AtuinStand.Tree (atuin_stand v0.2.0)

View Source

A generic, ordered tree.

For a more detailed overview of the API, see AtuinStand.

Raising API

Every function that can return an error tuple has a raising version that raises an error instead of returning an error tuple, and returns the result instead of an ok tuple if successful.

Each error tuple maps to a specific exception:

Summary

Types

t()

Functions

branches(tree)

An alias for internal_nodes/1.

destroy(tree)

Shuts down the tree and frees up its resources.

export(tree)

Exports the tree as an Elixir map.

external_nodes(tree, order \\ :dfs)

Returns a list of all external nodes (nodes with no children) in the tree, including the root node (if applicable).

has_node(tree, id)

Checks if a node with the given ID exists in the tree.

import(data)

Imports a tree from an Elixir map generated with export/1, or exported from another atuin-stand implementation.

internal_nodes(tree, order \\ :dfs)

Returns a list of all internal nodes (nodes with children) in the tree, including the root node (if applicable).

leaves(tree)

An alias for external_nodes/1.

new()

Creates a new tree. Starts a new process linked to the current process to manage the tree's state.

node(tree, id)

Returns the node with the given ID.

node!(tree, id)

A raising version of node/2.

nodes(tree, order \\ :dfs)

Returns a list of all nodes in the tree.

root(tree)

Returns the root node of the tree.

size(tree)

Returns the number of nodes in the tree, including the root node.

Types

t()

@type t() :: %AtuinStand.Tree{pid: pid()}

Functions

branches(tree)

An alias for internal_nodes/1.

destroy(tree)

Shuts down the tree and frees up its resources.

Returns :ok if the tree was successfully stopped, or {:error, reason} if it was not. See Agent.stop/1 for more information.

Note that all nodes associated with the tree are invalid once the tree is destroyed.

export(tree)

@spec export(tree :: t()) :: map()

Exports the tree as an Elixir map.

To be compatible with other atuin-stand implementations, any user-defined data stored in the tree should use string keys.

external_nodes(tree, order \\ :dfs)

@spec external_nodes(tree :: t(), order :: :dfs | :bfs) :: [AtuinStand.Node.t()]

Returns a list of all external nodes (nodes with no children) in the tree, including the root node (if applicable).

Provide :dfs or :bfs as an optional argument to return the results in depth-first or breadth-first order, respectively. Defaults to :dfs.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> root = AtuinStand.Tree.root(tree)
iex> AtuinStand.Tree.external_nodes(tree)
[root]
iex> {:ok, node1} = AtuinStand.Node.create_child(root, "node1")
iex> {:ok, node2} = AtuinStand.Node.create_child(root, "node2")
iex> {:ok, node3} = AtuinStand.Node.create_child(root, "node3")
iex> {:ok, node4} = AtuinStand.Node.create_child(node2, "node4")
iex> AtuinStand.Tree.external_nodes(tree, :dfs)
[node1, node4, node3]
iex> AtuinStand.Tree.external_nodes(tree, :bfs)
[node1, node3, node4]

has_node(tree, id)

@spec has_node(tree :: t(), id :: atom() | String.t()) :: boolean()

Checks if a node with the given ID exists in the tree.

The only atom for which this function returns true is :root.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> AtuinStand.Tree.has_node(tree, "node1")
false
iex> root = AtuinStand.Tree.root(tree)
iex> AtuinStand.Node.create_child(root, "node1")
iex> AtuinStand.Tree.has_node(tree, "node1")
true

import(data)

@spec import(data :: map()) :: t() | {:error, term()}

Imports a tree from an Elixir map generated with export/1, or exported from another atuin-stand implementation.

