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

NAME

6       Boulder::Stream - Read and write tag/value data from an input stream
7

SYNOPSIS

9          #!/bin/perl
10          # Read a series of People records from STDIN.
11          # Add an "Eligible" tag to all those whose
12          # Age >= 35 and Friends list includes "Fred"
13          use Boulder::Stream;
14
15          # filestream way:
16          my $stream = Boulder::Stream->newFh;
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(Eligible => 'yes');
23             print $stream $record;
24           }
25
26           # object oriented way:
27          my $stream = Boulder::Stream->new;
28          while (my $record = $stream->get ) {
29             next unless $record->Age >= 35;
30             my @friends = $record->Friends;
31             next unless grep {$_ eq 'Fred'} @friends;
32
33             $record->insert(Eligible => 'yes');
34             print $stream $record;
35           }
36

DESCRIPTION

38       Boulder::Stream provides stream-oriented access to Boulder IO
39       hierarchical tag/value data.  It can be used in a magic tied filehandle
40       mode, as shown in the synopsis, or in object-oriented mode.  Using tied
41       filehandles, Stone objects are read from input using the standard <>
42       operator.  Stone objects printed to the tied filehandle appear on the
43       output stream in Boulder format.
44
45       By default, data is read from the magic ARGV filehandle (STDIN or a
46       list of files provided on the command line) and written to STDOUT.
47       This can be changed to the filehandles of your choice.
48
49   Pass through behavior
50       When using the object-oriented form of Boulder::Stream, tags which
51       aren't specifically requested by the get() method are passed through to
52       output unchanged.  This allows pipes of programs to be constructed
53       easily. Most programs will want to put the tags back into the boulder
54       stream once they're finished, potentially adding their own.  Of course
55       some programs will want to behave differently.  For example, a database
56       query program will generate but not read a boulderio stream, while a
57       report generator will read but not write the stream.
58
59       This convention allows the following type of pipe to be set up:
60
61         query_database | find_vector | find_dups | \
62           | blast_sequence | pick_primer | mail_report
63
64       If all the programs in the pipe follow the conventions, then it will be
65       possible to interpose other programs, such as a repetitive element
66       finder, in the middle of the pipe without disturbing other components.
67

SKELETON BOULDER PROGRAM

69       Here is a skeleton example.
70
71          #!/bin/perl
72          use Boulder::Stream;
73
74          my $stream = Boulder::Stream->newFh;
75
76          while ( my $record = <$stream> ) {
77             next unless $record->Age >= 35;
78             my @friends = $record->Friends;
79             next unless grep {$_ eq 'Fred'} @friends;
80
81             $record->insert(Eligible => 'yes');
82             print $stream $record;
83           }
84
85       The code starts by creating a Boulder::Stream object to handle the I/O.
86       It reads from the stream one record at a time, returning a Stone
87       object.  We recover the Age and Friends tags, and continue looping
88       unless the Age is greater or equal to 35, and the list of Friends
89       contains "Fred".  If these criteria match, then we insert a new tag
90       named Eligible and print the record to the stream.  The output may look
91       like this:
92
93         Name=Janice
94         Age=36
95         Eligible=yes
96         Friends=Susan
97         Friends=Fred
98         Friends=Ralph
99         =
100         Name=Ralph
101         Age=42
102         Eligible=yes
103         Friends=Janice
104         Friends=Fred
105         =
106         Name=Susan
107         Age=35
108         Eligible=yes
109         Friends=Susan
110         Friends=Fred
111         =
112
113       Note that in this case only records that meet the criteria are echoed
114       to standard output.  The object-oriented version of the program looks
115       like this:
116
117          #!/bin/perl
118          use Boulder::Stream;
119
120          my $stream = Boulder::Stream->new;
121
122          while ( my $record = $stream->get('Age','Friends') ) {
123             next unless $record->Age >= 35;
124             my @friends = $record->Friends;
125             next unless grep {$_ eq 'Fred'} @friends;
126
127             $record->insert(Eligible => 'yes');
128             $stream->put($record);
129           }
130
131       The get() method is used to fetch Stones containing one or more of the
132       indicated tags.  The put() method is used to send the result to
133       standard output.  The pass-through behavior might produce a set of
134       records like this one:
135
136         Name=Janice
137         Age=36
138         Eligible=yes
139         Friends=Susan
140         Friends=Fred
141         Friends=Ralph
142         =
143         Name=Phillip
144         Age=30
145         =
146         Name=Ralph
147         Age=42
148         Eligible=yes
149         Friends=Janice
150         Friends=Fred
151         =
152         Name=Barbara
153         Friends=Agatha
154         Friends=Janice
155         =
156         Name=Susan
157         Age=35
158         Eligible=yes
159         Friends=Susan
160         Friends=Fred
161         =
162
163       Notice that there are now two records ("Phillip" and "Barbara") that do
164       not contain the Eligible tag.
165

