diff --git a/docs/user-defined-type-functions.md b/docs/user-defined-type-functions.md index 811370c..8b56bfc 100644 --- a/docs/user-defined-type-functions.md +++ b/docs/user-defined-type-functions.md @@ -98,380 +98,103 @@ This section details the initial programming interface we propose for `type`s wh
Expand for full type API reference. -

types Library

+### `types` Library - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Library PropertiesTypeDescription
unknowntypean immutable instance of the built-in type unknown
nevertypean immutable instance of the built-in type never
anytypean immutable instance of the built-in type any
booleantypean immutable instance of the built-in type boolean
numbertypean immutable instance of the built-in type number
stringtypean immutable instance of the built-in type string
+| Library Properties | Type | Description | +| ------------- | ------------- | ------------- | +| `unknown` | `type` | an immutable instance of the built-in type `unknown` | +| `never` | `type` | an immutable instance of the built-in type `never` | +| `any` | `type` | an immutable instance of the built-in type `any` | +| `boolean` | `type` | an immutable instance of the built-in type `boolean` | +| `number` | `type` | an immutable instance of the built-in type `number` | +| `string` | `type` | an immutable instance of the built-in type `string` | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Library FunctionsReturn TypeDescription
singleton(arg: string | boolean | nil)typereturns an immutable instance of the argument as a singleton type
negationof(arg: type)typereturns an immutable instance of the parameter as a negated type; the parameter cannot be a table or function type
unionof(...: type)typereturns an immutable instance of a union type of the arguments; requires at least 2 parameters to be provided
intersectionof(...: type)typereturns an immutable instance of an intersection type of the arguments; requires at least 2 parameters to be provided
newtable(props: {[type]: type | { read: type, write: type } }?, indexer: { key: type, value: type }?, metatable: type?)typereturns a mutable instance of a table type; the keys of the table's property must be a singleton type; sets the table's metatable if one is provided
newfunction(parameters: { head: {type}?, tail: type? }, returns: { head: {type}?, tail: type? })typereturns a mutable instance of a function type
copy(arg: type)typereturns a deep copy of the given type
+| Library Functions | Return Type | Description | +| ------------- | ------------- | ------------- | +| `singleton(arg: string \| boolean \| nil)` | `type` | returns an immutable instance of the argument as a singleton type | +| `negationof(arg: type)` | `type` | returns an immutable instance of the parameter as a negated type; the parameter cannot be a table or function type | +| `unionof(...: type)` | `type` | returns an immutable instance of an union type of the arguments; requires at least 2 parameters to be provided | +| `intersectionof(...: type)` | `type` | returns an immutable instance of an intersection type of the arguments; requires at least 2 parameters to be provided | +| `newtable(props: {[type]: type \| { read: type, write: type } }?, indexer: { key: type, value: type }?, metatable: type?)` | `type` | returns a mutable instance of a table type; the keys of the table's property must be a singleton type; sets the table's metatable if one is provided | +| `newfunction(parameters: { head: {type}?, tail: type? }, returns: { head: {type}?, tail: type? })` | `type` | returns a mutable instance of a `function` type | +| `copy(arg: type)` | `type` | returns a deep copy of the given `type` | -

type Instance

+### `type` Instance - - - - - - - - - - - - - - - -
Instance PropertiesTypeDescription
tag"nil" | "unknown" | "never" | "any" | "boolean" | "number" | "string" | "singleton" | "negation" | "union" | "intersection" | "table" | "function" | "class"an immutable property holding this type's tag
+| Instance Properties | Type | Description | +| ------------- | ------------- | ------------- | +| `tag` | `"nil" \| "unknown" \| "never" \| "any" \| "boolean" \| "number" \| "string" \| "singleton" \| "negation" \| "union" \| "intersection" \| "table" \| "function" \| "class"` | an immutable property holding this type's tag | - - - - - - - - - - - - - - - - - - - - -
Instance MethodsReturn TypeDescription
__eq(arg: type)booleanoverrides the == operator to return true if self is syntactically equal to arg, note that semantically equivalent types like true | false and boolean will not compare equal
is(arg: string)booleanreturns true if self has the same tag as the argument. List of available tags: "nil", "unknown", "never", "any", "boolean", "number", "string", "singleton", "negation", "union", "intersection", "table", "function", "class"
+| Instance Methods | Return Type | Description | +| ------------- | ------------- | ------------- | +| `__eq(arg: type)` | `boolean` | overrides the == operator to return true if self is syntactically equal to arg, note that semantically equivalent types like `true \| false` and `boolean` will _not_ compare equal | +| `is(arg: string)` | `boolean` | returns true if self has the same tag as the argument. List of available tags: "nil", "unknown", "never", "any", "boolean", "number", "string", "singleton", "negation", "union", "intersection", "table", "function", "class" | -

