Boulder(3pm)

Boulder(3pm) 💖

okay so bestie, welcome to the User Contributed Perl Documentation section, page 3pm, and today's main character is Boulder — an API for hierarchical tag/value structures. yes it's giving bioinformatics-core, but trust me, it's lowkey adorable once you get it. 🦋

---

✨ NAME ✨

Boulder — An API for hierarchical tag/value structures 🌸

---

💅 SYNOPSIS 💅

okay so here's the vibe, no cap. we're reading a bunch of People records off STDIN, and we're adding an Eligibility attribute to literally everyone whose Age >= 35 and whose Friends list has Fred in it. periodt.

# Read a series of People records from STDIN.
# Add an "Eligibility" attribute to all those whose
# Age >= 35 and Friends list includes "Fred"

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(Eligibility => 'yes');
   print $stream $record;
 }

now bestie, here are the related manual pages so you can go down the whole rabbit hole 🐇:

basics 🎀

• Stone — hierarchical tag/value records
• Stone::Cursor — Traverse a hierarchy
• Boulder::Stream — stream-oriented storage for Stones
• Boulder::Store — record-oriented storage for Stones
• Boulder::XML — XML conversion for Stones
• Boulder::String — conversion to strings

genome-related 🧬

• Boulder::Genbank — parse Genbank (DNA sequence) records
• Boulder::Blast — parse BLAST (basic local alignment search tool) reports
• Boulder::Medline — parse Medline (pubmed) records
• Boulder::Omim — parse OMIM (online Mendelian inheritance in man) records
• Boulder::Swissprot — parse Swissprot records
• Boulder::Unigene — parse Unigene records

---

🌈 DESCRIPTION 🌈

🍓 Boulder IO 🍓

okay so Boulder IO is a simple TAG=VALUE data format, and the whole point of it is sharing data between programs that are connected via a pipe. it's also simple enough to use as a common data exchange format between databases, Web pages, and other data representations. versatile queen. 👑

the basic data format is very simple. it's a series of TAG=VALUE pairs separated by newlines. it is record-oriented. the end of a record is indicated by an empty delimiter alone on a line. that delimiter is = by default, but you can adjust it if you want. your call bestie.

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, bestie, take notes: 📝

1. There is no need for all tags to appear in all records, or indeed for all the records to be homogeneous.
2. Multiple values are allowed, as with the Alias tag in the second record.
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 may contain embedded spaces. Conventionally we use the characters A-Z0-9_, because they can be used without single quoting as keys in Perl associative arrays, but this is merely stylistic. Values can be any character at all except for the reserved characters {}=% and newline. You can incorporate binary data into the data stream by escaping these characters in the URL manner, using a % sign followed by the (capitalized) hexadecimal code for the character. The module makes this automatic. ✨

🦋 Hierarchical Records 🦋

the simple boulder format can be extended to accommodate nested relations and other intresting structures. (yes, that's the original spelling, we respect the author's vibe 💜) nested records can be created 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. it's records all the way down bestie 🐢

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

💜 Using Boulder for I/O 💜

the Boulder API was designed to make reading and writing of complex hierarchical records almost as easy as reading and writing single lines of text. almost. iconic design honestly.

• Boulder::Stream — the main component of the Boulder modules is Boulder::Stream, which provides a stream-oriented view of the data. You can read and write to Boulder::Streams via tied filehandles, or via method calls. Data records are flattened into a simple format called boulderio format.
• Boulder::XML — acts like Boulder::Stream, but the serialization format is XML. You need XML::Parser installed to use this module. no parser, no party. 🙈
• Boulder::Store — this is a simple persistent storage class which allows you to store several (thousand) Stone's into a DB_File database. You must have libdb and the Perl DB_File extensions installed in order to take advantage 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 that have certain prescribed tags and values. Many of these modules were written by Luca I.G. Toldo <luca.toldo@merck.de>. 👑

🌸 Stone Objects 🌸

the Stone object encapsulates a set of tags and values. any tag can be single- or multivalued, and tags are allowed to contain subtags to any depth. a simple set of methods named tags(), get(), put(), insert(), replace() and so forth, lets you 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.

---

💖 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::Blast, Boulder::Genbank, Boulder::Medline, Boulder::Unigene, Boulder::Omim, Boulder::SwissProt

---

ok that's the whole page bestie, go forth and structure some tag/value hierarchies, you absolute legend 🫶

that's perl v5.34.0, dated 2022-06-08, and this page was Boulder(3pm) — mwah, slay, bye 💅✨