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".
component() = node_id() | 47 | 46 | 94
Component name in a path to a node.
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.
?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).?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.?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() = [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() = atom() | binary()
A node name.
path() = native_path() | unix_path()
Path to a node.
pattern() = native_pattern() | unix_pattern()
Path pattern which may match zero, one or more nodes.
pattern_component() = component() | khepri_condition:condition()
Path pattern component which may match zero, one or more nodes.
unix_path() = string() | binary()
Unix-like path to a node.
These Unix paths have the following syntax:
/
.:
character: :wood
.oak
./
, otherwise it is considered a
relative path.
and ..
represent ?THIS_NODE
and ?PARENT_NODE
respectivelyabc*def
is the same as #if_name_matches{regex = "^abc.*def$"}
*
is the same as ?STAR
or #if_name_matches{regex = any}
**
is the same as ?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.
Example:%% Unix path, equivalent of the first native path example.
UnixPath = "/:stock/:wood/oak".
unix_pattern() = string() | binary()
Unix-like path pattern to a node.
It accepts the following special characters:*
anywhere in a path component behaves like a khepri_condition:if_name_matches()
.**
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".
from_string/1 | Converts a Unix-like path to a native path. |
from_binary/1 | Converts a Unix-like path to a native path. |
to_string/1 | Converts a native path to a string. |
to_binary/1 | Converts 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 |
from_string(String) -> PathPattern
String = pattern()
PathPattern = native_pattern()
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(String) -> PathPattern
String = pattern()
PathPattern = native_pattern()
Converts a Unix-like path to a native path.
This is the same as callingfrom_string(String)
. Therefore, it accepts
Erlang strings or binaries and native paths.
See also: from_string/1.
to_string(NativePath) -> UnixPath
NativePath = native_path()
UnixPath = string()
Converts a native path to a string.
to_binary(NativePath) -> UnixPath
NativePath = native_path()
UnixPath = binary()
Converts a native path to a binary.
combine_with_conditions(PathPattern, Conditions) -> PathPattern
PathPattern = native_pattern()
Conditions = [khepri_condition:condition()]
targets_specific_node(PathPattern) -> Ret
PathPattern = native_pattern()
Ret = {true, Path} | false
Path = native_path()
is_valid(PathPattern) -> IsValid
PathPattern = native_pattern()
IsValid = true | {false, ComponentPattern}
ComponentPattern = pattern_component()
ensure_is_valid(PathPattern) -> ok | no_return()
PathPattern = native_pattern()
abspath(Path, BasePath) -> Path
Path = native_pattern()
BasePath = native_pattern()
realpath(Path) -> Path
Path = native_pattern()
pattern_includes_root_node(Path) -> any()
Generated by EDoc