Permalink
Browse files

readme: docs

  • Loading branch information...
1 parent e4e3484 commit 69380daa017fbf00671fde968a5fcd3182f49a6b @indutny committed Oct 1, 2012
Showing with 102 additions and 4 deletions.
  1. +94 −0 README.md
  2. +5 −3 lib/spoon/cfg.js
  3. +3 −1 test/asyncify-test.js
View
@@ -2,6 +2,100 @@
Continuation passing style for javascript.
+## It's hot
+
+Spoon is a javascript *transpiler*, it's designed to compile javascript to...
+javascript.
+
+Lets take following code sample:
+```javascript
+var x = 1;
+
+var y = hardMath(x) * 2;
+
+console.log(y);
+```
+
+Suppose you would like to do `hardMath` on some remote machine (or in thread),
+this will surely require you to make this call asynchronous - i.e. pass a
+continuation as a callback for `hardMath` function.
+
+Calling `spoon(code, ['hardMath'])` will find all occurences of `hardMath` and
+replace them with following thing:
+```javascript
+function __$fn1(__$r) {
+ y = __$r * 2;
+ console.log(y);
+ return __$callback.call(this);
+};
+
+var y;
+
+var x;
+
+x = 1;
+
+return hardMath(x, __$fn1);
+```
+
+As you can see `__$callback` function should be available in a context.
+
+## Why spoon is interesting?
+
+Spoon isn't just doing stupid tricks with your code, it compiles javascript to
+well-known form (used by almost every compiler, including v8) HIR (High-Level
+intermediate representation).
+
+You can do it yourself by calling:
+```javascript
+var cfg = spoon.construct(esprima.parse('x = y + 1 * 2'));
+
+console.log(cfg.toString());
+```
+
+Will produce:
+```
+--- CFG ---
+[block 0]
+# predecessors:
+# parent: null
+# frontier:
+# cfrontier:
+i0 = var y
+i1 = get x
+i2 = literal 1
+i3 = literal 2
+i4 = binop *, i2, i3
+i5 = binop +, i1, i4
+i6 = set =, y, i5
+# successors:
+# children:
+```
+
+You can manipulate blocks, change order of instruction, do some optimizations,
+and, after that, compile CFG back to JS:
+```javascript
+spoon.render(cfg);
+```
+
+## API
+
+```javascript
+// Transpile code
+spoon(code, [ functions ], {
+ declaration: 'enable spoon', // spoon will touch only code with
+ // "enable spoon"; declaration
+ uglify: {}, // uglifyjs options (used for code generation)
+ esprima: {} // esprima options (used for parsing)
+})
+
+// Construct CFG
+var cfg = spoon.construct(EsprimaAST);
+
+// Render CFG
+spoon.render(cfg);
+```
+
### License
This software is licensed under the MIT License.
View
@@ -188,9 +188,11 @@ Cfg.prototype.asyncify = function asyncify(asts, options) {
if (!hasDeclaration[block.id]) {
// Find declaration first
var found = block.instructions.some(function(instr) {
- if (instr.type !== 'literal' ||
- instr.args[0] !== (options.declaration || 'enable spoon') ||
- instr.uses.length > 0) {
+ // No declaration? - All blocks counts
+ if (options.declaration &&
+ (instr.type !== 'literal' ||
+ instr.args[0] !== options.declaration ||
+ instr.uses.length > 0)) {
return false;
}
View
@@ -9,7 +9,9 @@ describe('Spoon', function() {
var ast = esprima.parse(code.toString()),
cfg = spoon.construct(ast);
- cfg.asyncify([esprima.parse(what || 'async')], {});
+ cfg.asyncify([esprima.parse(what || 'async')], {
+ declaration: 'enable spoon'
+ });
var out = spoon.render(cfg);
var code = uglify.uglify.gen_code(out, { beautify: true });

0 comments on commit 69380da

Please sign in to comment.