View Source Sourceror.Zipper (Sourceror v1.0.3)

Tree-like data structure that provides enhanced navigation and modification of an Elixir AST.

This implementation is based on Gérard Huet Functional pearl: the zipper and Clojure's clojure.zip API.

A zipper is a data structure that represents a location in a tree from the perspective of the current node, also called the focus.

It is represented by a struct containing a :node and :path, which is a private field used to track the position of the :node with regards to the entire tree. The :path is an implementation detail that should be considered private.

For more information and examples, see the following guides:

Zippers (an introduction)
Expand multi-alias syntax (an example)

Summary

Types

path()

t()

tree()

Functions

append_child(zipper, child)

Inserts the item as the rightmost child of the node at this zipper, without moving.

branch?(list)

children(list)

Returns a list of children of the node.

down(zipper)

Returns the zipper of the leftmost child of the node at this zipper, or nil if no there's no children.

find(zipper, direction \\ :next, predicate)

Returns a zipper to the node that satisfies the predicate function, or nil if none is found.

insert_child(zipper, child)

Inserts the item as the leftmost child of the node at this zipper, without moving.

insert_left(zipper, child)

Inserts the item as the left sibling of the node at this zipper, without moving. Raises an ArgumentError when attempting to insert a sibling at the top level.

insert_right(zipper, child)

Inserts the item as the right sibling of the node at this zipper, without moving. Raises an ArgumentError when attempting to insert a sibling at the top level.

left(arg1)

Returns the zipper of the left sibling of the node at this zipper, or nil.

leftmost(zipper)

Returns the leftmost sibling of the node at this zipper, or itself.

make_node(list, args)

Returns a new branch node, given an existing node and new children.

next(zipper)

Returns the following zipper in depth-first pre-order.

node(zipper)

Returns the node at the zipper.

prev(zipper)

Returns the previous zipper in depth-first pre-order. If it's already at the end, it returns nil.

remove(zipper)

Removes the node at the zipper, returning the zipper that would have preceded it in a depth-first walk.

replace(zipper, tree)

Replaces the current node in the zipper with a new node.

right(arg1)

Returns the zipper of the right sibling of the node at this zipper, or nil.

rightmost(zipper)

Returns the rightmost sibling of the node at this zipper, or itself.

root(zipper)

Walks the zipper all the way up and returns the root node.

skip(zipper, direction \\ :next)

Returns the zipper of the right sibling of the node at this zipper, or the next zipper when no right sibling is available.

top(zipper)

Walks the zipper all the way up and returns the top zipper.

traverse(zipper, fun)

Traverses the tree in depth-first pre-order calling the given function for each node. When the traversal is finished, the zipper will be back where it began.

traverse(zipper, acc, fun)

Traverses the tree in depth-first pre-order calling the given function for each node with an accumulator. When the traversal is finished, the zipper will be back where it began.

traverse_while(zipper, fun)

Traverses the tree in depth-first pre-order calling the given function for each node.

traverse_while(zipper, acc, fun)

Traverses the tree in depth-first pre-order calling the given function for each node with an accumulator. When the traversal is finished, the zipper will be back where it began.

up(zipper)

Returns the zipper of the parent of the node at this zipper, or nil if at the top.

update(zipper, fun)

Replaces the current node in the zipper with the result of applying fun to the node.

zip(term)

Creates a zipper from a tree node.

Types

path()

@opaque path()

t()

@type t() :: %Sourceror.Zipper{node: tree(), path: path() | nil}

tree()

@type tree() :: Macro.t()

Functions

append_child(zipper, child)

Inserts the item as the rightmost child of the node at this zipper, without moving.

branch?(list)

@spec branch?(tree()) :: boolean()

children(list)

@spec children(tree()) :: [tree()]

Returns a list of children of the node.

down(zipper)

@spec down(t()) :: t() | nil

Returns the zipper of the leftmost child of the node at this zipper, or nil if no there's no children.

find(zipper, direction \\ :next, predicate)

@spec find(t(), direction :: :prev | :next, predicate :: (tree() -> any())) ::
  t() | nil

Returns a zipper to the node that satisfies the predicate function, or nil if none is found.

The optional second parameters specifies the direction, defaults to :next.

insert_child(zipper, child)

Inserts the item as the leftmost child of the node at this zipper, without moving.

