
Syntax Utilities
----------------

The libraries of the "syntax" collection provide utilities for
manipulating expressions and inspecting modules.

======================================================================
_stx.ss_: deconstructing syntax objects
======================================================================

> (stx-null? v) - returns #t if `v' is either the empty list or a
  syntax object representing the empty list (i.e., `syntax-e' on the
  syntax object returns the empty list).

> (stx-pair? v) - returns #t if `v' is either a pair or a syntax
  object representing a pair. See also the definition of "syntax pair"
  in the MzScheme manual.

> (stx-list? v) - returns #t if `v' is a list, or if it is a sequence
  of pairs leading to a syntax object such that `syntax->list' (from
  MzScheme) would produce a list.

> (stx->list stx-list) - produces a list by flatting out a trailing
  syntax object using `syntax->list'. The `stx-list' argument must be
  a value for which `stx-list?' would return #t.

> (stx-car v) - takes the car of a "syntax pair". See the definition
  of "syntax pair" in the MzScheme manual.

> (stx-cdr v) - takes the cdr of a "syntax pair". See the definition
  of "syntax pair" in the MzScheme manual.

> (module-or-top-identifier=? a-id b-id) - returns #t if `a-id' and
  `b-id' are module-identifier=?, or if `a-id' and `b-id' have the
  same name (as extracted by `syntax-e') and `a-id' has no binding
  other than at the top level.

  This procedure is useful in conjunction with `syntax-case*' to match
  procedure names that are normally bound by MzScheme. For example,
  the `include' macro uses this procedure to recognize `build-path';
  using `module-identifier=?'  would not work well outside of
  `module', since the top-level `build-path' is a distinct variable
  from the MzScheme export (though it's bound to the same procedure,
  initially).

======================================================================
_kerncase.ss_: matching fully-expanded expressions
======================================================================

> (kernel-syntax-case stx-expr trans?-expr clause ...) - a syntactic
  form like `syntax-case*', except that the literals are built-in as
  the names of the primitive MzScheme forms. (The primitive syntactic
  forms must have their normal bindings in the context of the
  `kernel-syntax-case' expression.)

  The `trans?-expr' boolean expression replaces the comparision
  procedure, and instead selects simply between normal-phase
  comparisions or transformer-phase comparisions. The `clause's are
  the same as in `syntax-case*'.

> (kernel-form-identifier-list syntax) - returns a list of identifiers
  for the names of the primitive MzScheme forms for expressions, with
  the lexical context of `syntax'. This function is useful for
  generating a list of stopping points to provide to
  `syntax-local-expand'.

======================================================================
_toplevel.ss_: helper for moduleless compilation and expansion
======================================================================

> (expand-top-level-with-compile-time-evals expr) - expands `expr' as
  a top-level expression, and evaluates its compile-time portion for
  the benefit of later expansions.

  The expander recognizes top-level `begin' expressions, and
  interleaves the evaluation and expansion of of the `begin' body, so
  that compile-time expressions within the `begin' body affect later
  expansions within the body. (In other words, it ensures that
  expanding a `begin' is the same as expanding separate top-level
  expressions.)

> (eval-compile-time-part-of-top-level syntax) - evaluates
  expansion-time code in the fully expanded top-level expression
  represented by `syntax' (or a part of it, in the case of `begin'
  expressions). The expansion-time code might affect the compilation
  of later top-level expressions. For example, if `syntax' is a
  `require' expression, then `namespace-require/expansion-time' is
  used on each require specification in the form. Normally, this
  function is used only by `expand-top-level-with-compile-time-evals'.

======================================================================
_struct.ss_: generating the same names as `define-struct'
======================================================================

> (build-struct-names name-id field-ids omit-sel? omit-set?) -
  generates the names bound by `define-struct' given an identifier for
  the struct type name and a list of identifiers for the field
  names. The result is a list of identifiers:

      struct:`name-id'
      make-`name-id'
      `name-id'?
      `name-id'-`field'       ; for each `field' in `field-ids'
      set-`name-id'-`field'!  ; (getter and setter names alternate)
      ...

  If `omit-sel?' is true, then the selector names are omitted from the
  result list. If `omit-set?' is true, then the setter names are
  omitted from the result list.

