      1
      2
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
     13
     14
     15
     16
     17
     18
     19
     20
     21
     22
     23
     24
     25
     26
     27
     28
     29
     30
     31
     32
     33
     34
     35
     36
     37
     38
     39
     40
     41
     42
     43
     44
     45
     46
     47
     48
     49
     50
     51
     52
     53
     54
     55
     56
     57
     58
     59
     60
     61
     62
     63
     64
     65
     66
     67
     68
     69
     70
     71
     72
     73
     74
     75
     76
     77
     78
     79
     80
     81
     82
     83
     84
     85
     86
     87
     88
     89
     90
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206

    use ast;
    use hir;

    use Result;

    /// A builder for a regular expression parser.
    ///
    /// This builder permits modifying configuration options for the parser.
    ///
    /// This type combines the builder options for both the
    /// [AST `ParserBuilder`](ast/parse/struct.ParserBuilder.html)
    /// and the
    /// [HIR `TranslatorBuilder`](hir/translate/struct.TranslatorBuilder.html).
    #[derive(Clone, Debug, Default)]
    pub struct ParserBuilder {
        ast: ast::parse::ParserBuilder,
        hir: hir::translate::TranslatorBuilder,
    }

    impl ParserBuilder {
        /// Create a new parser builder with a default configuration.
        pub fn new() -> ParserBuilder {
            ParserBuilder::default()
        }

        /// Build a parser from this configuration with the given pattern.
        pub fn build(&self) -> Parser {
            Parser {
                ast: self.ast.build(),
                hir: self.hir.build(),
            }
        }

        /// Set the nesting limit for this parser.
        ///
        /// The nesting limit controls how deep the abstract syntax tree is allowed
        /// to be. If the AST exceeds the given limit (e.g., with too many nested
        /// groups), then an error is returned by the parser.
        ///
        /// The purpose of this limit is to act as a heuristic to prevent stack
        /// overflow for consumers that do structural induction on an `Ast` using
        /// explicit recursion. While this crate never does this (instead using
        /// constant stack space and moving the call stack to the heap), other
        /// crates may.
        ///
        /// This limit is not checked until the entire Ast is parsed. Therefore,
        /// if callers want to put a limit on the amount of heap space used, then
        /// they should impose a limit on the length, in bytes, of the concrete
        /// pattern string. In particular, this is viable since this parser
        /// implementation will limit itself to heap space proportional to the
        /// lenth of the pattern string.
        ///
        /// Note that a nest limit of `0` will return a nest limit error for most
        /// patterns but not all. For example, a nest limit of `0` permits `a` but
        /// not `ab`, since `ab` requires a concatenation, which results in a nest
        /// depth of `1`. In general, a nest limit is not something that manifests
        /// in an obvious way in the concrete syntax, therefore, it should not be
        /// used in a granular way.
        pub fn nest_limit(&mut self, limit: u32) -> &mut ParserBuilder {
            self.ast.nest_limit(limit);
            self
        }

        /// Whether to support octal syntax or not.
        ///
        /// Octal syntax is a little-known way of uttering Unicode codepoints in
        /// a regular expression. For example, `a`, `\x61`, `\u0061` and
        /// `\141` are all equivalent regular expressions, where the last example
        /// shows octal syntax.
        ///
        /// While supporting octal syntax isn't in and of itself a problem, it does
        /// make good error messages harder. That is, in PCRE based regex engines,
        /// syntax like `\0` invokes a backreference, which is explicitly
        /// unsupported in Rust's regex engine. However, many users expect it to
        /// be supported. Therefore, when octal support is disabled, the error
        /// message will explicitly mention that backreferences aren't supported.
        ///
        /// Octal syntax is disabled by default.
        pub fn octal(&mut self, yes: bool) -> &mut ParserBuilder {
            self.ast.octal(yes);
            self
        }

        /// When enabled, the parser will permit the construction of a regular
        /// expression that may match invalid UTF-8.
        ///
        /// When disabled (the default), the parser is guaranteed to produce
        /// an expression that will only ever match valid UTF-8 (otherwise, the
        /// parser will return an error).
        ///
        /// Perhaps surprisingly, when invalid UTF-8 isn't allowed, a negated ASCII
        /// word boundary (uttered as `(?-u:\B)` in the concrete syntax) will cause
        /// the parser to return an error. Namely, a negated ASCII word boundary
        /// can result in matching positions that aren't valid UTF-8 boundaries.
        pub fn allow_invalid_utf8(&mut self, yes: bool) -> &mut ParserBuilder {
            self.hir.allow_invalid_utf8(yes);
            self
        }

        /// Enable verbose mode in the regular expression.
        ///
        /// When enabled, verbose mode permits insigificant whitespace in many
        /// places in the regular expression, as well as comments. Comments are
        /// started using `#` and continue until the end of the line.
        ///
        /// By default, this is disabled. It may be selectively enabled in the
        /// regular expression by using the `x` flag regardless of this setting.
        pub fn ignore_whitespace(&mut self, yes: bool) -> &mut ParserBuilder {
            self.ast.ignore_whitespace(yes);
            self
        }

        /// Enable or disable the case insensitive flag by default.
        ///
        /// By default this is disabled. It may alternatively be selectively
        /// enabled in the regular expression itself via the `i` flag.
        pub fn case_insensitive(&mut self, yes: bool) -> &mut ParserBuilder {
            self.hir.case_insensitive(yes);
            self
        }

        /// Enable or disable the multi-line matching flag by default.
        ///
        /// By default this is disabled. It may alternatively be selectively
        /// enabled in the regular expression itself via the `m` flag.
        pub fn multi_line(&mut self, yes: bool) -> &mut ParserBuilder {
            self.hir.multi_line(yes);
            self
        }

        /// Enable or disable the "dot matches any character" flag by default.
        ///
        /// By default this is disabled. It may alternatively be selectively
        /// enabled in the regular expression itself via the `s` flag.
        pub fn dot_matches_new_line(
            &mut self,
            yes: bool,
        ) -> &mut ParserBuilder {
            self.hir.dot_matches_new_line(yes);
            self
        }

        /// Enable or disable the "swap greed" flag by default.
        ///
        /// By default this is disabled. It may alternatively be selectively
        /// enabled in the regular expression itself via the `U` flag.
        pub fn swap_greed(&mut self, yes: bool) -> &mut ParserBuilder {
            self.hir.swap_greed(yes);
            self
        }

        /// Enable or disable the Unicode flag (`u`) by default.
        ///
        /// By default this is **enabled**. It may alternatively be selectively
        /// disabled in the regular expression itself via the `u` flag.
        ///
        /// Note that unless `allow_invalid_utf8` is enabled (it's disabled by
        /// default), a regular expression will fail to parse if Unicode mode is
        /// disabled and a sub-expression could possibly match invalid UTF-8.
        pub fn unicode(&mut self, yes: bool) -> &mut ParserBuilder {
            self.hir.unicode(yes);
            self
        }
    }

    /// A convenience parser for regular expressions.
    ///
    /// This parser takes as input a regular expression pattern string (the
    /// "concrete syntax") and returns a high-level intermediate representation
    /// (the HIR) suitable for most types of analysis. In particular, this parser
    /// hides the intermediate state of producing an AST (the "abstract syntax").
    /// The AST is itself far more complex than the HIR, so this parser serves as a
    /// convenience for never having to deal with it at all.
    ///
    /// If callers have more fine grained use cases that need an AST, then please
    /// see the [`ast::parse`](ast/parse/index.html) module.
    ///
    /// A `Parser` can be configured in more detail via a
    /// [`ParserBuilder`](struct.ParserBuilder.html).
    #[derive(Clone, Debug)]
    pub struct Parser {
        ast: ast::parse::Parser,
        hir: hir::translate::Translator,
    }

    impl Parser {
        /// Create a new parser with a default configuration.
        ///
        /// The parser can be run with `parse` method. The parse method returns
        /// a high level intermediate representation of the given regular
        /// expression.
        ///
        /// To set configuration options on the parser, use
        /// [`ParserBuilder`](struct.ParserBuilder.html).
        pub fn new() -> Parser {
            ParserBuilder::new().build()
        }

        /// Parse the regular expression into a high level intermediate
        /// representation.
        pub fn parse(&mut self, pattern: &str) -> Result<hir::Hir> {
            let ast = self.ast.parse(pattern)?;
            let hir = self.hir.translate(pattern, &ast)?;
            Ok(hir)
        }
    }

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)