NAME¶
Boulder::Stream - Read and write tag/value data from an input stream
SYNOPSIS¶
#!/bin/perl
# Read a series of People records from STDIN.
# Add an "Eligible" tag to all those whose
# Age >= 35 and Friends list includes "Fred"
use Boulder::Stream;
# filestream way:
my $stream = Boulder::Stream->newFh;
while ( my $record = <$stream> ) {
next unless $record->Age >= 35;
my @friends = $record->Friends;
next unless grep {$_ eq 'Fred'} @friends;
$record->insert(Eligible => 'yes');
print $stream $record;
}
# object oriented way:
my $stream = Boulder::Stream->new;
while (my $record = $stream->get ) {
next unless $record->Age >= 35;
my @friends = $record->Friends;
next unless grep {$_ eq 'Fred'} @friends;
$record->insert(Eligible => 'yes');
print $stream $record;
}
DESCRIPTION¶
Boulder::Stream provides stream-oriented access to Boulder IO hierarchical
tag/value data. It can be used in a magic tied filehandle mode, as shown in
the synopsis, or in object-oriented mode. Using tied filehandles, Stone
objects are read from input using the standard <> operator. Stone
objects printed to the tied filehandle appear on the output stream in Boulder
format.
By default, data is read from the magic ARGV filehandle (STDIN or a list of
files provided on the command line) and written to STDOUT. This can be changed
to the filehandles of your choice.
Pass through behavior¶
When using the object-oriented form of Boulder::Stream, tags which aren't
specifically requested by the
get() method are passed through to output
unchanged. This allows pipes of programs to be constructed easily. Most
programs will want to put the tags back into the boulder stream once they're
finished, potentially adding their own. Of course some programs will want to
behave differently. For example, a database query program will generate but
not read a
boulderio stream, while a report generator will read but not
write the stream.
This convention allows the following type of pipe to be set up:
query_database | find_vector | find_dups | \
| blast_sequence | pick_primer | mail_report
If all the programs in the pipe follow the conventions, then it will be possible
to interpose other programs, such as a repetitive element finder, in the
middle of the pipe without disturbing other components.
SKELETON BOULDER PROGRAM¶
Here is a skeleton example.
#!/bin/perl
use Boulder::Stream;
my $stream = Boulder::Stream->newFh;
while ( my $record = <$stream> ) {
next unless $record->Age >= 35;
my @friends = $record->Friends;
next unless grep {$_ eq 'Fred'} @friends;
$record->insert(Eligible => 'yes');
print $stream $record;
}
The code starts by creating a
Boulder::Stream object to handle the I/O.
It reads from the stream one record at a time, returning a Stone object. We
recover the
Age and
Friends tags, and continue looping unless
the Age is greater or equal to 35, and the list of Friends contains
"Fred". If these criteria match, then we insert a new tag named
Eligible and print the record to the stream. The output may look like this:
Name=Janice
Age=36
Eligible=yes
Friends=Susan
Friends=Fred
Friends=Ralph
=
Name=Ralph
Age=42
Eligible=yes
Friends=Janice
Friends=Fred
=
Name=Susan
Age=35
Eligible=yes
Friends=Susan
Friends=Fred
=
Note that in this case only records that meet the criteria are echoed to
standard output. The object-oriented version of the program looks like this:
#!/bin/perl
use Boulder::Stream;
my $stream = Boulder::Stream->new;
while ( my $record = $stream->get('Age','Friends') ) {
next unless $record->Age >= 35;
my @friends = $record->Friends;
next unless grep {$_ eq 'Fred'} @friends;
$record->insert(Eligible => 'yes');
$stream->put($record);
}
The
get() method is used to fetch Stones containing one or more of the
indicated tags. The
put() method is used to send the result to standard
output. The pass-through behavior might produce a set of records like this
one:
Name=Janice
Age=36
Eligible=yes
Friends=Susan
Friends=Fred
Friends=Ralph
=
Name=Phillip
Age=30
=
Name=Ralph
Age=42
Eligible=yes
Friends=Janice
Friends=Fred
=
Name=Barbara
Friends=Agatha
Friends=Janice
=
Name=Susan
Age=35
Eligible=yes
Friends=Susan
Friends=Fred
=
Notice that there are now two records ("Phillip" and
"Barbara") that do not contain the Eligible tag.
Boulder::Stream METHODS¶
$stream = Boulder::Stream->new(*IN,*OUT)¶
$stream = Boulder::Stream->new(-in=>*IN,-out=>*OUT)¶
The
new() method creates a new
Boulder::Stream object. You can provide input and output filehandles.
If you leave one or both undefined
new() will
default to standard input or standard output. You are free to use files,
pipes, sockets, and other types of file handles. You may provide the
filehandle arguments as bare words, globs, or glob refs. You are also free to
use the named argument style shown in the second heading.
$fh = Boulder::Stream->newFh(-in=>*IN, -out=>*OUT)¶
Returns a filehandle object tied to a Boulder::Stream object. Reads on the
filehandle perform a
get(). Writes invoke a
put().
To retrieve the underlying Boulder::Stream object, call Perl's built-in
tied() function:
$stream = tied $fh;
$stone = $stream->get(@taglist)¶
@stones = $stream->get(@taglist)¶
Every time
get() is called, it will return a new Stone object. The Stone
will be created from the input stream, using just the tags provided in the
argument list. Pass no tags to receive whatever tags are present in the input
stream.
If none of the tags that you specify are in the current boulder record, you will
receive an empty
Stone. At the end of the input stream, you will
receive
undef.
If called in an array context,
get() returns a list of all stones from
the input stream that contain one or more of the specified tags.
$stone = $stream->read_record(@taglist)¶
Identical to get(>, but the name is longer.
$stream->put($stone)¶
Write a
Stone to the output filehandle.
$stream->write_record($stone)¶
Identical to
put(), but the name is longer.
Useful State Variables in a Boulder::Stream¶
Every Boulder::Stream has several state variables that you can adjust. Fix them
in this fashion:
$a = new Boulder::Stream;
$a->{delim}=':';
$a->{record_start}='[';
$a->{record_end}=']';
$a->{passthru}=undef;
- •
- delim
This is the delimiter character between tags and values, "=" by
default.
- •
- record_start
This is the start of nested record character, "{" by default.
- •
- record_end
This is the end of nested record character, "}" by default.
- •
- passthru
This determines whether unrecognized tags should be passed through from the
input stream to the output stream. This is 'true' by default. Set it to
undef to override this behavior.
BUGS¶
Because the delim, record_start and record_end characters in the
Boulder::Stream object are used in optimized (once-compiled) pattern
matching, you cannot change these values once
get() has once been
called. To change the defaults, you must create the Boulder::Stream, set the
characters, and only then begin reading from the input stream. For the same
reason, different Boulder::Stream objects cannot use different delimiters.
AUTHOR¶
Lincoln D. Stein <lstein@cshl.org>, Cold Spring Harbor Laboratory, Cold
Spring Harbor, NY. This module can be used and distributed on the same terms
as Perl itself.
SEE ALSO¶
Boulder, Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
Boulder::Omim, Boulder::SwissProt