.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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 "Stone 3pm"
.TH Stone 3pm "2021-01-05" "perl v5.32.0" "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"
Stone \- In\-memory storage for hierarchical tag/value data structures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\& use Stone;
\& my $stone = Stone\->new( Jim => { First_name => \*(AqJames\*(Aq,
\& Last_name => \*(AqHill\*(Aq,
\& Age => 34,
\& Address => {
\& Street => [\*(AqThe Manse\*(Aq,
\& \*(Aq19 Chestnut Ln\*(Aq],
\& City => \*(AqGarden City\*(Aq,
\& State => \*(AqNY\*(Aq,
\& Zip => 11291 }
\& },
\& Sally => { First_name => \*(AqSarah\*(Aq,
\& Last_name => \*(AqJames\*(Aq,
\& Age => 30,
\& Address => {
\& Street => \*(AqHickory Street\*(Aq,
\& City => \*(AqKatonah\*(Aq,
\& State => \*(AqNY\*(Aq,
\& Zip => 10578 }
\& }
\& );
\&
\& @tags = $stone\->tags; # yields (\*(AqJames\*(Aq,\*(AqSally\*(Aq);
\& $address = $stone\->Jim\->Address; # gets the address subtree
\& @street = $address\->Street; # yeilds (\*(AqThe Manse\*(Aq,\*(Aq19 Chestnut Ln\*(Aq)
\&
\& $address = $stone\->get(\*(AqJim\*(Aq)\->get(\*(AqAddress\*(Aq); # same as $stone\->Jim\->Address
\& $address = $stone\->get(\*(AqJim.Address\*(Aq); # another way to express same thing
\&
\& # first Street tag in Jim\*(Aqs address
\& $address = $stone\->get(\*(AqJim.Address.Street[0]\*(Aq);
\& # second Street tag in Jim\*(Aqs address
\& $address = $stone\->get(\*(AqJim.Address.Street[1]\*(Aq);
\& # last Street tag in Jim\*(Aqs address
\& $address = $stone\->get(\*(AqJim.Address.Street[#]\*(Aq);
\&
\& # insert a tag/value pair
\& $stone\->insert(Martha => { First_name => \*(AqMartha\*(Aq, Last_name => \*(AqSteward\*(Aq} );
\&
\& # find the first Address
\& $stone\->search(\*(AqAddress\*(Aq);
\&
\& # change an existing subtree
\& $martha = $stone\->Martha;
\& $martha\->replace(Last_name => \*(AqStewart\*(Aq); # replace a value
\&
\& # iterate over the tree with a cursor
\& $cursor = $stone\->cursor;
\& while (my ($key,$value) = $cursor\->each) {
\& print "$value: Go Bluejays!\en" if $key eq \*(AqState\*(Aq and $value eq \*(AqKatonah\*(Aq;
\& }
\&
\& # various format conversions
\& print $stone\->asTable;
\& print $stone\->asString;
\& print $stone\->asHTML;
\& print $stone\->asXML(\*(AqPerson\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Stone consists of a series of tag/value pairs. Any given tag may
be single-valued or multivalued. A value can be another Stone,
allowing nested components. A big Stone can be made up of a lot of
little stones (pebbles?). You can obtain a Stone from a
Boulder::Stream or Boulder::Store persistent database.
Alternatively you can build your own Stones bit by bit.
.PP
Stones can be exported into string, \s-1XML\s0 and \s-1HTML\s0 representations. In
addition, they are flattened into a linearized representation when
reading from or writing to a Boulder::Stream or one of its
descendents.
.PP
Stone was designed for subclassing. You should be able to create
subclasses which create or require particular tags and data formats.
Currently only Stone::GB_Sequence subclasses Stone.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
Stones are either created by calling the \fBnew()\fR method, or by reading
them from a Boulder::Stream or persistent database.
.ie n .SS "$stone = Stone\->\fBnew()\fP"
.el .SS "\f(CW$stone\fP = Stone\->\fBnew()\fP"
.IX Subsection "$stone = Stone->new()"
This is the main constructor for the Stone class. It can be called
without any parameters, in which case it creates an empty Stone object
(no tags or values), or it may passed an associative array in order to
initialize it with a set of tags. A tag's value may be a scalar, an
anonymous array reference (constructed using [] brackets), or a hash
references (constructed using {} brackets). In the first case, the
tag will be single-valued. In the second, the tag will be
multivalued. In the third case, a subsidiary Stone will be generated
automatically and placed into the tree at the specified location.
.PP
Examples:
.PP
.Vb 12
\& $myStone = new Stone;
\& $myStone = new Stone(Name=>\*(AqFred\*(Aq,Age=>30);
\& $myStone = new Stone(Name=>\*(AqFred\*(Aq,
\& Friend=>[\*(AqJill\*(Aq,\*(AqJohn\*(Aq,\*(AqJerry\*(Aq]);
\& $myStone = new Stone(Name=>\*(AqFred\*(Aq,
\& Friend=>[\*(AqJill\*(Aq,
\& \*(AqJohn\*(Aq,
\& \*(AqGerald\*(Aq
\& ],
\& Attributes => { Hair => \*(Aqblonde\*(Aq,
\& Eyes => \*(Aqblue\*(Aq }
\& );
.Ve
.PP
In the last example, a Stone with the following structure is created:
.PP
.Vb 6
\& Name Fred
\& Friend Jill
\& Friend John
\& Friend Gerald
\& Attributes Eyes blue
\& Hair blonde
.Ve
.PP
Note that the value corresponding to the tag \*(L"Attributes\*(R" is itself a
Stone with two tags, \*(L"Eyes\*(R" and \*(L"Hair\*(R".
.PP
The \s-1XML\s0 representation (which could be created with \fBasXML()\fR) looks like this:
.PP
.Vb 11
\&
\&
\&
\& blue
\& blonde
\&
\& Jill
\& John
\& Gerald
\& Fred
\&
.Ve
.PP
More information on Stone initialization is given in the description
of the \fBinsert()\fR method.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
Once a Stone object is created or retrieved, you can manipulate it
with the following methods.
.ie n .SS "$stone\->insert(%hash)"
.el .SS "\f(CW$stone\fP\->insert(%hash)"
.IX Subsection "$stone->insert(%hash)"
.ie n .SS "$stone\->insert(\e%hash)"
.el .SS "\f(CW$stone\fP\->insert(\e%hash)"
.IX Subsection "$stone->insert(%hash)"
This is the main method for adding tags to a Stone. This method
expects an associative array as an argument or a reference to one.
The contents of the associative array will be inserted into the Stone.
If a particular tag is already present in the Stone, the tag's current
value will be appended to the list of values for that tag. Several
types of values are legal:
.IP "\(bu" 4
A \fBscalar\fR value
.Sp
The value will be inserted into the \f(CW\*(C`Stone\*(C'\fR.
.Sp
.Vb 4
\& $stone\->insert(name=>Fred,
\& age=>30,
\& sex=>M);
\& $stone\->dump;
\&
\& name[0]=Fred
\& age[0]=30
\& sex[0]=M
.Ve
.IP "\(bu" 4
An \fB\s-1ARRAY\s0\fR reference
.Sp
A multi-valued tag will be created:
.Sp
.Vb 3
\& $stone\->insert(name=>Fred,
\& children=>[Tom,Mary,Angelique]);
\& $stone\->dump;
\&
\& name[0]=Fred
\& children[0]=Tom
\& children[1]=Mary
\& children[2]=Angelique
.Ve
.IP "\(bu" 4
A \fB\s-1HASH\s0\fR reference
.Sp
A subsidiary \f(CW\*(C`Stone\*(C'\fR object will be created and inserted into the
object as a nested structure.
.Sp
.Vb 3
\& $stone\->insert(name=>Fred,
\& wife=>{name=>Agnes,age=>40});
\& $stone\->dump;
\&
\& name[0]=Fred
\& wife[0].name[0]=Agnes
\& wife[0].age[0]=40
.Ve
.IP "\(bu" 4
A \f(CW\*(C`Stone\*(C'\fR object or subclass
.Sp
The \f(CW\*(C`Stone\*(C'\fR object will be inserted into the object as a nested
structure.
.Sp
.Vb 6
\& $wife = new Stone(name=>agnes,
\& age=>40);
\& $husband = new Stone;
\& $husband\->insert(name=>fred,
\& wife=>$wife);
\& $husband\->dump;
\&
\& name[0]=fred
\& wife[0].name[0]=agnes
\& wife[0].age[0]=40
.Ve
.ie n .SS "$stone\->replace(%hash)"
.el .SS "\f(CW$stone\fP\->replace(%hash)"
.IX Subsection "$stone->replace(%hash)"
.ie n .SS "$stone\->replace(\e%hash)"
.el .SS "\f(CW$stone\fP\->replace(\e%hash)"
.IX Subsection "$stone->replace(%hash)"
The \fB\fBreplace()\fB\fR method behaves exactly like \f(CW\*(C`insert()\*(C'\fR with the
exception that if the indicated key already exists in the \fBStone\fR,
its value will be replaced. Use \fB\fBreplace()\fB\fR when you want to enforce
a single-valued tag/value relationship.
.ie n .SS "$stone\->insert_list($key,@list) =head2 $stone\->insert_hash($key,%hash) =head2 $stone\->replace_list($key,@list) =head2 $stone\->replace_hash($key,%hash)"
.el .SS "\f(CW$stone\fP\->insert_list($key,@list) =head2 \f(CW$stone\fP\->insert_hash($key,%hash) =head2 \f(CW$stone\fP\->replace_list($key,@list) =head2 \f(CW$stone\fP\->replace_hash($key,%hash)"
.IX Subsection "$stone->insert_list($key,@list) =head2 $stone->insert_hash($key,%hash) =head2 $stone->replace_list($key,@list) =head2 $stone->replace_hash($key,%hash)"
These are primitives used by the \f(CW\*(C`insert()\*(C'\fR and \f(CW\*(C`replace()\*(C'\fR methods.
Override them if you need to modify the default behavior.
.ie n .SS "$stone\->delete($tag)"
.el .SS "\f(CW$stone\fP\->delete($tag)"
.IX Subsection "$stone->delete($tag)"
This removes the indicated tag from the Stone.
.ie n .SS "@values = $stone\->get($tag [,$index])"
.el .SS "\f(CW@values\fP = \f(CW$stone\fP\->get($tag [,$index])"
.IX Subsection "@values = $stone->get($tag [,$index])"
This returns the value at the indicated tag and optional index. What
you get depends on whether it is called in a scalar or list context.
In a list context, you will receive all the values for that tag. You
may receive a list of scalar values or (for a nested record) or a list
of Stone objects. If called in a scalar context, you will either
receive the first or the last member of the list of values assigned to
the tag. Which one you receive depends on the value of the package
variable \f(CW$Stone::Fetchlast\fR. If undefined, you will receive the
first member of the list. If nonzero, you will receive the last
member.
.PP
You may provide an optional index in order to force \fBget()\fR to return a
particular member of the list. Provide a 0 to return the first member
of the list, or '#' to obtain the last member.
.PP
If the tag contains a period (.), \fBget()\fR will call \fBindex()\fR on your
behalf (see below).
.PP
If the tag begins with an uppercase letter, then you can use the
autogenerated method to access it:
.PP
.Vb 1
\& $stone\->Tag_name([$index])
.Ve
.PP
This is exactly equivalent to:
.PP
.Vb 1
\& $stone\->get(\*(AqTeg_name\*(Aq [,$index])
.Ve
.ie n .SS "@values = $stone\->search($tag)"
.el .SS "\f(CW@values\fP = \f(CW$stone\fP\->search($tag)"
.IX Subsection "@values = $stone->search($tag)"
Searches for the first occurrence of the tag, traversing the tree in a
breadth-first manner, and returns it. This allows you to retrieve the
value of a tag in a deeply nested structure without worrying about all
the intermediate nodes. For example:
.PP
.Vb 8
\& $myStone = new Stone(Name=>\*(AqFred\*(Aq,
\& Friend=>[\*(AqJill\*(Aq,
\& \*(AqJohn\*(Aq,
\& \*(AqGerald\*(Aq
\& ],
\& Attributes => { Hair => \*(Aqblonde\*(Aq,
\& Eyes => \*(Aqblue\*(Aq }
\& );
\&
\& $hair_colour = $stone\->search(\*(AqHair\*(Aq);
.Ve
.PP
The disadvantage of this is that if there is a tag named \*(L"Hair\*(R" higher
in the hierarchy, this tag will be retrieved rather than the lower
one. In an array context this method returns the complete list of
values from the matching tag. In a scalar context, it returns either
the first or the last value of multivalued tags depending as usual on
the value of \f(CW$Stone::Fetchlast\fR.
.PP
\&\f(CW$Stone::Fetchlast\fR is also consulted during the depth-first
traversal. If \f(CW$Fetchlast\fR is set to a true value, multivalued
intermediate tags will be searched from the last to the first rather
than the first to the last.
.PP
The Stone object has an \s-1AUTOLOAD\s0 method that invokes \fBget()\fR when you
call a method that is not predefined. This allows a very convenient
type of shortcut:
.PP
.Vb 3
\& $name = $stone\->Name;
\& @friends = $stone\->Friend;
\& $eye_color = $stone\->Attributes\->Eyes
.Ve
.PP
In the first example, we retrieve the value of the top-level tag Name.
In the second example, we retrieve the value of the Friend tag.. In
the third example, we retrieve the attributes stone first, then the
Eyes value.
.PP
\&\s-1NOTE:\s0 By convention, methods are only autogenerated for tags that
begin with capital letters. This is necessary to avoid conflict with
hard-coded methods, all of which are lower case.
.ie n .SS "@values = $stone\->index($indexstr)"
.el .SS "\f(CW@values\fP = \f(CW$stone\fP\->index($indexstr)"
.IX Subsection "@values = $stone->index($indexstr)"
You can access the contents of even deeply-nested \fBStone\fR objects
with the \f(CW\*(C`index\*(C'\fR method. You provide a \fBtag path\fR, and receive
a value or list of values back.
.PP
Tag paths look like this:
.PP
.Vb 1
\& tag1[index1].tag2[index2].tag3[index3]
.Ve
.PP
Numbers in square brackets indicate which member of a multivalued tag
you're interested in getting. You can leave the square brackets out
in order to return just the first or the last tag of that name, in a scalar
context (depending on the setting of \fB\f(CB$Stone::Fetchlast\fB\fR). In an
array context, leaving the square brackets out will return \fBall\fR
multivalued members for each tag along the path.
.PP
You will get a scalar value in a scalar context and an array value in
an array context following the same rules as \fB\fBget()\fB\fR. You can
provide an index of '#' in order to get the last member of a list or
a [?] to obtain a randomly chosen member of the list (this uses the \fBrand()\fR call,
so be sure to call \fBsrand()\fR at the beginning of your program in order
to get different sequences of pseudorandom numbers. If
there is no tag by that name, you will receive undef or an empty list.
If the tag points to a subrecord, you will receive a \fBStone\fR object.
.PP
Examples:
.PP
.Vb 8
\& # Here\*(Aqs what the data structure looks like.
\& $s\->insert(person=>{name=>Fred,
\& age=>30,
\& pets=>[Fido,Rex,Lassie],
\& children=>[Tom,Mary]},
\& person=>{name=>Harry,
\& age=>23,
\& pets=>[Rover,Spot]});
\&
\& # Return all of Fred\*(Aqs children
\& @children = $s\->index(\*(Aqperson[0].children\*(Aq);
\&
\& # Return Harry\*(Aqs last pet
\& $pet = $s\->index(\*(Aqperson[1].pets[#]\*(Aq);
\&
\& # Return first person\*(Aqs first child
\& $child = $s\->index(\*(Aqperson.children\*(Aq);
\&
\& # Return children of all person\*(Aqs
\& @children = $s\->index(\*(Aqperson.children\*(Aq);
\&
\& # Return last person\*(Aqs last pet
\& $Stone::Fetchlast++;
\& $pet = $s\->index(\*(Aqperson.pets\*(Aq);
\&
\& # Return any pet from any person
\& $pet = $s\->index(\*(Aqperson[?].pet[?]\*(Aq);
.Ve
.PP
\&\fINote\fR that \fB\fBindex()\fB\fR may return a \fBStone\fR object if the tag path
points to a subrecord.
.ie n .SS "$array = $stone\->at($tag)"
.el .SS "\f(CW$array\fP = \f(CW$stone\fP\->at($tag)"
.IX Subsection "$array = $stone->at($tag)"
This returns an \s-1ARRAY REFERENCE\s0 for the tag. It is useful to prevent
automatic dereferencing. Use with care. It is equivalent to:
.PP
.Vb 1
\& $stone\->{\*(Aqtag\*(Aq}
.Ve
.PP
\&\fBat()\fR will always return an array reference. Single-valued tags will
return a reference to an array of size 1.
.ie n .SS "@tags = $stone\->\fBtags()\fP"
.el .SS "\f(CW@tags\fP = \f(CW$stone\fP\->\fBtags()\fP"
.IX Subsection "@tags = $stone->tags()"
Return all the tags in the Stone. You can then use this list with
\&\fBget()\fR to retrieve values or recursively traverse the stone.
.ie n .SS "$string = $stone\->\fBasTable()\fP"
.el .SS "\f(CW$string\fP = \f(CW$stone\fP\->\fBasTable()\fP"
.IX Subsection "$string = $stone->asTable()"
Return the data structure as a tab-delimited table suitable for
printing.
.ie n .SS "$string = $stone\->asXML([$tagname])"
.el .SS "\f(CW$string\fP = \f(CW$stone\fP\->asXML([$tagname])"
.IX Subsection "$string = $stone->asXML([$tagname])"
Return the data structure in \s-1XML\s0 format. The entire data structure
will be placed inside a top-level tag called . If you wish to
change this top-level tag, pass it as an argument to \fBasXML()\fR.
.PP
An example follows:
.PP
.Vb 3
\& print $stone\->asXML(\*(AqAddress_list\*(Aq);
\& # yields:
\&
\&
\&
\&
\&
\& 10578
\& Katonah
\& Hickory Street
\& NY
\&
\& Smith
\& 30
\& Sarah
\&
\&
\&
\& 11291
\& Garden City
\& The Manse
\& 19 Chestnut Ln
\& NY
\&
\& Hill
\& 34
\& James
\&
\&
.Ve
.ie n .SS "$hash = $stone\->attributes([$att_name, [$att_value]]])"
.el .SS "\f(CW$hash\fP = \f(CW$stone\fP\->attributes([$att_name, [$att_value]]])"
.IX Subsection "$hash = $stone->attributes([$att_name, [$att_value]]])"
\&\fBattributes()\fR returns the \*(L"attributes\*(R" of a tag. Attributes are a
series of unique tag/value pairs which are associated with a tag, but
are not contained within it. Attributes can only be expressed in the
\&\s-1XML\s0 representation of a Stone:
.PP
.Vb 8
\&
\&
\& 10578
\& Katonah
\& Hickory Street
\& NY
\&
\&
.Ve
.PP
Called with no arguments, \fBattributes()\fR returns the current attributes
as a hash ref:
.PP
.Vb 2
\& my $att = $stone\->Address\->attributes;
\& my $type = $att\->{type};
.Ve
.PP
Called with a single argument, \fBattributes()\fR returns the value of the
named attribute, or undef if not defined:
.PP
.Vb 1
\& my $type = $stone\->Address\->attributes(\*(Aqtype\*(Aq);
.Ve
.PP
Called with two arguments, \fBattributes()\fR sets the named attribute:
.PP
.Vb 1
\& my $type = $stone\->Address\->attributes(type => \*(AqRural Free Delivery\*(Aq);
.Ve
.PP
You may also change all attributes in one fell swoop by passing a hash
reference as the single argument:
.PP
.Vb 1
\& $stone\->attributes({id=>\*(AqSally Mae\*(Aq,version=>\*(Aq2.1\*(Aq});
.Ve
.ie n .SS "$string = $stone\->\fBtoString()\fP"
.el .SS "\f(CW$string\fP = \f(CW$stone\fP\->\fBtoString()\fP"
.IX Subsection "$string = $stone->toString()"
\&\fBtoString()\fR returns a simple version of the Stone that shows just the
topmost tags and the number of each type of tag. For example:
.PP
.Vb 2
\& print $stone\->Jim\->Address;
\& #yields => Zip(1),City(1),Street(2),State(1)
.Ve
.PP
This method is used internally for string interpolation. If you try
to print or otherwise manipulate a Stone object as a string, you will
obtain this type of string as a result.
.ie n .SS "$string = $stone\->asHTML([\e&callback])"
.el .SS "\f(CW$string\fP = \f(CW$stone\fP\->asHTML([\e&callback])"
.IX Subsection "$string = $stone->asHTML([&callback])"
Return the data structure as a nicely-formatted \s-1HTML 3.2\s0 table,
suitable for display in a Web browser. You may pass this method a
callback routine which will be called for every tag/value pair in the
object. It will be passed a two-item list containing the current tag
and value. It can make any modifications it likes and return the
modified tag and value as a return result. You can use this to modify
tags or values on the fly, for example to turn them into \s-1HTML\s0 links.
.PP
For example, this code fragment will turn all tags named \*(L"Sequence\*(R"
blue:
.PP
.Vb 6
\& my $callback = sub {
\& my ($tag,$value) = @_;
\& return ($tag,$value) unless $tag eq \*(AqSequence\*(Aq;
\& return ( qq($tag),$value );
\& }
\& print $stone\->asHTML($callback);
.Ve
.SS "\fBStone::dump()\fP"
.IX Subsection "Stone::dump()"
This is a debugging tool. It iterates through the \fBStone\fR object and
prints out all the tags and values.
.PP
Example:
.PP
.Vb 1
\& $s\->dump;
\&
\& person[0].children[0]=Tom
\& person[0].children[1]=Mary
\& person[0].name[0]=Fred
\& person[0].pets[0]=Fido
\& person[0].pets[1]=Rex
\& person[0].pets[2]=Lassie
\& person[0].age[0]=30
\& person[1].name[0]=Harry
\& person[1].pets[0]=Rover
\& person[1].pets[1]=Spot
\& person[1].age[0]=23
.Ve
.ie n .SS "$cursor = $stone\->\fBcursor()\fP"
.el .SS "\f(CW$cursor\fP = \f(CW$stone\fP\->\fBcursor()\fP"
.IX Subsection "$cursor = $stone->cursor()"
Retrieves an iterator over the object. You can call this several
times in order to return independent iterators. The following brief
example is described in more detail in Stone::Cursor.
.PP
.Vb 10
\& my $curs = $stone\->cursor;
\& while (my($tag,$value) = $curs\->next_pair) {
\& print "$tag => $value\en";
\& }
\& # yields:
\& Sally[0].Address[0].Zip[0] => 10578
\& Sally[0].Address[0].City[0] => Katonah
\& Sally[0].Address[0].Street[0] => Hickory Street
\& Sally[0].Address[0].State[0] => NY
\& Sally[0].Last_name[0] => James
\& Sally[0].Age[0] => 30
\& Sally[0].First_name[0] => Sarah
\& Jim[0].Address[0].Zip[0] => 11291
\& Jim[0].Address[0].City[0] => Garden City
\& Jim[0].Address[0].Street[0] => The Manse
\& Jim[0].Address[0].Street[1] => 19 Chestnut Ln
\& Jim[0].Address[0].State[0] => NY
\& Jim[0].Last_name[0] => Hill
\& Jim[0].Age[0] => 34
\& Jim[0].First_name[0] => James
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln D. Stein .
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1997\-1999, Cold Spring Harbor Laboratory, Cold Spring Harbor
\&\s-1NY.\s0 This module can be used and distributed on the same terms as Perl
itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
Boulder::Omim, Boulder::SwissProt