.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Stag 3pm"
.TH Data::Stag 3pm "2016-05-29" "perl v5.22.2" "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"
.Vb 1
\&  Data::Stag \- Structured Tags datastructures
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 11
\&  # PROCEDURAL USAGE
\&  use Data::Stag qw(:all);
\&  $doc = stag_parse($file);
\&  @persons = stag_find($doc, "person");
\&  foreach $p (@persons) {
\&    printf "%s, %s phone: %s\en",
\&      stag_sget($p, "family_name"),
\&      stag_sget($p, "given_name"),
\&      stag_sget($p, "phone_no"),
\&    ;
\&  } 
\&
\&  # OBJECT\-ORIENTED USAGE
\&  use Data::Stag;
\&  $doc = Data::Stag\->parse($file);
\&  @persons = $doc\->find("person");
\&  foreach $p (@person) {
\&    printf "%s, %s phone:%s\en",
\&      $p\->sget("family_name"),
\&      $p\->sget("given_name"),
\&      $p\->sget("phone_no"),
\&    ;
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is for manipulating data as hierarchical tag/value
pairs (Structured TAGs or Simple Tree AGgreggates). These
datastructures can be represented as nested arrays, which have the
advantage of being native to perl. A simple example is shown below:
.PP
.Vb 3
\&  [ person=> [  [ family_name => $family_name ],
\&                [ given_name  => $given_name  ],
\&                [ phone_no    => $phone_no    ] ] ],
.Ve
.PP
Data::Stag uses a subset of \s-1XML\s0 for import and export. This
means the module can also be used as a general \s-1XML\s0 parser/writer (with
certain caveats).
.PP
The above set of structured tags can be represented in \s-1XML\s0 as
.PP
.Vb 5
\&  <person>
\&    <family_name>...</family_name>
\&    <given_name>...</given_name>
\&    <phone_no>...</phone_no>
\&  </person>
.Ve
.PP
This datastructure can be examined, manipulated and exported using
Stag functions or methods:
.PP
.Vb 7
\&  $document = Data::Stag\->parse($file);
\&  @persons = $document\->find(\*(Aqperson\*(Aq);
\&  foreach my $person (@person) {
\&    $person\->set(\*(Aqfull_name\*(Aq,
\&                 $person\->sget(\*(Aqgiven_name\*(Aq) . \*(Aq \*(Aq .
\&                 $person\->sget(\*(Aqfamily_name\*(Aq));
\&  }
.Ve
.PP
Advanced querying is performed by passing functions, for example:
.PP
.Vb 4
\&  # get all people in dataset with name starting \*(AqA\*(Aq
\&  @persons = 
\&    $document\->where(\*(Aqperson\*(Aq,
\&                     sub {shift\->sget(\*(Aqfamily_name\*(Aq) =~ /^A/});
.Ve
.PP
One of the things that marks this module out against other \s-1XML\s0 modules
is this emphasis on a \fBfunctional\fR approach as an obect-oriented or
procedural approach.
.PP
For full information on the stag project, see
<http://stag.sourceforge.net>
.SS "\s-1PROCEDURAL VS\s0 OBJECT-ORIENTED \s-1USAGE\s0"
.IX Subsection "PROCEDURAL VS OBJECT-ORIENTED USAGE"
Depending on your preference, this module can be used a set of
procedural subroutine calls, or as method calls upon Data::Stag
objects, or both.
.PP
In procedural mode, all the subroutine calls are prefixed \*(L"stag_\*(R" to
avoid namespace clashes. The following three calls are equivalent:
.PP
.Vb 3
\&  $person = stag_find($doc, "person");
\&  $person = $doc\->find("person");
\&  $person = $doc\->find_person;
.Ve
.PP
In object mode, you can treat any tree element as if it is an object
with automatically defined methods for getting/setting the tag values.
.SS "\s-1USE OF XML\s0"
.IX Subsection "USE OF XML"
Nested arrays can be imported and exported as \s-1XML,\s0 as well as other
formats. \s-1XML\s0 can be slurped into memory all at once (using less memory
than an equivalent \s-1DOM\s0 tree), or a simplified \s-1SAX\s0 style event handling
model can be used. Similarly, data can be exported all at once, or as
a series of events.
.PP
Although this module can be used as a general \s-1XML\s0 tool, it is intended
primarily as a tool for manipulating hierarchical data using nested
tag/value pairs.
.PP
This module is more suited to dealing with data-oriented documents
than text-oriented documents.
.PP
By using a simpler subset of \s-1XML\s0 equivalent to a basic data tree
structure, we can write simpler, cleaner code.
.PP
This module is ideally suited to element-only \s-1XML \s0(that is, \s-1XML\s0
without attributes or mixed elements).
.PP
If you are using attributes or mixed elements, it is useful to know
what is going on under the hood.
.PP
All attributes are turned into elements; they are nested inside an
element with name \fB'@'\fR.
.PP
For example, the following piece of \s-1XML\s0
.PP
.Vb 3
\&  <foo id="x">
\&    <bar>ugh</bar>
\&  </foo>
.Ve
.PP
Gets represented internally as
.PP
.Vb 6
\&  <foo>
\&    <@>
\&      <id>x</id>
\&    </@>
\&    <bar>ugh</bar>
\&  </foo>
.Ve
.PP
Of course, this is not valid \s-1XML.\s0 However, it is just an internal
representation \- when exporting back to \s-1XML\s0 it will look like normal
\&\s-1XML\s0 with attributes again.
.PP
Mixed content cannot be represented in a simple tree format, so this
is also expanded.
.PP
The following piece of \s-1XML\s0
.PP
.Vb 3
\&  <paragraph id="1" color="green">
\&    example of <bold>mixed</bold>content
\&  </paragraph>
.Ve
.PP
gets parsed as if it were actually:
.PP
.Vb 9
\&  <paragraph>
\&    <@>
\&      <id>1</id>
\&      <color>green</color>
\&    </@>
\&    <.>example of</.>
\&    <bold>mixed</bold>
\&    <.>content</.>
\&  </paragraph>
.Ve
.PP
When using stag with attribute or mixed attribute xml, you can treat
\&\fB'@'\fR and \fB'.'\fR as normal elements
.PP
\fI\s-1SAX\s0\fR
.IX Subsection "SAX"
.PP
This module can also be used as part of a SAX-style event generation /
handling framework \- see Data::Stag::BaseHandler
.PP
\fI\s-1PERL REPRESENTATION\s0\fR
.IX Subsection "PERL REPRESENTATION"
.PP
Because nested arrays are native to perl, we can specify an \s-1XML\s0
datastructure directly in perl without going through multiple object
calls.
.PP
For example, instead of using XML::Writer for the lengthy
.PP
.Vb 8
\&  $obj\->startTag("record");
\&  $obj\->startTag("field1");
\&  $obj\->characters("foo");
\&  $obj\->endTag("field1");
\&  $obj\->startTag("field2");
\&  $obj\->characters("bar");
\&  $obj\->endTag("field2");
\&  $obj\->end("record");
.Ve
.PP
We can instead write
.PP
.Vb 3
\&  $struct = [ record => [
\&              [ field1 => \*(Aqfoo\*(Aq],
\&              [ field2 => \*(Aqbar\*(Aq]]];
.Ve
.PP
\fI\s-1PARSING\s0\fR
.IX Subsection "PARSING"
.PP
The following example is for parsing out subsections of a tree and
changing sub-elements
.PP
.Vb 5
\&  use Data::Stag qw(:all);
\&  my $tree = stag_parse($xmlfile);
\&  my ($subtree) = stag_findnode($tree, $element);
\&  stag_set($element, $sub_element, $new_val);
\&  print stag_xml($subtree);
.Ve
.PP
\fI\s-1OBJECT ORIENTED\s0\fR
.IX Subsection "OBJECT ORIENTED"
.PP
The same can be done in a more \s-1OO\s0 fashion
.PP
.Vb 5
\&  use Data::Stag qw(:all);
\&  my $tree = Data::Stag\->parse($xmlfile);
\&  my ($subtree) = $tree\->findnode($element);
\&  $element\->set($sub_element, $new_val);
\&  print $subtree\->xml;
.Ve
.PP
\fI\s-1IN A STREAM\s0\fR
.IX Subsection "IN A STREAM"
.PP
Rather than parsing in a whole file into memory all at once (which may
not be suitable for very large files), you can take an \fBevent
handling\fR approach. The easiest way to do this to register which nodes
in the file you are interested in using the \fBmakehandler\fR method. The
parser will sweep through the file, building objects as it goes, and
handing the object to a subroutine that you specify.
.PP
For example:
.PP
.Vb 11
\&  use Data::Stag;
\&  # catch the end of \*(Aqperson\*(Aq elements
\&  my $h = Data::Stag\->makehandler( person=> sub {
\&                                               my ($self, $person) = @_;
\&                                               printf "name:%s phone:%s\en",
\&                                                 $person\->get_name,
\&                                                 $person\->get_phone;
\&                                               return;   # clear node
\&                                                });
\&  Data::Stag\->parse(\-handler=>$h,
\&                    \-file=>$f);
.Ve
.PP
see Data::Stag::BaseHandler for writing handlers
.PP
See the Stag website at <http://stag.sourceforge.net> for more examples.
.SS "\s-1STRUCTURED TAGS TREE DATA STRUCTURE\s0"
.IX Subsection "STRUCTURED TAGS TREE DATA STRUCTURE"
A tree of structured tags is represented as a recursively nested
array, the elements of the array represent nodes in the tree.
.PP
A node is a name/data pair, that can represent tags and values.  A
node is represented using a reference to an array, where the first
element of the array is the \fBtagname\fR, or \fBelement\fR, and the second
element is the \fBdata\fR
.PP
This can be visualised as a box:
.PP
.Vb 3
\&  +\-\-\-\-\-\-\-\-\-\-\-+
\&  |Name | Data|
\&  +\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
In perl, we represent this pair as a reference to an array
.PP
.Vb 1
\&  [ Name => $Data ]
.Ve
.PP
The \fBData\fR can either be a list of child nodes (subtrees), or a data value.
.PP
The terminal nodes (leafs of the tree) contain data values; this is represented in perl
using primitive scalars.
.PP
For example:
.PP
.Vb 1
\&  [ Name => \*(AqFred\*(Aq ]
.Ve
.PP
For non-terminal nodes, the Data is a reference to an array, where
each element of the the array is a new node.
.PP
.Vb 10
\&  +\-\-\-\-\-\-\-\-\-\-\-+
\&  |Name | Data|
\&  +\-\-\-\-\-\-\-\-\-\-\-+
\&          |||   +\-\-\-\-\-\-\-\-\-\-\-+
\&          ||+\-\->|Name | Data|
\&          ||    +\-\-\-\-\-\-\-\-\-\-\-+
\&          ||    
\&          ||    +\-\-\-\-\-\-\-\-\-\-\-+
\&          |+\-\-\->|Name | Data|
\&          |     +\-\-\-\-\-\-\-\-\-\-\-+
\&          |     
\&          |     +\-\-\-\-\-\-\-\-\-\-\-+
\&          +\-\-\-\->|Name | Data|
\&                +\-\-\-\-\-\-\-\-\-\-\-+
.Ve
.PP
In perl this would be:
.PP
.Vb 6
\&  [ Name => [
\&              [Name1 => $Data1],
\&              [Name2 => $Data2],
\&              [Name3 => $Data3],
\&            ]
\&  ];
.Ve
.PP
The extra level of nesting is required to be able to store any node in
the tree using a single variable. This representation has lots of
advantages over others, eg hashes and mixed hash/array structures.
.SS "\s-1MANIPULATION AND QUERYING\s0"
.IX Subsection "MANIPULATION AND QUERYING"
The following example is taken from biology; we have a list
of species (mouse, human, fly) and a list of genes found in that
species. These are cross-referenced by an identifier called
\&\fBtax_id\fR. We can do a relational-style inner join on this
identifier, as follows \-
.PP
.Vb 10
\&  use Data::Stag qw(:all);
\&  my $tree =
\&  Data::Stag\->new(
\&    \*(Aqdb\*(Aq => [
\&    [ \*(Aqspecies_set\*(Aq => [
\&      [ \*(Aqspecies\*(Aq => [
\&        [ \*(Aqcommon_name\*(Aq => \*(Aqhouse mouse\*(Aq ],
\&        [ \*(Aqbinomial\*(Aq => \*(AqMus musculus\*(Aq ],
\&        [ \*(Aqtax_id\*(Aq => \*(Aq10090\*(Aq ]]],
\&      [ \*(Aqspecies\*(Aq => [
\&        [ \*(Aqcommon_name\*(Aq => \*(Aqfruit fly\*(Aq ],
\&        [ \*(Aqbinomial\*(Aq => \*(AqDrosophila melanogaster\*(Aq ],
\&        [ \*(Aqtax_id\*(Aq => \*(Aq7227\*(Aq ]]],
\&      [ \*(Aqspecies\*(Aq => [
\&        [ \*(Aqcommon_name\*(Aq => \*(Aqhuman\*(Aq ],
\&        [ \*(Aqbinomial\*(Aq => \*(AqHomo sapiens\*(Aq ],
\&        [ \*(Aqtax_id\*(Aq => \*(Aq9606\*(Aq ]]]]],
\&    [ \*(Aqgene_set\*(Aq => [
\&      [ \*(Aqgene\*(Aq => [
\&        [ \*(Aqsymbol\*(Aq => \*(AqHGNC\*(Aq ],
\&        [ \*(Aqtax_id\*(Aq => \*(Aq9606\*(Aq ],
\&        [ \*(Aqphenotype\*(Aq => \*(AqHemochromatosis\*(Aq ],
\&        [ \*(Aqphenotype\*(Aq => \*(AqPorphyria variegata\*(Aq ],
\&        [ \*(AqGO_term\*(Aq => \*(Aqiron homeostasis\*(Aq ],
\&        [ \*(Aqmap\*(Aq => \*(Aq6p21.3\*(Aq ]]],
\&      [ \*(Aqgene\*(Aq => [
\&        [ \*(Aqsymbol\*(Aq => \*(AqHfe\*(Aq ],
\&        [ \*(Aqsynonym\*(Aq => \*(AqMR2\*(Aq ],
\&        [ \*(Aqtax_id\*(Aq => \*(Aq10090\*(Aq ],
\&        [ \*(AqGO_term\*(Aq => \*(Aqintegral membrane protein\*(Aq ],
\&        [ \*(Aqmap\*(Aq => \*(Aq13 A2\-A4\*(Aq ]]]]]]
\&   );
\&
\&  # inner join of species and gene parts of tree,
\&  # based on \*(Aqtax_id\*(Aq element
\&  my $gene_set = $tree\->find("gene_set");       # get <gene_set> element
\&  my $species_set = $tree\->find("species_set"); # get <species_set> element
\&  $gene_set\->ijoin("gene", "tax_id", $species_set);   # INNER JOIN
\&
\&  print "Reorganised data:\en";
\&  print $gene_set\->xml;
\&
\&  # find all genes starting with letter \*(AqH\*(Aq in where species/common_name=human
\&  my @genes =
\&    $gene_set\->where(\*(Aqgene\*(Aq,
\&                     sub { my $g = shift;
\&                           $g\->get_symbol =~ /^H/ &&
\&                           $g\->findval("common_name") eq (\*(Aqhuman\*(Aq)});
\&
\&  print "Human genes beginning \*(AqH\*(Aq\en";
\&  print $_\->xml foreach @genes;
.Ve
.SS "S\-Expression (Lisp) representation"
.IX Subsection "S-Expression (Lisp) representation"
The data represented using this module can be represented as
Lisp-style S\-Expressions.
.PP
See Data::Stag::SxprParser and  Data::Stag::SxprWriter
.PP
If we execute this code on the \s-1XML\s0 from the example above
.PP
.Vb 2
\&  $stag = Data::Stag\->parse($xmlfile);
\&  print $stag\->sxpr;
.Ve
.PP
The following S\-Expression will be printed:
.PP
.Vb 10
\&  \*(Aq(db
\&    (species_set
\&      (species
\&        (common_name "house mouse")
\&        (binomial "Mus musculus")
\&        (tax_id "10090"))
\&      (species
\&        (common_name "fruit fly")
\&        (binomial "Drosophila melanogaster")
\&        (tax_id "7227"))
\&      (species
\&        (common_name "human")
\&        (binomial "Homo sapiens")
\&        (tax_id "9606")))
\&    (gene_set
\&      (gene
\&        (symbol "HGNC")
\&        (tax_id "9606")
\&        (phenotype "Hemochromatosis")
\&        (phenotype "Porphyria variegata")
\&        (GO_term "iron homeostasis")
\&        (map
\&          (cytological
\&            (chromosome "6")
\&            (band "p21.3"))))
\&      (gene
\&        (symbol "Hfe")
\&        (synonym "MR2")
\&        (tax_id "10090")
\&        (GO_term "integral membrane protein")))
\&    (similarity_set
\&      (pair
\&        (symbol "HGNC")
\&        (symbol "Hfe"))
\&      (pair
\&        (symbol "WNT3A")
\&        (symbol "Wnt3a"))))
.Ve
.PP
\fI\s-1TIPS FOR EMACS USERS AND LISP PROGRAMMERS\s0\fR
.IX Subsection "TIPS FOR EMACS USERS AND LISP PROGRAMMERS"
.PP
If you use emacs, you can save this as a file with the \*(L".el\*(R" suffix
and get syntax highlighting for editing this file. Quotes around the
terminal node data items are optional.
.PP
If you know emacs lisp or any other lisp, this also turns out to be a
very nice language for manipulating these datastructures. Try copying
and pasting the above s\-expression to the emacs scratch buffer and
playing with it in lisp.
.SS "\s-1INDENTED TEXT REPRESENTATION\s0"
.IX Subsection "INDENTED TEXT REPRESENTATION"
Data::Stag has its own text format for writing data trees. Again,
this is only possible because we are working with a subset of \s-1XML \s0(no
attributes, no mixed elements). The data structure above can be
written as follows \-
.PP
.Vb 10
\&  db:
\&    species_set:
\&      species:
\&        common_name: house mouse
\&        binomial: Mus musculus
\&        tax_id: 10090
\&      species:
\&        common_name: fruit fly
\&        binomial: Drosophila melanogaster
\&        tax_id: 7227
\&      species:
\&        common_name: human
\&        binomial: Homo sapiens
\&        tax_id: 9606
\&    gene_set:
\&      gene:
\&        symbol: HGNC
\&        tax_id: 9606
\&        phenotype: Hemochromatosis
\&        phenotype: Porphyria variegata
\&        GO_term: iron homeostasis
\&        map: 6p21.3
\&      gene:
\&        symbol: Hfe
\&        synonym: MR2
\&        tax_id: 10090
\&        GO_term: integral membrane protein
\&        map: 13 A2\-A4
\&    similarity_set:
\&      pair:
\&        symbol: HGNC
\&        symbol: Hfe
\&      pair:
\&        symbol: WNT3A
\&        symbol: Wnt3a
.Ve
.PP
See Data::Stag::ITextParser and  Data::Stag::ITextWriter
.SS "\s-1NESTED ARRAY SPECIFICATION II\s0"
.IX Subsection "NESTED ARRAY SPECIFICATION II"
To avoid excessive square bracket usage, you can specify a structure
like this:
.PP
.Vb 1
\&  use Data::Stag qw(:all);
\&  
\&  *N = \e&stag_new;
\&  my $tree =
\&    N(top=>[
\&            N(\*(Aqpersonset\*(Aq=>[
\&                            N(\*(Aqperson\*(Aq=>[
\&                                         N(\*(Aqname\*(Aq=>\*(Aqdavey\*(Aq),
\&                                         N(\*(Aqaddress\*(Aq=>\*(Aqhere\*(Aq),
\&                                         N(\*(Aqdescription\*(Aq=>[
\&                                                           N(\*(Aqhair\*(Aq=>\*(Aqgreen\*(Aq),
\&                                                           N(\*(Aqeyes\*(Aq=>\*(Aqtwo\*(Aq),
\&                                                           N(\*(Aqteeth\*(Aq=>5),
\&                                                          ]
\&                                          ),
\&                                         N(\*(Aqpets\*(Aq=>[
\&                                                    N(\*(Aqpetname\*(Aq=>\*(Aqigor\*(Aq),
\&                                                    N(\*(Aqpetname\*(Aq=>\*(Aqginger\*(Aq),
\&                                                   ]
\&                                          ),
\&                                                                          
\&                                        ],
\&                             ),
\&                            N(\*(Aqperson\*(Aq=>[
\&                                         N(\*(Aqname\*(Aq=>\*(Aqshuggy\*(Aq),
\&                                         N(\*(Aqaddress\*(Aq=>\*(Aqthere\*(Aq),
\&                                         N(\*(Aqdescription\*(Aq=>[
\&                                                           N(\*(Aqhair\*(Aq=>\*(Aqred\*(Aq),
\&                                                           N(\*(Aqeyes\*(Aq=>\*(Aqthree\*(Aq),
\&                                                           N(\*(Aqteeth\*(Aq=>1),
\&                                                          ]
\&                                          ),
\&                                         N(\*(Aqpets\*(Aq=>[
\&                                                    N(\*(Aqpetname\*(Aq=>\*(Aqthud\*(Aq),
\&                                                    N(\*(Aqpetname\*(Aq=>\*(Aqspud\*(Aq),
\&                                                   ]
\&                                          ),
\&                                        ]
\&                             ),
\&                           ]
\&             ),
\&            N(\*(Aqanimalset\*(Aq=>[
\&                            N(\*(Aqanimal\*(Aq=>[
\&                                         N(\*(Aqname\*(Aq=>\*(Aqigor\*(Aq),
\&                                         N(\*(Aqclass\*(Aq=>\*(Aqrat\*(Aq),
\&                                         N(\*(Aqdescription\*(Aq=>[
\&                                                           N(\*(Aqfur\*(Aq=>\*(Aqwhite\*(Aq),
\&                                                           N(\*(Aqeyes\*(Aq=>\*(Aqred\*(Aq),
\&                                                           N(\*(Aqteeth\*(Aq=>50),
\&                                                          ],
\&                                          ),
\&                                        ],
\&                             ),
\&                           ]
\&             ),
\&
\&           ]
\&     );
\&
\&  # find all people
\&  my @persons = stag_find($tree, \*(Aqperson\*(Aq);
\&
\&  # write xml for all red haired people
\&  foreach my $p (@persons) {
\&    print stag_xml($p)
\&      if stag_tmatch($p, "hair", "red");
\&  } ;
\&
\&  # find all people that have name == shuggy
\&  my @p =
\&    stag_qmatch($tree, 
\&                "person",
\&                "name",
\&                "shuggy");
.Ve
.SH "NODES AS DATA OBJECTS"
.IX Header "NODES AS DATA OBJECTS"
As well as the methods listed below, a node can be treated as if it is
a data object of a class determined by the element.
.PP
For example, the following are equivalent.
.PP
.Vb 2
\&  $node\->get_name;
\&  $node\->get(\*(Aqname\*(Aq);
\&
\&  $node\->set_name(\*(Aqfred\*(Aq);
\&  $node\->set(\*(Aqname\*(Aq, \*(Aqfred\*(Aq);
.Ve
.PP
This is really just syntactic sugar. The autoloaded methods are not
checked against any schema, although this may be added in future.
.SH "INDEXING STAG TREES"
.IX Header "INDEXING STAG TREES"
A stag tree can be indexed as a hash for direct retrieval; see
Data::Stag::HashDB
.PP
This index can be made persistent as a \s-1DB\s0 file; see
Data::Stag::StagDB
.PP
If you wish to use Stag in conjunction with a relational database, you
should install DBIx::DBStag
.SH "STAG METHODS"
.IX Header "STAG METHODS"
All method calls are also available as procedural subroutine calls;
unless otherwise noted, the subroutine call is the same as the method
call, but with the string \fBstag_\fR prefixed to the method name. The
first argument should be a Data::Stag datastructure.
.PP
To import all subroutines into the current namespace, use this idiom:
.PP
.Vb 3
\&  use Data::Stag qw(:all);
\&  $doc = stag_parse($file);
\&  @persons = stag_find($doc, \*(Aqperson\*(Aq);
.Ve
.PP
If you wish to use this module procedurally, and you are too lazy to
prefix all calls with \fBstag_\fR, use this idiom:
.PP
.Vb 3
\&  use Data::Stag qw(:lazy);
\&  $doc = parse($file);
\&  @persons = find($doc, \*(Aqperson\*(Aq);
.Ve
.PP
But beware of clashes!
.PP
Most method calls also have a handy short mnemonic. Use of these is
optional. Software engineering types prefer longer names, in the
belief that this leads to clearer code. Hacker types prefer shorter
names, as this requires less keystrokes, and leads to a more compact
representation of the code. It is expected that if you do use this
module, then its usage will be fairly ubiquitous within your code, and
the mnemonics will become familiar, much like the qw and s/ operators
in perl. As always with perl, the decision is yours.
.PP
Some methods take a single parameter or list of parameters; some have
large lists of parameters that can be passed in any order. If the
documentation states:
.PP
.Vb 1
\&  Args: [x str], [y int], [z ANY]
.Ve
.PP
Then the method can be called like this:
.PP
.Vb 1
\&  $stag\->foo("this is x", 55, $ref);
.Ve
.PP
or like this:
.PP
.Vb 1
\&  $stag\->foo(\-z=>$ref, \-x=>"this is x", \-y=>55);
.Ve
.SS "\s-1INITIALIZATION METHODS\s0"
.IX Subsection "INITIALIZATION METHODS"
\fInew\fR
.IX Subsection "new"
.PP
.Vb 1
\&       Title: new
\&
\&        Args: element str, data STAG\-DATA
\&     Returns: Data::Stag node
\&     Example: $node = stag_new();
\&     Example: $node = Data::Stag\->new;
\&     Example: $node = Data::Stag\->new(person => [[name=>$n], [phone=>$p]]);
.Ve
.PP
creates a new instance of a Data::Stag node
.PP
\fIstagify (nodify)\fR
.IX Subsection "stagify (nodify)"
.PP
.Vb 5
\&       Title: stagify
\&     Synonym: nodify
\&        Args: data ARRAY\-REF
\&     Returns: Data::Stag node
\&     Example: $node = stag_stagify([person => [[name=>$n], [phone=>$p]]]);
.Ve
.PP
turns a perl array reference into a Data::Stag node.
.PP
similar to \fBnew\fR
.PP
\fIparse\fR
.IX Subsection "parse"
.PP
.Vb 1
\&       Title: parse
\&
\&        Args: [file str], [format str], [handler obj], [fh FileHandle]
\&     Returns: Data::Stag node
\&     Example: $node = stag_parse($fn);
\&     Example: $node = stag_parse(\-fh=>$fh, \-handler=>$h, \-errhandler=>$eh);
\&     Example: $node = Data::Stag\->parse(\-file=>$fn, \-handler=>$myhandler);
.Ve
.PP
slurps a file or string into a Data::Stag node structure. Will guess
the format (xml, sxpr, itext, indent) from the suffix if it is not given.
.PP
The format can also be the name of a parsing module, or an actual
parser object;
.PP
The handler is any object that can take nested Stag events
(start_event, end_event, evbody) which are generated from the
parse. If the handler is omitted, all events will be cached and the
resulting tree will be returned.
.PP
See Data::Stag::BaseHandler for writing your own handlers
.PP
See Data::Stag::BaseGenerator for details on parser classes, and
error handling
.PP
\fIparsestr\fR
.IX Subsection "parsestr"
.PP
.Vb 1
\&       Title: parsestr
\&
\&        Args: [str str], [format str], [handler obj]
\&     Returns: Data::Stag node
\&     Example: $node = stag_parsestr(\*(Aq(a (b (c "1")))\*(Aq);
\&     Example: $node = Data::Stag\->parsestr(\-str=>$str, \-handler=>$myhandler);
.Ve
.PP
Similar to \fIparse()\fR, except the first argument is a string
.PP
\fIfrom\fR
.IX Subsection "from"
.PP
.Vb 1
\&       Title: from
\&
\&        Args: format str, source str
\&     Returns: Data::Stag node
\&     Example: $node = stag_from(\*(Aqxml\*(Aq, $fn);
\&     Example: $node = stag_from(\*(Aqxmlstr\*(Aq, q[<top><x>1</x></top>]);
\&     Example: $node = Data::Stag\->from($parser, $fn);
.Ve
.PP
Similar to \fBparse\fR
.PP
slurps a file or string into a Data::Stag node structure.
.PP
The format can also be the name of a parsing module, or an actual
parser object
.PP
\fIunflatten\fR
.IX Subsection "unflatten"
.PP
.Vb 1
\&       Title: unflatten
\&
\&        Args: data array
\&     Returns: Data::Stag node
\&     Example: $node = stag_unflatten(person=>[name=>$n, phone=>$p, address=>[street=>$s, city=>$c]]);
.Ve
.PP
Creates a node structure from a semi-flattened representation, in
which children of a node are represented as a flat list of data rather
than a list of array references.
.PP
This means a structure can be specified as:
.PP
.Vb 4
\&  person=>[name=>$n,
\&           phone=>$p, 
\&           address=>[street=>$s, 
\&                     city=>$c]]
.Ve
.PP
Instead of:
.PP
.Vb 6
\&  [person=>[ [name=>$n],
\&             [phone=>$p], 
\&             [address=>[ [street=>$s], 
\&                         [city=>$c] ] ]
\&           ]
\&  ]
.Ve
.PP
The former gets converted into the latter for the internal representation
.PP
\fImakehandler\fR
.IX Subsection "makehandler"
.PP
.Vb 1
\&       Title: makehandler
\&
\&        Args: hash of CODEREFs keyed by element name
\&              OR a string containing the name of a module
\&     Returns: L<Data::Stag::BaseHandler>
\&     Example: $h = Data::Stag\->makehandler(%subs);
\&     Example: $h = Data::Stag\->makehandler("My::FooHandler");
\&     Example: $h = Data::Stag\->makehandler(\*(Aqxml\*(Aq);
.Ve
.PP
This creates a Stag event handler. The argument is a hash of
subroutines keyed by element/node name. After each node is fired by
the parser/generator, the subroutine is called, passing the handler
object and the stag node as arguments. whatever the subroutine returns
is placed back into the tree
.PP
For example, for a a parser/generator that fires events with the
following tree form
.PP
.Vb 4
\&  <person>
\&    <name>foo</name>
\&    ...
\&  </person>
.Ve
.PP
we can create a handler that writes person/name like this:
.PP
.Vb 6
\&  $h = Data::Stag\->makehandler(
\&                               person => sub { my ($self,$stag) = @_;
\&                                               print $stag\->name;
\&                                               return $stag; # don\*(Aqt change tree
\&                                             });
\&  $stag = Data::Stag\->parse(\-str=>"(...)", \-handler=>$h)
.Ve
.PP
See Data::Stag::BaseHandler for details on handlers
.PP
\fIgetformathandler\fR
.IX Subsection "getformathandler"
.PP
.Vb 1
\&       Title: getformathandler
\&
\&        Args: format str OR L<Data::Stag::BaseHandler>
\&     Returns: L<Data::Stag::BaseHandler>
\&     Example: $h = Data::Stag\->getformathandler(\*(Aqxml\*(Aq);
\&              $h\->file("my.xml");
\&              Data::Stag\->parse(\-fn=>$fn, \-handler=>$h);
.Ve
.PP
Creates a Stag event handler \- this handler can be passed to an event
generator / parser. Built in handlers include:
.IP "xml" 4
.IX Item "xml"
Generates xml tags from events
.IP "sxpr" 4
.IX Item "sxpr"
Generates S\-Expressions from events
.IP "itext" 4
.IX Item "itext"
Generates itext format from events
.IP "indent" 4
.IX Item "indent"
Generates indent format from events
.PP
All the above are kinds of Data::Stag::Writer
.PP
\fIchainhandler\fR
.IX Subsection "chainhandler"
.PP
.Vb 1
\&       Title: chainhandler
\&
\&        Args: blocked events \- str or str[]
\&              initial handler \- handler object
\&              final handler \- handler object
\&     Returns: 
\&     Example: $h = Data::Stag\->chainhandler(\*(Aqfoo\*(Aq, $processor, \*(Aqxml\*(Aq)
.Ve
.PP
chains handlers together \- for example, you may want to make
transforms on an event stream, and then pass the event stream to
another handler \- for example, and xml handler
.PP
.Vb 12
\&  $processor = Data::Stag\->makehandler(
\&                                       a => sub { my ($self,$stag) = @_;
\&                                                  $stag\->set_foo("bar");
\&                                                  return $stag
\&                                                },
\&                                       b => sub { my ($self,$stag) = @_;
\&                                                  $stag\->set_blah("eek");
\&                                                  return $stag
\&                                                },
\&                                       );
\&  $chainh = Data::Stag\->chainhandler([\*(Aqa\*(Aq, \*(Aqb\*(Aq], $processor, \*(Aqxml\*(Aq);
\&  $stag = Data::Stag\->parse(\-str=>"(...)", \-handler=>$chainh)
.Ve
.PP
If the inner handler has a method \s-1\fICONSUMES\s0()\fR, this method will
determine the blocked events if none are specified.
.PP
see also the script \fBstag\-handle.pl\fR
.SS "\s-1RECURSIVE SEARCHING\s0"
.IX Subsection "RECURSIVE SEARCHING"
\fIfind (f)\fR
.IX Subsection "find (f)"
.PP
.Vb 2
\&       Title: find
\&     Synonym: f
\&
\&        Args: element str
\&     Returns: node[] or ANY
\&     Example: @persons = stag_find($struct, \*(Aqperson\*(Aq);
\&     Example: @persons = $struct\->find(\*(Aqperson\*(Aq);
.Ve
.PP
recursively searches tree for all elements of the given type, and
returns all nodes or data elements found.
.PP
if the element found is a non-terminal node, will return the node
if the element found is a terminal (leaf) node, will return the data value
.PP
the element argument can be a path
.PP
.Vb 1
\&  @names = $struct\->find(\*(Aqdepartment/person/name\*(Aq);
.Ve
.PP
will find name in the nested structure below:
.PP
.Vb 3
\&  (department
\&   (person
\&    (name "foo")))
.Ve
.PP
\fIfindnode (fn)\fR
.IX Subsection "findnode (fn)"
.PP
.Vb 2
\&       Title: findnode
\&     Synonym: fn
\&
\&        Args: element str
\&     Returns: node[]
\&     Example: @persons = stag_findnode($struct, \*(Aqperson\*(Aq);
\&     Example: @persons = $struct\->findnode(\*(Aqperson\*(Aq);
.Ve
.PP
recursively searches tree for all elements of the given type, and
returns all nodes found.
.PP
paths can also be used (see \fBfind\fR)
.PP
\fIfindval (fv)\fR
.IX Subsection "findval (fv)"
.PP
.Vb 2
\&       Title: findval
\&     Synonym: fv
\&
\&        Args: element str
\&     Returns: ANY[] or ANY
\&     Example: @names = stag_findval($struct, \*(Aqname\*(Aq);
\&     Example: @names = $struct\->findval(\*(Aqname\*(Aq);
\&     Example: $firstname = $struct\->findval(\*(Aqname\*(Aq);
.Ve
.PP
recursively searches tree for all elements of the given type, and
returns all data values found. the data values could be primitive
scalars or nodes.
.PP
paths can also be used (see \fBfind\fR)
.PP
\fIsfindval (sfv)\fR
.IX Subsection "sfindval (sfv)"
.PP
.Vb 2
\&       Title: sfindval
\&     Synonym: sfv
\&
\&        Args: element str
\&     Returns: ANY
\&     Example: $name = stag_sfindval($struct, \*(Aqname\*(Aq);
\&     Example: $name = $struct\->sfindval(\*(Aqname\*(Aq);
.Ve
.PP
as findval, but returns the first value found
.PP
paths can also be used (see \fBfind\fR)
.PP
\fIfindvallist (fvl)\fR
.IX Subsection "findvallist (fvl)"
.PP
.Vb 2
\&       Title: findvallist
\&     Synonym: fvl
\&
\&        Args: element str[]
\&     Returns: ANY[]
\&     Example: ($name, $phone) = stag_findvallist($personstruct, \*(Aqname\*(Aq, \*(Aqphone\*(Aq);
\&     Example: ($name, $phone) = $personstruct\->findvallist(\*(Aqname\*(Aq, \*(Aqphone\*(Aq);
.Ve
.PP
recursively searches tree for all elements in the list
.PP
\&\s-1DEPRECATED\s0
.SS "\s-1DATA ACCESSOR METHODS\s0"
.IX Subsection "DATA ACCESSOR METHODS"
these allow getting and setting of elements directly underneath the
current one
.PP
\fIget (g)\fR
.IX Subsection "get (g)"
.PP
.Vb 2
\&       Title: get
\&     Synonym: g
\&
\&        Args: element str
\&      Return: node[] or ANY
\&     Example: $name = $person\->get(\*(Aqname\*(Aq);
\&     Example: @phone_nos = $person\->get(\*(Aqphone_no\*(Aq);
.Ve
.PP
gets the value of the named sub-element
.PP
if the sub-element is a non-terminal, will return a node(s)
if the sub-element is a terminal (leaf) it will return the data value(s)
.PP
the examples above would work on a data structure like this:
.PP
.Vb 3
\&  [person => [ [name => \*(Aqfred\*(Aq],
\&               [phone_no => \*(Aq1\-800\-111\-2222\*(Aq],
\&               [phone_no => \*(Aq1\-415\-555\-5555\*(Aq]]]
.Ve
.PP
will return an array or single value depending on the context
.PP
[equivalent to \fIfindval()\fR, except that only direct children (as
opposed to all descendents) are checked]
.PP
paths can also be used, like this:
.PP
.Vb 1
\& @phones_nos = $struct\->get(\*(Aqperson/phone_no\*(Aq)
.Ve
.PP
\fIsget (sg)\fR
.IX Subsection "sget (sg)"
.PP
.Vb 2
\&       Title: sget
\&     Synonym: sg
\&
\&        Args: element str
\&      Return: ANY
\&     Example: $name = $person\->sget(\*(Aqname\*(Aq);
\&     Example: $phone = $person\->sget(\*(Aqphone_no\*(Aq);
\&     Example: $phone = $person\->sget(\*(Aqdepartment/person/name\*(Aq);
.Ve
.PP
as \fBget\fR but always returns a single value
.PP
[equivalent to \fIsfindval()\fR, except that only direct children (as
opposed to all descendents) are checked]
.PP
\fIgetl (gl getlist)\fR
.IX Subsection "getl (gl getlist)"
.PP
.Vb 3
\&       Title: gl
\&     Synonym: getl
\&     Synonym: getlist
\&
\&        Args: element str[]
\&      Return: node[] or ANY[]
\&     Example: ($name, @phone) = $person\->getl(\*(Aqname\*(Aq, \*(Aqphone_no\*(Aq);
.Ve
.PP
returns the data values for a list of sub-elements of a node
.PP
[equivalent to \fIfindvallist()\fR, except that only direct children (as
opposed to all descendents) are checked]
.PP
\fIgetn (gn getnode)\fR
.IX Subsection "getn (gn getnode)"
.PP
.Vb 3
\&       Title: getn
\&     Synonym: gn
\&     Synonym: getnode
\&
\&        Args: element str
\&      Return: node[]
\&     Example: $namestruct = $person\->getn(\*(Aqname\*(Aq);
\&     Example: @pstructs = $person\->getn(\*(Aqphone_no\*(Aq);
.Ve
.PP
as \fBget\fR but returns the whole node rather than just the data value
.PP
[equivalent to \fIfindnode()\fR, except that only direct children (as
opposed to all descendents) are checked]
.PP
\fIsgetmap (sgm)\fR
.IX Subsection "sgetmap (sgm)"
.PP
.Vb 2
\&       Title: sgetmap
\&     Synonym: sgm
\&
\&        Args: hash
\&      Return: hash
\&     Example: %h = $person\->sgetmap(\*(Aqsocial\-security\-no\*(Aq=>\*(Aqid\*(Aq, 
\&                                    \*(Aqname\*(Aq              =>\*(Aqlabel\*(Aq,
\&                                    \*(Aqjob\*(Aq               =>0,
\&                                    \*(Aqaddress\*(Aq           =>\*(Aqlocation\*(Aq);
.Ve
.PP
returns a hash of key/val pairs based on the values of the data values
of the subnodes in the current element; keys are mapped according to
the hash passed (a value of '' or 0 will map an identical key/val).
.PP
no multivalued data elements are allowed
.PP
\fIset (s)\fR
.IX Subsection "set (s)"
.PP
.Vb 2
\&       Title: set
\&     Synonym: s
\&
\&        Args: element str, datavalue ANY (list)
\&      Return: ANY
\&     Example: $person\->set(\*(Aqname\*(Aq, \*(Aqfred\*(Aq);    # single val
\&     Example: $person\->set(\*(Aqphone_no\*(Aq, $cellphone, $homephone);
.Ve
.PP
sets the data value of an element for any node. if the element is
multivalued, all the old values will be replaced with the new ones
specified.
.PP
ordering will be preserved, unless the element specified does not
exist, in which case, the new tag/value pair will be placed at the
end.
.PP
for example, if we have a stag node \f(CW$person\fR
.PP
.Vb 3
\&  person:
\&    name: shuggy
\&    job:  bus driver
.Ve
.PP
if we do this
.PP
.Vb 1
\&  $person\->set(\*(Aqname\*(Aq, ());
.Ve
.PP
we will end up with
.PP
.Vb 2
\&  person:
\&    job:  bus driver
.Ve
.PP
then if we do this
.PP
.Vb 1
\&  $person\->set(\*(Aqname\*(Aq, \*(Aqshuggy\*(Aq);
.Ve
.PP
the 'name' node will be placed as the last attribute
.PP
.Vb 3
\&  person:
\&    job:  bus driver
\&    name: shuggy
.Ve
.PP
You can also use \fBmagic methods\fR, for example
.PP
.Vb 3
\&  $person\->set_name(\*(Aqshuggy\*(Aq);
\&  $person\->set_job(\*(Aqbus driver\*(Aq, \*(Aqpoet\*(Aq);
\&  print $person\->itext;
.Ve
.PP
will print
.PP
.Vb 4
\&  person:
\&    name: shuggy
\&    job:  bus driver
\&    job:  poet
.Ve
.PP
note that if the datavalue is a non-terminal node as opposed to a
primitive value, then you have to do it like this:
.PP
.Vb 10
\&  $people  = Data::Stag\->new(people=>[
\&                                      [person=>[[name=>\*(AqSherlock Holmes\*(Aq]]],
\&                                      [person=>[[name=>\*(AqMoriarty\*(Aq]]],
\&                                     ]);
\&  $address = Data::Stag\->new(address=>[
\&                                       [address_line=>"221B Baker Street"],
\&                                       [city=>"London"],
\&                                       [country=>"Great Britain"]]);
\&  ($person) = $people\->qmatch(\*(Aqperson\*(Aq, (name => "Sherlock Holmes"));
\&  $person\->set("address", $address\->data);
.Ve
.PP
If you are using \s-1XML\s0 data, you can set attributes like this:
.PP
.Vb 1
\&  $person\->set(\*(Aq@\*(Aq=>[[id=>$id],[foo=>$foo]]);
.Ve
.PP
\fIunset (u)\fR
.IX Subsection "unset (u)"
.PP
.Vb 2
\&       Title: unset
\&     Synonym: u
\&
\&        Args: element str, datavalue ANY
\&      Return: ANY
\&     Example: $person\->unset(\*(Aqname\*(Aq);
\&     Example: $person\->unset(\*(Aqphone_no\*(Aq);
.Ve
.PP
prunes all nodes of the specified element from the current node
.PP
You can use \fBmagic methods\fR, like this
.PP
.Vb 2
\&  $person\->unset_name;
\&  $person\->unset_phone_no;
.Ve
.PP
\fIfree\fR
.IX Subsection "free"
.PP
.Vb 2
\&       Title: free
\&     Synonym: u
\&
\&        Args: 
\&      Return: 
\&     Example: $person\->free;
.Ve
.PP
removes all data from a node. If that node is a subnode of another
node, it is removed altogether
.PP
for instance, if we had the data below:
.PP
.Vb 6
\&  <person>
\&    <name>fred</name>
\&    <address>
\&    ..
\&    </address>
\&  </person>
.Ve
.PP
and called
.PP
.Vb 1
\&  $person\->get_address\->free
.Ve
.PP
then the person node would look like this:
.PP
.Vb 3
\&  <person>
\&    <name>fred</name>
\&  </person>
.Ve
.PP
\fIadd (a)\fR
.IX Subsection "add (a)"
.PP
.Vb 2
\&       Title: add
\&     Synonym: a
\&
\&        Args: element str, datavalues ANY[]
\&              OR
\&              Data::Stag
\&      Return: ANY
\&     Example: $person\->add(\*(Aqphone_no\*(Aq, $cellphone, $homephone);
\&     Example: $person\->add_phone_no(\*(Aq1\-555\-555\-5555\*(Aq);
\&     Example: $dataset\->add($person)
.Ve
.PP
adds a datavalue or list of datavalues. appends if already existing,
creates new element value pairs if not already existing.
.PP
if the argument is a stag node, it will add this node under the
current one.
.PP
For example, if we have the following node in \f(CW$dataset\fR
.PP
.Vb 5
\& <dataset>
\&   <person>
\&     <name>jim</name>
\&   </person>
\& </dataset>
.Ve
.PP
And then we add data to it:
.PP
.Vb 2
\&  ($person) = $dataset\->qmatch(\*(Aqperson\*(Aq, name=>\*(Aqjim\*(Aq);
\&  $person\->add(\*(Aqphone_no\*(Aq, \*(Aq555\-1111\*(Aq, \*(Aq555\-2222\*(Aq);
.Ve
.PP
We will be left with:
.PP
.Vb 7
\& <dataset>
\&   <person>
\&     <name>jim</name>
\&     <phone_no>555\-1111</phone_no>
\&     <phone_no>555\-2222</phone_no>
\&   </person>
\& </dataset>
.Ve
.PP
The above call is equivalent to:
.PP
.Vb 1
\&  $person\->add_phone_no(\*(Aq555\-1111\*(Aq, \*(Aq555\-2222\*(Aq);
.Ve
.PP
As well as adding data values, we can add whole nodes:
.PP
.Vb 2
\&  $dataset\->add(person=>[[name=>"fred"],
\&                         [phone_no=>"555\-3333"]]);
.Ve
.PP
Which is equivalent to
.PP
.Vb 2
\&  $dataset\->add_person([[name=>"fred"],
\&                        [phone_no=>"555\-3333"]]);
.Ve
.PP
Remember, the value has to be specified as an array reference of
nodes. In general, you should use the \fIaddkid()\fR method to add nodes and
used \fIadd()\fR to add values
.PP
\fIelement (e name)\fR
.IX Subsection "element (e name)"
.PP
.Vb 3
\&       Title: element
\&     Synonym: e
\&     Synonym: name
\&
\&        Args:
\&      Return: element str
\&     Example: $element = $struct\->element
.Ve
.PP
returns the \fBelement name\fR of the current node.
.PP
This is illustrated in the different representation formats below
.IP "sxpr" 4
.IX Item "sxpr"
.Vb 1
\&  (element "data")
.Ve
.Sp
or
.Sp
.Vb 2
\&  (element
\&   (sub_element "..."))
.Ve
.IP "xml" 4
.IX Item "xml"
.Vb 1
\&  <element>data</element>
.Ve
.Sp
or
.Sp
.Vb 3
\&  <element>
\&    <sub_element>...</sub_element>
\&  </element>
.Ve
.IP "perl" 4
.IX Item "perl"
.Vb 1
\&  [element => $data ]
.Ve
.Sp
or
.Sp
.Vb 2
\&  [element => [
\&                [sub_element => "..." ]]]
.Ve
.IP "itext" 4
.IX Item "itext"
.Vb 1
\&  element: data
.Ve
.Sp
or
.Sp
.Vb 2
\&  element:
\&    sub_element: ...
.Ve
.IP "indent" 4
.IX Item "indent"
.Vb 1
\&  element "data"
.Ve
.Sp
or
.Sp
.Vb 2
\&  element
\&    sub_element "..."
.Ve
.PP
\fIkids (k children)\fR
.IX Subsection "kids (k children)"
.PP
.Vb 3
\&       Title: kids
\&     Synonym: k
\&     Synonym: children
\&
\&        Args:
\&      Return: ANY or ANY[]
\&     Example: @nodes = $person\->kids
\&     Example: $name = $namestruct\->kids
.Ve
.PP
returns the data value(s) of the current node; if it is a terminal
node, returns a single value which is the data. if it is non-terminal,
returns an array of nodes
.PP
\fIaddkid (ak addchild)\fR
.IX Subsection "addkid (ak addchild)"
.PP
.Vb 3
\&       Title: addkid
\&     Synonym: ak
\&     Synonym: addchild
\&
\&        Args: kid node
\&      Return: ANY
\&     Example: $person\->addkid($job);
.Ve
.PP
adds a new child node to a non-terminal node, after all the existing
child nodes
.PP
You can use this method/procedure to add \s-1XML\s0 attribute data to a node:
.PP
.Vb 1
\&  $person\->addkid([\*(Aq@\*(Aq=>[[id=>$id]]]);
.Ve
.PP
\fIsubnodes\fR
.IX Subsection "subnodes"
.PP
.Vb 1
\&       Title: subnodes
\&
\&        Args: 
\&      Return: ANY[]
\&     Example: @nodes = $person\->subnodes
.Ve
.PP
returns the child nodes; returns empty list if this is a terminal node
.PP
\fIntnodes\fR
.IX Subsection "ntnodes"
.PP
.Vb 1
\&       Title: ntnodes
\&
\&        Args: 
\&      Return: ANY[]
\&     Example: @nodes = $person\->ntnodes
.Ve
.PP
returns all non-terminal children of current node
.PP
\fItnodes\fR
.IX Subsection "tnodes"
.PP
.Vb 1
\&       Title: tnodes
\&
\&        Args: 
\&      Return: ANY[]
\&     Example: @nodes = $person\->tnodes
.Ve
.PP
returns all terminal children of current node
.SS "\s-1QUERYING AND ADVANCED DATA MANIPULATION\s0"
.IX Subsection "QUERYING AND ADVANCED DATA MANIPULATION"
\fIijoin (j)\fR
.IX Subsection "ijoin (j)"
.PP
.Vb 3
\&       Title: ijoin
\&     Synonym: j
\&     Synonym: ij
\&
\&        Args: element str, key str, data Node
\&      Return: undef
.Ve
.PP
does a relational style inner join \- see previous example in this doc
.PP
key can either be a single node name that must be shared (analogous to
\&\s-1SQL INNER JOIN .. USING\s0), or a key1=key2 equivalence relation
(analogous to \s-1SQL INNER JOIN ... ON\s0)
.PP
\fIqmatch (qm)\fR
.IX Subsection "qmatch (qm)"
.PP
.Vb 2
\&       Title: qmatch
\&     Synonym: qm
\&
\&        Args: return\-element str, match\-element str, match\-value str
\&      Return: node[]
\&     Example: @persons = $s\->qmatch(\*(Aqperson\*(Aq, \*(Aqname\*(Aq, \*(Aqfred\*(Aq);
\&     Example: @persons = $s\->qmatch(\*(Aqperson\*(Aq, (job=>\*(Aqbus driver\*(Aq));
.Ve
.PP
queries the node tree for all elements that satisfy the specified
key=val match \- see previous example in this doc
.PP
for those inclined to thinking relationally, this can be thought of
as a query that returns a stag object:
.PP
.Vb 1
\&  SELECT <return\-element> FROM <stag\-node> WHERE <match\-element> = <match\-value>
.Ve
.PP
this always returns an array; this means that calling in a scalar
context will return the number of elements; for example
.PP
.Vb 1
\&  $n = $s\->qmatch(\*(Aqperson\*(Aq, (name=>\*(Aqfred\*(Aq));
.Ve
.PP
the value of \f(CW$n\fR will be equal to the number of persons called fred
.PP
\fItmatch (tm)\fR
.IX Subsection "tmatch (tm)"
.PP
.Vb 2
\&       Title: tmatch
\&     Synonym: tm
\&
\&        Args: element str, value str
\&      Return: bool
\&     Example: @persons = grep {$_\->tmatch(\*(Aqname\*(Aq, \*(Aqfred\*(Aq)} @persons
.Ve
.PP
returns true if the the value of the specified element matches \- see
previous example in this doc
.PP
\fItmatchhash (tmh)\fR
.IX Subsection "tmatchhash (tmh)"
.PP
.Vb 2
\&       Title: tmatchhash
\&     Synonym: tmh
\&
\&        Args: match hashref
\&      Return: bool
\&     Example: @persons = grep {$_\->tmatchhash({name=>\*(Aqfred\*(Aq, hair_colour=>\*(Aqgreen\*(Aq})} @persons
.Ve
.PP
returns true if the node matches a set of constraints, specified as
hash.
.PP
\fItmatchnode (tmn)\fR
.IX Subsection "tmatchnode (tmn)"
.PP
.Vb 2
\&       Title: tmatchnode
\&     Synonym: tmn
\&
\&        Args: match node
\&      Return: bool
\&     Example: @persons = grep {$_\->tmatchnode([person=>[[name=>\*(Aqfred\*(Aq], [hair_colour=>\*(Aqgreen\*(Aq]]])} @persons
.Ve
.PP
returns true if the node matches a set of constraints, specified as node
.PP
\fIcmatch (cm)\fR
.IX Subsection "cmatch (cm)"
.PP
.Vb 2
\&       Title: cmatch
\&     Synonym: cm
\&
\&        Args: element str, value str
\&      Return: bool
\&     Example: $n_freds = $personset\->cmatch(\*(Aqname\*(Aq, \*(Aqfred\*(Aq);
.Ve
.PP
counts the number of matches
.PP
\fIwhere (w)\fR
.IX Subsection "where (w)"
.PP
.Vb 2
\&       Title: where
\&     Synonym: w
\&
\&        Args: element str, test CODE
\&      Return: Node[]
\&     Example: @rich_persons = $data\->where(\*(Aqperson\*(Aq, sub {shift\->get_salary > 100000});
.Ve
.PP
the tree is queried for all elements of the specified type that
satisfy the coderef (must return a boolean)
.PP
.Vb 6
\&  my @rich_dog_or_cat_owners =
\&    $data\->where(\*(Aqperson\*(Aq,
\&                 sub {my $p = shift;
\&                      $p\->get_salary > 100000 &&
\&                      $p\->where(\*(Aqpet\*(Aq,
\&                                sub {shift\->get_type =~ /(dog|cat)/})});
.Ve
.PP
\fIiterate (i)\fR
.IX Subsection "iterate (i)"
.PP
.Vb 2
\&       Title: iterate
\&     Synonym: i
\&
\&        Args: CODE
\&      Return: Node[]
\&     Example: $data\->iterate(sub {
\&                                 my $stag = shift;
\&                                 my $parent = shift;
\&                                 if ($stag\->element eq \*(Aqpet\*(Aq) {
\&                                     $parent\->set_pet_name($stag\->get_name);
\&                                 }
\&                             });
.Ve
.PP
iterates through whole tree calling the specified subroutine.
.PP
the first arg passed to the subroutine is the stag node representing
the tree at that point; the second arg is for the parent.
.PP
for instance, the example code above would turn this
.PP
.Vb 4
\&  (person
\&   (name "jim")
\&   (pet
\&    (name "fluffy")))
.Ve
.PP
into this
.PP
.Vb 5
\&  (person
\&   (name "jim")
\&   (pet_name "fluffy")
\&   (pet
\&    (name "fluffy")))
.Ve
.PP
\fImaptree\fR
.IX Subsection "maptree"
.PP
.Vb 1
\&       Title: maptree
\&
\&        Args: CODE
\&      Return: Node[]
\&     Example: $data\->maptree(sub {
\&                                 my $stag = shift;
\&                                 my $parent = shift;
\&                                 if ($stag\->element eq \*(Aqpet\*(Aq) {
\&                                     [pet=>$stag\->sget_foo]
\&                                 }
\&                                 else {
\&                                     $stag
\&                                 }
\&                             });
.Ve
.SS "\s-1MISCELLANEOUS METHODS\s0"
.IX Subsection "MISCELLANEOUS METHODS"
\fIduplicate (d)\fR
.IX Subsection "duplicate (d)"
.PP
.Vb 2
\&       Title: duplicate
\&     Synonym: d
\&
\&        Args:
\&      Return: Node
\&     Example: $node2 = $node\->duplicate;
.Ve
.PP
does a deep copy of a stag structure
.PP
\fIisanode\fR
.IX Subsection "isanode"
.PP
.Vb 1
\&       Title: isanode
\&
\&        Args:
\&      Return: bool
\&     Example: if (stag_isanode($node)) { ... }
.Ve
.PP
\fIhash\fR
.IX Subsection "hash"
.PP
.Vb 1
\&       Title: hash
\&
\&        Args:
\&      Return: hash
\&     Example: $h = $node\->hash;
.Ve
.PP
turns a tree into a hash. all data values will be arrayrefs
.PP
\fIpairs\fR
.IX Subsection "pairs"
.PP
.Vb 1
\&       Title: pairs
.Ve
.PP
turns a tree into a hash. all data values will be scalar (\s-1IMPORTANT:\s0
this means duplicate values will be lost)
.PP
\fIwrite\fR
.IX Subsection "write"
.PP
.Vb 1
\&       Title: write
\&
\&        Args: filename str, format str[optional]
\&      Return:
\&     Example: $node\->write("myfile.xml");
\&     Example: $node\->write("myfile", "itext");
.Ve
.PP
will try and guess the format from the extension if not specified
.PP
\fIxml\fR
.IX Subsection "xml"
.PP
.Vb 1
\&       Title: xml
\&
\&        Args: filename str, format str[optional]
\&      Return:
\&     Example: $node\->write("myfile.xml");
\&     Example: $node\->write("myfile", "itext");
\&
\&
\&        Args:
\&      Return: xml str
\&     Example: print $node\->xml;
.Ve
.SS "\s-1XML METHODS\s0"
.IX Subsection "XML METHODS"
\fIxslt\fR
.IX Subsection "xslt"
.PP
.Vb 1
\&       Title: xslt
\&
\&        Args: xslt_file str
\&      Return: Node
\&     Example: $new_stag = $stag\->xslt(\*(Aqmytransform.xsl\*(Aq);
.Ve
.PP
transforms a stag tree using \s-1XSLT\s0
.PP
\fIxsltstr\fR
.IX Subsection "xsltstr"
.PP
.Vb 1
\&       Title: xsltstr
\&
\&        Args: xslt_file str
\&      Return: str
\&     Example: print $stag\->xsltstr(\*(Aqmytransform.xsl\*(Aq);
.Ve
.PP
As above, but returns the string of the resulting transform, rather
than a stag tree
.PP
\fIsax\fR
.IX Subsection "sax"
.PP
.Vb 1
\&       Title: sax
\&
\&        Args: saxhandler SAX\-CLASS
\&      Return:
\&     Example: $node\->sax($mysaxhandler);
.Ve
.PP
turns a tree into a series of \s-1SAX\s0 events
.PP
\fIxpath (xp tree2xpath)\fR
.IX Subsection "xpath (xp tree2xpath)"
.PP
.Vb 3
\&       Title: xpath
\&     Synonym: xp
\&     Synonym: tree2xpath
\&
\&        Args:
\&      Return: xpath object
\&     Example: $xp = $node\->xpath; $q = $xp\->find($xpathquerystr);
.Ve
.PP
\fIxpquery (xpq xpathquery)\fR
.IX Subsection "xpquery (xpq xpathquery)"
.PP
.Vb 3
\&       Title: xpquery
\&     Synonym: xpq
\&     Synonym: xpathquery
\&
\&        Args: xpathquery str
\&      Return: Node[]
\&     Example: @nodes = $node\->xqp($xpathquerystr);
.Ve
.SH "STAG SCRIPTS"
.IX Header "STAG SCRIPTS"
The following scripts come with the stag module
.IP "stag\-autoschema.pl" 4
.IX Item "stag-autoschema.pl"
writes the implicit stag-schema for a stag file
.IP "stag\-db.pl" 4
.IX Item "stag-db.pl"
persistent storage and retrieval for stag data (xml, sxpr, itext)
.IP "stag\-diff.pl" 4
.IX Item "stag-diff.pl"
finds the difference between two stag files
.IP "stag\-drawtree.pl" 4
.IX Item "stag-drawtree.pl"
draws a stag file (xml, itext, sxpr) as a \s-1PNG\s0 diagram
.IP "stag\-filter.pl" 4
.IX Item "stag-filter.pl"
filters a stag file (xml, itext, sxpr) for nodes of interest
.IP "stag\-findsubtree.pl" 4
.IX Item "stag-findsubtree.pl"
finds nodes in a stag file
.IP "stag\-flatten.pl" 4
.IX Item "stag-flatten.pl"
turns stag data into a flat table
.IP "stag\-grep.pl" 4
.IX Item "stag-grep.pl"
filters a stag file (xml, itext, sxpr) for nodes of interest
.IP "stag\-handle.pl" 4
.IX Item "stag-handle.pl"
streams a stag file through a handler into a writer
.IP "stag\-join.pl" 4
.IX Item "stag-join.pl"
joins two stag files together based around common key
.IP "stag\-mogrify.pl" 4
.IX Item "stag-mogrify.pl"
mangle stag files
.IP "stag\-parse.pl" 4
.IX Item "stag-parse.pl"
parses a file and fires events (e.g. sxpr to xml)
.IP "stag\-query.pl" 4
.IX Item "stag-query.pl"
aggregare queries
.IP "stag\-split.pl" 4
.IX Item "stag-split.pl"
splits a stag file (xml, itext, sxpr) into multiple files
.IP "stag\-splitter.pl" 4
.IX Item "stag-splitter.pl"
splits a stag file into multiple files
.IP "stag\-view.pl" 4
.IX Item "stag-view.pl"
draws an expandable Tk tree diagram showing stag data
.PP
To get more documentation, type
.PP
.Vb 1
\&  stag_<script> \-h
.Ve
.SH "BUGS"
.IX Header "BUGS"
none known so far, possibly quite a few undocumented features!
.PP
Not a bug, but the underlying default datastructure of nested arrays
is more heavyweight than it needs to be. More lightweight
implementations are possible. Some time I will write a C
implementation.
.SH "WEBSITE"
.IX Header "WEBSITE"
<http://stag.sourceforge.net>
.SH "AUTHOR"
.IX Header "AUTHOR"
Chris Mungall <\fIcjm \s-1AT\s0 fruitfly \s-1DOT\s0 org\fR>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2004 Chris Mungall
.PP
This module is free software.
You may distribute this module under the same terms as perl itself