Negation `type` instance

+Depending on the particular `tag`, a `type` instance can have additional properties and methods available as described below. - - - - - - - - - - - - - - - -
Instance MethodsTypeDescription
inner()typereturns the type being negated
+#### Negation `type` instance -

Singleton `type` instance

+| Instance Methods | Type | Description | +| ------------- | ------------- | ------------- | +| `inner()` | `type` | returns the `type` being negated | - - - - - - - - - - - - - - - -
Instance MethodsReturn TypeDescription
value()string | boolean | nilreturns the actual value of the singleton, i.e., a specific string, boolean, or nil
+#### Singleton `type` instance -

Table `type` instance

+| Instance Methods | Return Type | Description | +| ------------- | ------------- | ------------- | +| `value()` | `string \| boolean \| nil` | returns the actual value of the singleton, i.e. a specific string, boolean, or `nil` | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Instance MethodsReturn TypeDescription
setproperty(key: type, value: type?)()adds / overrides (if same key exists) a key, value pair to the table's properties; if value is nil, removes the key, value pair; if the key does not exist and the value is nil, nothing happens; equivalent to calling setreadproperty and setwriteproperty with the same parameters
setreadproperty(key: type, value: type?)()adds / overrides (if same key exists) a key, value pair to the table's properties; if value is nil, removes the key, value pair; if the key does not exist and the value is nil, nothing happens
setwriteproperty(key: type, value: type?)()adds / overrides (if same key exists) a key, value pair to the table's properties; if value is nil, removes the key, value pair; if the key does not exist and the value is nil, nothing happens
readproperty(key: type)type?returns the type used for reading values to this property in the table; if the key does not exist, returns nil
writeproperty(key: type)type?returns the type used for writing values to this property in the table; if the key does not exist, returns nil
properties(){[type]: { read: type?, write: type? } }returns a table mapping property keys to a table with their respective read and write types
setindexer(index: type, result: type)()sets the table's indexer with the index type as the first parameter, and the result as the second parameter; equivalent to calling setreadindexer and setwriteindexer with the same parameters
setreadindexer(index: type, result: type)()sets the table's indexer with the index type as the first parameter, and the resulting read type as the second parameter
setwriteindexer(index: type, result: type)()sets the table's indexer with the index type as the first parameter, and the resulting write type as the second parameter
indexer(){ index: type, readresult: type, writeresult: type }?returns the table's indexer as a table; if the indexer does not exist, returns nil
readindexer(){ index: type, result: type }?returns the table's indexer as a table using the read type of the result; if the indexer does not exist, returns nil
writeindexer(){ index: type, result: type }?returns the table's indexer as a table using the write type of the result; if the indexer does not exist, returns nil
setmetatable(arg: type)()sets the table's metatable to the argument
metatable()type?returns the table's metatable; if the metatable does not exist, returns nil
+#### Table `type` instance -

Function `type` instance

