Sourceror.Zipper (Sourceror v0.11.0) View Source

Implements a Zipper for the Elixir AST based on Gérard Huet Functional pearl: the zipper paper 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 focus. It is represented by a 2-tuple where the first element is the focus and the second element is the metadata/context. When the focus is the topmost node, the metadata is nil, or :end after the end of a traversal.

Link to this section Summary

Types

path()

tree()

zipper()

Functions

append_child(arg, child)

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

branch?(list)

Returns true if the node is a branch.

children(list)

Returns a list of children of the node.

down(arg)

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

end?(arg)

Returns true if the zipper represents the end of a depth-first walk.

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

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

insert_child(arg, child)

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

insert_left(arg, 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(arg, 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(arg)

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. When reaching the end, returns a distinguished zipper detectable via end?/1. If it's already at the end, it stays there.

node(arg)

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(arg)

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

replace(arg, tree)

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

right(arg)

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.

traverse(zipper, acc, fun)

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

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.

up(arg)

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

update(arg, 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.

Link to this section Types

path()

Specs

path() :: %{l: [tree()], ptree: zipper(), r: [tree()]}

tree()

Specs

tree() :: Macro.t()

zipper()

Specs

zipper() :: {tree(), path() | nil | :end}

Link to this section Functions

append_child(arg, child)

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

branch?(list)

Specs

branch?(tree()) :: boolean()

Returns true if the node is a branch.

children(list)

Specs

children(tree()) :: [tree()]

Returns a list of children of the node.

down(arg)

Specs

down(zipper()) :: zipper() | nil

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

end?(arg)

Specs

end?(zipper()) :: boolean()

Returns true if the zipper represents the end of a depth-first walk.

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

Specs

find(zipper(), direction :: :prev | :next, predicate :: (tree() -> any())) ::
  zipper() | 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(arg, child)

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

insert_left(arg, child)

Specs

insert_left(zipper(), tree()) :: zipper()

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(arg, child)

Specs

insert_right(zipper(), tree()) :: zipper()

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(arg)

Specs

left(zipper()) :: zipper() | nil

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

leftmost(zipper)

Specs

leftmost(zipper()) :: zipper()

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

make_node(list, args)

Specs

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. When reaching the end, returns a distinguished zipper detectable via end?/1. If it's already at the end, it stays there.

node(arg)

Specs

node(zipper()) :: tree()

Returns the node at the zipper.

prev(zipper)

Specs

prev(zipper()) :: zipper()

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

remove(arg)

Specs

remove(zipper()) :: zipper()

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

replace(arg, tree)

Specs

replace(zipper(), tree()) :: zipper()

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

right(arg)

Specs

right(zipper()) :: zipper() | nil

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

rightmost(zipper)

Specs

rightmost(zipper()) :: zipper()

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

root(zipper)

Specs

root(zipper()) :: tree()

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

skip(zipper, direction \\ :next)

Specs

skip(zipper(), direction :: :next | :prev) :: zipper()

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.

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

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

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

top(zipper)

Specs

top(zipper()) :: zipper()

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

traverse(zipper, fun)

Specs

traverse(zipper(), (zipper() -> zipper())) :: zipper()

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

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

The function must return a zipper.

traverse(zipper, acc, fun)

Specs

traverse(zipper(), term(), (zipper(), term() -> {zipper(), term()})) ::
  {zipper(), term()}

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

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

traverse_while(zipper, fun)

Specs

traverse_while(
  zipper(),
  (zipper() -> {:cont, zipper()} | {:halt, zipper()} | {:skip, zipper()})
) :: zipper()

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}

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)

Specs

traverse_while(
  zipper(),
  term(),
  (zipper(), term() ->
     {:cont, zipper(), term()}
     | {:halt, zipper(), term()}
     | {:skip, zipper(), term()})
) :: {zipper(), term()}

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

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(arg)

Specs

up(zipper()) :: zipper() | nil

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

update(arg, fun)

Specs

update(zipper(), (tree() -> tree())) :: zipper()

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

zip(term)

Specs

zip(tree()) :: zipper()

Creates a zipper from a tree node.