@microsoft/api-extractor/lib/generators/Span.d.ts

Validate, document, and review the exported API for a TypeScript library

import * as ts from 'typescript';
/**
 * Callback for Span.modify()
 */
export declare type SpanModifyCallback = (span: Span, previousSpan: Span | undefined, parentSpan: Span | undefined) => void;
/**
 * Specifies various transformations that will be performed by Span.getModifiedText().
 */
export declare class SpanModification {
    skipChildren: boolean;
    skipSeparatorAfter: boolean;
    private readonly span;
    private _prefix;
    private _suffix;
    constructor(span: Span);
    /**
     * Allows the Span.prefix text to be changed.
     */
    prefix: string;
    /**
     * Allows the Span.suffix text to be changed.
     */
    suffix: string;
    /**
     * Reverts any modifications made to this object.
     */
    reset(): void;
    /**
     * Effectively deletes the Span from the tree, by skipping its children, skipping its separator,
     * and setting its prefix/suffix to the empty string.
     */
    skipAll(): void;
}
/**
 * The Span class provides a simple way to rewrite TypeScript source files
 * based on simple syntax transformations, i.e. without having to process deeper aspects
 * of the underlying grammar.  An example transformation might be deleting JSDoc comments
 * from a source file.
 *
 * @remarks
 * Technically, TypeScript's abstract syntax tree (AST) is represented using Node objects.
 * The Node text ignores its surrounding whitespace, and does not have an ordering guarantee.
 * For example, a JSDocComment node can be a child of a FunctionDeclaration node, even though
 * the actual comment precedes the function in the input stream.
 *
 * The Span class is a wrapper for a single Node, that provides access to every character
 * in the input stream, such that Span.getText() will exactly reproduce the corresponding
 * full Node.getText() output.
 *
 * A Span is comprised of these parts, which appear in sequential order:
 * - A prefix
 * - A collection of child spans
 * - A suffix
 * - A separator (e.g. whitespace between this span and the next item in the tree)
 *
 * These parts can be modified via Span.modification.  The modification is applied by
 * calling Span.getModifiedText().
 */
export declare class Span {
    readonly node: ts.Node;
    readonly startIndex: number;
    readonly endIndex: number;
    separatorStartIndex: number;
    separatorEndIndex: number;
    readonly children: Span[];
    readonly modification: SpanModification;
    private static _modifyHelper(callback, spans, parentSpan);
    constructor(node: ts.Node);
    readonly kind: ts.SyntaxKind;
    /**
     * The text associated with the underlying Node, up to its first child.
     */
    readonly prefix: string;
    /**
     * The text associated with the underlying Node, after its last child.
     * If there are no children, this is always an empty string.
     */
    readonly suffix: string;
    /**
     * Whitespace that appeared after this node, and before the "next" node in the tree.
     * Here we mean "next" according to an inorder traversal, not necessarily a sibling.
     */
    readonly separator: string;
    /**
     * Returns the separator of this Span, or else recursively calls getLastInnerSeparator()
     * on the last child.
     */
    getLastInnerSeparator(): string;
    /**
     * Recursively invokes the callback on this Span and all its children.  The callback
     * can make changes to Span.modification for each node.  If SpanModification.skipChildren
     * is true, those children will not be processed.
     */
    modify(callback: SpanModifyCallback): void;
    /**
     * Returns the original unmodified text represented by this Span.
     */
    getText(): string;
    /**
     * Returns the text represented by this Span, after applying all requested modifications.
     */
    getModifiedText(): string;
    /**
     * Returns a diagnostic dump of the tree, showing the prefix/suffix/separator for
     * each node.
     */
    getDump(indent?: string): string;
    private _getTrimmed(text);
    private _getSubstring(startIndex, endIndex);
}