The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Tree-Ops-20200627
River stage zero No dependents
1 ++
/ Tree::Ops

Name

Tree::Ops - Tree operations.

Synopsis

Create a tree:

  my $t = Tree::Ops::new 'a';
  for(1..2)
   {$t->open  ('b');
    $t->single('c');
    $t->close;
   }
  $t->single  ('d');

Print the tree:

  is_deeply $t->print(sub{@_}), <<END;
  a
    b
      c
    b
      c
    d
  END

Locate a specific child in the tree and print it:

  my ($c) = $t->select(sub{$_[0] eq 'c'});

  is_deeply $c->print (sub{$_[0]}), <<END;
  c
  END

Description

Tree operations.

Version 20200626.

The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.

Build

Create a tree.

new($user)

Create a new child recording the specified user data.

     Parameter  Description
  1  $user      User data to be recorded in the child

Example:

  if (1)
   {my $t = Tree::Ops::𝗻𝗲𝘄 'a';
    for(1..2)
     {$t->open  ('b');
      $t->single('c');
      $t->close;
     }
    $t->single  ('d');
    is_deeply $t->print(sub {$_[0]}), <<END;
  a
    b
      c
    b
      c
    d
  END

    my ($c) = $t->select(sub{$_[0] eq 'c'});
    is_deeply $c->print (sub{$_[0]}), <<END;
  c
  END
   }

This is a static method and so should either be imported or invoked as:

  Tree::Ops::new

open($tree, $user)

Add a child and make it the currently active scope into which new nodes are added.

     Parameter  Description
  1  $tree      Tree
  2  $user      User data to be recorded in the interior child being opened

Example:

  if (1)
   {my $t = Tree::Ops::new 'a';
    for(1..2)
     {$t->𝗼𝗽𝗲𝗻  ('b');
      $t->single('c');
      $t->close;
     }
    $t->single  ('d');
    is_deeply $t->print(sub {$_[0]}), <<END;
  a
    b
      c
    b
      c
    d
  END

    my ($c) = $t->select(sub{$_[0] eq 'c'});
    is_deeply $c->print (sub{$_[0]}), <<END;
  c
  END
   }

close($tree)

Close the current scope returning to the previous scope.

     Parameter  Description
  1  $tree      Tree

Example:

  if (1)
   {my $t = Tree::Ops::new 'a';
    for(1..2)
     {$t->open  ('b');
      $t->single('c');
      $t->𝗰𝗹𝗼𝘀𝗲;
     }
    $t->single  ('d');
    is_deeply $t->print(sub {$_[0]}), <<END;
  a
    b
      c
    b
      c
    d
  END

    my ($c) = $t->select(sub{$_[0] eq 'c'});
    is_deeply $c->print (sub{$_[0]}), <<END;
  c
  END
   }

single($tree, $user)

Add one child in the current scope.

     Parameter  Description
  1  $tree      Tree
  2  $user      User data to be recorded in the child being created

Example:

  if (1)
   {my $t = Tree::Ops::new 'a';
    for(1..2)
     {$t->open  ('b');
      $t->𝘀𝗶𝗻𝗴𝗹𝗲('c');
      $t->close;
     }
    $t->𝘀𝗶𝗻𝗴𝗹𝗲  ('d');
    is_deeply $t->print(sub {$_[0]}), <<END;
  a
    b
      c
    b
      c
    d
  END

    my ($c) = $t->select(sub{$_[0] eq 'c'});
    is_deeply $c->print (sub{$_[0]}), <<END;
  c
  END
   }

Traverse

Traverse through the tree.

first($parent)

Get the first child under the specified parent.

     Parameter  Description
  1  $parent    Parent

