regex

regex is a JavaScript library intended for parsing, generation and AST-construction of various regular expressions, as per the JavaScript variety's definition.

NOTE: the library depends upon the parsers.js package for parser-making

Installation

npm install @hgargg-0710/regex

Documentation

The package has the following exports:

1. parse (function)
2. generate (function)
3. parser (submodule)
4. generator (submodule)
5. tree (submodule)
6. tokens (submodule)

parse

function parse(regex: string): Flags

A function taking in a string containing a regular expression, and returning an AST of it.

generate

function generate(AST: Flags): string

Takes in the given AST node (not necessariliy Flags, but too long to express here), and returns a string representing it.

NOTE: partial nodes will give only partial results. For example, passing a PatternEnd will give "$".

parser

Various parsing layers APIs

export	description
ExpressionParser	Function. Parses an Expression, initially tokenizing it
boundry	Submodule. Handles parsing of boundries
chars	Submodule. Handles tokenization
classes	Submodule. Handles parsing of character classes
deflag	Submodule. Handles removal of flags
disjunction	Submodule. Handles parsing of disjunction expressions
escaped	Submodule. Handles parsing of escape-sequences
group	Submodule. Handles recursion within a regular expression
nogreedy	Submodule. Handles the "no-greedy" quantifiers
quantifier	Submodule. Handles the quantifiers

The submodule exports are a part of the parse function's final definition.

The order in which they (layers) are passed within the parse function are:

1. deflag
2. chars
3. classes
4. escaped
5. boundry
6. group (recursive, looped)
7. quantifier
8. nogreedy
9. disjunction

deflag

export	description
DeFlag	Functions for the de-flagging of a string with regular expression in it. Returns a Flags object, with the .expression field containing the expressions's string
flagTable	Table for identification of flags with appropriate TokenInstances
flagInstance	Function based off flagTable. Returns the TokenType of a given flag string
identifyFlags	Maps flagInstance to an array of strings

chars

export	description
ExpressionTokenizer	A PatternTokenizer for tokenizing the given Pattern with a regular expression in it
tokenizerMap	The RegExpMap, on which ExpressionTokenizer is based

classes

export	description
CharacterClassParser	Main parser for character classes
classLimit	Limits the given stream up to the next RectOp from the current element
classMap	TypeMap, on which CharacterClassParser is based
HandleClass	The handler for the RectOp token inside the classMap
ClassHandler	A multistep function, serving as the main component of HandleClass
EscapeInner	A parser function, first component of the ClassHandler. Escapes inside characters
HandleEscaped	Handler for the escaped characters, main part of the EscapeInner
IdentifyRanges	Second parsing function of ClassHandler. Identifies and parsers ranges
HandleRange	The main component of IdentifyRanges, parses encountered ranges
InClassEscapedHandler	A slightly modified version of the escapedMap from escaped module for escaping

escaped

export	description
EscapedParser	Main parser of the escaped characters
escapePreface	The TypeMap, on which EscapedParser is based
escapeMap	The ValueMap, on which defines the global-scope escaping
escapedHandler	Creates a function for handling escaped characters based off given map
parseBackreference	Returns a Backreference based on given arguments of curr, input
parseMultControl	Returns a ControlCharacter of lengths 4-5 based on curr, input
parseDoubleControl	Returns a ControlCharacter of length 2 based on curr, input
parseSingleControl	Returns a ControlCharacter of length 1 based on curr, input
readUnicodeClassProperty	Parses a UnicodeClassProperty based on curr, input
readBraced	Reads the given Stream, until a ClBrace is encountered
readNamedBackreference	Reads a NamedBackreference based on readIdentifier
readUBrace	Reads a sequence of {hhhh} or {hhhhh} where isHex(h) === true
readu	Reads a sequence of hhhh, where isHex(h) === true
readx	Reads a sequence of hh, where isHex(h) === true
isHex	Returns whether a character given is a hexidecimal

boundry

export	description
BoundryParser	Main parser of the submodule. Separates boundries into TokenInstances
boundryMap	The TypeMap, on which the BoundryParser is based
HandleEscaped	Handles the NonWordBoundry TokenInstances