+| Instance Methods | Return Type | Description | +| ------------- | ------------- | ------------- | +| `setproperty(key: type, value: type?)` | `()` | adds / overrides (if same key exists) a key, value pair to the table's properties; if value is nil, removes the key, value pair; if the key does not exist and the value is nil, nothing happens; equivalent to calling `setreadproperty` and `setwriteproperty` with the same parameters | +| `setreadproperty(key: type, value: type?)` | `()` | adds / overrides (if same key exists) a key, value pair to the table's properties; if value is nil, removes the key, value pair; if the key does not exist and the value is nil, nothing happens | +| `setwriteproperty(key: type, value: type?)` | `()` | adds / overrides (if same key exists) a key, value pair to the table's properties; if value is nil, removes the key, value pair; if the key does not exist and the value is nil, nothing happens | +| `readproperty(key: type)` | `type?` | returns the type used for _reading_ values to this property in the table; if the key does not exist, returns nil | +| `writeproperty(key: type)` | `type?` | returns the type used for _writing_ values to this property in the table; if the key does not exist, returns nil | +| `properties()` | `{[type]: { read: type?, write: type? } }` | returns a table mapping property keys to a table with their respective read and write types | +| `setindexer(index: type, result: type)` | `()` | sets the table's indexer with the index type as the first parameter, and the result as the second parameter; equivalent to calling `setreadindexer` and `setwriteindexer` with the same parameters | +| `setreadindexer(index: type, result: type)` | `()` | sets the table's indexer with the index type as the first parameter, and the resulting read type as the second parameter | +| `setwriteindexer(index: type, result: type)` | `()` | sets the table's indexer with the index type as the first parameter, and the resulting write type as the second parameter | +| `indexer()` | `{ index: type, readresult: type, writeresult: type }?` | returns the table's indexer as a table; if the indexer does not exist, returns nil | +| `readindexer()` | `{ index: type, result: type }?` | returns the table's indexer as a table using the read type of the result; if the indexer does not exist, returns nil | +| `writeindexer()` | `{ index: type, result: type }?` | returns the table's indexer as a table using the write type of the result; if the indexer does not exist, returns nil | +| `setmetatable(arg: type)` | `()` | sets the table's metatable to the argument | +| `metatable()` | `type?` | returns the table's metatable; if the metatable does not exist, returns nil | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Instance MethodsReturn TypeDescription
setparameters(head: {type}?, tail: type?)()sets the function's parameter types to the given arguments
parameters(){ head: {type}?, tail: type? }returns the function's parameter list as an array of ordered parameter types and optionally a variadic tail
setreturns(head: {type}?, tail: type?)()sets the function's return types to the given arguments
returns(){ head: {type}?, tail: type? }returns the function's return types as an array of types and optionally a variadic tail
+#### Function `type` instance -

Union `type` instance

+| Instance Methods | Return Type | Description | +| ------------- | ------------- | ------------- | +| `setparameters(head: {type}?, tail: type?)` | `()` | sets the function's parameter types to the given arguments | +| `parameters()` | `{ head: {type}?, tail: type? }` | returns the function's parameter list as an array of ordered parameter types and optionally a variadic tail | +| `setreturns(head: {type}?, tail: type?)` | `()` | sets the function's return types to the given arguments | +| `returns()` | `{ head: {type}?, tail: type? }` | returns the function's return types as an array of types and optionally a variadic tail | - - - - - - - - - - - - - - - -
Instance MethodsReturn TypeDescription
components(){type}returns an array of types being unioned
+#### Union `type` instance -

Intersection `type` instance

+| Instance Methods | Return Type | Description | +| ------------- | ------------- | ------------- | +| `components()` | `{type}` | returns an array of `types` being unioned | - - - - - - - - - - - - - - - -
Instance MethodsReturn TypeDescription
components(){type}returns an array of types being intersected
+#### Intersection `type` instance -

Class `type` instance

+| Instance Methods | Return Type | Description | +| ------------- | ------------- | ------------- | +| `components()` | `{type}` | returns an array of `types` being intersected | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Instance MethodsReturn TypeDescription
properties(){[type]: { read: type, write: type } }returns a table mapping class' property keys to a table with their respective read and write types
readparent()type?returns the read type of class' parent class; if the parent class does not exist, returns nil
writeparent()type?returns the write type class' parent class; if the parent class does not exist, returns nil
metatable()type?returns the class' metatable; if the metatable does not exist, returns nil
indexer(){ index: type, readresult: type, writeresult: type }?returns the class' indexer as a table; if the indexer does not exist, returns nil
readindexer(){ index: type, result: type }?returns the class' indexer as a table using the read type of the result; if the indexer does not exist, returns nil
writeindexer(){ index: type, result: type }?returns the class' indexer as a table using the write type of the result; if the indexer does not exist, returns nil
+#### Class `type` instance + +| Instance Methods | Return Type | Description | +| ------------- | ------------- | ------------- | +| `properties()` | `{[type]: { read: type, write: type } }` | returns a table mapping class' property keys to a table with their respective read and write types | +| `readparent()` | `type?` | returns the read type of class' parent class; if the parent class does not exist, returns nil | +| `writeparent()` | `type?` | returns the write type class' parent class; if the parent class does not exist, returns nil | +| `metatable()` | `type?` | returns the class' metatable; if the metatable does not exists, returns nil | +| `indexer()` | `{ index: type, readresult: type, writeresult: type }?` | returns the class' indexer as a table; if the indexer does not exist, returns nil | +| `readindexer()` | `{ index: type, result: type }?` | returns the class' indexer as a table using the read type of the result; if the indexer does not exist, returns nil | +| `writeindexer()` | `{ index: type, result: type }?` | returns the class' indexer as a table using the write type of the result; if the indexer does not exist, returns nil |