@gloom-sh/terminal 0.0.0-stage → 0.19.0

package/src/cli/symbol-args.ts

@@ -0,0 +1,158 @@
+import { isFigure, isNumberCell, protectFigureCommas, restoreFigureCommas } from "./symbol-cells";
+import { readTerminalListingCode, unknownBloombergMarket } from "../tickers/terminal-codes";
+
+/** The quote marks a pasted list wraps its entries in: "AAPL", 'MSFT', “NVDA”. */
+const QUOTE_MARKS = "\"'`\u2018\u2019\u201C\u201D";
+const QUOTE_EDGES = new RegExp(`^[${QUOTE_MARKS}]+|[${QUOTE_MARKS}]+$`, "g");
+
+/** What separates the entries of a list: a comma, a semicolon, a tab (a sheet's cells) or a line. */
+const LIST_SEPARATOR = /[,;\t\r\n]/;
+
+/**
+ * The entries of command arguments, each of which may hold several (a pasted
+ * list), with the blanks dropped, the quote marks around each entry removed
+ * and the typed case kept. An argument with commas, semicolons, tabs or lines
+ * in it is split on those, so an entry may be a company's name (`WHR,
+ * Whirlpool Corporation, BRK.B`) or several symbols with spaces between them
+ * (`brk.b bf-b` on a pasted line); one without them is split on spaces (`JNK
+ * EMB BRK.B`), or with `phrases` kept whole (`splitSymbolArgLines`). Which an
+ * entry with a space is takes a search: a command that
+ * resolves its symbols reads them with `readNameEntries`, and a parser that
+ * looks nothing up takes `splitSymbolWords`. A comma inside a figure
+ * (`2.582,52`, `1,899.21`) is no separator: the figure stays one entry. One
+ * between plain digits is a decimal comma only on a line with another
+ * separator (`ED 2,5`); alone it splits codes (`9988,5`, `700,388`).
+ */
+export function splitSymbolArgs(args: readonly string[], options: { phrases?: boolean } = {}): string[] {
+  return args.flatMap((arg) => splitSymbolArgLines(arg, options).flat());
+}
+
+/**
+ * `splitSymbolArgs` of one argument, its entries kept by the line they are
+ * on, so a figure can be told to sit beside the symbol on its line. With
+ * `phrases`, an argument with spaces and no list separator is one entry, as
+ * an entry between commas is: a company's name (`"Beyond Meat"`) or symbols
+ * typed on one line (`"GME AMC"`), which `readNameEntries` tells apart.
+ */
+export function splitSymbolArgLines(arg: string, { phrases = false }: { phrases?: boolean } = {}): string[][] {
+  const lines = arg.replace(/^\uFEFF/, "").split(/\r\n?|\n/).map((line) => protectFigureCommas(line));
+  const separated = lines.length > 1 || lines.some((line) => LIST_SEPARATOR.test(line));
+  // A terminal's code (`VOD LN`, `JPM US Equity`), or words written as one (`AAPL GP`), is one entry.
+  return lines.map((line) => (separated ? line.split(/[,;\t]/) : phrases || isTerminalCodeLine(line) ? [line] : line.split(/\s+/))
+    .map((entry) => restoreFigureCommas(entry).trim().replace(QUOTE_EDGES, "").trim().replace(/\s+/g, " "))
+    .filter(Boolean));
+}
+
+function isTerminalCodeLine(line: string): boolean {
+  const text = line.trim().replace(QUOTE_EDGES, "").trim();
+  return /\s/.test(text) && (readTerminalListingCode(text) != null || unknownBloombergMarket(text) != null);
+}
+
+/**
+ * The one argument a command was given, when the user quoted words with
+ * spaces and no list separator into it: `quote "10 year yield"`, `quote
+ * "Apple Inc"` or a pasted line `quote "AAPL MSFT"`. Which of those it is
+ * takes a lookup (`readPhraseArgument`); `splitSymbolArgs` would split it
+ * into words, each a symbol (10, YEAR, YIELD). A figure in it is part of
+ * the phrase (`"10.5 year yield"`, `"fed funds rate 5.25%"`). Null for
+ * anything else: several arguments, one word, a list with commas, or a
+ * pasted row of symbols each followed by its prices (`ED 2.582,52`, `AAPL
+ * 150.00 MSFT 300.00`), which is read as a list is.
+ */
+export function quotedPhrase(args: readonly string[]): string | null {
+  if (args.length !== 1) return null;
+  const text = args[0]!.replace(/^\uFEFF/, "");
+  if (LIST_SEPARATOR.test(protectFigureCommas(text))) return null;
+  const phrase = text.trim().replace(QUOTE_EDGES, "").trim().replace(/\s+/g, " ");
+  return phrase.includes(" ") && !isPricedRow(phrase.split(" ")) ? phrase : null;
+}
+
+/**
+ * Words that are a sheet's row rather than a phrase: a number (`2.582,52`)
+ * among them, and each word that is no figure followed by one (`ED
+ * 2.582,52`), so no two words of a name or a phrase sit side by side.
+ */
+function isPricedRow(words: readonly string[]): boolean {
+  if (!words.some(isNumberCell) || isFigure(words[0]!)) return false;
+  return words.every((word, index) => isFigure(word) || (index + 1 < words.length && isFigure(words[index + 1]!)));
+}
+
+/**
+ * Symbols given as command arguments, split on commas, semicolons, spaces,
+ * tabs and lines in any mix, each without its quote marks and in its typed
+ * case: `"GME", 'AMC'\nBF.B brk.b` is GME, AMC, BF.B and brk.b. The split of
+ * a parser that looks nothing up, and of an entry search finds no company for.
+ */
+export function splitSymbolWords(args: readonly string[]): string[] {
+  return splitSymbolArgs(args)
+    .flatMap((entry) => isTerminalCodeLine(entry) ? [entry] : entry.split(" "))
+    .map((word) => word.replace(QUOTE_EDGES, ""))
+    .filter(Boolean);
+}
+
+/** The list separators in `text`, each once: `,;` for a stray `;,;`. */
+function separatorsIn(text: string): string {
+  return [...new Set([...text].filter((char) => char === "," || char === ";"))].join("");
+}
+
+/**
+ * A pasted list, or one cell of a file, without the separators and quote marks
+ * stuck to its ends (`UPST;`, `"GME",`). The separators it dropped are named
+ * (`Ignored the stray ";" after UPST.`) rather than swallowed, and never reach
+ * a listing search as part of a symbol, which would ask for `UPST;`.
+ */
+export function stripStrayEdges(text: string): { text: string; notes: string[] } {
+  const junk = `[\\s,;${QUOTE_MARKS}]`;
+  const leading = text.match(new RegExp(`^${junk}+`))?.[0] ?? "";
+  const rest = text.slice(leading.length);
+  const trailing = rest.match(new RegExp(`${junk}+$`))?.[0] ?? "";
+  const inner = rest.slice(0, rest.length - trailing.length);
+  const entries = splitSymbolWords([inner]);
+  const [first, last] = [entries[0], entries.at(-1)];
+  const before = separatorsIn(leading);
+  const after = separatorsIn(trailing);
+  const notes = !first
+    ? (before || after ? [`Ignored the stray "${separatorsIn(leading + trailing)}".`] : [])
+    : [
+      ...before ? [`Ignored the stray "${before}" before ${first}.`] : [],
+      ...after ? [`Ignored the stray "${after}" after ${last}.`] : [],
+    ];
+  return { text: inner, notes };
+}
+
+/** How a symbol is compared for repeats: AAPL, aapl and $AAPL are one. */
+export function symbolInputKey(symbol: string): string {
+  return symbol.trim().replace(/^\$/, "").toUpperCase();
+}
+
+/**
+ * How a command's symbol list spots one security typed twice: `symbolInputKey`,
+ * with a share class written with a dot or a dash as one (BRK.B and BRK-B).
+ */
+function securityInputKey(symbol: string): string {
+  return symbolInputKey(symbol).replace(/-/g, ".");
+}
+
+/** The securities of a symbol list, each once, in the first spelling typed: `AAPL aapl BRK.B BRK-B` is AAPL and BRK.B. */
+export function uniqueSecuritySymbols(symbols: readonly string[]): string[] {
+  const seen = new Set<string>();
+  return symbols.filter((symbol) => {
+    const key = securityInputKey(symbol);
+    if (!key || seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+/** The symbols without repeats, first spelling kept, and how many repeats were dropped. */
+export function uniqueSymbols(symbols: readonly string[]): { symbols: string[]; repeated: number } {
+  const seen = new Set<string>();
+  const unique: string[] = [];
+  for (const symbol of symbols) {
+    const key = symbolInputKey(symbol);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    unique.push(symbol.trim());
+  }
+  return { symbols: unique, repeated: symbols.filter((symbol) => symbolInputKey(symbol)).length - unique.length };
+}

package/src/cli/symbol-cells.ts

@@ -0,0 +1,120 @@
+/**
+ * What one cell of a pasted list or a typed argument is before anything is
+ * looked up: a symbol, a figure (a price, a weight, a share count) or junk
+ * a sheet leaves where a value is missing (`N/A`, `--`, `$$$`). Every list
+ * reader and every lookup of a list's symbols decide it here, so a price
+ * from a European sheet (`2.582,52`) is never searched for as a ticker.
+ */
+
+/** A sign before a figure: plus, hyphen-minus or the minus sign. */
+const SIGN = "[+\\-\u2212]";
+/** The currency marks a sheet writes beside an amount. */
+const CURRENCY = "[$\u20ac\u00a3\u00a5\u20b9\u20a9\u20bd\u20ba\u20aa\u0e3f\u20ab\u00a2]";
+/** Thousands written with an apostrophe (1'234.50) or a no-break or thin space (1 234,50). */
+const GROUP_MARK = "['\u2019\u00a0\u202f\u2009]";
+const FIGURE_BODY = [
+  // 1,899.21 and 1,899: commas between thousands.
+  "\\d{1,3}(?:,\\d{3})+(?:\\.\\d+)?",
+  // 2.582,52, 1.899 and 1.234.567: dots between thousands, a decimal comma.
+  "\\d{1,3}(?:\\.\\d{3})+(?:,\\d+)?",
+  `\\d{1,3}(?:${GROUP_MARK}\\d{3})+(?:[.,]\\d+)?`,
+  // 2,5 and 12,345, and 1234,56: a decimal comma.
+  "\\d{1,3},\\d+",
+  "\\d+,\\d{1,2}",
+  "\\d*\\.\\d+",
+  "\\d+",
+].join("|");
+const FIGURE = new RegExp(
+  `^(?:${SIGN}?${CURRENCY}?${SIGN}?(?:${FIGURE_BODY})(?:%|\u2030|${CURRENCY})?|\\(${CURRENCY}?(?:${FIGURE_BODY})%?\\))$`,
+  "u",
+);
+/** A run of digits and the marks between them, where a comma may be a decimal comma rather than a list's separator. */
+const FIGURE_RUN = new RegExp(`(?<![\\p{L}\\p{N}.])(?:${SIGN}|${CURRENCY})*\\d[\\d.,'\u2019\u00a0\u202f\u2009]*(?:%|\u2030|${CURRENCY})?`, "gu");
+/** Placeholders a sheet writes for a missing value, and its error values: N/A, n.a., #N/A, #VALUE!. */
+const PLACEHOLDER = /^(?:#?n\/a|n\.a\.?|#(?:value!|ref!|div\/0!|name\?|num!|null!|spill!|calc!|getting_data))$/i;
+/** Stands in for a comma inside a figure while a line is split on its separators. */
+const FIGURE_COMMA = "\u0000";
+/** Plain digits split by commas (`7203,10`, `5,700`): a decimal comma, or the line's separator between two codes. */
+const PLAIN_COMMA_RUN = /^\d+(?:,\d+)+$/;
+
+/**
+ * A figure as a sheet or a keyboard writes it, a bare whole number (7203)
+ * included: `2.582,52`, `1,899.21`, `-3.2%`, `€1.234,56`, `(1,234.56)`.
+ */
+export function isFigure(cell: string): boolean {
+  return FIGURE.test(cell.trim());
+}
+
+/**
+ * A figure that is never a symbol: one with a decimal or thousands mark, a
+ * sign, a percent or a currency mark (`1.899`, `2,5`, `+4`, `12%`, `$12`). A
+ * bare whole number is not one, as `7203` and `0700` are tickers on their own.
+ */
+export function isNumberCell(cell: string): boolean {
+  const text = cell.trim();
+  return FIGURE.test(text) && !/^\d+$/.test(text);
+}
+
+/** A cell that names nothing: no letter or digit (`$$$`, `--`, `-`, `…`), or a placeholder for a missing value (`N/A`, `#N/A`). */
+export function isJunkCell(cell: string): boolean {
+  const text = cell.trim();
+  return !/[\p{L}\p{N}]/u.test(text) || PLACEHOLDER.test(text);
+}
+
+/** Why a cell is not a symbol, as a lookup refuses it without asking anything; null for one that may be. */
+function notASymbolReason(cell: string): string | null {
+  if (isJunkCell(cell)) return "not a symbol";
+  if (isNumberCell(cell)) return "a number, not a symbol";
+  return null;
+}
+
+/** An entry of a list that cannot be a symbol, refused before any lookup and never looked up again. */
+export class NotASymbolError extends Error {
+  constructor(readonly input: string, readonly reason: string) {
+    super(`${input.trim()} is ${reason}.`);
+    this.name = "NotASymbolError";
+  }
+}
+
+/** `NotASymbolError` for a cell that is not a symbol, else null. */
+export function notASymbolError(cell: string): NotASymbolError | null {
+  const reason = notASymbolReason(cell);
+  return reason ? new NotASymbolError(cell, reason) : null;
+}
+
+/**
+ * Whether a comma between plain digits on a line is a decimal comma (`ED
+ * 2,5`, `CNX;1899,21`): the line has another separator, a tab, a semicolon or
+ * spaces between its cells. Otherwise the comma is the line's only separator
+ * and splits the digits into cells, as a sheet of codes exports them
+ * (`0700,25`, `7203,10`). Quoted cells and separators at the ends are not
+ * counted.
+ */
+export function hasDecimalCommas(line: string): boolean {
+  const bare = line.replace(/"(?:[^"]|"")*"/g, "\"\"").replace(/^[\s,;]+|[\s,;]+$/g, "");
+  return /[\t;]/.test(bare) || /[^\s,;]\s+[^\s,;]/.test(bare);
+}
+
+/**
+ * The text with each comma inside a figure swapped for a stand-in, so
+ * splitting on commas leaves the figure whole; `restoreFigureCommas` puts
+ * them back. A figure only a number can be (`2.582,52`, `1,899.21`, `2,5%`)
+ * keeps its comma. One of plain digits (`7203,10`) keeps it only where its
+ * comma is a decimal comma: `decimalCommas`, else `hasDecimalCommas` of each
+ * line. A run that is no figure keeps its commas as separators.
+ */
+export function protectFigureCommas(text: string, decimalCommas?: boolean): string {
+  if (decimalCommas == null) {
+    return text.split(/(\r\n?|\n)/).map((part, index) => index % 2 === 1 ? part : protectFigureCommas(part, hasDecimalCommas(part))).join("");
+  }
+  return text.replace(FIGURE_RUN, (run) => {
+    const body = run.replace(/[.,'\u2019]+$/, "");
+    const tail = run.slice(body.length);
+    const figure = body.includes(",") && isFigure(body) && (decimalCommas || !PLAIN_COMMA_RUN.test(body));
+    return figure ? `${body.replaceAll(",", FIGURE_COMMA)}${tail}` : run;
+  });
+}
+
+export function restoreFigureCommas(text: string): string {
+  return text.replaceAll(FIGURE_COMMA, ",");
+}

package/src/cli/symbol-list.ts

@@ -0,0 +1,374 @@
+import { readFile } from "fs/promises";
+import { fstatSync } from "fs";
+import { splitSymbolArgLines, splitSymbolWords, stripStrayEdges, uniqueSymbols } from "./symbol-args";
+import { foldTypedText } from "../utils/typed-text";
+import { hasDecimalCommas, isFigure, isJunkCell, isNumberCell, protectFigureCommas, restoreFigureCommas } from "./symbol-cells";
+
+/** Header cells that name a spreadsheet's symbol column, compared without case, spaces or punctuation. */
+const SYMBOL_HEADERS = new Set(["symbol", "symbols", "ticker", "tickers", "code", "stockcode", "securitycode", "instrument"]);
+/** A header naming a column of company names, read when no column names the symbols. */
+const NAME_HEADERS = new Set(["name", "names", "company", "companies", "companyname", "security", "securityname", "issuer", "issuername"]);
+
+/** One symbol as it can be typed: AAPL, $nvda, TTF.AS, SAN:EPA, BRK-B, 7203.T, ^GSPC, ES=F. */
+const SYMBOL_TOKEN = /^\$?[\p{L}\p{N}^][\p{L}\p{N}.:\-^=/&]{0,23}$/u;
+
+function headerKey(cell: string): string {
+  return cell.toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
+}
+
+function isComment(cell: string): boolean {
+  return cell.startsWith("#") || cell.startsWith("//");
+}
+
+/** Whether a quote mark at `index` closes a quoted cell: it is followed by a separator, a line end or the end. */
+function closesCell(text: string, index: number): boolean {
+  return /^[^\S\n]*(?:[\t,;\n]|$)/.test(text.slice(index + 1, index + 40));
+}
+
+/** Where the quoted cell opened at `index` ends, or -1 when no quote mark closes it, so the mark is only a stray. */
+function closingQuote(text: string, index: number): number {
+  for (let at = text.indexOf("\"", index + 1); at >= 0; at = text.indexOf("\"", at + 1)) {
+    if (text[at + 1] === "\"") {
+      at += 1;
+      continue;
+    }
+    if (closesCell(text, at)) return at;
+  }
+  return -1;
+}
+
+/**
+ * The records of a text: its lines, except that a quoted cell (RFC 4180)
+ * may hold a line break. A quote mark opens a cell only at the start of
+ * one and when a mark closes it, so a stray one never swallows the lines after it.
+ */
+function splitRecords(text: string): string[] {
+  const records: string[] = [];
+  let start = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index]!;
+    if (char === "\"" && /(?:^|[\t,;])[^\S\n]*$/.test(text.slice(start, index))) {
+      const end = closingQuote(text, index);
+      if (end >= 0) index = end;
+    } else if (char === "\n") {
+      records.push(text.slice(start, index));
+      start = index + 1;
+    }
+  }
+  records.push(text.slice(start));
+  return records;
+}
+
+/**
+ * The separator of one line: a tab, else a semicolon, else a comma that
+ * splits cells, not one inside a figure (`ED 2.582,52` is split by its space,
+ * `CNX;1.899,21` by its semicolon). Null for a line split by spaces. A
+ * separator at either end is a stray (`UPST;`), named when the cell is read.
+ * `decimalCommas` says whether a comma between plain digits is a decimal one.
+ */
+function lineDelimiter(record: string, decimalCommas: boolean): string | null {
+  const bare = protectFigureCommas(record, decimalCommas).replace(/^[\s,;]+|[\s,;]+$/g, "").replace(/"(?:[^"]|"")*"/g, "");
+  return ["\t", ";", ","].find((delimiter) => bare.includes(delimiter)) ?? null;
+}
+
+/** The cells of a line split by `delimiter`; a quoted cell may hold the delimiter and doubled quotes. */
+function splitCells(record: string, delimiter: string, decimalCommas: boolean): string[] {
+  const text = protectFigureCommas(record, decimalCommas);
+  const cells: string[] = [];
+  let cell = "";
+  let quoted = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index]!;
+    if (quoted) {
+      if (char === "\"" && text[index + 1] === "\"") {
+        cell += "\"";
+        index += 1;
+      } else if (char === "\"") {
+        quoted = false;
+      } else {
+        cell += char;
+      }
+      continue;
+    }
+    if (char === "\"" && !cell.trim() && closingQuote(text, index) >= 0) {
+      quoted = true;
+      cell = "";
+    } else if (char === delimiter) {
+      cells.push(cell);
+      cell = "";
+    } else {
+      cell += char;
+    }
+  }
+  cells.push(cell);
+  return cells.map((value) => restoreFigureCommas(value).trim());
+}
+
+/**
+ * The cells of each line, each line split by its own separator
+ * (`lineDelimiter`), as a list pasted from several sheets mixes them. A line
+ * with no separator in a list whose other lines have one is one cell (a
+ * company's name), unless a figure follows its first word (`ED 2.582,52`).
+ * A comma between plain digits is a decimal comma on a line with another
+ * separator, or under a header split by tabs or semicolons; otherwise it
+ * splits the line (`0700,25` is a code and a weight). `delimited` says
+ * whether any line had a separator.
+ */
+function readRecords(text: string): { records: string[][]; delimited: boolean } {
+  const kept = splitRecords(text).filter((record) => record.replace(/[\s,;"']/g, ""));
+  const sheetDecimals = headerSplitsOnTabsOrSemicolons(kept[0]);
+  const lines = kept.map((record) => {
+    const decimalCommas = sheetDecimals || hasDecimalCommas(record);
+    const delimiter = lineDelimiter(record, decimalCommas);
+    return delimiter
+      ? { cells: splitCells(record, delimiter, decimalCommas), delimited: true }
+      : { cells: record.trim().split(/\s+/), delimited: false };
+  });
+  const delimited = lines.some((line) => line.delimited);
+  const records = lines.map(({ cells, delimited: own }) => (
+    own || !delimited || cells.slice(1).some(isFigure) ? cells : [cells.join(" ")]
+  ));
+  return { records: records.filter((cells) => cells.some(Boolean) && !isComment(cells[0] ?? "")), delimited };
+}
+
+/** Whether a header line (one with a Symbol, Ticker, Code or Name cell) splits its cells on tabs or semicolons. */
+function headerSplitsOnTabsOrSemicolons(record: string | undefined): boolean {
+  if (!record) return false;
+  const delimiter = lineDelimiter(record, false);
+  if (delimiter !== "\t" && delimiter !== ";") return false;
+  return splitCells(record, delimiter, false).map(headerKey)
+    .some((key) => SYMBOL_HEADERS.has(key) || NAME_HEADERS.has(key) || key.includes("symbol") || key.includes("ticker"));
+}
+
+function looksLikeSymbol(cell: string): boolean {
+  return SYMBOL_TOKEN.test(cell) && !isNumberCell(cell);
+}
+
+/** How many cells a table's ignored-cells note names before it counts the rest. */
+const IGNORED_PREVIEW = 8;
+
+/** What a file or piped text holds: its symbols in order, and the cells of a table read by one column that were left out. */
+interface SymbolText {
+  symbols: string[];
+  /** Cells beside the symbol column of a table with no header, in reading order; empty for a list or a CSV with a header. */
+  ignored: string[];
+  /**
+   * The symbols are a list's entries, each a line or a cell of a list split
+   * by semicolons or commas, and are read as typed entries are
+   * (`readNameEntries`): one with spaces is a company's name (`Altria
+   * Group`), or symbols written on one line (`AAPL MSFT`).
+   */
+  entries?: true;
+}
+
+/**
+ * The symbols in a file or piped text, in order. Each line is split by its
+ * own separator (`readRecords`): a tab, a semicolon, a comma that is not a
+ * decimal comma, or spaces. A figure (`2.582,52`, `1,899.21`, `12%`) is never
+ * a symbol, and a bare whole number beside a symbol is a value: such a cell
+ * makes the list a table. A spreadsheet export reads from the column its
+ * header names (Symbol, Ticker, Code), else from its Name or Company column,
+ * as `entries`. Without a header, every cell is a symbol unless some column
+ * after the first holds a name, a price or a weight: that table is read by
+ * its first column, and the cells beside it are returned as `ignored` so the
+ * command can name them. A list split by commas, spaces or newlines gives
+ * every entry, even when a line of it is ragged or carries a stray separator
+ * (`"BIMAS ,"`); a cell that names nothing (`N/A`, `$$$`) does not make it a
+ * table, and is refused by the lookup. A list of lines gives each line whole,
+ * and a list of names split by semicolons or commas (one line, or one name a
+ * line) each cell, as `entries`: a line with spaces is a company's name
+ * (`Altria Group`) or symbols on one line, which reading the entries tells
+ * apart. Names beside other text (`Apple Inc,Technology`) are a table read by
+ * its first column, its names as `entries`. A byte order mark, Windows line
+ * ends, blank lines and lines starting with # or // are ignored.
+ */
+export function parseSymbolText(text: string): SymbolText {
+  const normalized = text.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  const { records, delimited } = readRecords(normalized);
+  if (records.length === 0) return { symbols: [], ignored: [] };
+  const header = records[0]!.map(headerKey);
+  const exact = header.findIndex((cell) => SYMBOL_HEADERS.has(cell));
+  const column = exact >= 0 ? exact : header.findIndex((cell) => cell.includes("symbol") || cell.includes("ticker"));
+  if (column >= 0) return { symbols: records.slice(1).map((cells) => cells[column] ?? "").filter(Boolean), ignored: [] };
+  // Without one, a delimited export's Name or Company column holds the companies, read as typed names are.
+  const nameColumn = delimited ? header.findIndex((cell) => NAME_HEADERS.has(cell)) : -1;
+  if (nameColumn >= 0) return { symbols: records.slice(1).map((cells) => cells[nameColumn] ?? "").filter(Boolean), ignored: [], entries: true };
+  // A separator or quote mark stuck to a cell is dropped (and named) when it is read, so it does not make the list a table.
+  const cleaned = records.map((cells) => cells.map((cell) => stripStrayEdges(cell).text));
+  const figures = cleaned.some((cells) => cells.some((cell, index) => index > 0 && isFigure(cell)));
+  // Lines split by spaces alone are entries, unless figures sit beside the symbols.
+  if (!delimited && !figures) return { symbols: records.map((cells) => cells.join(" ")), ignored: [], entries: true };
+  const grid = cleaned.every((cells) => cells.every((cell, index) => (
+    !cell || isJunkCell(cell) || (looksLikeSymbol(cell) && (index === 0 || !isFigure(cell)))
+  )));
+  if (grid) return { symbols: records.flat().filter(Boolean), ignored: [] };
+  // Names split by semicolons or commas, with no figures: one pasted line, or one name a line with a separator left
+  // on it, is a list. A name beside a sector or any other text is a table, read by its first column below.
+  const names = cleaned.some((cells) => /\s/.test(cells[0] ?? ""));
+  if (!figures && (records.length === 1 || (names && cleaned.every((cells) => cells.filter(Boolean).length <= 1)))) {
+    return { symbols: records.flat().filter(Boolean), ignored: [], entries: true };
+  }
+  return {
+    symbols: records.map((cells) => cells[0] ?? "").filter(Boolean),
+    ignored: records.flatMap((cells) => cells.slice(1)).filter(Boolean),
+    // A first column of names (Apple Inc) is read as typed names are.
+    ...names ? { entries: true as const } : {},
+  };
+}
+
+/** Cells named in a note, split by semicolons when one of them has a comma of its own (`2.582,52; 1.899,21`). */
+function listCells(cells: readonly string[]): string {
+  const named = cells.slice(0, IGNORED_PREVIEW);
+  const more = cells.length - IGNORED_PREVIEW;
+  return `${named.join(named.some((cell) => cell.includes(",")) ? "; " : ", ")}${more > 0 ? ` and ${more} more` : ""}`;
+}
+
+/** "the cell", "the 3 number cells": number when every one is a figure. */
+function cellsNoun(cells: readonly string[]): string {
+  const kind = cells.every(isFigure) ? "number cell" : "cell";
+  return cells.length === 1 ? `the ${kind}` : `the ${cells.length} ${kind}s`;
+}
+
+/**
+ * The note a table read by its first column gets, naming what was left out:
+ * `Read the first column as symbols; ignored the 4 cells beside it: Apple
+ * Inc., 336.64, Microsoft, 535.07.` Long tables name the first few and count
+ * the rest. Null when nothing was ignored.
+ */
+function ignoredCellsNote(ignored: readonly string[]): string | null {
+  if (ignored.length === 0) return null;
+  return `Read the first column as symbols; ignored ${cellsNoun(ignored)} beside it: ${listCells(ignored)}.`;
+}
+
+/**
+ * The one note for the numbers read where a symbol goes, typed beside a
+ * symbol (`ED 2.582,52`) or on a line of their own: `Ignored 3 numbers, not
+ * symbols: 2.582,52; 1.899,21; 3.594,10.`
+ */
+function ignoredNumbersNote(numbers: readonly string[]): string | null {
+  if (numbers.length === 0) return null;
+  return numbers.length === 1
+    ? `Ignored ${numbers[0]}, a number, not a symbol.`
+    : `Ignored ${numbers.length} numbers, not symbols: ${listCells(numbers)}.`;
+}
+
+/**
+ * The entries of one line of what was typed, with the figures beside its
+ * symbols moved to `beside`: a number (`2.582,52`) on a line that has a
+ * symbol, and a bare whole number after a symbol when only figures follow it
+ * (`ED 2582`, `AAPL 150`). A bare whole number among symbols, or alone, is a
+ * code (`amd 2222 pltr`, `7203`).
+ */
+function withoutFigures(words: readonly string[], beside: string[]): string[] {
+  const symbolAt = words.findIndex((word) => !isFigure(word) && !isJunkCell(word));
+  if (symbolAt < 0) return [...words];
+  const row = symbolAt === 0 && words.length > 1 && words.slice(1).every(isFigure);
+  const value = (word: string, index: number) => index !== symbolAt && (isNumberCell(word) || (row && isFigure(word)));
+  beside.push(...words.filter(value));
+  return words.filter((word, index) => !value(word, index));
+}
+
+/**
+ * The entries of typed arguments (`splitSymbolArgs`), without the figures
+ * beside their symbols (`withoutFigures`), which go to `beside`. An entry with
+ * spaces (`ED 2.582,52` between semicolons) loses its figures the same way.
+ */
+function typedEntries(args: readonly string[], beside: string[]): string[] {
+  // An argument of words is one entry, read as a list's line is: `"Beyond Meat"` is a company, `"GME AMC"` two symbols.
+  return args.flatMap((arg) => splitSymbolArgLines(arg, { phrases: true }).flatMap((line) => withoutFigures(line, beside)
+    .map((entry) => withoutFigures(entry.split(" "), beside).join(" "))
+    .filter(Boolean)));
+}
+
+/** Whether standard input is a pipe or a file rather than a terminal, so a command may read its list from it. */
+function stdinIsPiped(): boolean {
+  try {
+    const stats = fstatSync(0);
+    return stats.isFIFO() || stats.isFile();
+  } catch {
+    // Intentional ignore: An unavailable standard input cannot supply an optional symbol list.
+    return false;
+  }
+}
+
+export interface SymbolListSource {
+  /** The arguments after the list name, symbols and `-` for standard input. */
+  args: readonly string[];
+  /** `--file <path>`. */
+  file?: string;
+  /** Reads standard input; injected so tests never block on it. */
+  readStdin?: () => Promise<string>;
+  /** Whether standard input was piped in, so a command given no symbols reads it. */
+  stdinPiped?: boolean;
+  /**
+   * Reads the typed entries (`splitSymbolArgs`) as symbols, such as
+   * `readNameEntries`, which keeps a company's name whole, and then the
+   * entries of each list a file or standard input holds. Called first for
+   * what was typed, even when that is nothing. Without it every entry is its
+   * words, each a symbol.
+   */
+  readEntries?: (entries: string[]) => Promise<string[]>;
+}
+
+export class SymbolListError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SymbolListError";
+  }
+}
+
+/**
+ * The symbols a command was given: as arguments, from `--file`, and from
+ * standard input when an argument is `-` or nothing else was given and input
+ * is piped in. This is the one reader of `watchlist add`, `portfolio add`,
+ * `quote`, `compare` and the command bar's pasted list. Repeats are dropped. A
+ * separator stuck to a symbol in a file, or left on the end of what was typed
+ * (`UPST;`), is dropped with the quote marks around it, and the cells beside
+ * the symbols of a table read by its first column, or the figures typed beside
+ * a symbol, are left out; `notes` names each so the command can say so, the
+ * numbers in one line: a number (`2.582,52`, `1,899.21`, `12%`) is never a
+ * symbol, beside one or on its own. An entry that names nothing (`N/A`, `$$$`,
+ * `--`) stays in `symbols`, for the lookup to refuse without asking anything
+ * (`notASymbolError`) and the command to name.
+ */
+export async function readSymbolList(source: SymbolListSource): Promise<{ symbols: string[]; repeated: number; notes: string[] }> {
+  const readStdin = source.readStdin ?? (() => Bun.stdin.text());
+  const wantsStdin = source.args.includes("-") || source.file === "-";
+  const typedArgs = source.args.filter((arg) => arg !== "-");
+  const figures: string[] = [];
+  const entries = typedEntries(typedArgs, figures);
+  const readEntries = (read: string[]) => source.readEntries ? source.readEntries(read) : Promise.resolve(splitSymbolWords(read));
+  const typed = source.readEntries ? await source.readEntries(entries) : splitSymbolWords(entries);
+  const collected = [...typed];
+  // A separator left on the end of what was typed: `UPST;`, or a list that ends in a comma.
+  const strays = new Set<string>(stripStrayEdges(typedArgs.join(" ")).notes);
+  const ignored: string[] = [];
+  const addCells = async ({ symbols, ignored: beside, entries: whole }: SymbolText) => {
+    const cells = symbols.map((cell) => {
+      const cleaned = stripStrayEdges(cell);
+      cleaned.notes.forEach((note) => strays.add(note));
+      return cleaned.text;
+    }).filter(Boolean);
+    // A list's lines and names are read as typed entries are: `Altria Group` stays one company.
+    collected.push(...whole ? await readEntries(cells) : cells);
+    ignored.push(...beside);
+  };
+  if (source.file != null && source.file !== "-") {
+    if (!source.file.trim() || source.file.startsWith("--")) throw new SymbolListError("--file needs a path, such as --file symbols.csv.");
+    let text: string;
+    try {
+      text = await readFile(source.file, "utf-8");
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      throw new SymbolListError(code === "ENOENT" ? `No file at ${source.file}.` : `Could not read ${source.file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    await addCells(parseSymbolText(foldTypedText(text)));
+  }
+  if (wantsStdin || (typed.length === 0 && source.file == null && (source.stdinPiped ?? stdinIsPiped()))) {
+    await addCells(parseSymbolText(foldTypedText(await readStdin())));
+  }
+  // A number where a symbol goes (a line of prices, a typed 1.899) is left out with those typed beside a symbol.
+  const numbers = [...figures, ...collected.filter(isNumberCell)];
+  const notes = [ignoredCellsNote(ignored), ignoredNumbersNote(numbers)].filter((note): note is string => !!note);
+  return { ...uniqueSymbols(collected.filter((symbol) => !isNumberCell(symbol))), notes: [...strays, ...notes] };
+}