@intellectual-frontiers/ergonex 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,162 +0,0 @@
1
- /**
2
- * RDF terms as typed values (commons 0012-ontology FR-001, FR-002): an IRI branded once checked, a namespace that pairs a prefix with
3
- * its IRI, a named node branded with the classes its term is an individual of, blank nodes, literals typed by their language or their
4
- * datatype, and triples and quads of them. A vocabulary is a typed value made from a namespace and the local names of its terms, so a
5
- * term it does not list does not compile. Generalized from erga's ontology DSL (`erga 248-ontology-in-typescript`) and stolos' RDF export.
6
- *
7
- * @example
8
- * ```ts
9
- * import { en, namespace, vocabulary } from "./rdf-term.js";
10
- * const ex = vocabulary(namespace("ex", "https://example.org/terms#"), { Widget: "rdfs:Class", size: "rdf:Property" });
11
- * ex.Widget.iri; // "https://example.org/terms#Widget"
12
- * en("a widget"); // { kind: "lang", value: "a widget", language: "en" }
13
- * ```
14
- *
15
- * @module
16
- */
17
- import { type Result } from "@intellectual-frontiers/core";
18
- import type { Brand } from "@intellectual-frontiers/core";
19
- /** An absolute IRI, checked by `parseIri` or made from a namespace. */
20
- export type Iri = Brand<string, "rdf/Iri">;
21
- /** Why a text is not an IRI: it has no scheme, or holds a character an IRI may not hold in N-Triples. */
22
- export type IriError = {
23
- readonly kind: "not-absolute";
24
- readonly text: string;
25
- } | {
26
- readonly kind: "forbidden-character";
27
- readonly text: string;
28
- readonly at: number;
29
- };
30
- /** The text as an IRI, or why it is not one. */
31
- export declare function parseIri(text: string): Result<Iri, IriError>;
32
- /** The sentence an IRI error is told with. */
33
- export declare function formatIriError(e: IriError): string;
34
- /** A fault of the code: a constant namespace or term whose IRI does not parse. It is thrown where the constant is made. */
35
- export declare class RdfFault extends Error {
36
- /** The fault, told as a sentence. */
37
- constructor(message: string);
38
- }
39
- /** The classes a named node is an individual of, as the compiler sees them: one key for each class's name. */
40
- export type Classes<C extends string> = {
41
- readonly [K in C]: true;
42
- };
43
- /**
44
- * A named node: an IRI, branded with the classes its term is an individual of (by their CURIEs, `"pm:PackageManager"`). A
45
- * `Named<"a" | "b">` is an individual of both, so it is accepted where either is asked for; a `Named<"a">` is not accepted where `"b"` is,
46
- * and a `Named` of no known class (`Named`, which is `Named<never>`) is not accepted where any one class is asked for: every named node is
47
- * a `Named`, so it is the type of a predicate or of any node at all.
48
- */
49
- export type Named<C extends string = never> = {
50
- readonly kind: "named";
51
- readonly iri: Iri;
52
- readonly "@ifc/rdf-classes": Classes<C>;
53
- };
54
- /** A named node of any one of the classes `C` (`NamedOf<"a" | "b">` is a `Named<"a">` or a `Named<"b">`). */
55
- export type NamedOf<C extends string> = C extends string ? Named<C> : never;
56
- /** The named node of an IRI, as an individual of the classes `C`; the brand is for the compiler alone. */
57
- export declare function named<C extends string = never>(iri: Iri): Named<C>;
58
- /** A namespace: a prefix and the IRI its terms' local names are appended to. */
59
- export type Namespace<P extends string = string> = {
60
- readonly prefix: P;
61
- readonly iri: Iri;
62
- };
63
- /** A namespace; one whose prefix or IRI is not well formed is a fault of the code, thrown as an `RdfFault`. */
64
- export declare function namespace<const P extends string>(prefix: P, iri: string): Namespace<P>;
65
- /** The IRI of a local name in a namespace; one that does not parse is a fault of the code, thrown as an `RdfFault`. */
66
- export declare function iriIn(ns: Namespace, local: string): Iri;
67
- /**
68
- * The named node of a local name in a namespace, as an individual of the classes `C`, which the compiler takes from where it is used.
69
- * It is how a term no module here states is named (an individual of another ontology); a term this code states comes from its schema.
70
- */
71
- export declare function term<C extends string = never>(ns: Namespace, local: string): Named<C>;
72
- /** The IRI of the ontology a namespace's terms belong to: the namespace's IRI without its last `#` or `/`. */
73
- export declare function ontologyIri(ns: Namespace): Iri;
74
- /** A term of a vocabulary: a named node of its class, with its CURIE. */
75
- export type VocabularyTerm<C extends string, Curie extends string> = Named<C> & {
76
- readonly curie: Curie;
77
- };
78
- /** A typed vocabulary: each local name of `T` gives a term of the class `T` names for it. */
79
- export type Vocabulary<P extends string, T extends Readonly<Record<string, string>>> = {
80
- readonly [K in keyof T & string]: VocabularyTerm<T[K], `${P}:${K}`>;
81
- };
82
- /** The vocabulary of a namespace: its terms by local name, each of the class given (`{ label: "rdf:Property" }`). */
83
- export declare function vocabulary<const P extends string, const T extends Readonly<Record<string, string>>>(ns: Namespace<P>, terms: T): Vocabulary<P, T>;
84
- /** A language tag, checked against BCP 47's shape (letters, then subtags of letters and digits, joined by `-`). */
85
- export type LanguageTag = Brand<string, "rdf/LanguageTag">;
86
- /** The text as a language tag, in lower case, or nothing where it is not one. */
87
- export declare function languageTag(text: string): LanguageTag | undefined;
88
- /** A string in a language: `"install"@en`. */
89
- export type LangString = {
90
- readonly kind: "lang";
91
- readonly value: string;
92
- readonly language: LanguageTag;
93
- };
94
- /** A literal with its datatype (a plain string is an `xsd:string`). */
95
- export type TypedLiteral = {
96
- readonly kind: "typed";
97
- readonly value: string;
98
- readonly datatype: Iri;
99
- };
100
- /** A literal: a string in a language, or a lexical form with its datatype. */
101
- export type Literal = LangString | TypedLiteral;
102
- /** A blank node, by its label. */
103
- export type Blank = {
104
- readonly kind: "blank";
105
- readonly label: string;
106
- };
107
- /** A node of the default graph's name. */
108
- export type DefaultGraph = {
109
- readonly kind: "default";
110
- };
111
- /** Any RDF term. */
112
- export type Term = Named | Blank | Literal;
113
- /** What a triple may be about. */
114
- export type Subject = Named | Blank;
115
- /** A triple. */
116
- export type Triple = {
117
- readonly subject: Subject;
118
- readonly predicate: Named;
119
- readonly object: Term;
120
- };
121
- /** A triple in a named graph, or in the default graph. */
122
- export type Quad = Triple & {
123
- readonly graph: Named | DefaultGraph;
124
- };
125
- /** Why a literal or a blank node could not be made. */
126
- export type TermError = {
127
- readonly kind: "language";
128
- readonly tag: string;
129
- } | {
130
- readonly kind: "blank-label";
131
- readonly label: string;
132
- };
133
- /** The sentence a term error is told with. */
134
- export declare function formatTermError(e: TermError): string;
135
- /** A string in the language of a tag, or why the tag is not one. */
136
- export declare function lang(value: string, tag: string): Result<LangString, TermError>;
137
- /** A string in English: `en("install")`. */
138
- export declare function en(value: string): LangString;
139
- /** The IRI of `xsd:string`. */
140
- export declare const XSD_STRING: Iri;
141
- /** The IRI of `xsd:integer`. */
142
- export declare const XSD_INTEGER: Iri;
143
- /** The IRI of `xsd:boolean`. */
144
- export declare const XSD_BOOLEAN: Iri;
145
- /** The IRI of `rdf:type`. */
146
- export declare const RDF_TYPE: Iri;
147
- /** A literal of a datatype: `typed("2026-11-16", xsd.date)`. */
148
- export declare function typed(value: string, datatype: Named): TypedLiteral;
149
- /** A plain string, an `xsd:string`. */
150
- export declare function plain(value: string): TypedLiteral;
151
- /** A blank node, or why its label is not one. */
152
- export declare function blank(label: string): Result<Blank, TermError>;
153
- /** The default graph. */
154
- export declare const defaultGraph: DefaultGraph;
155
- /** One value of a field: a plain string, an integer, a boolean, a literal or a named node. */
156
- export type Value = string | number | boolean | Literal | Named;
157
- /** The term of a value: a string is an `xsd:string`, a number an `xsd:integer` (in its canonical form), a boolean an `xsd:boolean`. */
158
- export declare function termOf(v: Value): Term;
159
- /** A string's characters escaped as N-Triples and Turtle write them, in quotes: `\b \t \n \f \r \" \\` and `\uXXXX` for the other controls. */
160
- export declare function quoted(s: string): string;
161
- /** A term as N-Triples writes it: `<iri>`, `_:label`, or a quoted literal with its language or its datatype (none for `xsd:string`). */
162
- export declare function nTriplesTerm(t: Term): string;
@@ -1,148 +0,0 @@
1
- /** The namespace of RDF itself. */
2
- export declare const RDF: import("./rdf-term.js").Namespace<"rdf">;
3
- /** The terms of `rdf:` that commons states. */
4
- export declare const rdf: import("./rdf-term.js").Vocabulary<"rdf", {
5
- readonly type: "rdf:Property";
6
- readonly first: "rdf:Property";
7
- readonly rest: "rdf:Property";
8
- readonly value: "rdf:Property";
9
- readonly Property: "rdfs:Class";
10
- readonly List: "rdfs:Class";
11
- readonly nil: "rdf:List";
12
- readonly langString: "rdfs:Datatype";
13
- }>;
14
- /** The namespace of RDF Schema. */
15
- export declare const RDFS: import("./rdf-term.js").Namespace<"rdfs">;
16
- /** The terms of `rdfs:` that commons states. */
17
- export declare const rdfs: import("./rdf-term.js").Vocabulary<"rdfs", {
18
- readonly Resource: "rdfs:Class";
19
- readonly Class: "rdfs:Class";
20
- readonly Datatype: "rdfs:Class";
21
- readonly Literal: "rdfs:Class";
22
- readonly label: "rdf:Property";
23
- readonly comment: "rdf:Property";
24
- readonly domain: "rdf:Property";
25
- readonly range: "rdf:Property";
26
- readonly subClassOf: "rdf:Property";
27
- readonly subPropertyOf: "rdf:Property";
28
- readonly seeAlso: "rdf:Property";
29
- readonly isDefinedBy: "rdf:Property";
30
- }>;
31
- /** The namespace of OWL 2. */
32
- export declare const OWL: import("./rdf-term.js").Namespace<"owl">;
33
- /** The terms of `owl:` that commons states. */
34
- export declare const owl: import("./rdf-term.js").Vocabulary<"owl", {
35
- readonly Ontology: "rdfs:Class";
36
- readonly Class: "rdfs:Class";
37
- readonly ObjectProperty: "rdfs:Class";
38
- readonly DatatypeProperty: "rdfs:Class";
39
- readonly AnnotationProperty: "rdfs:Class";
40
- readonly NamedIndividual: "rdfs:Class";
41
- readonly Thing: "rdfs:Class";
42
- readonly versionInfo: "rdf:Property";
43
- readonly versionIRI: "rdf:Property";
44
- readonly imports: "rdf:Property";
45
- readonly sameAs: "rdf:Property";
46
- readonly equivalentClass: "rdf:Property";
47
- }>;
48
- /** The namespace of the XML Schema datatypes. */
49
- export declare const XSD: import("./rdf-term.js").Namespace<"xsd">;
50
- /** The datatypes of `xsd:` that commons states. */
51
- export declare const xsd: import("./rdf-term.js").Vocabulary<"xsd", {
52
- readonly string: "rdfs:Datatype";
53
- readonly boolean: "rdfs:Datatype";
54
- readonly integer: "rdfs:Datatype";
55
- readonly nonNegativeInteger: "rdfs:Datatype";
56
- readonly positiveInteger: "rdfs:Datatype";
57
- readonly decimal: "rdfs:Datatype";
58
- readonly double: "rdfs:Datatype";
59
- readonly date: "rdfs:Datatype";
60
- readonly dateTime: "rdfs:Datatype";
61
- readonly duration: "rdfs:Datatype";
62
- readonly anyURI: "rdfs:Datatype";
63
- readonly language: "rdfs:Datatype";
64
- }>;
65
- /** The namespace of SKOS. */
66
- export declare const SKOS: import("./rdf-term.js").Namespace<"skos">;
67
- /** The terms of `skos:` that commons states. */
68
- export declare const skos: import("./rdf-term.js").Vocabulary<"skos", {
69
- readonly Concept: "rdfs:Class";
70
- readonly ConceptScheme: "rdfs:Class";
71
- readonly Collection: "rdfs:Class";
72
- readonly inScheme: "rdf:Property";
73
- readonly hasTopConcept: "rdf:Property";
74
- readonly topConceptOf: "rdf:Property";
75
- readonly prefLabel: "rdf:Property";
76
- readonly altLabel: "rdf:Property";
77
- readonly definition: "rdf:Property";
78
- readonly notation: "rdf:Property";
79
- readonly broader: "rdf:Property";
80
- readonly narrower: "rdf:Property";
81
- readonly related: "rdf:Property";
82
- readonly note: "rdf:Property";
83
- readonly scopeNote: "rdf:Property";
84
- readonly example: "rdf:Property";
85
- }>;
86
- /** The namespace of the Dublin Core terms. */
87
- export declare const DCTERMS: import("./rdf-term.js").Namespace<"dcterms">;
88
- /** The terms of `dcterms:` that commons states. */
89
- export declare const dcterms: import("./rdf-term.js").Vocabulary<"dcterms", {
90
- readonly identifier: "rdf:Property";
91
- readonly title: "rdf:Property";
92
- readonly description: "rdf:Property";
93
- readonly source: "rdf:Property";
94
- readonly license: "rdf:Property";
95
- readonly created: "rdf:Property";
96
- readonly modified: "rdf:Property";
97
- readonly date: "rdf:Property";
98
- readonly creator: "rdf:Property";
99
- readonly publisher: "rdf:Property";
100
- readonly isPartOf: "rdf:Property";
101
- readonly hasPart: "rdf:Property";
102
- readonly references: "rdf:Property";
103
- readonly conformsTo: "rdf:Property";
104
- readonly Standard: "rdfs:Class";
105
- }>;
106
- /** The namespace of PROV-O. */
107
- export declare const PROV: import("./rdf-term.js").Namespace<"prov">;
108
- /** The terms of `prov:` that commons states: PROV-O's starting point, and where an activity ran. */
109
- export declare const prov: import("./rdf-term.js").Vocabulary<"prov", {
110
- readonly Entity: "rdfs:Class";
111
- readonly Activity: "rdfs:Class";
112
- readonly Agent: "rdfs:Class";
113
- readonly Person: "rdfs:Class";
114
- readonly Organization: "rdfs:Class";
115
- readonly SoftwareAgent: "rdfs:Class";
116
- readonly wasGeneratedBy: "rdf:Property";
117
- readonly wasDerivedFrom: "rdf:Property";
118
- readonly wasAttributedTo: "rdf:Property";
119
- readonly wasAssociatedWith: "rdf:Property";
120
- readonly wasInformedBy: "rdf:Property";
121
- readonly actedOnBehalfOf: "rdf:Property";
122
- readonly used: "rdf:Property";
123
- readonly startedAtTime: "rdf:Property";
124
- readonly endedAtTime: "rdf:Property";
125
- readonly generatedAtTime: "rdf:Property";
126
- readonly atLocation: "rdf:Property";
127
- readonly value: "rdf:Property";
128
- }>;
129
- /** The namespace of SHACL. */
130
- export declare const SH: import("./rdf-term.js").Namespace<"sh">;
131
- /** The terms of `sh:` that commons states. */
132
- export declare const sh: import("./rdf-term.js").Vocabulary<"sh", {
133
- readonly NodeShape: "rdfs:Class";
134
- readonly PropertyShape: "rdfs:Class";
135
- readonly targetClass: "rdf:Property";
136
- readonly property: "rdf:Property";
137
- readonly path: "rdf:Property";
138
- readonly datatype: "rdf:Property";
139
- readonly class: "rdf:Property";
140
- readonly node: "rdf:Property";
141
- readonly minCount: "rdf:Property";
142
- readonly maxCount: "rdf:Property";
143
- readonly pattern: "rdf:Property";
144
- readonly in: "rdf:Property";
145
- readonly order: "rdf:Property";
146
- readonly name: "rdf:Property";
147
- readonly description: "rdf:Property";
148
- }>;
@@ -1,25 +0,0 @@
1
- import { type Namespace, type Quad, type Triple } from "./rdf-term.js";
2
- /** Two strings in the order of their code points (JavaScript's `<` orders UTF-16 units, which differs above U+FFFF). */
3
- export declare function compareCodePoints(a: string, b: string): number;
4
- /** Triples as N-Triples: each once, one a line, the lines in the order of their code points. */
5
- export declare function nTriples(triples: readonly Triple[]): string;
6
- /** Quads as N-Quads: each once, one a line (a triple of the default graph has no fourth term), in the order of their code points. */
7
- export declare function nQuads(quads: readonly Quad[]): string;
8
- /** What a Turtle document is made of: comment lines for its head, the prefixes it may use, and its triples. */
9
- export type TurtleDocument = {
10
- readonly comments?: readonly string[];
11
- readonly prefixes: readonly Namespace[];
12
- readonly triples: readonly Triple[];
13
- };
14
- /**
15
- * Triples as Turtle in its canonical form: the comment lines, then the prefixes sorted by name, then the subjects in the order of their
16
- * N-Triples terms, each with its `rdf:type` first as `a` and its other predicates by IRI, each predicate's objects in the order of their
17
- * N-Triples terms, one blank line between subjects. An IRI is a prefixed name where a prefix's IRI starts it and the rest is a plain local
18
- * name (the longest such prefix), and a whole IRI otherwise; an integer or a boolean of canonical form is written bare.
19
- */
20
- export declare function turtle(doc: TurtleDocument): string;
21
- /**
22
- * Triples as JSON-LD in its expanded form: one node object for each subject, in the order of their N-Triples terms, with its `@id`, its
23
- * `@type` (the IRIs of its `rdf:type`s, sorted) and then each other predicate by IRI, its values in the order of their N-Triples terms.
24
- */
25
- export declare function jsonLd(triples: readonly Triple[]): string;
@@ -1,35 +0,0 @@
1
- /**
2
- * RDF as algebraically typed values, and the writers of its syntaxes (commons 0012-ontology): IRIs branded once checked, namespaces and
3
- * typed vocabularies (RDF, RDFS, OWL, XSD, SKOS, Dublin Core terms, PROV-O, SHACL), named nodes branded with their classes, literals typed
4
- * by language or datatype, class schemas whose individuals' types are derived from them, code lists and SKOS concept schemes, the checks a
5
- * type cannot state, and N-Triples, N-Quads, canonical Turtle and expanded JSON-LD. A harness states its ontology as TypeScript with these,
6
- * and every RDF form of it is written, never read.
7
- *
8
- * @remarks
9
- * Generalized from erga's ontology DSL (`erga 248-ontology-in-typescript`), whose references are branded by class and whose Turtle is
10
- * written in one canonical form, and from stolos' PROV export, which wrote Turtle by hand. None of their vocabularies is here: a harness
11
- * keeps its own, made with `vocabulary`.
12
- *
13
- * @limits
14
- * It reads no RDF syntax, holds no blank-node values or RDF lists in a schema's fields, makes no SHACL shapes and compares no graphs with
15
- * blank nodes.
16
- *
17
- * @example
18
- * ```ts
19
- * import { classSchema, en, namespace, one, OwlClass, range, rdfs, term, triplesOf, turtle, vocabulary } from "./rdf.js";
20
- * const EX = namespace("ex", "https://example.org/terms#");
21
- * const ex = vocabulary(EX, { Tool: "owl:Class", runs: "owl:DatatypeProperty" });
22
- * const Tool = classSchema(ex.Tool, { label: one(rdfs.label, range.langString), runs: one(ex.runs, range.string) });
23
- * const git = Tool.make(term(EX, "git"), { label: en("git"), runs: "git" });
24
- * turtle({ prefixes: [EX], triples: triplesOf([OwlClass.make(ex.Tool, { label: en("Tool") }), git]) });
25
- * ```
26
- *
27
- * @module
28
- */
29
- export { blank, defaultGraph, en, formatIriError, formatTermError, iriIn, lang, languageTag, named, namespace, nTriplesTerm, ontologyIri, parseIri, plain, quoted, RDF_TYPE, RdfFault, term, termOf, typed, vocabulary, XSD_BOOLEAN, XSD_INTEGER, XSD_STRING, } from "./rdf-term.js";
30
- export type { Blank, Classes, DefaultGraph, Iri, IriError, LangString, LanguageTag, Literal, Named, NamedOf, Namespace, Quad, Subject, Term, TermError, Triple, TypedLiteral, Value, Vocabulary, VocabularyTerm, } from "./rdf-term.js";
31
- export { DCTERMS, dcterms, OWL, owl, PROV, prov, RDF, rdf, RDFS, rdfs, SH, sh, SKOS, skos, XSD, xsd } from "./rdf-vocabularies.js";
32
- export { classSchema, codeOf, codes, ConceptSchema, conceptScheme, ConceptSchemeSchema, DatatypeProperty, formatRdfFinding, many, ObjectProperty, one, ontologyOf, optional, OwlClass, OwlOntology, range, triplesOf, validate, } from "./rdf-schema.js";
33
- export type { AnyIndividual, Cardinality, ClassSchema, CodeList, ConceptEntry, ConceptScheme, Field, Fields, Individual, OntologyFile, Range, RangeKind, RdfFinding, Statement, ValuesOf, } from "./rdf-schema.js";
34
- export { compareCodePoints, jsonLd, nQuads, nTriples, turtle } from "./rdf-write.js";
35
- export type { TurtleDocument } from "./rdf-write.js";
@@ -1,78 +0,0 @@
1
- /** A colour of text or background: the terminal's default, one of 256 indexed colours (0 to 15 the basic and bright ones), or 24-bit. */
2
- export type Colour = {
3
- readonly kind: "default";
4
- } | {
5
- readonly kind: "indexed";
6
- readonly index: number;
7
- } | {
8
- readonly kind: "rgb";
9
- readonly r: number;
10
- readonly g: number;
11
- readonly b: number;
12
- };
13
- /** How a cell's text is drawn, as SGR left it. */
14
- export type Style = {
15
- readonly bold: boolean;
16
- readonly dim: boolean;
17
- readonly italic: boolean;
18
- readonly underline: boolean;
19
- readonly blink: boolean;
20
- readonly inverse: boolean;
21
- readonly hidden: boolean;
22
- readonly strike: boolean;
23
- readonly fg: Colour;
24
- readonly bg: Colour;
25
- };
26
- /** The style of a cell nothing styled: every attribute off, default colours. */
27
- export declare const PLAIN: Style;
28
- /** A style in words, for a snapshot: the attributes on, then `fg=` and `bg=` where not the default; "" for `PLAIN`. */
29
- export declare function describeStyle(style: Style): string;
30
- /** Whether two styles draw the same. */
31
- export declare function sameStyle(a: Style, b: Style): boolean;
32
- /** One cell of the screen: a grapheme and its style; a wide grapheme's second cell is a continuation, of width 0 and empty text. */
33
- export type Cell = {
34
- readonly text: string;
35
- readonly width: 0 | 1 | 2;
36
- readonly style: Style;
37
- };
38
- /** A run of cells of one style on a line, their text joined. */
39
- export type Run = {
40
- readonly text: string;
41
- readonly style: Style;
42
- };
43
- /** Where the cursor is (row and column from 0) and whether it is shown. */
44
- export type Cursor = {
45
- readonly row: number;
46
- readonly col: number;
47
- readonly visible: boolean;
48
- };
49
- /** The size of a screen and how it reads a line feed. */
50
- export type ScreenOptions = {
51
- /** Columns; at least 1. */
52
- readonly width: number;
53
- /** Rows: the screen scrolls when a line feed is written on the last; without it, the screen grows. */
54
- readonly height?: number;
55
- /** "crlf" (the default): a line feed also returns the carriage, as a terminal's line discipline does; "lf": it only moves down. */
56
- readonly newline?: "crlf" | "lf";
57
- };
58
- /** A screen being written to. */
59
- export type Screen = {
60
- /** Its width in columns. */
61
- readonly width: number;
62
- /** Its height in rows, or undefined where it grows. */
63
- readonly height: number | undefined;
64
- /** Feeds it what a program writes: text, or bytes decoded as UTF-8 (a character may be split across writes). */
65
- write(data: string | Uint8Array): void;
66
- /** Its lines as text: trailing spaces of each line and trailing empty lines left out. */
67
- lines(): readonly string[];
68
- /** Its lines joined by "\n". */
69
- text(): string;
70
- /** Its lines as runs of one style, trailing unstyled spaces and trailing empty lines left out. */
71
- styled(): readonly (readonly Run[])[];
72
- /** The cell at a row and column; undefined outside the screen. */
73
- cell(row: number, col: number): Cell | undefined;
74
- /** The cursor. */
75
- cursor(): Cursor;
76
- };
77
- /** A new, empty screen with the cursor at the top left, shown. */
78
- export declare function createScreen(options: ScreenOptions): Screen;
@@ -1,63 +0,0 @@
1
- /**
2
- * Display width: how many columns of a terminal a text takes, and a text cut to a number of columns (commons 0006-signals FR-023). An
3
- * escape sequence takes none and is never split; a grapheme (what a person sees as one character, found with `Intl.Segmenter`) is never
4
- * split either; a wide character or an emoji takes two columns.
5
- *
6
- * The width of a grapheme is an approximation of what terminals do (as `wcwidth` and the `string-width` package approximate it):
7
- * - a control character, a combining mark, a format character (such as the zero-width joiner) or a variation selector alone: 0;
8
- * - an emoji: 2 when it is shown as an emoji, which is when its first code point has the `Emoji_Presentation` property (✅ ❌ 👉), when
9
- * it carries the emoji variation selector U+FE0F (⏭️ ⏹️ ⚠️, keycaps such as 1️⃣), or when it is a zero-width-joiner sequence (one glyph
10
- * of two columns, however many code points it joins); the text variation selector U+FE0E makes it 1;
11
- * - an East Asian Wide or Fullwidth character (CJK ideographs, kana, Hangul syllables, fullwidth forms): 2, by the ranges in `WIDE`,
12
- * which follow Unicode's `EastAsianWidth.txt` in blocks rather than code point by code point (JavaScript has no property escape for it);
13
- * - anything else: 1. Ambiguous-width characters (Greek, box drawing) count 1, as a terminal in a Western locale shows them.
14
- *
15
- * @example
16
- * ```ts
17
- * import { cutToWidth, displayWidth } from "./width.js";
18
- * displayWidth("✅ 测试"); // 7
19
- * cutToWidth("✅ 测试", 6); // "✅ 测"
20
- * cutToWidth("\u001b[31mfailed badly\u001b[0m", 7, "…"); // "\u001b[31mfailed…\u001b[0m"
21
- * ```
22
- *
23
- * @module
24
- */
25
- /** A piece of a text: an escape sequence, or a run of text between them. */
26
- export type Token = {
27
- readonly kind: "escape";
28
- readonly text: string;
29
- } | {
30
- readonly kind: "text";
31
- readonly text: string;
32
- };
33
- /** A text split into its escape sequences and the runs of text between them, in order; joined, the pieces are the text again. */
34
- export declare function tokens(text: string): readonly Token[];
35
- /** The graphemes of a text with no escape sequence, in order (extended grapheme clusters, by `Intl.Segmenter`). */
36
- export declare function graphemes(text: string): readonly string[];
37
- /** The columns one grapheme takes: 0, 1 or 2 (see the module's rules). */
38
- export declare function graphemeWidth(grapheme: string): 0 | 1 | 2;
39
- /** The columns a text takes on a terminal: its graphemes' widths summed; escape sequences take none. */
40
- export declare function displayWidth(text: string): number;
41
- /** A text split in two at a number of columns. */
42
- export type Split = {
43
- /** The longest beginning that takes at most the columns asked for, with every escape sequence before the cut. */
44
- readonly head: string;
45
- /** The rest: `head + tail` is the text. */
46
- readonly tail: string;
47
- };
48
- /**
49
- * A text split where it reaches `width` columns, between two graphemes or escape sequences, never inside one: a wide character that would
50
- * cross the edge goes to the tail. Escape sequences up to the first grapheme that does not fit stay in the head.
51
- */
52
- export declare function splitAtWidth(text: string, width: number): Split;
53
- /** The parameters of an SGR sequence (`ESC [ ... m`), or undefined for another sequence. */
54
- export declare function sgrParams(escape: string): readonly number[] | undefined;
55
- /** The SGR sequence that turns every style off. */
56
- export declare const RESET: string;
57
- /**
58
- * A text cut to at most `width` columns. A text that fits is returned as it is. Otherwise it is cut between graphemes so that it and the
59
- * `ellipsis` (none by default; "…" is the usual one) fit; the escape sequences before the cut are kept, those after are dropped, and where a
60
- * colour or another style was still on at the cut, the result ends with a reset so that the style does not run on. An ellipsis wider than
61
- * `width` is left out.
62
- */
63
- export declare function cutToWidth(text: string, width: number, ellipsis?: string): string;