*: lots of polish

This commit grew into a monster. I ran out of energy trying to split
everything up. For the most part, this commit is about polishing and
writing docs.

.github/workflows/ci.yml

@@ -124,6 +124,8 @@ jobs:
       run: ${{ env.CARGO }} test --verbose --manifest-path regex-automata/Cargo.toml $TARGET
     - name: Run regex-lite tests
       run: ${{ env.CARGO }} test --verbose --manifest-path regex-lite/Cargo.toml $TARGET
+    - name: Run regex-cli tests
+      run: ${{ env.CARGO }} test --verbose --manifest-path regex-cli/Cargo.toml $TARGET
 
   # This job runs a stripped down version of CI to test the MSRV. The specific
   # reason for doing this is that the regex crate's dev-dependencies tend to

Cargo.toml

@@ -45,6 +45,15 @@ std = [
   "regex-automata/std",
   "regex-syntax/std",
 ]
+# This feature enables the 'log' crate to emit messages. This is usually
+# only useful for folks working on the regex crate itself, but can be useful
+# if you're trying hard to do some performance hacking on regex patterns
+# themselves. Note that you'll need to pair this with a crate like 'env_logger'
+# to actually emit the log messages somewhere.
+logging = [
+  "aho-corasick?/logging",
+  "regex-automata/logging",
+]
 # The 'use_std' feature is DEPRECATED. It will be removed in regex 2. Until
 # then, it is an alias for the 'std' feature.
 use_std = ["std"]
@@ -64,11 +73,6 @@ perf = [
   "perf-inline",
   "perf-literal",
 ]
-# Enables fast caching. (If disabled, caching is still used, but is slower.)
-# Currently, this feature has no effect. It used to remove the thread_local
-# dependency and use a slower internal cache, but now the default cache has
-# been improved and thread_local is no longer a dependency at all.
-perf-cache = []
 # Enables use of a lazy DFA when possible.
 perf-dfa = ["regex-automata/hybrid"]
 # Enables use of a fully compiled DFA when possible.
@@ -86,6 +90,11 @@ perf-literal = [
   "dep:memchr",
   "regex-automata/perf-literal",
 ]
+# Enables fast caching. (If disabled, caching is still used, but is slower.)
+# Currently, this feature has no effect. It used to remove the thread_local
+# dependency and use a slower internal cache, but now the default cache has
+# been improved and thread_local is no longer a dependency at all.
+perf-cache = []
 
 
 # UNICODE DATA FEATURES
@@ -151,7 +160,7 @@ unstable = ["pattern"]
 # by default if the unstable feature is enabled.
 pattern = []
 
-# For very fast prefix literal matching.
+# For very fast multi-prefix literal matching.
 [dependencies.aho-corasick]
 version = "1.0.0"
 optional = true
@@ -160,23 +169,22 @@ optional = true
 [dependencies.memchr]
 version = "2.5.0"
 optional = true
-
-# For parsing regular expressions.
-[dependencies.regex-syntax]
-path = "regex-syntax"
-version = "0.7.2"
-default-features = false
-
 # For the actual regex engines.
 [dependencies.regex-automata]
 path = "regex-automata"
 version = "0.3.0"
 default-features = false
 features = ["alloc", "syntax", "meta", "nfa-pikevm"]
 
+# For parsing regular expressions.
+[dependencies.regex-syntax]
+path = "regex-syntax"
+version = "0.7.2"
+default-features = false
+
 [dev-dependencies]
 # For examples.
-lazy_static = "1"
+once_cell = "1.17.1"
 # For property based tests.
 quickcheck = { version = "1.0.3", default-features = false }
 # To check README's example