Boulder::Stream(3pm)

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 hierar‐
39       chical tag/value data.  It can be used in a magic tied filehandle mode,
40       as shown in the synopsis, or in object-oriented mode.  Using tied file‐
41       handles, Stone objects are read from input using the standard <> opera‐
42       tor.  Stone objects printed to the tied filehandle appear on the output
43       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
51       When using the object-oriented form of Boulder::Stream, tags which
52       aren't specifically requested by the get() method are passed through to
53       output unchanged.  This allows pipes of programs to be constructed eas‐
54       ily. Most programs will want to put the tags back into the boulder
55       stream once they're finished, potentially adding their own.  Of course
56       some programs will want to behave differently.  For example, a database
57       query program will generate but not read a boulderio stream, while a
58       report generator will read but not write the stream.
59
60       This convention allows the following type of pipe to be set up:
61
62         query_database ⎪ find_vector ⎪ find_dups ⎪ \
63           ⎪ blast_sequence ⎪ pick_primer ⎪ mail_report
64
65       If all the programs in the pipe follow the conventions, then it will be
66       possible to interpose other programs, such as a repetitive element
67       finder, in the middle of the pipe without disturbing other components.
68

SKELETON BOULDER PROGRAM

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

Boulder::Stream METHODS

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

BUGS

245       Because the delim, record_start and record_end characters in the Boul‐
246       der::Stream object are used in optimized (once-compiled) pattern match‐
247       ing, you cannot change these values once get() has once been called.
248       To change the defaults, you must create the Boulder::Stream, set the
249       characters, and only then begin reading from the input stream.  For the
250       same reason, different Boulder::Stream objects cannot use different
251       delimiters.
252

AUTHOR

254       Lincoln D. Stein <lstein@cshl.org>, Cold Spring Harbor Laboratory, Cold
255       Spring Harbor, NY.  This module can be used and distributed on the same
256       terms as Perl itself.
257