group

export	description
EndParser	The main parser of the submodule. The ExpressionParser ends with it
GroupParser	The first parsing layer of the EndParser. Recursive. Handles recursion, groups/captures, look-aheads/-behinds
groupMap	The TypeMap, on which the GroupParser is based
GroupHandler	The main component of the groupMap
nestedBrack	Function for limiting the current-level nested bracket-expression
CollectionHandler	Function for handling current collection
HandleQMark	Function for handling "collections" starting with ? ((?<!...), (?<...>...), ...)
HandleCollectionBase	Function for recursively handling a capture group
QMarkHandler	Underlying TableParser of HandleQMark
HandleQMarkExclMark	Handles a negative look-ahead
HandleQMarkEq	Handles a look-ahead
HandleLeftAngular	Handles all "collections" starting with < ((?<...>...), (?<=...), ...)
HandleColon	Handles a no-capture group
LeftAngularHandler	Underlying TableParser for HandleLeftAngular
HandleLeftAngularBase	Handles a named capture
HandleLeftAngularExclMark	Handles a negative look-behind
HandleLeftAngularEq	Handles a look-behind
readIdentifier	Reads an identifier (for the named capture/backreference)

quantifier

export	description
QuantifierParser	Main parser of the submodule. Parses quantifiers
QuantifierHandler	A TableParser, main component of the QuantifierParser
HandlePlus	Handles a Plus token encountered
HandleStar	Handles a Star token encountered
HandleQMark	Handles a QMark token encountered
BraceHandler	Handles a OpBrace token encountered
HandleBraced	Returns a handling function for either one of NtoM, NPlus, or NOnly
readNumber	Reads a number from the given Stream (note: up to the first isNaN token)
limitBraced	Limits the given Stream up to the point of the first encountered ClBrace

nogreedy

export	description
ParseNoGreedy	Main parser of the submodule. Parsers NoGreedy tokens
noGreedyMap	The TypeMap, on which ParseNoGreedy is based
HandleQuantifier	Handler for quantifiers
QuantifierHandler	The underlying TableParser-function of HandleQuantifiers
HandleQMark	Handles QMark following a quantifier (no-greedy quantifiers)

disjunction

export	description
DisjunctionParser	The main export of the submodule. Parses disjunctions
EmptyFixer	First parsing layer of DisjunctionParser. Fixes empty expressions ||
DisjunctionTokenizer	Second parsing layer of DisjunctionParser. Puts non-Pipe bits of current Stream into DisjucntionArguments
DisjunctionDelimiter	Third and final parsing layer of DisjunctionParser. Delimits the Stream based off Pipe tokens
hasDisjunctions	Checks whether a given Stream has disjunctions to parse from given point on
limitPipe	Limits the given Stream until the moment the next Pipe is encountered
skipTilPipes	Skips Stream until a Pipe is discovered

generator

Provides regex-generation related exports based off the package's AST

