Outdated egg!

This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for the CHICKEN 4 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

eggs

packedobjects is a data encoding tool based on the telecommunications standard Packed Encoding Rules (PER). An abstract syntax language is used to define a protocol specification. packedobjects uses the Scheme programming language to represent the protocol specification within a symbolic expression (s-expression).

packedobjects is suitable for simple cross platform request/response protocols that require efficient encoding.

So far packedobjects has been run on the following platforms:

Mac OS X (PowerPC)
Linux (PowerPC)
Linux (Intel)
Linux (ARM)
NetBSD (alpha)

For a more detailed introduction refer to the following short paper.

Author

John P. T. Moore <jptmoore@gmail.com>

Version

0.76 fixed .setup issue
0.74 Removed .html from egg
0.73 Added set-finalizer! to automatically free PDU buffer
0.72 Bugfix to SET data type
0.71 Minor code improvement
0.70 Added two new data types: numeric-string and null
0.69 Performance improvements
0.66 Inital wiki version

Building from subversion repository

svn checkout http://anonymous:@code.call-cc.org/svn/chicken-eggs/release/3/packedobjects

chicken-setup packedobjects.setup

Usage

(packedobjects <protocol> #!key <pdusize> <strsize>)

Creates a packedobject using the supplied protocol specification. Optional values for the PDU and string buffer sizes can be specified. They default to 5000 and 1000 respectively. Both the PDU buffer and string buffer are fixed in size. The string buffer must be large enough to handle any string used by the protocol. The PDU buffer must be manually freed.

(<packedobject> 'pack <values>)

Encodes a list of values and returns the number of bytes used.

(<packedobject> 'unpack)

Returns a list of values.

(<packedobject> 'read <fd> <size>)

Reads a number of bytes from a file descriptor into the PDU buffer.

(<packedobject> 'write <fd> <size>)

Writes a number of bytes from the PDU buffer to a file descriptor.

(<packedobject> 'read-message <fd>)

Reads a message from a file descriptor into the PDU buffer.

(<packedobject> 'write-message <fd> <size>)

Writes a message containing a number of bytes from the PDU buffer to a file descriptor.

A message consists of the encoded data plus a 2 byte header representing the length of the message. Therefore, the maximum message size is 2^16-1 bytes.

(<packedobject> 'dump-buffer <filename> <size>)

Dumps a number of bytes from the PDU buffer to a file.

(<packedobject> 'free)

Explicitly frees the PDU buffer. N.B. This call is optional as the memory will be automatically garbage collected.

Data types with examples

The following data types are currently supported.

string

protocol: (foobar string (size 1 10))
values: (foobar "foobar")
description: 7 bit string limited to 10 characters in length.

octet-string

protocol: (foobar octet-string ())
values: (foobar "foobar")
description: 8 bit string with no length restriction.

bit-string

protocol: (foobar bit-string (size 8))
values: (foobar "10101010")
description: Bitstring fixed in length.

hex-string

protocol: (foobar hex-string (size 1 max))
values: (foobar "afafaf")
description: String of hexadecimal characters with no length restriction.

numeric-string

protocol: (foobar numeric-string ())
values: (foobar "123")
description: String of numeric characters with no length restriction.

integer

protocol: (foobar integer (range 1 10))
values: (foobar 5)
description: Integer with a minimum allowed value of 1 and maximum allowed value of 10.

boolean

protocol: (foobar boolean)
values: (foobar #t)
description: Boolean value.

enumerated

protocol: (foobar enumerated (mon tues wed thurs fri))
values: (foobar fri)
description: List of alternative symbols.

null

protocol: (foobar null)
values: (foobar)
description: Null value.

sequence

protocol: (foobar sequence (foo string (size 1 10)) (bar string (size 1 10)))
values: (foobar (foo "foo") (bar "bar"))
description: Ordered sequence of types.

sequence-of

protocol: (foobar sequence-of (foo string (size 1 10)) (bar string (size 1 10)))
values: (foobar ((foo "foo") (bar "bar")) ((foo "anotherfoo") (bar "anotherbar")))
description: Ordered sequence of types where the sequence may repeat.

set

protocol: (foobar set (foo string (size 1 10)) (bar string (size 1 10)))
values: (foobar (bar "bar") (foo "foo"))
description: Unordered sequence of types. Each element of a set is also optional.

choice

protocol: (foobar choice (foo integer ()) (bar integer ()))
values: (foobar (bar 100))
description: Single item from a series of types.

Constraints

Constraints may be placed on all string types as well as integers. Restricting the size of strings and the range of integers can reduce the amount of bits encoded.

The following are valid string contraints:

()
(size min max)
(size <unsigned> <unsigned>)
(size <unsigned>)

The following are valid integer constraints:

()
(range min max)
(range <int> <int>)

Note, min and max denotes no lower bound and upper bound respectively, therefore () is equivalent to (size min max) or (range min max).

Examples

(require-extension packedobjects)
 
(define bbcard
  '(bbcard sequence
           (name string (size 1 60))
           (team string (size 1 60))
           (age integer (range 1 100))
           (position string (size 1 60))
           (handedness enumerated (left-handed right-handed ambidextrous))
           (batting-average sequence
                            (mantissa integer ())
                            (base enumerated (2 10))
                            (exponent integer ()))))
 
(define bbcard-values
  '(bbcard
    (name "Casey")
    (team "Mudville Nine")
    (age 32)
    (position "left field")
    (handedness ambidextrous)
    (batting-average
     (mantissa 250)
     (base 10)
     (exponent -3))))
 
(define po (packedobjects bbcard))
(print* "encoded in " (po 'pack bbcard-values) " bytes.\n")
(print (po 'unpack))
(po 'free)

The following example retrieves random numbers from random.org.

The client talks to a server process which in turn obtains the numbers using HTTP. The data transferred between client and server is significantly more efficient, in terms of bits on the wire, than if the client talked directly to random.org using HTTP.

tcpclient.scm

tcpserver.scm

Limitations

The length of strings, the number of elements in a set and the number of times a sequence-of may repeat is restricted to 2^30-1.
The maximum integer (unsigned), the number of choices and the number of enumerations is restricted to 2^32-1.

To do

Tidy code.
Performance enhancements.
Improvements to error/exception handling.
Further testing.

License

BSD license