antlr-ng/dist/src/codegen/GeneratorBase.d.ts

Next generation ANTLR Tool

import type { CodeGenerator } from "./CodeGenerator.js";
import type { CodePoint, Lines } from "./ITargetGenerator.js";
/** Flags used when rendering a collection. */
export interface IRenderCollectionOptions {
    /**
     * The maximum number of characters per line. If not given, everything is rendered in a single line.
     * Don't use this with line breaks in the separator or the result will be unpredictable.
     */
    wrap?: number;
    /** The indentation level for the output. */
    indent?: number;
    /** The string rendered between elements. If not set then ", " is used. */
    separator?: string;
    /** The quote character(s) to use for wrapping each element. */
    quote?: string;
    /** The string to use for the final shape of the elements. */
    template?: string;
}
/**
 * Base class for all target generators. It provides some common functionality.
 * The actual code generation is done in the subclasses.
 */
export declare abstract class GeneratorBase {
    /**
     * For pure strings of Unicode char, how can we display it in the target language as a literal. Useful for dumping
     * predicates and such that may refer to chars that need to be escaped when represented as strings.
     *
     * @returns The default map with the most common escape sequences. Subclasses can override this method to provide
     *          additional or different escape sequences.
     */
    static readonly defaultCharValueEscape: Map<number, string>;
    /**
     * Returns the default escape map for the target language. This is used to escape characters in strings.
     * Subclasses can override this method to provide additional or different escape sequences.
     *
     * @returns The default escape map for the target language.
     */
    get charValueEscapeMap(): Map<CodePoint, string>;
    /**
     * Given a random string of unicode chars, return a new string with optionally appropriate quote characters for
     * target language and possibly with some escaped characters. For example, if the incoming string has actual
     * newline characters, the output of this method would convert them to the two char sequence \n for Java, C,
     * C++, ... The new string has double-quotes around it as well. Example string in memory:
     *
     * ```
     * a"[newlineChar]b'c[carriageReturnChar]d[tab]e\f
     * ```
     * would be converted to the valid string:
     * ```
     * "a\"\nb'c\rd\te\\f"
     * ```
     * or
     * ```
     * a\"\nb'c\rd\te\\f
     * ```
     * depending on the quoted arg.
     *
     * @param s The string to convert.
     * @param quoted If true, the string is quoted. If false, it is not.
     *
     * @returns The converted string.
     */
    getTargetStringLiteralFromString(s: string, quoted?: boolean): string;
    /**
     * Converts from an antlr-ng string literal found in a grammar file to an equivalent string literal in the target
     * language.
     *
     * For Java, this is the translation `'a\n"'` -> `"a\n\""`. Expect single quotes around the incoming literal.
     * Just flip the quotes and replace double quotes with `\"`.
     *
     * Note that we have decided to allow people to use '\"' without penalty, so we must build the target string in
     * a loop as {@link String.replaceAll} cannot handle both `\"` and `"` without a lot of messing around.
     *
     * @param generator The code generator instance.
     * @param literal The string literal to convert.
     * @param addQuotes If true, the string is quoted. If false, it is not.
     * @param escapeSpecial If true, escape special characters.
     *
     * @returns The converted string.
     */
    getTargetStringLiteralFromANTLRStringLiteral(generator: CodeGenerator, literal: string, addQuotes: boolean, escapeSpecial?: boolean): string;
    /**
     * Generates a comma separated list of the elements in the given list. The elements are converted to strings
     * using the `String` constructor. The list is formatted with a maximum of `wrap` elements per line.
     * The list is split into multiple lines if it exceeds the specified wrap length.
     *
     * @param list The list of entries to be formatted. We are using string coercion here, so make sure any
     *             non-primitive type is rendered to a string, before calling this method.
     * @param options The options for formatting the list.
     *
     * @returns A list of strings, each representing a line of the formatted list.
     */
    renderList<T>(list: Iterable<T>, options: IRenderCollectionOptions): Lines;
    /**
     * Takes a list of lines and formats them with the specified indentation. It filters out undefined
     * lines, and adds the specified indentation to each line.
     *
     * @param lines The lines to format.
     * @param indentation The number of spaces to use for indentation.
     *
     * @returns The formatted lines.
     */
    formatLines(lines: Array<string | undefined>, indentation?: number): Lines;
    /**
     * Converts the first character of the given string to uppercase.
     *
     * @param str The string to convert.
     *
     * @returns The converted string with the first character in uppercase.
     */
    toTitleCase(str: string): string;
    /**
     * Renders a template string with the provided parameters. The template can contain placeholders in the
     * format `${0}`, `${1}`, etc., which will be replaced with the corresponding values from the `params` array.
     *
     * @param template The template string to render.
     * @param params The parameters to use for rendering the template.
     *
     * @returns The rendered string.
     */
    renderTemplate(template: string, ...params: unknown[]): string;
    /**
     * Renders key/value pairs from a map into a string array using the provided template.
     *
     * @param map The map containing key/value pairs to render.
     * @param indent The number of spaces to use for indentation.
     * @param template The template string to use for rendering each key/value pair.
     *                 The template should contain two placeholders: `${0}` for the key and `${1}` for the value.
     *
     * @returns An array of strings, each representing a rendered key/value pair.
     */
    renderMap(map: Map<string, unknown>, indent: number, template: string): string[];
    /**
     * Renders a list of objects into a string array using the provided template.
     *
     * @param list The list of objects to render.
     * @param indent The number of spaces to use for indentation.
     * @param template The template string to use for rendering each object.
     *                 The template should contain as many placeholders as there are key..
     * @param keys The names of properties of each object to be used in the template.
     *             The indexed values are coerced to strings.
     *
     * @returns An array of strings, each representing a rendered object.
     */
    renderTemplatedObjectList(list: Iterable<object>, indent: number, template: string, ...keys: string[]): string[];
    protected escapeWord(word: string): string;
    protected escapeCodePoint(codePoint: number): string;
    protected shouldUseUnicodeEscapeForCodePointInDoubleQuotedString(codePoint: number): boolean;
    protected escapeChar(v: number): string;
    /**
     * Escapes the Unicode code point appropriately for this language and append the escaped value to `sb`.
     * It exists for flexibility and backward compatibility with external targets, The static method
     * {@link UnicodeEscapes.appendEscapedCodePoint(StringBuilder, int, String)} can be used as well
     * if default escaping method (Java) is used or language is officially supported
     *
     * @param codePoint The code point to escape.
     * @param escape If true, the code point is escaped.
     *
     * @returns The escaped code point as a string.
     */
    private createUnicodeEscapedCodePoint;
}