racket-common 6.3-1 / usr / share / racket / collects / syntax / doc.txt

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 Racket 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
  Racket) 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 Racket manual.

> (stx-cdr v) - takes the cdr of a "syntax pair". See the definition
  of "syntax pair" in the Racket 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 Racket. 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 Racket 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 Racket 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 comparison
  procedure, and instead selects simply between normal-phase
  comparisons or transformer-phase comparisons. The `clause's are
  the same as in `syntax-case*'.

> (kernel-syntax-case* stx-expr trans?-expr (extras ...) clause ...) -
  a syntactic form like `kernel-syntax-case', except that it takes an
  additional list of extra literals that are used as well as the
  primitive Racket forms.

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

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

> (expand-syntax-top-level-with-compile-time-evals stx) - expands `stx' 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.)

  The `stx' should have a context already, possibly introduced with
  `namespace-introduce-syntax'.

> (expand-top-level-with-compile-time-evals stx) - like
  `expand-syntax-top-level-with-compile-time-evals', but `stx' is
  first given context by applying `namespace-introduce-syntax' to it.

> (expand-top-level-with-compile-time-evals/flatten stx) - like
  `expand-syntax-top-level-with-compile-time-evals', except that it
  returns a list of syntax objects, none of which have a
  `begin'. These syntax objects are the flattened out contents of any
  `begin's in the expansion of `stx'.

> (eval-compile-time-part-of-top-level stx) - evaluates
  expansion-time code in the fully expanded top-level expression
  represented by `stx' (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 `stx' 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'.

> (eval-compile-time-part-of-top-level/compile stx) - like
  `eval-compile-time-part-of-top-level', but the result is compiled
  code.

======================================================================
_define.ss_: handling all the same function forms as `define'
======================================================================

> (normalize-definition defn-stx lambda-id-stx [check-context? opt+kws?]) -
  takes a definition form whose shape is like `define' (though
  possibly with a different name) and returns two values: the
  defined identifier and the right-hand side expression.

  To generate the right-hand side, this function may need to insert
  uses of `lambda'. The `lambda-id-stx' argument provides a suitable
  `lambda' identifier.

  If the definition is ill-formed, a syntax error is raised. If
  `check-context?' is true, then a syntax error is raised if
  `(syntax-local-context)' indicates that the current context is an
  expression context. The default value of `check-context?' is #t.

  If `opt-kws?' is #t, then arguments of the form `[id expr]',
  `keyword id', and `keyword [id expr]' are allowed, and they are
  preserved in the expansion.

> (normalize-definition/mk-rhs defn-stx lambda-id-stx [check-context? opt+kws? err-no-body?]) -

  the helper for `normalize-definition' that produces three values:
  the defined identifier, a function that takes the syntax of the body
  and produces syntax that has the expected binding structure, and
  finally the right-hand side expression that `normalize-definition'
  gives to the previous function.

  If `err-no-body?' is true, then there must be a right-hand side
  expression or else it is a syntax error. This is true for uses of
  `normalize-definition'.

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

> (parse-define-struct stx orig-stx) - parses `stx' as a `define-struct' 
  form, but uses `orig-stx' to report syntax errors (under the
  assumption that `orig-stx' is the same as `stx', or that they at
  least share sub-forms). The result is four values: an identifier for
  the struct type name, a identifier or #f for the super-name, a list
  of identifiers for fields, and a syntax object for the inspector
  expression.

> (build-struct-names name-id field-ids omit-sel? omit-set? [src-stx]) -
  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.

  The default src-stx is #f; it is used to provide a source location
  to the generated identifiers.

> (build-struct-generation name-id field-ids omit-sel? omit-set? 
                          [super-type prop-value-list immutable-k-list]) -
  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 created by
  `build-struct-names'.  The optional `super-type', `prop-value-list',
  and `immutable-k-list' parameters take s-expression values that are
  used as the corresponding arguments to `make-struct-type'.

> (build-struct-generation* all-name-ids name-id field-ids omit-sel? omit-set? 
                            [super-type prop-value-list immutable-k-list]) -
  like `build-struct-generation', but given the names produced by
  `build-struct-names', instead of re-generating them.

