@fraczak/k 1.3.4 → 2.0.1

package/README.md

@@ -4,36 +4,183 @@
 
 From javascript:
 
-    var k  = require("@fraczak/k"),
-        fn = k.compile("<.name,.nom,'?'>");
+    import k from "@fraczak/k";
+    
+    const fn = k.compile("<.name,.nom,'?'>");
     console.log([{name:"x"},{nom:"y"},{}].map(fn));
     // returns: [ "x", "y", "?" ]
 
-Another JSON transformation notation.  A `k`-expression (script)
-defines a __partial function__, i.e., a function which may fail
-for some input. `k`-expressions can be combined to build
-other `k`-expressions in three ways:
+---
 
-1. composition, e.g.:
+## k - the way of building and manipulating JSON-like data
 
-        (E1 E2 E3 ...)
+Technically, `k` is a notation for defining **first-order partial functions**.
 
-    Apart from empty composition, `()`, which defines _identity_, the
-    paranthesis can be omitted.
+An example of a _partial function_ is the _projection_, e.g., "`.toto`",
+which maps an object to its property named `toto`, or it is not defined if
+the property doesn't exist. E.g.,
 
-2. product, e.g., vector or structure:
+    1   .toto :
+    2        {"toto": 5, "titi": 10}  --> 5
+    3        {"titi": 10}             ... undefined // it is not a value!
 
-        [ E1, E2, E3, ... ]
-        { E1 "e1", E2 "e2", E3 "e3", ... }
+> Note: The above 3 lines should be read as follows. A `k`-expression
+> is printed in the first line (before "`:`").  The following lines
+> are examples of the function defined by the `k`-expression applayed
+> to JSON values (first part of each line).  If the function for the
+> value is defined, then the result is printed after "`-->`" (line 2 in
+> the above example).  If the function is not defined for the value,
+> then "`... undefined`" is printed (line 3).
 
-3. union (merge), e.g.:
+---
 
-        < E1, E2, E3, ... >
+### Combining "partial functions"
 
-    Elementary partial functions are:
+There are three ways of combining functions:
 
