-type native_path() :: [component()].

Native path to a node.

A native path is a list of atoms, binaries and special components.

It is called native because it requires no further processing (unlike unix_path()) and is the format used internally by the state machine.

1. ?KHEPRI_ROOT_NODE to explicitly mark the root node. A path is absolute by default. Using ?KHEPRI_ROOT_NODE is only useful when manipulating the root node itself (querying it or storing something in the root node).
2. ?THIS_KHEPRI_NODE to make a relative path (the default being an absolute path). This is mostly useful for khepri_condition:keep_while() to make it easy to put a condition on the node itself.
3. ?PARENT_KHEPRI_NODE to target the parent of a node, with the same benefits and use cases as ?THIS_KHEPRI_NODE.

Example:

  %% Native path.
  Path = [stock, wood, <<"oak">>].

-type native_pattern() :: [pattern_component()].

Path pattern which may match zero, one or more nodes.

A native pattern is a list of atoms, binaries, special components and conditions.

It is called native because it requires no further processing (unlike unix_pattern()) and is the format used internally by the state machine.

See native_path() for a description of special components.

Conditions are any condition defined by khepri_condition:condition().

Example:

  %% Path pattern with a condition on `wood'.
  PathPattern = [stock,
                 #if_all{conditions = [wood,
                                       #if_node_exists{exists = true}]},
                 oak].

-type unix_path() :: string() | binary().

Unix-like path to a node.

These Unix paths have the following syntax:

• Path components are separated by a forward slash, /.
• Atom-based node IDs are prefixed with a : character: :wood.
• Binary-based node IDs are written as-is: oak.
• Atom and binaries can be percent-encoded.
• An absolute path must start with /, otherwise it is considered a relative path
• . and .. represent ?THIS_KHEPRI_NODE and ?PARENT_KHEPRI_NODE respectively
• Simple glob patterns are accepted:
  • abc*def is the same as #if_name_matches{regex = "^abc.*def$"}
  • * is the same as ?KHEPRI_WILDCARD_STAR or #if_name_matches{regex = any}
  • ** is the same as ?KHEPRI_WILDCARD_STAR_STAR or if_path_matches{regex = any}

Warning: There is no special handling of Unicode in tree node names. To use Unicode, it is recommended to either use a native path or a binary-based Unix-like path. If using a string-based Unix-like path, the behavior is undefined and the call may crash. Matching against node names is also undefined behavior and may crash, regardless of the type of path being used. It will be improved in the future.

  %% Unix path, equivalent of the first native path example.
  UnixPath = "/:stock/:wood/oak".

-type unix_pattern() :: string() | binary().

Unix-like path pattern to a node.

1. * anywhere in a path component behaves like a khepri_condition:if_name_matches().
2. ** as a path component behaves like a khepri_condition:if_path_matches().

A Unix-like path pattern can't express all the conditions of a native path pattern currently.

Otherwise it works as a unix_path() and has the same syntax and limitations.

  %% Unix path pattern, matching multiple types of oak.
  UnixPathPattern = "/:stock/:wood/*oak".