refactor(preg): wrap the preg_* $matches maps in newtypes

The five IndexMap shapes that the preg_* functions and Preg fill in are
now distinct types generated by preg_match_map!, so a matches map no
longer interchanges with any other map of the same key and value type.

Index<usize> is kept alongside Index<&Q> because call sites such as
config_command and event_dispatcher reach for a group by its position in
the map rather than by its capture key.

1 files changed, 32 insertions, 27 deletions

diff --git a/crates/shirabe-pcre/src/preg.rs b/crates/shirabe-pcre/src/preg.rs
index 0448f81a..3a997ad3 100644
--- a/crates/shirabe-pcre/src/preg.rs
+++ b/crates/shirabe-pcre/src/preg.rs
@@ -11,13 +11,24 @@
 //!
 //! See docs/dev/regex-porting.md for more detailed regex porting rules.
 
-use indexmap::IndexMap;
-pub use shirabe_php_shim::CaptureKey;
+pub use shirabe_php_shim::{CaptureKey, PregMatches, PregMatchesAll, PregMatchesAllWithOffsets};
 use shirabe_php_shim::{
     PregPattern, preg_grep, preg_match_all_offset_capture_unmatched_as_null, preg_match_all2,
-    preg_match2, preg_match2_unmatched_as_null, preg_replace_callback, preg_replace2,
+    preg_match_map, preg_match2, preg_match2_unmatched_as_null, preg_replace_callback,
+    preg_replace2,
 };
 
+preg_match_map! {
+    /// A single match's `$matches` as `Preg` hands it to callers: an unmatched capture group is
+    /// absent rather than held as a null value.
+    pub struct PregMatchedGroups(CaptureKey => String);
+}
+
+preg_match_map! {
+    /// The named capture groups of a single match, keyed by group name alone.
+    pub struct PregNamedGroups(String => String);
+}
+
 #[derive(Debug)]
 pub struct Preg;
 