export	description
RegexGenerator	The SourceGenerator for the package's AST (generate is based on it)
generatorMap	The TypeMap, on which RegexGenerator is based
GenerateBackspaceClass	Generates a regex for BackspaceClass
GenerateWordBoundry	Generates a regex for WordBoundry
GenerateNonWordBoundry	Generates a regex for NonWordBoundry
GenerateNewline	Generates a regex for Newline
GenerateCarriageReturn	Generates a regex for CarriageReturn
GenerateWordClass	Generates a regex for WordClass
GenerateNonWordClass	Generates a regex for NonWordClass
GenerateFormFeed	Generates a regex for FormFeed
GenerateDigitClass	Generates a regex for DigitClass
GenerateNonDigitClass	Generates a regex for NonDigitClass
GenerateNULClass	Generates a regex for NULClass
GenerateVerticalTab	Generates a regex for VerticalTab
GenerateHorizontalTab	Generates a regex for HorizontalTab
GenerateNonWhitespaceClass	Generates a regex for NonWhitespaceClass
GenerateWhitespaceClass	Generates a regex for WhitespaceClass
GenerateEmptyExpression	Generates a regex for EmptyExpression
GenerateMatchIndicies	Generates a regex for MatchIndicies flag
GenerateGlobalSearch	Generates a regex for GlobalSearch flag
GenerateCaseInsensitive	Generates a regex for CaseInsensitive flag
GenerateMultline	Generates a regex for Multline flag
GenerateDotAll	Generates a regex for DotAll flag
GenerateUnicode	Generates a regex for Unicode flag
GenerateUnicodeSets	Generates a regex for UnicodeSets flag
GenerateSticky	Generates a regex for Sticky flag
GeneratePatterStart	Generates a regex for PatternStart
GeneratePatternEnd	Generates a regex for PatternEnd
GenerateFlags	Generates a regex for Flags
GenerateExpression	Generates an regex for Expression
GenerateNOnly	Generates an regex for NOnly
GenerateNtoM	Generates an regex for NtoM
GenerateNPlus	Generates an regex for NPlus
GenerateEscaped	Generates an regex for Escaped
GenerateBackreference	Generates a regex for Backreference
GenerateUnicodeClassProperty	Generates a regex for UnicodeClassProperty
GenerateControlCharacter	Generates a regex for ControlCharacter
GenerateNamedBackreference	Generates a regex for NamedBackreference
GenerateClassRange	Generates a regex for ClassRange
GenerateNoGreedy	Generates a regex for NoGreedy
GenerateOptional	Generates anregex for Optional
GenerateZeroPlus	Generates a regex for ZeroPlus
GenerateOnePlus	Generates a regex for OnePlus
GenerateClass	Generates a regex for CharacterClass
GenerateNegClass	Generates a regex for NegCharacterClass
GenerateDisjunction	Generates a regex for Disjunction
GenerateDisjunctionArgument	Generates a regex for DisjunctionArgument
GenerateNonCaptureGroup	Generates a regex for NonCaptureGroup
GenerateCaptureGroup	Generates a regex for CaptureGroup
GenerateLookAhead	Generates a regex for LookAhead
GenerateLookBehind	Generates a regex for LookBehind
GenerateNegLookAhead	Generates a regex for NegLookAhead
GenerateNegLookBehind	Generates a regex for NegLookBehind
GenerateNamedCapture	Generates a regex for NamedCapture
GenerateWildcard	Generates a regex for Wildcard
GeneratePipe	Generates a regex for Pipe
GenerateComma	Generates a regex for Comma
GenerateTrivial	Generates a regex for anything else not in the table already (with a typeof .value === 'string')

tree

export	description
RegexStream	A TreeStream for the library's AST (note: accepts THE AST ITSELF)
RegexTree	A Tree interface implementation for the library's AST
treeMap	The TypeMap, on which RegexTree is based
NamedCaptureTree	The function for conversion of a NamedCapture to a Tree
ExpressionTree	The function for conversion of an Expression to a Tree
FlagTree	The function for convertsion of a Flags to a Tree
SeveralTree	The function for conversion of NOnly, NtoM and NPlus to a Tree
SingleTree	The function for conversion of ZeroPlus, OnePlus, Optional, LookAhead, LookBehind, NegLookAhead, NegLookBehind, NamedBackreference to a Tree
ValueTree	The function for conversion of ClassRange, DisjunctionArgument, CharacterClass, NegCharacterClass and Disjunction to a Tree
ChildlessTree	The function for conversion of the rest of the tokens to a Tree

tokens

The tokens module has the same submodule structure as the parser module.

submodule	description
boundry	Various boundry tokens
chars	Various basic (first-order) tokens
classes	Tokens for representation of character classes
deflag	Flags and expressions representation tokens
disjunction	Disjunction-related tokens
escaped	Escape-sequence-related tokens
group	Tokens for groups and other recursive structures
nogreedy	Tokens for non-greedy quantifiers
quantifier	Tokens for quantifiers

deflag

