=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