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
80 subclasses which create or require particular tags and data formats.
81 Currently 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
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 Examples:
99 $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 In the last example, a Stone with the following structure is created:
114 Name Fred
116 Friend Jill
117 Friend John
118 Friend Gerald
119 Attributes Eyes blue
120 Hair blonde
121 Note that the value corresponding to the tag "Attributes" is itself a
123 Stone with two tags, "Eyes" and "Hair".
124 The XML representation (which could be created with asXML()) looks like
126 this:
127 <?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 More information on Stone initialization is given in the description of
141 the insert() method.
142
144 Once a Stone object is created or retrieved, you can manipulate it with
145 the following methods.
146 $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 • A scalar value
157 The value will be inserted into the "Stone".
159 $stone->insert(name=>Fred,
161 age=>30,
162 sex=>M);
163 $stone->dump;
164 name[0]=Fred
166 age[0]=30
167 sex[0]=M
168 • An ARRAY reference
170 A multi-valued tag will be created:
172 $stone->insert(name=>Fred,
174 children=>[Tom,Mary,Angelique]);
175 $stone->dump;
176 name[0]=Fred
178 children[0]=Tom
179 children[1]=Mary
180 children[2]=Angelique
181 • A HASH reference
183 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
198 structure.
199 $wife = new Stone(name=>agnes,
201 age=>40);
202 $husband = new Stone;
203 $husband->insert(name=>fred,
204 wife=>$wife);
205 $husband->dump;
206 name[0]=fred
208 wife[0].name[0]=agnes
209 wife[0].age[0]=40
210 $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 $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 $stone->delete($tag)
225 This removes the indicated tag from the Stone.
226 @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 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 If the tag contains a period (.), get() will call index() on your
243 behalf (see below).
244 If the tag begins with an uppercase letter, then you can use the
246 autogenerated method to access it:
247 $stone->Tag_name([$index])
249 This is exactly equivalent to:
251 $stone->get('Teg_name' [,$index])
253 @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 $myStone = new Stone(Name=>'Fred',
261 Friend=>['Jill',
262 'John',
263 'Gerald'
264 ],
265 Attributes => { Hair => 'blonde',
266 Eyes => 'blue' }
267 );
268 $hair_colour = $stone->search('Hair');
270 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 $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 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 $name = $stone->Name;
288 @friends = $stone->Friend;
289 $eye_color = $stone->Attributes->Eyes
290 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 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 @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 Tag paths look like this:
306 tag1[index1].tag2[index2].tag3[index3]
308 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 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 Examples:
326 # 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 # Return all of Fred's children
337 @children = $s->index('person[0].children');
338 # Return Harry's last pet
340 $pet = $s->index('person[1].pets[#]');
341 # Return first person's first child
343 $child = $s->index('person.children');
344 # Return children of all person's
346 @children = $s->index('person.children');
347 # Return last person's last pet
349 $Stone::Fetchlast++;
350 $pet = $s->index('person.pets');
351 # Return any pet from any person
353 $pet = $s->index('person[?].pet[?]');
354 Note that index() may return a Stone object if the tag path points to a
356 subrecord.
357 $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 $stone->{'tag'}
363 at() will always return an array reference. Single-valued tags will
365 return a reference to an array of size 1.
366 @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 $string = $stone->asTable()
372 Return the data structure as a tab-delimited table suitable for
373 printing.
374 $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 An example follows:
381 print $stone->asXML('Address_list');
383 # yields:
384 <?xml version="1.0" standalone="yes"?>
385 <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 $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 <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 Called with no arguments, attributes() returns the current attributes
428 as a hash ref:
429 my $att = $stone->Address->attributes;
431 my $type = $att->{type};
432 Called with a single argument, attributes() returns the value of the
434 named attribute, or undef if not defined:
435 my $type = $stone->Address->attributes('type');
437 Called with two arguments, attributes() sets the named attribute:
439 my $type = $stone->Address->attributes(type => 'Rural Free Delivery');
441 You may also change all attributes in one fell swoop by passing a hash
443 reference as the single argument:
444 $stone->attributes({id=>'Sally Mae',version=>'2.1'});
446 $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 print $stone->Jim->Address;
452 #yields => Zip(1),City(1),Street(2),State(1)
453 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 $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 For example, this code fragment will turn all tags named "Sequence"
468 blue:
469 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 Stone::dump()
478 This is a debugging tool. It iterates through the Stone object and
479 prints out all the tags and values.
480 Example:
482 $s->dump;
484 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 $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 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
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
532 Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
533 Boulder::Omim, Boulder::SwissProt
534perl v5.36.0 2022-07-22 Stone(3)