@fraczak/k 1.2.0 → 1.2.1

package/Benchmark/range200

@@ -0,0 +1,200 @@
+1
+2
+3
+4
+5
+6
+7
+8
+9
+10
+11
+12
+13
+14
+15
+16
+17
+18
+19
+20
+21
+22
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+34
+35
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
+76
+77
+78
+79
+80
+81
+82
+83
+84
+85
+86
+87
+88
+89
+90
+91
+92
+93
+94
+95
+96
+97
+98
+99
+100
+101
+102
+103
+104
+105
+106
+107
+108
+109
+110
+111
+112
+113
+114
+115
+116
+117
+118
+119
+120
+121
+122
+123
+124
+125
+126
+127
+128
+129
+130
+131
+132
+133
+134
+135
+136
+137
+138
+139
+140
+141
+142
+143
+144
+145
+146
+147
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+182
+183
+184
+185
+186
+187
+188
+189
+190
+191
+192
+193
+194
+195
+196
+197
+198
+199
+200

package/README.md

@@ -1,106 +1,108 @@
-# k-language 
+# k-language
 
-	npm install @fraczak/k
+    npm install @fraczak/k
 
-Another 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:
+From javascript:
+
+    var k  = require("@fraczak/k"),
+        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.:
-   
+
         (E1 E2 E3 ...)
-	
-	Apart from empty composition, `()`, which defines _identity_, the paranthesis can be omitted.
+
+    Apart from empty composition, `()`, which defines _identity_, the
+    paranthesis can be omitted.
 
 2. product, e.g., vector or structure:
 
         [ E1, E2, E3, ... ]
         { E1 "e1", E2 "e2", E3 "e3", ... }
 
-  Now, structure can also be written similarly to JSON, ie., 
-  
-		{ 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
+
+    Elementary partial functions are:
+
+4. _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).
+
+5. _constants_, literals for Strings, Booleans, and
    Integers. Examples:
