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

5 files changed, 68 insertions, 6 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c579739..8454b46c 100644
--- a/CHANGELOG.md
+++ b/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.
 
diff --git a/README.md b/README.md
index c9c2f6ee..760643fd 100644
--- a/README.md
+++ b/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
diff --git a/complete/_rg b/complete/_rg
index 44d63e63..399647f7 100644
--- a/complete/_rg
+++ b/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'
 
diff --git a/crates/core/app.rs b/crates/core/app.rs
index f6af7993..d65b41fa 100644
--- a/crates/core/app.rs
+++ b/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);
 }
 
diff --git a/crates/core/args.rs b/crates/core/args.rs
index 17f08b9f..a31d28a4 100644
--- a/crates/core/args.rs
+++ b/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)
         }
     }