From 3c1539a413a8715e161a9ea9d4ebf10929b1eadb Mon Sep 17 00:00:00 2001
From: Matthew Butterick <mb@mbtype.com>
Date: Sun, 28 Apr 2019 16:56:45 -0700
Subject: [PATCH] doc struct

---
 .../xenomorph/scribblings/xenomorph.scrbl     | 58 ++++++++++++++++++-
 xenomorph/xenomorph/struct.rkt                | 16 +++--
 xenomorph/xenomorph/versioned-struct.rkt      |  8 ++-
 3 files changed, 75 insertions(+), 7 deletions(-)

diff --git a/xenomorph/xenomorph/scribblings/xenomorph.scrbl b/xenomorph/xenomorph/scribblings/xenomorph.scrbl
index f9896aa7..2b0c1f2a 100644
--- a/xenomorph/xenomorph/scribblings/xenomorph.scrbl
+++ b/xenomorph/xenomorph/scribblings/xenomorph.scrbl
@@ -442,7 +442,6 @@ Base class for fixed-point number formats. Use @racket[x:fixed] to conveniently
 Create class instance that represents a fixed-point number format @racket[size] bytes long, either @racket[signed?] or not, with @racket[endian] byte ordering and @racket[fracbits] of precision.
 }
 
-
 }
 
 @defproc[
@@ -765,6 +764,63 @@ Generate an instance of @racket[x:vector%] (or a subclass of @racket[x:vector%])
 @defmodule[xenomorph/struct]
 
 
+@defclass[x:struct% x:base% ()]{
+Base class for struct formats. Use @racket[x:struct] to conveniently instantiate new struct formats.
+
+@defconstructor[
+([fields dict?])]{
+Create class instance that represents a struct format with @racket[fields] as a dictionary holding the key–value pairs that define the struct format. Each key must be a @racket[symbol?] and each value must be a @racket[xenomorphic?] type.
+}
+
+@defmethod[
+#:mode extend
+(x:decode
+[input-port input-port?]
+[parent (or/c xenomorphic? #false)])
+hash-eq?]{
+Returns a @tech{hash-eq?} whose keys are the same as the keys in @racket[_fields].
+
+}
+
+@defmethod[
+#:mode extend
+(x:encode
+[kvs dict?]
+[input-port input-port?]
+[parent (or/c xenomorphic? #false)])
+bytes?]{
+Take the keys and values in @racket[kvs] and encode them as a @tech{byte string}.
+}
+
+}
+
+@defproc[
+(x:struct?
+[x any/c])
+boolean?]{
+Whether @racket[x] is an object of type @racket[x:struct%].
+}
+
+@defproc[
+(x:struct
+[#:pre-encode pre-encode-proc (or/c (any/c . -> . any/c) #false) #false]
+[#:post-decode post-decode-proc (or/c (any/c . -> . any/c) #false) #false]
+[#:base-class base-class (λ (c) (subclass? c x:struct%)) x:struct%]
+[dict (listof (pairof symbol? xenomorphic?))] ...
+[key symbol?] [val-type xenomorphic?] ... ...
+)
+x:struct?]{
+Generate an instance of @racket[x:struct%] (or a subclass of @racket[x:struct%]) with certain optional attributes.
+
+The rest arguments determine the keys and value types of the struct. These arguments can either be alternating keys and value-type arguments (similar to the calling pattern for @racket[hasheq]) or @tech{association lists}.
+
+@racket[pre-encode-proc] and @racket[post-decode-proc] control the pre-encoding and post-decodeing procedures, respectively.
+
+@racket[base-class] controls the class used for instantiation of the new object.   
+}
+
+
+
 @subsection{Versioned structs}
 
 @defmodule[xenomorph/versioned-struct]
diff --git a/xenomorph/xenomorph/struct.rkt b/xenomorph/xenomorph/struct.rkt
index dc4cd073..17b4d838 100644
--- a/xenomorph/xenomorph/struct.rkt
+++ b/xenomorph/xenomorph/struct.rkt
@@ -4,6 +4,7 @@
          racket/sequence
          racket/match
          racket/list
+         racket/contract
          "base.rkt"
          "number.rkt"
          sugar/unstable/dict)
@@ -83,10 +84,17 @@ https://github.com/mbutterick/restructure/blob/master/src/Struct.coffee
 
 (define (x:struct? x) (is-a? x x:struct%))
 
-(define (x:struct #:pre-encode [pre-proc #f]
-                  #:post-decode [post-proc #f]
-                  #:base-class [base-class x:struct%]
-                  . dicts)
+(define/contract (x:struct #:pre-encode [pre-proc #f]
+                           #:post-decode [post-proc #f]
+                           #:base-class [base-class x:struct%]
+                           . dicts)
+  (()
+   (#:pre-encode (or/c (any/c . -> . any/c) #false)
+    #:post-decode (or/c (any/c . -> . any/c) #false)
+    #:base-class (λ (c) (subclass? c x:struct%)))
+    #:rest (listof any/c)
+   . ->* .
+   x:struct?)
   (define args (flatten dicts))
   (unless (even? (length args))
     (raise-argument-error 'x:struct "equal number of keys and values" dicts))
diff --git a/xenomorph/xenomorph/versioned-struct.rkt b/xenomorph/xenomorph/versioned-struct.rkt
index 94fd61b2..91b19bfe 100644
--- a/xenomorph/xenomorph/versioned-struct.rkt
+++ b/xenomorph/xenomorph/versioned-struct.rkt
@@ -103,9 +103,13 @@ https://github.com/mbutterick/restructure/blob/master/src/VersionedStruct.coffee
 
 (define (x:versioned-struct? x) (is-a? x x:versioned-struct%))
 
-(define (x:versioned-struct type [versions (dictify)]
+(define (x:versioned-struct type
+                            [versions (dictify)]
                             #:pre-encode [pre-proc #f]
                             #:post-decode [post-proc #f]
                             #:base-class [base-class x:versioned-struct%])
-  (new (generate-subclass base-class pre-proc post-proc) [type type] [versions versions][fields #f]))
+  (new (generate-subclass base-class pre-proc post-proc)
+       [type type]
+       [versions versions]
+       [fields #f]))