std/path/z

NAME

std/path/z - Pure Zuzu implementation of ZPath selectors.

SYNOPSIS

  from std/path/z import ZPath;
  from std/time import Time;

  let data := {
    users: [
      { name: "Ada", age: 32, updated: new Time() },
      { name: "Bob", age: 27 },
    ],
  };

  let names := query( data, "/users/*/name" );
  let zp := new ZPath( path: "/users/#0/name" );
  say( zp.first( data, "n/a" ) );
  say( exists( data, "/users/#9/name" ) );
  say( first( data, "/users/#0/updated/@year" ) );
  say( zp.assign_first( data, "Adele" ) );

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

Native (pure-Zuzu) path traversal for structured values.

EXPORTS

Classes

ZPath({ path: String, ast? })
Constructs a compiled ZPath selector. Returns: ZPath.
- ZPath.use()
  Parameters: none. Returns: null. Makes this path class the lexical implementation for @, @@, and @?.
- path.get_evaluator()
  Parameters: none. Returns: Evaluator. Returns the evaluator used for this path.
- path.evaluate(raw, meta := {})
  Parameters: raw is the query root and meta is optional evaluation metadata. Returns: Array. Evaluates the path and returns selected nodes.
- path.get(raw), path.select(raw), path.query(raw)
  Parameters: raw is the query root. Returns: Array. Evaluates the path and returns selected primitive values.
- path.first(raw, fallback?)
  Parameters: raw is the query root and fallback is optional. Returns: value. Returns the first selected value or fallback/null.
- path.exists(raw)
  Parameters: raw is the query root. Returns: Boolean. Returns true when the path selects at least one value.
- path.assign_first(raw, value, op := ":=", weak := false)
  Parameters: raw is the query root, value is the assignment value, op is an assignment operator, and weak requests weak assignment. Returns: value. Updates the first selected node or throws if none match.
- path.assign_all(raw, value, op := ":=", weak := false)
  Parameters: same as assign_first. Returns: value. Updates every selected node.
- path.assign_maybe(raw, value, op := ":=", weak := false)
  Parameters: same as assign_first. Returns: Boolean. Updates the first selected node when one exists.
- path.ref_first(raw)
  Parameters: raw is the query root. Returns: Function. Returns a reference-like getter/setter for the first selected node.
- path.ref_all(raw)
  Parameters: raw is the query root. Returns: Array. Returns reference-like getter/setters for all selected nodes.
- path.ref_maybe(raw)
  Parameters: raw is the query root. Returns: Function or null. Returns a reference-like getter/setter for the first selected node when one exists.

USE WITH PATH OPERATORS

The path operators @, @@, and @? can be set to use this module in a lexical scope.

  from std/path/z import ZPath;

  function find_usernames (data) {
    ZPath.use();
    return data @@ "/users/*/name";
  }

However, for repeatedly used paths it may be more efficient to compile the path once and use many times:

  let _usernames_zpath;
  function find_usernames (data) {
    from std/path/z import ZPath;
    _usernames_zpath ?:= new ZPath( path: "/users/*/name" );
    return data @@ _usernames_zpath;
  }

SUPPORTED TYPES

Null, Boolean, Number, String, BinaryString, Regexp
Treated as terminal nodes. These objects cannot have child objects.
Array
Array items can be indexed by number.
Bag, Set
Items cannot be indexed by number, but can be returned by "*".
Dict
Values are named by their key.
PairList
Pairs can be indexed by number, named by their key, or use a combination of both.
```
  {{ foo: 11, bar: -1, foo: 22, foo: 33 }}
```
/#2 (0-based index) will retrieve foo: 22. /foo will retrieve foo: 11, foo: 22, and foo: 33. /foo#2 (0-based index on just values with key "foo") will retrieve foo: 33.

Note that rather than just retrieving the value, a Pair object is retrieved. The selected Pair exposes @key and @value attributes. Path assignment to a selected Pair, or to its @value attribute, replaces that pair entry's value while preserving pair order and duplicate keys.

Pair

Pair objects do not have child objects but do have @key and @value attributes.

  let pairlist := {{ foo: 11, bar: -1, foo: 22, foo: 33 }};
  say( first( pairlist, "/#2/@key" ) );     // "foo"
  say( first( pairlist, "/#2/@value" ) );   // 22

Time
Time is treated as a terminal node with attributes @year, @month, @day, @hour, @min, and @sec.

See std/time.
Path
Paths representing files are treated as terminal nodes with attributes corresponding to the values from the stat system call: @dev, @ino, @mode, @nlink, @uid, @gid, @rdev, @size, @atime, @mtime, @ctime, @blksize, and @blocks.

See std/io.

XMLDocument, XMLNode, etc.

Are treated roughly how the ZPath specification suggests.

  /html/body/table/tbody/tr     // all rows in the tbody
  /html/body/table/tbody/tr#0   // the first row in the tbody
  /html/body/table/tbody/#0     // the child element in the tbody
  /html/body/table[@id]         // all tables that have an id attribute

See std/data/xml.

COPYRIGHT AND LICENCE

std/path/z 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.

Module