document racket/fasl

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]

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"]
 

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
+@scheme[write] or @racket[s-exp->fasl], later read from a stream using
-converted to a value like the original using
+@scheme[read] or @racket[fasl->s-exp], and then converted to a value
-@scheme[deserialize]. Serialization followed by deserialization
+like the original using @scheme[deserialize]. Serialization followed
-produces a value with the same graph structure and mutability as the
+by deserialization produces a value with the same graph structure and
-original value, but the serialized value is a plain tree (i.e., no
+mutability as the original value, but the serialized value is a plain
-sharing).
+tree (i.e., no sharing).
 
 The following kinds of values are serializable: