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

crow's Issues

Named method arguments

Assume the following code:

def fn(arg_a, arg_b, arg_c)
  ...
end

fn(1, 2, 3)
fn(1, 2, arg_a: 3)
fn(arg_a: 1, arg_b: 2, arg_c: 3)
fn(arg_c: 1, arg_b: 2, arg_a: 3)

JavaScript has no concept of named arguments. An object argument would of course be possible, but that would leave out the first and second variant. I don't want to litter the function definitions with too much new code, but I'm not sure there are any other options.

Ditching const

Crystal only have constants in the sense that capitalized variables are constant and may not be redefined. ES2015 introduces the const and let keywords to discern immutable and mutable variables.

Crow handles this right now, but I believe the implementation is quite brittle and won't work for most usecases.

ESLint has a rule prefer-const which supports --fix, which means it's possible to just define alll variables using let out of crow, and then perform cleanup after transpilation is done.

Module parsing

Modules are currently not transpiled, as I haven't decided how they should be treated.

I believe the most natural way would be to treat a Crystal module as an Object, defined as a global.

module Foo
  module Bar
    def hello
      "world"
    end
  end
end

global.Foo = {
  Bar: {
    hello() { return "world"; },
  },
};

Throw exception if transpilation was unsuccessful

The transpilation step is currently unforgivingly forgiving. Any valid Crystal code will transpile to something, no matter how monstrous the result is.

The CLI should accept a strict flag, which by default will be set.

# Both of these will fail if crow is unsure of how to transpile a piece of code:
$ crow
$ crow --strict 

# This lets crow transpile mostly any valid Crystal code (as it does today):
$ crow --no-strict

Auto-generated examples

Almost all the specs following the same format:

1. Define the Crystal code with a heredoc string
2. Define the expected Flow code with a heredoc string
3. Pass the Crystal code to crow and check output

If there was a macro defined that would run the specs as they are defined, but also generated markdown examples in an examples folder. Not really sure whether this folder should be checked into git.

Transpilation of case statements without condition

Crystal allows (like Ruby), a conditionless case statement:

case
when cond_a
  # Do something
when cond_b
  # Do something
else
  # Do something
end

I can't recall using this myself, or seeing this in the wild so I'm not sure whether transpilation should be supported. One option will be to transform the whole case statement to an if statement, but I'm afraid the syntax isn't just syntactic sugar and that the transformed statement would lose something in the process.

The same goes for handling type conditions:

case object
when Foo
  # Object is of type Foo
when Bar
  # Object is of type Bar
end

Consider compile to TypeScript

Hi @theodorton great project, I like it!

I think would be nice to compile/transpile Crystal -> TypeScript because the type syntax is very similar and we can add types easier.

Commonly I use TypeScript to understand Crystal code and viceversa, by example, see Refactoring in Crystal

The code above is very similar in crystal (despite the braces and new keyword 😉 )

not really an issue but...

FYI: I just put a discussion topic around this general topic: https://forum.crystal-lang.org/t/crystal-js-transpiler/903

If inappropriate please forgive and close :-)

Follow compiler convention of parser/transform/codegen

As crow borrows the Parser from Crystal's compiler, this means splitting the transform/codegen step. I.e. as #1 requires modules, a Crystal concept not really present in Flow, to be treated as object, it would seem natural that it is transformed to Crystal named struct before the code is generated.