-4. _projection_, i.e., extracting the value of a given field or
-   index. Examples:
+1. **composition**: `(f1 f2 ...)`, e.g. `(.toto .titi)` extracts
+    nested field.
+
+         (.toto .titi) :
+             {"toto": {"titi": 10}}   --> 10
+             {"toto": 10 }            ... undefined
+             {}                       ... undefined
+
+2. **merge**: `< f1, f2,... >`, e.g., `<.toto, .titi>` extracts field
+    `toto` if present; otherwise extracts `titi`.
+
+         <.toto, .titi> :
+             {"toto": 5, "titi": 10}  --> 5
+             {"titi": 10 }            --> 10
+             {}                       ... undefined
+
+3. **product**: `{ f1 label1, f2 label2, ...}`, e.g., `{.toto TOTO,
+.titi TITI}` extracts two fields and builds a record out of them.
+
+         {.toto TOTO, .titi TITI} :
+             {"toto": 5, "titi": 10, "x": 3}  --> {"TOTO": 5, "TITI": 10}
+             {"titi": 10 }                    ... undefined
+
+---
+
+**QUIZ**: What is:
+
+- empty composition: `()` ?
+- empty merge: `<>` ?
+- empty product: `{}` ?
+- `{{{{} s} s} s}` ?
+- `({{{() a} b} c} .c .b .a)` ?
+
+---
+
+### Syntactic sugar
+
+- parenthesis can be omitted, except for the empty composition `()`,
+- dot (`.`) in "projection" acts as a separator so the space around it can be omitted.
+
+For example, `[(.toto .titi (.0 .1))]` can be written as `[.toto.titi.0.1]`.
+
+Comments can be introduced by `//`, `--`, `%`, or `#` and extends to
+the end of line.  Multiline `C`-like comments, `/* ... */`, are also
+supported.
+
+### Basic extensions
+
+#### Constants, i.e., literals for `strings`, `integers`, `booleans`, and `null`
+
+A constant defines a function which ignores its argument and produces
+the constant value. E.g.:
+
+    {123 int, "kScript" str, true bool, null null} :
+        "any"  --> {"int":123,"str":"kScript","bool":true,"null":null}
+
+#### Vector product
+
+Vector product can be seen as an abbreviation for product whose field
+names are integers starting from zero. E.g., `{.toto 0, .titi 1, 123 2}`
+can be written as `[.toto, .titi, 123]`.
+
+    [.toto, .titi, 12] :
+        {"toto": 5, "titi": 10 }  --> [5, 10, 12] 
+
+    .1 :
+        ["A","B","C"]  --> "B"
+        ["a"]          ... undefined
+
+---
+
+### Pragmatic extensions, aka "standard library"
+
+- `GT` : -- identity for lists of decreasing elements; undefined otherwise
+
+        [4,3]     --> [4,3]
+        [3,4]     ... undefined
+        []        --> []
+        [4,3,0]   --> [4,3,0]
+
+- `EQ` : -- identity for lists of equal elements; undefined otherwise
+
+        [4,4]     --> [4,4]
+        [4,5]     ... undefined
+        [4,4,4]   --> [4,4,4]
+        []        --> []
+
+- `{PLUS plus, TIMES times}` :
+
+        [1,2]     --> {"plus":3,"times":2}
+        [2,2,2]   --> {"plus":6,"times":8}
+        []        --> {"plus":0,"times":1}
+
+- `CONCAT` :
+
+        ["a","bc","d"] --> "abcd"
+
+- `toJSON` :
+
+        {"a": 12} --> "{\"a\":12}"
+
+- `fromJSON` :
+
+        "{\"a\":12}" --> {"a":12}
+
+- other predefined parial functions are: `DIV`, `FDIV`, `CONS`, `SNOC`, `toDateMsec`,
+  `toDateStr`, and `_log!`.
+
+---
+
+### Function definitions
+
+      dec = [(),-1] PLUS;
+      max = <SNOC [.0, .1 max] <GT.0, .1>, .0> ;
+      factorial = < [(),0] GT .0 [dec factorial, ()] TIMES, 1 >;
+
+### Codes (_types_)
+
+_Codes_ (prefixed by `$`) can be defined by taged union and product. E.g.:
+
+      $nat = <nat 1, {} 0>;
+      $pair = {nat x, nat y};
+
+      suc = {$nat 1};
+      add = $pair <{.x.1 x, .y suc y} add, .y>;
+
+#### Basic extension codes
+
+Since _basic extension_ introduces integers, booleans, and strings, there are three
+predefined types: `int`, `bool`, and `string`. A vector product code can also be defined
+by `[ codeExp ]`. All members of the vector are the same code. E.g.,
+
+     $intVector = [ int ];
+     $boolVector = [ bool ];
+     $tree = [ tree ];
+
+     emptyList? = $intVector $[ string ]; -- as only an empty vector can be a vector
+                                          -- of integers and a vector of strings
+---
+
+## Examples
+
+1. projection:
 
         .x
         ."field name"
@@ -42,7 +189,7 @@ other `k`-expressions in three ways:
     The function is defined only if its argument is a structure with
 the field (or a vector with the index).
 
-5. _constants_, literals for Strings, Booleans, and
+2. _constants_, literals for Strings, Booleans, and
    Integers. Examples:
 
         "a string"
@@ -51,14 +198,12 @@ the field (or a vector with the index).
         false
         null
 
-6. The other "built-in" functions: `GT`, `EQ`, `PLUS`,
-    `TIMES`, `DIV`, `CONCAT`, `toJSON`, `fromJSON`, `CONS`,
-    `SNOC`, `toDateMsec`, `toDateStr`, and `_log!`. For example:
+3. "built-in" functions:
 
