This site is a static rendering of the Trac instance that was used by R7RS-WG1 for its work on R7RS-small (PDF), which was ratified in 2013. For more information, see Home.

Source for wiki LibraryDeclarationsCowan version 10

author

cowan

comment

ipnr

127.11.51.1

name

LibraryDeclarationsCowan

readonly

text

This is a proposal to add further library declarations and import-set types to the large language.  '''Issue:  Phases are not yet dealt with.'''

== Library declarations ==

In R7RS it is not an error to provide a library declaration that a specific implementation does not understand, although implementations should provide warnings in such cases.  Most of these declarations specified here use "should", which means that implementations are allowed to silently ignore them if they are inappropriate.  Conflicts between declarations are resolved in an implementation-specific way.  Exceptions:

 * Support for `reexport`, `export-all` and `specify-declarations` is required.

 * Support for `notinline` is required for implementations that make the decision to inline code.

=== Name control (required) ===

`(reexport `''import-set'' ...`)`

Like `import`, but also exports all identifiers that were imported.  This allows a library to easily extend one or more other libraries.

`(export-all)`

Exports all defined identifiers except those that were imported.  This allows a library to be easily extended.

=== Optimization ===

In the list below, ''importance'' represents a symbol, one of `unimportant` (no importance), `neutral` (some importance, the default), `important` (substantial importance), or `extreme` (extreme importance).  It is an error to specify anything else.  These correspond to the Common Lisp importance values 0, 1, 2, and 3 respectively.

If no identifiers are named, then the library declaration applies to all identifiers defined in the library.  Implementations may (but should not) ignore the named identifiers and treat the declaration as applying to all identifiers. 

`(speed `''importance'' ''identifier'' ...`)`

The named ''identifiers'' should be processed so as to maximize execution speed to the extent specified by ''importance''.

`(space `''importance'' ''identifier'' ...`)`

The named ''identifiers'' should be processed so as to minimize the use of space at run time to the extent specified by ''importance''.

`(safety `''importance'' ''identifier'' ...`)`

The named ''identifiers'' should be processed so as to maximize safety at execution time to the extent specified by ''importance''.

`(compilation-speed `''importance'' ''identifier'' ...`)`

The named ''identifiers'' should be processed so as to maximize compilation speed to the extent specified by ''importance''.

`(debuggability `''importance'' ''identifier'' ...`)`

The named ''identifiers'' should be processed so as to maximize ease of debugging to the extent specified by ''importance''.

=== Numeric tower ===

`(numeric-tower ` ''identifier'' ...`)`

The ''identifiers'' indicate the assumptions the library makes about the availability of different kinds of numbers.    They may appear in any order, and have the following meanings:

`exactness-preserving`

The library relies on arithmetic operators other than `/` returning exact results when given exact arguments.

`no-exactness-preserving`

The library does not rely on arithmetic operators other than `/` returning exact results when given exact arguments.

`ratios`

The library relies on `/` returning exact results when given exact arguments.

`no-ratios`

The library does not rely on `/` returning exact results when given exact arguments.

`inexact`

The library relies on the availability of inexact numbers.

`no-inexact`

The library does not rely on the availability of inexact numbers.

`complex`

The library relies on the availability of non-real numbers.

`no-complex`

The library relies on the availability of non-real numbers.

`exact-complex`

The library does not rely on the availability of exact non-real numbers.

`no-exact-complex`

The library relies on the availability of exact non-real numbers.

For example, the declaration `(no-exactness-preserving no-ratios inexact no-complex)` means that the library assumes only a limited range of exact integers, with numeric operations potentially overflowing to inexact reals.  In consequence, it cannot run on an implementation that does not provide these features, and an implementation that provides non-integer exact numbers and non-real numbers may assume that these features are not used.

Note that in R7RS-large, implementations provide `exactness-preserving`, `ratio`, `inexact`, and `complex` by default, but using a declaration may allow implementations to specialize.

