RegExpString overview

Composable regular-expression patterns expressed as plain strings.

Mental model

• Patterns are produced as string’s and combined as string’s. The final pattern is fed to the RegExp constructor by callers (or by helpers in {@link “./RegExp.js” | MRegExp}).
• Combinators ({@link zeroOrMore}, {@link oneOrMore}, {@link either}, …) wrap their argument in a non-capturing group (?:…) so they remain composable without affecting capture indices.
• Pre-built instances cover the common building blocks (digits, sign, separators, line breaks) and a few full patterns ({@link semVer}, {@link email}, {@link base10Number}).

Common tasks

• Quantifiers: {@link zeroOrMore}, {@link oneOrMore}, {@link repeatBetween}, {@link optional}
• Composition: {@link either}, {@link anyCharIn}, {@link charNotIn}
• Anchors / lookarounds: {@link makeLine}, {@link atStart}, {@link atEnd}, {@link positiveLookAhead}, {@link negativeLookAhead}
• Capturing: {@link capture}, {@link optionalCapture}
• Numbers: {@link unsignedBase10Int}, {@link unsignedNonNullBase10Int}, {@link base10Number}, {@link binaryInt}, {@link octalInt}, {@link hexaInt}
• Pre-built: {@link semVer}, {@link email}, {@link lineBreak}, {@link universalPathSep}

Quickstart

Example (Compose a pattern)

import { pipe } from "effect"
import * as MRegExpString from "@parischap/effect-lib/MRegExpString"

const pattern = pipe(MRegExpString.digit, MRegExpString.oneOrMore, MRegExpString.makeLine)
console.log(new RegExp(pattern).test("12345")) // true
console.log(new RegExp(pattern).test("12a45")) // false

Table of contents

• Constants
  • DIGIT_GROUP_SIZE
• Constructors
  • fromRegExp
• Instances
  • CR
  • LF
  • anyChar
  • anyCharButLineBreak
  • anyWord
  • anyWordLetter
  • anythingButDot
  • arrowbase
  • backslash
  • base10Number
  • binaryInt
  • digit
  • dollar
  • dot
  • email
  • hexaInt
  • letter
  • lineBreak
  • lowerCaseLetter
  • lowerCaseLetterOrDigit
  • minus
  • nonSpace
  • nonZeroDigit
  • octalInt
  • plus
  • semVer
  • sign
  • slash
  • space
  • spaces
  • star
  • tab
  • universalPathSep
  • unsignedBase10Int
  • unsignedNonNullBase10Int
  • upperCaseLetter
• Utils
  • anyCharIn
  • atEnd
  • atStart
  • capture
  • charNotIn
  • either
  • makeLine
  • negativeLookAhead
  • oneOrMore
  • optional
  • optionalCapture
  • positiveLookAhead
  • repeatBetween
  • zeroOrMore

Constants

DIGIT_GROUP_SIZE

Size of a group of digits separated by a thousand separator (e.g. 1,234,567).

Signature

export declare const DIGIT_GROUP_SIZE: 3

Constructors

fromRegExp

Returns the source of regExp as a string.

Signature

export declare const fromRegExp: (regExp: RegExp) => string

Instances

CR

A regular expression string representing a carriage return

Signature

export declare const CR: string

LF

A regular expression string representing a line-feed

Signature

export declare const LF: string

anyChar

A regular expression string representing any character

Signature

export declare const anyChar: string

anyCharButLineBreak

A regular expression string representing any character but a lineBreak

Signature

export declare const anyCharButLineBreak: "."

anyWord

A regular expression string representing a word

Signature

export declare const anyWord: string

anyWordLetter

A regular expression string representing a word letter

Signature

export declare const anyWordLetter: string

anythingButDot

A regular expression string representing anything but a dot

Signature

export declare const anythingButDot: string

arrowbase

A regular expression string representing the arrowbase

Signature

export declare const arrowbase: "@"

backslash

A regular expression string representing a backslashString

Signature

export declare const backslash: string

base10Number

Returns a regular expression string representing a left-padded number in base 10 using thousandSeparator as thousand separator, fractionalSeparator as fractional separator and eNotationChars as possible characters for scientific notation.

• thousandSeparator: Usually a string made of at most one character but not mandatory. Should be different from fractionalSeparator. Will not throw otherwise but unexpected results might occur. Use ‘’ for no thousand separator.
• fractionalSeparator: usually a one-character string but not mandatory (e.g. ‘.’). Should not be an empty string and be different from thousandSeparator. Will not throw otherwise but unexpected results might occur.
• eNotationChars: array of possible chracters that can be used to represent an exponent (e.g. value: [‘E’, ‘e’]).
• fillChar: usually a one-character string but not mandatory (e.g. ‘ ‘). If not an empty string, zero or more fillChar’s are tolerated between the sign and the number (or at the start of the number if it is unsigned). Beware if you use a digit as fillChar (e.g. you use ‘0’ as fillChar and try to parse ‘0000’)

Signature

export declare const base10Number: ({
  thousandSeparator,
  fractionalSeparator,
  eNotationChars,
  fillChar
}: {
  readonly thousandSeparator: string
  readonly fractionalSeparator: string
  readonly eNotationChars: ReadonlyArray<string>
  readonly fillChar: string
}) => string

binaryInt

A regular expression string representing an integer in base 2.

Signature

export declare const binaryInt: string

digit

A regular expression string representing a digit

Signature

export declare const digit: string

dollar

A regular expression string representing a dollar sign

Signature

export declare const dollar: string

dot

A regular expression string representing a dot

Signature

export declare const dot: string

email

A regular expression string representing an email - Imported from https://stackoverflow.com/questions/201323/how-can-i-validate-an-email-address-using-a-regular-expression

Signature

export declare const email: string

hexaInt

A regular expression string representing an integer in base 16.

Signature

export declare const hexaInt: string

letter

A regular expression string representing a letter

Signature

export declare const letter: "[A-Za-z]"

lineBreak

A regular expression string representing a linebreak in Windows, Unix and Mac Os

Signature

export declare const lineBreak: string

lowerCaseLetter

A regular expression string representing a lowercase letter

Signature

export declare const lowerCaseLetter: "[a-z]"

lowerCaseLetterOrDigit

A regular expression string representing a lowercase letter or a digit.

Signature

export declare const lowerCaseLetterOrDigit: "[a-z0-9]"

minus

A regular expression string representing a minus sign

Signature

export declare const minus: "-"

nonSpace

A regular expression string representing a non-space character.

Signature

export declare const nonSpace: string

nonZeroDigit

A regular expression string representing a strictly positive digit

Signature

export declare const nonZeroDigit: "[1-9]"

octalInt

A regular expression string representing an integer in base 8.

Signature

export declare const octalInt: string

plus

A regular expression string representing a plus sign

Signature

export declare const plus: string

semVer

A regular expression string representing a simplified SemVer. See https://semver.org/ for a more accurate version

Signature

export declare const semVer: string

sign

A regular expression string representing a plus or a minus sign

Signature

export declare const sign: string

slash

A regular expression string representing a slash

Signature

export declare const slash: string

space

A regular expression string representing a space

Signature

export declare const space: string

spaces

A regular expression string representing zero or more spaces

Signature

export declare const spaces: string

star

A regular expression string representing a star

Signature

export declare const star: string

tab

A regular expression string representing a tab

Signature

export declare const tab: string

universalPathSep

A path separator regular expression string to split all possible paths

Signature

export declare const universalPathSep: string

unsignedBase10Int

Returns a regular expression string representing an unsigned integer in base 10 using thousandSeparator as thousand separator. Pass an empty string for no thousand separator.

Signature

export declare const unsignedBase10Int: (thousandSeparator: string) => string

unsignedNonNullBase10Int

Returns a regular expression string representing an unsigned non-null integer in base 10 using thousandSeparator as thousand separator. Pass an empty string for no thousand separator.

Signature

export declare const unsignedNonNullBase10Int: (thousandSeparator: string) => string

upperCaseLetter

A regular expression string representing an uppercase letter

Signature

export declare const upperCaseLetter: "[A-Z]"

Utils

anyCharIn

Returns a pattern matching any one of the supplied characters as a character class.

• For an empty input returns the empty string.
• For a single argument returns it verbatim (no class is added).
• For two or more, builds [abc…].

Example

import * as MRegExpString from "@parischap/effect-lib/MRegExpString"

console.log(MRegExpString.anyCharIn(["a", "b", "c"])) // '[abc]'

Signature

export declare const anyCharIn: (args: ReadonlyArray<string>) => string

atEnd

Anchors self to the end of a line by appending $.

Signature

export declare const atEnd: MTypes.StringTransformer

atStart

Anchors self to the start of a line by prepending ^.

Signature

export declare const atStart: MTypes.StringTransformer

capture

Wraps self in a named capture group (?<name>…).

Example

import { pipe } from "effect"
import * as MRegExpString from "@parischap/effect-lib/MRegExpString"

console.log(pipe(MRegExpString.digit, MRegExpString.capture("d"))) // '(?<d>\\d)'

Signature

export declare const capture: (name: string) => (self: string) => string

charNotIn

Returns a pattern matching any character not in the supplied set, as a negated character class [^abc…].

Signature

export declare const charNotIn: (args: MTypes.ReadonlyOverOne<string>) => string

either

Returns a pattern matching any one of args (alternation).

• Empty strings in args are dropped.
• For a single non-empty argument, returns it verbatim (no group is added).
• For two or more, joins with | inside a non-capturing group.

Example

import * as MRegExpString from "@parischap/effect-lib/MRegExpString"

console.log(MRegExpString.either("foo", "bar", "baz")) // '(?:foo|bar|baz)'

Signature

export declare const either: (...args: ReadonlyArray<string>) => string

makeLine

Wraps self between ^ and $ so it must span an entire line.

Signature

export declare const makeLine: MTypes.StringTransformer

negativeLookAhead

Wraps self in a negative lookahead (?!…).

Signature

export declare const negativeLookAhead: MTypes.StringTransformer

oneOrMore

Wraps self so it may appear one or more times, using a non-capturing group.

Signature

export declare const oneOrMore: MTypes.StringTransformer

optional

Wraps self so it is optional, using a non-capturing group.

Signature

export declare const optional: MTypes.StringTransformer

optionalCapture

Combines {@link capture} and {@link optional}: wraps self in a named capture group followed by ?.

Signature

export declare const optionalCapture: (name: string) => (self: string) => string

positiveLookAhead

Wraps self in a positive lookahead (?=…).

Signature

export declare const positiveLookAhead: MTypes.StringTransformer

repeatBetween

Wraps self so it may appear between low and high times.

• low must be a non-negative integer with low <= high.
• high must be a strictly positive integer or +Infinity; +Infinity is rendered as an open-ended quantifier {low,}.

Example

import { pipe } from "effect"
import * as MRegExpString from "@parischap/effect-lib/MRegExpString"

console.log(pipe("a", MRegExpString.repeatBetween(2, 4))) // '(?:a){2,4}'
console.log(pipe("a", MRegExpString.repeatBetween(2, Infinity))) // '(?:a){2,}'

Signature

export declare const repeatBetween: (low: number, high: number) => (self: string) => string

zeroOrMore

Wraps self so it may appear zero or more times, using a non-capturing group.

Example

import * as MRegExpString from "@parischap/effect-lib/MRegExpString"

console.log(MRegExpString.zeroOrMore("a")) // '(?:a)*'

Signature

export declare const zeroOrMore: (self: string) => string