Macaron NPM | npm.io

Macaron

Macros for CoffeeScript. Try online: http://f.github.io/macaron/

Installation

npm install macaron

Using Macaron Grunt Task

Macaron has a Grunt plugin written by Ahmet Aygün.

npm install grunt-macaron --save-dev

Please read the README file of grunt-macaron for installation instructions.

Overview

Create a Macro library:

# macros.coffee
macro.swap = (x, y)->
  $tmp = y
  y = x
  x = $tmp

Write your Coffee using macros like functions:

# main.coffee
x = 1
y = 2
console.log "before: x is #{x}, y is #{y}"
swap x, y
console.log "after: x is #{x}, y is #{y}"

Compile them on Terminal ..:

$ macaron macros.coffee main.coffee
before: x is 1, y is 2
after: x is 2, y is 1

.. Or in your CoffeeScript Code:

# mycoffee.coffee
Macaron = require 'macaron'
macros = new Macaron
compiledJS = macros.compileFile 'macros.coffee', 'main.coffee', bare: no

console.log compiledJS

coffee mycoffee.coffee

Usage

macaron [MACROS FILE] [SOURCE FILES...] [COFFEE OPTIONS]

Basic Compilation

It basically replaces the code with the macro code.

// $ macaron examples/macros.coffee examples/source.coffee
var x, y, _tmp$1;
x = 1;
y = 2;
console.log("before swap, x is " + x + ", y is " + y);

// swap x, y macro starts here
_tmp$1 = y;
y = x;
x = _tmp$1;
// ends here

console.log("after swap, x is " + x + ", y is " + y);

Using Code Blocks

You can also use code blocks to use efficiently. To do this, just use splats of CoffeeScript (...)

# Create a macro named do_something which accepts a code block
macro.do_something = (block...)->
  hello = "world"
  do ->
    block

Then you can simply call like a callback

# Call the macro with a code block
do_something ->
  console.log hello

It will generate that code:

var hello;

hello = "world";
(function() {
  return console.log(hello);
})();

Composing

You can compose macros.

macro.sayHello = (world)->
  hello = "world"
  world = "hello"
  swap hello, world # Calling Scope Macro
  console.log hello, world

Replace Macros

Replace macros are so stupid ones, you can just pass the code to replace. The code won't be parsed by Macaron. To define replace macros, use do keyword. This macro type doesn't take any parameters since there are no parse process.

macro.strict = do ->
  "use strict"

You can use do keyword to call these macros:

do strict

It will generate the output:

"use strict";

Hygiene

You can keep your variables safe using $ prefix on your variables.

# macros.coffee
macro.swap = (x, y)->
  $tmp = y
  y = x
  x = $tmp

# main.coffee
x = 2
y = 3
swap x, y
console.log $tmp

When you run it, it will generate an error:

ReferenceError: $tmp is not defined

Escape Hygiene

You can always disable hygiene using fat-arrow (=>) or just don't use $ prefix.

macro.swap = (x, y)=> # disabling hygienic variables
  $tmp = y
  y = x
  x = $tmp

Literal Macros

You can use Literal macros using literal definition keyword. It takes two arguments, one is a regular expression, another is the function.

literal /(\w+) is (\w+) plus (\w+)/, (variable, first, second)->
  variable = first + second
    
literal /tell (.*) the (\w+)/, (channel, parameter)->
  channel parameters

With these literal macros you can now write some talkative declarations:

"a is 3 plus 4"
"tell console.log the a"

It will generate the output:

var a;
a = 3 + 4;
console.log(a);

You can wrap matches into quotes using @ (this) prefix on parameters.

literal /tell my (\w+) is (.*)/, (@key, @value)->
  user[key] = value

You can now use the macros easily:

"tell my name is fka" #=> It will be compiled to `user["name"] = "fka"`

Examples

# macros.coffee
macro.each = (variable, name, eachBlock...)->
  value = variable
  value.forEach ->
    $item = arguments[0]
    name = $item
    eachBlock

Using this macro:

each [1, 2, 3], item, ->
  console.log item

And it'll generate that code:

value = [1, 2];
value.forEach(function() {
  var item, _item$2;
  _item$2 = arguments[0];
  item = _item$2;
  return console.log(item);
});

Reading from STDIN

You can simply use standard input to run macaron:

echo "x = 1; y = 2; swap x, y; console.log x, y" | macaron -scb examples/macros.coffee | node

Command Line Usage

Usage: coffee ./bin/macaron [MACRO FILE] [SOURCE FILES...] [OPTIONS]

Options:
  -b, --bare     [default: true]
  -c, --compile  [default: false]
  --concat       [string]  [default: true]