view release on metacpan or  search on metacpan

Stone.pm  view on Meta::CPAN

 </Address_list>

=head2 $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'});

=head2 $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.

=head2 $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);

=head2 Stone::dump()

This is a debugging tool.  It iterates through the B<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

=head2 $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 L<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>.