8 WXME Decoding
Peeks from
in and returns
#t if it starts with the
magic bytes indicating a
WXME-format stream (see
File Format),
#f otherwise.
Takes an input port whose stream starts with
WXME-format data
and returns an input port that produces a text form of the WXME
content, like the result of opening a WXME file in DrRacket and saving
it as text.
If close? is true, then closing the result port close the
original port.
See Snip Class Mapping for information about the kinds of
non-text content that can be read.
Takes an input port whose stream starts with
WXME-format data
and returns an input port that produces text content converted to
bytes, and non-text content as “special” values (see
read-char-or-special).
These special values produced by the new input port are different than
the ones produced by reading a file into an editor<%>
object. Instead of instances of the snip%, the special values
are typically simple extensions of object%. See
Snip Class Mapping for information about the kinds of
non-text content that can be read.
If close? is true, then closing the result port close the
original port.
The snip-filter procedure is applied to any special value
generated for the stream, and its result is used as an alternate
special value.
If a special value (possibly produced by the filter procedure) is an
object implementing the readable<%> interface, then the
object’s read-special method is called to produce
the special value.
Returns two values: a list of snip-class names used by the given
stream, and a list of data-class names used by the stream. If the
stream is not a
WXME stream, the result is two empty lists. The
given stream is not closed, and only data for a
WXME stream (if
any) is consumed.
Maps a snip-class name to a quoted module path that provides a
reader% implementation. The module path must have the form
'(lib string ...), where each
string
contains only alpha-numeric ASCII characters,
.,
_,
-, and spaces.
Returns a quoted module path for
str for either
editor<%> mode when
gui? is true, or
wxme mode when
gui? is
#f. For the
latter, built-in mappings and mapping registered via
register-lib-mapping! are used. If
str cannot be
parsed as a library path, and if no mapping is available (either
because the class is built-in or not known), the result is
#f.
A parameter. When set to #f (the default), an exception is raised when
an unrecognized snip class is encountered in a
WXME
stream. When set to a true value, instances of unrecognized snip
classes are simply omitted from the transformed stream.
A parameter. Some old and short-lived
WXME formats depended on
the endian order of the machine where the file was saved. Set this
parameter to pick the endian order to use when reading the file; the
default is the current platform’s endian order.
Like
read, but for a stream that starts with
WXME-format data. If multiple S-expressions are in the
WXME data, they are all read and combined with
'begin.
If racket/gui/base is available (as determined by
gui-available?), then open-input-text-editor is
used. Otherwise, wxme-port->port is used.
Like
read-syntax, but for a
WXME-format input stream.
If multiple S-expressions are in the
WXME data, they are all
read and combined with
'begin.
If racket/gui/base is available (as determined by
gui-available?), then open-input-text-editor is
used. Otherwise, wxme-port->port is used.
An interface to be implemented by a reader for a specific kind of data
in a
WXME stream. The interface has two methods:
read-header and
read-snip.
Called at most once per
WXME stream to initialize the data
type’s stream-specific information. This method usually does nothing.
Called when an instance of the data type is encountered in the
stream. This method reads the data and returns either bytes to be
returned as part of the decoded stream or any other kind of value to
be returned as a “special” value from the decoded stream. The result
value can optionally be an object that implements
readable<%>.
An interface to be implemented by values returned from a snip reader.
The only method is
read-special.
Like
read-special, but for non-graphical
mode. When a value implements this interface, its
read-special method is called with source-location information to
obtain the “special” result from the
WXME-decoding port.
Reads an exact integer, analogous to
get-exact.
The what field describes what is being read, for
error-message purposes, in case the stream does not continue with an
integer.
Reads an exact integer that has a fixed size in the stream, analogous
to
get-fixed.
The what argument is as for read-integer.
Reads an inexact real number, analogous to
get-inexact.
The what argument is as for read-integer.
The what argument is as for read-integer.
The what argument is as for read-integer.
Reads a nested editor, producing a new input port to extract the
editor’s content.
8.1 Snip Class Mapping
When graphical data is marshaled to the WXME format, it is associated
with a snip-class name to be matched with an implementation at load
time. See also Snip Classes.
Ideally, the snip-class name is generated as
where each element of the formated list is a quoted module
path (see module-path?). The strings must contain only
alpha-numeric ASCII characters, plus ., _,
-, and spaces, and they must not be "." or
"..".
In that case, the first quoted module path is used for loading
WXME files in graphical mode; the corresponding module must
provide snip-class object that implements the
snip-class% class. The second quoted module path is used by
the wxme library for converting WXME streams
without graphical support; the corresponding module must provide a
reader object that implements the reader<%>
interface. Naturally, the snip-class% instance and
reader<%> instance are expected to parse the same format, but
generate different results suitable for the different contexts (i.e.,
graphical or not).
If a snip-class name is generated as
(format "~s" '(lib string ...))
then graphical mode uses the sole module path, and
wxme needs a compatibility mapping. Install one with
register-lib-mapping!.
If a snip-class name has neither of the above formats, then graphical
mode can use the data only if a snip class is registered for the name,
or if it the name of one of the built-in classes: "wxtext",
"wxtab", "wximage", or "wxmedia" (for
nested editors). The wxme library needs a
compatibility mapping installed with register-lib-mapping!
if it is not one of the built-in classes.
Several compatibility mappings are installed automatically for the
wxme library. They correspond to popular graphical
elements supported by various versions of DrRacket, including comment
boxes, fractions, XML boxes, Racket boxes, text boxes, and images
generated by the htdp/image teachpack (or, more
generally, from mrlib/cache-image-snip), and test-case
boxes.
For a port created by wxme-port->port, nested editors are
represented by instances of the editor% class provided by the
wxme/editor library. This class provides a single
method, get-content-port, which returns a port for
the editor’s content. Images are represented as instances of the
image% class provided by the wxme/image
library.
Comment boxes are represented as instances of a class that extends
editor% to implement readable<%>; see
wxme/comment. The read form produces a special comment
(created by make-special-comment), so that the comment box
disappears when read is used to read the stream; the
special-comment content is the readable instance. XML, Racket, and
text boxes similarly produce instances of editor% and
readable<%> that expand in the usual way; see
wxme/xml, wxme/scheme, and
wxme/text. Images from the
htdp/image teachpack
are packaged as instances of cache-image% from the
wxme/cache-image library. Test-case boxes are packaged
as instances of test-case% from the
wxme/test-case library.
8.1.1 Nested Editors
Instantiated for plain nested editors in a
WXME stream in text
mode.
Returns a port (like the one from
wxme-port->port) for the
editor’s content.
8.1.2 Images
Instantiated for images in a
WXME stream in text mode.
This class can just be treated like
image-snip% and should
behave just like it, except it has the methods below in addition
in case old code still needs them. In other words, the methods
below are provided for backwards compatibility with earlier
verisons of Racket.
Returns bytes for a PNG, XBM,or XPM file for the image.
Returns the display width of the image, which may differ from the
width of the actual image specified as data or by a filename; -1 means
that the image data’s width should be used.
Returns the display height of the image, which may differ from the
height of the actual image specified as data or by a filename; -1
means that the image data’s height should be used.
Returns an offset into the actual image to be used
as the left of the display image.
Returns an offset into the actual image to be used as the top of the
display image.
8.2 DrRacket Comment Boxes
A text-mode reader for comment boxes.
Instantiated for DrRacket comment boxes in a
WXME stream for
text mode.
No data is available.
Generates a special comment using
make-special-comment. The
special comment contains the comment text.
8.3 DrRacket XML Boxes
A text-mode reader for XML boxes.
Instantiated for DrRacket XML boxes in a
WXME stream for text
mode.
Returns #t if whitespace is elimited from the contained XML
literal, #f otherwise.
8.4 DrRacket Racket Boxes
A text-mode reader for Racket boxes.
Instantiated for DrRacket Racket boxes in a
WXME stream for text
mode.
Returns #t if the box corresponds to a splicing unquote,
#f for a non-splicing unquote.
Generates an S-expression for the code in the box.
8.5 DrRacket Text Boxes
A text-mode reader for text boxes.
Instantiated for DrRacket text boxes in a
WXME stream for text
mode.
No data is available.
Generates a string containing the text.
8.6 DrRacket Fractions
A text-mode reader for DrRacket fractions that generates exact,
rational numbers.
8.7 DrRacket Teachpack Images
Instantiated for DrRacket teachpack boxes in a
WXME stream for
text mode.
Returns a vector of bytes representing the content of the image.
Returns the width of the image.
Returns the height of the image.
Returns an offset across into the image for the pinhole.
Returns an offset down into the image for the pinhole.
8.8 DrRacket Test-Case Boxes
A text-mode reader for DrRacket test-case boxes in a WXME stream. It
generates instances of
test-case%.
Instantiated for old-style DrRacket test-case boxes in a
WXME
stream for text mode.
Returns a port for the comment field, if any.
Returns a port for the “test” field.
Returns a port for the “expected” field.
Returns a port for the “should raise” field, if any.
Returns a port for the “error msg” field, if any.
Returns #t if the test is enabled.
Returns #t if the test is collapsed.
Returns #t if the test is for an exception.