sunterlib/s48/banana/README

'Banana' is a simple object serialisation protocol.

- Main Procedures -

(encode value [profile]) ==> byte-vector               [procedure]
  Turns a value into a byte-vector representing that value.
  Generally, the 'none' profile is used (and PROFILE defaults to
  PROFILE/NONE), and with that one can encode only integers
  (positive, zero, and negative, and of any size), lists, strings,
  and reals (*FIXME* Real number encoding and decoding doesn't
  work right now -- I haven't a clue how to encode them in the
  IEEE floating point format, which is what Banana requires).
    Example:
      (encode '(1 -1 ("hello")))
        (not printed as byte-vectors would normally print; this is
        just how Banana output is ordinarily shown)
        ==> 03 80 01 81 01 83 01 80 05 82 68 65 6c 6c 6c 6f

(decode input-port/string/byte-vector [profile])       [procedure]
    ==> value
  Decodes the output of ENCODE, or reads similar output from an
  input port, or processes a string similarly.
    Example:
      (decode (encode '(1 -1 ("hello"))))
        ==> (1 -1 ("hello"))

(etb? byte)                                            [procedure]
    ==> boolean
  Returns #t if BYTE > 127 (#x7f), #f if otherwise.  BYTE must be
  an exact integer.

- Exceptions -

banana-error <-- error                            [condition type]
  Subtypes of BANANA-ERROR are raised whenever anything involving
  Banana-ing goes wrong.  The procedure that raised the error is
  stored in each BANANA-ERROR condition, too, accessed by
  BANANA-ERROR-CALLER.

(banana-error? value)                   [condition type predicate]

(banana-error-caller banana-error) ==> symbol          [procedure]
  Returns the name of the procedure that raised BANANA-ERROR.

banana:unknown-byte <-- banana-error              [condition type]
  Raised when DECODE encounters an element type byte (see the
  Banana specification on http://twistedmatrix.com/ for what the
  element type bytes are) that it can't find in the profile it was
  passed.

(unknown-byte-error? value)             [condition type predicate]

(unknown-byte-error-byte banana:unknown-byte) ==> byte [procedure]
  Returns the byte that DECODE didn't recognise.

(unknown-byte-error-profile banana:unknown-byte)       [procedure]
    ==> profile
  Returns the profile that DECODE was searching through.

banana:unsupported-type <-- banana-error          [condition type]
  Raised when a profile's encoder doesn't know how to Banana a
  value of a certain type.

(unsupported-type-error? value)         [condition type predicate]

(unsupported-type-error-type banana:unsupported-type)  [procedure]
    ==> string
  Returns the name of the type that a profile's encoder didn't
  support.

(unsupported-type-error-value banana:unsupported-type) [procedure]
    ==> value
  Returns the value of that type that a profile's encoder didn't
  support.

read-eof-error <-- read-error                     [condition type]
  Raised when an EOF is reached and was not expected.

- Profiles -

Profiles are ways to extend the Banana protocol.  See the Banana
specification for how they work in Banana.

:profile                                             [record type]
  Profiles are stored in instances of this.  They have four
  fields, accessed by similar names --
    name          -- profile-name
    encoder       -- profile-encoder
    decoder-table -- profile-decoder-table
    super-profile -- profile-super-profile

  NAME is mainly for debugging purposes.

  ENCODER should be a procedure of one argument and should return
  a byte vector.

  DECODER-TABLE is a table of element type bytes to procedures of
  two arguments.

  SUPER-PROFILE is either #f or a profile from which another
  profile can inherit element type byte decoders and such.

(make-profile string proc alist)                       [procedure]
  Makes a profile, whose name is STRING, whose encoder is PROC,
  and whose decoder table is a table made from ALIST, which should
  be a list of pairs, the CAR of each being an element type byte,
  and the CDR of each being a decoder procedure.

(extend-profile profile string proc alist)             [procedure]
  The preferred profile constructor, this one allows you to make a
  profile that inherits behaviour from another profile, but is
  otherwise just like MAKE-PROFILE.

The BANANA-EXTRAS package include a couple prettifying procedures
and a couple useful procedures should one desire to extend Banana.

(posint->byte-vector nonnegative-integer)              [procedure]
  The name is slightly misleading, since it also works on zero,
  but in any case, it returns a byte vector of NONNEGATIVE-INTEGER
  encoded as the Banana specification states.  Note that it does
  -not- produce a byte vector with the PROFILE/NONE element type
  byte for nonnegative integers.

(byte-vector->posint byte-vector)                      [procedure]
  The inverse of POSINT->BYTE-VECTOR.

(prettify-byte byte)                                   [procedure]
  Makes BYTE look like it normally does when being described in
  the context of Banana.

(prettify-byte-vector byte-vector)                     [procedure]
  Returns a list of prettified bytes in BYTE-VECTOR.