.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "TM::Bulk 3pm" .TH TM::Bulk 3pm "2008-04-23" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" TM::Bulk \- Topic Maps, Bulk Retrieval Trait .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& my $tm = ..... # get a map from anywhere \& \& use TM::Bulk; \& use Class::Trait; \& Class::Trait\->apply ($tm, \*(AqTM::Bulk\*(Aq); # give the map the trait \& \& # find out environment of topic \& my $vortex = $tm\->vortex (\*(Aqsome\-lid\*(Aq, \& { \& \*(Aqtypes\*(Aq => [ \*(Aqtypes\*(Aq ], \& \*(Aqinstances\*(Aq => [ \*(Aqinstances*\*(Aq, 0, 20 ], \& \*(Aqtopic\*(Aq => [ \*(Aqtopic\*(Aq ], \& \*(Aqroles\*(Aq => [ \*(Aqroles\*(Aq, 0, 10 ], \& \*(Aqmembers\*(Aq => [ \*(Aqplayers\*(Aq ], \& }, \& ); \& # find names of topics (optionally using a scope preference list) \& my $names = $tm\->names ([ \*(Aqccc\*(Aq, \*(Aqbbb\*(Aq, \*(Aqaaa\*(Aq ], [ \*(Aqs1\*(Aq, \*(Aqs3\*(Aq, \*(Aq*\*(Aq ]); .Ve .SH "DESCRIPTION" .IX Header "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. .IP "\fBnames\fR" 4 .IX Item "names" \&\fI\f(CI$name_hash_ref\fI\fR = \fI\f(CI$tm\fI\fR\->names (\fI\f(CI$lid_list_ref\fI\fR, [ \fI\f(CI$scope_list_ref\fI\fR ] ) .Sp 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 \fIname\fRs (\fItopic names\fR for \s-1TMDM\s0 acolytes). .Sp 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. .Sp 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 \f(CW\*(C`*\*(C'\fR to the scoping list. .Sp If no name exist for a particular \fIlid\fR, then an \f(CW\*(C`undef\*(C'\fR is returned in the result hash. References to non-existing topics are ignored. .Sp The overall result is a hash (reference). The keys are of the form \f(CW\*(C`topic\-id @ scope\-id\*(C'\fR (without the blanks) and the name strings are the values. .IP "\fBvortex\fR" 4 .IX Item "vortex" \&\fI\f(CI$info\fI\fR = \fI\f(CI$tm\fI\fR\->vortex (, \fI\f(CI$vortex_lid\fI\fR, \fI\f(CI$what_hashref\fI\fR, \fI\f(CI$scope_list_ref\fI\fR ) .Sp This method returns \fBa lot\fR of information about a particular toplet (vortex). The function expects the following parameters: .RS 4 .IP "\fIlid\fR:" 4 .IX Item "lid:" the lid of the toplet in question .IP "\fIwhat\fR:" 4 .IX Item "what:" a hash reference describing the extent of the information (see below) .IP "\fIscopes\fR:" 4 .IX Item "scopes:" a list (reference) to scopes (currently \fB\s-1NOT\s0\fR honored) .RE .RS 4 .Sp To control \fBwhat\fR exactly should be returned, the \f(CW\*(C`what\*(C'\fR hash reference can contain following components. All of them being tagged with accept an additional pair of integer specify the range which should be returned. To ask for the first twenty, use \f(CW\*(C`0,19\*(C'\fR, for the next \&\f(CW\*(C`20,39\*(C'\fR. The order in which the identifiers is returned is undefined but stable over subsequent read-only calls. .IP "\fItopic\fR:" 4 .IX Item "topic:" fetches the toplet (which is only the subject locator, subject indicators information). .IP "\fInames\fR ():" 4 .IX Item "names ():" fetches all names (as array reference triple [ \fItype\fR, \fIscope\fR, string value ]) .IP "\fIoccurrences\fR ():" 4 .IX Item "occurrences ():" fetches all occurrences (as array reference triple [ \fItype\fR, \fIscope\fR, \fIvalue\fR ]) .IP "\fIinstances\fR ():" 4 .IX Item "instances ():" fetches all toplets which are direct instances of the vortex (that is regarded as class here); .IP "\fIinstances*\fR ():" 4 .IX Item "instances* ():" same as \f(CW\*(C`instances\*(C'\fR, but including all instances of subclasses of the vortex .IP "\fItypes\fR ():" 4 .IX Item "types ():" fetches all (direct) types of the vortex (that is regarded as instance here) .IP "\fItypes*\fR ():" 4 .IX Item "types* ():" fetches all (direct and indirect) types of the vortex (that is regarded as instance here) .IP "\fIsubclasses\fR ():" 4 .IX Item "subclasses ():" fetches all direct subclasses .IP "\fIsubclasses*\fR ():" 4 .IX Item "subclasses* ():" same as \f(CW\*(C`subclasses\*(C'\fR, but creates reflexive, transitive closure .IP "\fIsuperclasses\fR ():" 4 .IX Item "superclasses ():" fetches all direct superclasses .IP "\fIsuperclasses*\fR ():" 4 .IX Item "superclasses* ():" same as \f(CW\*(C`superclasses\*(C'\fR, but creates reflexive, transitive closure .IP "\fIroles\fR ():" 4 .IX Item "roles ():" fetches all assertion ids where the vortex plays a role .IP "\fIpeers\fR ():" 4 .IX Item "peers ():" fetches all topics which are also a direct instance of any of the (direct) types of this topic .IP "\fIpeers*\fR ():" 4 .IX Item "peers* ():" fetches all topics which are also a (direct or indirect) instances of any of the (direct) types of this topic .IP "\fIpeers**\fR ():" 4 .IX Item "peers** ():" fetches all topics which are also a (direct or indirect) instances of any of the (direct or indirect) types of this topic .RE .RS 4 .Sp 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: .Sp Example: .Sp .Vb 8 \& $vortex = $tm\->vortex (\*(Aqsome\-lid\*(Aq, \& { \& \*(Aqtypes\*(Aq => [ \*(Aqtypes\*(Aq ], \& \*(Aqinstances\*(Aq => [ \*(Aqinstances*\*(Aq, 0, 20 ], \& \*(Aqtopic\*(Aq => [ \*(Aqtopic\*(Aq ], \& \*(Aqroles\*(Aq => [ \*(Aqroles\*(Aq, 0, 10 ], \& }, \& ); .Ve .Sp The method dies if \f(CW\*(C`lid\*(C'\fR does not identify a proper toplet. .RE .SH "SEE ALSO" .IX Header "SEE ALSO" TM::Overview .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 200[3\-57] by Robert Barta, .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.