Ubuntu Manpage: Boulder::Stream - Read and write tag/value data from an input stream

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:

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.