Improve docs

ltrzesniewski · Sep 21, 2024 · 4b1b8b8 · 4b1b8b8
1 parent d6a9586
commit 4b1b8b8
Show file tree

Hide file tree

Showing 5 changed files with 98 additions and 8 deletions.
diff --git a/src/PCRE.NET.Tests/PcreNet/DocumentationTests.cs b/src/PCRE.NET.Tests/PcreNet/DocumentationTests.cs
@@ -79,14 +79,26 @@ public void should_have_expected_remarks(MethodInfo method)
         AssertContainsIfParam(p => p.Name is "callout" or "onCallout", "(?C<arg>)");
         AssertContainsIfParam(p => p.Name is "replacement" && p.ParameterType == typeof(string), "supported placeholders");
 
+        AssertXmlContainsIf(method.DeclaringType == typeof(PcreRegex) && method.Name == nameof(PcreRegex.Replace), """<seealso cref="M:PCRE.PcreRegex.Substitute(System.String,System.String)" />""");
+        AssertXmlContainsIf(method.DeclaringType == typeof(PcreRegex) && method.Name == nameof(PcreRegex.Substitute), """<seealso cref="M:PCRE.PcreRegex.Replace(System.String,System.String)" />""");
+
         void AssertContainsIf(bool condition, string expectedString)
-            => Assert.That(doc.Value, condition
-                               ? Does.Contain(expectedString)
-                               : Does.Not.Contain(expectedString)
+            => Assert.That(
+                doc.Value, condition
+                    ? Does.Contain(expectedString)
+                    : Does.Not.Contain(expectedString)
             );
 
         void AssertContainsIfParam(Func<ParameterInfo, bool> param, string expectedString)
             => AssertContainsIf(method.GetParameters().Any(param), expectedString);
+
+        void AssertXmlContainsIf(bool condition, string expectedString)
+            => Assert.That(
+                doc.ToString(), condition
+                    ? Does.Contain(expectedString)
+                    : Does.Not.Contain(expectedString)
+            );
+
     }
 
     private static Dictionary<string, XElement> GetMembers()

