cli: add engine flag

This permits switching between the different regex engine modes that
ripgrep supports. The purpose of this flag is to make it easier to
extend ripgrep with additional regex engines.

Closes #1488, Closes #1502

CHANGELOG.md

@@ -9,6 +9,8 @@ Deprecations:
   `--no-pcre2-unicode` and `--pcre2-unicode` are aliases to `--no-unicode`
   and `--unicode`, respectively. The `--[no-]pcre2-unicode` flags may be
   removed in a future release.
+* The `--auto-hybrid-regex` flag is deprecated. Instead, use the new `--engine`
+  flag with the `auto` value.
 
 Performance improvements:
 
@@ -35,6 +37,8 @@ Feature enhancements:
   Add `--no-require-git` flag to allow ripgrep to respect gitignores anywhere.
 * [FEATURE #1420](https://github.com/BurntSushi/ripgrep/pull/1420):
   Add `--no-ignore-exclude` to disregard rules in `.git/info/exclude` files.
+* [FEATURE #1488](https://github.com/BurntSushi/ripgrep/pull/1488):
+  Add '--engine' flag for easier switching between regex engines.
 * [FEATURE 75cbe88f](https://github.com/BurntSushi/ripgrep/commit/75cbe88f):
   Add `--no-unicode` flag. This works on all supported regex engines.
 

README.md

@@ -109,7 +109,8 @@ increases the times to `2.640s` for ripgrep and `10.277s` for GNU grep.
   Among other things, this makes it possible to use look-around and
   backreferences in your patterns, which are not supported in ripgrep's default
   regex engine. PCRE2 support can be enabled with `-P/--pcre2` (use PCRE2
-  always) or `--auto-hybrid-regex` (use PCRE2 only if needed).
+  always) or `--auto-hybrid-regex` (use PCRE2 only if needed). An alternative
+  syntax is provided via the `--engine (default|pcre2|auto-hybrid)` option.
 * ripgrep supports searching files in text encodings other than UTF-8, such
   as UTF-16, latin-1, GBK, EUC-JP, Shift_JIS and more. (Some support for
   automatically detecting UTF-16 is provided. Other text encodings must be

complete/_rg

@@ -78,6 +78,13 @@ _rg() {
     {-E+,--encoding=}'[specify text encoding of files to search]: :_rg_encodings'
     $no'--no-encoding[use default text encoding]'
 
+    + '(engine)' # Engine choice options
+    '--engine=[select which regex engine to use]:when:((
+      default\:"use default engine"
+      pcre2\:"identical to --pcre2"
+      auto\:"identical to --auto-hybrid-regex"
+    ))'
+
     + file # File-input options
     '(1)*'{-f+,--file=}'[specify file containing patterns to search for]: :_files'
 

crates/core/app.rs

@@ -505,6 +505,13 @@ impl RGArg {
         self
     }
 
+    /// Sets the default value of this argument when not specified at
+    /// runtime.
+    fn default_value(mut self, value: &'static str) -> RGArg {
+        self.claparg = self.claparg.default_value(value);
+        self
+    }
+
     /// Sets the default value of this argument if and only if the argument
     /// given is present.
     fn default_value_if(
@@ -563,6 +570,7 @@ pub fn all_args_and_flags() -> Vec<RGArg> {
     flag_debug(&mut args);
     flag_dfa_size_limit(&mut args);
     flag_encoding(&mut args);
+    flag_engine(&mut args);
     flag_file(&mut args);
     flag_files(&mut args);
     flag_files_with_matches(&mut args);
@@ -706,6 +714,8 @@ fn flag_auto_hybrid_regex(args: &mut Vec<RGArg>) {
     const SHORT: &str = "Dynamically use PCRE2 if necessary.";
     const LONG: &str = long!(
         "\
+DEPRECATED. Use --engine instead.
+
 When this flag is used, ripgrep will dynamically choose between supported regex
 engines depending on the features used in a pattern. When ripgrep chooses a
 regex engine, it applies that choice for every regex provided to ripgrep (e.g.,
@@ -738,14 +748,16 @@ This flag can be disabled with --no-auto-hybrid-regex.
         .long_help(LONG)
         .overrides("no-auto-hybrid-regex")
         .overrides("pcre2")
-        .overrides("no-pcre2");
+        .overrides("no-pcre2")
+        .overrides("engine");
     args.push(arg);
 
     let arg = RGArg::switch("no-auto-hybrid-regex")
         .hidden()
         .overrides("auto-hybrid-regex")
         .overrides("pcre2")
-        .overrides("no-pcre2");
+        .overrides("no-pcre2")
+        .overrides("engine");
     args.push(arg);
 }
 
@@ -1182,6 +1194,41 @@ This flag can be disabled with --no-encoding.
     args.push(arg);
 }
 
+fn flag_engine(args: &mut Vec<RGArg>) {
+    const SHORT: &str = "Specify which regexp engine to use.";
+    const LONG: &str = long!(
+        "\
+Specify which regular expression engine to use. When you choose a regex engine,
+it applies that choice for every regex provided to ripgrep (e.g., via multiple
+-e/--regexp or -f/--file flags).
+
+Accepted values are 'default', 'pcre2', or 'auto'.
+
+The default value is 'default', which is the fastest and should be good for
+most use cases. The 'pcre2' engine is generally useful when you want to use
+features such as look-around or backreferences. 'auto' will dynamically choose
+between supported regex engines depending on the features used in a pattern on
+a best effort basis.
+
+Note that the 'pcre2' engine is an optional ripgrep feature. If PCRE2 wasn't
+including in your build of ripgrep, then using this flag will result in ripgrep
+printing an error message and exiting.
+
+This overrides previous uses of --pcre2 and --auto-hybrid-regex flags.
+"
+    );
+    let arg = RGArg::flag("engine", "ENGINE")
+        .help(SHORT)
+        .long_help(LONG)
+        .possible_values(&["default", "pcre2", "auto"])
+        .default_value("default")
+        .overrides("pcre2")
+        .overrides("no-pcre2")
+        .overrides("auto-hybrid-regex")
+        .overrides("no-auto-hybrid-regex");
+    args.push(arg);
+}
+
 fn flag_file(args: &mut Vec<RGArg>) {
     const SHORT: &str = "Search for patterns from the given file.";
     const LONG: &str = long!(
@@ -2300,14 +2347,16 @@ This flag can be disabled with --no-pcre2.
         .long_help(LONG)
         .overrides("no-pcre2")
         .overrides("auto-hybrid-regex")
-        .overrides("no-auto-hybrid-regex");
+        .overrides("no-auto-hybrid-regex")
+        .overrides("engine");
     args.push(arg);
 
     let arg = RGArg::switch("no-pcre2")
         .hidden()
         .overrides("pcre2")
         .overrides("auto-hybrid-regex")
-        .overrides("no-auto-hybrid-regex");
+        .overrides("no-auto-hybrid-regex")
+        .overrides("engine");
     args.push(arg);
 }
 

crates/core/args.rs

@@ -582,7 +582,8 @@ impl ArgMatches {
         } else if self.is_present("auto-hybrid-regex") {
             self.matcher_engine("auto", patterns)
         } else {
-            self.matcher_engine("default", patterns)
+            let engine = self.value_of_lossy("engine").unwrap();
+            self.matcher_engine(&engine, patterns)
         }
     }