@fraczak/k 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# k-language 
+
+Another JSON-to-JSON transformation notation.  A `k`-expression
+(script) defines a __partial function__, i.e., a function which, in
+general, is not defined for every input. `k`-expressions can be
+combined to build other `k`-expressions in three ways:
+
+1. composition, e.g.:
+   
+        (E1 E2 E3 ...)
+	
+	Apart from empty composition, `()`, which defines _identity_, the paranthesis can be omitted.
+
+2. product, e.g., vector:
+
+        [ E1, E2, E3, ... ]
+   
+    or structure:
+  
+        { E1 "e1", E2 "e2", E3 "e3", ... }
+
+3. union (merge), e.g.:
+
+        < E1, E2, E3, ... >
+		
+Elementary partial functions are: 
+
+1.  _projection_, i.e., extracting the value of a given field or
+	index. Examples:
+	
+		.x
+		."field name"
+		.4
+	
+	The function is defined only if its argument is a structure with
+	the field (or a vector with the index).
+   
+2. _constants_, literals for Strings, Booleans, and
+   Integers. Examples:
+   
+		"a string"
+		'another "String"'
+		123
+		false
+
+	Those functions are always defined, i.e., they ignore their argument.
+	
+3.  There is a number of built-in functions: `GT`, `EQ`, `PLUS`,
+	`TIMES`, `MINUS`, `DIV`, `CONCAT`, `toJSON`, `fromJSON`. For example
+	
+		[1, 2, 3] PLUS       --> integer constant 6
+		[4, 4] TIMES toJSON  --> string constant "16"
+		[3, 2] GT            --> vector constant [3, 2]
+		[3, 4] GT            --> is not defined!
+		
+	A more interesting example could be:
+	
+		< [.0, .1] GT, [.1, .0] GT > .0
+		
+	which selects the bigger of two first integers of a vector argument, i.e.,
+	
+		[3,8] < [.0, .1] GT, [.1, .0] GT > .0    --> 8
+
+
+
+## Command line script
+
+There is a wrapper, `./node_modules/.bin/k` , which makes it easy to
+run the language from command line.
+
+    $ ./node_modules/.bin/k
+	... errors ...
+	Usage: ./node_modules/.bin/k ( k-expr | -k k-file) [ json-file ]
+	       E.g., cat '{"a": 10}' | ./node_modules/.bin/k '[(),()]'
+
+### Examples
+
+1. One `k`-expression with one `json`-object:
+
+		$ echo '{"x": 12, "y": 13}' | ./k.coffee '{ <.x, "no x"> x, () input}' 
+		{"x":12,"input":{"x":12,"y":13}}
+	
+2. By providing only `k`-expression, the script will compile the
+   `k`-expression and apply the generated function to the `stdin`, line by line:
+
+		$ ./k.coffee '<["x=",.x," & y=",.y],["only x=",.x],["only y=",.y],["no x nor y"]>{CONCAT "x&y"}' 
+		
+		{"y": 123, "x": 432,"others": "..."}  --> {"x&y":"x=432 & y=123"} 
+		{"x":987}                             --> {"x&y":"only x=987"} 
+		{"z":123}                             --> {"x&y":"no x nor y"}
+		^D - to interrupt
+
+3. If the `k`-expression is long, it can be put in a file, e.g.:
+
+		$ cat test.k
+		 ---------  comments start by #, --, or // ----------------------------------
+		 <                          -- merge of 4 partial functions...
+		   ["x=", .x, " & y=", .y], -- produces a vector of 4 values, if fields 'x' and 'y' are present
+		   ["only x=", .x],         -- produces a pair '["only x=", "value-of-x"]', for input like {"x":"value-of-x"}
+									-- it is defined only if field 'x' is present
+		   ["only y=", .y],
+		   ["no x nor y"]           -- defined for all input, returns always the same one element vector
+		 > 
+		 -- one of the string vectors is passed to the following partial function, 
+		 -- which produces a record (map) with one field "x&y", whose value is the
+		 -- result of concatenating elements of the passed in vector
+		 { CONCAT "x&y" } 
+		 ------------------------------------------------------------------------------
+		 
+	We can use it by:
+	
+		$ ./k.coffee -k test.k
+	
+	If we want to read `json` objects from a file, e.g., `my-objects.json`, we do
+	
+		$ ./k.coffee -k test.k -j my-objects.json
+		{"x&y":"x=432 & y=123"} 
+		{"x&y":"onlyx=987"} 
+		{"x&y":"no x nor y"}
+	
+	where:
+	
+		$ cat my-objects.json 
+		 ####################################################
+		 # empty lines and lines starting with # are ignored
+		 {"y": 123, "x": 432,"others": "..."}
+		 {"x":987}
+		 {"z":123}
+		 ####################################################
+		
+# Using from `javascript`
+    
+    var k = require("k");
+
+    var k_expression;
+
+    k_expression = '()';
+    k.run(t_expression,"ANYTHING...");
+    // RETURNS: "ANYTHING..."
+
+    k_expression = '{"ala" name, 23 age}';
+    k.run(k_expression,"ANYTHING...");
+    // RETURNS: {"name":"ala","age":23}
+
+    k_expression = '[.year, .age]';
+    k.run(k_expression,{"year":2002,"age":19});
+    // RETURNS: [2002,19]
+
+    k_expression = '[(), ()]';
+    k.run(k_expression,"duplicate me");
+    // RETURNS: ["duplicate me","duplicate me"]
+
+    k_expression = '[[[()]]]';
+    k.run(k_expression,"nesting");
+    // RETURNS: [[["nesting"]]]
+
+    k_expression = '[[()]] {() nested, .0.0 val}';
+    k.run(k_expression,"nesting and accessing")
+    // RETURNS: {"nested":[["nesting and accessing"]],"val":"nesting and accessing"}
+
+    k_expression = '0000';
+    k.run(k_expression,{"test":"parse integer"});
+    // RETURNS: 0
+
+    k_expression = '[.y,.x] PLUS';
+    k.run(k_expression,{"x":3,"y":4});
+    // RETURNS: 7
+
+    k_expression = '{.name nom, <[.age, 18] GT .0, [.age, 12] GT "ado", "enfant"> age}';
+
+    var k_fn = k.compile(k_expression);
+
+    k_fn({"age":23,"name":"Emily"});
+    // RETURNS: {"nom":"Emily","age":23}
+
+    k_fn({"age":16,"name":"Katrina"});
+    // RETURNS: {"nom":"Katrina","age":"ado"}
+
+    k_fn({"age":2,"name":"Mark"})
+    // RETURNS: {"nom":"Mark","age":"enfant"}
+