-        [1, 2, 3] PLUS       --> integer constant function 6
-        [4, 4] TIMES toJSON  --> string constant function "16"
-        [3, 2] GT            --> vector constant function [3, 2]
-        [3, 4] GT            ... is not defined!
+        [1, 2, 3] PLUS       -- integer constant function 6
+        [4, 4] TIMES toJSON  -- string constant function "16"
+        [3, 2] GT            -- vector constant function [3, 2]
+        [3, 4] GT            -- ... undefined
 
     A more interesting example could be:
 
@@ -68,7 +213,7 @@ the field (or a vector with the index).
 
         [3,8] < GT .0, .1 >    --> 8
 
-## User defined functions
+### User defined functions
 
 `k`-expression can be prefixed by function definitions. E.g.:
 
@@ -83,22 +228,22 @@ the field (or a vector with the index).
 Another example could be finding the biggest (max) value in a vector:
 
     max = < 
-      SNOC         -- [x0, x1, x2, ...] -> [x0, [x1, x2, ...]]
-      [.0, .1 max] -- [x0, [x1, x2, ...]] -> [x0, max(x1,x2,...)], i.e., recursive call 
-      <GT .0, .1>, -- if x0 > max(x1,x2,...) then x0 else max(x1,x2,...)
-      -- when SNOC is not defined, e.g. the argument is a singleton vector [x0]
-      .0           -- [x0] -> x0, 
+      SNOC         #   [x0, x1, x2, ...] --> [x0, [x1, x2, ...]]
+      [.0, .1 max] #   [x0, [x1, x2, ...]] --> [x0, max(x1,x2,...)], i.e., recursive call 
+      <GT .0, .1>  #   if x0 > max(x1,x2,...) then x0 else max(x1,x2,...)
+    ,              # when SNOC is not defined, i.e., if the input vector has one element:
+      .0           #   [x0] --> x0
     >; 
     max
 
-## Value encodings (_codes_)
+### Value encodings (_codes_)
 
 There are three predefined value encodings: `int`, `string`, and
 `bool`. The language supports `code`-expressions:
 
