zuzu-js 0.1.0

package/stdlib/modules/std/path/simple.zzm

@@ -0,0 +1,520 @@
+=encoding utf8
+
+=head1 NAME
+
+std/path/simple - Tiny JSONPath/XPath-like traversal helper.
+
+=head1 SYNOPSIS
+
+  from std/path/simple import SimplePath;
+  
+  let data := {
+    store: {
+      books: [
+        { author: "Nigel Rees" },
+        { author: "J. R. R. Tolkien" },
+      ],
+    },
+  };
+  
+  let p := new SimplePath( path: "store.books[*].author" );
+  for ( let name in p.query(data) ) {
+    say name;
+  }
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+C<SimplePath> implements only a tiny subset of path traversal:
+
+=over
+
+=item * C<.something>
+
+Dict/PairList lookup by key.
+
+=item * C<.*>
+
+Dict/PairList wildcard that yields all values.
+
+=item * C<[1]>
+
+Array lookup by numeric index.
+
+=item * C<[-1]>
+
+Negative indexes count from the end of arrays.
+
+=item * C<[*]>
+
+Array/Bag/Set wildcard that yields all items.
+
+=back
+
+No other syntax is supported.
+
+The public API intentionally mirrors key C<std/path/z> methods:
+C<get>, C<select>, C<query>, C<first>, C<exists>,
+C<expression>, C<assign_first>, C<assign_all>, C<assign_maybe>,
+C<ref_first>, C<ref_all>, and C<ref_maybe>.
+
+The path operators C<@>, C<@@>, and C<@?> can be set to use this module
+in a lexical scope:
+
+  from std/path/simple import SimplePath;
+  SimplePath.use();
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<< SimplePath({ path: String }) >>
+
+Constructs a simple path selector. Returns: C<SimplePath>.
+
+=over
+
+=item C<< SimplePath.use() >>
+
+Parameters: none. Returns: C<null>. Makes this path class the lexical
+implementation for C<@>, C<@@>, and C<@?>.
+
+=item C<< path.expression() >>
+
+Parameters: none. Returns: C<String>. Returns the original path
+expression.
+
+=item C<< path.get(value) >>, C<< path.select(value) >>, C<< path.query(value) >>
+
+Parameters: C<value> is the query root. Returns: C<Array>. Evaluates the
+path and returns selected values.
+
+=item C<< path.first(value, fallback) >>
+
+Parameters: C<value> is the query root and C<fallback> is returned when
+there is no match. Returns: value. Returns the first selected value.
+
+=item C<< path.exists(value) >>
+
+Parameters: C<value> is the query root. Returns: C<Boolean>. Returns
+true when the path selects at least one value.
+
+=item C<< path.assign_first(target, value, op := ":=", weak := false) >>
+
+Parameters: C<target> is the query root, C<value> is the assignment
+value, C<op> is an assignment operator, and C<weak> is accepted for path
+API compatibility. Returns: value. Updates the first selected location.
+
+=item C<< path.assign_all(target, value, op := ":=", weak := false) >>
+
+Parameters: same as C<assign_first>. Returns: value. Updates every
+selected location.
+
+=item C<< path.assign_maybe(target, value, op := ":=", weak := false) >>
+
+Parameters: same as C<assign_first>. Returns: C<Boolean>. Updates the
+first selected location when one exists.
+
+=item C<< path.ref_first(target) >>
+
+Parameters: C<target> is the query root. Returns: C<Function>. Returns a
+reference-like getter/setter for the first selected location.
+
+=item C<< path.ref_all(target) >>
+
+Parameters: C<target> is the query root. Returns: C<Array>. Returns
+reference-like getter/setters for all selected locations.
+
+=item C<< path.ref_maybe(target) >>
+
+Parameters: C<target> is the query root. Returns: C<Function> or
+C<null>. Returns a reference-like getter/setter for the first selected
+location when one exists.
+
+=back
+
+=back
+
+=cut
+
+from std/string import substr;
+
+
+class SimplePath {
+	let String path;
+	let Array _steps := [];
+
+	static method use () {
+		from std/internals import setupperprop;
+		setupperprop( 1, "paths", self );
+	}
+
+	method __build__ () {
+		_steps := self._parse(path);
+	}
+
+	method expression () {
+		return path;
+	}
+
+	method _parse ( String raw ) {
+		let text := raw;
+		let steps := [];
+		let i := 0;
+
+		while ( i < length text ) {
+			let ch := substr( text, i, 1 );
+			if ( ch ≡ "." ) {
+				i++;
+				die "SimplePath parse error: expected name or * after '.'"
+					if i >= length text;
+				let after_dot := substr( text, i, 1 );
+				if ( after_dot ≡ "*" ) {
+					steps.push( { kind: "dict_wildcard" } );
+					i++;
+					next;
+				}
+				let start := i;
+				while ( i < length text ) {
+					let c := substr( text, i, 1 );
+					last if c ≡ "." or c ≡ "[" or c ≡ "]";
+					i++;
+				}
+				let key := substr( text, start, i - start );
+				die "SimplePath parse error: empty key"
+					if key ≡ "";
+				steps.push( { kind: "key", value: key } );
+				next;
+			}
+
+			if ( ch ≡ "[" ) {
+				let close := i + 1;
+				while ( close < length text and substr( text, close, 1 ) ≢ "]" ) {
+					close++;
+				}
+				die "SimplePath parse error: missing closing ']'"
+					if close >= length text;
+				let inner := substr( text, i + 1, close - i - 1 );
+				if ( inner ≡ "*" ) {
+					steps.push( { kind: "list_wildcard" } );
+				}
+				else if ( inner ~ /^-?[0-9]+$/ ) {
+					steps.push( { kind: "index", value: int(inner) } );
+				}
+				else {
+					die `SimplePath parse error: unsupported bracket token '[${inner}]'`;
+				}
+				i := close + 1;
+				next;
+			}
+
+			let start := i;
+			while ( i < length text ) {
+				let c := substr( text, i, 1 );
+				last if c ≡ "." or c ≡ "[" or c ≡ "]";
+				i++;
+			}
+			let key := substr( text, start, i - start );
+			die `SimplePath parse error: unexpected token '${ch}'`
+				if key ≡ "";
+			steps.push( { kind: "key", value: key } );
+		}
+
+		return steps;
+	}
+
+	method _node ( value, parent, key ) {
+		return {
+			value: value,
+			parent: parent,
+			key: key,
+		};
+	}
+
+	method _evaluate_nodes ( value ) {
+		let current := [ self._node( value, null, null ) ];
+
+		for ( let step in _steps ) {
+			let next_nodes := [];
+
+			for ( let node in current ) {
+				let v := node{value};
+
+				if ( step{kind} ≡ "key" ) {
+					if ( v instanceof Dict and v.exists( step{value} ) ) {
+						next_nodes.push( self._node( v.get( step{value} ), node, step{value} ) );
+					}
+					else if ( v instanceof PairList ) {
+						for ( let item in v.get_all( step{value} ) ) {
+							next_nodes.push( self._node( item, node, step{value} ) );
+						}
+					}
+					next;
+				}
+
+				if ( step{kind} ≡ "dict_wildcard" ) {
+					if ( v instanceof Dict ) {
+						for ( let k in v.keys() ) {
+							next_nodes.push( self._node( v.get(k), node, k ) );
+						}
+					}
+					else if ( v instanceof PairList ) {
+						for ( let pair in v.to_Array() ) {
+							next_nodes.push( self._node( pair.value, node, pair.key ) );
+						}
+					}
+					next;
+				}
+
+				if ( step{kind} ≡ "index" ) {
+					if ( v instanceof Array ) {
+						let idx := step{value};
+						if ( idx < 0 ) {
+							idx := v.length() + idx;
+						}
+						if ( idx >= 0 and idx < v.length() ) {
+							next_nodes.push( self._node( v[idx], node, idx ) );
+						}
+					}
+					next;
+				}
+
+				if ( step{kind} ≡ "list_wildcard" ) {
+					if ( v instanceof Array ) {
+						let i := 0;
+						while ( i < v.length() ) {
+							next_nodes.push( self._node( v[i], node, i ) );
+							i++;
+						}
+					}
+					else if ( v instanceof Bag or v instanceof Set ) {
+						for ( let item in v.to_Array() ) {
+							next_nodes.push( self._node( item, node, "*" ) );
+						}
+					}
+					next;
+				}
+			}
+
+			current := next_nodes;
+		}
+
+		return current;
+	}
+
+	method _evaluate ( value ) {
+		return self._evaluate_nodes(value).map( fn n -> n{value} );
+	}
+
+	method get ( value ) {
+		return self._evaluate(value);
+	}
+
+	method select ( value ) {
+		return self._evaluate(value);
+	}
+
+	method query ( value ) {
+		return self._evaluate(value);
+	}
+
+	method first ( value, fallback ) {
+		let out := self._evaluate(value);
+		return out.length() = 0 ? fallback : out[0];
+	}
+
+	method exists ( value ) {
+		return self._evaluate(value).length() > 0;
+	}
+
+	method _assign_node ( Dict node, value ) {
+		let parent := node{parent};
+		die "SimplePath assignment target has no parent node"
+			if parent ≡ null;
+
+		let container := parent{value};
+		let key := node{key};
+
+		if ( container instanceof Array ) {
+			die "SimplePath assignment expects numeric array index"
+				if not( key instanceof Number );
+			container[key] := value;
+			return value;
+		}
+
+		if ( container instanceof Dict ) {
+			die "SimplePath assignment expects string dict key"
+				if not( key instanceof String );
+			container{(key)} := value;
+			return value;
+		}
+
+		if ( container instanceof PairList ) {
+			die "SimplePath assignment expects string pairlist key"
+				if not( key instanceof String );
+			container.set( key, value );
+			return value;
+		}
+
+		die `SimplePath assignment target container '${typeof container}' is not assignable`;
+	}
+
+	method _ref_for_node ( Dict node ) {
+		let parent := node{parent};
+		die "SimplePath assignment target has no parent node"
+			if parent ≡ null;
+
+		let container := parent{value};
+		let key := node{key};
+
+		if ( container instanceof Array ) {
+			die "SimplePath assignment expects numeric array index"
+				if not( key instanceof Number );
+			return \ container[key];
+		}
+
+		if ( container instanceof Dict ) {
+			die "SimplePath assignment expects string dict key"
+				if not( key instanceof String );
+			return \ container{(key)};
+		}
+
+		if ( container instanceof PairList ) {
+			die "SimplePath assignment expects string pairlist key"
+				if not( key instanceof String );
+			return \ container{(key)};
+		}
+
+		die `SimplePath assignment target container '${typeof container}' is not assignable`;
+	}
+
+	method _apply_assignment_ref ( ref, value, op := ":=", weak := false ) {
+		die "SimplePath weak assignment is not supported"
+			if weak;
+
+		if ( op ≡ ":=" ) {
+			return ref(value);
+		}
+
+		let current := ref();
+
+		if ( op ≡ "+=" ) {
+			current += value;
+		}
+		else if ( op ≡ "-=" ) {
+			current -= value;
+		}
+		else if ( op ≡ "*=" or op ≡ "×=" ) {
+			current *= value;
+		}
+		else if ( op ≡ "/=" or op ≡ "÷=" ) {
+			current /= value;
+		}
+		else if ( op ≡ "**=" ) {
+			current **= value;
+		}
+		else if ( op ≡ "_=" ) {
+			current _= value;
+		}
+		else if ( op ≡ "?:=" ) {
+			current ?:= value;
+		}
+		else if ( op ≡ "~=" ) {
+			current ~= value[0] -> value[1](m);
+		}
+		else {
+			die `Unsupported path assignment operator '${op}'`;
+		}
+
+		ref(current);
+		return current;
+	}
+
+	method _assign_all_result ( value, op, last_result ) {
+		return op ≡ "~=" ? last_result : value;
+	}
+
+	method assign_first ( target, value, op := ":=", weak := false ) {
+		let nodes := self._evaluate_nodes(target);
+		die "SimplePath assignment found no matches"
+			if nodes.length() ≡ 0;
+		return self._apply_assignment_ref(
+			self._ref_for_node( nodes[0] ),
+			value,
+			op,
+			weak,
+		);
+	}
+
+	method assign_all ( target, value, op := ":=", weak := false ) {
+		let nodes := self._evaluate_nodes(target);
+		if ( nodes.length() ≡ 0 ) {
+			return self._assign_all_result( value, op, value );
+		}
+
+		let i := 0;
+		let last_result := value;
+		while ( i < nodes.length() ) {
+			last_result := self._apply_assignment_ref(
+				self._ref_for_node( nodes[i] ),
+				value,
+				op,
+				weak,
+			);
+			i++;
+		}
+
+		return self._assign_all_result( value, op, last_result );
+	}
+
+	method assign_maybe ( target, value, op := ":=", weak := false ) {
+		let nodes := self._evaluate_nodes(target);
+		if ( nodes.length() ≡ 0 ) {
+			return false;
+		}
+
+		self._apply_assignment_ref(
+			self._ref_for_node( nodes[0] ),
+			value,
+			op,
+			weak,
+		);
+		return true;
+	}
+
+	method ref_first ( target ) {
+		let nodes := self._evaluate_nodes(target);
+		die "SimplePath assignment found no matches"
+			if nodes.length() ≡ 0;
+		return self._ref_for_node( nodes[0] );
+	}
+
+	method ref_all ( target ) {
+		let nodes := self._evaluate_nodes(target);
+		let out := [];
+		for ( let node in nodes ) {
+			out.push( self._ref_for_node(node) );
+		}
+		return out;
+	}
+
+	method ref_maybe ( target ) {
+		let nodes := self._evaluate_nodes(target);
+		return nodes.length() ≡ 0 ? null : self._ref_for_node( nodes[0] );
+	}
+}
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/path/simple >> is copyright Toby Inkster.
+
+It is free software; you may redistribute it and/or modify it under
+the terms of either the Artistic License 1.0 or the GNU General Public
+License version 2.
+
+=cut