package/index.coffee

@@ -0,0 +1,18 @@
+fs = require "fs"
+{parse} = require "./parser.js"
+run = require "./run"
+
+compile = (script) ->
+  do (exp = parse script) ->
+    (data) -> run exp, data
+compile.doc = "Transforms k-script (string) into a function"
+
+compile_file = (fileName) ->
+  compile fs.readFileSync(fileName).toString "utf8"
+compile_file.doc = "Transforms k-script (from file) into a function"
+
+runScriptOnData = (script, data) ->
+  compile(script) data
+runScriptOnData.doc = "Run 'script' (string) on 'data': (script,data) -> data"
+
+module.exports = {compile, compile_file, run: runScriptOnData, parse: parse}

package/index.js

@@ -0,0 +1,40 @@
+// Generated by CoffeeScript 2.7.0
+(function() {
+  var compile, compile_file, fs, parse, run, runScriptOnData;
+
+  fs = require("fs");
+
+  ({parse} = require("./parser.js"));
+
+  run = require("./run");
+
+  compile = function(script) {
+    return (function(exp) {
+      return function(data) {
+        return run(exp, data);
+      };
+    })(parse(script));
+  };
+
+  compile.doc = "Transforms k-script (string) into a function";
+
+  compile_file = function(fileName) {
+    return compile(fs.readFileSync(fileName).toString("utf8"));
+  };
+
+  compile_file.doc = "Transforms k-script (from file) into a function";
+
+  runScriptOnData = function(script, data) {
+    return compile(script)(data);
+  };
+
+  runScriptOnData.doc = "Run 'script' (string) on 'data': (script,data) -> data";
+
+  module.exports = {
+    compile,
+    compile_file,
+    run: runScriptOnData,
+    parse: parse
+  };
+
+}).call(this);

package/k.coffee

