stdlib 41.2.3 Reference

# 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

### See also:

std.container

## 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 table if non-`nil` don't copy metatables

  ### Returns:

  std.tree.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 std.tree.Tree or table tree or tree-like table

  ### Returns:

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

  ### See also:

  - std.tree.inodes
  - std.tree.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 std.tree.nodes, but only traverses the array part of the nodes of *tr*, ignoring any others.

  ### Parameters:

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

  ### Returns:

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

  ### See also:

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

  ### Parameters:

  - t table tree or tree-like table

  ### Returns:

  1. table iterator function
  2. table *t*

  ### See also:

  - std.tree.ileaves
  - std.tree.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 std.tree.Tree or table tree or tree-like table to iterate over

  ### Returns:

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

  ### See also:

  std.tree.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 std.tree.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 std.tree.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.5.0 Last updated 2026-07-25 13:31:42