package/stdlib/modules/std/path/z/context.zzm

@@ -0,0 +1,147 @@
+=encoding utf8
+
+=head1 NAME
+
+std/path/z/context - Evaluation context used by std/path/z.
+
+=head1 IMPLEMENTATION SUPPORT
+
+This module is supported by all implementations of ZuzuScript.
+
+=head1 DESCRIPTION
+
+This module provides the pure-Zuzu evaluation context used by ZPath.
+
+=head1 EXPORTS
+
+=head2 Classes
+
+=over
+
+=item C<< Ctx({ root, nodeset?, parentset?, meta? }) >>
+
+Constructs a ZPath evaluation context. Returns: C<Ctx>. Wraps C<root>
+as a C<std/path/z/node> C<Node> and stores the active node sets.
+
+=over
+
+=item C<< ctx.with_nodeset(ns, ps) >>
+
+Parameters: C<ns> is the next node set and C<ps> is the parent set.
+Returns: C<Ctx>. Returns a copy of the context with different node
+sets.
+
+=item C<< ctx.nested(extras?) >>
+
+Parameters: C<extras> is optional metadata. Returns: C<Ctx>. Returns a
+nested context with incremented metadata level.
+
+=item C<< ctx.root() >>
+
+Parameters: none. Returns: C<Node>. Returns the root node.
+
+=item C<< ctx.nodeset() >>
+
+Parameters: none. Returns: C<Array>. Returns the current node set.
+
+=item C<< ctx.parentset() >>
+
+Parameters: none. Returns: C<Array> or C<null>. Returns the parent node
+set.
+
+=item C<< ctx.meta() >>
+
+Parameters: none. Returns: C<Dict>. Returns context metadata.
+
+=back
+
+=back
+
+=head1 COPYRIGHT AND LICENCE
+
+B<< std/path/z/context >> is copyright Toby Inkster.
+
+It is free software; you may redistribute it and/or modify it under
+the terms of either the Artistic License 1.0 or the GNU General Public
+License version 2.
+
+=cut
+
+from std/path/z/node import Node;
+
+class Ctx {
+	let root := null;
+	let nodeset := null;
+	let parentset := null;
+	let meta := null;
+
+	method __build__ () {
+		if ( not ( root instanceof Node ) ) {
+			let root_obj := root;
+			let node_type := null;
+
+			try {
+				node_type := int( "" _ root_obj.nodeType() );
+			}
+			catch {
+			}
+
+			let xml_document := node_type = 9;
+			if ( not xml_document and root_obj can documentElement ) {
+				try {
+					root_obj.documentElement();
+					xml_document := true;
+				}
+				catch {
+				}
+			}
+
+			if ( xml_document ) {
+				try {
+					let de := root_obj.documentElement();
+					root_obj := de if de ≢ null;
+				}
+				catch {
+				}
+			}
+
+			root := Node.wrap( root_obj );
+		}
+
+		nodeset ?:= [ root ];
+		meta ?:= { level: 0 };
+	}
+
+	method with_nodeset ( ns, ps ) {
+		return new Ctx(
+			root: root,
+			nodeset: ns,
+			parentset: ps,
+			meta: meta,
+		);
+	}
+
+	method nested ( extras? ) {
+		let extra_meta := extras ?: {};
+
+		let next_meta := {
+			level: meta.get( "level", 0 ) + 1,
+		};
+
+		for ( let pair in extra_meta.enumerate ) {
+			next_meta.add( pair );
+		}
+
+		return new Ctx(
+			root: root,
+			nodeset: nodeset,
+			parentset: parentset,
+			meta: next_meta,
+		);
+	}
+
+	method root () { return root; }
+	method nodeset () { return nodeset; }
+	method parentset () { return parentset; }
+	method meta () { return meta; }
+}