<![CDATA[
#!perl -w
use strict;
use Stone;
my $stone = Stone->new( Jim => { First_name => 'James',
Last_name => 'Hill',
Age => 34,
Address => {
Street => ['The Manse',
'19 Chestnut Ln'],
City => 'Garden City',
State => 'NY',
Zip => 11291 }
},
Sally => { First_name => 'Sarah',
Last_name => 'James',
Age => 30,
Address => {
Street => 'Hickory Street',
City => 'Katonah',
State => 'NY',
Zip => 10578 }
}
);
my @tags = $stone->tags; # yields ('James','Sally');
my $address = $stone->Jim->Address; # gets the address subtree
my @street = $address->Street; # yeilds ('The Manse','19 Chestnut Ln')
$address = $stone->get('Jim')->get('Address'); # same as $stone->Jim->Address
$address = $stone->get('Jim.Address'); # another way to express same thing
# first Street tag in Jim's address
$address = $stone->get('Jim.Address.Street[0]');
# second Street tag in Jim's address
$address = $stone->get('Jim.Address.Street[1]');
# last Street tag in Jim's address
$address = $stone->get('Jim.Address.Street[#]');
# insert a tag/value pair
$stone->insert(Martha => { First_name => 'Martha', Last_name => 'Steward'} );
# find the first Address
$stone->search('Address');
# change an existing subtree
my $martha = $stone->Martha;
$martha->replace(Last_name => 'Stewart'); # replace a value
# iterate over the tree with a cursor
my $cursor = $stone->cursor;
while (my ($key,$value) = $cursor->each) {
print "$value: Go Bluejays!\n" if $key eq 'State' and $value eq 'Katonah';
}
# various format conversions
print $stone->asTable;
print $stone->asString;
print $stone->asHTML;
print $stone->asXML('Person');
exit(0);
__END__
=head1 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.
Stones can be exported into string, XML and HTML representations. In
addition, they are flattened into a linearized representation when
reading from or writing to a Boulder::Stream or one of its descendents.
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.
=head1 CONSTRUCTORS
Stones are either created by calling the new() method, or by reading
them from a Boulder::Stream or persistent database.
$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.
=head1 Examples:
$myStone = new Stone;
$myStone = new Stone(Name=>'Fred',Age=>30);
$myStone = new Stone(Name=>'Fred',
Friend=>['Jill','John','Jerry']);
$myStone = new Stone(Name=>'Fred',
Friend=>['Jill',
'John',
'Gerald'
],
Attributes => { Hair => 'blonde',
Eyes => 'blue' }
);
=head1 EXAMPLE NOTES
In the last example, a Stone with the following structure is created:
Name Fred
Friend Jill
Friend John
Friend Gerald
Attributes Eyes blue
Hair blonde
Note that the value corresponding to the tag "Attributes" is itself a
Stone with two tags, "Eyes" and "Hair".
The XML representation (which could be created with asXML()) looks like
this:
<?xml version="1.0" standalone="yes"?>
<Stone>
<Attributes>
<Eyes>blue</Eyes>
<Hair>blonde</Hair>
</Attributes>
<Friend>Jill</Friend>
<Friend>John</Friend>
<Friend>Gerald</Friend>
<Name>Fred</Name>
</Stone>
More information on Stone initialization is given in the description of
the insert() method.
=head1 OBJECT METHODS
Once a Stone object is created or retrieved, you can manipulate it with
the following methods.
$stone->insert(%hash)
$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:
* A scalar value
The value will be inserted into the "Stone".
$stone->insert(name=>Fred,
age=>30,
sex=>M);
$stone->dump;
name[0]=Fred
age[0]=30
sex[0]=M
* An ARRAY reference
A multi-valued tag will be created:
$stone->insert(name=>Fred,
children=>[Tom,Mary,Angelique]);
$stone->dump;
name[0]=Fred
children[0]=Tom
children[1]=Mary
children[2]=Angelique
* A HASH reference
A subsidiary "Stone" object will be created and inserted into the
object as a nested structure.
$stone->insert(name=>Fred,
wife=>{name=>Agnes,age=>40});
$stone->dump;
name[0]=Fred
wife[0].name[0]=Agnes
wife[0].age[0]=40
* A "Stone" object or subclass
The "Stone" object will be inserted into the object as a nested
structure.
$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
$stone->replace(%hash)
$stone->replace(\%hash)
The replace() method behaves exactly like "insert()" with the exception
that if the indicated key already exists in the Stone, its value will be
replaced. Use replace() when you want to enforce a single-valued
tag/value relationship.
$stone->insert_list($key,@list)
$stone->insert_hash($key,%hash)
$stone->replace_list($key,@list)
$stone->replace_hash($key,%hash)
These are primitives used by the "insert()" and "replace()" methods.
Override them if you need to modify the default behavior.
$stone->delete($tag)
This removes the indicated tag from the Stone.
@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
$Stone::Fetchlast. If undefined, you will receive the first member of
the list. If nonzero, you will receive the last member.
You may provide an optional index in order to force get() 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.
If the tag contains a period (.), get() will call index() on your behalf
(see below).
If the tag begins with an uppercase letter, then you can use the
autogenerated method to access it:
$stone->Tag_name([$index])
This is exactly equivalent to:
$stone->get('Teg_name' [,$index])
@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:
$myStone = new Stone(Name=>'Fred',
Friend=>['Jill',
'John',
'Gerald'
],
Attributes => { Hair => 'blonde',
Eyes => 'blue' }
);
$hair_colour = $stone->search('Hair');
The disadvantage of this is that if there is a tag named "Hair" 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
$Stone::Fetchlast.
$Stone::Fetchlast is also consulted during the depth-first traversal. If
$Fetchlast 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.
The Stone object has an AUTOLOAD method that invokes get() when you call
a method that is not predefined. This allows a very convenient type of
shortcut:
$name = $stone->Name;
@friends = $stone->Friend;
$eye_color = $stone->Attributes->Eyes
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.
NOTE: 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.
@values = $stone->index($indexstr)
You can access the contents of even deeply-nested Stone objects with the
"index" method. You provide a tag path, and receive a value or list of
values back.
Tag paths look like this:
tag1[index1].tag2[index2].tag3[index3]
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 $Stone::Fetchlast). In an array
context, leaving the square brackets out will return all multivalued
members for each tag along the path.
You will get a scalar value in a scalar context and an array value in an
array context following the same rules as get(). 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 rand() call,
so be sure to call srand() 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 Stone object.
=head1 Examples 2:
# Here's 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's children
@children = $s->index('person[0].children');
# Return Harry's last pet
$pet = $s->index('person[1].pets[#]');
# Return first person's first child
$child = $s->index('person.children');
# Return children of all person's
@children = $s->index('person.children');
# Return last person's last pet
$Stone::Fetchlast++;
$pet = $s->index('person.pets');
# Return any pet from any person
$pet = $s->index('person[?].pet[?]');
*Note* that index() may return a Stone object if the tag path points to
a subrecord.
$array = $stone->at($tag)
This returns an ARRAY REFERENCE for the tag. It is useful to prevent
automatic dereferencing. Use with care. It is equivalent to:
$stone->{'tag'}
at() will always return an array reference. Single-valued tags will
return a reference to an array of size 1.
@tags = $stone->tags()
Return all the tags in the Stone. You can then use this list with get()
to retrieve values or recursively traverse the stone.
$string = $stone->asTable()
Return the data structure as a tab-delimited table suitable for
printing.
$string = $stone->asXML([$tagname])
Return the data structure in XML format. The entire data structure will
be placed inside a top-level tag called <Stone>. If you wish to change
this top-level tag, pass it as an argument to asXML().
An example follows:
print $stone->asXML('Address_list');
# yields:
<?xml version="1.0" standalone="yes"?>
<Address_list>
<Sally>
<Address>
<Zip>10578</Zip>
<City>Katonah</City>
<Street>Hickory Street</Street>
<State>NY</State>
</Address>
<Last_name>Smith</Last_name>
<Age>30</Age>
<First_name>Sarah</First_name>
</Sally>
<Jim>
<Address>
<Zip>11291</Zip>
<City>Garden City</City>
<Street>The Manse</Street>
<Street>19 Chestnut Ln</Street>
<State>NY</State>
</Address>
<Last_name>Hill</Last_name>
<Age>34</Age>
<First_name>James</First_name>
</Jim>
</Address_list>
$hash = $stone->attributes([$att_name, [$att_value]]])
attributes() returns the "attributes" 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 XML
representation of a Stone:
<Sally id="sally_tate" version="2.0">
<Address type="postal">
<Zip>10578</Zip>
<City>Katonah</City>
<Street>Hickory Street</Street>
<State>NY</State>
</Address>
</Sally>
Called with no arguments, attributes() returns the current attributes as
a hash ref:
my $att = $stone->Address->attributes;
my $type = $att->{type};
Called with a single argument, attributes() returns the value of the
named attribute, or undef if not defined:
my $type = $stone->Address->attributes('type');
Called with two arguments, attributes() sets the named attribute:
my $type = $stone->Address->attributes(type => 'Rural Free Delivery');
You may also change all attributes in one fell swoop by passing a hash
reference as the single argument:
$stone->attributes({id=>'Sally Mae',version=>'2.1'});
$string = $stone->toString()
toString() returns a simple version of the Stone that shows just the
topmost tags and the number of each type of tag. For example:
print $stone->Jim->Address;
#yields => Zip(1),City(1),Street(2),State(1)
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.
$string = $stone->asHTML([\&callback])
Return the data structure as a nicely-formatted HTML 3.2 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 HTML links.
For example, this code fragment will turn all tags named "Sequence"
blue:
my $callback = sub {
my ($tag,$value) = @_;
return ($tag,$value) unless $tag eq 'Sequence';
return ( qq(<FONT COLOR="blue">$tag</FONT>),$value );
}
print $stone->asHTML($callback);
Stone::dump()
This is a debugging tool. It iterates through the Stone object and
prints out all the tags and values.
Example:
$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
$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.
my $curs = $stone->cursor;
while (my($tag,$value) = $curs->next_pair) {
print "$tag => $value\n";
}
# 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
=head1 AUTHOR
Lincoln D. Stein <lstein@cshl.org>.
=head1 COPYRIGHT
Copyright 1997-1999, Cold Spring Harbor Laboratory, Cold Spring Harbor
NY. This module can be used and distributed on the same terms as Perl
itself.
=head1 SEE ALSO
Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
Boulder::Omim, Boulder::SwissProt
=cut
]]>