1Stone(3)              User Contributed Perl Documentation             Stone(3)
2
3
4

NAME

6       Stone - In-memory storage for hierarchical tag/value data structures
7

SYNOPSIS

9        use Stone;
10        my $stone = Stone->new( Jim => { First_name => 'James',
11                                         Last_name  => 'Hill',
12                                         Age        => 34,
13                                         Address    => {
14                                                Street => ['The Manse',
15                                                           '19 Chestnut Ln'],
16                                                City  => 'Garden City',
17                                                State => 'NY',
18                                                Zip   => 11291 }
19                                       },
20                                 Sally => { First_name => 'Sarah',
21                                            Last_name  => 'James',
22                                            Age        => 30,
23                                            Address    => {
24                                                Street => 'Hickory Street',
25                                                City  => 'Katonah',
26                                                State => 'NY',
27                                                Zip  => 10578 }
28                                       }
29                                );
30
31        @tags    = $stone->tags;          # yields ('James','Sally');
32        $address = $stone->Jim->Address;  # gets the address subtree
33        @street  = $address->Street;      # yeilds ('The Manse','19 Chestnut Ln')
34
35        $address = $stone->get('Jim')->get('Address'); # same as $stone->Jim->Address
36        $address = $stone->get('Jim.Address'); # another way to express same thing
37
38        # first Street tag in Jim's address
39        $address = $stone->get('Jim.Address.Street[0]');
40        # second Street tag in Jim's address
41        $address = $stone->get('Jim.Address.Street[1]');
42        # last Street tag in Jim's address
43        $address = $stone->get('Jim.Address.Street[#]');
44
45        # insert a tag/value pair
46        $stone->insert(Martha => { First_name => 'Martha', Last_name => 'Steward'} );
47
48        # find the first Address
49        $stone->search('Address');
50
51        # change an existing subtree
52        $martha = $stone->Martha;
53        $martha->replace(Last_name => 'Stewart');  # replace a value
54
55        # iterate over the tree with a cursor
56        $cursor = $stone->cursor;
57        while (my ($key,$value) = $cursor->each) {
58          print "$value: Go Bluejays!\n" if $key eq 'State' and $value eq 'Katonah';
59        }
60
61        # various format conversions
62        print $stone->asTable;
63        print $stone->asString;
64        print $stone->asHTML;
65        print $stone->asXML('Person');
66

DESCRIPTION

68       A Stone consists of a series of tag/value pairs.  Any given tag may be
69       single-valued or multivalued.  A value can be another Stone, allowing
70       nested components.  A big Stone can be made up of a lot of little
71       stones (pebbles?).  You can obtain a Stone from a Boulder::Stream or
72       Boulder::Store persistent database.  Alternatively you can build your
73       own Stones bit by bit.
74
75       Stones can be exported into string, XML and HTML representations.  In
76       addition, they are flattened into a linearized representation when
77       reading from or writing to a Boulder::Stream or one of its descendents.
78
79       Stone was designed for subclassing.  You should be able to create
80       subclasses which create or require particular tags and data formats.
81       Currently only Stone::GB_Sequence subclasses Stone.
82

CONSTRUCTORS

84       Stones are either created by calling the new() method, or by reading
85       them from a Boulder::Stream or persistent database.
86
87   $stone = Stone->new()
88       This is the main constructor for the Stone class.  It can be called
89       without any parameters, in which case it creates an empty Stone object
90       (no tags or values), or it may passed an associative array in order to
91       initialize it with a set of tags.  A tag's value may be a scalar, an
92       anonymous array reference (constructed using [] brackets), or a hash
93       references (constructed using {} brackets).  In the first case, the tag
94       will be single-valued.  In the second, the tag will be multivalued. In
95       the third case, a subsidiary Stone will be generated automatically and
96       placed into the tree at the specified location.
97
98       Examples:
99
100               $myStone = new Stone;
101               $myStone = new Stone(Name=>'Fred',Age=>30);
102               $myStone = new Stone(Name=>'Fred',
103                                    Friend=>['Jill','John','Jerry']);
104               $myStone = new Stone(Name=>'Fred',
105                                    Friend=>['Jill',
106                                             'John',
107                                             'Gerald'
108                                             ],
109                                    Attributes => { Hair => 'blonde',
110                                                    Eyes => 'blue' }
111                                    );
112
113       In the last example, a Stone with the following structure is created:
114
115        Name        Fred
116        Friend      Jill
117        Friend      John
118        Friend      Gerald
119        Attributes  Eyes    blue
120                    Hair    blonde
121
122       Note that the value corresponding to the tag "Attributes" is itself a
123       Stone with two tags, "Eyes" and "Hair".
124
125       The XML representation (which could be created with asXML()) looks like
126       this:
127
128        <?xml version="1.0" standalone="yes"?>
129        <Stone>
130           <Attributes>
131              <Eyes>blue</Eyes>
132              <Hair>blonde</Hair>
133           </Attributes>
134           <Friend>Jill</Friend>
135           <Friend>John</Friend>
136           <Friend>Gerald</Friend>
137           <Name>Fred</Name>
138        </Stone>
139
140       More information on Stone initialization is given in the description of
141       the insert() method.
142