-   
-		"a string"
-		'another "String"'
-		123
-		false
-		null
-	
-3.  There is a number of built-in functions: `GT`, `EQ`, `PLUS`,
-	`TIMES`, `MINUS`, `DIV`, `CONCAT`, `toJSON`, `fromJSON`, `CONS`, `SNOC`. For example
-	
-		[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!
-		
-	A more interesting example could be:
-	
-		< GT .0, .1>
-		
-	which selects the maximum element in two element vector, i.e.,
-	
-		[3,8] < GT .0, .1 >    --> 8
+
+        "a string"
+        'another "String"'
+        123
+        false
+        null
+
+6. There is a number of built-in functions: `GT`, `EQ`, `PLUS`,
+    `TIMES`, `MINUS`, `DIV`, `CONCAT`, `toJSON`, `fromJSON`, `CONS`,
+    `SNOC`, `_log!`, ... For example:
+
+        [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!
+
+    A more interesting example could be:
+
+        < GT .0, .1>
+
+    which selects the maximum element in two element vector, i.e.,
+
+        [3,8] < GT .0, .1 >    --> 8
 
 ## User defined functions
 
-`k`-expression can be prefixed by function definitions. E.g.: 
+`k`-expression can be prefixed by function definitions. E.g.:
 
-	dec = [(),1] MINUS;
-	factorial = <
-	  [1,()] GT 1,
-	  [dec factorial, ()] TIMES
-	>;
-	{ () x, factorial "x!" }
+    dec = [(),1] MINUS;
+    factorial = <
+      [(),1] EQ 1,
+      [dec factorial, ()] TIMES
+    >;
+    { () x, < factorial, "not defined" > "x!" }
 
 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, 
-	>; 
-	max
+    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, 
+    >; 
+    max
 
-## Value encodings (also called _codes_)
+## Value encodings (_codes_)
 
-There are three predefined value encodings: `int`, `string`, and `bool`. The language
-supports `code`-expressions:
+There are three predefined value encodings: `int`, `string`, and
+`bool`. The language supports `code`-expressions:
 
-* product, e.g., `{int x, int y, bool flag}` (in JSON-like syntax `{x: int, y: int, flag: bool}`)
-* disjoint union, e.g., `<{} true, {} false>` (in JSON-like syntax `<true: {}, false: {}>`)
-* vector, e.g., `[ int ]` (all elements of the vector use the same encoding)
+* 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.:
 
-	$ tree = <string leaf, {tree left, tree right} tree>;
-
-or, the same in JSON-like notation:
-
-	$ tree = <leaf: string, tree: {left: tree, right: tree}>;
+    tree = <string leaf, {tree left, tree right} tree>;
 
 Each _code_ definition starts with a `$`.
 The above example defines new code called _tree_.
@@ -108,138 +110,164 @@ The above example defines new code called _tree_.
 The code can be then used in a `k`-expression as a filter. A `code`-expression
 within `k`-expression is again prefixed by `$`.
 
-	$ tree = <string leaf, {tree left, tree right} tree>;
-	inc = [(),1] PLUS;
-	max = <GT .0, .1>;
-	height = $ tree <
-		.leaf 0,
-		.tree [.left height, .right height] max inc
-	> $ int;
-	height
-
+    $ tree = <string leaf, {tree left, tree right} tree>;
+    inc = [(),1] PLUS;
+    max = <GT .0, .1>;
+    height = $ tree <
+        .leaf 0,
+        .tree [.left height, .right height] max inc
+    > $ int;
+    height
 
 ## 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) [ -1 ] [ json-file ]
-	       E.g., cat '{"a": 10}' | ./node_modules/.bin/k '[(),()]'
+    > ./node_modules/.bin/k
+    ... errors ...
+    Usage: ./node_modules/.bin/k ( k-expr | -k k-file) [ -1 ] [ 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}}
-	
+        > 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`-expression and apply the generated function to the `stdin`,
+   line by line:
 
-		$ ./node_modules/.bin/k '<["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
+        > ./node_modules/.bin/k '<["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:
-	
-		$ ./node_modules/.bin/k -k test.k
-	
-	If we want to read `json` objects from a file, e.g., `my-objects.json`, we do
-	
-		$ ./node_modules/.bin/k -k test.k 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");
-
-		k_expression = '()';
-		k.run(k_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
-
-		var k_fn = k.compile('{.name nom, <[.age, 18] GT .0, [.age, 12] GT "ado", "enfant"> age}');
-
-		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"}
-
-		var k_fn = k.compile('$t = < i: int, t: [ t ] > ; <$t, $int>');
-
-		k_fn(1);
-		// RETURNS: 1
-
-		k_fn({"i":1});
-		// RETURNS: {"i":1}
-
-		k_fn([{"i":2},{"i":3},{"t":[]}]);
-		// RETURNS: undefined
-
-		k_fn({"t":[{"i":2},{"i":3},{"t":[]}]});
-		// RETURNS: {"t":[{"i":2},{"i":3},{"t":[]}]}
+        > 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:
+
+        > ./node_modules/.bin/k -k test.k
+
+    If we want to read `json` objects from a file, e.g., `my-objects.json`, we do
+
+        > ./node_modules/.bin/k -k test.k 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}
+         ####################################################
+
+### 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.:
+
+    > ./node_modules/.bin/k-repl 
+     {'a' a, 'b' b} toJSON
+     => "{\"a\":\"a\",\"b\":\"b\"}"
+     {"a" a} toJSON fromJSON
+     => {"a":"a"}
+     inc = [(),1] PLUS; 1 inc inc
+     => 3
+     inc inc inc inc
+     => 7
+
+## Using from `javascript`
+
+     var k = require("k");
+
+     k_expression = '()';
+     k.run(k_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
+
+     var k_fn = k.compile('{.name nom, <[.age, 18] GT .0, [.age, 12] GT "ado", "enfant"> age}');
+
+     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"}
+
+     var k_fn = k.compile('$t = < i: int, t: [ t ] > ; <$t, $int>');
+
+     k_fn(1);
+     // RETURNS: 1
+
+     k_fn({"i":1});
+     // RETURNS: {"i":1}
+
+     k_fn([{"i":2},{"i":3},{"t":[]}]);
+     // RETURNS: undefined
+
+     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({"None":"None"});
+     // RETURNS: {"None":"None"}
+
+     k_fn({"list":{"ints":[]}});
+     // RETURNS: {"list":{"ints":[]}}
+
+     k_fn({"list":{"ints":[1,2,3]}});
+     // RETURNS: {"list":{"ints":[1,2,3]}}