-* product, e.g., `{int x, int y, bool flag}`
-* disjoint union, e.g., `<{} true, {} false>`
-* vector, e.g., `[ int ]` (all elements of the vector use the same
+- product, e.g., `{int x, int y, bool flag}`
+- disjoint union, e.g., `<{} true, {} false>`
+- vector, e.g., `[ int ]` (all elements of the vector use the same
   encoding)
 
 One can define recursive codes. E.g.:
@@ -120,7 +265,9 @@ within `k`-expression is again prefixed by `$`.
     > $ int;
     height
 
-## Command line script
+---
+
+## `k` (a command-line JSON processor using `k` syntax)
 
 There is a wrapper, `./node_modules/.bin/k` , which makes it easy to
 run the language from command line.
@@ -130,7 +277,7 @@ run the language from command line.
     Usage: ./node_modules/.bin/k ( k-expr | -k k-file) [ -1 ] [ json-file ]
     E.g., cat '{"a": 10}' | ./node_modules/.bin/k '[(),()]'
 
-### Examples
+For example:
 
 1. One `k`-expression with one `json`-object:
 
@@ -148,6 +295,8 @@ run the language from command line.
          {"z": 123}                            --> {"x&y":"no x nor y"}
          ^D - to interrupt
 
+   If the input is a multiline json object, we need to add `-1` to the command-line options.
+
 3. If the `k`-expression is long, it can be put in a file, e.g.:
 
         > cat test.k
@@ -186,7 +335,36 @@ run the language from command line.
          {"z": 123}
          ####################################################
 
-### k-REPL (Read-Evaluate-Print Loop)
+---
+
+### Short comparaison with `jq` tutorial examples: <https://stedolan.github.io/jq/tutorial/>
+
+1.
+        curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5' | jq '.'
+        curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5' | k  '()' -1 
+2.
+        curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5' | jq '.[0]'
+        curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5' | k  '.0' -1 
+3.
+        jq '.[0] | {message: .commit.message, name: .commit.committer.name}'
+        k '.0 {.commit.message message, .commit.committer.name name}' -1
+4. note: `k`-expression defines a partial function yielding a single json object, i.e., as far as `k` is concerned,
+   examples 4 and 5 of the `jq` tutorial are equivalent.
+5.
+        jq '[.[] | {message: .commit.message, name: .commit.committer.name}]'
+        k 'f = .commit {.message message, .committer.name name}; %\
+           map_f = <SNOC [.0 f,.1 map_f] CONS, [.0 f], []>; %\
+           map_f' -1 
+6.
+        jq '[.[] | {message: .commit.message, name: .commit.committer.name, parents: [.parents[].html_url]}]'
+        k 'map_html_url = <SNOC [.0 .html_url, .1 map_html_url] CONS, [.0 .html_url], []>; %\
+           f = {.commit.message message, .commit.committer.name name, .parents map_html_url parents}; %\
+           map_f = <SNOC [.0 f, .1 map_f] CONS, [.0 f] , []>; %\
+           map_f' -1 
+
+---
+
+## k-REPL (Read-Evaluate-Print Loop)
 
 Also there is a REPL, `./node_modules/.bin/k-repl`, which acts like a toy
 shell for the language. E.g.:
@@ -201,11 +379,13 @@ shell for the language. E.g.:
      inc inc inc inc
      => 7
 
-## Using from `javascript`
+---
+
+## Using `k` from `javascript`
 
-     var k = require("k");
+     import k from "@fraczak/k";
 
-     k_expression = '()';
+     let k_expression = '()';
      k.run(k_expression,"ANYTHING...");
      // RETURNS: "ANYTHING..."
 
@@ -248,7 +428,7 @@ shell for the language. E.g.:
      k_fn({"age":2,"name":"Mark"});
      // RETURNS: {"nom":"Mark","age":"enfant"}
 
-     var k_fn = k.compile('$t = < i: int, t: [ t ] > ; <$t, $int>');
+     k_fn = k.compile('$t = < i: int, t: [ t ] > ; <$t, $int>');
 
      k_fn(1);
      // RETURNS: 1
@@ -262,7 +442,7 @@ shell for the language. E.g.:
      k_fn({"t":[{"i":2},{"i":3},{"t":[]}]});
      // RETURNS: {"t":[{"i":2},{"i":3},{"t":[]}]}
 
-     var k_fn = k.compile('$ < < [ int ] ints, [ bool ] bools > list, string None>');
+     k_fn = k.compile('$ < < [ int ] ints, [ bool ] bools > list, string None>');
 
      k_fn({"None":"None"});
      // RETURNS: {"None":"None"}

package/codes.mjs

@@ -0,0 +1,103 @@
+function are_different(classes, representatives, name1, name2, codes) {
+  if (name1 === name2) return false;
+  const code1 = codes[name1];
+  const code2 = codes[name2];
+  if (code1.code !== code2.code) return true;
+  switch (code1.code) {
+    case "union":
+    case "product":
+      const [fields1, fields2] = [code1, code2].map((code) => {
+        const arg = code[code.code];
+        return Object.keys(arg).reduce((fields, label) => {
+          const ref = representatives[arg[label]];
+          fields[label] = ref != null ? ref : arg[label];
+          return fields;
+        }, {});
+      });
+      if (Object.keys(fields1).length !== Object.keys(fields2).length)
+        return true;
+
+      for (const field in fields1) {
+        if (fields2[field] !== fields1[field]) return true;
+      }
+      break;
+    case "vector":
+      const [arg1, arg2] = [code1, code2].map(
+        ({ vector }) => representatives[vector] || vector
+      );
+      if (arg1 !== arg2) return true;
+  }
+  return false;
+}
+
+function minimize(codes) {
+  const names = Object.keys(codes);
+  const classes = {};
+  classes["{}"] = names;
+  const representatives = names.reduce((representatives, name) => {
+    representatives[name] = "{}";
+    return representatives;
+  }, {});
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const name1 in classes) {
+      const [eq_names, dif_names] = classes[name1].reduce(
+        ([eq_names, dif_names], name2) => {
+          if (are_different(classes, representatives, name1, name2, codes)) {
+            dif_names.push(name2);
+          } else {
+            eq_names.push(name2);
+          }
+          return [eq_names, dif_names];
+        },
+        [[], []]
+      );
+      classes[name1] = eq_names;
+
+      if (dif_names.length > 0) {
+        const new_rep = dif_names[0];
+        changed = true;
+        classes[new_rep] = dif_names;
+        dif_names.forEach((name) => (representatives[name] = new_rep));
+      }
+    }
+  }
+  return { classes, representatives };
+}
+
+function normalize(label_ref_map, representatives) {
+  return Object.keys(label_ref_map).reduce((result, label) => {
+    const name = label_ref_map[label];
+    result[label] = representatives[name] || name;
+    return result;
+  }, {});
+}
+
+function normalizeAll(codes, representatives) {
+  return Object.keys(codes).reduce(function (normalized, name) {
+    if (name === representatives[name]) {
+      const code = codes[name];
+      switch (code.code) {
+        case "union":
+        case "product":
+          normalized[name] = { code: code.code };
+          normalized[name][code.code] = normalize(
+            code[code.code],
+            representatives
+          );
+          break;
+        case "vector":
+          normalized[name] = {
+            code: "vector",
+            vector: representatives[code.vector] || code.vector,
+          };
+      }
+    }
+
+    return normalized;
+  }, {});
+}
+
+export default { minimize, normalize, normalizeAll };
+export { minimize, normalize, normalizeAll };

