@adguard/agtree/dist/types/utils/quotes.d.ts

Tool set for working with adblock filter lists

/**
 * @file Utility functions for working with quotes.
 */
/**
 * Set of all possible quote characters supported by the library.
 */
export declare const QUOTE_SET: Set<string>;
/**
 * Possible quote types for scriptlet parameters.
 */
export declare const QuoteType: {
    /**
     * No quotes at all.
     */
    readonly None: "none";
    /**
     * Single quotes (`'`).
     */
    readonly Single: "single";
    /**
     * Double quotes (`"`).
     */
    readonly Double: "double";
    /**
     * Backtick quotes (`` ` ``).
     */
    readonly Backtick: "backtick";
};
export type QuoteType = typeof QuoteType[keyof typeof QuoteType];
/**
 * Utility functions for working with quotes.
 */
export declare class QuoteUtils {
    /**
     * Escape all unescaped occurrences of the character.
     *
     * @param string String to escape.
     * @param char Character to escape.
     *
     * @returns Escaped string.
     */
    static escapeUnescapedOccurrences(string: string, char: string): string;
    /**
     * Unescape all single escaped occurrences of the character.
     *
     * @param string String to unescape.
     * @param char Character to unescape.
     *
     * @returns Unescaped string.
     */
    static unescapeSingleEscapedOccurrences(string: string, char: string): string;
    /**
     * Get quote type of the string.
     *
     * @param string String to check.
     *
     * @returns Quote type of the string.
     */
    static getStringQuoteType(string: string): QuoteType;
    /**
     * Set quote type of the string.
     *
     * @param string String to set quote type of.
     * @param quoteType Quote type to set.
     *
     * @returns String with the specified quote type.
     */
    static setStringQuoteType(string: string, quoteType: QuoteType): string;
    /**
     * Removes bounding quotes from a string, if any.
     *
     * @param string Input string.
     *
     * @returns String without quotes.
     */
    static removeQuotes(string: string): string;
    /**
     * Removes bounding quotes from a string, if any, and unescapes the escaped quotes,
     * like transforming `'abc\'def'` to `abc'def`.
     *
     * @param string Input string.
     *
     * @returns String without quotes.
     */
    static removeQuotesAndUnescape(string: string): string;
    /**
     * Wraps given `strings` with `quote` (defaults to single quote `'`)
     * and joins them with `separator` (defaults to comma+space `, `).
     *
     * @param strings Strings to quote and join.
     * @param quoteType Quote to use.
     * @param separator Separator to use.
     *
     * @returns String with joined items.
     *
     * @example
     * ['abc', 'def']: strings[]  ->  "'abc', 'def'": string
     */
    static quoteAndJoinStrings(strings: string[], quoteType?: QuoteType, separator?: string): string;
    /**
     * Convert `""` to `\"` within strings inside of attribute selectors,
     * because it is not compatible with the standard CSS syntax.
     *
     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#wildcard}
     *
     * @param selector CSS selector string.
     *
     * @returns Escaped CSS selector.
     *
     * @example
     * ```ts
     * QuoteUtils.escapeAttributeDoubleQuotes('[attr="value with "" quotes"]');
     * QuoteUtils.escapeAttributeDoubleQuotes('div[attr="value with "" quotes"] > span');
     * ```
     *
     * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used
     * in the standard CSS syntax, so we use conversion functions to handle this.
     * @note This function is intended to be used on whole attribute selector or whole selector strings.
     */
    static escapeAttributeDoubleQuotes(selector: string): string;
    /**
     * Convert escaped double quotes `\"` to `""` within strings inside of attribute selectors,
     * because it is not compatible with the standard CSS syntax.
     *
     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#tag-content}
     * @see {@link https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters#wildcard}
     *
     * @param selector CSS selector string.
     *
     * @returns Unescaped CSS selector.
     *
     * @example
     * ```ts
     * QuoteUtils.unescapeAttributeDoubleQuotes('[attr="value with \\" quotes"]');
     * QuoteUtils.unescapeAttributeDoubleQuotes('div[attr="value with \\" quotes"] > span');
     * ```
     *
     * @note In the legacy syntax, `""` is used to escape double quotes, but it cannot be used
     * in the standard CSS syntax, so we use conversion functions to handle this.
     * @note This function is intended to be used on whole attribute selector or whole selector strings.
     */
    static unescapeAttributeDoubleQuotes(selector: string): string;
}