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

# TM::Bulk(3pm)

Topic Maps, Bulk Retrieval Trait

## NAME

TM::Bulk - Topic Maps, Bulk Retrieval Trait

## SYNOPSIS

```
  my $tm = .....                          # get a map from anywhere
  use TM::Bulk;
  use Class::Trait;
  Class::Trait->apply ($tm, 'TM::Bulk');  # give the map the trait
  # find out environment of topic
  my $vortex = $tm->vortex ('some-lid',
                           {
                            'types'       => [ 'types' ],
                            'instances'   => [ 'instances*', 0, 20 ],
                            'topic'       => [ 'topic' ],
                            'roles'       => [ 'roles',     0, 10 ],
                            'members'     => [ 'players' ],
                           },
                           );
  # find names of topics (optionally using a scope preference list)
  my $names = $tm->names ([ 'ccc', 'bbb', 'aaa' ], [ 's1', 's3', '*' ]);
```

## DESCRIPTION

Especially when you build user interfaces, you might need access to a lot of topic-related information. Instead of collecting this 'by foot' the following methods help you achieve this more effectively.

- **names**

  *$name\_hash\_ref* = *$tm*-\>names (*$lid\_list\_ref*, \[ *$scope\_list\_ref* \] )

  This method takes a list (reference) of topic ids and an optional list of scoping topic ids.  For the former it will try to find the *name*s (*topic names* for TMDM acolytes).

  If the list of scopes is empty then the preference is on the unconstrained scope. If no name for a topic is in that scope, some other will be used.

  If the list of scopes is non-empty, it directs to look first for a name in the first scoping topic, then second, and so on. If you want to have one name in any case, append `"*"` to the scoping list.

  If no name exist for a particular *lid*, then an `"undef"` is returned in the result hash. References to non-existing topics are ignored.

  The overall result is a hash (reference). The keys are of the form `"topic-id @ scope-id"` (without the blanks) and the name strings are the values.

- **vortex**

  *$info* = *$tm*-\>vortex (,\
                  *$vortex\_lid*,\
                  *$what\_hashref*,\
                  *$scope\_list\_ref* )

  This method returns **a lot** of information about a particular toplet (vortex). The function expects the following parameters:

  - *lid*:

    the lid of the toplet in question

  - *what*:

    a hash reference describing the extent of the information (see below)

  - *scopes*:

    a list (reference) to scopes (currently **NOT** honored)

  To control **what** exactly should be returned, the `"what"` hash reference can contain following components. All of them being tagged with \<n,m\> accept an additional pair of integer specify the range which should be returned.  To ask for the first twenty, use `"0,19"`, for the next `"20,39"`. The order in which the identifiers is returned is undefined but stable over subsequent read-only calls.

  - *topic*:

    fetches the toplet (which is only the subject locator, subject indicators information).

  - *names* (\<n,m\>):

    fetches all names (as array reference triple \[ *type*, *scope*, string value \])

  - *occurrences* (\<n,m\>):

    fetches all occurrences (as array reference triple \[ *type*, *scope*, *value* \])

  - *instances* (\<n,m\>):

    fetches all toplets which are direct instances of the vortex (that is regarded as class here);

  - *instances\** (\<n,m\>):

    same as `"instances"`, but including all instances of subclasses of the vortex

  - *types* (\<n,m\>):

    fetches all (direct) types of the vortex (that is regarded as instance here)

  - *types\** (\<n,m\>):

    fetches all (direct and indirect) types of the vortex (that is regarded as instance here)

  - *subclasses* (\<n,m\>):

    fetches all direct subclasses

  - *subclasses\** (\<n,m\>):

    same as `"subclasses"`, but creates reflexive, transitive closure

  - *superclasses* (\<n,m\>):

    fetches all direct superclasses

  - *superclasses\** (\<n,m\>):

    same as `"superclasses"`, but creates reflexive, transitive closure

  - *roles* (\<n,m\>):

    fetches all assertion ids where the vortex plays a role

  - *peers* (\<n,m\>):

    fetches all topics which are also a direct instance of any of the (direct) types of this topic

  - *peers\** (\<n,m\>):

    fetches all topics which are also a (direct or indirect) instances of any of the (direct) types of this topic

  - *peers\*\** (\<n,m\>):

    fetches all topics which are also a (direct or indirect) instances of any of the (direct or indirect) types of this topic

  The function will determine all of the requested information and will prepare a hash reference storing each information into a hash component. Under which name this information is stored, the caller can determine with the hash above as the example shows:

  Example:

  ```
    $vortex = $tm->vortex ('some-lid',
                           {
                            'types'       => [ 'types' ],
                            'instances'   => [ 'instances*', 0, 20 ],
                            'topic'       => [ 'topic' ],
                            'roles'       => [ 'roles',     0, 10 ],
                           },
                          );
  ```

  The method dies if `"lid"` does not identify a proper toplet.

## SEE ALSO

TM::Overview

## COPYRIGHT AND LICENSE

Copyright 200\[3-57\] 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.