Scheme index

Table of Contents

• Identifiers definitions
• Filterset definitions
• Development

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:

• https://index.scheme.org

• https://scheme-index.aartaka.me

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, except that it needs no desc-ription for the virtue of having a group one.
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: pure for procedures modifying no state; and predicate for boolean-returning single-argument procedures checking conformance of a value with certain criteria.
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).