rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/words.ts

@@ -0,0 +1,254 @@
+// a film row's declared words (wiki build/trailer.md, A row's words): the row says which words it takes and their
+// types, the core reads every word of a film line at its own line against that, refuses an unknown one with the row's
+// list, and hands the row its values made plain (argv stays the transport). Pure: times arrive as moments the grammar
+// resolves once the shots have landed
+
+export type WordType = 'number' | 'int' | 'enum' | 'point' | 'time' | 'cues' | 'file' | 'text' | 'word' | 'flag'
+export const WORD_TYPES: readonly WordType[] = ['number', 'int', 'enum', 'point', 'time', 'cues', 'file', 'text', 'word', 'flag']
+
+/** one word a row takes: its type and bounds; `arg: n` makes it the n-th positional */
+export interface WordSpec {
+    type: WordType
+    arg?: number
+    optional?: boolean
+    min?: number
+    max?: number
+    values?: string[]
+    /** a point's numbers, 2 by default */
+    count?: number
+    /** a word's shape, a regular expression */
+    pattern?: string
+    /** what it means, for the error that lists the row's words */
+    doc?: string
+}
+
+export type Words = Record<string, WordSpec>
+
+/** a word of a film line, with the line it sits on (an option line under the film line keeps its own) */
+export interface LineWord {
+    text: string
+    quoted: boolean
+    line: number
+}
+
+/** a time: seconds, or a section or mark of the cut and a time from it */
+export type Moment = number | { mark: string; offset: number }
+
+export interface Typed {
+    /** the row's path, then its words in the order written, each value plain; a time's slot is filled by `times` */
+    argv: string[]
+    /** argv slots made of moments: a time (`name` null) or cues (`name@seconds`, comma joined) */
+    times: { index: number; parts: { name: string | null; at: Moment; line: number }[] }[]
+    /** argv slots that are files, as written: the build finds them and keys their content */
+    files: number[]
+    errors: { line: number; message: string }[]
+}
+
+/** the row's words checked as a declaration: every type known, its bounds sane; null when it is one */
+export function wordsProblem(words: unknown): string | null {
+    if (typeof words !== 'object' || words === null) return 'words is a record of word → { type }'
+    for (const [k, v] of Object.entries(words as Record<string, unknown>)) {
+        const w = v as Partial<WordSpec> | null
+        if (!/^[a-z][a-z0-9-]*$/.test(k)) return `word ${k}: a word is lowercase letters, digits and -`
+        if (!w || !WORD_TYPES.includes(w.type as WordType)) return `word ${k}: type is one of ${WORD_TYPES.join(', ')}`
+        if (w.type === 'enum' && (!Array.isArray(w.values) || w.values.length === 0)) return `word ${k}: an enum names its values`
+        if (w.pattern !== undefined) {
+            try {
+                new RegExp(w.pattern)
+            } catch {
+                return `word ${k}: pattern ${w.pattern} is no regular expression`
+            }
+        }
+    }
+    return null
+}
+
+const n4 = (x: number): string => String(+x.toFixed(4))
+
+/** one value read by its type: its plain text, a moment, or why it does not fit */
+function valueOf(key: string, spec: WordSpec, w: LineWord, time: (text: string) => Moment | null): { text: string } | { at: Moment } | { error: string } {
+    const t = w.text
+    const what = `${key} wants ${describe(spec)}, got ${w.quoted ? `"${t}"` : t}`
+    switch (spec.type) {
+        case 'number':
+        case 'int': {
+            const v = w.quoted ? Number.NaN : Number(t)
+            if (!Number.isFinite(v) || (spec.type === 'int' && !Number.isInteger(v)) || (spec.min !== undefined && v < spec.min) || (spec.max !== undefined && v > spec.max)) return { error: what }
+            return { text: t }
+        }
+        case 'enum':
+            return !w.quoted && spec.values!.includes(t) ? { text: t } : { error: what }
+        case 'point': {
+            const parts = w.quoted ? [] : t.split(',')
+            const ok = parts.length === (spec.count ?? 2) && parts.every((p) => p !== '' && Number.isFinite(Number(p)))
+            return ok ? { text: t } : { error: what }
+        }
+        case 'time': {
+            const at = w.quoted ? null : time(t)
+            return at === null ? { error: what } : { at }
+        }
+        case 'file':
+        case 'word':
+            if (w.quoted || t === '' || (spec.pattern !== undefined && !new RegExp(spec.pattern).test(t))) return { error: what }
+            return { text: t }
+        case 'text':
+            return t.trim() === '' ? { error: `${key}: the text is empty` } : { text: t }
+        default:
+            return { error: what }
+    }
+}
+
+function describe(s: WordSpec): string {
+    switch (s.type) {
+        case 'number':
+        case 'int':
+            return `${s.type === 'int' ? 'a whole number' : 'a number'}${s.min !== undefined || s.max !== undefined ? ` from ${s.min ?? '-∞'} to ${s.max ?? '∞'}` : ''}`
+        case 'enum':
+            return s.values!.join('|')
+        case 'point':
+            return `${s.count ?? 2} numbers joined by commas`
+        case 'time':
+            return 'a time (1.5s, 400ms, 0:04, 2beats, a mark, mark+1beat)'
+        case 'cues':
+            return 'cues, name@<time> each'
+        case 'file':
+            return 'a file'
+        case 'word':
+            return `a word${s.pattern ? ` like ${s.pattern}` : ''}`
+        case 'text':
+            return 'a text'
+        case 'flag':
+            return 'no value'
+    }
+}
+
+/** the row's words, for an error: positionals in order, then keys */
+export const wordList = (words: Words): string =>
+    [
+        ...Object.entries(words)
+            .filter(([, s]) => s.arg !== undefined)
+            .sort((a, b) => a[1].arg! - b[1].arg!)
+            .map(([k, s]) => `<${k}>${s.optional ? '?' : ''}`),
+        ...Object.entries(words)
+            .filter(([, s]) => s.arg === undefined)
+            .map(([k]) => k),
+    ].join(' ')
+
+interface Entry {
+    key: string
+    /** a positional's words carry no key on the line */
+    positional: boolean
+    values: LineWord[]
+    line: number
+}
+
+/** the entries of a run of words: a word that names a key opens it (its value words follow), any other word fills the
+ *  next positional that takes it */
+function entriesOf(path: string, words: Words, ws: LineWord[], time: (text: string) => Moment | null, errors: Typed['errors']): Entry[] {
+    const args = Object.entries(words)
+        .filter(([, s]) => s.arg !== undefined)
+        .sort((a, b) => a[1].arg! - b[1].arg!)
+    let next = 0
+    const out: Entry[] = []
+    for (let i = 0; i < ws.length; i++) {
+        const w = ws[i]!
+        const spec = !w.quoted && words[w.text] && words[w.text]!.arg === undefined ? words[w.text]! : null
+        if (spec) {
+            if (spec.type === 'flag') out.push({ key: w.text, positional: false, values: [], line: w.line })
+            else if (spec.type === 'cues') {
+                const values: LineWord[] = []
+                while (i + 1 < ws.length && !ws[i + 1]!.quoted && /^[^@\s]+@\S+$/.test(ws[i + 1]!.text) && !words[ws[i + 1]!.text]) {
+                    const c = ws[++i]!
+                    for (const text of c.text.split(',')) values.push({ ...c, text })
+                }
+                if (values.length === 0) errors.push({ line: w.line, message: `film ${path} ${w.text} wants cues, name@<time> each` })
+                out.push({ key: w.text, positional: false, values, line: w.line })
+            } else {
+                const v = ws[i + 1]
+                if (!v || v.line !== w.line) errors.push({ line: w.line, message: `film ${path} ${w.text} wants ${describe(spec)}` })
+                else {
+                    out.push({ key: w.text, positional: false, values: [v], line: w.line })
+                    i++
+                }
+            }
+            continue
+        }
+        // the next positional that takes this word; an optional one that does not is passed over
+        let placed = false
+        while (next < args.length) {
+            const [k, s] = args[next++]!
+            if (!('error' in valueOf(k, s, w, time))) {
+                out.push({ key: k, positional: true, values: [w], line: w.line })
+                placed = true
+                break
+            }
+            if (!s.optional) {
+                errors.push({ line: w.line, message: `film ${path}: ${w.quoted ? `"${w.text}"` : w.text} fits no word here, <${k}> wants ${describe(s)} (${path} takes ${wordList(words)})` })
+                placed = true
+                break
+            }
+        }
+        if (!placed) {
+            errors.push({ line: w.line, message: `film ${path}: unknown word ${w.quoted ? `"${w.text}"` : w.text} (${path} takes ${wordList(words)})` })
+            // its value goes with it: one error a word
+            const v = ws[i + 1]
+            if (v && v.line === w.line && !(!v.quoted && words[v.text])) i++
+        }
+    }
+    return out
+}
+
+/**
+ * a film line of a row that declares its words: `ws` its words after the row's path, `defaults` its section's (a key
+ * the line gives itself wins). The plain argv, the slots that wait on a moment, the file slots, every error at its line
+ */
+export function typedFilm(path: string[], words: Words, ws: LineWord[], defaults: LineWord[], time: (text: string) => Moment | null): Typed {
+    const errors: Typed['errors'] = []
+    const own = entriesOf(path.join(' '), words, ws, time, errors)
+    const given = new Set(own.map((e) => e.key))
+    const fromDefaults = defaults.length > 0 ? entriesOf(path.join(' '), words, defaults, time, errors).filter((e) => !given.has(e.key)) : []
+    const all = [...fromDefaults, ...own]
+    const seen = new Set<string>()
+    const argv = [...path]
+    const times: Typed['times'] = []
+    const files: number[] = []
+    for (const e of all) {
+        if (seen.has(e.key)) {
+            errors.push({ line: e.line, message: `film ${path.join(' ')}: ${e.key} given twice` })
+            continue
+        }
+        seen.add(e.key)
+        const spec = words[e.key]!
+        if (!e.positional) argv.push(e.key)
+        if (spec.type === 'flag') continue
+        if (spec.type === 'cues') {
+            const parts: Typed['times'][number]['parts'] = []
+            for (const v of e.values) {
+                const at = v.text.indexOf('@')
+                const name = v.text.slice(0, at)
+                const m = time(v.text.slice(at + 1))
+                if (m === null) errors.push({ line: v.line, message: `film ${path.join(' ')} ${e.key}: ${v.text}, the time after @ is no time (1.5s, 2beats, a mark, mark+1beat)` })
+                else parts.push({ name, at: m, line: v.line })
+            }
+            times.push({ index: argv.length, parts })
+            argv.push('')
+            continue
+        }
+        const got = valueOf(e.key, spec, e.values[0]!, time)
+        if ('error' in got) {
+            errors.push({ line: e.values[0]!.line, message: `film ${path.join(' ')}: ${got.error}` })
+            argv.push(e.values[0]!.text)
+        } else if ('at' in got) {
+            times.push({ index: argv.length, parts: [{ name: null, at: got.at, line: e.values[0]!.line }] })
+            argv.push('')
+        } else {
+            if (spec.type === 'file') files.push(argv.length)
+            argv.push(got.text)
+        }
+    }
+    for (const [k, s] of Object.entries(words)) if (s.arg !== undefined && !s.optional && !seen.has(k)) errors.push({ line: ws[0]?.line ?? defaults[0]?.line ?? 0, message: `film ${path.join(' ')}: <${k}> is missing (${path.join(' ')} takes ${wordList(words)})` })
+    return { argv, times, files, errors }
+}
+
+/** a slot's text once its moments are seconds: a time, or cues joined by commas */
+export const slotText = (parts: readonly { name: string | null; seconds: number }[]): string => parts.map((p) => (p.name === null ? n4(p.seconds) : `${p.name}@${n4(p.seconds)}`)).join(',')