@ranchonyx/nanoparse/dist/BasicParser.d.ts

A super simple basic parser / tokenizer for easier processing of various configuration files

/**
 * Asserts that `target` is not `null` or `undefined`
 * @param target
 * @param info
 */
export declare function assertNotNull<T>(target: T | undefined | null, info?: string): asserts target is NonNullable<T>;
/**
 * Represents an {@link InputStream}'s internal 'cursor'
 */
export type InputStreamPosition = {
    line: number;
    col: number;
    pos: number;
};
/**
 * This class consumes and iterates over a piece of source text
 */
export declare class InputStream {
    private readonly input;
    END_OF_LINE: string;
    COMMENT_START: string;
    private streamPosition;
    private sourceColumn;
    private sourceLine;
    constructor(pStreamInput: string, pCommentStart?: string, pSourceEOL?: string);
    /**
     * Gets the next character
     */
    next(): string;
    /**
     * Looks up the next character
     */
    peek(): string;
    /**
     * Checks if we have reached the end of the source code
     */
    eof(): boolean;
    /**
     * Returns the current internal cursor position
     */
    getPosition(): InputStreamPosition;
}
/**
 * Represents a token as emitted by {@link TokenStream}s
 */
export type Token = {
    type: string;
    value: string;
    position: InputStreamPosition;
};
/**
 * Represents the union of a {@link Token} and `null`
 */
export type TokenOrNull = Token | null;
/**
 * Checks if `T` is exactly equal to {@link Token}
 */
export type IsExactlyToken<T> = T extends Token ? (Token extends T ? true : false) : false;
/**
 * Describes the signature of a function which transforms {@link Token}s into the type specified by `TransformTo`
 */
export type TokenTransformFunction<TransformTo> = (token: Token) => TransformTo;
/**
 * This class consumes an {@link InputStream} to generate {@link Token}s
 */
export declare class TokenStream {
    private input;
    private current;
    constructor(streamInput: InputStream);
    /**
     * Checks if `ch` is whitespace
     * @param ch The character produced by the internal {@link InputStream} to be checked
     */
    private is_whitespace;
    /**
     * Checks if `ch` is the start of an identifier
     * @param ch The character produced by the internal {@link InputStream} to be checked
     */
    private is_ident_start;
    /**
     * Checks if `ch` represents an identifier
     * @param ch The character produced by the internal {@link InputStream} to be checked
     */
    private is_ident;
    /**
     * Reads from its internal {@link InputStream} until `predicate` returns false
     * @param predicate A function, which the character produced by the internal {@link InputStream} is passed, which controls the reading of new characters
     */
    private read_while;
    /**
     * Reads an entire identifier from the internal {@link InputStream}
     */
    private read_ident;
    /**
     * Skips a comment, the start character of which is determined by the internal {@link InputStream}'s `COMMEND_START` property
     */
    private skip_comment;
    /**
     * Produce the next available {@link TokenOrNull} from the internal {@link InputStream}
     * @throws Error When unable to handle a character
     */
    private read_next;
    /**
     * Looks up the next token
     */
    private peek;
    /**
     * Checks if we have reached the end of the available tokens
     */
    eof(): boolean;
    /**
     * Gets the next token
     */
    next(): TokenOrNull;
}
/**
 * Represents non-generic options for a {@link BasicParser}
 * - If `lineTerminator` is left blank, it will be set to `\n`
 * - If `commentStart` is left blank, it will be set to `#`
 */
export type BasicParserOptions = {
    sourceText: string;
    lineTerminator?: string;
    commentStart?: string;
};
/**
 * Represents an optionally generic configuration for a {@link BasicParser}
 * - If *not* typed, this type is equal to {@link BasicParserOptions}
 * - if it *is* typed, this type will *require* a `forEachToken` function of type {@link TokenTransformFunction} which serves to transform the produces tokens into the desired format
 */
export type BasicParserConfig<TransformTo = Token> = IsExactlyToken<TransformTo> extends true ? BasicParserOptions : BasicParserOptions & {
    forEachToken: TokenTransformFunction<TransformTo>;
};
/**
 * This class consumes and wraps an {@link TokenStream}, providing methods for normal, safe and asynchronous parsing of a source text
 */
export default class BasicParser<TransformTo = Token> {
    private readonly inputStream;
    private readonly tokenStream;
    private readonly tokenTransformer?;
    private readonly hasTokenTransformer;
    private current;
    constructor(pTokenizerConfig: BasicParserConfig<TransformTo>);
    /**
     * Produces the next token
     * @private
     */
    private next;
    /**
     * Returns the current token
     */
    PeekRaw(): Token;
    /**
     * Returns the current token in its transformed state
     */
    PeekTransformed(): TransformTo;
    /**
     * Parses tokens iteratively
     */
    ParseNext(): TransformTo;
    HasNext(): boolean;
    /**
     * Parses the internal source text and returns an Array of {@link Token}s or, if this class was constructed with a type parameter, in an Array of that type.
     * @throws Error On invalid source text
     */
    Parse(): Array<TransformTo>;
    /**
     * Parses the internal source text and returns an Array of {@link Token}s or, if this class was constructed with a type parameter, in an Array of that type.
     * - If an exceptions was thrown during parsing, it returns an empty array
     * - Does not throw exceptions on invalid source text
     */
    TryParse(): Array<TransformTo> | [];
    /**
     * Asynchronously Parses the internal source text and returns a Promise of an Array of {@link Token}s or, if this class was constructed with a type parameter, an Array of that type.
     * @throws Error On invalid source text
     */
    ParseAsync(): Promise<Array<TransformTo>>;
    /**
     * Asynchronously Parses the internal source text and returns a Promise of an Array of {@link Token}s or, if this class was constructed with a type parameter, an Array of that type.
     * - If an exceptions was thrown during parsing, it returns an empty array
     * - Does not throw exceptions on invalid source text
     */
    TryParseAsync(): Promise<Array<TransformTo> | []>;
}