path: root/devdocs/go/regexp%2Fsyntax%2Findex.html

<h1> Package syntax  </h1>     <ul id="short-nav">
<li><code>import "regexp/syntax"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
</ul>     <h2 id="pkg-overview">Overview </h2> <p>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. </p>
<h3 id="hdr-Syntax">Syntax</h3> <p>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. </p>
<p>Single characters: </p>
<pre data-language="go">.              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
</pre> <p>Composites: </p>
<pre data-language="go">xy             x followed by y
x|y            x or y (prefer x)
</pre> <p>Repetitions: </p>
<pre data-language="go">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
</pre> <p>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. </p>
<p>Grouping: </p>
<pre data-language="go">(re)           numbered capturing group (submatch)
(?P&lt;name&gt;re)   named &amp; numbered capturing group (submatch)
(?&lt;name&gt;re)    named &amp; 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)
</pre> <p>Empty strings: </p>
<pre data-language="go">^              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
</pre> <p>Escape sequences: </p>
<pre data-language="go">\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
</pre> <p>Character class elements: </p>
<pre data-language="go">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)
</pre> <p>Named character classes as character class elements: </p>
<pre data-language="go">[\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})
</pre> <p>Perl character classes (all ASCII-only): </p>
<pre data-language="go">\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_])
</pre> <p>ASCII character classes: </p>
<pre data-language="go">[[: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!"#$%&amp;'()*+,\-./:;&lt;=&gt;?@[\\\]^_`{|}~])
[[: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])
</pre> <p>Unicode character classes are those in unicode.Categories and unicode.Scripts. </p>     <h2 id="pkg-index">Index </h2>  <ul id="manual-nav">
<li><a href="#IsWordChar">func IsWordChar(r rune) bool</a></li>
<li><a href="#EmptyOp">type EmptyOp</a></li>
<li> <a href="#EmptyOpContext">func EmptyOpContext(r1, r2 rune) EmptyOp</a>
</li>
<li><a href="#Error">type Error</a></li>
<li> <a href="#Error.Error">func (e *Error) Error() string</a>
</li>
<li><a href="#ErrorCode">type ErrorCode</a></li>
<li> <a href="#ErrorCode.String">func (e ErrorCode) String() string</a>
</li>
<li><a href="#Flags">type Flags</a></li>
<li><a href="#Inst">type Inst</a></li>
<li> <a href="#Inst.MatchEmptyWidth">func (i *Inst) MatchEmptyWidth(before rune, after rune) bool</a>
</li>
<li> <a href="#Inst.MatchRune">func (i *Inst) MatchRune(r rune) bool</a>
</li>
<li> <a href="#Inst.MatchRunePos">func (i *Inst) MatchRunePos(r rune) int</a>
</li>
<li> <a href="#Inst.String">func (i *Inst) String() string</a>
</li>
<li><a href="#InstOp">type InstOp</a></li>
<li> <a href="#InstOp.String">func (i InstOp) String() string</a>
</li>
<li><a href="#Op">type Op</a></li>
<li> <a href="#Op.String">func (i Op) String() string</a>
</li>
<li><a href="#Prog">type Prog</a></li>
<li> <a href="#Compile">func Compile(re *Regexp) (*Prog, error)</a>
</li>
<li> <a href="#Prog.Prefix">func (p *Prog) Prefix() (prefix string, complete bool)</a>
</li>
<li> <a href="#Prog.StartCond">func (p *Prog) StartCond() EmptyOp</a>
</li>
<li> <a href="#Prog.String">func (p *Prog) String() string</a>
</li>
<li><a href="#Regexp">type Regexp</a></li>
<li> <a href="#Parse">func Parse(s string, flags Flags) (*Regexp, error)</a>
</li>
<li> <a href="#Regexp.CapNames">func (re *Regexp) CapNames() []string</a>
</li>
<li> <a href="#Regexp.Equal">func (x *Regexp) Equal(y *Regexp) bool</a>
</li>
<li> <a href="#Regexp.MaxCap">func (re *Regexp) MaxCap() int</a>
</li>
<li> <a href="#Regexp.Simplify">func (re *Regexp) Simplify() *Regexp</a>
</li>
<li> <a href="#Regexp.String">func (re *Regexp) String() string</a>
</li>
</ul> <h3>Package files</h3> <p>  <span>compile.go</span> <span>doc.go</span> <span>op_string.go</span> <span>parse.go</span> <span>perl_groups.go</span> <span>prog.go</span> <span>regexp.go</span> <span>simplify.go</span>  </p>   <h2 id="IsWordChar">func <span>IsWordChar</span>  </h2> <pre data-language="go">func IsWordChar(r rune) bool</pre> <p>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_]. </p>
<h2 id="EmptyOp">type <span>EmptyOp</span>  </h2> <p>An EmptyOp specifies a kind or mixture of zero-width assertions. </p>
<pre data-language="go">type EmptyOp uint8</pre> <pre data-language="go">const (
    EmptyBeginLine EmptyOp = 1 &lt;&lt; iota
    EmptyEndLine
    EmptyBeginText
    EmptyEndText
    EmptyWordBoundary
    EmptyNoWordBoundary
)</pre> <h3 id="EmptyOpContext">func <span>EmptyOpContext</span>  </h3> <pre data-language="go">func EmptyOpContext(r1, r2 rune) EmptyOp</pre> <p>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. </p>
<h2 id="Error">type <span>Error</span>  </h2> <p>An Error describes a failure to parse a regular expression and gives the offending expression. </p>
<pre data-language="go">type Error struct {
    Code ErrorCode
    Expr string
}
</pre> <h3 id="Error.Error">func (*Error) <span>Error</span>  </h3> <pre data-language="go">func (e *Error) Error() string</pre> <h2 id="ErrorCode">type <span>ErrorCode</span>  </h2> <p>An ErrorCode describes a failure to parse a regular expression. </p>
<pre data-language="go">type ErrorCode string</pre> <pre data-language="go">const (
    // Unexpected error
    ErrInternalError ErrorCode = "regexp/syntax: internal error"

    // Parse errors
    ErrInvalidCharClass      ErrorCode = "invalid character class"
    ErrInvalidCharRange      ErrorCode = "invalid character class range"
    ErrInvalidEscape         ErrorCode = "invalid escape sequence"
    ErrInvalidNamedCapture   ErrorCode = "invalid named capture"
    ErrInvalidPerlOp         ErrorCode = "invalid or unsupported Perl syntax"
    ErrInvalidRepeatOp       ErrorCode = "invalid nested repetition operator"
    ErrInvalidRepeatSize     ErrorCode = "invalid repeat count"
    ErrInvalidUTF8           ErrorCode = "invalid UTF-8"
    ErrMissingBracket        ErrorCode = "missing closing ]"
    ErrMissingParen          ErrorCode = "missing closing )"
    ErrMissingRepeatArgument ErrorCode = "missing argument to repetition operator"
    ErrTrailingBackslash     ErrorCode = "trailing backslash at end of expression"
    ErrUnexpectedParen       ErrorCode = "unexpected )"
    ErrNestingDepth          ErrorCode = "expression nests too deeply"
    ErrLarge                 ErrorCode = "expression too large"
)</pre> <h3 id="ErrorCode.String">func (ErrorCode) <span>String</span>  </h3> <pre data-language="go">func (e ErrorCode) String() string</pre> <h2 id="Flags">type <span>Flags</span>  </h2> <p>Flags control the behavior of the parser and record information about regexp context. </p>
<pre data-language="go">type Flags uint16</pre> <pre data-language="go">const (
    FoldCase      Flags = 1 &lt;&lt; iota // case-insensitive match
    Literal                         // treat pattern as literal string
    ClassNL                         // allow character classes like [^a-z] and [[:space:]] to match newline
    DotNL                           // allow . to match newline
    OneLine                         // treat ^ and $ as only matching at beginning and end of text
    NonGreedy                       // make repetition operators default to non-greedy
    PerlX                           // allow Perl extensions
    UnicodeGroups                   // allow \p{Han}, \P{Han} for Unicode group and negation
    WasDollar                       // regexp OpEndText was $, not \z
    Simple                          // regexp contains no counted repetition

    MatchNL = ClassNL | DotNL

    Perl        = ClassNL | OneLine | PerlX | UnicodeGroups // as close to Perl as possible
    POSIX Flags = 0                                         // POSIX syntax
)</pre> <h2 id="Inst">type <span>Inst</span>  </h2> <p>An Inst is a single instruction in a regular expression program. </p>
<pre data-language="go">type Inst struct {
    Op   InstOp
    Out  uint32 // all but InstMatch, InstFail
    Arg  uint32 // InstAlt, InstAltMatch, InstCapture, InstEmptyWidth
    Rune []rune
}
</pre> <h3 id="Inst.MatchEmptyWidth">func (*Inst) <span>MatchEmptyWidth</span>  </h3> <pre data-language="go">func (i *Inst) MatchEmptyWidth(before rune, after rune) bool</pre> <p>MatchEmptyWidth reports whether the instruction matches an empty string between the runes before and after. It should only be called when i.Op == InstEmptyWidth. </p>
<h3 id="Inst.MatchRune">func (*Inst) <span>MatchRune</span>  </h3> <pre data-language="go">func (i *Inst) MatchRune(r rune) bool</pre> <p>MatchRune reports whether the instruction matches (and consumes) r. It should only be called when i.Op == InstRune. </p>
<h3 id="Inst.MatchRunePos">func (*Inst) <span>MatchRunePos</span>  <span title="Added in Go 1.3">1.3</span> </h3> <pre data-language="go">func (i *Inst) MatchRunePos(r rune) int</pre> <p>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. </p>
<h3 id="Inst.String">func (*Inst) <span>String</span>  </h3> <pre data-language="go">func (i *Inst) String() string</pre> <h2 id="InstOp">type <span>InstOp</span>  </h2> <p>An InstOp is an instruction opcode. </p>
<pre data-language="go">type InstOp uint8</pre> <pre data-language="go">const (
    InstAlt InstOp = iota
    InstAltMatch
    InstCapture
    InstEmptyWidth
    InstMatch
    InstFail
    InstNop
    InstRune
    InstRune1
    InstRuneAny
    InstRuneAnyNotNL
)</pre> <h3 id="InstOp.String">func (InstOp) <span>String</span>  <span title="Added in Go 1.3">1.3</span> </h3> <pre data-language="go">func (i InstOp) String() string</pre> <h2 id="Op">type <span>Op</span>  </h2> <p>An Op is a single regular expression operator. </p>
<pre data-language="go">type Op uint8</pre> <pre data-language="go">const (
    OpNoMatch        Op = 1 + iota // matches no strings
    OpEmptyMatch                   // matches empty string
    OpLiteral                      // matches Runes sequence
    OpCharClass                    // matches Runes interpreted as range pair list
    OpAnyCharNotNL                 // matches any character except newline
    OpAnyChar                      // matches any character
    OpBeginLine                    // matches empty string at beginning of line
    OpEndLine                      // matches empty string at end of line
    OpBeginText                    // matches empty string at beginning of text
    OpEndText                      // matches empty string at end of text
    OpWordBoundary                 // matches word boundary `\b`
    OpNoWordBoundary               // matches word non-boundary `\B`
    OpCapture                      // capturing subexpression with index Cap, optional name Name
    OpStar                         // matches Sub[0] zero or more times
    OpPlus                         // matches Sub[0] one or more times
    OpQuest                        // matches Sub[0] zero or one times
    OpRepeat                       // matches Sub[0] at least Min times, at most Max (Max == -1 is no limit)
    OpConcat                       // matches concatenation of Subs
    OpAlternate                    // matches alternation of Subs
)</pre> <h3 id="Op.String">func (Op) <span>String</span>  <span title="Added in Go 1.11">1.11</span> </h3> <pre data-language="go">func (i Op) String() string</pre> <h2 id="Prog">type <span>Prog</span>  </h2> <p>A Prog is a compiled regular expression program. </p>
<pre data-language="go">type Prog struct {
    Inst   []Inst
    Start  int // index of start instruction
    NumCap int // number of InstCapture insts in re
}
</pre> <h3 id="Compile">func <span>Compile</span>  </h3> <pre data-language="go">func Compile(re *Regexp) (*Prog, error)</pre> <p>Compile compiles the regexp into a program to be executed. The regexp should have been simplified already (returned from re.Simplify). </p>
<h3 id="Prog.Prefix">func (*Prog) <span>Prefix</span>  </h3> <pre data-language="go">func (p *Prog) Prefix() (prefix string, complete bool)</pre> <p>Prefix returns a literal string that all matches for the regexp must start with. Complete is true if the prefix is the entire match. </p>
<h3 id="Prog.StartCond">func (*Prog) <span>StartCond</span>  </h3> <pre data-language="go">func (p *Prog) StartCond() EmptyOp</pre> <p>StartCond returns the leading empty-width conditions that must be true in any match. It returns ^EmptyOp(0) if no matches are possible. </p>
<h3 id="Prog.String">func (*Prog) <span>String</span>  </h3> <pre data-language="go">func (p *Prog) String() string</pre> <h2 id="Regexp">type <span>Regexp</span>  </h2> <p>A Regexp is a node in a regular expression syntax tree. </p>
<pre data-language="go">type Regexp struct {
    Op       Op // operator
    Flags    Flags
    Sub      []*Regexp  // subexpressions, if any
    Sub0     [1]*Regexp // storage for short Sub
    Rune     []rune     // matched runes, for OpLiteral, OpCharClass
    Rune0    [2]rune    // storage for short Rune
    Min, Max int        // min, max for OpRepeat
    Cap      int        // capturing index, for OpCapture
    Name     string     // capturing name, for OpCapture
}
</pre> <h3 id="Parse">func <span>Parse</span>  </h3> <pre data-language="go">func Parse(s string, flags Flags) (*Regexp, error)</pre> <p>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. </p>
<h3 id="Regexp.CapNames">func (*Regexp) <span>CapNames</span>  </h3> <pre data-language="go">func (re *Regexp) CapNames() []string</pre> <p>CapNames walks the regexp to find the names of capturing groups. </p>
<h3 id="Regexp.Equal">func (*Regexp) <span>Equal</span>  </h3> <pre data-language="go">func (x *Regexp) Equal(y *Regexp) bool</pre> <p>Equal reports whether x and y have identical structure. </p>
<h3 id="Regexp.MaxCap">func (*Regexp) <span>MaxCap</span>  </h3> <pre data-language="go">func (re *Regexp) MaxCap() int</pre> <p>MaxCap walks the regexp to find the maximum capture index. </p>
<h3 id="Regexp.Simplify">func (*Regexp) <span>Simplify</span>  </h3> <pre data-language="go">func (re *Regexp) Simplify() *Regexp</pre> <p>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. </p>
<h3 id="Regexp.String">func (*Regexp) <span>String</span>  </h3> <pre data-language="go">func (re *Regexp) String() string</pre><div class="_attribution">
  <p class="_attribution-p">
    &copy; Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
    <a href="http://golang.org/pkg/regexp/syntax/" class="_attribution-link">http://golang.org/pkg/regexp/syntax/</a>
  </p>
</div>