
======================================================================
_wxme.ss_ --- reading PLT graphical format (WXME) files without MrEd
======================================================================

> (is-wxme-stream? input-port)

Peeks from `input-port' and returns #t if it starts with magic bytes
indicating a WXME-format stream, #f otherwise.

The magic bytes are "WXME01<n><m> ##" for digits <n> and <n>, followed
by either a space, carriage return, or newline, and optionally
prefixed with "#reader(\"read.ss\"\"wxme\")".

> (wxme-port->text-port input-port [close?])

Takes an import 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 DrScheme and saving it as
text.

If `close?' is true (the default), then closing the result port close
the original port.

See "Snip Class Mapping" (below) for information about the kinds of
non-text content that can be read.

> (wxme-port->port input-port [close? snip-filter-proc-or-false])

Takes an import 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.

If `close?' is true (the default), then closing the result port close
the original port.

The `snip-filter-proc' is applied to any special value generated for
the stream, and its result is used as an alternate special value. The
default `snip-filter-proc' is the identity function.

If a special value (possibly produced by the filter procedure) is an
object implementing the `readable<%>' interface provided by "wxme.ss",
then the object's `read-special' method is called to produce the
special value.

See "Snip Class Mapping" (below) for information about the kinds of
non-text content that can be read.

> (extract-used-classes input-port)

Returns two values: a list of snip-class names (as strings) used by
the given stream, and a list of data-class names (as strings) 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.

> (register-lib-mapping! string quoted-module-path)

Maps a snip-class name to a quoted module path that provides a reader%
implementation. The module path must have the form '(lib <str> ...),
where each <str> contains only alpha-numeric ASCII characters, ".",
"_", "-", and spaces.

> (string->lib-path string mred?)

Returns a quoted module path for `string' for either MrEd mode (when
`mred?' is #t) or "wxme.ss" mode (when `mred?' is #f). For the latter,
built-in mappings and mapping registered via `register-lib-mapping!'
are used. If `string' 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.

> unknown-extensions-skip-enabled

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.

> broken-wxme-big-endian?

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.

> (wxme-read port)

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 MrEd is available (as determined by checking for `#%mred-kernel'),
then MrEd is used via `open-input-text-editor'. Otherwise,
`wxme-port->port' is used.

> (wxme-read-syntax source-v port)

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 MrEd is available (as determined by checking for `#%mred-kernel'),
then MrEd is used via `open-input-text-editor'. Otherwise,
`wxme-port->port' is used.

> snip-reader<%>

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 version-k stream-object)
>   (read-snip text-only? version-k stream-object)

The first method is called at most once per WXME stream to initialize
the data type's stream-specific information. This method usually does
nothing.

The second method is 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.

> readable<%>

An interface to be implemented by values returned from a snip reader.
The only method is `read-special', which takes four arguments related
to source location: a value indicating the source, the line (positive
integer or #f), column (non-negative integer or #f), and position
(positive integer or #f).

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.

------------------------------------------------------------
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.

Ideally, the snip-class name is generated as

 (format "~s" (list '(lib <str> ...)
                    '(lib <str> ...)))

where each element of the list is a quoted module path. The <str>s
must contain only alpha-numeric ASCII characters, plus ".", "-", "_",
or space, and must not be "." or "..".

In that case, the first quoted module path is used by MrEd for loading
WXME files in graphical mode; the corresponding module must provide
`snip-class' object that implements MrEd's `snip-class%' class. the
second quoted module path is used by the "wxme.ss" library for
converting WXME streams without MrEd support; the corresponding module
must provide a `reader' object that implements `reader<%>' interface
described above. Of course, the `snip-class%' instance and `reader<%>'
instance are expected to parse the same format, but generate different
results suitable for the different contexts (graphical or not).

If a snip-class name is generated as

 (format "~s" '(lib <str> ...))

then MrEd uses the sole module path, and the "wxme.ss" needs a
compatibility mapping. Install one with `register-lib-mapping!'.

If a snip-class name has neither of the above formats, then MrEd 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.ss" 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.ss" library. They correspond to popular graphical elements
supported by various versions of DrScheme, including comment boxes,
fractions, XML boxes, Scheme boxes, text boxes, and images generated
by the "world.ss" and "image.ss" teachpacks (or, more generally, from
"cache-image-snip.ss" in "mrlib"), 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
"editor.ss" library of the "wxme" collection. 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 "image.ss" library (see below).

Comment boxes are represented as instances of a class that extends
`editor%' to implement `readable<%>' (see "comment.ss"); 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,
Scheme, and text boxes similarly produce instances of `editor%' and
`readable<%>' that expand in the usual way (see "xml.ss", "scheme.ss",
and "text.ss"). Images from the "world.ss" and "image.ss" teachpacks
are packaged as instances of `cache-image%' from the "cache-image.ss"
library (see below). Test-case boxes are packaged as instances of
`test-case%' from the "test-case.ss" library (see below).

