Boulder IO¶

Boulder IO is a simple TAG=VALUE data format designed for sharing databetween programs connected via a pipe. It is also simple enough to useas a common data exchange format between databases, Web pages, and otherdata representations.

The basic data format is very simple. It consists of a series of TAG=VALUEpairs separated by newlines. It is record-oriented. The end of a record isindicated by an empty delimiter alone on a line. The delimiter is "=" bydefault, but can be adjusted by the user.

An example boulder stream looks like this:

        Name=Lincoln Stein
        Home=/u/bush202/lds32
        Organization=Cold Spring Harbor Laboratory
        Login=lds32
        Password_age=20
        Password_expires=60
        Alias=lstein
        Alias=steinl
        =
        Name=Leigh Deacon
        Home=/u/bush202/tanager
        Organization=Cold Spring Harbor Laboratory
        Login=tanager
        Password_age=2
        Password_expires=60
        =

Notes:

(1)

There is no need for all tags to appear in all records, orindeed for all the records to be homogeneous.

(2)

Multiple values are allowed, as with the Alias tag in the secondrecord.

(3)

Lines can be any length, as in a potential 40 Kbp DNA sequence entry.

(4)

Tags can be any alphanumeric character (upper or lower case) and maycontain embedded spaces. Conventionally we use the charactersA-Z0-9_, because they can be used without single quoting as keys inPerl associative arrays, but this is merely stylistic. Values can beany character at all except for the reserved characters {}=% andnewline. You can incorporate binary data into the data stream byescaping these characters in the URL manner, using a % sign followedby the (capitalized) hexadecimal code for the character. The modulemakes this automatic.

Hierarchical Records¶

The simple boulder format can be extended to accommodate nestedrelations and other intresting structures. Nested records can becreated in this way:

 Name=Lincoln Stein
 Home=/u/bush202/lds32
 Organization=Cold Spring Harbor Laboratory
 Login=lds32
 Password_age=20
 Password_expires=60
 Privileges={
   ChangePasswd=yes
   CronJobs=yes
   Reboot=yes
   Shutdown=no
 }
 =
 Name=Leigh Deacon
 Home=/u/bush202/tanager
 Organization=Cold Spring Harbor Laboratory
 Login=tanager
 Password_age=2
 Password_expires=60
 Privileges={
   ChangePasswd=yes
   CronJobs=no
   Reboot=no
   Shutdown=no
 }
 =

As in the original format, tags may be multivalued. For example,there might be several Privilege record assigned to a login account.Each subrecord may contain further subrecords.

Within the program, a hierarchical record is encapsulated within a"Stone", an opaque structure that implements methods for fetching andsettings its various tags.

Using Boulder for I/O¶

The Boulder API was designed to make reading and writing of complexhierarchical records almost as easy as reading and writing singlelines of text.

Boulder::Stream

The main component of the Boulder modules is Boulder::Stream, whichprovides a stream-oriented view of the data. You can read and writeto Boulder::Streams via tied filehandles, or via method calls. Datarecords are flattened into a simple format called "boulderio" format.

Boulder::XML

Boulder::XML acts like Boulder::Stream, but the serialization formatis XML. You need XML::Parser installed to use this module.

Boulder::Store

This is a simple persistent storage class which allows you to storeseveral (thousand) Stone's into a DB_File database. You must havelibdb and the Perl DB_File extensions installed in order to takeadvantage of this class.

Boulder::Genbank

Boulder::Unigene

Boulder::OMIM

Boulder::Blast

Boulder::Medline

Boulder::SwissProt

These are parsers and accessors for various biological data sources.They act like Boulder::Stream, but return a set of Stone objects thathave certain prescribed tags and values. Many of these modules werewritten by Luca I.G. Toldo <luca.toldo@merck.de>.

Stone Objects¶

The Stone object encapsulates a set of tags and values. Any tag canbe single- or multivalued, and tags are allowed to contain subtags toany depth. A simple set of methods named tags(), get(), put(), insert(), replace() and so forth, allows you to examine the tags that are available, get and set their values, and search for particular tags. In addition, an autoload mechanism allows you to use method calls to access tags, for example:

   my @friends = $record->Friends;

is equivalent to:

   my @friends = $record->get('Friends');

A Stone::Cursor class allows you to traverse Stones systematically.

A full explanation of the Stone class can be found in its manual page.