Scheme index

Table of Contents

• Identifiers definitions
• Signature syntax
  • Function
  • Syntax
  • Value
• Faux types
• 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/scheme-index .

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; see [_signature_syntax].
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.

Signature syntax

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.

A parameter <type> is either:

• a predicate name (eg. list?)^[1];

• a known "faux type" (see [_faux_types]);

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

A return type can be one 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>) …​)

A <pattern> is one of:

• symbol;

• .;

• …​;

• a list, i.e., (<pattern> …​).

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.

Faux types

Given dynamic typing nature of Scheme, without inherant introspection, the pragmatic way to define a type is through association to a predicate function that is capable to recognize it. This works well for majority of cases, but there are exceptions, and some type names don’t name an actual function you can call. These exceptions are documented in types/faux-types.scm, containing an alist, where key is a type symbol, and value is a string description documenting it.

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

---

1. The data is validated that a predicate follows convention and ends with an ?; subject to change if an exception is discovered