redac---n 0.0.0-stage → 0.0.2

package/dist/shell.d.ts

@@ -0,0 +1,127 @@
+export interface ShellWord {
+    /** The word with its quotes and escapes removed. */
+    text: string;
+    /** Where it was written: its start and end, and what is there (offset added). */
+    start: number;
+    end: number;
+    raw: string;
+    /** Whether any of it was quoted. */
+    quoted: boolean;
+    /** Whether its last part sat in single quotes (`'…'`, `$'…'`), where a shell expands nothing: `'$mIWy…'` is a literal. */
+    literalEnd: boolean;
+    /** Where each character of `text` was written (offset added): a value's span is read off it, never searched for. */
+    map: number[];
+    /** Where each character's source ends (offset added): an escape, `\x63` in `$'…'`, is several characters of the line. */
+    ends: number[];
+    /** Where the commands its substitutions run are written (offset added): `$(…)`, backticks, `<(…)`, `>(…)`. */
+    substitutions: {
+        start: number;
+        end: number;
+    }[];
+}
+export interface ShellRedirect {
+    /** The operator, without its file descriptor: `>`, `>>`, `>|`, `&>`, `&>>`, `<`, `<>`, `>&`, `<&`, `<<`, `<<-`, `<<<`. */
+    op: string;
+    /** The file descriptor written before it, if one was: `2` of `2>/dev/null`. */
+    fd?: number;
+    /** Its target: a file, a descriptor (`2>&1`'s `1`), a heredoc's delimiter, a here-string. */
+    target?: ShellWord;
+    /** Where the redirection is written, its target included (offset added). */
+    start: number;
+    end: number;
+}
+export interface Heredoc {
+    /** The delimiter, unquoted, and whether it was quoted (`<<'EOF'`, `<<\EOF`: the body isn't expanded). */
+    delimiter: string;
+    quoted: boolean;
+    /** `<<-`: the body's and the terminator's leading tabs are stripped. */
+    strip: boolean;
+    /** The body: the lines after the command's line, up to the delimiter's line, or the end (offset added). */
+    start: number;
+    end: number;
+    terminated: boolean;
+}
+/** A compound command around simple ones: its redirections and the operator after it apply to all of them. */
+export interface ShellGroup {
+    kind: string;
+    redirects: ShellRedirect[];
+}
+type ShellOperator = "|" | "|&" | "||" | "&&" | ";" | "&" | "\n" | "";
+export interface ShellCommand {
+    /** The command as written, and where it starts and ends (offset added). */
+    text: string;
+    start: number;
+    end: number;
+    /** Its words, redirections aside. */
+    words: ShellWord[];
+    redirects: ShellRedirect[];
+    heredocs: Heredoc[];
+    /** The groups it is inside, innermost first. */
+    groups: ShellGroup[];
+    /** The operator after it, or after the group it ends: `|` and `|&` pipe its output into the next command. */
+    then: ShellOperator;
+}
+/**
+ * Where each short line of a text starts, by its content (and by its content without leading tabs): a heredoc's
+ * terminator is then a lookup, so many heredoc lines in a text cost each body once.
+ */
+export declare class LineIndex {
+    private readonly exact;
+    private readonly stripped;
+    constructor(text: string);
+    /** The first line at or after `from` that is `line` (with `strip`, after its leading tabs), or -1. */
+    next(line: string, strip: boolean, from: number): number;
+}
+/**
+ * The commands of a command line (or several: a line break ends a command), read from `at` to the end of `text`. With
+ * `oneLine`, through the logical line at `at` (continued by `\`-newlines, and by a quote that closes within a few lines)
+ * and its heredocs' bodies, as out of other text. With `backslash` false a backslash is a character like any other, as
+ * on Windows (`.\.env`, `\\srv\share`). A `lines` index of `text` finds heredocs' terminators by lookup.
+ */
+export declare function shellCommands(text: string, offset?: number, { backslash, oneLine, at, lines, }?: {
+    backslash?: boolean;
+    oneLine?: boolean;
+    at?: number;
+    lines?: LineIndex;
+}): ShellCommand[];
+/** The shell word written at `at`, read to its line's end at most: `'it'\''s'` is one word, `it's`. */
+export declare function shellWordAt(text: string, at: number): ShellWord;
+/** The words of a command line, redirections aside (see shellCommands). */
+export declare function shellWords(command: string, offset?: number, { backslash }?: {
+    backslash?: boolean | undefined;
+}): ShellWord[];
+/** A command's redirections and those of the groups it is inside. */
+export declare function allRedirects(c: ShellCommand): ShellRedirect[];
+/**
+ * Whether a redirection sends the command's standard output to a file: `>`, `>>`, `>|`, `&>`, `&>>`, and `>&` onto a
+ * file (`>& out`; `>&2` and `2>&1` copy a descriptor), with no descriptor written before it or standard output's
+ * (`1> out`, `1>& out`; `2> out` sends another's).
+ */
+export declare function redirectsStdout(r: ShellRedirect): boolean;
+/**
+ * Where `text.slice(from)` of a word was written: the characters themselves when they were written together, or,
+ * when quotes or escapes sit among them (`'Xk9'"mQ2"`, `'a'\''b'`, `a\ b`), the whole stretch with the quotes around it,
+ * so what replaces it leaves the line's quoting whole.
+ */
+export declare function wordSpan(word: ShellWord, from?: number): {
+    start: number;
+    end: number;
+};
+/** The command line an argument vector stands for, each word quoted as a shell needs it: `["bash", "-lc", "cat .env"]` → `bash -lc 'cat .env'`. */
+export declare function shellLine(argv: string[]): string;
+/**
+ * A terminal prompt at the start of a line, before a command: a shell's `$ `, `user@host:~$ `, PowerShell's
+ * `PS C:\> `, a notebook's `In [3]: !` or a cell's bare `!` before a command. Group 1 is the command.
+ */
+export declare const PROMPT: RegExp;
+/** Whether a word names a wrapper, a command that runs the command after it. */
+export declare function isWrapper(word: string): boolean;
+/** A program's name without its directory and Windows' `.exe`: `/usr/bin/grep` → `grep`, `.\\steamcmd.exe` → `steamcmd`. */
+export declare function programName(word: ShellWord | undefined): string;
+/**
+ * A simple command's words from the program it runs: past assignments (`FOO=1`), reserved words (`!`, `then`, `do`)
+ * and wrappers with their options and operands (`sudo -iu app`, `env -i`, `timeout 5`, `nice -n 10`, `xargs -I{}`).
+ * A wrapper that runs nothing (`env -0`, `sudo -l`) is the program itself.
+ */
+export declare function simpleCommand(words: ShellWord[]): ShellWord[];
+export {};