Skip to content

Modules Common Library / description

description ​

A language-neutral description of the types of a module's exports (see #996 and #997).

A typed language that lets a program import a module (Python §4 Typed, for one) checks the program against the module's description, and maps it to its own types: number and function become the language's number and function types. The description is a superset of what the conductor knows: the conductor's DataType says CLOSURE, the description says what the function takes and returns, and it names the opaque types (Rune, not OPAQUE).

A description is written next to the plugin (description.ts in the bundle) and checked against it in the bundle's tests with checkDescription. It is JSON-serializable, so that a bundle can publish it next to its code.

Interfaces ​

FunctionDescription ​

Defined in: lib/modules-lib/src/description.ts:51

Properties ​

PropertyTypeDescriptionDefined in

name

string

‐

lib/modules-lib/src/description.ts:52

params

ParameterDescription[]

‐

lib/modules-lib/src/description.ts:55

returns

TypeDescription

‐

lib/modules-lib/src/description.ts:56

typeParameters?

string[]

The type parameters of a function that works for several types (make_tree[A]).

lib/modules-lib/src/description.ts:54


GenericOpaqueType ​

Defined in: lib/modules-lib/src/description.ts:46

An opaque type that has type parameters: a BinaryTree[A].

Properties ​

PropertyTypeDefined in

name

string

lib/modules-lib/src/description.ts:47

typeParameters

string[]

lib/modules-lib/src/description.ts:48


ModuleDescription ​

Defined in: lib/modules-lib/src/description.ts:59

Properties ​

PropertyTypeDescriptionDefined in

constants

{ name: string; type: TypeDescription; }[]

‐

lib/modules-lib/src/description.ts:66

functions

FunctionDescription[]

‐

lib/modules-lib/src/description.ts:65

module

string

The name that a program imports: rune.

lib/modules-lib/src/description.ts:62

opaqueTypes

(string | GenericOpaqueType)[]

The opaque types that the module defines: a name (Rune), or a name with type parameters.

lib/modules-lib/src/description.ts:64

version

1

‐

lib/modules-lib/src/description.ts:60


ParameterDescription ​

Defined in: lib/modules-lib/src/description.ts:40

Properties ​

PropertyTypeDefined in

name

string

lib/modules-lib/src/description.ts:41

type

TypeDescription

lib/modules-lib/src/description.ts:42

Type Aliases ​

TypeDescription ​

ts
type TypeDescription = 
  | "number"
  | "integer"
  | "string"
  | "boolean"
  | "void"
  | "any"
  | {
  arguments?: TypeDescription[];
  opaque: string;
}
  | {
  parameter: string;
}
  | {
  list: TypeDescription;
}
  | {
  pair: [TypeDescription, TypeDescription];
}
  | {
  array: TypeDescription;
}
  | {
  function: {
     params: TypeDescription[];
     returns: TypeDescription;
  };
};

Defined in: lib/modules-lib/src/description.ts:20

The type of a value that a module's function takes or returns.

Union Members ​

"number"


"integer"


"string"


"boolean"


"void"


"any"

A value of any type, which the function only inspects (is_tree): a program can only pass it on.


Type Literal ​
ts
{
  arguments?: TypeDescription[];
  opaque: string;
}

A value that the module defines and that a program can only pass back to it, by the name of its type; with the types that it is applied to, if the type has type parameters (BinaryTree[A]).


Type Literal ​
ts
{
  parameter: string;
}

A type parameter of the function that this type is a part of (A in entry[A]).


Type Literal ​
ts
{
  list: TypeDescription;
}

Type Literal ​
ts
{
  pair: [TypeDescription, TypeDescription];
}

Type Literal ​
ts
{
  array: TypeDescription;
}

Type Literal ​
ts
{
  function: {
     params: TypeDescription[];
     returns: TypeDescription;
  };
}

Variables ​

DESCRIPTION_VERSION ​

ts
const DESCRIPTION_VERSION: 1 = 1;

Defined in: lib/modules-lib/src/description.ts:17

The version of the format. A consumer rejects a version that it does not know.

Functions ​

checkDescription() ​

ts
function checkDescription(description, exportedSymbols): string[];

Defined in: lib/modules-lib/src/description.ts:171

What is wrong with a description of a plugin: validateDescription, and every name that the plugin exports must be described, and no other. Give it the symbols of the plugin's exports after initialise(), not exportedNames: a plugin can export names when it is loaded (rune's shapes).

Parameters ​

ParameterType

description

ModuleDescription

exportedSymbols

readonly string[]

Returns ​

string[]


fn() ​

ts
function fn(
   name, 
   params, 
   returns, 
   typeParameters?
): FunctionDescription;

Defined in: lib/modules-lib/src/description.ts:76

fn('scale', [['ratio', 'number'], ['rune', Rune]], Rune); typeParameters for a function that works for several types.

Parameters ​

ParameterType

name

string

params

[string, TypeDescription][]

returns

TypeDescription

typeParameters?

string[]

Returns ​

FunctionDescription


fun() ​

ts
function fun(params, returns): TypeDescription;

Defined in: lib/modules-lib/src/description.ts:72

Parameters ​

ParameterType

params

TypeDescription[]

returns

TypeDescription

Returns ​

TypeDescription


opaque() ​

ts
function opaque(name, ...args): TypeDescription;

Defined in: lib/modules-lib/src/description.ts:70

Short forms for writing a description by hand.

Parameters ​

ParameterType

name

string

...args

TypeDescription[]

Returns ​

TypeDescription


parameter() ​

ts
function parameter(name): TypeDescription;

Defined in: lib/modules-lib/src/description.ts:71

Parameters ​

ParameterType

name

string

Returns ​

TypeDescription


validateDescription() ​

ts
function validateDescription(description): string[];

Defined in: lib/modules-lib/src/description.ts:137

What is wrong with a description in itself, as messages (none if it is fine): a name that is used twice, an opaque type or type parameter that is not declared, an integer result.

Parameters ​

ParameterType

description

ModuleDescription

Returns ​

string[]