app/lib/novels/frontmatter.ts

Functions

Imports

It imports no other module of this repo. Imported by app/lib/books.server.ts, app/lib/novels/checks.ts, app/lib/novels/layout.ts, app/routes/book.chapter.tsx, app/routes/book.corkboard.tsx, app/routes/book.file.tsx.

Source

1// The header at the top of a book file: a narrow YAML subset, enough for scene headers and bible
2// entries and small enough to test completely. Keys hold a string, a boolean, or a list of strings
3// (inline `[a, b]` or one `- item` per line). Anything else is reported, never guessed at.
4
5export type HeaderValue = string | boolean | string[];
6
7export type Parsed = {
8  data: Record<string, HeaderValue>;
9  body: string;
10  /** The 1-based line of the file where the body starts, so a finding in the body names the file's line. */
11  bodyLine: number;
12  /** Lines the parser did not understand, by file line. A file with no header has none. */
13  problems: { line: number; text: string }[];
14};
15
16const KEY = /^([A-Za-z][A-Za-z0-9_-]*):(?:\s+(.*))?$/;
17
18function unquote(value: string): string {
19  const v = value.trim();
20  if (v.length >= 2 && ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))) {
21    return v.slice(1, -1);
22  }
23  return v;
24}
25
26/** Splits `a, "b, c", d` on the commas outside quotes. */
27function splitList(inner: string): string[] {
28  const items: string[] = [];
29  let current = "";
30  let quote: string | null = null;
31  for (const ch of inner) {
32    if (quote) {
33      if (ch === quote) quote = null;
34      current += ch;
35    } else if (ch === '"' || ch === "'") {
36      quote = ch;
37      current += ch;
38    } else if (ch === ",") {
39      items.push(current);
40      current = "";
41    } else {
42      current += ch;
43    }
44  }
45  items.push(current);
46  return items.map(unquote).filter((item) => item.length > 0);
47}
48
49function scalar(raw: string): HeaderValue {
50  const v = raw.trim();
51  if (v.startsWith("[") && v.endsWith("]")) return splitList(v.slice(1, -1));
52  if (v === "true") return true;
53  if (v === "false") return false;
54  return unquote(v);
55}
56
57export function parseFile(source: string): Parsed {
58  const lines = source.replace(/\r\n/g, "\n").split("\n");
59  if (lines[0]?.trim() !== "---") return { data: {}, body: lines.join("\n"), bodyLine: 1, problems: [] };
60  const end = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
61  if (end === -1) {
62    return { data: {}, body: lines.join("\n"), bodyLine: 1, problems: [{ line: 1, text: "The header opens with --- and never closes." }] };
63  }
64
65  const data: Record<string, HeaderValue> = {};
66  const problems: Parsed["problems"] = [];
67  // A key with nothing after it is an empty value until a `- item` line makes it a list.
68  let listKey: string | null = null;
69  for (let i = 1; i < end; i++) {
70    const line = lines[i]!;
71    if (line.trim() === "" || line.trim().startsWith("#")) continue;
72    const item = /^\s*-\s+(.*)$/.exec(line);
73    if (item && listKey) {
74      const current = data[listKey];
75      data[listKey] = [...(Array.isArray(current) ? current : []), unquote(item[1]!)];
76      continue;
77    }
78    const match = KEY.exec(line);
79    if (!match) {
80      problems.push({ line: i + 1, text: line });
81      listKey = null;
82      continue;
83    }
84    const [, key, value] = match;
85    const empty = value === undefined || value.trim() === "";
86    data[key!] = empty ? "" : scalar(value);
87    listKey = empty ? key! : null;
88  }
89  return { data, body: lines.slice(end + 1).join("\n"), bodyLine: end + 2, problems };
90}
91
92export function text(data: Record<string, HeaderValue>, key: string): string {
93  const value = data[key];
94  if (typeof value === "string") return value.trim();
95  if (Array.isArray(value)) return value.join(", ");
96  return "";
97}
98
99export function list(data: Record<string, HeaderValue>, key: string): string[] {
100  const value = data[key];
101  if (Array.isArray(value)) return value.map((v) => v.trim()).filter(Boolean);
102  if (typeof value === "string" && value.trim()) return splitList(value);
103  return [];
104}
105
106export function flag(data: Record<string, HeaderValue>, key: string): boolean {
107  return data[key] === true;
108}