Calls Agent.start_link/3 to create a new process to manage the tree's state, and returns the tree, or an error tuple if Agent.start_link/3 fails, similar to new/0.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> root = AtuinStand.Tree.root(tree)
iex> {:ok, child} = AtuinStand.Node.create_child(root, "child")
iex> AtuinStand.Node.set_data(child, %{"name" => "Child"})
iex> tree_data = AtuinStand.Tree.export(tree)
iex> AtuinStand.Tree.destroy(tree)
iex> tree = AtuinStand.Tree.import(tree_data)
iex> {:ok, child} = AtuinStand.Tree.node(tree, "child")
{:ok, %AtuinStand.Node{id: "child", tree: tree}}
iex> AtuinStand.Node.get_data(child)
{:ok, %{"name" => "Child"}}

internal_nodes(tree, order \\ :dfs)

@spec internal_nodes(tree :: t(), order :: :dfs | :bfs) :: [AtuinStand.Node.t()]

Returns a list of all internal nodes (nodes with children) in the tree, including the root node (if applicable).

Provide :dfs or :bfs as an optional argument to return the results in depth-first or breadth-first order, respectively. Defaults to :dfs.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> root = AtuinStand.Tree.root(tree)
iex> {:ok, node1} = AtuinStand.Node.create_child(root, "node1")
iex> {:ok, node2} = AtuinStand.Node.create_child(root, "node2")
iex> {:ok, node3} = AtuinStand.Node.create_child(node1, "node3")
iex> _ = AtuinStand.Node.create_child(node2, "node4")
iex> _ = AtuinStand.Node.create_child(node3, "node5")
iex> AtuinStand.Tree.internal_nodes(tree, :dfs)
[root, node1, node3, node2]
iex> AtuinStand.Tree.internal_nodes(tree, :bfs)
[root, node1, node2, node3]

leaves(tree)

An alias for external_nodes/1.

new()

@spec new() :: t() | {:error, term()}

Creates a new tree. Starts a new process linked to the current process to manage the tree's state.

Returns the tree, or an error tuple if Agent.start_link/3 fails.

node(tree, id)

@spec node(tree :: t(), id :: atom() | String.t()) ::
  {:ok, AtuinStand.Node.t()} | {:error, atom()}

Returns the node with the given ID.

Returns {:error, :not_found} if the node does not exist.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> root = AtuinStand.Tree.root(tree)
iex> AtuinStand.Node.create_child(root, "node1")
iex> {:ok, node1} = AtuinStand.Tree.node(tree, "node1")
iex> node1.id
"node1"

node!(tree, id)

@spec node!(tree :: t(), id :: atom() | String.t()) :: AtuinStand.Node.t()

A raising version of node/2.

nodes(tree, order \\ :dfs)

@spec nodes(tree :: t(), order :: :dfs | :bfs) :: [AtuinStand.Node.t()]

Returns a list of all nodes in the tree.

Provide :dfs or :bfs as an optional argument to return the results in depth-first or breadth-first order, respectively. Defaults to :dfs.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> root = AtuinStand.Tree.root(tree)
iex> {:ok, node1} = AtuinStand.Node.create_child(root, "node1")
iex> {:ok, node2} = AtuinStand.Node.create_child(root, "node2")
iex> {:ok, node3} = AtuinStand.Node.create_child(root, "node3")
iex> {:ok, node4} = AtuinStand.Node.create_child(node2, "node4")
iex> AtuinStand.Tree.nodes(tree, :dfs)
[root, node1, node2, node4, node3]
iex> AtuinStand.Tree.nodes(tree, :bfs)
[root, node1, node2, node3, node4]

root(tree)

@spec root(tree :: t()) :: AtuinStand.Node.t()

Returns the root node of the tree.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> root = AtuinStand.Tree.root(tree)
iex> root.id
:root

size(tree)

@spec size(tree :: t()) :: non_neg_integer()

Returns the number of nodes in the tree, including the root node.

Examples 

iex> tree = AtuinStand.Tree.new()
iex> AtuinStand.Tree.size(tree)
1
iex> root = AtuinStand.Tree.root(tree)
iex> AtuinStand.Node.create_child(root, "node1")
iex> AtuinStand.Tree.size(tree)
2
iex> AtuinStand.Node.create_child(root, "node2")
iex> AtuinStand.Tree.size(tree)
3