From a0e4eb990d112c6a3c922bcf4d94e15e247c1969 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sat, 9 Oct 2010 08:14:23 -0600
Subject: [PATCH] document racket/fasl

---
 collects/scribblings/reference/fasl.scrbl     | 43 +++++++++++++++++++
 collects/scribblings/reference/io.scrbl       |  1 +
 .../scribblings/reference/serialization.scrbl | 15 ++++---
 3 files changed, 52 insertions(+), 7 deletions(-)
 create mode 100644 collects/scribblings/reference/fasl.scrbl

diff --git a/collects/scribblings/reference/fasl.scrbl b/collects/scribblings/reference/fasl.scrbl
new file mode 100644
index 0000000000..a87752641c
--- /dev/null
+++ b/collects/scribblings/reference/fasl.scrbl
@@ -0,0 +1,43 @@
+#lang scribble/doc
+@(require "mz.ss"
+          (for-label racket/fasl))
+
+@(define fasl-eval (make-base-eval))
+@(interaction-eval #:eval fasl-eval (require racket/fasl))
+
+@title[#:tag "fasl"]{Fast-Load Serialization}
+
+@note-lib-only[racket/fasl]
+
+@deftogether[(
+@defproc[(s-exp->fasl [v any/c] [out (or/c output-port? #f) #f]) (or/c (void) bytes?)]
+@defproc[(fasl->s-exp [in (or/c input-port? bytes?)]) any/c]
+)]{
+
+The @racket[s-exp->fasl] function serializes @racket[v] to a byte
+string, printing it directly to @racket[out] if @racket[out] is an
+output port or return the byte string otherwise. The
+@racket[fasl->s-exp] function decodes a value from a byte string
+(supplied either directly or as an input port) that was encoded with
+@racket[s-exp->fasl].
+
+The @racket[v] argument must be a value that could be @racket[quote]d
+as a literal, because @racket[s-exp->fasl] essentially uses
+@racket[(compile `(quote ,v))] to encode the value using Racket's
+built-in fast-load format for bytecode.
+
+The byte-string encoding produced by @racket[s-exp->fasl] is specific
+to a version of Racket. That is, the resulting byte string can be
+decoded back to @racket[v] only using the same version with which it
+was encoded.
+
+@mz-examples[
+#:eval fasl-eval
+(define fasl (s-exp->fasl (list #("speed") 'racer #\!)))
+fasl
+(fasl->s-exp fasl)
+]}
+
+@; ----------------------------------------------------------------------
+
+@close-eval[fasl-eval]
diff --git a/collects/scribblings/reference/io.scrbl b/collects/scribblings/reference/io.scrbl
index 55118d78e2..99a271caf4 100644
--- a/collects/scribblings/reference/io.scrbl
+++ b/collects/scribblings/reference/io.scrbl
@@ -16,4 +16,5 @@
 @include-section["readtables.scrbl"]
 @include-section["custom-write.scrbl"]
 @include-section["serialization.scrbl"]
+@include-section["fasl.scrbl"]
 
diff --git a/collects/scribblings/reference/serialization.scrbl b/collects/scribblings/reference/serialization.scrbl
index df41ebb751..74dfee320b 100644
--- a/collects/scribblings/reference/serialization.scrbl
+++ b/collects/scribblings/reference/serialization.scrbl
@@ -1,7 +1,8 @@
 #lang scribble/doc
 @(require "mz.ss"
           racket/serialize
-          (for-label racket/serialize))
+          (for-label racket/serialize
+                     racket/fasl))
 
 @(define ser-eval (make-base-eval))
 @(interaction-eval #:eval ser-eval (require racket/serialize))
@@ -22,12 +23,12 @@ See @scheme[serialize] for an enumeration of serializable values.}
 
 Returns a value that encapsulates the value @scheme[v]. This value
 includes only readable values, so it can be written to a stream with
-@scheme[write], later read from a stream using @scheme[read], and then
-converted to a value like the original using
-@scheme[deserialize]. Serialization followed by deserialization
-produces a value with the same graph structure and mutability as the
-original value, but the serialized value is a plain tree (i.e., no
-sharing).
+@scheme[write] or @racket[s-exp->fasl], later read from a stream using
+@scheme[read] or @racket[fasl->s-exp], and then converted to a value
+like the original using @scheme[deserialize]. Serialization followed
+by deserialization produces a value with the same graph structure and
+mutability as the original value, but the serialized value is a plain
+tree (i.e., no sharing).
 
 The following kinds of values are serializable: