---
name: "TM::Tree"
section: "3pm"
platform: "linux"
package: "libtm-perl"
version: "1.56-7"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/TM::Tree"
---

# TM::Tree(3pm)

Topic Maps, trait for induced tree retrieval

## NAME

TM::Tree - Topic Maps, trait for induced tree retrieval

## SYNOPSIS

```
  use TM::Materialized::AsTMa;
  my $tm = new TM::Materialized::AsTMa (file => 'old_testament.atm');
  Class::Trait->apply ( $tm => 'TM::Tree' );
  $tm->sync_in;
  # old-testament pedigree
  print Dumper $tm->tree (lid   => 'adam',
                          type  => 'has-parent',
                          arole => 'parent',
                          brole => 'child' );
  # new-testament inverse pedigree
  print Dumper $tm->tree (lid   => 'gw-bush',
                          type  => 'has-parent',
                          arole => 'child',
                          brole => 'parent' );
```

## DESCRIPTION

Obviously, topic maps can carry information which is tree structured. A family pedigree is a typical example of it; associations having a particular type, particular roles and you can derive a tree structure from that.

This is exactly what this operator does: it takes one topic map basis and primed with a starting node, an association type and two roles a tree will be returned to the caller.

## INTERFACE

### Methods

- **tree**

  *$treeref* = *$tm*-\>tree (\
                    *$start\_topic*,\
                    *$type\_topic*,\
                    *$role\_topic*,\
                    *$role\_topic*,\
                    \[ depth =\> *$integer* \])

  *$treeref* = *$tm*-\>tree\_x (\
                    *$start\_topic*,\
                    *$type\_topic*,\
                    *$role\_topic*,\
                    *$role\_topic*,\
                    \[ depth =\> *$integer* \])

  This function will analyze the topic map and will detect all maplets of the given type (direct and indirect ones) having the specified roles. Starting from the *start topic* it will so find other topics playing the *brole*. Those will be used as a next starting point, and so forth.

  To avoid the tree to become too big, you can impose an optional limit. Loops are detected.

  Every output tree node contains following fields:

  - "lid":

    the lid of the node

  - "children":

    a list reference of child nodes, there is no specific sort order

  - "children\*":

    **Note**: This is currently deactivated.

    for convenience this list reference contains all children, grand-children, grand-grand children.... of this node (this list is neither sorted nor unique out of performance considerations).

  The version `"tree_x"` does not honor subclassing of roles and type (but `"tree"` does). This means that is can be considerably faster, especially if you use it for taxonomy stuff with `"isa"` and `"is-subclass-of"`.

- **taxonomy**

  *$treeref* = *$tm*-\>taxonomy (\[ *$start\_lid* \])

  This function is a specialization of `"tree"`, in that it looks at a particular association type (`"is-subclass-of"`) and the appropriate roles (`"superclass"`, `"subclass"`). Obviously the result is a tree holding all subtypes.

  The only optional parameter is a toplet `"lid"`; that becomes the starting point of the tree. If that parameter is missing, `"thing"` is assumed.

## SEE ALSO

TM

## COPYRIGHT AND LICENSE

Copyright 200\[3-6\] by Robert Barta, \<drrho@cpan.org\>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.