@@ -0,0 +1,45 @@
+#!/usr/bin/env coffee
+fs = require "fs"
+k = require "./"
+
+prog = process.argv[1]
+
+{kScript,jsonStream} = do (args = process.argv.slice(2)) ->
+  try 
+    kScript = do (arg = args.shift()) ->
+      throw new Error() unless arg?
+      if arg is "-k"
+        fs.readFileSync(args.shift()).toString "utf8"
+      else
+        arg
+
+    kScript = k.compile kScript
+    
+    jsonStream = do (arg = args.shift()) ->
+      return process.stdin unless arg?
+      fs.createReadStream args.shift()
+
+    {kScript, jsonStream}
+  catch e
+    console.error e
+    console.error "Usage: #{prog} ( k-expr | -k k-file ) [ json-file ]"
+    console.error "       E.g.,  echo '{\"a\": 12}' | #{prog} '[(),()]'"
+    process.exit -1 
+
+do (buffer = [], line = 0) ->
+  jsonStream.on 'data', (data) ->
+    [first, rest...] = data.toString("utf8").split "\n"
+    buffer.push first
+    if rest.length > 0
+      todo = buffer.join ""
+      [rest..., last] = rest
+      buffer = [last]
+      todo = [todo, rest...]
+      for json in todo
+        if not json.match /^[ \n\t]*(?:#.*)?$/
+          try
+            console.log JSON.stringify kScript JSON.parse json
+          catch e 
+            console.error "Problem [line #{line}]: '#{json}'"
+            console.error e
+        line = line + 1

package/k.js

@@ -0,0 +1,72 @@
+// Generated by CoffeeScript 2.7.0
+(function() {
+  //!/usr/bin/env coffee
+  var fs, jsonStream, k, kScript, prog,
+    splice = [].splice;
+
+  fs = require("fs");
+
+  k = require("./");
+
+  prog = process.argv[1];
+
+  ({kScript, jsonStream} = (function(args) {
+    var e;
+    try {
+      kScript = (function(arg) {
+        if (arg == null) {
+          throw new Error();
+        }
+        if (arg === "-k") {
+          return fs.readFileSync(args.shift()).toString("utf8");
+        } else {
+          return arg;
+        }
+      })(args.shift());
+      kScript = k.compile(kScript);
+      jsonStream = (function(arg) {
+        if (arg == null) {
+          return process.stdin;
+        }
+        return fs.createReadStream(args.shift());
+      })(args.shift());
+      return {kScript, jsonStream};
+    } catch (error) {
+      e = error;
+      console.error(e);
+      console.error(`Usage: ${prog} ( k-expr | -k k-file ) [ json-file ]`);
+      console.error(`       E.g.,  echo '{\"a\": 12}' | ${prog} '[(),()]'`);
+      return process.exit(-1);
+    }
+  })(process.argv.slice(2)));
+
+  (function(buffer, line) {
+    return jsonStream.on('data', function(data) {
+      var e, first, i, json, last, len, ref, rest, results, todo;
+      [first, ...rest] = data.toString("utf8").split("\n");
+      buffer.push(first);
+      if (rest.length > 0) {
+        todo = buffer.join("");
+        ref = rest, [...rest] = ref, [last] = splice.call(rest, -1);
+        buffer = [last];
+        todo = [todo, ...rest];
+        results = [];
+        for (i = 0, len = todo.length; i < len; i++) {
+          json = todo[i];
+          if (!json.match(/^[ \n\t]*(?:#.*)?$/)) {
+            try {
+              console.log(JSON.stringify(kScript(JSON.parse(json))));
+            } catch (error) {
+              e = error;
+              console.error(`Problem [line ${line}]: '${json}'`);
+              console.error(e);
+            }
+          }
+          results.push(line = line + 1);
+        }
+        return results;
+      }
+    });
+  })([], 0);
+
+}).call(this);

package/k.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Generated by CoffeeScript 2.7.0
+(function() {
+  //!/usr/bin/env coffee
+  var fs, jsonStream, k, kScript, prog,
+    splice = [].splice;
+
+  fs = require("fs");
+
+  k = require("./");
+
+  prog = process.argv[1];
+
+  ({kScript, jsonStream} = (function(args) {
+    var e;
+    try {
+      kScript = (function(arg) {
+        if (arg == null) {
+          throw new Error();
+        }
+        if (arg === "-k") {
+          return fs.readFileSync(args.shift()).toString("utf8");
+        } else {
+          return arg;
+        }
+      })(args.shift());
+      kScript = k.compile(kScript);
+      jsonStream = (function(arg) {
+        if (arg == null) {
+          return process.stdin;
+        }
+        return fs.createReadStream(args.shift());
+      })(args.shift());
+      return {kScript, jsonStream};
+    } catch (error) {
+      e = error;
+      console.error(e);
+      console.error(`Usage: ${prog} ( k-expr | -k k-file ) [ json-file ]`);
+      console.error(`       E.g.,  echo '{\"a\": 12}' | ${prog} '[(),()]'`);
+      return process.exit(-1);
+    }
+  })(process.argv.slice(2)));
+
+  (function(buffer, line) {
+    return jsonStream.on('data', function(data) {
+      var e, first, i, json, last, len, ref, rest, results, todo;
+      [first, ...rest] = data.toString("utf8").split("\n");
+      buffer.push(first);
+      if (rest.length > 0) {
+        todo = buffer.join("");
+        ref = rest, [...rest] = ref, [last] = splice.call(rest, -1);
+        buffer = [last];
+        todo = [todo, ...rest];
+        results = [];
+        for (i = 0, len = todo.length; i < len; i++) {
+          json = todo[i];
+          if (!json.match(/^[ \n\t]*(?:#.*)?$/)) {
+            try {
+              console.log(JSON.stringify(kScript(JSON.parse(json))));
+            } catch (error) {
+              e = error;
+              console.error(`Problem [line ${line}]: '${json}'`);
+              console.error(e);
+            }
+          }
+          results.push(line = line + 1);
+        }
+        return results;
+      }
+    });
+  })([], 0);
+
+}).call(this);

package/my-objects.json

@@ -0,0 +1,6 @@
+####################################################
+# empty lines and lines starting with # are ignored
+{"y": 123, "x": 432,"others": "..."}
+{"x":987}
+{"z":123}
+####################################################

package/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "@fraczak/k",
+    "version": "1.0.0",
+    "description": "k-language for untyped JSON like data transformation",
+    "main": "index.js",
+    "scripts": {
+        "prepare": "coffee -c symbol-table.coffee; jison parser.jison",
+        "prepublishOnly": "coffee -c *.coffee; echo '#!/usr/bin/env node' | cat - k.js > k.sh",
+        "test": "coffee -c symbol-table.coffee; jison parser.jison; coffee test.coffee;"
+    },
+    "author": "Wojciech Fraczak",
+    "license": "ISC",
+    "bin": {
+        "k": "./k.sh"
+    },
+    "devDependencies": {
+        "jison": "^0.4.18"
+    },
+    "dependencies": {
+        "coffeescript": "^2.7.0"
+    }
+}

package/parser.jison

@@ -0,0 +1,93 @@
+%{
+
+var s = require("./symbol-table");
+
+%}
+
+%lex
+
+%%
+[/][*]([*][^/]|[^*])*[*][/]                    /* c-comment */
+("//"|"#"|"%"|"--")[^\n]*                      /* one line comment */
+\s+                                            /* blanks */
+"<"                                            return 'LA';
+"{"                                            return 'LC';
+"["                                            return 'LB';
+"("                                            return 'LP';
+">"                                            return 'RA';
+"}"                                            return 'RC';
+"]"                                            return 'RB';
+")"                                            return 'RP';
+"."                                            return 'DOT';
+","                                            return 'COMMA';
+\"[^\"\n]*\"|\'[^\'\n]*\'                      return 'STRING'
+[a-zA-Z_][a-zA-Z0-9_]*                         return 'NAME';
+0|[-]?[1-9][0-9]*                              return 'INT';
+<<EOF>>                                        return 'EOF';
+
+/lex
+
+%token NAME STRING INT
+%token LA LC LB LP RA RP RB RC COMMA
+%token EOF
+
+%start input_with_eof
+
+%%
+
+name: NAME                              { $$ = String(yytext); };
+str: STRING                             { $$ = String(yytext).slice(1,-1); };
+int: INT                                { $$ = parseInt(String(yytext)); };
+
+input_with_eof: comp EOF               {
+    // console.log(JSON.stringify($1, "", 2));
+    return $1;
+};
+
+comp 
+    : exp          { $$ = $1; }
+    | comp exp     { $$ = s.comp($1, $2); }
+    ;
+
+exp
+    : LC labelled RC                    { $$ = $2; }
+    | LB list RB                        { $$ = {op: "vector", vector: $2}; }
+    | LA list RA                        { $$ = {op: "union", union: $2}; }
+    | name                              { $$ = {op: "ref", ref: $1}; }
+    | LP RP                             { $$ = s.identity;  }
+    | LP comp RP                        { $$ = $2;  }
+    | str                               { $$ = {op: "str", str: $1}; }
+    | int                               { $$ = {op: "int", int: $1}; }
+    | DOT int                           { $$ = {op: "dot", dot: $2}; }
+    | DOT str                           { $$ = {op: "dot", dot: $2}; }
+    | DOT name                          { $$ = {op: "dot", dot: $2}; }
+    ;
+
+labelled
+    :                                   { $$ = {op: "product", product: []}; }
+    | non_empty_labelled                { $$ = $1; }
+    ;
+
+non_empty_labelled
+    : comp_label
+        { $$ = {op: "product", product: [$1]}; }
+    | non_empty_labelled COMMA comp_label
+        { $1.product = [].concat($1.product,$3); $$ = $1; }
+    ;
+
+comp_label
+    : comp name  { $$ = {label: $2, exp: $1}; }
+    | comp str   { $$ = {label: $2, exp: $1}; }
+    ;
+
+list
+    : /*empty */             { $$ = []; }
+    | non_empty_list         { $$ = $1; }
+    ;
+
+non_empty_list
+    : comp                              { $$ = [$1]; }
+    | non_empty_list COMMA comp  { $$ = [].concat($1,$3); }
+    ;
+
+%%