tangent128
/
prototype-3x5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Port to TS

This commit is contained in:
Tangent Wantwight 2023-08-05 01:09:33 -04:00
parent 8b4584eb48
commit 8fc2892630
5 changed files with 191 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
index.html
View File

@ -5,9 +5,6 @@
<meta charset="UTF-8" /> <meta charset="UTF-8" />
</head> </head>
<body> <body>
<script src="helpers.js"></script> <script src="bundle.js"></script>
<script src="peg.js"></script>
<script src="notcl.js"></script>
<script src="3x5.js"></script>
</body> </body>
</html> </html>

37
src/3x5.ts
View File

@ -1,22 +1,35 @@
/** import { parse } from "./notcl";
* @typedef {object} Card Basic unit of information, also an "actor" in the programming system
* @property {number} id Unique identifier
* @property {Record<string, string>} fields Key-value properties on the card
* @property {string} code Eventually: a markdown string containing code, but for now, just code
*/
/** /**
* @typedef {"action" | "render"} ScriptType "Mode" of the environment a script runs in; determines access to mutability features and such. * Basic unit of information, also an "actor" in the programming system
*/
type Card = {
/** Unique identifier */
id: number;
/** Key-value properties on the card */
fields: Record<string, string>;
/** Eventually: a markdown string containing code, but for now, just code */
code: string;
};
/**
* "Mode" of the environment a script runs in; determines access to mutability features and such.
* *
* "action": response to a UI action; allowed to modify card fields and access time and random numbers. * "action": response to a UI action; allowed to modify card fields and access time and random numbers.
* *
* "render": deterministic generation of display markup from card and workspace state; can only modify temporary variables. * "render": deterministic generation of display markup from card and workspace state; can only modify temporary variables.
*/ */
type ScriptType = "action" | "render";
/** /**
* @typedef {object} Vm State for running a script in. * State for running a script in.
* @property {ScriptType} mode Mutability status
* @property {string} output Markup to render / output
*/ */
type Vm = {
/** Mutability status */
mode: ScriptType;
/** Markup to render / output */
output: string;
};
/** /**
* @param {Vm} state VM state * @param {Vm} state VM state
@ -24,7 +37,7 @@
* @returns {string} Markup to render / output * @returns {string} Markup to render / output
*/ */
function renderCard(state, code) { function renderCard(state, code) {
const script = Notcl.parse(code); const script = parse(code);
if (script[0]) { if (script[0]) {
state.output = JSON.stringify(script[1], null, 2); state.output = JSON.stringify(script[1], null, 2);
} else { } else {
@ -88,7 +101,7 @@ const debugDisplay = document.createElement("pre");
function render() { function render() {
const vm = { const vm = {
mode: /** @type {ScriptType} */ ("render"), mode: /** @type {ScriptType} */ "render",
output: "", output: "",
}; };
const html = renderCard(vm, theCard.code); const html = renderCard(vm, theCard.code);

6
src/helpers.ts
View File

@ -1,9 +1,9 @@
const escapeDiv = document.createElement("div"); const escapeDiv = document.createElement("div");
/** /**
* @param {string} text Potentially dangerous text * @param text Potentially dangerous text
* @returns {string} Text safe to embed in HTML * @returns Text safe to embed in HTML
**/ **/
function escapeHtml(text) { export function escapeHtml(text: string): string {
escapeDiv.textContent = text; escapeDiv.textContent = text;
return escapeDiv.innerHTML; return escapeDiv.innerHTML;
} }

205
src/notcl.ts
View File

@ -1,115 +1,106 @@
import { escapeHtml } from "./helpers";
import { AtLeast, Choose, End, Regex, Sequence, Use } from "./peg";
export type Word = {
text: string;
};
export type Command = Word[];
export type Script = Command[];
const InterCommandWhitespace = Regex(/\s+/y).expects("whitespace");
const Comment = Regex(/#[^\n]*/y)
.expects("#")
.map(() => []);
const PreCommand = AtLeast(0, InterCommandWhitespace);
const PreWordWhitespace = Regex(/[^\S\n;]+/y).expects("whitespace");
const BasicWord = Regex(/(?!\{)[^\s;]+/y)
.map(([word]) => ({ text: word }))
.expects("BASIC_WORD");
// WIP, need to be able to escape braces correctly
const Brace = Sequence(
Regex(/\{/y).expects("{"),
AtLeast(
0,
Choose(
Use(() => Brace)
.expects("{")
.map((text) => `{${text}}`),
Regex(/[^{}]+/y)
.expects("text")
.map(([text]) => text)
)
),
Regex(/\}/y).expects("}")
).map(([_left, fragments, _right]) => fragments.join(""));
const Word = Choose(
BasicWord,
Brace.map((text) => ({ text }))
);
const CommandTerminator = Regex(/[\n;]/y)
.expects("NEWLINE | ;")
.map(() => true);
const Command = Sequence(
Word,
AtLeast(
0,
Sequence(PreWordWhitespace, Word).map(([, word]) => word)
),
AtLeast(0, PreWordWhitespace)
).map(([word, moreWords]) => [word].concat(moreWords));
const Script = Sequence(
AtLeast(
0,
Choose(
PreWordWhitespace.map(() => []),
CommandTerminator.map(() => []),
Sequence(Comment, Choose(CommandTerminator, End())).map(() => []),
Sequence(Command, Choose(CommandTerminator, End())).map(
([words]) => words
)
)
),
End()
).map(([commands]) => commands.filter((command) => command.length > 0));
const ERROR_CONTEXT = /(?<=([^\n]{0,50}))([^\n]{0,50})/y;
/** /**
* @typedef {Notcl.Command[]} Notcl.Script * Parse out a Notcl script into an easier-to-interpret representation.
* @typedef {Notcl.Word[]} Notcl.Command * No script is actually executed yet.
* @typedef {object} Notcl.Word *
* @property {string} text * @param - code to parse
* @returns - parsed list of commands, or error message on failure
*/ */
export function parse(code: string): [true, Script] | [false, string] {
/* Preprocess */
// fold line endings
code = code.replace(/(?<!\\)((\\\\)*)\\\n/g, "$1");
var Notcl = (() => { /* Parse */
const { AtLeast, Choose, End, Regex, Sequence, Use } = Peg; const [commands, errorPos, expected] = Script(code, 0);
const InterCommandWhitespace = Regex(/\s+/y).expects("whitespace"); if (commands) {
return [true, commands[0]];
const Comment = Regex(/#[^\n]*/y) } else {
.expects("#") ERROR_CONTEXT.lastIndex = errorPos;
.map(() => []); const [, before, after] = ERROR_CONTEXT.exec(code)!;
return [
const PreCommand = AtLeast(0, InterCommandWhitespace); false,
`<pre>Error at position ${errorPos}
const PreWordWhitespace = Regex(/[^\S\n;]+/y).expects("whitespace");
const BasicWord = Regex(/(?!\{)[^\s;]+/y)
.map(([word]) => ({ text: word }))
.expects("BASIC_WORD");
// WIP, need to be able to escape braces correctly
/** @type {Peg.Pattern<string>} */
const Brace = Sequence(
Regex(/\{/y).expects("{"),
AtLeast(
0,
Choose(
Use(() => Brace)
.expects("{")
.map((text) => `{${text}}`),
Regex(/[^{}]+/y)
.expects("text")
.map(([text]) => text)
)
),
Regex(/\}/y).expects("}")
).map(([_left, fragments, _right]) => fragments.join(""));
const Word = Choose(
BasicWord,
Brace.map((text) => ({ text }))
);
const CommandTerminator = Regex(/[\n;]/y)
.expects("NEWLINE | ;")
.map(() => true);
/** @type {Peg.Pattern<Notcl.Command>} */
const Command = Sequence(
Word,
AtLeast(
0,
Sequence(PreWordWhitespace, Word).map(([, word]) => word)
),
AtLeast(0, PreWordWhitespace)
).map(([word, moreWords]) => [word].concat(moreWords));
/** @type {Peg.Pattern<Notcl.Script>} */
const Script = Sequence(
AtLeast(
0,
Choose(
PreWordWhitespace.map(() => []),
CommandTerminator.map(() => []),
Sequence(Comment, Choose(CommandTerminator, End())).map(() => []),
Sequence(Command, Choose(CommandTerminator, End())).map(
([words]) => words
)
)
),
End()
).map(([commands]) => commands.filter((command) => command.length > 0));
const ERROR_CONTEXT = /(?<=([^\n]{0,50}))([^\n]{0,50})/y;
return {
/**
* Parse out a Notcl script into an easier-to-interpret representation.
* No script is actually executed yet.
*
* @param {string} code to parse
* @returns {[true, Notcl.Script] | [false, string]} parsed list of commands, or error message on failure
*/
parse(code) {
/* Preprocess */
// fold line endings
code = code.replace(/(?<!\\)((\\\\)*)\\\n/g, "$1");
/* Parse */
const [commands, errorPos, expected] = Script(code, 0);
if (commands) {
return [true, commands[0]];
} else {
ERROR_CONTEXT.lastIndex = errorPos;
const [, before, after] = /** @type {RegExpExecArray} */ (
ERROR_CONTEXT.exec(code)
);
return [
false,
`<pre>Error at position ${errorPos}
${escapeHtml(before + "" + after)} ${escapeHtml(before + "" + after)}
${"-".repeat(before.length)}^ ${"-".repeat(before.length)}^
Expected: ${escapeHtml(expected)}</pre>`, Expected: ${escapeHtml(expected)}</pre>`,
]; ];
} }
}, }
};
})();

135
src/peg.ts
View File

@ -1,44 +1,48 @@
/** /**
* A Pattern is a function that matches against a string starting at a given index. * A Pattern is a function that matches against a string starting at a given index.
* *
* If it matches successfully, it returns some captured value, and the index following the match.
*
* On success or failure, it returns the furthest point the pattern could make sense of, and a description of what was expected next at that point.
*
* For simple patterns, the "furthest point" may just be the following index; however, some more complex patterns might succeed,
* but consume less input than they would have been able to if some other expected symbol was found. Reporting
* the furthest a pattern could hypothetically have gotten can help generate better error messages if no valid parse tree is found.
*
* @template T
* @callback Peg.PatternCall
* @param {string} source - the string being parsed
* @param {number} index - the index in the string to begin matching from
* @returns {[[T, number] | null, number, string]} - [successValue, furthest symbol attempted, expected pattern]
*/ */
/** export type Pattern<T> = PatternFunc<T> & {
* @template T /**
* @typedef {object} Peg.PatternExt * Creates a pattern that wraps another pattern, transforming the returned value on a match.
* @property {<U>(map: (value: T) => U) => Peg.Pattern<U>} map Creates a pattern that wraps another pattern, transforming the returned value on a match *
* @property {string} expectLabel A human-readable annotation describing the pattern for error messages * @param map - Mapping function
* @property {(label: string) => Peg.Pattern<T>} expects Adds a human-readable annotation describing the pattern */
*/ map<U>(map: (value: T) => U): Pattern<U>;
/**
* @template T /** A human-readable annotation describing the pattern for error messages */
* @typedef {Peg.PatternCall<T> & Peg.PatternExt<T>} Peg.Pattern expectLabel: string;
*/
var Peg = window.Peg ?? {}; /** Adds a human-readable annotation describing the pattern */
expects(label: string): Pattern<T>;
};
type PatternFunc<T> = {
/**
* If the pattern matches successfully, it returns some captured value, and the index following the match.
*
* It may also return an error, if that error may have prevented the pattern from matching more than it did.
*
* Some more complex patterns might succeed, but consume less input than they would have been able to if some
* other expected symbol was found. Reporting the furthest a pattern could hypothetically have gotten can help generate
* better error messages if no valid parse tree is found.
*
* @param source - the string being parsed
* @param index - the index in the string to begin matching from
* @returns - [successValue, furthest symbol attempted, expected pattern]
*/
(source: string, index: number): [[T, number] | null, number, string];
};
/** /**
* Makes a pattern from a function, adding helper methods. * Makes a pattern from a function, adding helper methods.
* *
* @template T
* @param {(source: string, index: number) => ([[T, number] | null, number, string])} matchFunc * @param {(source: string, index: number) => ([[T, number] | null, number, string])} matchFunc
* @returns {Peg.Pattern<T>} * @returns {Peg.Pattern<T>}
*/ */
Peg.WrapPattern = function (matchFunc) { function WrapPattern<T>(matchFunc: PatternFunc<T>) {
const pattern = /** @type {Peg.Pattern<T>} */ (matchFunc); const pattern = matchFunc as Pattern<T>;
pattern.map = function (map) { pattern.map = (map) => {
return Peg.WrapPattern(function (source, index) { return WrapPattern((source, index) => {
const [value, furthest, expected] = pattern(source, index); const [value, furthest, expected] = pattern(source, index);
return [value ? [map(value[0]), value[1]] : null, furthest, expected]; return [value ? [map(value[0]), value[1]] : null, furthest, expected];
}).expects(pattern.expectLabel); }).expects(pattern.expectLabel);
@ -51,31 +55,26 @@ Peg.WrapPattern = function (matchFunc) {
}; };
return pattern; return pattern;
}; }
/** /**
* Proxies to a pattern retrieved from an accessor function. * Proxies to a pattern retrieved from an accessor function.
* *
* Allows using a pattern recursively in its own definition, by returning the value of the const assigned to. * Allows using a pattern recursively in its own definition, by returning the value of the const assigned to.
* *
* @template T * @param getPattern
* @param {() => Peg.Pattern<T>} getPattern
* @returns {Peg.Pattern<T>}
*/ */
Peg.Use = function (getPattern) { export function Use<T>(getPattern: () => Pattern<T>): Pattern<T> {
return Peg.WrapPattern(function (source, index) { return WrapPattern((source, index) => getPattern()(source, index)).expects(
return getPattern()(source, index); String(getPattern)
}).expects(String(getPattern)); );
}; }
/** /**
* Creates a pattern matching a regex & returning any captures. The regex needs to be sticky (using the //y modifier) * Creates a pattern matching a regex & returning any captures. The regex needs to be sticky (using the //y modifier)
* @param {RegExp} regex
* @return {Peg.Pattern<RegExpExecArray>}
*/ */
Peg.Regex = function (regex) { export function Regex(regex: RegExp): Pattern<RegExpExecArray> {
/** @type {Peg.Pattern<RegExpExecArray>} */ const pattern = WrapPattern((source, index) => {
const pattern = Peg.WrapPattern(function (source, index) {
regex.lastIndex = index; regex.lastIndex = index;
const matches = regex.exec(source); const matches = regex.exec(source);
return matches return matches
@ -83,19 +82,18 @@ Peg.Regex = function (regex) {
: [null, index, pattern.expectLabel]; : [null, index, pattern.expectLabel];
}).expects(regex.source); }).expects(regex.source);
return pattern; return pattern;
}; }
/** /**
* Creates a pattern that tries the given patterns, in order, until it finds one that matches at the current index. * Creates a pattern that tries the given patterns, in order, until it finds one that matches at the current index.
* @template T
* @param {...Peg.Pattern<T>} patterns * @param {...Peg.Pattern<T>} patterns
* @return {Peg.Pattern<T>} * @return {}
*/ */
Peg.Choose = function (...patterns) { export function Choose<T>(...patterns: Pattern<T>[]): Pattern<T> {
const genericExpected = patterns const genericExpected = patterns
.map((pattern) => pattern.expectLabel) .map((pattern) => pattern.expectLabel)
.join(" | "); .join(" | ");
return Peg.WrapPattern(function (source, index) { return WrapPattern((source, index) => {
let furthestFound = index; let furthestFound = index;
let furthestExpected = genericExpected; let furthestExpected = genericExpected;
for (const pattern of patterns) { for (const pattern of patterns) {
@ -111,21 +109,20 @@ Peg.Choose = function (...patterns) {
} }
return [null, furthestFound, furthestExpected]; return [null, furthestFound, furthestExpected];
}).expects(genericExpected); }).expects(genericExpected);
}; }
/** /**
* Creates a pattern that concatenates the given patterns, returning a tuple of their captured values. * Creates a pattern that concatenates the given patterns, returning a tuple of their captured values.
* *
* For example, if A matches "a" and captures 1, while B matches "b" and captures null, * For example, if A matches "a" and captures 1, while B matches "b" and captures null,
* then `Sequence(A,B)` will match "ab" and capture [1, null] * then `Sequence(A,B)` will match "ab" and capture [1, null]
* @template {unknown[]} T
* @param {{[K in keyof T]: Peg.Pattern<T[K]>}} patterns
* @return {Peg.Pattern<T>}
*/ */
Peg.Sequence = function (...patterns) { export function Sequence<T extends unknown[]>(
...patterns: { [K in keyof T]: Pattern<T[K]> }
): Pattern<T> {
const genericExpected = patterns[0]?.expectLabel ?? "(nothing)"; const genericExpected = patterns[0]?.expectLabel ?? "(nothing)";
return Peg.WrapPattern(function (source, index) { return WrapPattern((source, index) => {
const values = /** @type {T} */ (/** @type {unknown} */ ([])); const values: unknown[] = [];
let furthestFound = index; let furthestFound = index;
let furthestExpected = genericExpected; let furthestExpected = genericExpected;
for (const pattern of patterns) { for (const pattern of patterns) {
@ -142,9 +139,9 @@ Peg.Sequence = function (...patterns) {
values.push(value[0]); values.push(value[0]);
index = value[1]; index = value[1];
} }
return [[values, index], furthestFound, furthestExpected]; return [[values as T, index], furthestFound, furthestExpected];
}).expects(genericExpected); }).expects(genericExpected);
}; }
/** /**
* Creates a pattern that matches consecutive runs of the given pattern, returning an array of all captures. * Creates a pattern that matches consecutive runs of the given pattern, returning an array of all captures.
@ -154,14 +151,12 @@ Peg.Sequence = function (...patterns) {
* If the given pattern does not consume input, the matching will be terminated to prevent an eternal loop. * If the given pattern does not consume input, the matching will be terminated to prevent an eternal loop.
* *
* Note that if the minimum run is zero, this pattern will always succeed, but might not consume any input. * Note that if the minimum run is zero, this pattern will always succeed, but might not consume any input.
* @template {unknown} T
* @param {number} min * @param {number} min
* @param {Peg.Pattern<T>} pattern
* @return {Peg.Pattern<T[]>}
*/ */
Peg.AtLeast = function (min, pattern) { export function AtLeast<T>(min, pattern: Pattern<T>): Pattern<T[]> {
return Peg.WrapPattern(function (source, index) { return WrapPattern(function (source, index) {
const values = /** @type {T[]} */ ([]); const values: T[] = [];
let furthestFound = index; let furthestFound = index;
let furthestExpected = pattern.expectLabel; let furthestExpected = pattern.expectLabel;
do { do {
@ -185,20 +180,18 @@ Peg.AtLeast = function (min, pattern) {
return [null, furthestFound, furthestExpected]; return [null, furthestFound, furthestExpected];
} }
}).expects(pattern.expectLabel); }).expects(pattern.expectLabel);
}; }
/** /**
* Creates a pattern that matches the end of input * Creates a pattern that matches the end of input
* @return {Peg.Pattern<true>}
*/ */
Peg.End = () => { export function End(): Pattern<true> {
/** @type {Peg.Pattern<true>} */ const end = WrapPattern(function End(source, index) {
const end = Peg.WrapPattern(function End(source, index) {
return [ return [
source.length == index ? [/** @type {true} */ (true), index] : null, source.length == index ? [true, index] : null,
index, index,
end.expectLabel, end.expectLabel,
]; ];
}).expects("<eof>"); }).expects("<eof>");
return end; return end;
}; }