Compilers

Version 0.2 Files setup (obsolete)

The easiest way to write streamline code is to put the following line at the top of your module:

if (!require('streamline/module')(module)) return;

Then you can use the _ marker anywhere in your module:

function lineCount(path, _) {
  return fs.readFile(path, "utf8", _).split('\n').length;
}

You can run your module with node-streamline:

node-streamline myModule

The code will be automatically transformed and the transformed files will be cached under ~/.streamline.

You can also run your module with node:

node myModule

If you run with node, streamline will create (and delete) a temporary copy of your source file. So you need r/w access to the module's directory. Note that only the main module will be copied, the streamline modules that are required by the main module won't be copied so you don't need r/w access to all directories.

Version 0.1 Files setup (obsolete)

To create a module called myModule, put your streamlined source in a file called myModule_.js.

Then you have several options:

1. You can compile your module with node-streamline -c. This will create a file called myModule.js that you can directly run with the node command, or require from a normal node program.
2. You can run the module with node-streamline myModule_ or require it as require('myModule_') from a program that you launch with node-streamline. If you choose this option, the myModule.js file will not be created.
3. You can run the module with node-streamline myModule or require it as require('myModule') from a program that you launch with node-streamline. If you choose this option, you have to create an empty myModule.js file to initiate the process.
4. You can load source and transform it on the fly with the transform API.

Option 1 is ideal for production code, as your transformed module will be loaded standalone. The transformation engine will not be loaded.

Option 2 is your best option if you do not want to save the transformed code to disk.

Option 3 is ideal for the development phase if you do not have a build script. The files will only be recompiled if the source has changed (so you won't get the overhead every time you launch your program). The transformed source will be available on disk, and will be loaded by the debugger (because you require myModule, not myModule_). Also, this option makes the switch to production really easy: recompile the whole tree and run with node rather than with node-streamline.

Option 4 is reserved for advanced scenarios where the code is transformed on the fly.

There is an alternative to running your application with node-streamline: you can call require('streamline') from your main script and then run it with node. Modules that are required (directly or indirectly) by your main script will be transformed on demand.

Note: streamline can also transform vanilla Javascript files that don't use CommonJS modules and don't target node. So you can compile them (option 1) and load them directly in the browser from a <script> directive.

Javascript

The node-streamline script can be used to compile one or more scripts. The command line options are similar to CoffeeScript (with additional options to control how output lines are formatted):

-c,  --compile         compile *_.js files and save as *.js files
-f,  --force           force recompilation of files that have not been modified.
-v,  --verbose         displays the names of files being compiled.
     --fibers          target the fibers runtime.
-li, --lines-ignore    don't do anything special with line numbers.
-lm, --lines-mark      insert a comment with original line number at the beginning of lines.
-lp, --lines-preserve  rearrange output so that lines number match (to get correct line numbers in stack traces).
-h,  --help            displays this help message.

For example:

node-streamline -c .           # recompiles all modified *_.js scripts in current tree
node-streamline -f -v -c lib   # compiles all *_.js scripts in 'lib' in verbose mode. 

Note: the -f and -v options must come before the -c option.

The scripts loaded with require are also automatically recompiled if you run you main script with node-streamline or if you call require('streamline') at the beginning of your main script. So you do not have to recompile manually before running your program. But the compiler is handy if you want to produce files for other environments than node (browser for example).

Note: you can also control line numbering / folding by setting a line option inside the source file. If you do so, the file level setting will override the options that you specified on the command line. Here is an example:

// streamline.options = { "lines": "ignore" }

CoffeeScript

The coffee-streamline script can be used to run streamlined CoffeeScript code. You just need to call your streamline CoffeeScript source files xxx_.coffee. The coffee-streamline script will apply the streamline transform if it detects the - character before the .coffee extension.

If you want to compile streamlined CoffeeScript source to Javascript, you have to do two passes: a first pass with coffee -c to generate the xxx_.js files, and a second pass with node-streamline -c to generate xxx.js from xxx_.js.

Limitation: this compilation process does not work with main modules that contain asynchronous calls at top level (like the diskUsage examples) but it should work with all library modules that define asynchronous functions but don't call them from their top level script.