import { Writable } from 'stream';
import { Completer } from "./cmdbuf";
/**
 * One entry in the command line file list, like less's ifile.
 */
export interface FileEntry {
    path: string;
    /**
     * What to CALL this file, when its path is not the answer.
     *
     * A lesskey form that is not a file - a compiled one, or a content
     * variable - is materialized as a temp file so it can be paged and
     * edited, and the path that produces says nothing:
     * /var/folders/3z/b8wpqjgn.../T/lesskey-Ab12Cd/LESSKEY_CONTENT.
     * The prompt shows this instead, so the screen names the thing the
     * text came FROM. Everything that opens, reads or shells out still
     * uses path.
     */
    display?: string;
    /** Preloaded lines for non-file content, like stdin's "-". */
    lines: string[] | null;
    /** Byte size, from stat for real files. */
    size: number;
    /** False while a pipe's length reads as unknown, like ch_length()
     *  returning NULL_POSITION before ch has read to EOF. */
    sizeKnown: boolean;
    /** True once the entry opened successfully, like less's opened():
     *  a re-open skips the binary file confirmation. */
    everOpened?: boolean;
    /** True while a pipe is still delivering data, like less's ch layer
     *  before read() returns end-of-file. */
    streaming?: boolean;
    /** Early pipe data recycled away under memory pressure, like less's
     *  ch_addbuf failure reusing the oldest buffer: these lines and
     *  bytes are gone but still count in line numbers and offsets. */
    discardedLines?: number;
    discardedBytes?: number;
    /** Saved screen position, like ifile.c's store_pos/get_pos. */
    saved: {
        row: number;
        subRow: number;
    } | null;
    /** The $LESSOPEN replacement name, like ifile.c's altfilename. */
    alt?: string;
    /** A failed pipe preprocessor's message, reported at close like
     *  less's close_altfile (edit.c:288). */
    preprocError?: string;
    /** Where the "-" entry's spooled standard input lives. less keeps fd0
     *  open with CH_KEEPOPEN and buffers it in ch; the spool is our ch,
     *  and it makes the entry an ordinary growing file to everything
     *  downstream. */
    spoolPath?: string;
}
/**
 * The command line file list state.
 *
 * - `index` is -1 before any file is opened.
 * - `newFile` shows the filename prompt after opening, like prompt.c's
 *   new_file flag (`%n` in the default prompt).
 */
export declare const files: {
    list: FileEntry[];
    index: number;
    newFile: boolean;
};
interface SourceFileHooks {
    /** Undefined declines the file; null is an acquisition failure. */
    load(index: number): string[] | null | undefined;
    /** Completes a successful shared switch after files.index changes. */
    activate(index: number): void;
    /** Drops a remembered position, for a file that will not be back. */
    forget(filePath: string): void;
}
/** Registers the active seekable input with the shared file workflow. */
export declare function onSourceFiles(hooks: SourceFileHooks | null): void;
/** Finishes a source-backed switch after the common edit bookkeeping. */
export declare function activateSourceFile(index: number): void;
/**
 * Forgets where a file was left.
 *
 * The engine remembers a position per PATH so :n and :p come back to
 * it, which is right for a file list the user assembled and wrong for
 * one the pager put up on its own: a screen you quit out of should
 * open at the top next time, the way quitting help does.
 */
export declare function forgetSourceFile(filePath: string): void;
/**
 * `Examine: ` prompt state (`:e`, `^X^V`).
 */
export declare const examine: {
    pending: boolean;
    text: string;
};
/**
 * Remembers the file being left as the previous file, like less updating
 * old_ifile in edit_ifile.
 *
 * @param filePath - Path of the file being switched away from.
 */
export declare function setPreviousPath(filePath: string | null): void;
/** The `#` file, for a caller that has to put it back. */
export declare function getPreviousPath(): string | null;
/** How many examine entries exist, so a swap can trim its own back. */
export declare function examineHistoryLength(): number;
/** Drops examine entries added after a mark, like a file list that
 *  was only ever on screen to be looked at. */
export declare function trimExamineHistory(length: number): void;
/**
 * Starts a session over in-memory content, registered as the pseudo-file
 * `-` so `:e`/`:p` can navigate back to it, like less reading stdin.
 *
 * @param lines - The content to page.
 */
