std/path/simple

Standard Library documentation

Tiny JSONPath/XPath-like traversal helper.

Back to Stdlib View Source

Module

Name
std/path/simple
Area
Standard Library
Source
modules/std/path/simple.zzm

NAME

std/path/simple - Tiny JSONPath/XPath-like traversal helper.

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;
  }

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

SimplePath implements only a tiny subset of path traversal:

  • .something

    Dict/PairList lookup by key.

  • .*

    Dict/PairList wildcard that yields all values.

  • [1]

    Array lookup by numeric index.

  • [-1]

    Negative indexes count from the end of arrays.

  • [*]

    Array/Bag/Set wildcard that yields all items.

No other syntax is supported.

The public API intentionally mirrors key std/path/z methods: get, select, query, first, exists, expression, assign_first, assign_all, assign_maybe, ref_first, ref_all, and ref_maybe.

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

  from std/path/simple import SimplePath;
  SimplePath.use();

EXPORTS

Classes

  • SimplePath({ path: String })

    Constructs a simple path selector. Returns: SimplePath.

    • SimplePath.use()

      Parameters: none. Returns: null. Makes this path class the lexical implementation for @, @@, and @?.

    • path.expression()

      Parameters: none. Returns: String. Returns the original path expression.

    • path.get(value), path.select(value), path.query(value)

      Parameters: value is the query root. Returns: Array. Evaluates the path and returns selected values.

    • path.first(value, fallback)

      Parameters: value is the query root and fallback is returned when there is no match. Returns: value. Returns the first selected value.

    • path.exists(value)

      Parameters: value is the query root. Returns: Boolean. Returns true when the path selects at least one value.

    • path.assign_first(target, value, op := ":=", weak := false)

      Parameters: target is the query root, value is the assignment value, op is an assignment operator, and weak is accepted for path API compatibility. Returns: value. Updates the first selected location.

    • path.assign_all(target, value, op := ":=", weak := false)

      Parameters: same as assign_first. Returns: value. Updates every selected location.

    • path.assign_maybe(target, value, op := ":=", weak := false)

      Parameters: same as assign_first. Returns: Boolean. Updates the first selected location when one exists.

    • path.ref_first(target)

      Parameters: target is the query root. Returns: Function. Returns a reference-like getter/setter for the first selected location.

    • path.ref_all(target)

      Parameters: target is the query root. Returns: Array. Returns reference-like getter/setters for all selected locations.

    • path.ref_maybe(target)

      Parameters: target is the query root. Returns: Function or null. Returns a reference-like getter/setter for the first selected location when one exists.

COPYRIGHT AND LICENCE

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.