cake is a simplified version of Make
(Rake, Jake)
for CoffeeScript. You define tasks with names and descriptions in a Cakefile,
and can call them from the command line, or invoke them from other tasks.
CoffeeScript can be used both on the server, as a command-line compiler based
on Node.js/V8, or to run CoffeeScripts directly in the browser. This module
contains the main entry functions for tokenzing, parsing, and compiling source
CoffeeScript into JavaScript.
diff --git a/documentation/docs/command_line.html b/documentation/docs/command.html
similarity index 66%
rename from documentation/docs/command_line.html
rename to documentation/docs/command.html
index b5139fb7..eb3cb9ff 100644
--- a/documentation/docs/command_line.html
+++ b/documentation/docs/command.html
@@ -1,16 +1,16 @@
- command_line.coffee
The coffee utility. Handles command-line compilation of CoffeeScript
+into various forms: saved into .js files or printed to stdout, piped to
+JSLint or recompiled every time the source is
+saved, printed as a token stream or as the syntax tree, or launch an
+interactive REPL.
The list of all the valid option flags that coffee knows how to handle.
SWITCHES: [['-c','--compile','compile to JavaScript and save as .js files']['-i','--interactive','run an interactive CoffeeScript REPL']['-o','--output [DIR]','set the directory for compiled JavaScript']
@@ -24,11 +24,11 @@
['-n','--nodes','print the parse tree that Jison produces']['-v','--version','display CoffeeScript version']['-h','--help','display this help message']
-]
-
-options: {}
+]
Run coffee by parsing passed options and determining what action to take.
+Many flags cause us to divert before compiling anything. Flags passed after
+-- will be passed verbatim to your script as arguments in process.ARGV
Compile a single source script, containing the given code, according to the
-requested options. Both compile_scripts and watch_scripts share this method.
Compile a single source script, containing the given code, according to the
+requested options. Both compile_scripts and watch_scripts share this method
+in common. If evaluating the script directly sets __filename, __dirname
+and module.filename to be correct relative to the script's path.
compile_script: (source,code)->o: optionstryifo.tokensthenprint_tokensCoffeeScript.tokenscode
@@ -71,37 +68,47 @@ requested options. Both compile_scripts and watch_scripts share this method.
module.filename: sourceevaljscatcherr
- ifo.watchthenputserr.messageelsethrowerr
Watch a list of source CoffeeScript files using fs.watchFile, recompiling
+them every time the files are updated. May be used in combination with other
+options, such as --lint or --print.
Write out a JavaScript source file with the compiled code. By default, files
+are written out in cwd as .js files with the same name, but the output
+directory can be customized with --output.
version: ->
+ puts"CoffeeScript version ${CoffeeScript.VERSION}"
+ process.exit0
\ No newline at end of file
diff --git a/documentation/docs/grammar.html b/documentation/docs/grammar.html
index 4b1e9707..4f96b3f2 100644
--- a/documentation/docs/grammar.html
+++ b/documentation/docs/grammar.html
@@ -1,4 +1,4 @@
- grammar.coffee
The CoffeeScript Lexer. Uses a series of token-matching regexes to attempt
matches against the beginning of the source code. When a match is found,
a token is produced, we consume the match, and start again. Tokens are in the
form:
Create an OptionParser with a list of valid options, in the form:
[short-flag (optional), long-flag, description]
And an optional banner for the usage help.
Scope objects form a tree corresponding to the shape of the function
definitions present in the script. They provide lexical scope, to determine
whether a variable has been seen before or if it needs to be declared.
diff --git a/lib/command.js b/lib/command.js
index 1fc519bb..88b460d3 100644
--- a/lib/command.js
+++ b/lib/command.js
@@ -2,19 +2,25 @@
var BANNER, CoffeeScript, SWITCHES, compile_options, compile_script, compile_scripts, compile_stdio, fs, lint, option_parser, options, optparse, parse_options, path, print_tokens, sources, usage, version, watch_scripts, write_js;
// The `coffee` utility. Handles command-line compilation of CoffeeScript
// into various forms: saved into `.js` files or printed to stdout, piped to
- // JSLint or recompiled every time the source is saved, printed as a token
- // stream or as the syntax tree.
+ // [JSLint](http://javascriptlint.com/) or recompiled every time the source is
+ // saved, printed as a token stream or as the syntax tree, or launch an
+ // interactive REPL.
// External dependencies.
fs = require('fs');
path = require('path');
optparse = require('optparse');
CoffeeScript = require('coffee-script');
+ // The help banner that is printed when `coffee` is called without arguments.
BANNER = "coffee compiles CoffeeScript source files into JavaScript.\n\nUsage:\n coffee path/to/script.coffee";
+ // The list of all the valid option flags that `coffee` knows how to handle.
SWITCHES = [['-c', '--compile', 'compile to JavaScript and save as .js files'], ['-i', '--interactive', 'run an interactive CoffeeScript REPL'], ['-o', '--output [DIR]', 'set the directory for compiled JavaScript'], ['-w', '--watch', 'watch scripts for changes, and recompile'], ['-p', '--print', 'print the compiled JavaScript to stdout'], ['-l', '--lint', 'pipe the compiled JavaScript through JSLint'], ['-s', '--stdio', 'listen for and compile scripts over stdio'], ['-e', '--eval', 'compile a string from the command line'], ['--no-wrap', 'compile without the top-level function wrapper'], ['-t', '--tokens', 'print the tokens that the lexer produces'], ['-n', '--nodes', 'print the parse tree that Jison produces'], ['-v', '--version', 'display CoffeeScript version'], ['-h', '--help', 'display this help message']];
+ // Top-level objects shared by all the functions.
options = {};
sources = [];
option_parser = null;
- // The CommandLine handles all of the functionality of the `coffee` utility.
+ // Run `coffee` by parsing passed options and determining what action to take.
+ // Many flags cause us to divert before compiling anything. Flags passed after
+ // `--` will be passed verbatim to your script as arguments in `process.ARGV`
exports.run = function run() {
var flags, separator;
parse_options();
@@ -46,21 +52,10 @@
if (options.watch) {
watch_scripts();
}
- compile_scripts();
- return this;
+ return compile_scripts();
};
- // The "--help" usage message.
- usage = function usage() {
- puts(option_parser.help());
- return process.exit(0);
- };
- // The "--version" message.
- version = function version() {
- puts("CoffeeScript version " + (CoffeeScript.VERSION));
- return process.exit(0);
- };
- // Compiles the source CoffeeScript, returning the desired JavaScript, tokens,
- // or JSLint results.
+ // Asynchronously read in each CoffeeScript in a list of source files and
+ // compile them.
compile_scripts = function compile_scripts() {
var _a, _b, _c, _d, compile, source;
compile = function compile(source) {
@@ -81,7 +76,9 @@
return _a;
};
// Compile a single source script, containing the given code, according to the
- // requested options. Both compile_scripts and watch_scripts share this method.
+ // requested options. Both compile_scripts and watch_scripts share this method
+ // in common. If evaluating the script directly sets `__filename`, `__dirname`
+ // and `module.filename` to be correct relative to the script's path.
compile_script = function compile_script(source, code) {
var __dirname, __filename, js, o;
o = options;
@@ -113,7 +110,8 @@
}
}
};
- // Listen for and compile scripts over stdio.
+ // Attach the appropriate listeners to compile scripts incoming over **stdin**,
+ // and write them back to **stdout**.
compile_stdio = function compile_stdio() {
var code;
code = '';
@@ -127,8 +125,9 @@
return process.stdio.write(CoffeeScript.compile(code, compile_options()));
});
};
- // Watch a list of source CoffeeScript files, recompiling them every time the
- // files are updated.
+ // Watch a list of source CoffeeScript files using `fs.watchFile`, recompiling
+ // them every time the files are updated. May be used in combination with other
+ // options, such as `--lint` or `--print`.
watch_scripts = function watch_scripts() {
var _a, _b, _c, _d, source, watch;
watch = function watch(source) {
@@ -151,7 +150,9 @@
}
return _a;
};
- // Write out a JavaScript source file with the compiled code.
+ // Write out a JavaScript source file with the compiled code. By default, files
+ // are written out in `cwd` as `.js` files with the same name, but the output
+ // directory can be customized with `--output`.
write_js = function write_js(source, js) {
var dir, filename, js_path;
filename = path.basename(source, path.extname(source)) + '.js';
@@ -159,7 +160,8 @@
js_path = path.join(dir, filename);
return fs.writeFile(js_path, js);
};
- // Pipe compiled JS through JSLint (requires a working 'jsl' command).
+ // Pipe compiled JS through JSLint (requires a working `jsl` command), printing
+ // any errors or warnings that arise.
lint = function lint(js) {
var jsl;
jsl = process.createChildProcess('jsl', ['-nologo', '-stdin']);
@@ -176,7 +178,7 @@
jsl.write(js);
return jsl.close();
};
- // Pretty-print a token stream.
+ // Pretty-print a stream of tokens.
print_tokens = function print_tokens(tokens) {
var _a, _b, _c, _d, _e, strings, tag, token, value;
strings = (function() {
@@ -194,16 +196,27 @@
}).call(this);
return puts(strings.join(' '));
};
- // Use OptionParser for all the options.
+ // Use the [OptionParser module](optparse.html) to extract all options from
+ // `process.ARGV` that are specified in `SWITCHES`.
parse_options = function parse_options() {
option_parser = new optparse.OptionParser(SWITCHES, BANNER);
options = option_parser.parse(process.ARGV);
return sources = options.arguments.slice(2, options.arguments.length);
};
- // The options to pass to the CoffeeScript compiler.
+ // The compile-time options to pass to the CoffeeScript compiler.
compile_options = function compile_options() {
return options['no-wrap'] ? {
no_wrap: true
} : {};
};
+ // Print the `--help` usage message and exit.
+ usage = function usage() {
+ puts(option_parser.help());
+ return process.exit(0);
+ };
+ // Print the "--version" message and exit.
+ version = function version() {
+ puts("CoffeeScript version " + (CoffeeScript.VERSION));
+ return process.exit(0);
+ };
})();
diff --git a/src/command.coffee b/src/command.coffee
index a65b1bb2..d52582a5 100644
--- a/src/command.coffee
+++ b/src/command.coffee
@@ -1,7 +1,8 @@
# The `coffee` utility. Handles command-line compilation of CoffeeScript
# into various forms: saved into `.js` files or printed to stdout, piped to
-# JSLint or recompiled every time the source is saved, printed as a token
-# stream or as the syntax tree.
+# [JSLint](http://javascriptlint.com/) or recompiled every time the source is
+# saved, printed as a token stream or as the syntax tree, or launch an
+# interactive REPL.
# External dependencies.
fs: require 'fs'
@@ -9,6 +10,7 @@ path: require 'path'
optparse: require 'optparse'
CoffeeScript: require 'coffee-script'
+# The help banner that is printed when `coffee` is called without arguments.
BANNER: '''
coffee compiles CoffeeScript source files into JavaScript.
@@ -16,6 +18,7 @@ BANNER: '''
coffee path/to/script.coffee
'''
+# The list of all the valid option flags that `coffee` knows how to handle.
SWITCHES: [
['-c', '--compile', 'compile to JavaScript and save as .js files']
['-i', '--interactive', 'run an interactive CoffeeScript REPL']
@@ -32,11 +35,14 @@ SWITCHES: [
['-h', '--help', 'display this help message']
]
+# Top-level objects shared by all the functions.
options: {}
sources: []
option_parser: null
-# The CommandLine handles all of the functionality of the `coffee` utility.
+# Run `coffee` by parsing passed options and determining what action to take.
+# Many flags cause us to divert before compiling anything. Flags passed after
+# `--` will be passed verbatim to your script as arguments in `process.ARGV`
exports.run: ->
parse_options()
return usage() if options.help
@@ -53,20 +59,9 @@ exports.run: ->
process.ARGV: process.argv: flags
watch_scripts() if options.watch
compile_scripts()
- this
-# The "--help" usage message.
-usage: ->
- puts option_parser.help()
- process.exit 0
-
-# The "--version" message.
-version: ->
- puts "CoffeeScript version ${CoffeeScript.VERSION}"
- process.exit 0
-
-# Compiles the source CoffeeScript, returning the desired JavaScript, tokens,
-# or JSLint results.
+# Asynchronously read in each CoffeeScript in a list of source files and
+# compile them.
compile_scripts: ->
compile: (source) ->
path.exists source, (exists) ->
@@ -75,7 +70,9 @@ compile_scripts: ->
compile(source) for source in sources
# Compile a single source script, containing the given code, according to the
-# requested options. Both compile_scripts and watch_scripts share this method.
+# requested options. Both compile_scripts and watch_scripts share this method
+# in common. If evaluating the script directly sets `__filename`, `__dirname`
+# and `module.filename` to be correct relative to the script's path.
compile_script: (source, code) ->
o: options
try
@@ -94,7 +91,8 @@ compile_script: (source, code) ->
catch err
if o.watch then puts err.message else throw err
-# Listen for and compile scripts over stdio.
+# Attach the appropriate listeners to compile scripts incoming over **stdin**,
+# and write them back to **stdout**.
compile_stdio: ->
code: ''
process.stdio.open()
@@ -103,8 +101,9 @@ compile_stdio: ->
process.stdio.addListener 'close', ->
process.stdio.write CoffeeScript.compile code, compile_options()
-# Watch a list of source CoffeeScript files, recompiling them every time the
-# files are updated.
+# Watch a list of source CoffeeScript files using `fs.watchFile`, recompiling
+# them every time the files are updated. May be used in combination with other
+# options, such as `--lint` or `--print`.
watch_scripts: ->
watch: (source) ->
fs.watchFile source, {persistent: true, interval: 500}, (curr, prev) ->
@@ -112,14 +111,17 @@ watch_scripts: ->
fs.readFile source, (err, code) -> compile_script(source, code)
watch(source) for source in sources
-# Write out a JavaScript source file with the compiled code.
+# Write out a JavaScript source file with the compiled code. By default, files
+# are written out in `cwd` as `.js` files with the same name, but the output
+# directory can be customized with `--output`.
write_js: (source, js) ->
filename: path.basename(source, path.extname(source)) + '.js'
dir: options.output or path.dirname(source)
js_path: path.join dir, filename
fs.writeFile js_path, js
-# Pipe compiled JS through JSLint (requires a working 'jsl' command).
+# Pipe compiled JS through JSLint (requires a working `jsl` command), printing
+# any errors or warnings that arise.
lint: (js) ->
jsl: process.createChildProcess('jsl', ['-nologo', '-stdin'])
jsl.addListener 'output', (result) ->
@@ -129,19 +131,30 @@ lint: (js) ->
jsl.write js
jsl.close()
-# Pretty-print a token stream.
+# Pretty-print a stream of tokens.
print_tokens: (tokens) ->
strings: for token in tokens
[tag, value]: [token[0], token[1].toString().replace(/\n/, '\\n')]
"[$tag $value]"
puts strings.join(' ')
-# Use OptionParser for all the options.
+# Use the [OptionParser module](optparse.html) to extract all options from
+# `process.ARGV` that are specified in `SWITCHES`.
parse_options: ->
option_parser: new optparse.OptionParser SWITCHES, BANNER
options: option_parser.parse(process.ARGV)
sources: options.arguments[2...options.arguments.length]
-# The options to pass to the CoffeeScript compiler.
+# The compile-time options to pass to the CoffeeScript compiler.
compile_options: ->
if options['no-wrap'] then {no_wrap: true} else {}
+
+# Print the `--help` usage message and exit.
+usage: ->
+ puts option_parser.help()
+ process.exit 0
+
+# Print the `--version` message and exit.
+version: ->
+ puts "CoffeeScript version ${CoffeeScript.VERSION}"
+ process.exit 0