OBJECT METHODS

144       Once a Stone object is created or retrieved, you can manipulate it with
145       the following methods.
146
147   $stone->insert(%hash)
148   $stone->insert(\%hash)
149       This is the main method for adding tags to a Stone.  This method
150       expects an associative array as an argument or a reference to one.  The
151       contents of the associative array will be inserted into the Stone.  If
152       a particular tag is already present in the Stone, the tag's current
153       value will be appended to the list of values for that tag.  Several
154       types of values are legal:
155
156       •   A scalar value
157
158           The value will be inserted into the "Stone".
159
160                   $stone->insert(name=>Fred,
161                                  age=>30,
162                                  sex=>M);
163                   $stone->dump;
164
165                   name[0]=Fred
166                   age[0]=30
167                   sex[0]=M
168
169       •   An ARRAY reference
170
171           A multi-valued tag will be created:
172
173                   $stone->insert(name=>Fred,
174                                  children=>[Tom,Mary,Angelique]);
175                   $stone->dump;
176
177                   name[0]=Fred
178                   children[0]=Tom
179                   children[1]=Mary
180                   children[2]=Angelique
181
182       •   A HASH reference
183
184           A subsidiary "Stone" object will be created and inserted into the
185           object as a nested structure.
186
187                   $stone->insert(name=>Fred,
188                                  wife=>{name=>Agnes,age=>40});
189                   $stone->dump;
190
191                   name[0]=Fred
192                   wife[0].name[0]=Agnes
193                   wife[0].age[0]=40
194
195       •   A "Stone" object or subclass
196
197           The "Stone" object will be inserted into the object as a nested
198           structure.
199
200                   $wife = new Stone(name=>agnes,
201                                     age=>40);
202                   $husband = new Stone;
203                   $husband->insert(name=>fred,
204                                    wife=>$wife);
205                   $husband->dump;
206
207                   name[0]=fred
208                   wife[0].name[0]=agnes
209                   wife[0].age[0]=40
210
211   $stone->replace(%hash)
212   $stone->replace(\%hash)
213       The replace() method behaves exactly like "insert()" with the exception
214       that if the indicated key already exists in the Stone, its value will
215       be replaced.  Use replace() when you want to enforce a single-valued
216       tag/value relationship.
217
218   $stone->insert_list($key,@list) =head2 $stone->insert_hash($key,%hash)
219       =head2 $stone->replace_list($key,@list) =head2
220       $stone->replace_hash($key,%hash)
221       These are primitives used by the "insert()" and "replace()" methods.
222       Override them if you need to modify the default behavior.
223
224   $stone->delete($tag)
225       This removes the indicated tag from the Stone.
226
227   @values = $stone->get($tag [,$index])
228       This returns the value at the indicated tag and optional index.  What
229       you get depends on whether it is called in a scalar or list context.
230       In a list context, you will receive all the values for that tag.  You
231       may receive a list of scalar values or (for a nested record) or a list
232       of Stone objects. If called in a scalar context, you will either
233       receive the first or the last member of the list of values assigned to
234       the tag.  Which one you receive depends on the value of the package
235       variable $Stone::Fetchlast.  If undefined, you will receive the first
236       member of the list. If nonzero, you will receive the last member.
237
238       You may provide an optional index in order to force get() to return a
239       particular member of the list.  Provide a 0 to return the first member
240       of the list, or '#' to obtain the last member.
241
242       If the tag contains a period (.), get() will call index() on your
243       behalf (see below).
244
245       If the tag begins with an uppercase letter, then you can use the
246       autogenerated method to access it:
247
248         $stone->Tag_name([$index])
249
250       This is exactly equivalent to:
251
252         $stone->get('Teg_name' [,$index])
253
254   @values = $stone->search($tag)
255       Searches for the first occurrence of the tag, traversing the tree in a
256       breadth-first manner, and returns it.  This allows you to retrieve the
257       value of a tag in a deeply nested structure without worrying about all
258       the intermediate nodes.  For example:
259
260        $myStone = new Stone(Name=>'Fred',
261                             Friend=>['Jill',
262                                      'John',
263                                      'Gerald'
264                                     ],
265                             Attributes => { Hair => 'blonde',
266                                             Eyes => 'blue' }
267                           );
268
269          $hair_colour = $stone->search('Hair');
270
271       The disadvantage of this is that if there is a tag named "Hair" higher
272       in the hierarchy, this tag will be retrieved rather than the lower one.
273       In an array context this method returns the complete list of values
274       from the matching tag.  In a scalar context, it returns either the
275       first or the last value of multivalued tags depending as usual on the
276       value of $Stone::Fetchlast.
277
278       $Stone::Fetchlast is also consulted during the depth-first traversal.
279       If $Fetchlast is set to a true value, multivalued intermediate tags
280       will be searched from the last to the first rather than the first to
281       the last.
282
283       The Stone object has an AUTOLOAD method that invokes get() when you
284       call a method that is not predefined.  This allows a very convenient
285       type of shortcut:
286
287         $name        = $stone->Name;
288         @friends     = $stone->Friend;
289         $eye_color   = $stone->Attributes->Eyes
290
291       In the first example, we retrieve the value of the top-level tag Name.
292       In the second example, we retrieve the value of the Friend tag..  In
293       the third example, we retrieve the attributes stone first, then the
294       Eyes value.
295
296       NOTE: By convention, methods are only autogenerated for tags that begin
297       with capital letters.  This is necessary to avoid conflict with hard-
298       coded methods, all of which are lower case.
299
300   @values = $stone->index($indexstr)
301       You can access the contents of even deeply-nested Stone objects with
302       the "index" method.  You provide a tag path, and receive a value or
303       list of values back.
304
305       Tag paths look like this:
306
307               tag1[index1].tag2[index2].tag3[index3]
308
309       Numbers in square brackets indicate which member of a multivalued tag
310       you're interested in getting.  You can leave the square brackets out in
311       order to return just the first or the last tag of that name, in a
312       scalar context (depending on the setting of $Stone::Fetchlast).  In an
313       array context, leaving the square brackets out will return all
314       multivalued members for each tag along the path.
315
316       You will get a scalar value in a scalar context and an array value in
317       an array context following the same rules as get().  You can provide an
318       index of '#' in order to get the last member of a list or a [?] to
319       obtain a randomly chosen member of the list (this uses the rand() call,
320       so be sure to call srand() at the beginning of your program in order to
321       get different sequences of pseudorandom numbers.  If there is no tag by
322       that name, you will receive undef or an empty list.  If the tag points
323       to a subrecord, you will receive a Stone object.
324
325       Examples:
326
327               # Here's what the data structure looks like.
328               $s->insert(person=>{name=>Fred,
329                                   age=>30,
330                                   pets=>[Fido,Rex,Lassie],
331                                   children=>[Tom,Mary]},
332                          person=>{name=>Harry,
333                                   age=>23,
334                                   pets=>[Rover,Spot]});
335
336               # Return all of Fred's children
337               @children = $s->index('person[0].children');
338
339               # Return Harry's last pet
340               $pet = $s->index('person[1].pets[#]');
341
342               # Return first person's first child
343               $child = $s->index('person.children');
344
345               # Return children of all person's
346               @children = $s->index('person.children');
347
348               # Return last person's last pet
349               $Stone::Fetchlast++;
350               $pet = $s->index('person.pets');
351
352               # Return any pet from any person
353               $pet = $s->index('person[?].pet[?]');
354
355       Note that index() may return a Stone object if the tag path points to a
356       subrecord.
357
358   $array = $stone->at($tag)
359       This returns an ARRAY REFERENCE for the tag.  It is useful to prevent
360       automatic dereferencing.  Use with care.  It is equivalent to:
361
362               $stone->{'tag'}
363
364       at() will always return an array reference.  Single-valued tags will
365       return a reference to an array of size 1.
366
367   @tags = $stone->tags()
368       Return all the tags in the Stone.  You can then use this list with
369       get() to retrieve values or recursively traverse the stone.
370
371   $string = $stone->asTable()
372       Return the data structure as a tab-delimited table suitable for
373       printing.
374
375   $string = $stone->asXML([$tagname])
376       Return the data structure in XML format.  The entire data structure
377       will be placed inside a top-level tag called <Stone>.  If you wish to
378       change this top-level tag, pass it as an argument to asXML().
379
380       An example follows:
381
382        print $stone->asXML('Address_list');
383        # yields:
384        <?xml version="1.0" standalone="yes"?>
385
386        <Address_list>
387           <Sally>
388              <Address>
389                 <Zip>10578</Zip>
390                 <City>Katonah</City>
391                 <Street>Hickory Street</Street>
392                 <State>NY</State>
393              </Address>
394              <Last_name>Smith</Last_name>
395              <Age>30</Age>
396              <First_name>Sarah</First_name>
397           </Sally>
398           <Jim>
399              <Address>
400                 <Zip>11291</Zip>
401                 <City>Garden City</City>
402                 <Street>The Manse</Street>
403                 <Street>19 Chestnut Ln</Street>
404                 <State>NY</State>
405              </Address>
406              <Last_name>Hill</Last_name>
407              <Age>34</Age>
408              <First_name>James</First_name>
409           </Jim>
410        </Address_list>
411
412   $hash = $stone->attributes([$att_name, [$att_value]]])
413       attributes() returns the "attributes" of a tag.  Attributes are a
414       series of unique tag/value pairs which are associated with a tag, but
415       are not contained within it.  Attributes can only be expressed in the
416       XML representation of a Stone:
417
418          <Sally id="sally_tate" version="2.0">
419            <Address type="postal">
420                 <Zip>10578</Zip>
421                 <City>Katonah</City>
422                 <Street>Hickory Street</Street>
423                 <State>NY</State>
424              </Address>
425          </Sally>
426
427       Called with no arguments, attributes() returns the current attributes
428       as a hash ref:
429
430           my $att = $stone->Address->attributes;
431           my $type = $att->{type};
432
433       Called with a single argument, attributes() returns the value of the
434       named attribute, or undef if not defined:
435
436           my $type = $stone->Address->attributes('type');
437
438       Called with two arguments, attributes() sets the named attribute:
439
440           my $type = $stone->Address->attributes(type => 'Rural Free Delivery');
441
442       You may also change all attributes in one fell swoop by passing a hash
443       reference as the single argument:
444
445           $stone->attributes({id=>'Sally Mae',version=>'2.1'});
446
447   $string = $stone->toString()
448       toString() returns a simple version of the Stone that shows just the
449       topmost tags and the number of each type of tag.  For example:
450
451         print $stone->Jim->Address;
452             #yields => Zip(1),City(1),Street(2),State(1)
453
454       This method is used internally for string interpolation.  If you try to
455       print or otherwise manipulate a Stone object as a string, you will
456       obtain this type of string as a result.
457
458   $string = $stone->asHTML([\&callback])
459       Return the data structure as a nicely-formatted HTML 3.2 table,
460       suitable for display in a Web browser.  You may pass this method a
461       callback routine which will be called for every tag/value pair in the
462       object.  It will be passed a two-item list containing the current tag
463       and value.  It can make any modifications it likes and return the
464       modified tag and value as a return result.  You can use this to modify
465       tags or values on the fly, for example to turn them into HTML links.
466
467       For example, this code fragment will turn all tags named "Sequence"
468       blue:
469
470         my $callback = sub {
471               my ($tag,$value) = @_;
472               return ($tag,$value) unless $tag eq 'Sequence';
473               return ( qq(<FONT COLOR="blue">$tag</FONT>),$value );
474         }
475         print $stone->asHTML($callback);
476
477   Stone::dump()
478       This is a debugging tool.  It iterates through the Stone object and
479       prints out all the tags and values.
480
481       Example:
482
483               $s->dump;
484
485               person[0].children[0]=Tom
486               person[0].children[1]=Mary
487               person[0].name[0]=Fred
488               person[0].pets[0]=Fido
489               person[0].pets[1]=Rex
490               person[0].pets[2]=Lassie
491               person[0].age[0]=30
492               person[1].name[0]=Harry
493               person[1].pets[0]=Rover
494               person[1].pets[1]=Spot
495               person[1].age[0]=23
496
497   $cursor = $stone->cursor()
498       Retrieves an iterator over the object.  You can call this several times
499       in order to return independent iterators. The following brief example
500       is described in more detail in Stone::Cursor.
501
502        my $curs = $stone->cursor;
503        while (my($tag,$value) = $curs->next_pair) {
504          print "$tag => $value\n";
505        }
506        # yields:
507          Sally[0].Address[0].Zip[0] => 10578
508          Sally[0].Address[0].City[0] => Katonah
509          Sally[0].Address[0].Street[0] => Hickory Street
510          Sally[0].Address[0].State[0] => NY
511          Sally[0].Last_name[0] => James
512          Sally[0].Age[0] => 30
513          Sally[0].First_name[0] => Sarah
514          Jim[0].Address[0].Zip[0] => 11291
515          Jim[0].Address[0].City[0] => Garden City
516          Jim[0].Address[0].Street[0] => The Manse
517          Jim[0].Address[0].Street[1] => 19 Chestnut Ln
518          Jim[0].Address[0].State[0] => NY
519          Jim[0].Last_name[0] => Hill
520          Jim[0].Age[0] => 34
521          Jim[0].First_name[0] => James
522

AUTHOR

524       Lincoln D. Stein <lstein@cshl.org>.
525
527       Copyright 1997-1999, Cold Spring Harbor Laboratory, Cold Spring Harbor
528       NY.  This module can be used and distributed on the same terms as Perl
529       itself.
530

SEE ALSO

532       Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
533       Boulder::Omim, Boulder::SwissProt
534
535
536
537perl v5.36.0                      2022-07-22                          Stone(3)
Impressum