1Boulder(3) User Contributed Perl Documentation Boulder(3)
2
6 Boulder - An API for hierarchical tag/value structures
7
9 # Read a series of People records from STDIN.
10 # Add an "Eligibility" attribute to all those whose
11 # Age >= 35 and Friends list includes "Fred"
12 use Boulder::Stream;
14 my $stream = Boulder::Stream->newFh;
16 while ( my $record = <$stream> ) {
18 next unless $record->Age >= 35;
19 my @friends = $record->Friends;
20 next unless grep {$_ eq 'Fred'} @friends;
21 $record->insert(Eligibility => 'yes');
23 print $stream $record;
24 }
25 Related manual pages:
27 basics
29 ------
30 Stone hierarchical tag/value records
31 Stone::Cursor Traverse a hierarchy
32 Boulder::Stream stream-oriented storage for Stones
34 Boulder::Store record-oriented storage for Stones
35 Boulder::XML XML conversion for Stones
36 Boulder::String conversion to strings
37 genome-related
39 ---------------
40 Boulder::Genbank parse Genbank (DNA sequence) records
42 Boulder::Blast parse BLAST (basic local alignment search tool) reports
43 Boulder::Medline parse Medline (pubmed) records
44 Boulder::Omim parse OMIM (online Mendelian inheritance in man) records
45 Boulder::Swissprot parse Swissprot records
46 Boulder::Unigene parse Unigene records
47
49 Boulder IO
50 Boulder IO is a simple TAG=VALUE data format designed for sharing data
52 between programs connected via a pipe. It is also simple enough to use
53 as a common data exchange format between databases, Web pages, and
54 other data representations.
55 The basic data format is very simple. It consists of a series of
57 TAG=VALUE pairs separated by newlines. It is record-oriented. The end
58 of a record is indicated by an empty delimiter alone on a line. The
59 delimiter is "=" by default, but can be adjusted by the user.
60 An example boulder stream looks like this:
62 Name=Lincoln Stein
64 Home=/u/bush202/lds32
65 Organization=Cold Spring Harbor Laboratory
66 Login=lds32
67 Password_age=20
68 Password_expires=60
69 Alias=lstein
70 Alias=steinl
71 =
72 Name=Leigh Deacon
73 Home=/u/bush202/tanager
74 Organization=Cold Spring Harbor Laboratory
75 Login=tanager
76 Password_age=2
77 Password_expires=60
78 =
79 Notes:
81 (1) There is no need for all tags to appear in all records, or indeed
83 for all the records to be homogeneous.
84 (2) Multiple values are allowed, as with the Alias tag in the second
86 record.
87 (3) Lines can be any length, as in a potential 40 Kbp DNA sequence
89 entry.
90 (4) Tags can be any alphanumeric character (upper or lower case) and
92 may contain embedded spaces. Conventionally we use the characters
93 A-Z0-9_, because they can be used without single quoting as keys in
94 Perl associative arrays, but this is merely stylistic. Values can
95 be any character at all except for the reserved characters {}=% and
96 newline. You can incorporate binary data into the data stream by
97 escaping these characters in the URL manner, using a % sign fol‐
98 lowed by the (capitalized) hexadecimal code for the character. The
99 module makes this automatic.
100 Hierarchical Records
102 The simple boulder format can be extended to accomodate nested rela‐
104 tions and other intresting structures. Nested records can be created
105 in this way:
106 Name=Lincoln Stein
108 Home=/u/bush202/lds32
109 Organization=Cold Spring Harbor Laboratory
110 Login=lds32
111 Password_age=20
112 Password_expires=60
113 Privileges={
114 ChangePasswd=yes
115 CronJobs=yes
116 Reboot=yes
117 Shutdown=no
118 }
119 =
120 Name=Leigh Deacon
121 Home=/u/bush202/tanager
122 Organization=Cold Spring Harbor Laboratory
123 Login=tanager
124 Password_age=2
125 Password_expires=60
126 Privileges={
127 ChangePasswd=yes
128 CronJobs=no
129 Reboot=no
130 Shutdown=no
131 }
132 =
133 As in the original format, tags may be multivalued. For example, there
135 might be several Privilege record assigned to a login account. Each
136 subrecord may contain further subrecords.
137 Within the program, a hierarchical record is encapsulated within a
139 "Stone", an opaque structure that implements methods for fetching and
140 settings its various tags.
141 Using Boulder for I/O
143 The Boulder API was designed to make reading and writing of complex
145 hierarchical records almost as easy as reading and writing single lines
146 of text.
147 Boulder::Stream
149 The main component of the Boulder modules is Boulder::Stream, which
150 provides a stream-oriented view of the data. You can read and
151 write to Boulder::Streams via tied filehandles, or via method
152 calls. Data records are flattened into a simple format called
153 "boulderio" format.
154 Boulder::XML
156 Boulder::XML acts like Boulder::Stream, but the serialization for‐
157 mat is XML. You need XML::Parser installed to use this module.
158 Boulder::Store
160 This is a simple persistent storage class which allows you to store
161 several (thousand) Stone's into a DB_File database. You must have
162 libdb and the Perl DB_File extensions installed in order to take
163 advantage of this class.
164 Boulder::Genbank
166 Boulder::Unigene
167 Boulder::OMIM
168 Boulder::Blast
169 Boulder::Medline
170 Boulder::SwissProt
171 These are parsers and accessors for various biological data
172 sources. They act like Boulder::Stream, but return a set of Stone
173 objects that have certain prescribed tags and values. Many of
174 these modules were written by Luca I.G. Toldo
175 <luca.toldo@merck.de>.
176 Stone Objects
178 The Stone object encapsulates a set of tags and values. Any tag can be
180 single- or multivalued, and tags are allowed to contain subtags to any
181 depth. A simple set of methods named tags(), get(), put(), insert(),
182 replace() and so forth, allows you to examine the tags that are avail‐
183 able, get and set their values, and search for particular tags. In
184 addition, an autoload mechanism allows you to use method calls to
185 access tags, for example:
186 my @friends = $record->Friends;
188 is equivalent to:
190 my @friends = $record->get('Friends');
192 A Stone::Cursor class allows you to traverse Stones systematically.
194 A full explanation of the Stone class can be found in its manual page.
196
198 Lincoln D. Stein <lstein@cshl.org>, Cold Spring Harbor Laboratory, Cold
199 Spring Harbor, NY. This module can be used and distributed on the same
200 terms as Perl itself.
201
203 Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
204 Boulder::Omim, Boulder::SwissProt
205perl v5.8.8 2000-06-08 Boulder(3)