std/path/kdl

Standard Library documentation

KDL Query Language selectors for KDL documents.

Back to Stdlib View Source

Module

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

NAME

std/path/kdl - KDL Query Language selectors for KDL documents.

SYNOPSIS

  from std/data/kdl import KDL;
  from std/path/kdl import KDLQuery;

  let doc := ( new KDL() ).decode( """
  package {
    name foo
    dependencies platform=windows {
      winapi "1.0.0"
    }
  }
  """ );

  let names := doc @@ new KDLQuery( path: "package >> name" );

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

KDLQuery implements the KDL Query Language described in tmp/QUERY-SPEC.md. It provides the same read-oriented public API as std/path/z and std/path/simple: get, select, query, first, exists, and expression. It also supports the assignment and reference methods from the path API for replacing selected KDLNode objects.

The values and props helper methods extract argument values and properties from the selected nodes.

If the query root is not already a KDLDocument or KDLNode, it is converted to a KDLDocument using std/data/kdl/json's json_to_kdl mapping before the query runs.

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

  from std/path/kdl import KDLQuery;
  KDLQuery.use();
  let dependencies := doc @@ "package >> dependencies";

EXPORTS

Classes

  • KDLQuery({ path: String })

    Constructs a KDL Query Language selector. Returns: KDLQuery.

    • KDLQuery.use()

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

    • query.expression()

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

    • query.get(raw), query.select(raw), query.query(raw)

      Parameters: raw is a KDL root or JSON-like value. Returns: Array. Evaluates the query and returns selected nodes.

    • query.first(raw, fallback?)

      Parameters: raw is the query root and fallback is optional. Returns: value. Returns the first selected node or fallback.

    • query.exists(raw)

      Parameters: raw is the query root. Returns: Boolean. Returns true when the query selects at least one node.

    • query.values(raw)

      Parameters: raw is the query root. Returns: Array. Returns selected node argument values.

    • query.props(raw)

      Parameters: raw is the query root. Returns: Array. Returns selected node property data.

    • query.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 node.

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

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

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

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

    • query.ref_first(target)

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

    • query.ref_all(target)

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

    • query.ref_maybe(target)

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

COPYRIGHT AND LICENCE

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