@@ -25,7 +36,7 @@ impl Preg {
     pub fn match3(
         pattern: impl PregPattern,
         subject: &str,
-        matches: Option<&mut IndexMap<CaptureKey, String>>,
+        matches: Option<&mut PregMatchedGroups>,
     ) -> bool {
         Self::match4(pattern, subject, matches, 0)
     }
@@ -33,10 +44,10 @@ impl Preg {
     pub fn match4(
         pattern: impl PregPattern,
         subject: &str,
-        matches: Option<&mut IndexMap<CaptureKey, String>>,
+        matches: Option<&mut PregMatchedGroups>,
         offset: usize,
     ) -> bool {
-        let mut internal: IndexMap<CaptureKey, Option<String>> = IndexMap::new();
+        let mut internal = PregMatches::new();
         let result = preg_match2_unmatched_as_null(pattern, subject, &mut internal, offset);
 
         if let Some(out) = matches {
@@ -47,14 +58,14 @@ impl Preg {
     }
 
     pub fn match_all(pattern: impl PregPattern, subject: &str) -> usize {
-        let mut dummy = IndexMap::new();
+        let mut dummy = PregMatchesAll::new();
         preg_match_all2(pattern, subject, &mut dummy)
     }
 
     pub fn match_all2(
         pattern: impl PregPattern,
         subject: &str,
-        matches: &mut IndexMap<CaptureKey, Vec<Option<String>>>,
+        matches: &mut PregMatchesAll,
     ) -> usize {
         preg_match_all2(pattern, subject, matches)
     }
@@ -62,9 +73,9 @@ impl Preg {
     fn match_all_with_offsets5(
         pattern: impl PregPattern,
         subject: &str,
-        matches: Option<&mut IndexMap<CaptureKey, Vec<(Option<String>, i64)>>>,
+        matches: Option<&mut PregMatchesAllWithOffsets>,
     ) -> usize {
-        let mut internal: IndexMap<CaptureKey, Vec<(Option<String>, i64)>> = IndexMap::new();
+        let mut internal = PregMatchesAllWithOffsets::new();
         let result =
             preg_match_all_offset_capture_unmatched_as_null(pattern, subject, &mut internal);
 
@@ -98,14 +109,12 @@ impl Preg {
         preg_replace2(pattern, replacement, subject, limit, Some(count))
     }
 
-    pub fn replace_callback<F: FnMut(&IndexMap<CaptureKey, String>) -> String>(
+    pub fn replace_callback<F: FnMut(&PregMatchedGroups) -> String>(
         pattern: impl PregPattern,
         mut replacement: F,
         subject: &str,
     ) -> String {
-        let adapter = |internal: &IndexMap<CaptureKey, Option<String>>| {
-            Ok(replacement(&drop_null_matches_ref(internal)))
-        };
+        let adapter = |internal: &PregMatches| Ok(replacement(&drop_null_matches_ref(internal)));
 
         preg_replace_callback(pattern, adapter, subject).expect("$replacement cannot fail")
     }
@@ -124,7 +133,7 @@ impl Preg {
     pub fn is_match3(
         pattern: impl PregPattern,
         subject: &str,
-        matches: Option<&mut IndexMap<CaptureKey, String>>,
+        matches: Option<&mut PregMatchedGroups>,
     ) -> bool {
         Self::match4(pattern, subject, matches, 0)
     }
@@ -132,7 +141,7 @@ impl Preg {
     pub fn is_match4(
         pattern: impl PregPattern,
         subject: &str,
-        matches: Option<&mut IndexMap<CaptureKey, String>>,
+        matches: Option<&mut PregMatchedGroups>,
         offset: usize,
     ) -> bool {
         Self::match4(pattern, subject, matches, offset)
@@ -141,9 +150,9 @@ impl Preg {
     pub fn is_match_named(
         pattern: impl PregPattern,
         subject: &str,
-        matches: &mut IndexMap<String, String>,
+        matches: &mut PregNamedGroups,
     ) -> bool {
-        let mut internal: IndexMap<CaptureKey, Option<String>> = IndexMap::new();
+        let mut internal = PregMatches::new();
         let result = preg_match2_unmatched_as_null(pattern, subject, &mut internal, 0);
 
         matches.clear();
@@ -162,7 +171,7 @@ impl Preg {
     ) -> Option<Vec<String>> {
         // Classic preg_match semantics (no PREG_UNMATCHED_AS_NULL): trailing
         // unmatched groups are truncated, interior unmatched groups become "".
-        let mut internal: IndexMap<CaptureKey, Option<String>> = IndexMap::new();
+        let mut internal = PregMatches::new();
         let result = preg_match2(pattern, subject, &mut internal, 0);
 
         if !result {
@@ -193,7 +202,7 @@ impl Preg {
     pub fn is_match_all(
         pattern: impl PregPattern,
         subject: &str,
-        matches: &mut IndexMap<CaptureKey, Vec<Option<String>>>,
+        matches: &mut PregMatchesAll,
     ) -> bool {
         Self::match_all2(pattern, subject, matches) > 0
     }
@@ -201,7 +210,7 @@ impl Preg {
     pub fn is_match_all_with_offsets3(
         pattern: impl PregPattern,
         subject: &str,
-        matches: Option<&mut IndexMap<CaptureKey, Vec<(Option<String>, i64)>>>,
+        matches: Option<&mut PregMatchesAllWithOffsets>,
     ) -> bool {
         Self::match_all_with_offsets5(pattern, subject, matches) > 0
     }
@@ -209,18 +218,14 @@ impl Preg {
 
 // Drops `null` (unmatched) groups, mirroring how the public `string`-valued
 // `matches` map represents PHP's `string|null` entries by their absence.
-fn drop_null_matches(
-    matches: IndexMap<CaptureKey, Option<String>>,
-) -> IndexMap<CaptureKey, String> {
+fn drop_null_matches(matches: PregMatches) -> PregMatchedGroups {
     matches
         .into_iter()
         .filter_map(|(key, value)| value.map(|value| (key, value)))
         .collect()
 }
 
-fn drop_null_matches_ref(
-    matches: &IndexMap<CaptureKey, Option<String>>,
-) -> IndexMap<CaptureKey, String> {
+fn drop_null_matches_ref(matches: &PregMatches) -> PregMatchedGroups {
     matches
         .iter()
         .filter_map(|(key, value)| value.clone().map(|value| (key.clone(), value)))