(use eggdoc) ; defines an example (define bbcard '(pre "(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)")) (define doc `((eggdoc:begin (name "packedobjects") (description "Cross-platform data encoding based on Packed Encoding Rules") (author "John P. T. Moore") (history (version "0.5" "Alpha release")) (usage) (download "packedobjects.egg") (documentation (p "packedobjects is a highly portable, cross platform, data encoding tool. The project is 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). Using an s-expression provides a more dynamic approach over the traditional method of parsing the specification and producing high level language code. The output of applying packedobjects' encoding rules to a protocol specification is a concisely encoded bit stream suitable for application domains such as network games development and mobile application development. The project has been released under the terms of the BSD license.") (p "For a more detailed introduction refer to the following short " (url "http://zedstar.org/papers/packedobjects.pdf" "paper.")) (procedure "(packedobjects #!key )" (p "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. The PDU buffer can grow dynamically, however, the string buffer is fixed in size and therefore must handle the largest possible string. The PDU buffer must be freed manually whereas the string buffer will be automatically garabage collected.")) (procedure "( 'pack )" (p "Encodes a list of values and returns the number of bytes used.")) (procedure "( 'unpack)" (p "Returns a list of values.")) (procedure "( 'read )" (p "Reads a number of bytes from a file descriptor into the PDU buffer.")) (procedure "( 'write )" (p "Writes a number of bytes from the PDU buffer to a file descriptor.")) (procedure "( 'dump-buffer )" (p "Dumps a number of bytes from the PDU buffer to a file.")) (procedure "( 'free)" (p "Frees the PDU buffer."))) (section "Data types") (p "string" (symbol-table (describe "desc:" "7 bit string limited to 10 characters in length.") (describe "spec:" "(foobar string (size 1 10))") (describe "values:" "(foobar \"foobar\")"))) (p "octet-string" (symbol-table (describe "desc:" "8 bit string with no length restriction.") (describe "spec:" "(foobar string ())") (describe "values:" "(foobar \"foobar\")"))) (p "bit-string" (symbol-table (describe "desc:" "Bitstring fixed in length.") (describe "spec:" "(foobar bit-string (size 8))") (describe "values:" "(foobar \"10101010\")"))) (p "hex-string" (symbol-table (describe "desc:" "String of hexadecimal characters with no length restriction.") (describe "spec:" "(foobar hex-string (size 1 max))") (describe "values:" "(foobar \"foobar\")"))) (p "integer" (symbol-table (describe "desc:" "Integer with a minimum allowed value of 1 and maximum allowed value of 10.") (describe "spec:" "(foobar integer (range 1 10))") (describe "values:" "(foobar 5)"))) (p "boolean" (symbol-table (describe "desc:" "Boolean value.") (describe "spec:" "(foobar boolean)") (describe "values:" "(foobar #t)"))) (p "enumerated" (symbol-table (describe "desc:" "List of alternative symbols.") (describe "spec:" "(foobar enumerated (mon tues wed thurs fri))") (describe "values:" "(foobar fri)"))) (p "sequence" (symbol-table (describe "desc:" "Ordered sequence of types.") (describe "spec:" "(foobar sequence (foo string (size 1 10)) (bar string (size 1 10)))") (describe "values:" "(foobar (foo \"foo\") (bar \"bar\"))"))) (p "set" (symbol-table (describe "desc:" "Unordered sequence of types. Each element of a set is also optional.") (describe "spec:" "(foobar set (foo string (size 1 10)) (bar string (size 1 10)))") (describe "values:" "(foobar (bar \"bar\") (foo \"foo\"))"))) (p "sequence-of" (symbol-table (describe "desc:" "Ordered sequence of types where the sequence may repeat.") (describe "spec:" "(foobar sequence-of (foo string (size 1 10)) (bar string (size 1 10)))") (describe "values:" "(foobar ((foo \"foo\") (bar \"bar\")) ((foo \"anotherfoo\") (bar \"anotherbar\")))"))) (p "choice" (symbol-table (describe "desc:" "Single item from a series of types.") (describe "spec:" "(foobar choice (foo integer ()) (bar integer ()))") (describe "values:" "(foobar (bar 100))"))) (examples ,bbcard) (section "Extended Example" (p "The following example retrieves random numbers from " (url "http://random.org" "random.org.")) (p "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.") (p "Download the source files:") (ul (li (url "http://www.call-with-current-continuation.org/eggs/tcpclient.scm")) (li (url "http://www.call-with-current-continuation.org/eggs/tcpserver.scm")))) (section "Limits" (ul (li "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.") (li "The maximum integer (unsigned), the number of choices and the number of enumerations is restricted to 2^32-1."))) (section "To do" (ul (li "Performance enhancements.") (li "Improvements to error/exception handling.") (li "Further testing."))) (license "Copyright (c) 2006, John P. T. Moore\nAll rights reserved.\n\nBSD license: " (url "http://www.opensource.org/licenses/bsd-license.php" "http://www.opensource.org/licenses/bsd-license.php"))))) (eggdoc->html doc)