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
51 between programs connected via a pipe. It is also simple enough to use
52 as a common data exchange format between databases, Web pages, and
53 other data representations.
54 The basic data format is very simple. It consists of a series of
56 TAG=VALUE pairs separated by newlines. It is record-oriented. The end
57 of a record is indicated by an empty delimiter alone on a line. The
58 delimiter is "=" by default, but can be adjusted by the user.
59 An example boulder stream looks like this:
61 Name=Lincoln Stein
63 Home=/u/bush202/lds32
64 Organization=Cold Spring Harbor Laboratory
65 Login=lds32
66 Password_age=20
67 Password_expires=60
68 Alias=lstein
69 Alias=steinl
70 =
71 Name=Leigh Deacon
72 Home=/u/bush202/tanager
73 Organization=Cold Spring Harbor Laboratory
74 Login=tanager
75 Password_age=2
76 Password_expires=60
77 =
78 Notes:
80 (1) There is no need for all tags to appear in all records, or indeed
82 for all the records to be homogeneous.
83 (2) Multiple values are allowed, as with the Alias tag in the second
85 record.
86 (3) Lines can be any length, as in a potential 40 Kbp DNA sequence
88 entry.
89 (4) Tags can be any alphanumeric character (upper or lower case) and
91 may contain embedded spaces. Conventionally we use the characters
92 A-Z0-9_, because they can be used without single quoting as keys in
93 Perl associative arrays, but this is merely stylistic. Values can
94 be any character at all except for the reserved characters {}=% and
95 newline. You can incorporate binary data into the data stream by
96 escaping these characters in the URL manner, using a % sign
97 followed by the (capitalized) hexadecimal code for the character.
98 The module makes this automatic.
99 Hierarchical Records
101 The simple boulder format can be extended to accomodate nested
102 relations and other intresting structures. Nested records can be
103 created in this way:
104 Name=Lincoln Stein
106 Home=/u/bush202/lds32
107 Organization=Cold Spring Harbor Laboratory
108 Login=lds32
109 Password_age=20
110 Password_expires=60
111 Privileges={
112 ChangePasswd=yes
113 CronJobs=yes
114 Reboot=yes
115 Shutdown=no
116 }
117 =
118 Name=Leigh Deacon
119 Home=/u/bush202/tanager
120 Organization=Cold Spring Harbor Laboratory
121 Login=tanager
122 Password_age=2
123 Password_expires=60
124 Privileges={
125 ChangePasswd=yes
126 CronJobs=no
127 Reboot=no
128 Shutdown=no
129 }
130 =
131 As in the original format, tags may be multivalued. For example, there
133 might be several Privilege record assigned to a login account. Each
134 subrecord may contain further subrecords.
135 Within the program, a hierarchical record is encapsulated within a
137 "Stone", an opaque structure that implements methods for fetching and
138 settings its various tags.
139 Using Boulder for I/O
141 The Boulder API was designed to make reading and writing of complex
142 hierarchical records almost as easy as reading and writing single lines
143 of text.
144 Boulder::Stream
146 The main component of the Boulder modules is Boulder::Stream, which
147 provides a stream-oriented view of the data. You can read and
148 write to Boulder::Streams via tied filehandles, or via method
149 calls. Data records are flattened into a simple format called
150 "boulderio" format.
151 Boulder::XML
153 Boulder::XML acts like Boulder::Stream, but the serialization
154 format is XML. You need XML::Parser installed to use this module.
155 Boulder::Store
157 This is a simple persistent storage class which allows you to store
158 several (thousand) Stone's into a DB_File database. You must have
159 libdb and the Perl DB_File extensions installed in order to take
160 advantage of this class.
161 Boulder::Genbank
163 Boulder::Unigene
164 Boulder::OMIM
165 Boulder::Blast
166 Boulder::Medline
167 Boulder::SwissProt
168 These are parsers and accessors for various biological data
169 sources. They act like Boulder::Stream, but return a set of Stone
170 objects that have certain prescribed tags and values. Many of
171 these modules were written by Luca I.G. Toldo
172 <luca.toldo@merck.de>.
173 Stone Objects
175 The Stone object encapsulates a set of tags and values. Any tag can be
176 single- or multivalued, and tags are allowed to contain subtags to any
177 depth. A simple set of methods named tags(), get(), put(), insert(),
178 replace() and so forth, allows you to examine the tags that are
179 available, get and set their values, and search for particular tags.
180 In addition, an autoload mechanism allows you to use method calls to
181 access tags, for example:
182 my @friends = $record->Friends;
184 is equivalent to:
186 my @friends = $record->get('Friends');
188 A Stone::Cursor class allows you to traverse Stones systematically.
190 A full explanation of the Stone class can be found in its manual page.
192
194 Lincoln D. Stein <lstein@cshl.org>, Cold Spring Harbor Laboratory, Cold
195 Spring Harbor, NY. This module can be used and distributed on the same
196 terms as Perl itself.
197
199 Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
200 Boulder::Omim, Boulder::SwissProt
201perl v5.36.0 2022-07-22 Boulder(3)