Dentdoche

Dentdoche is a Lisp interpreter in node.js that abstracts away the difficulties of asynchronous programming so that functions calling callbacks can be treated as regular functions returning values.

Dentdoche is just a regular node library that is included in the source code, so no extra build step is necessary. Functions defined in Dentdoche can call Javascript functions, and Javascript functions can call functions defined with Dentdoche, because Dentdoche functions compile to Javascript functions. The two languages can be used and live together, side by side, in the same source file.

Dentdoche code can be written either as Javascript literals, or as S-expressions that are parsed. The parsed S-expression compile to Javascript literals, that in turn compile into something that can be evaluated in Javascript.

Example usage

Consider this Javascript function that concatenates files:

var fs = require('fs');

function filecat(srcA, srcB, dst, cb) {
  fs.readFile(srcA, 'utf8', function(err, aData) {
    if (err) {
      cb(err);
    } else {
      fs.readFile(srcB, 'utf8', function(err, bData) {
	if (err) {
	  cb(err);
	} else {
	  fs.writeFile(dst, srcA + srcB, cb);
	}
      });
    }
  });
}

In Dentdoche, you would write

var fs = require('fs');
var dd = require('dentdoche');

dd.setAsync(fs.readFile);
dd.setAsync(fs.writeFile);

eval(dd.parse(
  '(dafn filecat (srcA srcB dst) '+
    '(fs.writeFile dst '+
    '  (+ (fs.readFile srcA "utf8") (fs.readFile srcB "utf8"))))'));

but one could also write it directly using Javascript literals:

var fs = require('fs');
var dd = require('dentdoche');

dd.setAsync(fs.readFile);
dd.setAsync(fs.writeFile);

var filecat2 = dd.makeAfn(
  ['srcA', 'srcB', 'dst'],
  [fs.writeFile,
   dd.sym('dst'),
   ['+',
    [fs.readFile,
     dd.sym('srcA'), 'utf8'],
    [fs.readFile,
     dd.sym('srcB'), 'utf8']]]);

Also, generalizing the function for more files is simple.

var filecatMany = dd.makeAfn(
  [],
  [fs.writeFile,
   [dd.last, dd.sym('arguments')],
   [dd.reduce,
    dd.sym('+'),
    [dd.map,
     [dd.afn, ['fname'], 
      [fs.readFile, dd.sym('fname'), 'utf8']],
     [dd.butLast, dd.sym('arguments')]]]]);

Documentation

The documentation is partial and written for the Dentdoche in parsed mode. Please see the test cases for up-to-date usage examples. In parsed mode, the included Dentdoche module must be named dd as in

var dd = require('dentdoche');

This is because the generated code will assume that the exported symbols can be referred to as dd.symbolName.

In order to just run some code for side effects, you can

eval(dd.parse('(console.log (+ "Three plus four is " (+ 3 4)))'));

Several expressions can be evaluated within the same string:

eval(dd.parse('(console.log (+ "Three plus four is " (+ 3 4))) (console.log "Hello!")'));

Global variables can be defined with def:

eval(dd.parse('(def seven (+ 3 4))'));

or as in

eval(dd.parse('(def fs (require "fs"))'));

A function that delivers its result as return value can be defined with dfn:

eval(dd.parse('(dfn fib (x) (if (< x 2) x (+ (fib (- x 1)) (fib (- x 2)))))'));

assert(fib(7) == 13);

and likewise, a function that calls a callback cb as cb(error, result), can be defined as

eval(dd.parse('(dafn fiba (x) (if (< x 2) x (+ (fiba (- x 1)) (fiba (- x 2)))))'));

fiba(7, function(err, value) {
  assert(value == 13);
});            

By default, functions not defined by Dentdoche will be assumed to return their results through their return value. However, Dentdoche can be told that they deliver their results through a callback:

eval(dd.parse('(dafn loadFile (fname) (async (fs.readFile fname)))'));

or

dd.setAsync(fs.readFile);
eval(dd.parse('(dafn loadFile (fname) (fs.readFile fname))'));

Note that in the above two functions, we must use dafn and not dfn, because the expression inside involves asynchronous computations.

Anonymous functions can also be defined, either as delivering their result through return value (using fn) or by calling a callback (using afn):

eval(dd.parse('(def fa (fn (a b) (+ (* a a) (* b b))))'));
eval(dd.parse('(def fb (afn (a b) (+ (* a a) (* b b))))'));
assert(fa(3, 4) == 25);
fb(3, 4, function(err, value) {
  assert(value == 25);
});

The sync keyword can also be used to override a function that was previously set to being async. All these keywords (sync, async and async1) override what was previously associated with a function:

dd.setAsync(fs.readFile);
eval(dd.parse('(sync (fs.readFile "somefile" (fn (err value) '+
                     +'(console.log "Maybe loaded."))))'));

This means that you can write regular callback-style code in Dentdoche, but with Lisp syntax.

Macros are regular Javascript functions that transform programs. Here is a macro that defines or in a lazy way:

function or() {
  var args = argsToArray(arguments);
  if (args.length == 0) {
    return false;
  } else {
    return ['if', first(args), true, or.apply(null, rest(args))];
  }
} macro(or);

See the test cases in order to understand how to really make use of Dentdoche.

Licence

Copyright Jonas Östlund 2015. Released under EPL (Eclipse Public Licence).