shelving/util/regexp.d.ts

Toolkit for using data in JavaScript.

import type { NotString } from "./string.js";
/** Regular expression that always matches everything. */
export declare const ALWAYS_REGEXP: RegExp;
/** Regular expression that never matches anything. */
export declare const NEVER_REGEXP: RegExp;
/** Things that can be convert to a regular expression. */
export type PossibleRegExp = string | RegExp;
/** Is an unknown value a `RegExp` instance? */
export declare function isRegExp(value: unknown): value is RegExp;
/** Assert that an unknown value is a `RegExp` instance. */
export declare function assertRegExp(value: unknown): asserts value is RegExp;
/** Convert a string to a regular expression that matches that string. */
export declare function getRegExp<T extends NamedRegExpData>(pattern: NamedRegExp<T>, flags?: string): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
export declare function getRegExp<T extends NamedRegExpData | undefined = undefined>(pattern: PossibleRegExp, flags?: string): T extends NamedRegExpData ? NamedRegExp<T> : RegExp;
/** Convert a regular expression to its string source. */
export declare function getRegExpSource(regexp: PossibleRegExp): string;
/** Escape special characters in a string regular expression. */
export declare function escapeRegExp(pattern: string): string;
/** Create regular expression that matches any of a list of other expressions. */
export declare function createRegExpAny(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
/** Create regular expression that matches all of a list of other expressions. */
export declare function createRegExpAll(patterns: Iterable<PossibleRegExp> & NotString, flags?: string): RegExp;
/** Regular expression match array that matches a specific string format. */
export interface TypedRegExpExecArray<T extends string = string> extends RegExpExecArray {
    0: T;
}
/** Regular expression that matches a specific string format. */
export interface TypedRegExp<T extends string = string> extends RegExp {
    exec(input: string): TypedRegExpExecArray<T> | null;
}
/** Set of named match groups from a regular expression. */
export type NamedRegExpData = {
    [named: string]: string;
};
/** Regular expression match array that contains the specified named groups. */
export interface NamedRegExpExecArray<T extends NamedRegExpData = NamedRegExpData> extends RegExpExecArray {
    groups: T;
}
/** Regular expression that contains the specified named capture groups. */
export interface NamedRegExp<T extends NamedRegExpData = NamedRegExpData> extends RegExp {
    exec(input: string): NamedRegExpExecArray<T> | null;
}
/** Match function for finding strings that match against regular expressions (use with `filter()` to positively filter iterable sets of items). */
export declare function isMatch(str: string, regexp: RegExp): boolean;
/** Match function for finding strings that match against regular expressions (use with `filter()` to negatively filter iterable sets of items). */
export declare function notMatch(str: string, regexp: RegExp): boolean;
/** Get an optional regular expression match, or `undefined` if no match could be made. */
export declare function getMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T> | undefined;
export declare function getMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T> | undefined;
export declare function getMatch(str: string, regexp: RegExp): RegExpExecArray | undefined;
/** Get a required regular expression match, or throw `ValueError` if no match could be made. */
export declare function requireMatch<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): NamedRegExpExecArray<T>;
export declare function requireMatch<T extends string>(str: string, regexp: TypedRegExp<T>): TypedRegExpExecArray<T>;
export declare function requireMatch(str: string, regexp: RegExp): RegExpExecArray;
/** Get an optional regular expression match, or `undefined` if no match could be made. */
export declare function getMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T | undefined;
export declare function getMatchGroups(str: string, regexp: RegExp): NamedRegExpData | undefined;
/** Get a required regular expression match, or throw `ValueError` if no match could be made. */
export declare function requireMatchGroups<T extends NamedRegExpData>(str: string, regexp: NamedRegExp<T>): T;
export declare function requireMatchGroups(str: string, regexp: RegExp): NamedRegExpData;