start xenodocs

pitfall/.gitignore

@@ -14,3 +14,7 @@ Icon
 # Files that might appear on external disk
 .Spotlight-V100
 .Trashes
+xenomorph/doc/*
+xenomorph/scribblings/*.css
+xenomorph/scribblings/*.js
+xenomorph/scribblings/*.html

pitfall/xenomorph/info.rkt

@@ -0,0 +1,4 @@
+#lang info
+
+(define scribblings '(("scribblings/xenomorph.scrbl" ())))
+(define compile-omit-paths '("test/test.rkt" "test/~stream.test.rkt" "private/~stream.rkt"))

pitfall/xenomorph/scribblings/xenomorph.scrbl

@@ -0,0 +1,49 @@
+#lang scribble/manual
+
+@(require scribble/eval (for-label racket xenomorph))
+
+@(define my-eval (make-base-eval))
+@(my-eval `(require xenomorph))
+
+
+@title{Xenomorph: binary decoding & encoding}
+
+@author[(author+email "Matthew Butterick" "mb@mbtype.com")]
+
+@defmodule[xenomorph]
+
+Hands up: who likes reading and writing binary structures? 
+
+OK, great. All of you are free to go. 
+
+Everyone else: keep reading. This library is for you.
+
+@italic{Derived principally from Devon Govett's @link["https://github.com/devongovett/restructure"]{@tt{restructure}} library for Node.}
+
+
+@section{Installation}
+
+At the command line:
+@verbatim{raco pkg install xenomorph}
+
+After that, you can update the package from the command line:
+@verbatim{raco pkg update xenomorph}
+
+Invoke the library in a source file by importing it in the usual way: @code{(require xenomorph)}. 
+
+@section{Quick demo}
+
+
+@section{The big idea}
+
+@section{Numbers}
+
+
+
+@section{License & source code}
+
+This module is licensed under the LGPL.
+
+
+Source repository at @link["http://github.com/mbutterick/xenomorph"]{http://github.com/mbutterick/xenomorph}. Suggestions & corrections welcome.
+

pitfall/xenomorph/test/~stream-test.rkt

@@ -11,150 +11,150 @@ https://github.com/mbutterick/restructure/blob/master/test/DecodeStream.coffee
 ;    buf = new Buffer [1,2,3]
 ;    stream = new DecodeStream buf
 ;    stream.readBuffer(buf.length).should.deep.equal new Buffer [1,2,3]
-
-(let ()
-  (define buf (+Buffer '(1 2 3)))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readBuffer (length buf)) (+Buffer '(1 2 3))))
-
 ;
-;  it 'should readUInt16BE', ->
+;(let ()
-;    buf = new Buffer [0xab, 0xcd]
+;  (define buf (+Buffer '(1 2 3)))
-;    stream = new DecodeStream buf
+;  (define stream (+DecodeStream buf))
-;    stream.readUInt16BE().should.deep.equal 0xabcd
+;  (check-equal? (send stream readBuffer (length buf)) (+Buffer '(1 2 3))))
-
-(let ()
-  (define buf (+Buffer '(#xab #xcd)))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readUInt16BE) #xabcd))
-
 ;
-;  it 'should readUInt16LE', ->
+;;
-;    buf = new Buffer [0xab, 0xcd]
+;;  it 'should readUInt16BE', ->
-;    stream = new DecodeStream buf
+;;    buf = new Buffer [0xab, 0xcd]
-;    stream.readUInt16LE().should.deep.equal 0xcdab
+;;    stream = new DecodeStream buf
-
+;;    stream.readUInt16BE().should.deep.equal 0xabcd
-(let ()
-  (define buf (+Buffer '(#xab #xcd)))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readUInt16LE) #xcdab))
-
 ;
-;  it 'should readUInt24BE', ->
+;(let ()
-;    buf = new Buffer [0xab, 0xcd, 0xef]
+;  (define buf (+Buffer '(#xab #xcd)))
-;    stream = new DecodeStream buf
+;  (define stream (+DecodeStream buf))
-;    stream.readUInt24BE().should.deep.equal 0xabcdef
+;  (check-equal? (send stream readUInt16BE) #xabcd))
-
-(let ()
-  (define buf (+Buffer '(#xab #xcd #xef)))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readUInt24BE) #xabcdef))
-
 ;
-;  it 'should readUInt24LE', ->
+;;
-;    buf = new Buffer [0xab, 0xcd, 0xef]
+;;  it 'should readUInt16LE', ->
-;    stream = new DecodeStream buf
+;;    buf = new Buffer [0xab, 0xcd]
-;    stream.readUInt24LE().should.deep.equal 0xefcdab
+;;    stream = new DecodeStream buf
-
+;;    stream.readUInt16LE().should.deep.equal 0xcdab
-(let ()
-  (define buf (+Buffer '(#xab #xcd #xef)))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readUInt24LE) #xefcdab))
-
 ;
-;  it 'should readInt24BE', ->
+;(let ()
-;    buf = new Buffer [0xff, 0xab, 0x24]
+;  (define buf (+Buffer '(#xab #xcd)))
-;    stream = new DecodeStream buf
+;  (define stream (+DecodeStream buf))
-;    stream.readInt24BE().should.deep.equal -21724
+;  (check-equal? (send stream readUInt16LE) #xcdab))
-
-(let ()
-  (define buf (+Buffer '(#xff #xab #x24)))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readInt24BE) -21724))
-
 ;
-;  it 'should readInt24LE', ->
+;;
-;    buf = new Buffer [0x24, 0xab, 0xff]
+;;  it 'should readUInt24BE', ->
-;    stream = new DecodeStream buf
+;;    buf = new Buffer [0xab, 0xcd, 0xef]
-;    stream.readInt24LE().should.deep.equal -21724
+;;    stream = new DecodeStream buf
-
+;;    stream.readUInt24BE().should.deep.equal 0xabcdef
-(let ()
-  (define buf (+Buffer '(#x24 #xab #xff)))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readInt24LE) -21724))
-
 ;
-;  describe 'readString', ->
+;(let ()
-;    it 'should decode ascii by default', ->
+;  (define buf (+Buffer '(#xab #xcd #xef)))
-;      buf = new Buffer 'some text', 'ascii'
+;  (define stream (+DecodeStream buf))
-;      stream = new DecodeStream buf
+;  (check-equal? (send stream readUInt24BE) #xabcdef))
-;      stream.readString(buf.length).should.equal 'some text'
-
-(let ()
-  (define buf (+Buffer "some text" 'ascii))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readString (length buf)) "some text"))
-
 ;
-;    it 'should decode ascii', ->
+;;
-;      buf = new Buffer 'some text', 'ascii'
+;;  it 'should readUInt24LE', ->
-;      stream = new DecodeStream buf
+;;    buf = new Buffer [0xab, 0xcd, 0xef]
-;      stream.readString(buf.length, 'ascii').should.equal 'some text'
+;;    stream = new DecodeStream buf
-
+;;    stream.readUInt24LE().should.deep.equal 0xefcdab
-(let ()
-  (define buf (+Buffer "some text" 'ascii))
-  (define stream (+DecodeStream buf))
-  (check-equal? (send stream readString (length buf) 'ascii) "some text"))
-
 ;
-;    it 'should decode utf8', ->
+;(let ()
-;      buf = new Buffer 'unicode! 👍', 'utf8'
+;  (define buf (+Buffer '(#xab #xcd #xef)))
-;      stream = new DecodeStream buf
+;  (define stream (+DecodeStream buf))
-;      stream.readString(buf.length, 'utf8').should.equal 'unicode! 👍'
+;  (check-equal? (send stream readUInt24LE) #xefcdab))
-
+;
-(let ()
+;;
-  (define buf (+Buffer "unicode! 👍" 'utf8))
+;;  it 'should readInt24BE', ->
-  (define stream (+DecodeStream buf))
+;;    buf = new Buffer [0xff, 0xab, 0x24]
-  (check-equal? (send stream readString (length buf) 'utf8) "unicode! 👍"))
+;;    stream = new DecodeStream buf
-
+;;    stream.readInt24BE().should.deep.equal -21724
-#|
+;
-; todo: support freaky string encodings
+;(let ()
-
+;  (define buf (+Buffer '(#xff #xab #x24)))
-;    it 'should decode utf16le', ->
+;  (define stream (+DecodeStream buf))
-;      buf = new Buffer 'unicode! 👍', 'utf16le'
+;  (check-equal? (send stream readInt24BE) -21724))
-;      stream = new DecodeStream buf
+;
-;      stream.readString(buf.length, 'utf16le').should.equal 'unicode! 👍'
+;;
-;
+;;  it 'should readInt24LE', ->
-;    it 'should decode ucs2', ->
+;;    buf = new Buffer [0x24, 0xab, 0xff]
-;      buf = new Buffer 'unicode! 👍', 'ucs2'
+;;    stream = new DecodeStream buf
-;      stream = new DecodeStream buf
+;;    stream.readInt24LE().should.deep.equal -21724
-;      stream.readString(buf.length, 'ucs2').should.equal 'unicode! 👍'
+;
-;
+;(let ()
-;    it 'should decode utf16be', ->
+;  (define buf (+Buffer '(#x24 #xab #xff)))
-;      buf = new Buffer 'unicode! 👍', 'utf16le'
+;  (define stream (+DecodeStream buf))
-;      for i in [0...buf.length - 1] by 2
+;  (check-equal? (send stream readInt24LE) -21724))
-;        byte = buf[i]
+;
-;        buf[i] = buf[i + 1]
+;;
-;        buf[i + 1] = byte
+;;  describe 'readString', ->
-;
+;;    it 'should decode ascii by default', ->
-;      stream = new DecodeStream buf
+;;      buf = new Buffer 'some text', 'ascii'
-;      stream.readString(buf.length, 'utf16be').should.equal 'unicode! 👍'
+;;      stream = new DecodeStream buf
-;
+;;      stream.readString(buf.length).should.equal 'some text'
-;    it 'should decode macroman', ->
+;
-;      buf = new Buffer [0x8a, 0x63, 0x63, 0x65, 0x6e, 0x74, 0x65, 0x64, 0x20, 0x63, 0x68, 0x87, 0x72, 0x61, 0x63, 0x74, 0x65, 0x72, 0x73]
+;(let ()
-;      stream = new DecodeStream buf
+;  (define buf (+Buffer "some text" 'ascii))
-;      stream.readString(buf.length, 'mac').should.equal 'äccented cháracters'
+;  (define stream (+DecodeStream buf))
-|#
+;  (check-equal? (send stream readString (length buf)) "some text"))
-
+;
-
+;;
-
+;;    it 'should decode ascii', ->
-
+;;      buf = new Buffer 'some text', 'ascii'
-;    it 'should return a buffer for unsupported encodings', ->
+;;      stream = new DecodeStream buf
-;      stream = new DecodeStream new Buffer [1, 2, 3]
+;;      stream.readString(buf.length, 'ascii').should.equal 'some text'
-;      stream.readString(3, 'unsupported').should.deep.equal new Buffer [1, 2, 3]
+;
-
+;(let ()
-
+;  (define buf (+Buffer "some text" 'ascii))
-(let ()
+;  (define stream (+DecodeStream buf))
-  (define buf (+Buffer '(1 2 3)))
+;  (check-equal? (send stream readString (length buf) 'ascii) "some text"))
-  (define stream (+DecodeStream buf))
+;
-  (check-equal? (send stream readString 3 'unsupported) (+Buffer '(1 2 3))))
+;;
+;;    it 'should decode utf8', ->
+;;      buf = new Buffer 'unicode! 👍', 'utf8'
+;;      stream = new DecodeStream buf
+;;      stream.readString(buf.length, 'utf8').should.equal 'unicode! 👍'
+;
+;(let ()
+;  (define buf (+Buffer "unicode! 👍" 'utf8))
+;  (define stream (+DecodeStream buf))
+;  (check-equal? (send stream readString (length buf) 'utf8) "unicode! 👍"))
+;
+;#|
+;; todo: support freaky string encodings
+;
+;;    it 'should decode utf16le', ->
+;;      buf = new Buffer 'unicode! 👍', 'utf16le'
+;;      stream = new DecodeStream buf
+;;      stream.readString(buf.length, 'utf16le').should.equal 'unicode! 👍'
+;;
+;;    it 'should decode ucs2', ->
+;;      buf = new Buffer 'unicode! 👍', 'ucs2'
+;;      stream = new DecodeStream buf
+;;      stream.readString(buf.length, 'ucs2').should.equal 'unicode! 👍'
+;;
+;;    it 'should decode utf16be', ->
+;;      buf = new Buffer 'unicode! 👍', 'utf16le'
+;;      for i in [0...buf.length - 1] by 2
+;;        byte = buf[i]
+;;        buf[i] = buf[i + 1]
+;;        buf[i + 1] = byte
+;;
+;;      stream = new DecodeStream buf
+;;      stream.readString(buf.length, 'utf16be').should.equal 'unicode! 👍'
+;;
+;;    it 'should decode macroman', ->
+;;      buf = new Buffer [0x8a, 0x63, 0x63, 0x65, 0x6e, 0x74, 0x65, 0x64, 0x20, 0x63, 0x68, 0x87, 0x72, 0x61, 0x63, 0x74, 0x65, 0x72, 0x73]
+;;      stream = new DecodeStream buf
+;;      stream.readString(buf.length, 'mac').should.equal 'äccented cháracters'
+;|#
+;
+;
+;
+;
+;;    it 'should return a buffer for unsupported encodings', ->
+;;      stream = new DecodeStream new Buffer [1, 2, 3]
+;;      stream.readString(3, 'unsupported').should.deep.equal new Buffer [1, 2, 3]
+;
+;
+;(let ()
+;  (define buf (+Buffer '(1 2 3)))
+;  (define stream (+DecodeStream buf))
+;  (check-equal? (send stream readString 3 'unsupported) (+Buffer '(1 2 3))))