# Class `std.tree`

Tree container prototype.

Note that Functions listed below are only available from the Tree prototype returned by requiring this module, because Container objects cannot have object methods.

## Prototype Chain

    table
     `-> Object
          `-> Container
               `-> Tree

## Objects

std.tree.Tree | Tree prototype object.

## Functions

std.tree.clone (t, nometa) | Make a deep copy of a tree, including any metatables.
std.tree.ileaves (tr) | Tree iterator which returns just numbered leaves, in order.
std.tree.inodes (tr) | Tree iterator over numbered nodes, in order.
std.tree.leaves (t) | Tree iterator which returns just leaves.
std.tree.merge (t, u) | Destructively deep-merge one tree into another.
std.tree.nodes (tr) | Tree iterator over all nodes.

## Metamethods

std.tree.__index (tr, i) | Deep retrieval.
std.tree.__newindex (tr, i[, v]) | Deep insertion.

## Objects

std.tree.Tree
  Tree prototype object.

  ### Fields:

  - _type string object name (default "Tree")

  ### See also:

  - std.container
  - std.object.__call

  ### Usage:

       local std = require "std"
       local Tree = std.tree {}
       local tr = Tree {}
       tr[{"branch1", 1}] = "leaf1"
       tr[{"branch1", 2}] = "leaf2"
       tr[{"branch2", 1}] = "leaf3"
       print (tr[{"branch1"}])      --> Tree {leaf1, leaf2}
       print (tr[{"branch1", 2}])   --> leaf2
       print (tr[{"branch1", 3}])   --> nil
       --> leaf1	leaf2	leaf3
       for leaf in std.tree.leaves (tr) do
         io.write (leaf .. "\t")
       end

## Functions

Methods

std.tree.clone (t, nometa)
  Make a deep copy of a tree, including any metatables.

  ### Parameters:

  - t table tree or tree-like table
  - nometa boolean if non-`nil` don't copy metatables

  ### Returns:

  Tree or table a deep copy of tr

  ### See also:

  std.table.clone

  ### Usage:

       tr = {"one", {two=2}, {{"three"}, four=4}}
       copy = clone (tr)
       copy[2].two=5
       assert (tr[2].two == 2)

std.tree.ileaves (tr)
  Tree iterator which returns just numbered leaves, in order.

  ### Parameters:

  - tr Tree or table tree or tree-like table

  ### Returns:

  1. function iterator function
  2. Tree or table the tree tr

  ### See also:

  - inodes
  - leaves

  ### Usage:

       --> t = {"one", "three", "five"}
       for leaf in ileaves {"one", {two=2}, {{"three"}, four=4}}, foo="bar", "five"}
       do
         t[#t + 1] = leaf
       end

std.tree.inodes (tr)
  Tree iterator over numbered nodes, in order.

  The iterator function behaves like nodes, but only traverses the array part of the nodes of tr, ignoring any others.

  ### Parameters:

  - tr Tree or table tree or tree-like table to iterate over

  ### Returns:

  1. function iterator function
  2. tree or table the tree, tr

  ### See also:

  nodes
std.tree.leaves (t)
  Tree iterator which returns just leaves.

  ### Parameters:

  - t table tree or tree-like table

  ### Returns:

  1. function iterator function
  2. table t

  ### See also:

  - ileaves
  - nodes

  ### Usage:

       for leaf in leaves {"one", {two=2}, {{"three"}, four=4}}, foo="bar", "five"}
       do
         t[#t + 1] = leaf
       end
       --> t = {2, 4, "five", "foo", "one", "three"}
       table.sort (t, lambda "=tostring(_1) < tostring(_2)")

std.tree.merge (t, u)
  Destructively deep-merge one tree into another.

  ### Parameters:

  - t table destination tree
  - u table table with nodes to merge

  ### Returns:

  table t with nodes from u merged in

  ### See also:

  std.table.merge

  ### Usage:

      merge (dest, {{exists=1}, {{not = {present = { inside = "dest" }}}}})

std.tree.nodes (tr)
  Tree iterator over all nodes.

  The returned iterator function performs a depth-first traversal of `tr`, and at each node it returns `{node-type, tree-path, tree-node}` where `node-type` is `branch`, `join` or `leaf`; `tree-path` is a list of keys used to reach this node, and `tree-node` is the current node.

  Note that the `tree-path` reuses the same table on each iteration, so you must `table.clone` a copy if you want to take a snap-shot of the current state of the `tree-path` list before the next iteration changes it.

  ### Parameters:

  - tr Tree or table tree or tree-like table to iterate over

  ### Returns:

  1. function iterator function
  2. Tree or table the tree, tr

  ### See also:

  inodes

  ### Usage:

       -- tree = +-- node1
       --        |    +-- leaf1
       --        |    '-- leaf2
       --        '-- leaf 3
       tree = Tree { Tree { "leaf1", "leaf2"}, "leaf3" }
       for node_type, path, node in nodes (tree) do
         print (node_type, path, node)
       end
       --> "branch"   {}      {{"leaf1", "leaf2"}, "leaf3"}
       --> "branch"   {1}     {"leaf1", "leaf"2")
       --> "leaf"     {1,1}   "leaf1"
       --> "leaf"     {1,2}   "leaf2"
       --> "join"     {1}     {"leaf1", "leaf2"}
       --> "leaf"     {2}     "leaf3"
       --> "join"     {}      {{"leaf1", "leaf2"}, "leaf3"}
       os.exit (0)

## Metamethods

std.tree.__index (tr, i)
  Deep retrieval.

  ### Parameters:

  - tr Tree a tree
  - i non-table, or list of keys `{i1, ...i_n}`

  ### Returns:

  `tr[i1]...[i_n]` if i is a key list, `tr[i]` otherwise

  ### Usage:

      del_other_window = keymap[{"C-x", "4", KEY_DELETE}]

std.tree.__newindex (tr, i[, v])
  Deep insertion.

  ### Parameters:

  - tr Tree a tree
  - i non-table, or list of keys `{i1, ...i_n}`
  - v value (optional)

  ### Usage:

      function bindkey (keylist, fn) keymap[keylist] = fn end

generated by LDoc 1.4.3 Last updated 2018-09-03 17:48:42