Example:

    if (1) {

last($parent)

Get the last child under the specified parent.

     Parameter  Description
  1  $parent    Parent

Example:

    if (1) {

next($child)

Get the next sibling following the specified child.

     Parameter  Description
  1  $child     Child

Example:

    if (1) {

prev($child)

Get the previous sibling of the specified child.

     Parameter  Description
  1  $child     Child

Example:

    if (1) {

Put

Insert children into a tree.

putFirst($parent, $child)

Place a new child first under the specified parent and return the child.

     Parameter  Description
  1  $parent    Parent
  2  $child     Child

Example:

    if (1) {

putLast($parent, $child)

Place a new child last under the specified parent and return the child.

     Parameter  Description
  1  $parent    Parent
  2  $child     Child

Example:

    if (1) {

putNext($child, $new)

Place a new child after the specified child.

     Parameter  Description
  1  $child     Existing child
  2  $new       New child

Example:

    if (1) {

putPrev($child, $new)

Place a new child before the specified child.

     Parameter  Description
  1  $child     Child
  2  $new       New child

Example:

    if (1) {

Edit

Edit nodes in context.

context($child)

Get the context of the current child.

     Parameter  Description
  1  $child     Child

Example:

    if (1) {

cut($node)

Cut out a child and all its content and children, return it ready for reinsertion else where.

     Parameter  Description
  1  $node      Child

Example:

    if (1) {

dup($parent)

Duplicate a child and all its parents.

     Parameter  Description
  1  $parent    Parent

Example:

    if (1) {

unwrap($child)

Unwrap the specified child and return the unwrapped child.

     Parameter  Description
  1  $child     Child

Example:

    if (1) {

wrap($child, $new)

Wrap the specified child with a new child.

     Parameter  Description
  1  $child     Child to wrap
  2  $new       Wrapping child

Example:

    if (1) {

Traverse

Traverse the tree.

by($tree, $sub)

Traverse a tree in order to process each child and return an array of the results of processing each node.

     Parameter  Description
  1  $tree      Tree
  2  $sub       Method to process a child

Example:

    if (1) {

select($tree, $select, $user)

Select matching children in a tree.

     Parameter  Description
  1  $tree      Tree
  2  $select    Method to select a child
  3  $user      User data handed to selecting sub

Example:

  if (1)
   {my $t = Tree::Ops::new 'a';
    for(1..2)
     {$t->open  ('b');
      $t->single('c');
      $t->close;
     }
    $t->single  ('d');
    is_deeply $t->print(sub {$_[0]}), <<END;
  a
    b
      c
    b
      c
    d
  END

    my ($c) = $t->𝘀𝗲𝗹𝗲𝗰𝘁(sub{$_[0] eq 'c'});
    is_deeply $c->print (sub{$_[0]}), <<END;
  c
  END
   }

Print

Print the tree.

print($tree, $print)

String representation as a horizontal tree.

     Parameter  Description
  1  $tree      Tree
  2  $print     Print method

Example:

  if (1)
   {my $t = Tree::Ops::new 'a';
    for(1..2)
     {$t->open  ('b');
      $t->single('c');
      $t->close;
     }
    $t->single  ('d');
    is_deeply $t->𝗽𝗿𝗶𝗻𝘁(sub {$_[0]}), <<END;
  a
    b
      c
    b
      c
    d
  END

    my ($c) = $t->select(sub{$_[0] eq 'c'});
    is_deeply $c->𝗽𝗿𝗶𝗻𝘁 (sub{$_[0]}), <<END;
  c
  END
   }

brackets($tree, $print, $separator)

Bracketed string representation of a tree.

     Parameter   Description
  1  $tree       Tree
  2  $print      Print method
  3  $separator  Child separator

Example:

    if (1) {

Data Structures

Data structures use by this package.

Tree::Ops Definition

Child in the tree

Output fields

children - Children of this child

lastChild - Last active child

parent - Parent for this child

user - User data for this child

Private Methods

activeScope($tree)

Locate the active scope in a tree.

     Parameter  Description
  1  $tree      Tree

indexOfChildInParent($child)

Get the index of a child within the specified parent.

     Parameter  Description
  1  $child     Child

Index

1 activeScope - Locate the active scope in a tree.

2 brackets - Bracketed string representation of a tree.

3 by - Traverse a tree in order to process each child and return an array of the results of processing each node.

4 close - Close the current scope returning to the previous scope.

5 context - Get the context of the current child.

6 cut - Cut out a child and all its content and children, return it ready for reinsertion else where.

7 dup - Duplicate a child and all its parents.

8 first - Get the first child under the specified parent.

9 indexOfChildInParent - Get the index of a child within the specified parent.

10 last - Get the last child under the specified parent.

11 new - Create a new child recording the specified user data.

12 next - Get the next sibling following the specified child.

13 open - Add a child and make it the currently active scope into which new nodes are added.

14 prev - Get the previous sibling of the specified child.

15 print - String representation as a horizontal tree.

16 putFirst - Place a new child first under the specified parent and return the child.

17 putLast - Place a new child last under the specified parent and return the child.

18 putNext - Place a new child after the specified child.

19 putPrev - Place a new child before the specified child.

20 select - Select matching children in a tree.

21 single - Add one child in the current scope.

22 unwrap - Unwrap the specified child and return the unwrapped child.

23 wrap - Wrap the specified child with a new child.

Installation

This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:

  sudo cpan install Tree::Ops

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

Copyright (c) 2016-2019 Philip R Brenan.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.