TokenType/TokenInstance	represents	type
MatchIndicies	The d flag	"indicies"
GlobalSearch	The g flag	"global"
CaseInsensitive	The i flag	"case-insensitive"
Multiline	The m flag	"multiline"
DotAll	The s flag	"dot-all"
Unicode	The u flag	"unicode"
UnicodeSets	The v flag	"unicode-sets"
Sticky	The y flag	"sticky"
Flags	The complete regular expression with flags	"flags"
Expression	A partial expression, without flags (can have other Expressions inside)	"expression"

chars

TokenType	represents	type
Escape	\\	"escape"
RectOp	[	"rop"
RectCl	]	"rcl"
Hyphen	-	"hyphen"
Pipe	|	"pipe"
OpBrack	(	"opbrack"
ClBrack	)	clbrack
QMark	?	"qmark"
ExclMark	!	"emark
Eq	=	"eq"
Wildcard	.	"wildcard"
Star	*	"star"
Plus	+	"plus"
OpBrace	{	"opbrc"
ClBrace	}	"clbrc"
Colon	:	"colon"
Comma	,	"comma"
LeftAngular	<	"lang"
RightAngular	>	"rang"
Dollar	$	"dollar"
Xor	^	"xor"
RegexSymbol	everything else	"symbol"

classes

TokenType	represents	type
CharacterClass	A character class [...]	"charclass"
NegCharacterClass	A negative character class [^...]	"neg-charclass"
ClassRange	A character class range X-Y	"class-range"

escaped

TokenType/TokenInstance	represents	type
ControlCharacter	\cX, \xhh, \uhhhh, \u{hhhh} or \u{hhhhh}	"control-char"
Backreference	\N - numeric backreference	"backref"
NamedBackreference	\k<name> - named backreference	"named-backref"
UnicodeClassProperty	\p{...} - unicode class property	"uniprop"
RegexIdentifier	name - identifier in named captures/backreferences	"identifier"
CarriageReturn	\r - carriage return	"cr"
NonWordBoundry	\B - non-word boundry (outside classes)	"non-word-boundry"
WordBoundry	\b - word-boundry	"word-boundry"
NULClass	\0 - NUL class	"nul-class"
FormFeed	\f - form feed	"form-feed"
DigitClass	\d - digit class	"digit-class"
NonDigitClass	\D - non-digit class	"non-digit-class"
WordClass	\w - word-class	"word-class"
NonWordClass	\W - nonw-word-class	"non-word-class"
WhitespaceClass	\s - whitespace class	"whitespace-class"
NonWhitespaceClass	\S - non-whitespace class	"non-whitespace-class"
HorizontalTab	\t - horizontal tab	"tab"
VerticalTab	\v - vertical tab	"vtab"
BackspaceClass	\b - backspace	"backspace"
Newline	\n - newline	"newline"
Escaped	Any other escaped character	"escaped"

boundry

TokenInstance	represents	type
PatternStart	^	"start"
PatternEnd	$	"end"

group

TokenType	represents	type
CaptureGroup	(...)	"capture"
NoCaptureGroup	(?:...)	"non-capture"
NamedCapture	(<name>...)	"named-capture"
LookAhead	(?=...)	"lookahead"
LookBehind	(?<=...)	"lookbehind"
NegLookAhead	(?!...)	"neg-lookahead"
NegLookBehind	(?<!...)	"neg-lookbehind"

quantifier

TokenType	represents	type
ZeroPlus	...*	"zero-plus"
OnePlus	...+	"one-plus"
Optional	...?	"optional"
NOnly	...{...}	"n-only"
NPlus	...{...,}	"n-plus"
NtoM	...{...,...}	"n-to-m"

nogreedy

export	description	type
NoGreedy	A TokenType representing no-greedy opertors	"nogreedy"
isQuantifier	A predicate returning true only for tokens with types from the quantifier module

disjunction

TokenType/TokenInstance	represents	type
Disjunction	...|...|...	"disjunction"
DisjunctionArgument	An element of a Disjunction	"disjunction-arg"
EmptyExpression	An empty element of a Disjunction (||)	"empty"