view release on metacpan or  search on metacpan

docs/javaboulder.txt  view on Meta::CPAN

Return the nth Stone at the given tag.  Uses zero-based indexing.
Returns null if the tag is not found or if the index is out of bounds
(? should it raise an array exception).  Negative numbers count in
from the right end of the array.  The last item is index -1.

*public Stone getFirst(String tag)

Return the first Stone at the indicated tag.  Returns null if the tag
is not found.  This is the same as get(tag,0).

*public Stone getLast(String tag)

Return the first Stone at the indicated tag.  Returns null if the tag
is not found.  This is the same as get(tag,-1).

*public Stone getAny(String tag)

Return a random value from the indicated tag.  This has never been
used, to my knowledge, but it is a feature of the Perl implementation.

*public String[] tags()

Return all the tags available in this Stone.  If it is a scalar Stone, 
an empty (not null) array is returned.

*public Boolean exists(String tag)

Returns true if the indicated tag exists.

*public void delete(String tag)

Delete the tag and its associated subtree from the Stone.

*public Stone[] search(String tag)

Recursively searches through the Stone and its subtrees for the first
tag that matches the argument and returns its contents.  The search
method is depth-first (top-level tags returned preferentially).

*public Stone[] index(String index_string)

Follows a path through the Stone, returning the value.  The path is of 
the form:

   tag1[index].tag2[index].tag3[index]

Indexes can be omitted, in which case the path follows the first value 
of the tag.  Indexes match any of the following expressions:

	[0-9]+  index leftward from first value
        -[0-9]+ index rightward from last value
	#       last item
	\?      random item (question mark)

*public Stone[] path(String index_string)

This is a better name for index(), but unfortunately not part of the
Perl Boulder API.  Maybe index() should be phased out.

*public Enumeration cursor()

Return an Enumeration over the Stone object.  Each call to
nextElement() takes a step in a breadth-first traversal of the Stone.
The elements of the Enumeration are Stones with three tags:

	tag name   interpretation
        --------   --------------
	"tag"      String representing the name of the current
                       element's tag
        "path"     String representing full path to current element
        "value"    The value pointed to by the tag.

===========================================================================
public interface Boulder.Filter;

Boulder.Filter can prefilter a BoulderIO stream so that only certain
Stones are passed to higher layers.  Its filter() method is presented
with each candidate Stone in turn.  It returns a boolean True to
accept the Stone, or False to filter it.

*public abstract Boolean filter(Stone s)

Return True if this Stone should be passed up to higher layers.

===========================================================================

public interface Boulder.IO;

This interface defines everything that a generic Boulder IO class
should be able to do.  Both Boulder.Stream (serial input/output) and
Boulder.Store (record-oriented input/output) implement this interface.

Note that Boulder.IO has an intrinsic cursor behavior, in that it
returns Stones in some defined order.

* public abstract Stone read_record() throws IOException

Reads a new Stone from input and returns it.  If no further stones can 
be read returns NULL.  If an I/O error occurs returns IOException.
Returns EOFException if the caller makes additional calls to
read_record() after it has returned NULL.

* public abstract Stone read_record(String[] f) throws IOException

Reads a new Stone from input and returns it, filtering tag(s) based on
an array of tag filter patterns. The argument is an array of strings
of the form "tag1.tag2.tag3....", corresponding to a set of tag paths.
For example, if the current Stone has the structure:

  NAME=Fred
  DEMOGRAPHICS={
    AGE=62
    GENDER=Male
    PHYSICAL_ATTRIBUTES={
      BALDING=Y
      OVERWEIGHT=N
    }
  }
  ADDRESS={
    STREET=1313 Mockingbird Lane
    TOWN=Port Washington
    STATE=NY
  }

then the stone returned by
read_record(["NAME","DEMOGRAPHICS.AGE","ADDRESS"]) will return the
Stone:

  NAME=Fred
  DEMOGRAPHICS={
    AGE=62
  }
  ADDRESS={
    STREET=1313 Mockingbird Lane
    TOWN=Port Washington
    STATE=NY
  }
  
If no tags match the filter specification, returns an empty (but not
NULL) Stone.  If no further stones can be read returns NULL.  If an
I/O error occurs, returns IOException.  Returns EOFException if the
caller makes additional calls to read_record() after it has returned
NULL.

* public abstract Stone get() throws IOException
* public abstract Stone get(String[] f) throws IOException

The Perl version of Boulder uses get() as a synonum for read_record(),
because some people requested it.  Now I use get() in preference to
the longer form and am open to entirely replacing read_record() with
get().

* public abstract void write_record(Stone s) throws IOException