/ 
TM-Easy-0.03
River stage zero No dependents
/ TM::Easy

NAME

TM::Easy - Topic Maps, Easy Usage

SYNOPSIS

use TM::Easy;

# for the couch potatoes
my $mm = new TM::Easy (file => 'somewhere.atm');
# or, alternatively
my $mm = new TM::Easy (inline => ' # here is AsTMa');
# or, alternatively from LTM
my $mm = new TM::Easy (file => 'somewhereelse.ltm');

# more flexibility when doing it in several steps:
# acquire a map from somewhere, any map should do (see TM)
use TM;
my $tm = new TM;

# create an Easy Access (I'm sure some stupid company has a trademark on this)
my $mm = new TM::Easy::Map ($tm);

# walking, walking, ...
foreach my $tid (keys %$mm) {        # iterate over all toplet identifiers
   ...
}

warn "oh no" unless $mm->{hubert};   # check whether a topic exists with this local identifier
my $hubert = $mm->{hubert};          # using the local identifier

print $hubert->{'!'};                # the local identifier, TMQL notation
my $add = $hubert->{'='};            # the subject address, TMQL notation
my @sin = $hubert->{'~'};            # the subject identifiers (as list reference, TMQL notation)

print $hubert->{name_s}              # get a list of names
print $hubert->{name}                # get _some_ name (or undef if there is none)
print $hubert->{occurrence_s}        # get a list of all occurrences
print $hubert->{occurrence}          # get a scalar with _some_ occurrence
print $hubert->{blog_s}              # list of all blog characteristics
print $hubert->{blog}                # get occurrence (or name) with this type, one value

my $a = $hubert->{-owner};           # get association where hubert is owner
my $a = $hubert->{'<- owner'};       # same, but with TMQL notation

foreach my $role (keys %$a) {        # iterate over all roles
   warn $a->{$role}                  # output ONE player (does not work if there are several!)
   warn $a->{"-> $role"}             # same with TMQL notation

   warn $a->{"${role}_s"};           # get list of all role players
   warn $a->{"-> ${role}_s"};        # same, with TMQL notation
}

foreach (@{ $hubert->{'<-> likes'} }) {  # iterate over all on the other side(s)
   ...
}

ABSTRACT

This package provides a HASH-like access to a topic map. For this purpose, first a given topic map object will be tied to a hash and then the user can access certain aspects of a topic map via keys. The same holds true for topics and associations.

DESCRIPTION

This abstraction layer provides a rather simplified view on topic map content. It pretends that a topic map is a hash, a topic is a hash and an association is an hash. In that, this package offers access to topics in maps, names and occurrences in topics and roles and players in associations via keys.

Unsurprisingly, this package does not harness all the beauty (or ugliness) of TM.

NOTE: At the moment, we support only reading. That may change in the future.

Maps as Hashes

keys: get all local toplet identifiers

keys %$map

fetch
get the toplet with this toplet identifier

$map->{xxx}

get the toplet with this subject identifier

$map->{'http://... ~'}

same

$map->{'http://...'}

get the toplet with this subject address

$map->{'http://... ='}

exists: check whether the toplet exists

exists $map->{xxx}

exists $map->{'http://... ~'}

exists $map->{'http://... ='}

Topics as Hashes

identification

$t->{'!'} # get local identifier

$t->{'='} # get subject address (or undef)

$t->{'~'} # get subject identifiers (as list reference)

characteristics

$t->{name} # get ONE name

$t->{name_s} # get ALL names (as list reference)

$t->{nickname} # get ONE name of this type

$t->{nickname_s} # get ALL names of this type (as list reference)

$t->{homepage} # get ONE occurrence of this type

$t->{homepage_s} # get ALL occurrences of this type (as list reference)

role playing

$t->{'<- in_role'} # get ONE association where toplet plays in_role

$t->{-in_role} # same, shorter

$t->{'<- in_role_s'} # get ALL associations where toplet plays in_role

$t->{-in_role_s} # same, shorter

Associations as Hashes

keys

keys %$a # all roles (role types)

fetch

%$a->{out_role} # get ONE toplet playing out_role

%$a->{'-> out_role'} # same longer

%$a->{out_role_s} # get ALL toplets playing out_role

%$a->{'-> out_role_s'} # same longer

TODOs?

$someone->{'<- husband -> wife'};

INTERFACE

Constructor

The constructor accepts an optional hash specifying the source of the map:

inline:

The string value specifies directly a map denoted in AsTMa.

file:

The string denotes a file from where the map is consumed. If the filename ends with .atm, then an AsTMa file is assumed. If it ends with .ltm, then it will be parsed as LTM file. Otherwise the machinery falls back to AsTMa.

TODO: support XTM x.x

Methods

map

This read-only method gives you access to the underlying TM object.

SEE ALSO

TM

CREDITS

All this was strongly inspired by the Mappa project (Lars Heuer).

COPYRIGHT AND LICENSE

Copyright 200[8] 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.

Work under a Research Grant by the Austrian Research Centers Seibersdorf.