1Boulder::Stream(3) User Contributed Perl Documentation Boulder::Stream(3)
2
6 Boulder::Stream - Read and write tag/value data from an input stream
7
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 # 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 $record->insert(Eligible => 'yes');
23 print $stream $record;
24 }
25 # 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 $record->insert(Eligible => 'yes');
34 print $stream $record;
35 }
36
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 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 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 This convention allows the following type of pipe to be set up:
60 query_database | find_vector | find_dups | \
62 | blast_sequence | pick_primer | mail_report
63 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
69 Here is a skeleton example.
70 #!/bin/perl
72 use Boulder::Stream;
73 my $stream = Boulder::Stream->newFh;
75 while ( my $record = <$stream> ) {
77 next unless $record->Age >= 35;
78 my @friends = $record->Friends;
79 next unless grep {$_ eq 'Fred'} @friends;
80 $record->insert(Eligible => 'yes');
82 print $stream $record;
83 }
84 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 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 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 #!/bin/perl
118 use Boulder::Stream;
119 my $stream = Boulder::Stream->new;
121 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 $record->insert(Eligible => 'yes');
128 $stream->put($record);
129 }
130 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 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 Notice that there are now two records ("Phillip" and "Barbara") that do
164 not contain the Eligible tag.
165
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 $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 To retrieve the underlying Boulder::Stream object, call Perl's built-in
182 tied() function:
183 $stream = tied $fh;
185 $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 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 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 $stone = $stream->read_record(@taglist)
201 Identical to get(>, but the name is longer.
202 $stream->put($stone)
204 Write a Stone to the output filehandle.
205 $stream->write_record($stone)
207 Identical to put(), but the name is longer.
208 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 $a = new Boulder::Stream;
214 $a->{delim}=':';
215 $a->{record_start}='[';
216 $a->{record_end}=']';
217 $a->{passthru}=undef;
218 • delim
220 This is the delimiter character between tags and values, "=" by
222 default.
223 • record_start
225 This is the start of nested record character, "{" by default.
227 • record_end
229 This is the end of nested record character, "}" by default.
231 • passthru
233 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
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
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
253 Boulder, Boulder::Blast, Boulder::Genbank, Boulder::Medline,
254 Boulder::Unigene, Boulder::Omim, Boulder::SwissProt
255perl v5.36.0 2023-01-20 Boulder::Stream(3)