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

NAME

6       Boulder - An API for hierarchical tag/value structures
7

SYNOPSIS

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
13          use Boulder::Stream;
14
15          my $stream = Boulder::Stream->newFh;
16
17          while ( my $record = <$stream> ) {
18             next unless $record->Age >= 35;
19             my @friends = $record->Friends;
20             next unless grep {$_ eq 'Fred'} @friends;
21
22             $record->insert(Eligibility => 'yes');
23             print $stream $record;
24           }
25
26       Related manual pages:
27
28         basics
29         ------
30         Stone            hierarchical tag/value records
31         Stone::Cursor    Traverse a hierarchy
32
33         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
38         genome-related
39         ---------------
40
41         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

DESCRIPTION

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
55       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
60       An example boulder stream looks like this:
61
62               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
79       Notes:
80
81       (1) There is no need for all tags to appear in all records, or indeed
82           for all the records to be homogeneous.
83
84       (2) Multiple values are allowed, as with the Alias tag in the second
85           record.
86
87       (3) Lines can be any length, as in a potential 40 Kbp DNA sequence
88           entry.
89
90       (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
100   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
105        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
132       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
136       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
140   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
145       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
152       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
156       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
162       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
174   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
183          my @friends = $record->Friends;
184
185       is equivalent to:
186
187          my @friends = $record->get('Friends');
188
189       A Stone::Cursor class allows you to traverse Stones systematically.
190
191       A full explanation of the Stone class can be found in its manual page.
192

AUTHOR

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

SEE ALSO

199       Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
200       Boulder::Omim, Boulder::SwissProt
201
202
203
204perl v5.12.0                      2000-06-20                        Boulder(3)
Impressum