======================================================================
_editor.ss_ --- MrEd nested editors
======================================================================

Provides

> editor%

that is instantiated for plain nested editors in a WXME stream.
The class has one method:

> (get-content-port)

which returns a port (like the one from `wxme-port->port') for the
editor's content.

======================================================================
_image.ss_ --- MrEd images
======================================================================

Provides

> image%

that is instantiated for MrEd images in a WXME stream. The class
provides several methods:

> (get-filename) - returns a filename as bytes, or #f if 
                   data is available instead
> (get-data) - returns bytes for a PNG, XBM,or XPM file for the
               image
> (get-width) - returns the display width of the image, which may
                differ from the width of the actual image secified
                as data or by a filename
> (get-height) - returns the display height of the image, which may
                differ from the width of the actual image secified
                as data or by a filename
> (get-x-offset) - returns an offset into the actual image to be used
                   as the left of the display image
> (get-y-offset) - returns an offset into the actual image to be used
                   as the top of the display image

======================================================================
_comment.ss_ --- DrScheme comment boxes
======================================================================

In addition to `reader', an instance of `snip-reader<%>', this library
provides

> comment-editor%

which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for Drscheme comment boxes in a WXME stream. The
class includes a `get-data' method that always returns #f.

======================================================================
_xml.ss_ --- DrScheme XML boxes
======================================================================

In addition to `reader', an instance of `snip-reader<%>', this library
provides

> xml-editor%

which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for Drscheme XML boxes in a WXME stream. The
class includes a `get-data' method that returns #t if whitespace is
elimited from the contained XML literal, #f otherwise.

======================================================================
_scheme.ss_ --- DrScheme Scheme boxes
======================================================================

In addition to `reader', an instance of `snip-reader<%>', this library
provides

> scheme-editor%

which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for Drscheme Scheme boxes in a WXME stream. The
class includes a `get-data' method that returns #t if the box
corresponds to a spliciing unquote, #f for a non-splicing unquote.

======================================================================
_text.ss_ --- DrScheme text boxes
======================================================================

In addition to `reader', an instance of `snip-reader<%>', this library
provides

> text-editor%

which is a sub-class of `editor%' and implementation of `readable<%>'
that is instantiated for DrScheme text boxes in a WXME stream. The
class includes a `get-data' method that always returns #f.

======================================================================
_number.ss_ --- DrScheme fractions
======================================================================

This library provides just `reader', which an instance of
`snip-reader<%>' that converts DrScheme fractions in a WXME stream to
exact numbers.

======================================================================
_cache-image.ss_ --- DrScheme teachpack images
======================================================================

In addition to `reader', an instance of `snip-reader<%>', this library
provides

> cache-image%

which is instantiated for images in a WXME stream generated by the
"image.ss" and "world.ss" teachpacks (or, more generally, by
"cache-image-snip.ss" of "mrlib".  The class provides several methods:

> (get-argb) - returns a vector of integersin [0,255] representing
               the content of the image
> (get-width) - returns the width of the image
> (get-height) - returns the height of the image
> (get-pin-x) - returns an offset into the image for the pinhole
> (get-pin-y) - returns an offset into the image for the pinhole

======================================================================
_test-case.ss_ --- DrScheme test-case boxes
======================================================================

In addition to `reader', an instance of `snip-reader<%>', this library
provides

> test-case%

which is instantiated for DrScheme test-case boxes in a WXME stream.
The class provides several methods:

> (get-comment) - returns a port or #f for the comment field (if any)
> (get-test) - returns a port for the "test" field
> (get-expected) - returns a port for the "expected" field
> (get-should-raise) - returns a port/#f for the "should raise" field
> (get-error-message) - returns a port/#f for the "error msg" field
> (get-enabled?) - returns #t if the test is enabled
> (get-collapsed?) - returns #t if the test is collapsed
> (get-error-box?) - return #t if the test is for an exception
