A Stone consists of a series of tag/value pairs. Any given tag may be single-valued or multivalued. A value can be another Stone, allowing nested components. A big Stone can be made up of a lot of little stones (pebbles?). You can obtain a Stone from a Boulder::Stream or Boulder::Store persistent database. Alternatively you can build your own Stones bit by bit.

Stones can be exported into string, XML and HTML representations. In addition, they are flattened into a linearized representation when reading from or writing to a Boulder::Stream or one of its descendents.

Stone was designed for subclassing. You should be able to create subclasses which create or require particular tags and data formats. Currently only Stone::GB_Sequence subclasses Stone.

This is the main constructor for the Stone class. It can be called without any parameters, in which case it creates an empty Stone object (no tags or values), or it may passed an associative array in order to initialize it with a set of tags. A tag's value may be a scalar, an anonymous array reference (constructed using [] brackets), or a hash references (constructed using {} brackets). In the first case, the tag will be single-valued. In the second, the tag will be multivalued. In the third case, a subsidiary Stone will be generated automatically and placed into the tree at the specified location.

This is the main method for adding tags to a Stone. This method expects an associative array as an argument or a reference to one. The contents of the associative array will be inserted into the Stone. If a particular tag is already present in the Stone, the tag's current value will be appended to the list of values for that tag. Several types of values are legal:

The replace() method behaves exactly like insert() with the exception that if the indicated key already exists in the Stone, its value will be replaced. Use replace() when you want to enforce a single-valued tag/value relationship.

This returns the value at the indicated tag and optional index. What you get depends on whether it is called in a scalar or list context. In a list context, you will receive all the values for that tag. You may receive a list of scalar values or (for a nested record) or a list of Stone objects. If called in a scalar context, you will either receive the first or the last member of the list of values assigned to the tag. Which one you receive depends on the value of the package variable $Stone::Fetchlast. If undefined, you will receive the first member of the list. If nonzero, you will receive the last member.

You may provide an optional index in order to force get() to return a particular member of the list. Provide a 0 to return the first member of the list, or '#' to obtain the last member.

If the tag contains a period (.), get() will call index() on your behalf (see below).

If the tag begins with an uppercase letter, then you can use the autogenerated method to access it:

Searches for the first occurrence of the tag, traversing the tree in a breadth-first manner, and returns it. This allows you to retrieve the value of a tag in a deeply nested structure without worrying about all the intermediate nodes. For example:

The disadvantage of this is that if there is a tag named "Hair" higher in the hierarchy, this tag will be retrieved rather than the lower one. In an array context this method returns the complete list of values from the matching tag. In a scalar context, it returns either the first or the last value of multivalued tags depending as usual on the value of $Stone::Fetchlast.

$Stone::Fetchlast is also consulted during the depth-first traversal. If $Fetchlast is set to a true value, multivalued intermediate tags will be searched from the last to the first rather than the first to the last.

The Stone object has an AUTOLOAD method that invokes get() when you call a method that is not predefined. This allows a very convenient type of shortcut:

In the first example, we retrieve the value of the top-level tag Name. In the second example, we retrieve the value of the Friend tag.. In the third example, we retrieve the attributes stone first, then the Eyes value.

NOTE: By convention, methods are only autogenerated for tags that begin with capital letters. This is necessary to avoid conflict with hard-coded methods, all of which are lower case.

You can access the contents of even deeply-nested Stone objects with the index method. You provide a tag path, and receive a value or list of values back.

Tag paths look like this:

tag1[index1].tag2[index2].tag3[index3]

Numbers in square brackets indicate which member of a multivalued tag you're interested in getting. You can leave the square brackets out in order to return just the first or the last tag of that name, in a scalar context (depending on the setting of $Stone::Fetchlast). In an array context, leaving the square brackets out will return all multivalued members for each tag along the path.

You will get a scalar value in a scalar context and an array value in an array context following the same rules as get(). You can provide an index of '#' in order to get the last member of a list or a [?] to obtain a randomly chosen member of the list (this uses the rand() call, so be sure to call srand() at the beginning of your program in order to get different sequences of pseudorandom numbers. If there is no tag by that name, you will receive undef or an empty list. If the tag points to a subrecord, you will receive a Stone object.

attributes() returns the "attributes" of a tag. Attributes are a series of unique tag/value pairs which are associated with a tag, but are not contained within it. Attributes can only be expressed in the XML representation of a Stone:

Return the data structure as a nicely-formatted HTML 3.2 table, suitable for display in a Web browser. You may pass this method a callback routine which will be called for every tag/value pair in the object. It will be passed a two-item list containing the current tag and value. It can make any modifications it likes and return the modified tag and value as a return result. You can use this to modify tags or values on the fly, for example to turn them into HTML links.

For example, this code fragment will turn all tags named "Sequence" blue: