shelving/util/regexp.d.ts

Toolkit for using data in JavaScript.

import { type ImmutableArray } from "./array.js";
import { type Nullish } from "./null.js";
import type { NotString } from "./string.js";
/** A thing that a string can be matched against. */
export type Matchable = string | RegExp;
/** A list of things that strings can be matched against. */
export type Matchables = ImmutableArray<Nullish<Matchable>>;
/** 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;
}
/**
 * Does a string match against a regular expressions or string.
 * - Use with `filter()` to positively filter iterable sets of items.
 *
 * @param str String to test against the regular expression.
 * @param regexp Regular expression to test against the string.
 * - If `regexp` is a `RegExp` it is tested against the string using `RegExp.test()`.
 * - If `regexp` is a `string` it is simply tested against the string using `===` equality.
 * @returns `true` if the string matches the regular expression, otherwise `false`.
 */
export declare function isMatch(str: string, regexp: Matchable): boolean;
/**
 * Does a string not match against a regular expressions or string.
 * - Use with `filter()` to negatively filter iterable sets of items.
 *
 * @param str String to test against the regular expression.
 * @param regexp Regular expression to test against the string.
 * - If `regexp` is a `RegExp` it is tested against the string using `RegExp.test()`.
 * - If `regexp` is a `string` it is simply tested against the string using `!==` equality.
 * @returns `true` if the string matches the regular expression, otherwise `false`.
 */
export declare function notMatch(str: string, regexp: Matchable): boolean;
/**
 * All of the provided regular expressions match the string.
 *
 * @param regexps - Regular expressions to match against the string.
 * - If empty the function returns `true` (since all zero of the provided regexps match everything).
 * - If a `RegExp` it is tested against the string using `RegExp.test()`.
 * - If a `string` it is simply tested against the string using `===` equality.
 * - If `null` or `undefined` it is ignored.
 */
export declare function allMatch(str: string, ...regexps: Matchables): boolean;
/** At least one of the provided regular expressions matches the string. */
export declare function anyMatch(str: string, ...regexps: Matchables): boolean;
/** None of the provided regular expressions match the string. */
export declare function noneMatch(str: string, ...regexps: Matchables): 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;