@chemzqm/neovim/lib/api/Buffer.d.ts

NodeJS client API for vim9 and neovim

import { Range, VimValue } from '../types';
import { BaseApi } from './Base';
import { Disposable, KeymapOption } from './types';
export interface BufferSetLines {
    start?: number;
    end?: number;
    strictIndexing?: boolean;
}
export interface BufferHighlight {
    hlGroup?: string;
    line?: number;
    colStart?: number;
    colEnd?: number;
    srcId?: number;
}
export interface VirtualTextOption {
    /**
     * Used on vim9 and neovim >= 0.10.0.
     */
    col?: number;
    /**
     * highlight mode
     */
    hl_mode?: 'combine' | 'replace' | 'blend';
    /**
     * nvim and vim.
     */
    text_align?: 'after' | 'right' | 'below' | 'above';
    /**
     * neovim only, right_gravity of nvim_buf_set_extmark.
     */
    right_gravity?: boolean;
    /**
     * neovim only
     */
    virt_text_win_col?: number;
    /**
     * vim9 only
     */
    text_wrap?: 'wrap' | 'truncate';
    /**
     * Add line indent when text_align is below or above.
     */
    indent?: boolean;
}
export interface ExtmarkOptions {
    id?: number;
    end_line?: number;
    end_col?: number;
    hl_group?: string;
    hl_mode?: 'replace' | 'combine' | 'blend';
    hl_eol?: boolean;
    virt_text?: [string, string | string[]][];
    virt_text_pos?: 'eol' | 'overlay' | 'right_align' | 'inline';
    virt_text_win_col?: number;
    virt_text_hide?: boolean;
    virt_lines?: [string, string | string[]][][];
    virt_lines_above?: boolean;
    virt_lines_leftcol?: boolean;
    right_gravity?: boolean;
    end_right_gravity?: boolean;
    priority?: number;
    url?: string;
}
export interface ExtmarkDetails {
    end_col: number;
    end_row: number;
    priority: number;
    hl_group?: string;
    virt_text?: [string, string][];
    virt_lines?: [string, string | string][][];
}
export interface BufferClearHighlight {
    srcId?: number;
    lineStart?: number;
    lineEnd?: number;
}
export interface SignPlaceOption {
    id?: number;
    group?: string;
    name: string;
    lnum: number;
    priority?: number;
}
export interface SignUnplaceOption {
    group?: string;
    id?: number;
}
export interface SignPlacedOption {
    group?: string;
    id?: number;
    lnum?: number;
}
export interface SignItem {
    group: string;
    id: number;
    lnum: number;
    name: string;
    priority: number;
}
export interface HighlightItem {
    hlGroup: string;
    /**
     * 0 based
     */
    lnum: number;
    /**
     * 0 based
     */
    colStart: number;
    /**
     * 0 based
     */
    colEnd: number;
    /**
     * See :h prop_type_add on vim8
     */
    combine?: boolean;
    start_incl?: boolean;
    end_incl?: boolean;
}
export interface HighlightConfig {
    /**
     * Clear namespace highlights first.
     */
    clear?: boolean;
    priority?: number;
    combine?: boolean;
    start_incl?: boolean;
    end_incl?: boolean;
}
export interface VimHighlightItem {
    hlGroup: string;
    /**
     * 0 based
     */
    lnum: number;
    /**
     * 0 based
     */
    colStart: number;
    /**
     * 0 based
     */
    colEnd: number;
    /**
     * Extmark id
     */
    id?: number;
}
export interface HighlightOption {
    start?: number;
    end?: number;
    priority?: number;
    changedtick?: number;
}
type Chunk = [string, string];
export declare class Buffer extends BaseApi {
    prefix: string;
    /**
     * Attach to buffer to listen to buffer events
     * @param sendBuffer Set to true if the initial notification should contain
     *        the whole buffer. If so, the first notification will be a
     *        `nvim_buf_lines_event`. Otherwise, the first notification will be
     *        a `nvim_buf_changedtick_event`
     */
    attach(sendBuffer?: boolean, options?: {}): Promise<boolean>;
    /**
     * Detach from buffer to stop listening to buffer events
     */
    detach(): Promise<boolean>;
    /** Retrieves a scoped option depending on type of `this` */
    getOption(name: string): Promise<VimValue>;
    /** Set scoped option */
    setOption(name: string, value: VimValue): Promise<void>;
    setOption(name: string, value: VimValue, isNotify: true): void;
    /**
     * Get the bufnr of Buffer
     */
    get id(): number;
    /** Total number of lines in buffer */
    get length(): Promise<number>;
    /** Get lines in buffer */
    get lines(): Promise<string[]>;
    /** Gets a changed tick of a buffer */
    get changedtick(): Promise<number>;
    get commands(): Promise<Object>;
    getCommands(options?: {}): Promise<Object>;
    /** Get specific lines of buffer */
    getLines({ start, end, strictIndexing }?: {
        start: number;
        end: number;
        strictIndexing: boolean;
    }): Promise<string[]>;
    /** Set lines of buffer given indices */
    setLines(lines: string | string[], opts?: BufferSetLines): Promise<void>;
    setLines(lines: string | string[], opts: BufferSetLines, notify: true): void;
    /**
     * Set virtual text for a line, works on nvim >= 0.5.0 and vim9
     *
     * @public
     * @param {number} src_id - Source group to use or 0 to use a new group, or -1
     * @param {number} line - Line to annotate with virtual text (zero-indexed)
     * @param {Chunk[]} chunks - List with [text, hl_group]
     * @param {{[index} opts
     * @returns {Promise<number>}
     */
    setVirtualText(src_id: number, line: number, chunks: Chunk[], opts?: VirtualTextOption): void;
    /**
     * Removes an ext mark by notification.
     *
     * @public
     * @param {number} ns_id - Namespace id
     * @param {number} id - Extmark id
     */
    deleteExtMark(ns_id: number, id: number): void;
    /**
     * Gets the position (0-indexed) of an extmark.
     *
     * @param {number} ns_id - Namespace id
     * @param {number} id - Extmark id
     * @param {Object} opts - Optional parameters.
     * @returns {Promise<[] | [number, number] | [number, number, ExtmarkDetails]>}
     */
    getExtMarkById(ns_id: number, id: number, opts?: {
        details?: boolean;
    }): Promise<[] | [number, number] | [number, number, ExtmarkDetails]>;
    /**
     * Gets extmarks in "traversal order" from a |charwise| region defined by
     * buffer positions (inclusive, 0-indexed |api-indexing|).
     *
     * Region can be given as (row,col) tuples, or valid extmark ids (whose
     * positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
     * respectively, thus the following are equivalent:
     *
     *     nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
     *     nvim_buf_get_extmarks(0, my_ns, [0,0], [-1,-1], {})
     *
     * @param {number} ns_id - Namespace id
     * @param {[number, number] | number} start
     * @param {[number, number] | number} end
     * @param {Object} opts
     * @returns {Promise<[number, number, number, ExtmarkDetails?][]>}
     */
    getExtMarks(ns_id: number, start: [number, number] | number, end: [number, number] | number, opts?: {
        details?: boolean;
        limit?: number;
    }): Promise<[number, number, number, ExtmarkDetails?][]>;
    /**
     * Creates or updates an extmark by notification, `:h nvim_buf_set_extmark`.
     *
     * @param {number} ns_id
     * @param {number} line
     * @param {number} col
     * @param {ExtmarkOptions} opts
     * @returns {void}
     */
    setExtMark(ns_id: number, line: number, col: number, opts?: ExtmarkOptions): void;
    /** Insert lines at `start` index */
    insert(lines: string[] | string, start: number): Promise<void>;
    /** Replace lines starting at `start` index */
    replace(_lines: string[] | string, start: number): Promise<void>;
    /** Remove lines at index */
    remove(start: number, end: number, strictIndexing?: boolean): Promise<void>;
    /** Append a string or list of lines to end of buffer */
    append(lines: string[] | string): Promise<void>;
    /** Get buffer name */
    get name(): Promise<string>;
    /** Set current buffer name */
    setName(value: string): Promise<void>;
    /** Is current buffer valid */
    get valid(): Promise<boolean>;
    /** Get mark position given mark name */
    mark(name: string): Promise<[number, number]>;
    /** Gets keymap */
    getKeymap(mode: string): Promise<object[]>;
    /**
     * Add buffer keymap by notification, replace keycodes for expr keymap enabled by default.
     */
    setKeymap(mode: string, lhs: string, rhs: string, opts?: KeymapOption): void;
    deleteKeymap(mode: string, lhs: string): void;
    /**
   * Checks if a buffer is valid and loaded. See |api-buffer| for
   * more info about unloaded buffers.
   */
    get loaded(): Promise<boolean>;
    /**
     * Returns the byte offset for a line.
     *
     * Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is
     * one byte. 'fileformat' and 'fileencoding' are ignored. The
     * line index just after the last line gives the total byte-count
     * of the buffer. A final EOL byte is counted if it would be
     * written, see 'eol'.
     *
     * Unlike |line2byte()|, throws error for out-of-bounds indexing.
     * Returns -1 for unloaded buffer.
     *
     * @return {Number} Integer byte offset, or -1 for unloaded buffer.
     */
    getOffset(index: number): Promise<number>;
    /**
      Adds a highlight to buffer.
  
      This can be used for plugins which dynamically generate
      highlights to a buffer (like a semantic highlighter or
      linter). The function adds a single highlight to a buffer.
      Unlike matchaddpos() highlights follow changes to line
      numbering (as lines are inserted/removed above the highlighted
      line), like signs and marks do.
  
      "src_id" is useful for batch deletion/updating of a set of
      highlights. When called with src_id = 0, an unique source id
      is generated and returned. Succesive calls can pass in it as
      "src_id" to add new highlights to the same source group. All
      highlights in the same group can then be cleared with
      nvim_buf_clear_namespace. If the highlight never will be
      manually deleted pass in -1 for "src_id".
  
      If "hl_group" is the empty string no highlight is added, but a
      new src_id is still returned. This is useful for an external
      plugin to synchrounously request an unique src_id at
      initialization, and later asynchronously add and clear
      highlights in response to buffer changes. */
    addHighlight({ hlGroup, line, colStart: _start, colEnd: _end, srcId: _srcId, }: BufferHighlight): Promise<number | null>;
    /**
     * Clear highlights of specified lins.
     *
     * @deprecated use clearNamespace() instead.
     */
    clearHighlight(args?: BufferClearHighlight): void;
    /**
     * Add highlight to ranges by notification.
     *
     * @param {string | number} srcId Unique key or namespace number.
     * @param {string} hlGroup Highlight group.
     * @param {Range[]} ranges List of highlight ranges
     */
    highlightRanges(srcId: string | number, hlGroup: string, ranges: Range[], option?: HighlightConfig): void;
    /**
     * Clear namespace by id or name.
     *
     * @param key Unique key or namespace number, use -1 for all namespaces
     * @param lineStart Start of line, 0 based, default to 0.
     * @param lineEnd End of line, 0 based, default to -1.
     */
    clearNamespace(key: number | string, lineStart?: number, lineEnd?: number): void;
    /**
     * Add sign to buffer by notification.
     *
     * @param {SignPlaceOption} sign
     * @returns {void}
     */
    placeSign(sign: SignPlaceOption): void;
    /**
     * Unplace signs by notification
     */
    unplaceSign(opts: SignUnplaceOption): void;
    /**
     * Get signs by group name or id and lnum.
     *
     * @param {SignPlacedOption} opts
     * @returns {Promise<SignItem[]>}
     */
    getSigns(opts: SignPlacedOption): Promise<SignItem[]>;
    /**
     * Get highlight items by name space (end inclusive).
     *
     * @param {string} ns Namespace key.
     * @param {number} start 0 based line number.
     * @param {number} end 0 based line number.
     * @returns {Promise<HighlightItem[]>}
     */
    getHighlights(ns: string | number, start?: number, end?: number): Promise<VimHighlightItem[]>;
    /**
     * Update highlight items by notification.
     *
     * @param {string | number} ns Namespace key or id.
     * @param {HighlightItem[]} highlights Highlight items.
     * @param {HighlightOption} opts Optional options.
     * @returns {void}
     */
    updateHighlights(ns: string, highlights: HighlightItem[], opts?: HighlightOption): void;
    /**
     * Listens to buffer for events
     */
    listen(eventName: string, cb: Function, disposables?: Disposable[]): void;
}
export {};