wiki:LibraryDeclarationsCowan

Version 7 (modified by cowan, 4 years ago) (diff)

--

This is a proposal to add further library declarations and import-set types to the large language.

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. Furthermore, implementations may (but should not) ignore any list of identifiers. Conflicts between declarations are resolved in an implementation-specific way. Exceptions:

  • Support for reexport and export-all is required.
  • Precise 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.

If no identifiers are named, then the library declaration applies to all defined 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.

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: This introduces phasing complications (where and when are the predicates bound?) which must be resolved as part of a comprehensive treatment of phasing.

Compilation

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

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:

(declare 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 declare declarations.

Import sets

(drop-prefix import-set identifier)

This import set 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.

See also InterfacesCowan.