> (build-struct-expand-info name-id field-ids omit-sel? omit-set?
                            base-name base-getters base-setters) - 
  takes the same arguments as `build-struct-names', plus a parent
  identifier/#t/#f and 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. A #t for the base-name means no super-type, #f
  means that the super-type (if any) is unknown, and an identifier
  indicates the super-type identifier.

> (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 Racket manual.

> (generate-struct-declaration orig-stx name-id super-id-or-false
                               field-id-list current-context
			       make-make-struct-type
                               [omit-sel? omit-set?])

  This procedure implements the core of a `define-struct' expansion.

  The `generate-struct-declaration' procedure is called by a macro
  expander to generate the expansion, where the `name-id',
  `super-id-or-false', and `field-id-list' arguments provide the main
  parameters. The `current-context' argument is normally the result of
  `syntax-local-context'. The `orig-stx' argument is used for syntax
  errors. The optional `omit-sel?' and `omit-set?' arguments default
  to #f; a #t value suppresses definitions of field selectors or
  mutators, respectively.

  The `make-struct-type' procedure is called to generate the
  expression to actually create the struct type. Its arguments are
  `orig-stx', `name-id-stx', `defined-name-stxes', and `super-info'.
  The first two are as provided originally to
  `generate-struct-declaration', the third is the set of names
  generated by `build-struct-names', and the last is super-struct info
  obtained by resolving `super-id-or-false' when it is not #f, #f
  otherwise.

  The result should be an expression whose values are the same as the
  result of `make-struct-type'. Thus, the following is a basic
  `make-make-struct-type'

      (lambda (orig-stx name-stx defined-name-stxes super-info)
	#`(make-struct-type '#,name-stx 
			     #,(and super-info (list-ref super-info 0))
			     #,(/ (- (length defined-name-stxes) 3) 2)
			     0 #f))

  but an actual `make-make-struct-type' will likely do more.
 
======================================================================
_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 Racket'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
======================================================================

Re-exports "modread.ss", "modcode.ss", "modcollapse.ss", and
"modresolve.ss", in addition to the following:

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

======================================================================
_modread.ss_: reading module source code
======================================================================

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

> (check-module-form stx expected-module-sym source-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 Racket's `module'. The syntax object
  `stx' can contain a compiled expression. Also, `stx' can be an
  end-of-file, on the grounds that `read-syntax' can produce an
  end-of-file.

  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
  `source-string-or-#f' is not #f, a suitable exception is raised
  using the `write' form of the source in the message; if
  `source-or-#f' is #f, #f is returned.

  If stx is eof or eof wrapped as a syntax object, then an error is
  raised or #f is returned.

======================================================================
_modcode.ss_: getting module compiled code
======================================================================

> (get-module-code path [compiled-subdir compile-proc ext-proc]
                   [#:choose choose-proc]
                   [#:notify notify-proc]) -
  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 Racket's `dynamic-require' using the
  default module path resolver.

  The `compiled-subdir' argument defaults to "compiled"; it specifies
  the sub-directory to search for a compiled version of the module.

  The `compile-proc' argument defaults to `compile'. This procedure is
  used to compile module source if an already-compiled version is not
  available.

  The `ext-proc' argument defaults to #f. If it is not #f, it must be
  a procedure of two arguments that is called when a native-code
  version of `path' is should be used. In that case, the arguments to
  `ext-proc' are the path for the extension, and a boolean indicating
  whether the extension is a _loader file (#t) or not (#f).

  The `choose-proc' argument is a procedure that takes three paths: a
  source path, a .zo file path, and an extension path (for a
  non-_loader extension). Some of the paths may not exist. The result
  should be either 'src, 'zo, 'so, or #f, indicating which variant
  should be used or (in the case of #f) that the default choice should
  be used.

  The default choice is computed as follows: if a ".zo" version of
  `path' is available and newer than `path' itself (in one of the
  directories specified by `compiled-subdir'), then it is used instead
  of the source. Native-code versions of `path' are ignored, unless
  only a native-code non_loader version exists (i.e., `path' itself
  does not exist). A _loader extension is selected a last resort.

  If an extension is preferred or is the only file that exists, it is
  supplied to `ext-proc' when `ext-proc' is #f, or an exception is
  raised (to report that an extension file cannot be used) when
  `ext-proc' is #f.

   If `notify-proc' is supplied, it is called for the file (source,
   ".zo" or extension) that is chosen.

> moddep-current-open-input-file
 
  A parameter whose value is used like `open-input-file' to read a
  module source or ".zo" file.


> exn:get-module-code
> exn:get-module-code?
> exn:get-module-code-path
> make-exn:get-module-code

  An exception structure type for exceptions raised by
  `get-module-code'.

======================================================================
_modresolve.ss_: resolving module paths to file paths
======================================================================

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

> (resolve-module-path module-path-v rel-to-path-string/thunk/#f) -
  resolves a module path to filename path. The module path is resolved
  relative to `rel-to-path-string/thunk/#f' if it is a path string
  (assumed to be for a file), to the directory result of calling the
  thunk if it is a thunk, or to the current directory otherwise. The
  `module-path-v' argument is a quoted module path, as for Racket's
  `dynamic-require' using the default module path resolver.

> (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 Racket 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-index' depends on
  the "self" module path index, then an exception is raised unless
  `rel-to-path-string/thunk/#f' is a path string.

======================================================================
_modcollapse.ss_: simplifying module paths
======================================================================

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

> (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
  ....), '(file <string>), '(path ....) a path, or a thunk to generate
  one of those. The `module-path-v' argument is a quoted module path,
  as for Racket's `dynamic-require' using the default module path
  resolver.

  The result can be a path if `module-path-v' contains a path element
  that is needed for the result, or if `rel-to-module-path-v' is a
  non-string path that is needed for the result; otherwise, the result
  is a printable "quoted" module 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 Racket manual for details); in this case, the
  `rel-to-module-path-v' base is used where the module path index
  contains the "self" index.

======================================================================
_readerr.ss_: signaling 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', `pos-k' arguments is #f or a positive exact integer
  representing the location within `source-name' (as much as known),
  `col-k' is a non-negative exact integer for the source column (if
  known), and `span-k' is #f or a non-negative exact integer for an
  item range starting from the indicated position.

  The usual location values should point at the beginning of whatever
  it is you were reading, and the span usually goes to the point the
  error was discovered.

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

  Like `raise-read-error', but raises
>  exn:read:eof
  instead of `exn:read'.

======================================================================
_boundmap.ss_: mapping identifiers based on bound-identifier=? and module-identifier=?
======================================================================

> (make-bound-identifier-mapping) - produces a hash-table-like value
   for storing a mapping from syntax identifiers to arbitrary
   values.

   The mapping uses `bound-identifier=?' to compare mapping keys, but
   also uses a hash table based on symbol equality to make the mapping
   efficient in the common case (i.e., where non-equivalent identifiers
   are derived from different symbolic names).

> (bound-identifier-mapping? v) - #t if v was produced by
   `make-bound-identifier-mapping', #f otherwise.

> bound-identifier-mapping-get : (bound-identifier-mapping?
				  identifier?
				  [(-> any)]
				  . opt-> . 
				  any)
  - Like `hash-table-get' for bound-identifier mappings.

> bound-identifier-mapping-put! : (bound-identifier-mapping?
				   identifier?
				   any?
				   . -> .
				   void?)
  - Like `hash-table-put! for bound-identifier mappings.

> bound-identifier-mapping-for-each : (bound-identifier-mapping?
				       (identifier? any? . -> . any)
				       . -> .
				       void?)
  - Like `hash-table-for-each'

> bound-identifier-mapping-map : (bound-identifier-mapping?
				  (identifier? any? . -> . any)
				  . -> .
				  (listof any?))
  - Like `hash-table-map'


> (make-module-identifier-mapping) - produces a hash-table-like value
   for storing a mapping from syntax identifiers to arbitrary
   values.

   The mapping uses `module-identifier=?' to compare mapping
   keys, but also uses a hash table based on symbol equality
   to make the mapping efficient in the common case (i.e., where
   non-equivalent identifiers are derived from different symbolic
   names at their definition sites).

> (module-identifier-mapping? v) - #t if v was produced by
   `make-module-identifier-mapping', #f otherwise.

> module-identifier-mapping-get : (opt->
                                   (module-identifier-mapping?
                                    identifier?)
                                   [(-> any)]
                                   any)
  - Like `hash-table-get' for module-identifier mappings.

> module-identifier-mapping-put! : (module-identifier-mapping?
                                    identifier?
                                    any?
                                    . -> .
                                    void?)
  - Like `hash-table-put! for module-identifier mappings.

> module-identifier-mapping-for-each : (module-identifier-mapping?
                                        (identifier? any? . -> . any)
                                        . -> .
                                        void?)
  - Like `hash-table-for-each'

> module-identifier-mapping-map : (module-identifier-mapping?
                                   (identifier? any? . -> . any)
                                   . -> .
                                   (listof any?))
  - Like `hash-table-map'


======================================================================
_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 result is a complete path.

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 usually
#'build-path; it provides an identifier to compare to parts of
`path-spec-stx' to recognize the `build-path' keyword.

======================================================================
_context.ss_: support for _local-expand_
======================================================================

> (build-expand-context v) - returns an immutable list suitable for
  use as a context argument to `local-expand' for an
  internal-definition context. The `v' argument represents the
  immediate context for expansion. The context list builds on
  `(syntax-local-context)' if it is a list.

> (generate-expand-context) - calls `build-expand-context' with a
  generated symbol.

======================================================================
_trusted-xforms.ss_: trustworthy recertifying transformers
======================================================================

This module has no exports. It exists only to require other modules
that perform syntax transformations, where the other transformations
must use `syntax-recertify'. An application that wishes to provide a
less powerful code inspector to a sub-program should generally attach
"trusted-xforms.ss" to the sub-program's namespace so that things like
the class system work properly.


======================================================================
_to-string.ss_: rendering syntax objects with formatting
======================================================================

> (syntax->string stx-list) - builds a string with newlines
  and indenting according to the source locations in stx-list

  the outer pair of parens are not rendered from stx-list.

======================================================================
_free-vars.ss_: computing the free variables of an expression
======================================================================

> (free-vars expr-stx) - Returns a list of free lambda- and let-bound
  identifiers in expr-stx. The expression must be fully expanded.