export declare function initContent(lines: string[]): void;
/**
 * Starts a session over a command line file list.
 *
 * @param paths - File paths to page.
 */
/** A file list from paths, with nothing opened yet. */
export declare function makeFileList(paths: string[]): FileEntry[];
export declare function initFiles(paths: string[]): void;
/**
 * The `"X" may be a binary file.  See it anyway?` confirmation state,
 * like less's edit query: loadFile raises `request`, and the caller
 * either answers synchronously (startup) or arms the `pending` prompt
 * answered with y/Y (runtime).
 */
export declare const binaryConfirm: {
    request: boolean;
    pending: boolean;
    path: string;
    proceed: (() => void) | null;
};
/**
 * True when a file's first 256 bytes look binary, like less's bin_file:
 * malformed UTF-8 and IS_BINARY_CHAR chars count, ANSI sequences skip
 * under -R, and more than 5 binary characters qualify.
 */
export declare function binFile(bytes: Buffer): boolean;
/**
 * Opens an entry the way a NON-terminal session needs it, like less
 * reaching cat_file through the same edit_ifile every session uses.
 *
 * $LESSOPEN applies with output on a pipe exactly as it does on a
 * screen (main.c:376 runs edit_first before the cat loop), but the
 * copy that follows is byte for byte - ch_forw_get, no line
 * processing - so a pipe preprocessor writes straight to `out` and
 * anything else hands back a path to stream. less's binary-file
 * question is gated on is_tty and never asked here.
 *
 * @param index - Entry index in the file list.
 * @param out - Where a pipe preprocessor's bytes go.
 * @returns A file left to stream, or null with a message set.
 */
export declare function openForCat(index: number, out: Writable): Promise<{
    path?: string;
} | null>;
/**
 * Reads a file entry's lines, reporting errors like less's edit.
 *
 * - A binary-looking file sets binaryConfirm.request instead of
 *   opening, unless -f, a re-open, or a non-tty session (edit.c).
 *
 * @param index - Entry index in the file list.
 * @returns The file's lines, or null with a message set on failure.
 */
export declare function loadFile(index: number): string[] | null;
/**
 * Runs $LESSCLOSE for an entry's $LESSOPEN product and forgets it,
 * like less's close_altfile when a file is left.
 */
export declare function closeAlt(entry: FileEntry | undefined): void;
/**
 * Saves the current screen position into the current file entry, like
 * less's store_pos when leaving a file.
 */
export declare function saveFilePosition(): void;
/**
 * Resolves the target of `:n`/`:p`, reporting like less when the list
 * runs out.
 *
 * @param delta - 1 for next, -1 for previous.
 * @param n - How many files to step.
 * @returns The target index, or null with a message set.
 */
export declare function stepFileTarget(delta: 1 | -1, n: number): number | null;
/**
 * Resolves the target of `:x`, reporting like less when out of range.
 *
 * @param n - 1-based file number.
 * @returns The target index, or null with a message set.
 */
export declare function indexFileTarget(n: number): number | null;
/**
 * Adds an opened file to the examine history, quoted like edit_ifile's
 * cmd_addhist call: consecutive duplicates are skipped and
 * --no-histdups drops older occurrences anywhere.
 *
 * @param filePath - Path of the file just opened.
 */
export declare function addExamineHistory(filePath: string): void;
/**
 * Opens the `Examine: ` prompt over the shared command buffer.
 */
export declare function startExamine(): void;
/**
 * Handles a key at the `Examine: ` prompt.
 *
 * - Backspacing past the start aborts, like less's CF_QUIT_ON_ERASE.
 * - TAB / ^O cycle filename completions of the last word, ^L expands it
 *   to all matches, like cmdbuf.c's cmd_complete.
 * - Up/Down recall previously opened file names starting with the
 *   typed text, like cmdbuf.c's cmd_updown; editing the text starts
 *   a fresh prefix match.
 *
 * @param key - Raw key input.
 * @returns `run` to open the entered path, `pending` or `cancel`.
 */