Boulder::Stream METHODS

167   $stream = Boulder::Stream->new(*IN,*OUT)
168   $stream = Boulder::Stream->new(-in=>*IN,-out=>*OUT)
169       The new() method creates a new Boulder::Stream object.  You can provide
170       input and output filehandles. If you leave one or both undefined new()
171       will default to standard input or standard output.  You are free to use
172       files, pipes, sockets, and other types of file handles.  You may
173       provide the filehandle arguments as bare words, globs, or glob refs.
174       You are also free to use the named argument style shown in the second
175       heading.
176
177   $fh = Boulder::Stream->newFh(-in=>*IN, -out=>*OUT)
178       Returns a filehandle object tied to a Boulder::Stream object.  Reads on
179       the filehandle perform a get().  Writes invoke a put().
180
181       To retrieve the underlying Boulder::Stream object, call Perl's built-in
182       tied() function:
183
184         $stream = tied $fh;
185
186   $stone = $stream->get(@taglist)
187   @stones = $stream->get(@taglist)
188       Every time get() is called, it will return a new Stone object.  The
189       Stone will be created from the input stream, using just the tags
190       provided in the argument list.  Pass no tags to receive whatever tags
191       are present in the input stream.
192
193       If none of the tags that you specify are in the current boulder record,
194       you will receive an empty Stone.  At the end of the input stream, you
195       will receive undef.
196
197       If called in an array context, get() returns a list of all stones from
198       the input stream that contain one or more of the specified tags.
199
200   $stone = $stream->read_record(@taglist)
201       Identical to get(>, but the name is longer.
202
203   $stream->put($stone)
204       Write a Stone to the output filehandle.
205
206   $stream->write_record($stone)
207       Identical to put(), but the name is longer.
208
209   Useful State Variables in a Boulder::Stream
210       Every Boulder::Stream has several state variables that you can adjust.
211       Fix them in this fashion:
212
213               $a = new Boulder::Stream;
214               $a->{delim}=':';
215               $a->{record_start}='[';
216               $a->{record_end}=']';
217               $a->{passthru}=undef;
218
219       •   delim
220
221           This is the delimiter character between tags and values, "=" by
222           default.
223
224       •   record_start
225
226           This is the start of nested record character, "{" by default.
227
228       •   record_end
229
230           This is the end of nested record character, "}" by default.
231
232       •   passthru
233
234           This determines whether unrecognized tags should be passed through
235           from the input stream to the output stream.  This is 'true' by
236           default.  Set it to undef to override this behavior.
237

BUGS

239       Because the delim, record_start and record_end characters in the
240       Boulder::Stream object are used in optimized (once-compiled) pattern
241       matching, you cannot change these values once get() has once been
242       called.  To change the defaults, you must create the Boulder::Stream,
243       set the characters, and only then begin reading from the input stream.
244       For the same reason, different Boulder::Stream objects cannot use
245       different delimiters.
246

AUTHOR

248       Lincoln D. Stein <lstein@cshl.org>, Cold Spring Harbor Laboratory, Cold
249       Spring Harbor, NY.  This module can be used and distributed on the same
250       terms as Perl itself.
251

SEE ALSO

253       Boulder, Boulder::Blast, Boulder::Genbank, Boulder::Medline,
254       Boulder::Unigene, Boulder::Omim, Boulder::SwissProt
255
256
257
258perl v5.36.0                      2022-07-22                Boulder::Stream(3)
Impressum