SyntaxCodetypeno test imports ittype SyntaxCode = "empty" | "bad-envelope" | "bad-delimiter" | "bad-character" | "bad-structure" | "unbalanced" | "too-long" | "unexpected-end";Why a text is not of a syntax: a code and an offset, never the text.
The plugin contract of standards (commons integrations 0008-integrations-plugins): a standard is a package that gives the library a codec (parse and serialize one syntax to the abstract tree) and loaders (read the machine-readable definitions of schemas, profiles and terminologies from data the user supplies or the issuer publishes), behind typed ports, and registers its standards with their licences. The library embeds none of any standard.
SyntaxCodetypeno test imports ittype SyntaxCode = "empty" | "bad-envelope" | "bad-delimiter" | "bad-character" | "bad-structure" | "unbalanced" | "too-long" | "unexpected-end";Why a text is not of a syntax: a code and an offset, never the text.
SyntaxProblemtypeno test imports ittype SyntaxProblem = { readonly kind: "syntax"; readonly code: SyntaxCode; readonly offset: number };A problem of the first level of validation: the offset at which the text could not be read.
Codectypeno test imports ittype Codec = {
readonly syntax: Ref<"syntax">;
readonly parse: (text: string) => Result<Interchange, SyntaxProblem>;
readonly serialize: (i: Interchange) => Result<string, SyntaxProblem>;
};The codec port of one syntax: parse a text to the tree and serialize the tree to a text.
Suppliedtypeno test imports ittype Supplied = { readonly origin: Source; readonly standard: StandardUrn; readonly text: string };What a loader is given: where the text came from, which standard it defines and the text.
LoadErrortypeno test imports ittype LoadError =
| { readonly kind: "source-not-allowed"; readonly standard: StandardUrn; readonly origin: Source }
| { readonly kind: "malformed"; readonly standard: StandardUrn; readonly code: "not-json" | "not-xml" | "wrong-resource" | "no-elements" }
| { readonly kind: "unknown-standard"; readonly standard: StandardUrn };Why a definition is not loaded.
Definitionstypeno test imports ittype Definitions = { readonly schemas: readonly Schema[]; readonly profiles: readonly Profile[]; readonly terminologies: readonly Terminology[] };What a definition gives.
Loadertypetype Loader = { readonly standard: StandardUrn; readonly load: (supplied: Supplied) => Result<Definitions, LoadError> };The loader port: a definition in, schemas, profiles and terminologies out.
AckPorttypeno test imports ittype AckPort = {
readonly acknowledge: (received: Interchange, status: "accepted" | "accepted-with-errors" | "rejected") => Result<Interchange, SyntaxProblem>;
readonly read: (i: Interchange) => Result<readonly Acknowledgement[], SyntaxProblem>;
};The port that makes and reads the acknowledgements of a standard.
StandardsPlugintypeno test imports ittype StandardsPlugin = {
readonly id: string;
readonly standards: readonly Standard[];
readonly codec: Codec;
readonly loaders: readonly Loader[];
readonly acks: AckPort | undefined;
};A plugin: the standards it registers and the ports it gives.
PluginRegistrytypetype PluginRegistry = ReadonlyMap<StandardUrn, StandardsPlugin>;Plugins by the urn of the syntax they parse.
PluginErrortypeno test imports ittype PluginError =
| { readonly kind: "syntax-taken"; readonly urn: StandardUrn; readonly by: string }
| { readonly kind: "no-such-standard"; readonly urn: StandardUrn }
| { readonly kind: "loader-for-unlisted"; readonly urn: StandardUrn };Why a plugin is not registered.
registerPluginfunctionfunction registerPlugin(reg: PluginRegistry, p: StandardsPlugin): Result<PluginRegistry, PluginError>The registry with a plugin: its codec's syntax must be one of its standards at the level syntax, and each loader's standard one of its own.
loadFromfunctionfunction loadFrom(plugin: StandardsPlugin, supplied: Supplied): Result<Definitions, LoadError>A definition taken from a source only where the licence of its standard lets that source be used.
detectfunctionfunction detect(reg: PluginRegistry, text: string): Result<{ readonly plugin: StandardsPlugin; readonly tree: Interchange; }, SyntaxProblem>The first plugin that parses a text, with its tree: the syntaxes are tried in the order of the registry.