geppetto-apps / crow

Transpile/compile Crystal to Flow

crow

crow transpiles Crystal source code to valid Flow/ES2015/JavaScript.

Code that is transpiled to valid Flow syntax may be transpiled to valid ES2015, which may be transpiled to Javascript (via Babel).

Warning: Experimental

This project is in alpha stage and should be considered highly experimental.

Installation

Via Homebrew:

brew install geppetto-apps/bin/crow

Via npm:

npm install crow-cli -g

Usage

# Compiles and outputs to foo.js.flow
$ crow foo.cr

# Same as above
$ cat foo.cr | crow > foo.js.flow

# Compile to JavaScript (via Babel)
$ npm install babel-preset-es2015 babel-plugin-transform-flow-strip-types
$ cat foo.cr | crow | babel --plugins transform-flow-strip-types --presets es2015

You can also use Docker:

$ cat foo.cr | docker run -i geppettoapps/crow > foo.js.flow

Motivation & Goal

This is both my first Crystal and first compiler project. I was inspired to learn more about compilers after reading Game Programming Patterns' chapter on bytecode and also Crystal and its relationship with LLVM. Since Crystal is a high-level, self-hosted programming language, it's very easy to work with Crystal's internals. In addition to attempting make Crystal target the web, I've learned a lot about Crystal from working on this project.

The goal of this project is to make it possible to write both frontend and backend code for a web project in Crystal; preferably in a way that allows for communication between native JS and native Crystal code. @asterite from the Crystal Team has noted that crystal is not geared against the web and there's still work left to make Crystal to work with asm.js. Due to this crow currently approach the problem by using transpilation, but that may not be the case forever. The only public API for crow is the CLI that takes in some Crystal code and spits out something may run in the browser.

Milestones

• 1.0: Run Crystal code in isolation in the browser
• 1.1: DOM manipulations from Crystal code
• 1.2: Bind Crystal code to DOM events
• 1.3: Call Crystal code from Javascript
• 1.4: Call non-DOM related Javascript code from Crystal

Supported AST nodes

Extracted from [Crystal's compiler][cr-parser].

• Expressions
• NilLiteral
• BoolLiteral
• NumberLiteral
• CharLiteral
• StringLiteral
• StringInterpolation
• SymbolLiteral
• ArrayLiteral
• HashLiteral
• NamedTupleLiteral
• ProcLiteral
• RangeLiteral
• RegexLiteral
• TupleLiteral
• Var
• Block
• Call
• NamedArgument
• If
• Unless
• IfDef
• Assign
• MultiAssign
• InstanceVar
• ReadInstanceVar
• ClassVar
• BinaryOp
• Arg
• ProcNotation
• Def
• Macro
• UnaryExpression
• VisibilityModifier
• IsA
• RespondsTo
• Require
• When
• Case
• ImplicitObj
• Path
• While
• Until
• Generic
• TypeDeclaration
• UninitializedVar
• Rescue
• ExceptionHandler
• ProcPointer
• Union
• Self
• ControlExpression
• Yield
• Include
• Extend
• EnumDef
• ClassDef
• ModuleDef
• LibDef
• FunDef
• TypeDef
• CStructOrUnionDef
• ExternalVar
• Alias
• Metaclass
• Cast
• NilableCast
• TypeOf
• Attribute
• MacroExpression
• MacroIf
• MacroFor
• MacroVar
• MacroLiteral
• Underscore
• MagicConstant
• Asm
• AsmOperand

Contributing

1. Fork it ( https://github.com/geppetto-apps/crow/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Attribution

Logo: Crow by Encrico Francese

Contributors

• theodorton Theodor Tonum - creator, maintainer