package/index.mjs

@@ -0,0 +1,32 @@
+import { parse } from "./parser.mjs";
+import run from "./run.mjs";
+import t from "./codes.mjs";
+
+function finalize(codes) {
+  const representatives = t.minimize(codes).representatives;
+  return {
+    codes: t.normalizeAll(codes, representatives),
+    representatives,
+  };
+}
+
+function compile(script) {
+  const { defs, exp } = parse(script);
+  const { codes, representatives } = finalize(defs.codes);
+  run.defs = {
+    codes,
+    representatives,
+    rels: defs.rels,
+  };
+  return run.bind(null, exp);
+}
+
+compile.doc = "Transforms k-script (string) into a function";
+
+function runScriptOnData(script, data) {
+  return compile(script)(data);
+}
+runScriptOnData.doc = "Run 'script' (string) on 'data': (script,data) -> data";
+
+export default { compile, run: runScriptOnData, parse };
+export { compile, runScriptOnData as run, parse };

package/k.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import k from "./index.mjs";
+
+const splice = [].splice;
+
+const prog = process.argv[1];
+
+let kScript, jsonStream, oneJson;
+
+({ kScript, jsonStream, oneJson } = ((oneJson, args) => {
+  let 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 === "-1") {
+        oneJson = true;
+        arg = args.shift();
+      }
+      if (arg == null) {
+        return process.stdin;
+      }
+      return fs.createReadStream(arg);
+    })(args.shift());
+    return { kScript, jsonStream, oneJson };
+  } catch (error) {
+    e = error;
+    console.error(e);
+    console.error(`Usage: ${prog} ( k-expr | -k k-file ) [ -1 ] [ json-file ]`);
+    console.error(`       E.g.,  echo '{\"a\": 12}' | ${prog} '[(),()]'`);
+    return process.exit(-1);
+  }
+})(false, process.argv.slice(2)));
+
+if (oneJson) {
+  const buffer = [];
+  jsonStream.on("data", (data) => buffer.push(data));
+  jsonStream.on("end", () => {
+    try {
+      console.log(JSON.stringify(kScript(JSON.parse(buffer.join(""))), null, 2));
+    } catch (error) {
+      console.error(error);
+    }
+  });
+} else {
+  let buffer = [];
+  let line = 0;
+  jsonStream.on("data", (data) => {
+    const [first, ...rest] = data.toString("utf8").split("\n");
+    buffer.push(first);
+    if (rest.length > 0) {
+      const todo = buffer.join("");
+      const last = rest.pop();
+      buffer = [last];;
+      for (const exp of [todo, ...rest]) {
+        if (!exp.match(/^[ \n\t]*(?:#.*)?$/)) {
+          try {
+            console.log(JSON.stringify(kScript(JSON.parse(exp))));
+          } catch (error) {
+            console.error(`Problem [line ${line}]: '${exp}'`);
+            console.error(error);
+          }
+        }
+        line++;
+      }
+    }
+  });
+}

package/package.json

@@ -1,13 +1,11 @@
 {
     "name": "@fraczak/k",
-    "version": "1.3.4",
+    "version": "2.0.1",
     "description": "k-language for JSON-like data transformation",
-    "main": "index.js",
+    "main": "index.mjs",
     "scripts": {
-        "prepare": "coffee -c symbol-table.coffee; jiwson parser.jison",
-        "prepublishOnly": "coffee -c *.coffee; echo '#!/usr/bin/env node' | cat - k.js > k.sh; echo '#!/usr/bin/env node' | cat - repl.js > repl.sh;",
-        "all": "coffee -c *.coffee; npm run prepare; npm run prepublishOnly",
-        "test": "coffee -c symbol-table.coffee; jiwson parser.jison; coffee test.coffee"
+        "prepare": "jiwson -m es6 parser.jison -o parser.mjs",
+        "test": "node test.mjs"
     },
     "repository": {
         "type": "git",
@@ -16,11 +14,10 @@
     "author": "Wojciech Fraczak",
     "license": "ISC",
     "bin": {
-        "k": "./k.sh",
-        "k-repl": "./repl.sh"
+        "k": "./k.mjs",
+        "k-repl": "./repl.mjs"
     },
     "devDependencies": {
-        "coffeescript": "^2.7.0",
         "jiwson": "^0.1.1"
     }
 }

package/parser.jison

@@ -1,6 +1,6 @@
 %{
 
-var s = require("./symbol-table");
+import s from "./symbol-table.mjs";
 
 function fromEscString(escString) {
   const isSingleQuoted = escString.startsWith("'");

package/{parser.js → parser.mjs}

@@ -1,3 +1,4 @@
+
 /* parser generated by jison 0.1.1 */
 /*
   Returns a Parser object of the following structure:
@@ -74,7 +75,7 @@
 
 
 
-var s = require("./symbol-table");
+import s from "./symbol-table.mjs";
 
 function fromEscString(escString) {
   const isSingleQuoted = escString.startsWith("'");
@@ -756,20 +757,11 @@ Parser.prototype = parser;parser.Parser = Parser;
 return new Parser;
 })();
 
-
-if (typeof require !== 'undefined' && typeof exports !== 'undefined') {
-exports.parser = parser;
-exports.Parser = parser.Parser;
-exports.parse = function () { return parser.parse.apply(parser, arguments); };
-exports.main = function commonjsMain (args) {
-    if (!args[1]) {
-        console.log('Usage: '+args[0]+' FILE');
-        process.exit(1);
-    }
-    var source = require('fs').readFileSync(require('path').normalize(args[1]), "utf8");
-    return exports.parser.parse(source);
-};
-if (typeof module !== 'undefined' && require.main === module) {
-  exports.main(process.argv.slice(1));
+const ___parser = parser;
+const ___Parser = parser.Parser;
+const ___parse = parser.parse.bind(parser);
+export {
+___parser as parser,
+___Parser as Parser,
+___parse as parse 
 }
-}