1Stone(3) User Contributed Perl Documentation Stone(3)
2
6 Stone - In-memory storage for hierarchical tag/value data structures
7
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 @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 $address = $stone->get('Jim')->get('Address'); # same as $stone->Jim->Address
36 $address = $stone->get('Jim.Address'); # another way to express same thing
37 # 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 # insert a tag/value pair
46 $stone->insert(Martha => { First_name => 'Martha', Last_name => 'Steward'} );
47 # find the first Address
49 $stone->search('Address');
50 # change an existing subtree
52 $martha = $stone->Martha;
53 $martha->replace(Last_name => 'Stewart'); # replace a value
54 # 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 # various format conversions
62 print $stone->asTable;
63 print $stone->asString;
64 print $stone->asHTML;
65 print $stone->asXML('Person');
66
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 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 Stone was designed for subclassing. You should be able to create sub‐
80 classes which create or require particular tags and data formats. Cur‐
81 rently only Stone::GB_Sequence subclasses Stone.
82
84 Stones are either created by calling the new() method, or by reading
85 them from a Boulder::Stream or persistent database.
86 $stone = Stone->new()
88 This is the main constructor for the Stone class. It can be called
90 without any parameters, in which case it creates an empty Stone object
91 (no tags or values), or it may passed an associative array in order to
92 initialize it with a set of tags. A tag's value may be a scalar, an
93 anonymous array reference (constructed using [] brackets), or a hash
94 references (constructed using {} brackets). In the first case, the tag
95 will be single-valued. In the second, the tag will be multivalued. In
96 the third case, a subsidiary Stone will be generated automatically and
97 placed into the tree at the specified location.
98 Examples:
100 $myStone = new Stone;
102 $myStone = new Stone(Name=>'Fred',Age=>30);
103 $myStone = new Stone(Name=>'Fred',
104 Friend=>['Jill','John','Jerry']);
105 $myStone = new Stone(Name=>'Fred',
106 Friend=>['Jill',
107 'John',
108 'Gerald'
109 ],
110 Attributes => { Hair => 'blonde',
111 Eyes => 'blue' }
112 );
113 In the last example, a Stone with the following structure is created:
115 Name Fred
117 Friend Jill
118 Friend John
119 Friend Gerald
120 Attributes Eyes blue
121 Hair blonde
122 Note that the value corresponding to the tag "Attributes" is itself a
124 Stone with two tags, "Eyes" and "Hair".
125 The XML representation (which could be created with asXML()) looks like
127 this:
128 <?xml version="1.0" standalone="yes"?>
130 <Stone>
131 <Attributes>
132 <Eyes>blue</Eyes>
133 <Hair>blonde</Hair>
134 </Attributes>
135 <Friend>Jill</Friend>
136 <Friend>John</Friend>
137 <Friend>Gerald</Friend>
138 <Name>Fred</Name>
139 </Stone>
140 More information on Stone initialization is given in the description of
142 the insert() method.
143
145 Once a Stone object is created or retrieved, you can manipulate it with
146 the following methods.
147 $stone->insert(%hash)
149 $stone->insert(\%hash)
151 This is the main method for adding tags to a Stone. This method
153 expects an associative array as an argument or a reference to one. The
154 contents of the associative array will be inserted into the Stone. If
155 a particular tag is already present in the Stone, the tag's current
156 value will be appended to the list of values for that tag. Several
157 types of values are legal:
158 * A scalar value
160 The value will be inserted into the "Stone".
161 $stone->insert(name=>Fred,
163 age=>30,
164 sex=>M);
165 $stone->dump;
166 name[0]=Fred
168 age[0]=30
169 sex[0]=M
170 * An ARRAY reference
172 A multi-valued tag will be created:
173 $stone->insert(name=>Fred,
175 children=>[Tom,Mary,Angelique]);
176 $stone->dump;
177 name[0]=Fred
179 children[0]=Tom
180 children[1]=Mary
181 children[2]=Angelique
182 * A HASH reference
184 A subsidiary "Stone" object will be created and inserted into the
185 object as a nested structure.
186 $stone->insert(name=>Fred,
188 wife=>{name=>Agnes,age=>40});
189 $stone->dump;
190 name[0]=Fred
192 wife[0].name[0]=Agnes
193 wife[0].age[0]=40
194 * A "Stone" object or subclass
196 The "Stone" object will be inserted into the object as a nested
197 structure.
198 $wife = new Stone(name=>agnes,
200 age=>40);
201 $husband = new Stone;
202 $husband->insert(name=>fred,
203 wife=>$wife);
204 $husband->dump;
205 name[0]=fred
207 wife[0].name[0]=agnes
208 wife[0].age[0]=40
209 $stone->replace(%hash)
211 $stone->replace(\%hash)
213 The replace() method behaves exactly like "insert()" with the exception
215 that if the indicated key already exists in the Stone, its value will
216 be replaced. Use replace() when you want to enforce a single-valued
217 tag/value relationship.
218 $stone->insert_list($key,@list) =head2 $stone->insert_hash($key,%hash)
220 =head2 $stone->replace_list($key,@list) =head2
221 $stone->replace_hash($key,%hash)
222 These are primitives used by the "insert()" and "replace()" methods.
224 Override them if you need to modify the default behavior.
225 $stone->delete($tag)
227 This removes the indicated tag from the Stone.
229 @values = $stone->get($tag [,$index])
231 This returns the value at the indicated tag and optional index. What
233 you get depends on whether it is called in a scalar or list context.
234 In a list context, you will receive all the values for that tag. You
235 may receive a list of scalar values or (for a nested record) or a list
236 of Stone objects. If called in a scalar context, you will either
237 receive the first or the last member of the list of values assigned to
238 the tag. Which one you receive depends on the value of the package
239 variable $Stone::Fetchlast. If undefined, you will receive the first
240 member of the list. If nonzero, you will receive the last member.
241 You may provide an optional index in order to force get() to return a
243 particular member of the list. Provide a 0 to return the first member
244 of the list, or '#' to obtain the last member.
245 If the tag contains a period (.), get() will call index() on your
247 behalf (see below).
248 If the tag begins with an uppercase letter, then you can use the auto‐
250 generated method to access it:
251 $stone->Tag_name([$index])
253 This is exactly equivalent to:
255 $stone->get('Teg_name' [,$index])
257 @values = $stone->search($tag)
259 Searches for the first occurrence of the tag, traversing the tree in a
261 breadth-first manner, and returns it. This allows you to retrieve the
262 value of a tag in a deeply nested structure without worrying about all
263 the intermediate nodes. For example:
264 $myStone = new Stone(Name=>'Fred',
266 Friend=>['Jill',
267 'John',
268 'Gerald'
269 ],
270 Attributes => { Hair => 'blonde',
271 Eyes => 'blue' }
272 );
273 $hair_colour = $stone->search('Hair');
275 The disadvantage of this is that if there is a tag named "Hair" higher
277 in the hierarchy, this tag will be retrieved rather than the lower one.
278 In an array context this method returns the complete list of values
279 from the matching tag. In a scalar context, it returns either the
280 first or the last value of multivalued tags depending as usual on the
281 value of $Stone::Fetchlast.
282 $Stone::Fetchlast is also consulted during the depth-first traversal.
284 If $Fetchlast is set to a true value, multivalued intermediate tags
285 will be searched from the last to the first rather than the first to
286 the last.
287 The Stone object has an AUTOLOAD method that invokes get() when you
289 call a method that is not predefined. This allows a very convenient
290 type of shortcut:
291 $name = $stone->Name;
293 @friends = $stone->Friend;
294 $eye_color = $stone->Attributes->Eyes
295 In the first example, we retrieve the value of the top-level tag Name.
297 In the second example, we retrieve the value of the Friend tag.. In
298 the third example, we retrieve the attributes stone first, then the
299 Eyes value.
300 NOTE: By convention, methods are only autogenerated for tags that begin
302 with capital letters. This is necessary to avoid conflict with hard-
303 coded methods, all of which are lower case.
304 @values = $stone->index($indexstr)
306 You can access the contents of even deeply-nested Stone objects with
308 the "index" method. You provide a tag path, and receive a value or
309 list of values back.
310 Tag paths look like this:
312 tag1[index1].tag2[index2].tag3[index3]
314 Numbers in square brackets indicate which member of a multivalued tag
316 you're interested in getting. You can leave the square brackets out in
317 order to return just the first or the last tag of that name, in a
318 scalar context (depending on the setting of $Stone::Fetchlast). In an
319 array context, leaving the square brackets out will return all multi‐
320 valued members for each tag along the path.
321 You will get a scalar value in a scalar context and an array value in
323 an array context following the same rules as get(). You can provide an
324 index of '#' in order to get the last member of a list or a [?] to
325 obtain a randomly chosen member of the list (this uses the rand() call,
326 so be sure to call srand() at the beginning of your program in order to
327 get different sequences of pseudorandom numbers. If there is no tag by
328 that name, you will receive undef or an empty list. If the tag points
329 to a subrecord, you will receive a Stone object.
330 Examples:
332 # Here's what the data structure looks like.
334 $s->insert(person=>{name=>Fred,
335 age=>30,
336 pets=>[Fido,Rex,Lassie],
337 children=>[Tom,Mary]},
338 person=>{name=>Harry,
339 age=>23,
340 pets=>[Rover,Spot]});
341 # Return all of Fred's children
343 @children = $s->index('person[0].children');
344 # Return Harry's last pet
346 $pet = $s->index('person[1].pets[#]');
347 # Return first person's first child
349 $child = $s->index('person.children');
350 # Return children of all person's
352 @children = $s->index('person.children');
353 # Return last person's last pet
355 $Stone::Fetchlast++;
356 $pet = $s->index('person.pets');
357 # Return any pet from any person
359 $pet = $s->index('person[?].pet[?]');
360 Note that index() may return a Stone object if the tag path points to a
362 subrecord.
363 $array = $stone->at($tag)
365 This returns an ARRAY REFERENCE for the tag. It is useful to prevent
367 automatic dereferencing. Use with care. It is equivalent to:
368 $stone->{'tag'}
370 at() will always return an array reference. Single-valued tags will
372 return a reference to an array of size 1.
373 @tags = $stone->tags()
375 Return all the tags in the Stone. You can then use this list with
377 get() to retrieve values or recursively traverse the stone.
378 $string = $stone->asTable()
380 Return the data structure as a tab-delimited table suitable for print‐
382 ing.
383 $string = $stone->asXML([$tagname])
385 Return the data structure in XML format. The entire data structure
387 will be placed inside a top-level tag called <Stone>. If you wish to
388 change this top-level tag, pass it as an argument to asXML().
389 An example follows:
391 print $stone->asXML('Address_list');
393 # yields:
394 <?xml version="1.0" standalone="yes"?>
395 <Address_list>
397 <Sally>
398 <Address>
399 <Zip>10578</Zip>
400 <City>Katonah</City>
401 <Street>Hickory Street</Street>
402 <State>NY</State>
403 </Address>
404 <Last_name>Smith</Last_name>
405 <Age>30</Age>
406 <First_name>Sarah</First_name>
407 </Sally>
408 <Jim>
409 <Address>
410 <Zip>11291</Zip>
411 <City>Garden City</City>
412 <Street>The Manse</Street>
413 <Street>19 Chestnut Ln</Street>
414 <State>NY</State>
415 </Address>
416 <Last_name>Hill</Last_name>
417 <Age>34</Age>
418 <First_name>James</First_name>
419 </Jim>
420 </Address_list>
421 $hash = $stone->attributes([$att_name, [$att_value]]])
423 attributes() returns the "attributes" of a tag. Attributes are a
425 series of unique tag/value pairs which are associated with a tag, but
426 are not contained within it. Attributes can only be expressed in the
427 XML representation of a Stone:
428 <Sally id="sally_tate" version="2.0">
430 <Address type="postal">
431 <Zip>10578</Zip>
432 <City>Katonah</City>
433 <Street>Hickory Street</Street>
434 <State>NY</State>
435 </Address>
436 </Sally>
437 Called with no arguments, attributes() returns the current attributes
439 as a hash ref:
440 my $att = $stone->Address->attributes;
442 my $type = $att->{type};
443 Called with a single argument, attributes() returns the value of the
445 named attribute, or undef if not defined:
446 my $type = $stone->Address->attributes('type');
448 Called with two arguments, attributes() sets the named attribute:
450 my $type = $stone->Address->attributes(type => 'Rural Free Delivery');
452 You may also change all attributes in one fell swoop by passing a hash
454 reference as the single argument:
455 $stone->attributes({id=>'Sally Mae',version=>'2.1'});
457 $string = $stone->toString()
459 toString() returns a simple version of the Stone that shows just the
461 topmost tags and the number of each type of tag. For example:
462 print $stone->Jim->Address;
464 #yields => Zip(1),City(1),Street(2),State(1)
465 This method is used internally for string interpolation. If you try to
467 print or otherwise manipulate a Stone object as a string, you will
468 obtain this type of string as a result.
469 $string = $stone->asHTML([\&callback])
471 Return the data structure as a nicely-formatted HTML 3.2 table, suit‐
473 able for display in a Web browser. You may pass this method a callback
474 routine which will be called for every tag/value pair in the object.
475 It will be passed a two-item list containing the current tag and value.
476 It can make any modifications it likes and return the modified tag and
477 value as a return result. You can use this to modify tags or values on
478 the fly, for example to turn them into HTML links.
479 For example, this code fragment will turn all tags named "Sequence"
481 blue:
482 my $callback = sub {
484 my ($tag,$value) = @_;
485 return ($tag,$value) unless $tag eq 'Sequence';
486 return ( qq(<FONT COLOR="blue">$tag</FONT>),$value );
487 }
488 print $stone->asHTML($callback);
489 Stone::dump()
491 This is a debugging tool. It iterates through the Stone object and
493 prints out all the tags and values.
494 Example:
496 $s->dump;
498 person[0].children[0]=Tom
500 person[0].children[1]=Mary
501 person[0].name[0]=Fred
502 person[0].pets[0]=Fido
503 person[0].pets[1]=Rex
504 person[0].pets[2]=Lassie
505 person[0].age[0]=30
506 person[1].name[0]=Harry
507 person[1].pets[0]=Rover
508 person[1].pets[1]=Spot
509 person[1].age[0]=23
510 $cursor = $stone->cursor()
512 Retrieves an iterator over the object. You can call this several times
514 in order to return independent iterators. The following brief example
515 is described in more detail in Stone::Cursor.
516 my $curs = $stone->cursor;
518 while (my($tag,$value) = $curs->next_pair) {
519 print "$tag => $value\n";
520 }
521 # yields:
522 Sally[0].Address[0].Zip[0] => 10578
523 Sally[0].Address[0].City[0] => Katonah
524 Sally[0].Address[0].Street[0] => Hickory Street
525 Sally[0].Address[0].State[0] => NY
526 Sally[0].Last_name[0] => James
527 Sally[0].Age[0] => 30
528 Sally[0].First_name[0] => Sarah
529 Jim[0].Address[0].Zip[0] => 11291
530 Jim[0].Address[0].City[0] => Garden City
531 Jim[0].Address[0].Street[0] => The Manse
532 Jim[0].Address[0].Street[1] => 19 Chestnut Ln
533 Jim[0].Address[0].State[0] => NY
534 Jim[0].Last_name[0] => Hill
535 Jim[0].Age[0] => 34
536 Jim[0].First_name[0] => James
537
539 Lincoln D. Stein <lstein@cshl.org>.
540
542 Copyright 1997-1999, Cold Spring Harbor Laboratory, Cold Spring Harbor
543 NY. This module can be used and distributed on the same terms as Perl
544 itself.
545
547 Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
548 Boulder::Omim, Boulder::SwissProt
549perl v5.8.8 2000-06-08 Stone(3)