Scheme index catalogs definitions of procedures, macros, values from scheme specifications and SRFI libraries, using sexpr textual format.

Browse index content through one of available frontends:

Rendered HTML version of this readme is available at https://schemeorg-community.github.io/index.scheme.org/.

Identifiers definitions

Identifiers definitions are grouped into files (one file for each library) under types/*.scm, and a single root index file which defines names and paths to those files types/index.scm.

Index file is a list of pairs - where car is a symbolic library name, and cdr is associated information regarding definitions to load from. cdr may be an alist, with following fields:

  • 'file - path from where to load definitions.

  • 'exclude - a list of definitions to ignore from the file.

Alternatively, cdr might be a string, in which case it’s treated as a file path.

(
    ((scheme base) . "types/scheme.base.scm")
    ((scheme r5rs) . ((file . "types/r5rs.scm")
                      (exclude . (transcript-on transcript-off))))
)

Each library definition file is a list of entries, where each entry is an association list, using symbols as keys. Each entry either describes a group of identifiers, or a single identifier.

Group has following properties:

key

description

group

A list of identifiers under the group. Each entry must have format as described under a table for single idenfier entry.

desc

A textual description applicable for entire group

Single identifier has following properties:

key

description

name

The name of the function / syntax / value. The name doesn’t have to be unique - in particular with procedures, definition is repeated for all possible invocation overloads with different parameter counts. Required.

signature

S-expr defining signature. The format depends on a type (function / syntax / value) being described.

Function

In case of function, the format is either (lambda (<parameter> …​) <return type>) or (case-lambda ((<parameter> …​) <return type>) …​).

Each parameter is either of the form (<type> param-name) or just param-name, when type is "any". Each parameter may be succeeded by a …​ literal to indicate varargs / repetition.

Parameter type is either:

  • a predicate name (eg. list?);

  • a type union in the form of (or <type> …​) (eg. (or list? number?)). When using or, #f might be used as a type inside of it due to its common appearance as a "null" value.

Return type can be same as parameter type described above, plus:

  • undefined, indicating a value that shouldn’t be used in portable code (eg. result of for-each);

  • *, indicating a useful value but of unknown type.

  • (values <type> …​) form when the function returns more than one value.

Syntax

In case of syntax, the format is (syntax-rules (<keyword> …​) (<pattern> <optional-return-type>) …​)

Pattern should be: symbol, ., …​, or grouping of patterns inside (). If optional return type is provided, it describes the resultant type when syntax is used as an expression. As a hatch to rendering outside of parens, use (_append ) form, which concatenates its arguments.

Value

In case of simple value, the format is (value <type>)

where type is same as described under functions.

tags

A list of symbols. Tags don’t have inherent special treatment (ie., definition can make use of any tag it wants). Currently used tags are described in [Tags]

subsigs

Additional elaboration of signatures for the parameters / returns / syntax fragments / datastructure content. Each entry in this list is a list, where first element is a name (corresponding to parameter / syntax fragment / etc), and second parameter is its signature. The signature can be either one of as described in signature section, as well as additionally:

  • (pattern <pattern> …​) - describes subsyntax pattern, expanding template variables used in main signature of the syntax;

  • (alist <car> <cdr>) - describes an alist datastrucutre, where <car> and <cdr> has same format as function parameter definition;

  • (list <element>) - describes a list datastrucutre, where <element> has same format as function parameter definition;

  • (vector <element>) - describes a vector datastrucutre, where <element> has same format as function parameter definition.

desc

Textual description.

Filterset definitions

Filterset is a coarse filter, and defines which libraries to include (and optionally how to rename them). Filterset definitions are structured into files one for each filterset option under filters/*.scm, and a single root index file which defines names and paths to those files filters/index.scm.

Index should be a list of alists. Each alist contains three fields:

  • code - used in links;

  • name - displayed text;

  • file - associated filterset definition file.

Filterset definition file should be a list of pairs. car is a symbolic library name (matching what is defined in index for identifiers definitions). cdr is either a symbolic library name (in which case, all the usages of library in car are renamed to what is in cdr), or a #t value (indicating to include library in car as is, without a rename).

Development

Use validatedata.scm helper in scheme-index-util folder to validate the data conforms to specification, by either:

  • Running validatedata-native.sh (requires chicken scheme installation);

  • Running validatedata-docker.sh (requires docker installation).