ig-serialize 1.0.1 → 1.0.5

package/README.md

@@ -11,5 +11,71 @@ This extends the default JSON serialization adding the following:
 
 ## Motivation
 
+This was originally built as a companion to a testing module for a 
+programming class, illustrating several concepts, including: guaranteed 
+clean isolation of data structures via serialization, instrumenting code 
+and tooling design, basic parsing, among others.
+
+
+
+## Installation
+
+
+## Introduction
+
+
+### Serializing functions
+
+Due to how JavaScript is designed it is not possible to trivially and 
+fully clone a function with all of it's references, `.serilaize(..)` will
+not attempt to clone any state a function may have, this will lead to 
+loosing:
+
+- Function closure
+- Attributes set on the function or any of it's prototypes, including the
+  `.__proto__` value if it was changed.
+ 
+Thus, care must be taken when serializing structures containing function.
+
+
+## API
+
+### `serialize(..)` / `eJSON.stringify(..)`
+
+### `deserialize(..)` / 'eJSON.parse(..)'
+
+### `deepCopy(..)`
+
+### `partialDeepCopy(..)`
+
+
+## Format
+
+The output of `.serialize(..)` is a strict superset of [standard JSON](https://www.json.org/json-en.html), 
+while the input format is a bit more relaxed than in several details.
+
+Extensions to JSON:
+- Recursion
+- undefined / NaN
+- BigInt
+- Map / Set
+- Function
+
+### Structural paths
+
+### Recursion
+
+### null types
+
+### BigInt
+
+### Map / Set
+
+### Functions
+
+
+
+
+
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ig-serialize",
-  "version": "1.0.1",
+  "version": "1.0.5",
   "description": "experimental extended json serializaion...",
   "main": "serialize.js",
   "scripts": {

package/serialize.js

@@ -1,5 +1,41 @@
 /**********************************************************************
 * 
+* TODO would be useful to split this into:
+* 	- object traversal using object path
+* 		Object.walk(..) -- a-la Python's walk(..)
+* 		Object.graph(..)
+* 			like .map(..) but deep and paths instead of indexes...
+* 	- get/set object by path
+* 		Object.get(..) / Object.set(..)
+*
+* XXX the current path implementation is fully complient to the task at 
+* 	hand but it will not suite the diff task as there is no way to know
+* 	the meaning of the path element without seeing the object (map/set 
+* 	indexes)...
+* 	a different path format would suit both tasks and make things more 
+* 	universal:
+* 		Current:
+*	 		[1, 'a', 5, 0, 3]
+*	 		 \   \   +-++  +---------------- Set index (from context)
+*	 		  \   \     +------------------- Map index (from context)
+*	 		   \   +------------------------ Object key (string)
+*	 		    +--------------------------- Array index (from context)
+* 		Proposed:
+*	 		[1, 'a', ['map', 5, 0], ['set', 3]]
+*	 		 \   \   +---------+-+  +------+-+
+*	 		  \   \             \           +--- Set index
+*			   \   \             +-------------- Map index
+*				\   +--------------------------- Object key (string)
+*				 +------------------------------ Array index (number)
+*		And/or:
+*	 		[1, ['object', 3], ['map', 5, 0], ['set', 3]]
+*	 		    +---------+-+
+*	 		               +----- Object attr index
+*	The questions is which to use as default for objects, the key or 
+*	position?
+*	(XXX move this note to diff.jx)
+*
+* XXX do a revision of the JSON standard for things I could have forgotten...
 *
 *
 **********************************************************************/
@@ -41,8 +77,12 @@ var debug = {
 
 //---------------------------------------------------------------------
 
+module.STRING_LENGTH_REF = RECURSIVE.length * 8
+
+
 //
-// 	serialize(obj[, indent[, depth]])
+// 	serialize(obj[, options])
+// 	serialize(obj[, indent[, depth[, options]]])
 // 		-> str
 //
 // 	indent can be:
@@ -50,7 +90,7 @@ var debug = {
 // 		string	- string to use for indenting
 //
 //
-// 	_serialize(obj, base_path, seen, indent, depth, functions)
+// 	_serialize(obj, base_path, seen, indent, depth, options)
 // 		-> str
 //
 //
@@ -98,12 +138,16 @@ var debug = {
 // 		]
 //
 //
-// XXX BUG: using non-whitespace as indent breaks the depth of the first 
+// XXX BUG?: using non-whitespace as indent breaks the depth of the first 
 // 		or last elements in sequences
 // 		...breaks .trim*() in Map/Set/Object...
 var _serialize = 
 module._serialize = 
-function(obj, path=[], seen=new Map(), indent, depth=0, functions){
+function(obj, path=[], seen=new Map(), indent, depth=0, options={}){
+	var string_length_ref = 
+		options.string_length_ref 
+			?? module.STRING_LENGTH_REF
+
 	// recursive...
 	var p = seen.get(obj)
 	if(p != null){
@@ -117,14 +161,25 @@ function(obj, path=[], seen=new Map(), indent, depth=0, functions){
 		seen.set(obj, path)
 		// if functions array is given add function to it and store its
 		// index in the serialized data...
-		if(functions instanceof Array){
-			functions.push(obj) 
-			obj = functions.length-1 }
+		if(options.functions instanceof Array){
+			options.functions.push(obj) 
+			obj = options.functions.length-1 }
 		var s = '('+ obj.toString() +')'
 		return FUNCTION
 			.replace('%', s.length +','+ s) }
 
+	// long strings...
+	// NOTE: this saves on output size...
+	if(typeof(obj) == 'string' 
+			&& obj.length > string_length_ref){
+		seen.set(obj, path) }
+	// BigInt...
+	if(typeof(obj) == 'bigint'){
+		seen.set(obj, path)
+		return obj.toString() +'n' }
+
 	// atomics...
+	// NOTE: these are not stored in seen thus are not re-referenced...
 	if(obj === null){
 		return NULL }
 	if(typeof(obj) != 'object'){
@@ -137,6 +192,8 @@ function(obj, path=[], seen=new Map(), indent, depth=0, functions){
 				INFINITY
 			: obj === -Infinity ?
 				NEG_INFINITY
+			// XXX might be a good idea to reference really long strings instead 
+			// 		of storing each...
 			: JSON.stringify(obj, null, indent) } 
 
 	// objects...
@@ -152,20 +209,20 @@ function(obj, path=[], seen=new Map(), indent, depth=0, functions){
 		for(var i=0; i < obj.length; i++){
 			elems.push(
 				i in obj ?
-					_serialize(obj[i], [...path, i], seen, indent, depth+1, functions)
+					_serialize(obj[i], [...path, i], seen, indent, depth+1, options)
 					: EMPTY) }
 	} else if(obj instanceof Map){
 		pre = 'Map(['
 		post = '])'
 		elems = [
-			_serialize([...obj], path, seen, indent, depth, functions)
+			_serialize([...obj], path, seen, indent, depth, options)
 				.slice(1, -1)
 				.trim() ]
 	} else if(obj instanceof Set){
 		pre = 'Set(['
 		post = '])'
 		elems = [
-			_serialize([...obj], path, seen, indent, depth, functions)
+			_serialize([...obj], path, seen, indent, depth, options)
 				.slice(1, -1)
 				.trim() ]
 	} else {
@@ -175,7 +232,7 @@ function(obj, path=[], seen=new Map(), indent, depth=0, functions){
 			elems.push(`${ 
 					JSON.stringify(k) 
 				}:${ indent != null ? ' ' : '' }${ 
-					_serialize(v, [...path, k], seen, indent, depth+1, functions)
+					_serialize(v, [...path, k], seen, indent, depth+1, options)
 						// relevant for pretty-printing only...
 						.trimLeft()
 				}`) } }
@@ -196,8 +253,8 @@ function(obj, path=[], seen=new Map(), indent, depth=0, functions){
 // user interface...
 var serialize = 
 module.serialize = 
-function(obj, indent, depth=0, functions){
-	return _serialize(obj, [], new Map(), indent, depth, functions) }
+function(obj, indent, depth=0, options){
+	return _serialize(obj, [], new Map(), indent, depth, options) }
 
 
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
@@ -211,7 +268,7 @@ module.eJSON = {
 
 		0: 'number', 1: 'number', 2: 'number', 3: 'number', 4: 'number',
 		5: 'number', 6: 'number', 7: 'number', 8: 'number', 9: 'number',
-		'.': 'number', '-': 'number',
+		'.': 'number', '-': 'number', '+': 'number',
 
 		'[': 'array',
 		'{': 'object',
@@ -351,12 +408,37 @@ module.eJSON = {
 				&& str.slice(i, i+'-Infinity'.length) == '-Infinity'){
 			return [-Infinity, i+'-Infinity'.length, line] }
 		// numbers...
-		var j = i+1
+		// XXX do we need to handle the odd case of 077 vs 088???
+		var j = i
+		var mode = 'dec'
+		if(str[j] == '0' 
+				&& 'xXbBoO'.includes(str[j+1])){
+			mode = str[j+1]
+			j++ }
+		j++
 		while(j < str.length
 				&& (str[j] == '.'
+					// dec/oct/bin...
+					// XXX do we need to be pedantic and check the rest 
+					// 		of the modes explicitly???
 					|| (str[j] >= '0'
-						&& str[j] <= '9'))){
+						&& str[j] <= '9')
+					// hex...
+					|| (mode == 'x'
+						&& ((str[j] >= 'a'
+								&& str[j] <= 'f')
+							|| (str[j] >= 'A'
+								&& str[j] <= 'F')))
+					// exponent...
+					|| str[j] == 'e'
+						|| str[j] == 'E')){
+			if('eE'.includes(str[j]) 
+				&& '+-'.includes(str[j+1])){
+				j++ }
 			j++ }
+		// BigInt...
+		if(str[j] == 'n'){
+			return [ BigInt(str.slice(i, j)), j+1, line ] }
 		return [ str.slice(i, j)*1, j, line ] },
 	// XXX TEST count \\n
 	string: function(state, path, match, str, i, line){
@@ -381,7 +463,10 @@ module.eJSON = {
 		if(j == str.length 
 				&& str[j-1] != match){
 			this.error('Unexpected end of input wile looking fot "'+ match +'".', str, i, line) }
-		return [ str.slice(i+1, j), j+1, line ] },
+		// NOTE: this is cheating -- instead of dancing around and 
+		// 		replicating the full functionality of JSON.parse(..) we
+		// 		are simply falling back on it, as we did when serializing.
+		return [ JSON.parse(`"${str.slice(i+1, j)}"`), j+1, line ] },
 	identifier: function(state, path, match, str, i, line){
 		debug.lex('identifier', str, i, line)
 		if(!/[a-zA-Z_]/.test(str[i])){
@@ -543,7 +628,6 @@ module.eJSON = {
 	// NOTE: this uses eval(..) so care must be taken when enabling this...
 	func: function(state, path, match, str, i, line){
 		if(state.functions == null){
-			console.log('---', state)
 			this.error('Deserializing functions disabled.', str, i, line) }
 
 		debug.lex('function', str, i, line)
@@ -555,7 +639,7 @@ module.eJSON = {
 			this.error('Expected "," got "'+ str[i] +'"', str, i, line) }
 		i++
 
-		// func ref...
+		// func index...
 		if(state.functions instanceof Array){
 			var [n, i, line] = this.number(state, path, str[i+1], str, i+1, line)
 			res = state.functions[n]
@@ -604,10 +688,10 @@ module.eJSON = {
 		return this[handler](state, path, match, str, i, line) },
 
 
-	parse: function(str, functions){
+	parse: function(str, options={}){
 
 		// stage 1: build the object...
-		var state = {functions}
+		var state = {functions: options.functions}
 		var res = this.value(state, [], str)[0] 
 
 		// stage 2: link the recursive structures...
@@ -615,13 +699,20 @@ module.eJSON = {
 			this.setItem(res, a, this.getItem(res, b)) }
 
 		return res },
+
+	// to comply with POLS...
+	stringify: serialize,
 }
 
 
 var deserialize =
 module.deserialize =
-function(str, functions){
-	return eJSON.parse(str, functions) }
+function(str, options){
+	options = 
+		options === true ?
+			{functions: true}
+			: options
+	return eJSON.parse(str, options) }
 
 
 
@@ -630,18 +721,20 @@ function(str, functions){
 
 var deepCopy =
 module.deepCopy =
-function(obj, functions){
+function(obj, funcs){
+	var options = {functions: funcs}
 	return deserialize(
-		serialize(obj, null, 0, functions), 
-		functions) }
+		serialize(obj, null, 0, options), 
+		options) }
 
 
 var partialDeepCopy =
 module.partialDeepCopy =
 function(obj, funcs=[]){
+	var options = {functions: funcs}
 	return deserialize(
-		serialize(obj, null, 0, funcs), 
-		funcs) }
+		serialize(obj, null, 0, options), 
+		options) }
 
 
 

package/test.js

@@ -26,6 +26,8 @@ var eJSON = require('./serialize')
 var json = true
 var ejson = false
 
+var pre_cycle = true
+
 // XXX test whitespace handling...
 var setups = test.Setups({
 	'true': function(assert){
@@ -43,17 +45,23 @@ var setups = test.Setups({
 		return ['123', json] },
 	'number-neg': function(assert){
 		return ['-123', json] },
+	//'number-pos': function(assert){
+	//	return ['+123', json] },
+	'number-exp': function(assert){
+		return ['1e+100', json] },
 	'number-zero': function(assert){
 		return ['0', json] },
 	'float-a': function(assert){
 		return ['0.123', json] },
 	'float-b': function(assert){
 		return ['1.23', json] },
+	'bigint': function(assert){
+		return ['999999999999999999999n'] },
 	// XXX need a way to test this...
 	//'float-a': function(assert){
-	//	return '.123' },
+	//	return ['.123'] },
 	//'float-c': function(assert){
-	//	return '123.' },
+	//	return ['123.'] },
 	// XXX also test:
 	// 		hex/bin/orc/...
 	Infinity: function(assert){
@@ -64,6 +72,10 @@ var setups = test.Setups({
 	// XXX also test diffrerent quotations...
 	string: function(assert){
 		return ['"string"', json] },
+	'string-empty': function(assert){
+		return ['""', json] },
+	'string-multiline': function(assert){
+		return ['"string\\nstring\\nstring"', json] },
 
 	'array-empty': function(assert){
 		return ['[]', json] },
@@ -99,7 +111,6 @@ var setups = test.Setups({
 		return ['Map([[<RECURSIVE[]>,"value"]])'] },
 	'map-recursive-value': function(assert){
 		return ['Map([["key",<RECURSIVE[]>]])'] },
-
 })
 
 test.Modifiers({
@@ -163,7 +174,6 @@ test.Tests({
 		// XXX
 	},
 
-	//* XXX ERR
 	'partial-deep-copy': function(assert, [setup]){
 		var obj = eJSON.deserialize(setup, true)
 		var funcs = []
@@ -177,17 +187,85 @@ test.Tests({
 	//*/
 })
 
-/* XXX these break things...
 test.Cases({
-	'deep-copy-function': function(assert, [setup]){
-		// XXX check function isolation...
-	},
-
-	'partial-deep-copy-function': function(assert, [setup]){
-		// XXX check function isolation...
-	},
+	//
+	// Format:
+	// 	[
+	// 		[ "<extended-syntax>", "<JSON-syntax>" ],
+	// 		...
+	// 	]
+	//
+	// NOTE: these syntax variants are not output by .serialize(..) this it
+	// 		is less critical to test them in the main loop.
+	// 		XXX though it would be nice to do so...
+	tests: [
+		// numbers/floats...
+		['.123', '0.123'],
+		['123.', '123'],
+		['+123', '123'],
+		['123e100', '123e+100'],
+		['0xff', '255'],
+
+		// string quotes...
+		["'abc'", '"abc"'],
+		['`abc`', '"abc"'],
+
+		// arrays...
+		['[1,2,]', '[1,2]'],
+
+		// sparse arrays...
+		['[<empty>]', '[,]'],
+		['[1,2,<empty>]', '[1,2,,]'],
+		['[1,2,<empty>]', '[1,2,<empty>,]'],
+	],
+	'syntax-simplifications': function(assert){
+		var aa, bb
+		for(var [a, b] of this.tests){
+			assert(eJSON.serialize(aa = eJSON.deserialize(a)) == eJSON.serialize(bb = eJSON.deserialize(b)),
+				`"${ a }" and "${ b }" should deserialize to the samve value.`,
+					'got:', aa, 'and', bb, 'resp.') } },
+
+	_make_object_with_methods: function(){
+		var in_closure = 123
+		return {
+			stateful: function(){
+				return typeof(in_closure) != 'undefined' ?
+		   			'state_retained'
+					: 'state_lost' },
+			stateless: function(){
+				return 'stateless' },
+		} },
+	'deep-copy-function': function(assert){
+		var obj = this._make_object_with_methods()
+		var obj_copy = eJSON.deepCopy(obj, true)
+
+		// sanity checks...
+		assert(obj.stateless() == 'stateless')
+		assert(obj.stateful() == 'state_retained')
+		assert(obj_copy.stateless() == 'stateless')
+
+		// context should be lost...
+		assert(
+			obj_copy.stateful() == 'state_lost',
+			'Function closure not lost.')
+		assert(obj.stateful !== obj_copy.stateful,
+			'Function objects retained.') },
+	'partial-deep-copy-function': function(assert){
+		var obj = this._make_object_with_methods()
+		var obj_copy = eJSON.partialDeepCopy(obj)
+
+		// sanity checks...
+		assert(obj.stateless() == 'stateless')
+		assert(obj.stateful() == 'state_retained')
+		assert(obj_copy.stateless() == 'stateless')
+
+		// context should be retained...
+		assert(
+			obj_copy.stateful() == 'state_retained',
+			'Function closure lost.') 
+		assert(obj.stateful === obj_copy.stateful,
+			'Function objects not retained.') },
 })
-//*/
 
 
 //---------------------------------------------------------------------

package/serialize2.js

@@ -1,645 +0,0 @@
-/**********************************************************************
-* 
-*
-*
-**********************************************************************/
-((typeof define)[0]=='u'?function(f){module.exports=f(require)}:define)
-(function(require){ var module={} // make module AMD/node compatible...
-/*********************************************************************/
-
-
-var EMPTY = '<empty>'
-var NULL = 'null'
-var UNDEFINED = 'undefined'
-var NAN = 'NaN'
-var INFINITY = 'Infinity'
-var NEG_INFINITY = '-Infinity'
-
-var RECURSIVE = '<RECURSIVE%>'
-
-var FUNCTION = '<FUNCTION[%]>'
-
-
-
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
-
-module.DEBUG = false
-
-var DEBUG_PREFIX = '---'
-
-var debug = {
-	context: 16,
-
-	log: function(...args){
-		if(!module.DEBUG){
-			return }
-		return console.log(DEBUG_PREFIX, ...arguments) },
-	lex: function(name, str, i, line){
-		return this.log(name +':', str.slice(i, i+this.context) +'...') },
-}
-
-
-//---------------------------------------------------------------------
-
-//
-// 	serialize(obj[, indent[, depth]])
-// 		-> str
-//
-// 	indent can be:
-// 		number	- number of spaces to use for indent
-// 		string	- string to use for indenting
-//
-//
-// 	_serialize(obj, base_path, seen, indent, depth, functions)
-// 		-> str
-//
-//
-// Paths
-// 	A path is a chain of indexes/keys leading to a specific object in 
-// 	tree.
-//
-// 	the root object is referenced by an empty path array.
-//
-// 	For sets, positional indexes are used, i.e. a set is treated like 
-// 	an array ov values.
-//
-// 	For maps a two number index is used with the first being the position
-// 	of the item and the second indicated if the target is the key or the 
-// 	value. i.e. a map is treated like an array of key value pairs.
-//
-//
-// 	Examples:
-// 		Object						   paths
-// 		---------------------------------------------------------------
-// 		obj = [						<- []
-// 			null,					<- [0]
-// 			[
-// 				'a', 
-// 				'b', 				<- [1, 1]
-// 				'c',
-// 			],
-// 			Set([ 
-// 				1, 
-// 				2, 
-// 				3,					<- [2, 2]
-// 			]),
-// 			Map([i					<- [3]   +----- index of elemnt in map
-// 				[							/  +--- 0 means key
-// 					'key',			<- [3, 0, 0]
-// 					'value'			<- [3, 0, 1]
-// 				],                             +--- 1 means value
-// 				[
-// 					[
-// 						123			<- [3, 1, 0, 0]
-// 					],
-// 					'got tired of thinking up names',
-// 				],
-// 			]),
-// 		]
-//
-//
-// XXX BUG: using non-whitespace as indent breaks the depth of the first 
-// 		or last elements in sequences
-// 		...breaks .trim*() in Map/Set/Object...
-var _serialize = 
-module._serialize = 
-function(obj, path=[], seen=new Map(), indent, depth=0, functions){
-	// recursive...
-	var p = seen.get(obj)
-	if(p != null){
-		// NOTE: _serialize(..) is always printed flat here, regardless of indent/depth...
-		return RECURSIVE.replace('%', _serialize(p)) }
-
-	// functions...
-	// NOTE: we are storing function length to avoid parsing the function...
-	// NOTE: storing length is a potential attack vector...
-	if(typeof(obj) == 'function'){
-		seen.set(obj, path)
-		// if functions array is given add function to it and store its
-		// index in the serialized data...
-		if(functions != null){
-			functions.push(obj) 
-			obj = functions.length-1 }
-		var s = '('+ obj.toString() +')'
-		return FUNCTION
-			.replace('%', s.length +','+ s) }
-
-	// atomics...
-	if(obj === null){
-		return NULL }
-	if(typeof(obj) != 'object'){
-		return typeof(obj) == 'number' 
-					&& isNaN(obj) ?
-				NAN
-			: obj === undefined ?
-				UNDEFINED
-			: obj === Infinity ?
-				INFINITY
-			: obj === -Infinity ?
-				NEG_INFINITY
-			: JSON.stringify(obj, null, indent) } 
-
-	// objects...
-	seen.set(obj, path)
-	
-	var elems = []
-	var pre = ''
-	var join = ','
-	var post = ''
-	if(obj instanceof Array){
-		pre = '['
-		post = ']'
-		for(var i=0; i < obj.length; i++){
-			elems.push(
-				i in obj ?
-					_serialize(obj[i], [...path, i], seen, indent, depth+1, functions)
-					: EMPTY) }
-	} else if(obj instanceof Map){
-		pre = 'Map(['
-		post = '])'
-		elems = [
-			_serialize([...obj], path, seen, indent, depth, functions)
-				.slice(1, -1)
-				.trim() ]
-	} else if(obj instanceof Set){
-		pre = 'Set(['
-		post = '])'
-		elems = [
-			_serialize([...obj], path, seen, indent, depth, functions)
-				.slice(1, -1)
-				.trim() ]
-	} else {
-		pre = '{'
-		post = '}'
-		for(var [k, v] of Object.entries(obj)){
-			elems.push(`${ 
-					JSON.stringify(k) 
-				}:${ indent != null ? ' ' : '' }${ 
-					_serialize(v, [...path, k], seen, indent, depth+1, functions)
-						// relevant for pretty-printing only...
-						.trimLeft()
-				}`) } }
-
-	// handle indent...
-	if(indent != null){
-		i = indent.repeat(depth)
-		s = i + indent
-		if(elems.length > 0){
-			pre = pre + '\n' + s
-			post = '\n' + i + post
-			// XXX set limit for number of elements to keep horizontal...
-			// 		...also account for element length...
-			join = join + '\n' + s } }
-
-	return pre+ elems.join(join) +post }
-
-// user interface...
-var serialize = 
-module.serialize = 
-function(obj, indent, depth=0, functions){
-	return _serialize(obj, [], new Map(), indent, depth, functions) }
-
-
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
-
-// XXX better error handling...
-// XXX try and make this single stage (see notes for : .recursive(..))
-var eJSON = 
-module.eJSON = {
-	chars: {
-		'"': 'string', "'": 'string', '`': 'string', 
-
-		0: 'number', 1: 'number', 2: 'number', 3: 'number', 4: 'number',
-		5: 'number', 6: 'number', 7: 'number', 8: 'number', 9: 'number',
-		'.': 'number', '-': 'number',
-
-		'[': 'array',
-		'{': 'object',
-	},
-	words: {
-		true: true,
-		false: false,
-
-		Infinity: 'number',
-		
-		'Set(': 'set',
-		'Map(': 'map',
-
-		null: null,
-		undefined: undefined,
-		NaN: NaN,
-
-		'<empty>': 'empty',
-		'<RECURSIVE': 'recursive',
-
-		'<FUNCTION[': 'func',
-	},
-	
-
-	// generic helpers...
-	//
-	// XXX need to keep the context constrained to one line...
-	context_size: 16,
-	error: function(msg, str, i, line){
-		var pre = i
-		var post = i
-		while(pre > 0 
-				&& i - pre <= this.context_size
-				&& str[pre] != '\n'){
-			pre-- }
-		while(post < str.length 
-				&& post - i <= this.context_size
-				&& str[post] != '\n'){
-			post++ }
-		throw new SyntaxError(`${ msg }\n`
-			+`    ${line}: ${ str.slice(pre, post) }\n`
-			+`    ${ ' '.repeat( i - pre + ((line + ': ').length) ) }^`) },
-
-	//
-	// 	._getItem(obj, path)
-	// 		-> [path, obj]
-	//
-	// NOTE: we are returning path here because we need to distinguish 
-	// 		incomplete paths that we can infer the container from and 
-	// 		complete paths, e.g:
-	// 			For
-	// 				m = [new Map([[1,2], [2,3]])]
-	// 			Both of the below will return the map and the correct path ([0]):
-	// 				eJSON._getItem(m, [0, 1])
-	// 				eJSON._getItem(m, [0])
-	// 			But we need to destinguish between the two cases when 
-	// 			writing to a map (see: .setItem(..))
-	_getItem: function(obj, path){
-		for(var i=0; i<path.length; i++){
-			var k = path[i]
-			// speacial case: incomplete map index...
-			if( obj instanceof Map 
-					&& i == path.length-1){
-				return [path.slice(0, -1), obj] }
-
-			obj = obj instanceof Set ?
-					[...obj][k]
-				: obj instanceof Map ?
-					[...obj][k][path[++i]]
-				: obj[k] }
-		return [path, obj] },
-	//
-	// 	.getItem(obj, path)
-	// 		-> obj
-	//
-	// NOTE: this is a POLS wrapper of ._getItem(..)
-	getItem: function(obj, path){
-		return this._getItem(...arguments)[1] },
-	// NOTE: this behaves in a similar way to normal key value assignment,
-	// 		i.e. replacing items if they exist, this is not a problem here 
-	// 		as in the general case we are assigning over a placeholder 
-	// 		object...
-	// NOTE: as a side-effect this maintains element oreder even in object
-	// 		with no direct concept of element order, like objects, sets and
-	// 		maps.
-	// NOTE: some operations envolve rewriting the container elements so 
-	// 		are not as fast, namely writing set elements and map keys.
-	setItem: function(obj, path, value){
-		var [p, parent] = this._getItem(obj, path.slice(0, -1))
-		var k = path.at(-1)
-		if(parent instanceof Set){
-			var elems = [...parent]
-			elems[k] = value
-			// we cant to keep the order...
-			parent.clear()
-			for(var e of elems){
-				parent.add(e) }
-		} else if(parent instanceof Map){
-			if(path.length-2 !== p.length){
-				throw new Error('.setItem(..): incomplete path.') }
-			var i = path.at(-2)
-			// replace the index...
-			if(k == 0){
-				var elems = [...parent]
-				elems[i][0] = value
-				parent.clear()
-				for(var e of elems){
-					parent.set(...e) }
-			// set the value...
-			} else {
-				parent.set([...parent][i][0], value) }
-		} else {
-			parent[k] = value }
-		return value },
-
-
-
-	WHITESPACE: ' \t\n',
-	skipWhitespace: function(str, i, line){
-		while(i < str.length 
-				&& this.WHITESPACE.includes(str[i])){
-			if(str[i] == '\n'){
-				line++ }
-			i++ }
-		return [i, line] },
-
-	//
-	//	.handler(match, str, i, line)
-	//		-> [value, i, line]
-	//
-	number: function(state, path, match, str, i, line){
-		debug.lex('number', str, i, line)
-		// special cases..,
-		if(match == 'Infinity'){
-			return [Infinity, i+'Infinity'.length, line] }
-		if(match == '-' 
-				&& str.slice(i, i+'-Infinity'.length) == '-Infinity'){
-			return [-Infinity, i+'-Infinity'.length, line] }
-		// numbers...
-		var j = i+1
-		while(j < str.length
-				&& (str[j] == '.'
-					|| (str[j] >= '0'
-						&& str[j] <= '9'))){
-			j++ }
-		return [ str.slice(i, j)*1, j, line ] },
-	// XXX TEST count \\n
-	string: function(state, path, match, str, i, line){
-		debug.lex('string', str, i, line)
-		var j = i+1
-		while(j < str.length 
-				&& str[j] != match){
-			// newlines...
-			if(str[j] == '\n'){
-				line++ }
-			// escaped newlines...
-			if(str[j] == '\\' 
-					&& j+1 < str.length 
-					&& str[j+1] == 'n'){
-				line++ }
-			// skip escaped quotes...
-			if(str[j] == '\\' 
-					&& j+1 < str.length 
-					&& str[j+1] == match){
-				j++ }
-			j++ }
-		if(j == str.length 
-				&& str[j-1] != match){
-			this.error('Unexpected end of input wile looking fot "'+ match +'".', str, i, line) }
-		return [ str.slice(i+1, j), j+1, line ] },
-	identifier: function(state, path, match, str, i, line){
-		debug.lex('identifier', str, i, line)
-		if(!/[a-zA-Z_]/.test(str[i])){
-			this.error('Not an identifier: "'+ str[i] +'"', str, i, line) }
-		var j = i+1
-		while(j < str.length 
-				&& /[a-zA-Z0-9_]/.test(str[j])){
-			j++ }
-		return [ str.slice(i, j), j, line ] },
-
-	//
-	//	handler(res, index, str, i, line)
-	//		-> [res, i, line]
-	//
-	sequence: function(state, path, str, i, line, end, handler, initial=[]){
-		var index = 0
-		while(i < str.length){
-			;[i, line] = this.skipWhitespace(str, i, line)
-
-			// done...
-			if(str.slice(i, i+end.length) == end){
-				return [initial, i+end.length, line] }
-
-			// empty...
-			if(str[i] == ','){
-				index++
-				i++
-				// XXX this feels hackish -- can this be deligated to the handler???
-				initial instanceof Array
-					&& initial.length++
-				continue }
-			if(str.slice(i, i+EMPTY.length) == EMPTY){
-				index++
-				i += EMPTY.length
-				if(str[i] == ','){
-					i++ }
-				// XXX this feels hackish -- can this be deligated to the handler???
-				initial instanceof Array
-					&& initial.length++
-				continue }
-
-			// end of input...
-			if(i >= str.length-1){
-				break }
-
-			// value...
-			;[initial, i, line] = handler.call(this, initial, index, str, i, line)
-
-			;[i, line] = this.skipWhitespace(str, i, line)
-			if(str[i] == ','){
-				i++ }
-			index++ }
-
-		// XXX better message -- show starting seq...
-		this.error('Unexpected end of input wile looking for "'+ end +'".', str, i, line) },
-
-	array: function(state, path, match, str, i, line){
-		debug.lex('array', str, i, line)
-		return this.sequence(
-			state, path, str, i+1, line, 
-			']',
-			function(res, index, str, i, line){
-				var obj
-				;[obj, i, line] = this.value(state, [...path, index], str, i, line)
-				res[index] = obj
-				return [res, i, line] }) },
-	object: function(state, path, match, str, i, line){
-		debug.lex('object', str, i, line)
-		return this.sequence(
-			state, path, str, i+1, line, 
-			'}',
-			function(res, index, str, i, line){
-				var obj, key
-				// key...
-				;[key, i, line] = '\'"`'.includes(str[i]) ?
-					this.string(state, path, str[i], str, i, line)
-					: this.identifier(state, path, str[i], str, i, line)
-
-				// ':'...
-				;[i, line] = this.skipWhitespace(str, i, line)
-				if(str[i] != ':'){
-					this.error('Expected ":", got "'+ str[i] +'".', str, i, line) }
-				i++
-				;[i, line] = this.skipWhitespace(str, i, line)
-
-				// value...
-				;[obj, i, line] = this.value(state, [...path, key], str, i, line)
-				res[key] = obj
-				return [res, i, line] }, 
-			{}) },
-
-	set: function(state, path, match, str, i, line){
-		debug.lex('set', str, i, line)
-		i += match.length
-		;[res, i, line] = this.sequence(
-			state, path, 
-			str, i+1, line, 
-			']',
-			function(res, index, str, i, line){
-				var obj
-				;[obj, i, line] = this.value(
-					state, 
-					[...path, index], 
-					str, i, line)
-				res.add(obj)
-				return [res, i, line] },
-			new Set()) 
-		if(str[i] != ')'){
-			this.error('Expected ")", got "'+ str[i] +'".', str, i, line) }
-		return [res, i+1, line] },
-	map: function(state, path, match, str, i, line){
-		debug.lex('map', str, i, line)
-		i += match.length
-		;[res, i, line] = this.sequence(
-			state, path, 
-			str, i+1, line, 
-			']',
-			function(res, index, str, i, line){
-				debug.lex('    map-content', str, i, line)
-				var obj
-				;[[key, value], i, line] = this.value(
-					state, 
-					[...path, index], 
-					str, i, line)
-				res.set(key, value)
-				return [res, i, line] },
-			new Map()) 
-		if(str[i] != ')'){
-			this.error('Expected ")", got "'+ str[i] +'".', str, i, line) }
-		return [res, i+1, line] },
-
-	// XXX should this be done inline or on a separate stage?
-	// 		for inline we need these:
-	// 			- all containers must be placed as soon as they are created
-	// 				"return" before the items are processed...
-	// 			- containers must be "filled" as the items are parsed
-	// 				like .array(..) and .object(..) but not like .map(..) and .set(..)
-	// 			- thread the root object...
-	// 		alternatively, for a two stage process we need to:
-	// 			- have a mechanism to write placeholders
-	// 			- remember their positions (paths)
-	// 			- build/get said path
-	// XXX another strategy would be to have an path-object map and 
-	// 		directly reference that -- this would eliminate the need for 
-	// 		stage two... (XXX TEST)
-	// 		...need to use serialized paths as keys...
-	recursive: function(state, path, match, str, i, line){
-		debug.lex('recursive', str, i, line)
-		return this.sequence(
-			state, path, str, i+match.length, line, 
-			'>',
-			function(res, index, str, i, line){
-				var obj
-				;[obj, i, line] = this.array(state, [...path, index], '[', str, i, line)
-				var rec = state.recursive ??= []
-				rec.push([path, obj])
-				return [{}, i, line] }) },
-
-	// NOTE: this uses eval(..) so care must be taken when enabling this...
-	func: function(state, path, match, str, i, line){
-		if(state.functions == null){
-			this.error('Deserializing functions disabled.', str, i, line) }
-
-		debug.lex('function', str, i, line)
-		var res
-		// length...
-		i += match.length
-		var [l, i, line] = this.number(state, path, str[i], str, i, line)
-		if(str[i] != ','){
-			this.error('Expected "," got "'+ str[i] +'"', str, i, line) }
-		i++
-
-		// func ref...
-		if(state.functions instanceof Array){
-			var [n, i, line] = this.number(state, path, str[i+1], str, i+1, line)
-			res = state.functions[n]
-		// func code...
-		} else {
-			var code = str.slice(i, i+l)
-			i += l
-			line += code.split(/\n/g).length
-			if(str.slice(i, i+2) == ']>'){
-				res = eval?.(code) } }
-
-		if(str.slice(i, i+2) != ']>'){
-			this.error('Expected "]>" got "'+ str.slice(i, i+2) +'"', str, i, line) }
-		return [res, i+2, line] },
-
-	value: function(state, path, str, i=0, line=0){
-
-		;[i, line] = this.skipWhitespace(str, i, line)
-
-		// get handler...	
-		var NONE = {}
-		var handler = NONE
-		var match = str[i]
-		if(match in this.chars){
-			handler = this.chars[match]
-		} else {
-			for(match in this.words){
-				if(match == str.slice(i, i+match.length)){
-					handler = this.words[match]
-					break } } }
-
-		// syntax error...
-		if(handler === NONE){
-			var context = 8
-			var pre = Math.max(i-context, 0)
-			var post = Math.min(i+context, str.length)
-			this.error(`Unexpected: ${ str.slice(i, i+10) }`, str, i, line) }
-
-		// value...
-		if(typeof(handler) != 'string'){
-			return [handler, i+match.length, line] }
-		// func...
-		return this[handler](state, path, match, str, i, line) },
-
-
-	parse: function(str, functions){
-
-		// stage 1: build the object...
-		var state = {functions}
-		var res = this.value(state, [], str)[0] 
-
-		// stage 2: link the recursive structures...
-		for(var [a, b] of state.recursive ?? []){
-			this.setItem(res, a, this.getItem(res, b)) }
-
-		return res },
-}
-
-
-var deserialize =
-module.deserialize =
-function(str, functions){
-	return eJSON.parse(str, functions) }
-
-
-
-//---------------------------------------------------------------------
-// utils...
-
-var deepCopy =
-module.deepCopy =
-function(obj){
-	return deserialize(
-		serialize(obj)) }
-
-
-var semiDeepCopy =
-module.semiDeepCopy =
-function(obj){
-	var funcs = []
-	return deserialize(
-		serialize(obj, null, 0, funcs), 
-		funcs) }
-
-
-
-/**********************************************************************
-* vim:set ts=4 sw=4 nowrap :                        */ return module })