It is an error to specify any other identifier.

=== Types ===

`(type `''identifier'' ''predicate''`)`

The implementation may assume that ''identifier'' always has a value that will satisfy the predicate bound to ''predicate''.  If `#t` appears instead of ''predicate'', any value will satisfy it, but the absence of a value will not.

`(procedure-type `''identifier return-predicate arg-predicate'' ... `)`

`(procedure-type `''identifier` ( `''return-predicate'' ...`) `''arg-predicate'' ... `)`

The implementation may assume that ''identifier'' always has a value that is a procedure.  When this procedure is invoked, its value satisfies the predicate bound to ''return-predicate'' (for the first format) or its values satisfy the predicates bound to the ''return-predicates'' (for the second format).  In addition, its arguments (or an initial subsequence of them) satisfy the ''arg-predicates''.  f `#t` appears instead of a predicate identifier, any value will satisfy it, but the absence of a value will not.

'''Issue:  These declarations introduce phasing complications (where and when are the predicate names bound?) which must be resolved as part of a comprehensive treatment of phasing.'''

=== Compilation ===

If no identifiers are named, then the library declaration applies to all identifiers defined in the library.  Implementations may (but should not) ignore the named identifiers and treat the declaration as applying to all identifiers. 

`(inline `''identifier'' ...`)`

The procedures named by the ''identifiers'' should be inlined by the compiler, if there is one.

`(notinline `''identifier'' ...`)`

The procedures named by the ''identifiers'' must not be inlined by the compiler, if there is one.

`(unused `''identifier'' ...`)`

The implementation should not warn the user if the ''identifiers'' are defined but not used in the library.

`(verbose `''identifier'' ...`)`

The implementation should process the definitions of the named identifiers (if none are named, the whole library) verbosely.

`(terse `''identifier'' ...`)`

The implementation should process the definitions of the named identifiers (if none are named, the whole library) as quietly as is reasonable.  The user should still be notified of errors and warnings.

`(silent `''identifier'' ...`)`

The implementation should process the definitions of the named identifiers (if none are named, the whole library) silently.  The user should still be notified of errors.

=== Semantics ===

If no identifiers are named, then the library declaration applies to all identifiers defined in the library.  Implementations may (but should not) ignore the named identifiers and treat the declaration as applying to all identifiers. 

`(no-location `''identifier'' ...`)`

The implementation may assume that the procedures bound to ''identifier'' (if none are named, all procedures) have no location, so that neither `eq?` nor `eqv?` is required to return `#t` in any circumstances when passed a procedure argument.

== Declarations in main programs ==

To allow library declarations in main programs (not in files of code included by `include` or `include-ci`), the following new syntax is added:

`(specify-declarations `''declaration'' ...`)`

Allows any library declaration except `export` and `reexport` to be included as part of a main program.   It is an error for `declare` to appear except at the beginning of a main program.  For backward compatibility with R7RS-small, programmers should avoid wrapping `import`, `include`, `include-ci`, or `begin` declarations in `specify-declarations`.

The more natural term `declare` is avoided because some implementations use it for related but implementation-specific uses.

== Import sets ==

`(drop-prefix `''import-set'' ''identifier''`)`

Import sets of this kind automatically renames identifiers in the given ''import-set'': any of them which begin with the characters in ''identifier'' have those characters removed.

For example, if the library `(foo)` exports identifiers `foo-a`, `foo-b`, and `foo-c`, then `(import (drop-prefix (foo) foo-)` will import them under the names of `a`, `b`, and `c` respectively.  (Chibi Scheme already supports this type of import set.)

== Features ==

`(provide ` ''feature'' ...`)`

As a consequence of loading this library, the specified ''features'' are made immediately available to future `cond-expand` library declarations, to `cond-expand` syntax, and to the `features` procedure.

== See also ==

See also InterfacesCowan.

time

2014-05-15 20:22:22