Module khepri_path

Khepri path API.

Description

Khepri path API.

A path is the type used by Khepri to reference nodes in the tree structure. A path describes how to reach a node from the root node.

A path, or native path, is a list of components. Components can be Erlang atoms and binaries. Example:

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

A path may contain conditions to tune how a node is matched or to match multiple nodes at once. This is called a path pattern. A path pattern may contain conditions in addition to regular components (Erlang atoms and binaries). See khepri_condition to learn more about conditions. Example:

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

To be user-friendly, string-based and binary-based Unix-like paths are accepted by most functions. The syntax of these Unix paths is described in the unix_path() type documentation. Example:

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

Data Types

component()

component() = node_id() | 47 | 46 | 94

Component name in a path to a node.

native_path()

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.

Special components are:
  1. ?ROOT_NODE to explicitly mark the root node. A path is absolute by default. Using ?ROOT_NODE is only useful when manipulating the root node itself (querying it or storing something in the root node).
  2. ?THIS_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_NODE to target the parent of a node, with the same benefits and use cases as ?THIS_NODE.

Example:

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

native_pattern()

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].

node_id()

node_id() = atom() | binary()

A node name.

path()

path() = native_path() | unix_path()

Path to a node.

pattern()

pattern() = native_pattern() | unix_pattern()

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

pattern_component()

pattern_component() = component() | khepri_condition:condition()

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

unix_path()

unix_path() = string() | binary()

Unix-like path to a node.

These Unix paths have the following syntax:

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.

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

unix_pattern()

unix_pattern() = string() | binary()

Unix-like path pattern to a node.

It accepts the following special characters:
  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.

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

Function Index

from_string/1Converts a Unix-like path to a native path.
from_binary/1Converts a Unix-like path to a native path.
to_string/1Converts a native path to a string.
to_binary/1Converts a native path to a binary.
combine_with_conditions/2
targets_specific_node/1
is_valid/1
ensure_is_valid/1
abspath/2
realpath/1
pattern_includes_root_node/1

Function Details

from_string/1

from_string(String) -> PathPattern

Converts a Unix-like path to a native path.

The Unix-like string can be either an Erlang string or an Erlang binary.

For convenience, a native path is also accepted and returned as-is.

from_binary/1

from_binary(String) -> PathPattern

Converts a Unix-like path to a native path.

This is the same as calling from_string(String). Therefore, it accepts Erlang strings or binaries and native paths.

See also: from_string/1.

to_string/1

to_string(NativePath) -> UnixPath

Converts a native path to a string.

to_binary/1

to_binary(NativePath) -> UnixPath

Converts a native path to a binary.

combine_with_conditions/2

combine_with_conditions(PathPattern, Conditions) -> PathPattern

targets_specific_node/1

targets_specific_node(PathPattern) -> Ret

is_valid/1

is_valid(PathPattern) -> IsValid

ensure_is_valid/1

ensure_is_valid(PathPattern) -> ok | no_return()

abspath/2

abspath(Path, BasePath) -> Path

realpath/1

realpath(Path) -> Path

pattern_includes_root_node/1

pattern_includes_root_node(Path) -> any()


Generated by EDoc