> (build-struct-generation name-id field-ids omit-sel? omit-set?) -
  takes the same arguments as `build-struct-names' and generates an
  S-expression for code using `make-struct-type' to generate the
  structure type and return values for the identifiers creates by
  `build-struct-names'.

> (build-struct-expand-info name-id field-ids omit-sel? omit-set? base-getters base-setters) -
  takes the same arguments as `build-struct-names', plus a list of
  accessor and mutator identifiers (possibly ending in #f) for a
  parent type, and generates an S-expression for expansion-time code
  to be used in the binding for the structure name.

> (struct-declaration-info? v) - returns #t if `x' has the shape of
  expansion-time information for structure type declarations, #f
  otherwise. See also the syntax chapter of the MzScheme manual.

======================================================================
_name.ss_: extracting inferred names
======================================================================

> (syntax-local-infer-name stx) - similar to
>   syntax-local-name
  except that `stx' is checked for an
>   'inferred-name
  property (which overrides any inferred name). If neither
  `syntax-local-name' not 'inferred-name produce a name, then a name
  is constructed from the source-location information in `stx', if
  any. If no name can be constructed, the result is #f.

======================================================================
_docprovide.ss_: attaching documentation to exports
======================================================================

> (provide-and-document doc-label-id doc-row ...) - a form that
  exports names and records documentation information.  The
  `doc-label-id' identifier is used as a key for accessing the
  documentation through `lookup-documentation'.  The actual
  documentation is organized into "rows", each with a section title.

  A `row' has one of the following forms

   (section-string (name type-datum doc-string ...) ...)

     Creates a documentation section whose title is `section-string',
     and provides/documents each `name. The `type-datum' is arbitrary,
     for use by clients that call `lookup-documentation'. The
     `doc-string's are also arbitrary documentation information,
     usually concatenated by clients.

     A `name' is either an identifier or a renaming sequence
     `(local-name-id extenal-name-id)'.

     Multiple `row's with the same section name will be merged in the
     documentation output. The final order of sections matches the
     order of the first mention of each section.
  
   (all-from prefix-id module-path doc-label-id)
   (all-from-except prefix-id module-path doc-label-id id ...)

     where `all-from' and `all-from-except' are keywords. Merges
     documentation and provisions from the specified module into the
     current one; the `prefix-id' is used to prefix the imports into
     the current module (so they can be re-exported). If `id's are
     provided, the specified `id's are not re-exported and their
     documentation is not merged.  

> (lookup-documentation module-path-v label-sym) - returns
  documentation for the specified module and label. The
  `module-path-v' argument is a quoted module path, like the argument
  to MzScheme's `dynamic-require'. The `label-sym' identifies a set of
  documentation using the symbol as a label identifier in
  `provide-and-document'.

======================================================================
_moddep.ss_: inspecting modules and module dependencies
======================================================================

Interpretations of module paths in this library mimic that of the
default module path resolver in MzScheme (which means that the library
is limited, but certainly useful as no other module path resolvers
currently exist).

> (with-module-reading-parameterization thunk) - calls `thunk' with
  all reader parameters reset to their default values.

> (check-module-form stx expected-module-sym filename-string-or-#f) -
  inspects `stx' to check whether evaluating it will declare a module
  named `expected-module-sym' (plus a prefix, if
  `current-module-name-prefix' is set) --- at least if `module' is
  bound in the top-level to MzScheme's `module'. The syntax object
  `stx' can contain a compiled expression.

  If `stx' can declare a module in an appropriate top-level, then the
  `check-module-form' procedure returns a syntax object that certainly
  will declare a module (adding explicit context to the leading
  `module' if necessary) in any top-level. Otherwise, if
  `filename-string-or-#f' is a string, a suitable exception is raised,
  and if `filename-string-or-#f' is #f, #f is returned.

> (get-module-code module-path-v) - returns a compiled expression for
  the declaration of the module specified by `module-path-v'. The
  `module-path-v' argument is a quoted module path, as for MzScheme's
  `dynamic-require' using the default module path resolver.

> (resolve-module-path module-path-v rel-to-path-string/thunk/#f) -
  resolves a module path to filename string. The module path is
  resolved relative to `rel-to-path-string/thunk/#f' if it is a string
  (a filename path), to the directory result of calling the thunk if
  it is a thunk, or to the current directory otherwise.

> (resolve-module-path-index module-path-index rel-to-path-string/thunk/#f)
  - like `resolve-module-path' but the input is a module path index
  (see the MzScheme manual for details); in this case, the
  `rel-to-path-string/thunk/#f' base is used where the module path index
  contains the "self" index.  If `module-path-v' represents the
  "self" module path index, then an exception is raised unless
  `rel-to-path-string/thunk/#f' is a path string.

> (collapse-module-path module-path-v rel-to-module-path-v) - returns
  a "simplified" module path by combining `module-path-v' with
  `rel-to-module-path', where the latter must have the form '(lib
  <relative-path> <collection>), or '(file <path>).

> (collapse-module-path-index module-path-index rel-to-module-path-v)
  - like `collapse-module-path', but the input is a module path index
  (see the MzScheme manual for details); in this case, the
  `rel-to-module-path-v' base is used where the module path index
  contains the "self" index.

> (show-import-tree module-path-v) - a debugging aid that prints the
  import hierarchy starting from a given module path.

======================================================================
_readerr.ss_: signalling parse errors
======================================================================

> (raise-read-error msg-string source-v line-k col-k pos-k span-k)

Creates and raises an
>  exn:read
exception, using `msg-string' as the base error message.

Source-location information is added to the error message using the
last five arguments (if the `error-print-source-location' parameter is
set to #t). The `source-v' argument is an arbitrary value naming the
source location --- usually a file path string. Each of the `line-k',
`col-k', and `pos-k' arguments is #f or a positive exact integer
representing the location within `source-name' (as much as known), and
`span-k' is #f or a non-negative exact integer for an item range
starting from the indicated position.


======================================================================
_zodiac.ss_, _zodiac-unit.ss_, and _zodiac-sig.ss_: compatibility
  layer for software that used to use Zodiac
======================================================================

The interface is similar to Zodiac --- enough to be useful for porting
--- but different in many ways. See "zodiac-sig.ss" for details. New
software should not use this compatibility layer.

======================================================================
_path-spec.ss_: resolves `include'-like static path specification
======================================================================

> (resolve-path-spec path-spec-stx source-stx expr-stx build-path-stx)

Resolves the syntactic path specification `path-spec-stx' as for
MzLib's `include'. The `source-stx' specifies a syntax object whose
source-location information determines relative-path resolution.  The
`expr-stx' is used for reporting syntax errors. The `build-path-stx'
is usualyl #'build-path; it provides an identifier to compare to parts
of `path-spec-stx' to recognize the `build-path' keyword.
