package syntax

Import Path
	regexp/syntax (on go.dev)

Dependency Relation
	imports 5 packages, and imported by one package


Involved Source Files

	    compile.go
	
		Package syntax parses regular expressions into parse trees and compiles
		parse trees into programs. Most clients of regular expressions will use the
		facilities of package regexp (such as Compile and Match) instead of this package.
		
		# Syntax
		
		The regular expression syntax understood by this package when parsing with the Perl flag is as follows.
		Parts of the syntax can be disabled by passing alternate flags to Parse.
		
		Single characters:
		
			.              any character, possibly including newline (flag s=true)
			[xyz]          character class
			[^xyz]         negated character class
			\d             Perl character class
			\D             negated Perl character class
			[[:alpha:]]    ASCII character class
			[[:^alpha:]]   negated ASCII character class
			\pN            Unicode character class (one-letter name)
			\p{Greek}      Unicode character class
			\PN            negated Unicode character class (one-letter name)
			\P{Greek}      negated Unicode character class
		
		Composites:
		
			xy             x followed by y
			x|y            x or y (prefer x)
		
		Repetitions:
		
			x*             zero or more x, prefer more
			x+             one or more x, prefer more
			x?             zero or one x, prefer one
			x{n,m}         n or n+1 or ... or m x, prefer more
			x{n,}          n or more x, prefer more
			x{n}           exactly n x
			x*?            zero or more x, prefer fewer
			x+?            one or more x, prefer fewer
			x??            zero or one x, prefer zero
			x{n,m}?        n or n+1 or ... or m x, prefer fewer
			x{n,}?         n or more x, prefer fewer
			x{n}?          exactly n x
		
		Implementation restriction: The counting forms x{n,m}, x{n,}, and x{n}
		reject forms that create a minimum or maximum repetition count above 1000.
		Unlimited repetitions are not subject to this restriction.
		
		Grouping:
		
			(re)           numbered capturing group (submatch)
			(?P<name>re)   named & numbered capturing group (submatch)
			(?:re)         non-capturing group
			(?flags)       set flags within current group; non-capturing
			(?flags:re)    set flags during re; non-capturing
		
			Flag syntax is xyz (set) or -xyz (clear) or xy-z (set xy, clear z). The flags are:
		
			i              case-insensitive (default false)
			m              multi-line mode: ^ and $ match begin/end line in addition to begin/end text (default false)
			s              let . match \n (default false)
			U              ungreedy: swap meaning of x* and x*?, x+ and x+?, etc (default false)
		
		Empty strings:
		
			^              at beginning of text or line (flag m=true)
			$              at end of text (like \z not \Z) or line (flag m=true)
			\A             at beginning of text
			\b             at ASCII word boundary (\w on one side and \W, \A, or \z on the other)
			\B             not at ASCII word boundary
			\z             at end of text
		
		Escape sequences:
		
			\a             bell (== \007)
			\f             form feed (== \014)
			\t             horizontal tab (== \011)
			\n             newline (== \012)
			\r             carriage return (== \015)
			\v             vertical tab character (== \013)
			\*             literal *, for any punctuation character *
			\123           octal character code (up to three digits)
			\x7F           hex character code (exactly two digits)
			\x{10FFFF}     hex character code
			\Q...\E        literal text ... even if ... has punctuation
		
		Character class elements:
		
			x              single character
			A-Z            character range (inclusive)
			\d             Perl character class
			[:foo:]        ASCII character class foo
			\p{Foo}        Unicode character class Foo
			\pF            Unicode character class F (one-letter name)
		
		Named character classes as character class elements:
		
			[\d]           digits (== \d)
			[^\d]          not digits (== \D)
			[\D]           not digits (== \D)
			[^\D]          not not digits (== \d)
			[[:name:]]     named ASCII class inside character class (== [:name:])
			[^[:name:]]    named ASCII class inside negated character class (== [:^name:])
			[\p{Name}]     named Unicode property inside character class (== \p{Name})
			[^\p{Name}]    named Unicode property inside negated character class (== \P{Name})
		
		Perl character classes (all ASCII-only):
		
			\d             digits (== [0-9])
			\D             not digits (== [^0-9])
			\s             whitespace (== [\t\n\f\r ])
			\S             not whitespace (== [^\t\n\f\r ])
			\w             word characters (== [0-9A-Za-z_])
			\W             not word characters (== [^0-9A-Za-z_])
		
		ASCII character classes:
		
			[[:alnum:]]    alphanumeric (== [0-9A-Za-z])
			[[:alpha:]]    alphabetic (== [A-Za-z])
			[[:ascii:]]    ASCII (== [\x00-\x7F])
			[[:blank:]]    blank (== [\t ])
			[[:cntrl:]]    control (== [\x00-\x1F\x7F])
			[[:digit:]]    digits (== [0-9])
			[[:graph:]]    graphical (== [!-~] == [A-Za-z0-9!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~])
			[[:lower:]]    lower case (== [a-z])
			[[:print:]]    printable (== [ -~] == [ [:graph:]])
			[[:punct:]]    punctuation (== [!-/:-@[-`{-~])
			[[:space:]]    whitespace (== [\t\n\v\f\r ])
			[[:upper:]]    upper case (== [A-Z])
			[[:word:]]     word characters (== [0-9A-Za-z_])
			[[:xdigit:]]   hex digit (== [0-9A-Fa-f])
		
		Unicode character classes are those in unicode.Categories and unicode.Scripts.

	    op_string.go
	    parse.go
	    perl_groups.go
	    prog.go
	    regexp.go
	    simplify.go


Package-Level Type Names (total 15, in which 9 are exported)


	/* sort exporteds by:  |  */
	
		An EmptyOp specifies a kind or mixture of zero-width assertions.

		
			func EmptyOpContext(r1, r2 rune) EmptyOp
			func (*Prog).StartCond() EmptyOp
		
			const EmptyBeginLine
			const EmptyBeginText
			const EmptyEndLine
			const EmptyEndText
			const EmptyNoWordBoundary
			const EmptyWordBoundary


	
		An Error describes a failure to parse a regular expression
		and gives the offending expression.

		
			Code ErrorCode
			Expr string
		
			(*Error) Error() string
		
			*Error : error


	
		An ErrorCode describes a failure to parse a regular expression.

		
			( ErrorCode) String() string
		
			 ErrorCode : fmt.Stringer
			
		
			const ErrInternalError
			const ErrInvalidCharClass
			const ErrInvalidCharRange
			const ErrInvalidEscape
			const ErrInvalidNamedCapture
			const ErrInvalidPerlOp
			const ErrInvalidRepeatOp
			const ErrInvalidRepeatSize
			const ErrInvalidUTF8
			const ErrLarge
			const ErrMissingBracket
			const ErrMissingParen
			const ErrMissingRepeatArgument
			const ErrNestingDepth
			const ErrTrailingBackslash
			const ErrUnexpectedParen


	
		Flags control the behavior of the parser and record information about regexp context.

		
			func Parse(s string, flags Flags) (*Regexp, error)
			
		
			const ClassNL
			const DotNL
			const FoldCase
			const Literal
			const MatchNL
			const NonGreedy
			const OneLine
			const Perl
			const PerlX
			const POSIX
			const Simple
			const UnicodeGroups
			const WasDollar


	
		An Inst is a single instruction in a regular expression program.

		
			
				// InstAlt, InstAltMatch, InstCapture, InstEmptyWidth

			Op InstOp
			
				// all but InstMatch, InstFail

			Rune []rune
		
			
				MatchEmptyWidth reports whether the instruction matches
				an empty string between the runes before and after.
				It should only be called when i.Op == InstEmptyWidth.

			
				MatchRune reports whether the instruction matches (and consumes) r.
				It should only be called when i.Op == InstRune.

			
				MatchRunePos checks whether the instruction matches (and consumes) r.
				If so, MatchRunePos returns the index of the matching rune pair
				(or, when len(i.Rune) == 1, rune singleton).
				If not, MatchRunePos returns -1.
				MatchRunePos should only be called when i.Op == InstRune.

			(*Inst) String() string
			
		
			*Inst : fmt.Stringer
			
		
			
		
			


	
		An InstOp is an instruction opcode.

		
			( InstOp) String() string
		
			 InstOp : fmt.Stringer
			
		
			
		
			const InstAlt
			const InstAltMatch
			const InstCapture
			const InstEmptyWidth
			const InstFail
			const InstMatch
			const InstNop
			const InstRune
			const InstRune1
			const InstRuneAny
			const InstRuneAnyNotNL


	
		An Op is a single regular expression operator.

		
			( Op) String() string
		
			 Op : fmt.Stringer
			
		
			
		
			const OpAlternate
			const OpAnyChar
			const OpAnyCharNotNL
			const OpBeginLine
			const OpBeginText
			const OpCapture
			const OpCharClass
			const OpConcat
			const OpEmptyMatch
			const OpEndLine
			const OpEndText
			const OpLiteral
			const OpNoMatch
			const OpNoWordBoundary
			const OpPlus
			const OpQuest
			const OpRepeat
			const OpStar
			const OpWordBoundary
			


	
		A Prog is a compiled regular expression program.

		
			Inst []Inst
			
				// number of InstCapture insts in re

			
				// index of start instruction

		
			
				Prefix returns a literal string that all matches for the
				regexp must start with. Complete is true if the prefix
				is the entire match.

			
				StartCond returns the leading empty-width conditions that must
				be true in any match. It returns ^EmptyOp(0) if no matches are possible.

			(*Prog) String() string
			
		
			*Prog : fmt.Stringer
			
		
			func Compile(re *Regexp) (*Prog, error)
		
			


	
		A Regexp is a node in a regular expression syntax tree.

		
			
				// capturing index, for OpCapture

			Flags Flags
			
				// min, max for OpRepeat

			
				// min, max for OpRepeat

			
				// capturing name, for OpCapture

			
				// operator

			
				// matched runes, for OpLiteral, OpCharClass

			
				// storage for short Rune

			
				// subexpressions, if any

			
				// storage for short Sub

		
			
				CapNames walks the regexp to find the names of capturing groups.

			
				Equal reports whether x and y have identical structure.

			
				MaxCap walks the regexp to find the maximum capture index.

			
				Simplify returns a regexp equivalent to re but without counted repetitions
				and with various other simplifications, such as rewriting /(?:a+)+/ to /a+/.
				The resulting regexp will execute correctly but its string representation
				will not produce the same parse tree, because capturing parentheses
				may have been duplicated or removed. For example, the simplified form
				for /(x){1,2}/ is /(x)(x)?/ but both parentheses capture as $1.
				The returned regexp may share structure with or be the original.

			(*Regexp) String() string
			
		
			*Regexp : fmt.Stringer
			
		
			func Parse(s string, flags Flags) (*Regexp, error)
			func (*Regexp).Simplify() *Regexp
			
		
			func Compile(re *Regexp) (*Prog, error)
			func (*Regexp).Equal(y *Regexp) bool
			


	


Package-Level Functions (total 36, in which 4 are exported)


	
		Compile compiles the regexp into a program to be executed.
		The regexp should have been simplified already (returned from re.Simplify).


	
		EmptyOpContext returns the zero-width assertions
		satisfied at the position between the runes r1 and r2.
		Passing r1 == -1 indicates that the position is
		at the beginning of the text.
		Passing r2 == -1 indicates that the position is
		at the end of the text.


	
		IsWordChar reports whether r is considered a “word character”
		during the evaluation of the \b and \B zero-width assertions.
		These assertions are ASCII-only: the word characters are [A-Za-z0-9_].


	
		Parse parses a regular expression string s, controlled by the specified
		Flags, and returns a regular expression parse tree. The syntax is
		described in the top-level comment.


	



Package-Level Constants (total 79, in which 65 are exported)


	const ClassNL Flags = 4 // allow character classes like [^a-z] and [[:space:]] to match newline
	const DotNL Flags = 8 // allow . to match newline
	
		Unexpected error


	
		Parse errors


	const ErrInvalidCharRange ErrorCode = "invalid character class range"
	const ErrInvalidEscape ErrorCode = "invalid escape sequence"
	const ErrInvalidNamedCapture ErrorCode = "invalid named capture"
	const ErrInvalidPerlOp ErrorCode = "invalid or unsupported Perl syntax"
	const ErrInvalidRepeatOp ErrorCode = "invalid nested repetition operator"
	const ErrInvalidRepeatSize ErrorCode = "invalid repeat count"
	const ErrInvalidUTF8 ErrorCode = "invalid UTF-8"
	const ErrLarge ErrorCode = "expression too large"
	const ErrMissingBracket ErrorCode = "missing closing ]"
	const ErrMissingParen ErrorCode = "missing closing )"
	const ErrMissingRepeatArgument ErrorCode = "missing argument to repetition operator"
	const ErrNestingDepth ErrorCode = "expression nests too deeply"
	const ErrTrailingBackslash ErrorCode = "trailing backslash at end of expression"
	const FoldCase Flags = 1 // case-insensitive match
	const Literal Flags = 2 // treat pattern as literal string
	const NonGreedy Flags = 32 // make repetition operators default to non-greedy
	const OneLine Flags = 16 // treat ^ and $ as only matching at beginning and end of text
	const OpAlternate Op = 19 // matches alternation of Subs
	const OpAnyChar Op = 6 // matches any character
	const OpAnyCharNotNL Op = 5 // matches any character except newline
	const OpBeginLine Op = 7 // matches empty string at beginning of line
	const OpBeginText Op = 9 // matches empty string at beginning of text
	const OpCapture Op = 13 // capturing subexpression with index Cap, optional name Name
	const OpCharClass Op = 4 // matches Runes interpreted as range pair list
	const OpConcat Op = 18 // matches concatenation of Subs
	const OpEmptyMatch Op = 2 // matches empty string
	const OpEndLine Op = 8 // matches empty string at end of line
	const OpEndText Op = 10 // matches empty string at end of text
	const OpLiteral Op = 3 // matches Runes sequence
	const OpNoMatch Op = 1 // matches no strings
	const OpNoWordBoundary Op = 12 // matches word non-boundary `\B`
	const OpPlus Op = 15 // matches Sub[0] one or more times
	const OpQuest Op = 16 // matches Sub[0] zero or one times
	const OpRepeat Op = 17 // matches Sub[0] at least Min times, at most Max (Max == -1 is no limit)
	const OpStar Op = 14 // matches Sub[0] zero or more times
	const OpWordBoundary Op = 11 // matches word boundary `\b`
	const Perl Flags = 212 // as close to Perl as possible
	const PerlX Flags = 64 // allow Perl extensions
	const POSIX Flags = 0 // POSIX syntax
	const Simple Flags = 512 // regexp contains no counted repetition
	const UnicodeGroups Flags = 128 // allow \p{Han}, \P{Han} for Unicode group and negation
	const WasDollar Flags = 256 // regexp OpEndText was $, not \z