insert_left(zipper, child)

@spec insert_left(t(), tree()) :: t()

Inserts the item as the left sibling of the node at this zipper, without moving. Raises an ArgumentError when attempting to insert a sibling at the top level.

insert_right(zipper, child)

@spec insert_right(t(), tree()) :: t()

Inserts the item as the right sibling of the node at this zipper, without moving. Raises an ArgumentError when attempting to insert a sibling at the top level.

left(arg1)

@spec left(t()) :: t() | nil

Returns the zipper of the left sibling of the node at this zipper, or nil.

leftmost(zipper)

@spec leftmost(t()) :: t()

Returns the leftmost sibling of the node at this zipper, or itself.

make_node(list, args)

@spec make_node(tree(), [tree()]) :: tree()

Returns a new branch node, given an existing node and new children.

next(zipper)

Returns the following zipper in depth-first pre-order.

node(zipper)

@spec node(t()) :: tree()

Returns the node at the zipper.

prev(zipper)

@spec prev(t()) :: t()

Returns the previous zipper in depth-first pre-order. If it's already at the end, it returns nil.

remove(zipper)

@spec remove(t()) :: t()

Removes the node at the zipper, returning the zipper that would have preceded it in a depth-first walk.

replace(zipper, tree)

@spec replace(t(), tree()) :: t()

Replaces the current node in the zipper with a new node.

right(arg1)

@spec right(t()) :: t() | nil

Returns the zipper of the right sibling of the node at this zipper, or nil.

rightmost(zipper)

@spec rightmost(t()) :: t()

Returns the rightmost sibling of the node at this zipper, or itself.

root(zipper)

@spec root(t()) :: tree()

Walks the zipper all the way up and returns the root node.

skip(zipper, direction \\ :next)

@spec skip(t(), direction :: :next | :prev) :: t() | nil

Returns the zipper of the right sibling of the node at this zipper, or the next zipper when no right sibling is available.

This allows to skip subtrees while traversing the siblings of a node.

The optional second parameters specifies the direction, defaults to :next.

If no right/left sibling is available, this function returns the same value as next/1/prev/1.

The function skip/1 behaves like the :skip in traverse_while/2 and traverse_while/3.

top(zipper)

@spec top(t()) :: t()

Walks the zipper all the way up and returns the top zipper.

traverse(zipper, fun)

@spec traverse(t(), (t() -> t())) :: t()

Traverses the tree in depth-first pre-order calling the given function for each node. When the traversal is finished, the zipper will be back where it began.

If the zipper is not at the top, just the subtree will be traversed.

The function must return a zipper.

traverse(zipper, acc, fun)

@spec traverse(t(), term(), (t(), term() -> {t(), term()})) :: {t(), term()}

Traverses the tree in depth-first pre-order calling the given function for each node with an accumulator. When the traversal is finished, the zipper will be back where it began.

If the zipper is not at the top, just the subtree will be traversed.

traverse_while(zipper, fun)

@spec traverse_while(t(), (t() -> {:cont, t()} | {:halt, t()} | {:skip, t()})) :: t()

Traverses the tree in depth-first pre-order calling the given function for each node.

The traversing will continue if the function returns {:cont, zipper}, skipped for {:skip, zipper} and halted for {:halt, zipper}. When the traversal is finished, the zipper will be back where it began.

If the zipper is not at the top, just the subtree will be traversed.

The function must return a zipper.

traverse_while(zipper, acc, fun)

@spec traverse_while(
  t(),
  term(),
  (t(), term() ->
     {:cont, t(), term()} | {:halt, t(), term()} | {:skip, t(), term()})
) :: {t(), term()}

Traverses the tree in depth-first pre-order calling the given function for each node with an accumulator. When the traversal is finished, the zipper will be back where it began.

The traversing will continue if the function returns {:cont, zipper, acc}, skipped for {:skip, zipper, acc} and halted for {:halt, zipper, acc}

If the zipper is not at the top, just the subtree will be traversed.

up(zipper)

@spec up(t()) :: t() | nil

Returns the zipper of the parent of the node at this zipper, or nil if at the top.

update(zipper, fun)

@spec update(t(), (tree() -> tree())) :: t()

Replaces the current node in the zipper with the result of applying fun to the node.

zip(term)

@spec zip(tree()) :: t()

Creates a zipper from a tree node.