.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Boulder::Stream 3pm"
.TH Boulder::Stream 3pm "2022-06-08" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Boulder::Stream \- Read and write tag/value data from an input stream
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&   #!/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 \*(AqFred\*(Aq} @friends;
\&
\&      $record\->insert(Eligible => \*(Aqyes\*(Aq);
\&      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 \*(AqFred\*(Aq} @friends;
\&
\&      $record\->insert(Eligible => \*(Aqyes\*(Aq);
\&      print $stream $record;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Boulder::Stream provides stream-oriented access to Boulder \s-1IO\s0
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.
.PP
By default, data is read from the magic \s-1ARGV\s0 filehandle (\s-1STDIN\s0 or a
list of files provided on the command line) and written to \s-1STDOUT.\s0
This can be changed to the filehandles of your choice.
.SS "Pass through behavior"
.IX Subsection "Pass through behavior"
When using the object-oriented form of Boulder::Stream, tags which
aren't specifically requested by the \fBget()\fR 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 \fBboulderio\fR
stream, while a report generator will read but not write the stream.
.PP
This convention allows the following type of pipe to be set up:
.PP
.Vb 2
\&  query_database | find_vector | find_dups | \e
\&    | blast_sequence | pick_primer | mail_report
.Ve
.PP
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.
.SH "SKELETON BOULDER PROGRAM"
.IX Header "SKELETON BOULDER PROGRAM"
Here is a skeleton example.
.PP
.Vb 2
\&   #!/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 \*(AqFred\*(Aq} @friends;
\&
\&      $record\->insert(Eligible => \*(Aqyes\*(Aq);
\&      print $stream $record;
\&    }
.Ve
.PP
The code starts by creating a \fBBoulder::Stream\fR object to handle the
I/O.  It reads from the stream one record at a time, returning a
Stone object.  We recover the \fIAge\fR and \fIFriends\fR tags, and
continue looping unless the Age is greater or equal to 35, and the
list of Friends contains \*(L"Fred\*(R".  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:
.PP
.Vb 10
\&  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
\&  =
.Ve
.PP
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:
.PP
.Vb 2
\&   #!/bin/perl
\&   use Boulder::Stream;
\&   
\&   my $stream = Boulder::Stream\->new;
\&   
\&   while ( my $record = $stream\->get(\*(AqAge\*(Aq,\*(AqFriends\*(Aq) ) {
\&      next unless $record\->Age >= 35;
\&      my @friends = $record\->Friends;
\&      next unless grep {$_ eq \*(AqFred\*(Aq} @friends;
\&
\&      $record\->insert(Eligible => \*(Aqyes\*(Aq);
\&      $stream\->put($record);
\&    }
.Ve
.PP
The \fBget()\fR method is used to fetch Stones containing one or more of the
indicated tags.  The \fBput()\fR method is used to send the result to
standard output.  The pass-through behavior might produce a set of
records like this one:
.PP
.Vb 10
\&  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
\&  =
.Ve
.PP
Notice that there are now two records (\*(L"Phillip\*(R" and \*(L"Barbara\*(R") that
do not contain the Eligible tag.
.SH "Boulder::Stream METHODS"
.IX Header "Boulder::Stream METHODS"
.ie n .SS "$stream = Boulder::Stream\->new(*IN,*OUT)"
.el .SS "\f(CW$stream\fP = Boulder::Stream\->new(*IN,*OUT)"
.IX Subsection "$stream = Boulder::Stream->new(*IN,*OUT)"
.ie n .SS "$stream = Boulder::Stream\->new(\-in=>*IN,\-out=>*OUT)"
.el .SS "\f(CW$stream\fP = Boulder::Stream\->new(\-in=>*IN,\-out=>*OUT)"
.IX Subsection "$stream = Boulder::Stream->new(-in=>*IN,-out=>*OUT)"
The \fB\fBnew()\fB\fR method creates a new \fBBoulder::Stream\fR object.  You can
provide input and output filehandles. If you leave one or both
undefined \fB\fBnew()\fB\fR 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.
.ie n .SS "$fh = Boulder::Stream\->newFh(\-in=>*IN, \-out=>*OUT)"
.el .SS "\f(CW$fh\fP = Boulder::Stream\->newFh(\-in=>*IN, \-out=>*OUT)"
.IX Subsection "$fh = Boulder::Stream->newFh(-in=>*IN, -out=>*OUT)"
Returns a filehandle object tied to a Boulder::Stream object.  Reads
on the filehandle perform a \fBget()\fR.  Writes invoke a \fBput()\fR.
.PP
To retrieve the underlying Boulder::Stream object, call Perl's
built-in \fBtied()\fR function:
.PP
.Vb 1
\&  $stream = tied $fh;
.Ve
.ie n .SS "$stone = $stream\->get(@taglist)"
.el .SS "\f(CW$stone\fP = \f(CW$stream\fP\->get(@taglist)"
.IX Subsection "$stone = $stream->get(@taglist)"
.ie n .SS "@stones = $stream\->get(@taglist)"
.el .SS "\f(CW@stones\fP = \f(CW$stream\fP\->get(@taglist)"
.IX Subsection "@stones = $stream->get(@taglist)"
Every time \fBget()\fR 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.
.PP
If none of the tags that you specify are in the current boulder
record, you will receive an empty \fBStone\fR.  At the end of the input
stream, you will receive \fBundef\fR.
.PP
If called in an array context, \fBget()\fR returns a list of all stones from
the input stream that contain one or more of the specified tags.
.ie n .SS "$stone = $stream\->read_record(@taglist)"
.el .SS "\f(CW$stone\fP = \f(CW$stream\fP\->read_record(@taglist)"
.IX Subsection "$stone = $stream->read_record(@taglist)"
Identical to get(>, but the name is longer.
.ie n .SS "$stream\->put($stone)"
.el .SS "\f(CW$stream\fP\->put($stone)"
.IX Subsection "$stream->put($stone)"
Write a \fBStone\fR to the output filehandle.
.ie n .SS "$stream\->write_record($stone)"
.el .SS "\f(CW$stream\fP\->write_record($stone)"
.IX Subsection "$stream->write_record($stone)"
Identical to \fBput()\fR, but the name is longer.
.SS "Useful State Variables in a \fBBoulder::Stream\fP"
.IX Subsection "Useful State Variables in a Boulder::Stream"
Every Boulder::Stream has several state variables that you can adjust.
Fix them in this fashion:
.PP
.Vb 5
\&        $a = new Boulder::Stream;
\&        $a\->{delim}=\*(Aq:\*(Aq;
\&        $a\->{record_start}=\*(Aq[\*(Aq;
\&        $a\->{record_end}=\*(Aq]\*(Aq;
\&        $a\->{passthru}=undef;
.Ve
.IP "\(bu" 4
delim
.Sp
This is the delimiter character between tags and values, \*(L"=\*(R" by default.
.IP "\(bu" 4
record_start
.Sp
This is the start of nested record character, \*(L"{\*(R" by default.
.IP "\(bu" 4
record_end
.Sp
This is the end of nested record character, \*(L"}\*(R" by default.
.IP "\(bu" 4
passthru
.Sp
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.
.SH "BUGS"
.IX Header "BUGS"
Because the delim, record_start and record_end characters in the
\&\fBBoulder::Stream\fR object are used in optimized (once-compiled)
pattern matching, you cannot change these values once \fBget()\fR 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln D. Stein <lstein@cshl.org>, Cold Spring Harbor Laboratory,
Cold Spring Harbor, \s-1NY.\s0  This module can be used and distributed on
the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Boulder, 
Boulder::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene,
Boulder::Omim, Boulder::SwissProt