export declare function examineKey(key: string): 'run' | 'pending' | 'cancel';
/**
 * Expands an `Examine: ` answer into filenames, like less's edit_list
 * pipeline: `%`/`#` substitution (fexpand), whitespace splitting with
 * quotes, `~`/`$VAR` expansion and globbing (lglob via the shell).
 *
 * @param text - The raw prompt answer.
 * @returns Expanded filenames, in order.
 */
export declare function expandExamineList(text: string): string[];
/**
 * Substitutes `%` with the current filename and `#` with the previous
 * one, doubling to escape, like filename.c's fexpand.
 */
export declare function fexpand(text: string): string;
/**
 * Expands a leading `~` and `$VAR`/`${VAR}` references, as the shell
 * would during less's glob step. Unset variables expand to nothing.
 */
export declare function expandHomeEnv(word: string): string;
/**
 * Expands a filename pattern, like lglob.
 *
 * - A pattern matching nothing is returned as-is, like less trying to
 *   open the raw filename when the glob does not expand.
 *
 * @param pattern - The pattern to expand.
 */
export declare function glob(pattern: string): string[];
/**
 * Cycles the last word through its filename completions (TAB / ^O),
 * like cmd_complete: through the matches, then back to the original.
 *
 * @param direction - 1 to cycle forward, -1 backward.
 */
/** Filename completion for any prompt, like cmd_complete. */
export declare const filenameComplete: Completer;
/**
 * Builds the new-file prompt, like the `%f (file %i of %m)` part of
 * less's default prompt. The stdin pseudo-file shows no name.
 */
export declare function fileTitle(): string;
/**
 * Returns the path shown by the `(END) - Next: x` marker, or an empty
 * string when there is no next file.
 */
export declare function nextFileName(): string;
/**
 * Reports the current file name and position (`=`, `^G`, `:f`) by
 * expanding less's e_proto (changeable with -P=).
 *
 * @param content - Displayed content lines.
 */
export declare function fileInfo(content: string[]): void;
/**
 * Returns the last content row displayed on screen.
 *
 * @param content - Displayed content lines.
 */
export declare function bottomRow(content: string[]): number;
/**
 * Returns the byte offset of the start of a content row, counting one
 * newline per line.
 *
 * @param content - Content lines.
 * @param row - Row whose starting offset to compute.
 */
export declare function byteOffset(content: string[], row: number): number;
/**
 * True when the current file's length is known, like less's
 * ch_length() != NULL_POSITION: displaying the last line of a pipe
 * is not enough — the length arrives only when a read past the end
 * returns EOI (revealPipeEnd, or revealSize for explicit scans).
 */
export declare function sizeIsKnown(): boolean;
/**
 * A forward read past the end of a completed pipe returns EOI and
 * teaches the length, like less's ch_forw_get at end-of-input; a pipe
 * still delivering has no end to return yet.
 */
export declare function revealPipeEnd(): void;
/**
 * less reads a pipe-form $LESSOPEN alt to EOI when its content ends
 * within the first screen: the length is learned at the first paint
 * and the prompt shows (END), like eof_displayed.
 */
export declare function revealAltEnd(content: string[]): void;
/**
 * Learns the current file's size now, like less's scan_eof: --file-size
 * turning on, or a forward search scanning to the end of a pipe.
 */
export declare function revealSize(): void;
/**
 * The bottom line state while a pipe drains for G/%: less's G reads
 * with a blank command line, while % shows ierror's interruptible
 * "Determining length of file" note.
 */
export declare const pipeDraining: {
    active: boolean;
    note: string;
    cancelMessage: string;
};
/**
 * A forward move blocked reading a live pipe, like less's forw loop
 * waiting in forw_line: the display rows still owed, and whether any
 * line has painted yet (forw's nlines, deciding the eof_bell).
 */
export declare const pendingScroll: {
    rows: number;
    moved: boolean;
};
/** Lines recycled off the front of a streaming pipe (0 otherwise). */
export declare function lineBase(): number;
/** Bytes recycled off the front of a streaming pipe (0 otherwise). */
export declare function byteBase(): number;
/**
 * Integer percentage, rounded half to even like less's percentage().
 */
export declare function percentage(num: number, den: number): number;
/**
 * Renders a file open error like less's errno messages.
 */
export declare function errorText(error: unknown): string;
export {};