diff --git a/src/PCRE.NET/Internal/PcreEnumExtensions.cs b/src/PCRE.NET/Internal/PcreEnumExtensions.cs
@@ -12,6 +12,10 @@ public static uint ToPatternOptions(this PcreOptions options)
     public static uint ToPatternOptions(this PcreMatchOptions options)
         => (uint)((long)options & 0xFFFFFFFF);
 
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public static uint ToPatternOptions(this PcreSubstituteOptions options)
+        => (uint)((long)options & 0xFFFFFFFF);
+
     public static PcreJitCompileOptions ToJitCompileOptions(this PcreOptions options)
     {
         var jitOptions = PcreJitCompileOptions.None;

diff --git a/src/PCRE.NET/PcreRegex.Replace.cs b/src/PCRE.NET/PcreRegex.Replace.cs
@@ -16,6 +16,7 @@ public partial class PcreRegex
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="replacementString"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     [Pure]
     public string Replace(string subject, string replacement)
         => Replace(subject, replacement, -1, 0);
@@ -25,6 +26,7 @@ public string Replace(string subject, string replacement)
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="replacementString"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     [Pure]
     public string Replace(string subject, string replacement, int count)
         => Replace(subject, replacement, count, 0);
@@ -34,6 +36,7 @@ public string Replace(string subject, string replacement, int count)
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="replacementString" or @name="startIndex"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     [Pure]
     public string Replace(string subject, string replacement, int count, int startIndex)
     {
@@ -45,11 +48,13 @@ public string Replace(string subject, string replacement, int count, int startIn
 
     /// <include file='PcreRegex.xml' path='/doc/method[@name="Replace"]/*'/>
     /// <include file='PcreRegex.xml' path='/doc/param[@name="subject" or @name="replacementFunc"]'/>
+    /// <seealso cref="Substitute(string,string)"/>
     public string Replace(string subject, Func<PcreMatch, string> replacementFunc)
         => Replace(subject, replacementFunc, -1, 0);
 
     /// <include file='PcreRegex.xml' path='/doc/method[@name="Replace"]/*'/>
     /// <include file='PcreRegex.xml' path='/doc/param[@name="subject" or @name="replacementFunc" or @name="count"]'/>
+    /// <seealso cref="Substitute(string,string)"/>
     public string Replace(string subject, Func<PcreMatch, string> replacementFunc, int count)
         => Replace(subject, replacementFunc, count, 0);
 
@@ -58,6 +63,7 @@ public string Replace(string subject, Func<PcreMatch, string> replacementFunc, i
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="startIndex"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     public string Replace(string subject, Func<PcreMatch, string> replacementFunc, int count, int startIndex)
     {
         if (subject == null)
@@ -94,6 +100,7 @@ public string Replace(string subject, Func<PcreMatch, string> replacementFunc, i
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static" or @name="replacementString"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     [Pure]
     public static string Replace(string subject, string pattern, string replacement)
         => Replace(subject, pattern, replacement, PcreOptions.None, -1, 0);
@@ -103,6 +110,7 @@ public static string Replace(string subject, string pattern, string replacement)
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static" or @name="replacementString"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     [Pure]
     public static string Replace(string subject, string pattern, string replacement, PcreOptions options)
         => Replace(subject, pattern, replacement, options, -1, 0);
@@ -112,6 +120,7 @@ public static string Replace(string subject, string pattern, string replacement,
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static" or @name="replacementString"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     [Pure]
     public static string Replace(string subject, string pattern, string replacement, PcreOptions options, int count)
         => Replace(subject, pattern, replacement, options, count, 0);
@@ -121,6 +130,7 @@ public static string Replace(string subject, string pattern, string replacement,
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static" or @name="replacementString" or @name="startIndex"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     [Pure]
     public static string Replace(string subject, string pattern, string replacement, PcreOptions options, int count, int startIndex)
         => new PcreRegex(pattern, options).Replace(subject, replacement, count, startIndex);
@@ -130,6 +140,7 @@ public static string Replace(string subject, string pattern, string replacement,
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     public static string Replace(string subject, string pattern, Func<PcreMatch, string> replacementFunc)
         => Replace(subject, pattern, replacementFunc, PcreOptions.None, -1, 0);
 
@@ -138,6 +149,7 @@ public static string Replace(string subject, string pattern, Func<PcreMatch, str
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     public static string Replace(string subject, string pattern, Func<PcreMatch, string> replacementFunc, PcreOptions options)
         => Replace(subject, pattern, replacementFunc, options, -1, 0);
 
@@ -146,6 +158,7 @@ public static string Replace(string subject, string pattern, Func<PcreMatch, str
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     public static string Replace(string subject, string pattern, Func<PcreMatch, string> replacementFunc, PcreOptions options, int count)
         => Replace(subject, pattern, replacementFunc, options, count, 0);
 
@@ -154,6 +167,7 @@ public static string Replace(string subject, string pattern, Func<PcreMatch, str
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="static" or @name="startIndex"]/*'/>
     /// </remarks>
+    /// <seealso cref="Substitute(string,string)"/>
     public static string Replace(string subject, string pattern, Func<PcreMatch, string> replacementFunc, PcreOptions options, int count, int startIndex)
         => new PcreRegex(pattern, options).Replace(subject, replacementFunc, count, startIndex);
 }
diff --git a/src/PCRE.NET/PcreRegex.Substitute.cs b/src/PCRE.NET/PcreRegex.Substitute.cs
@@ -1,6 +1,7 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using System.Diagnostics.Contracts;
+using PCRE.Internal;
 
 namespace PCRE;
 
@@ -14,6 +15,7 @@ public partial class PcreRegex
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="replacementStringPcre2"]/*'/>
     /// </remarks>
+    /// <seealso cref="Replace(string,string)"/>
     [Pure]
     public string Substitute(string subject, string replacement)
         => Substitute(subject, replacement, PcreSubstituteOptions.None, 0);
@@ -23,6 +25,7 @@ public string Substitute(string subject, string replacement)
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="replacementStringPcre2"]/*'/>
     /// </remarks>
+    /// <seealso cref="Replace(string,string)"/>
     [Pure]
     public string Substitute(string subject, string replacement, PcreSubstituteOptions options)
         => Substitute(subject, replacement, options, 0);
@@ -32,6 +35,7 @@ public string Substitute(string subject, string replacement, PcreSubstituteOptio
     /// <remarks>
     /// <include file='PcreRegex.xml' path='/doc/remarks[@name="replacementStringPcre2" or @name="startIndex"]/*'/>
     /// </remarks>
+    /// <seealso cref="Replace(string,string)"/>
     [Pure]
     public string Substitute(string subject, string replacement, PcreSubstituteOptions options, int startIndex)
     {
@@ -43,7 +47,7 @@ public string Substitute(string subject, string replacement, PcreSubstituteOptio
         if (unchecked((uint)startIndex > (uint)subject.Length))
             ThrowInvalidStartIndex();
 
-        return InternalRegex.Substitute(subject, replacement, (uint)options, startIndex);
+        return InternalRegex.Substitute(subject, replacement, options.ToPatternOptions(), startIndex);
     }
 
     // TODO: Static methods

diff --git a/src/PCRE.NET/PcreRegex.xml b/src/PCRE.NET/PcreRegex.xml
@@ -20,13 +20,17 @@
 
   <method name="Replace">
     <summary>
-      Replaces matches found in the given subject string, using PCRE.NET replacement syntax.
+      Replaces matches found in the given subject string, using the
+      <b>PCRE.NET replacement syntax</b>
+      (similar to the one used by the
+      <see cref="System.Text.RegularExpressions.Regex"/>
+      class).
     </summary>
   </method>
 
   <method name="Substitute">
     <summary>
-      Replaces matches found in the given subject string, using the PCRE2 replacement syntax.
+      Replaces matches found in the given subject string, using the <b>PCRE2 replacement syntax</b>.
     </summary>
   </method>
 
@@ -130,13 +134,65 @@
   <remarks name="replacementStringPcre2">
     <para>
       The supported placeholders in the replacement string are specific to the PCRE2 library.
+      <list type="bullet">
+        <item>
+          <c>$n</c>
+          - The value of the capture group <c>n</c> (by index or name).
+        </item>
+        <item>
+          <c>${n}</c>
+          - The value of the capture group <c>n</c> (by index or name).
+        </item>
+        <item>
+          <c>$$</c>
+          - A literal dollar sign.
+        </item>
+        <item>
+          <c>$*MARK</c>
+          or
+          <c>${*MARK}</c>
+          - The last encountered backtracking control verb name.
+        </item>
+      </list>
+      When the option
+      <see cref="PcreSubstituteOptions.SubstituteExtended"/>
+      is enabled, additional syntax is available:
+      <list type="bullet">
+        <item>
+          Backslash in a replacement string is interpreted as an escape character.
+          The usual forms such as <c>\x{ddd}</c> can be used to specify particular character codes, and backslash
+          followed by any non-alphanumeric character quotes that character.
+          Extended quoting can be coded using <c>\Q...\E</c>, exactly as in pattern strings.
+        </item>
+        <item>
+          Case forcing: <c>\U</c> and <c>\L</c> change to upper or lower case forcing, respectively,
+          and <c>\E</c> (when not terminating a <c>\Q</c> quoted sequence) reverts to no case forcing.
+          The sequences <c>\u</c> and <c>\l</c> force the next character (if it is a letter) to upper
+          or lower case, respectively, and then the state automatically reverts to no case forcing.
+          However, if <c>\u</c> is immediately followed by <c>\L</c> or <c>\l</c> is immediately followed by <c>\U</c>,
+          the next character's case is forced by the first escape sequence, and subsequent characters by the second.
+          This provides a "title casing" facility that can be applied to group captures.
+        </item>
+        <item>
+          <c>${n:-string}</c>
+          - If group <c>n</c> is set, its value is inserted;
+          if not, the string is expanded and the result inserted.
+          This is a shorthand for <c>${n:+${n}:string}</c>.
+        </item>
+        <item>
+          <c>${n:+string1:string2}</c>
+          - Strings that are expanded and inserted when group <c>n</c> is set or unset, respectively.
+        </item>
+      </list>
     </para>
   </remarks>
 
   <remarks name="callout">
     <para>
-      Within a regular expression, <c>(?C&lt;arg&gt;)</c> indicates a point at which the external function is to be called.
-      Different callout points can be identified by putting a number less than 256 after the letter C. The default value is zero.
+      Within a regular expression, <c>(?C&lt;arg&gt;)</c> indicates a point at which the external function is to be
+      called.
+      Different callout points can be identified by putting a number less than 256 after the letter C. The default value
+      is zero.
       Alternatively, the argument may be a delimited string. The starting delimiter must be one of
       <c>` ' " ^ % # $ {</c>
       and the ending delimiter is the same as the start, except for <c>{</c>, where the ending delimiter is <c>}</c>.