[groovy] 02/02: GROOVY-9925: Groovy match operator documentation should contain real examples and slashy strings reminder

[pa...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

paulk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git

commit e0b399365cd33a32fc09b861d1e0f6b045541a05
Author: Paul King <pa...@asert.com.au>
AuthorDate: Tue Feb 2 10:40:34 2021 +1000

    GROOVY-9925: Groovy match operator documentation should contain real examples and slashy strings reminder
---
 src/spec/doc/core-operators.adoc   | 22 ++++++++++++++++++++++
 src/spec/test/OperatorsTest.groovy | 21 +++++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/src/spec/doc/core-operators.adoc b/src/spec/doc/core-operators.adoc
index 9dace42..e9a5f04 100644
--- a/src/spec/doc/core-operators.adoc
+++ b/src/spec/doc/core-operators.adoc
@@ -522,6 +522,11 @@ include::../test/OperatorsTest.groovy[tags=pattern_op_variants,indent=0]
 <3> the dollar-slashy string lets you use slashes and the dollar sign without having to escape them
 <4> you can also use a GString!
 
+[NOTE]
+While you can use most String forms with the Pattern, Find and Match operators,
+we recommend using the slashy string most of the time to save having to
+remember the otherwise needed escaping requirements.
+
 === Find operator
 
 Alternatively to building a pattern, you can use the find operator `=~` to directly create a `java.util.regex.Matcher` instance:
@@ -551,6 +556,23 @@ include::../test/OperatorsTest.groovy[tags=pattern_matcher_strict_op,indent=0]
 <2> the return type of `==~` is therefore a `boolean`
 <3> equivalent to calling `if (text ==~ /match/)`
 
+=== Comparing Find vs Match operators
+
+Typically, the match operator is used when the pattern involves a single exact match, otherwise
+the find operator might be more useful.
+[source,groovy]
+----
+include::../test/OperatorsTest.groovy[tags=pattern_find_vs_matcher,indent=0]
+----
+<1> equivalent, but explicit ^ and $ are discouraged since they aren't needed
+<2> no match because of leading space
+<3> one match
+<4> ^ and $ indicate exact match required
+<5> zero matches
+<6> one match, greedily starting at first word
+<7> one match, ignores leading space
+<8> two matches
+
 == Other operators
 
 === Spread operator
diff --git a/src/spec/test/OperatorsTest.groovy b/src/spec/test/OperatorsTest.groovy
index a833afa..0393a47 100644
--- a/src/spec/test/OperatorsTest.groovy
+++ b/src/spec/test/OperatorsTest.groovy
@@ -373,6 +373,27 @@ assert user.@name == 'Bob'                   // <1>
             throw new RuntimeException("Should not reach that point!")
         }
         // end::pattern_matcher_strict_op[]
+
+        // tag::pattern_find_vs_matcher[]
+        assert 'two words' ==~ /\S+\s+\S+/
+        assert 'two words' ==~ /^\S+\s+\S+$/         // <1>
+        assert !(' leading space' ==~ /\S+\s+\S+/)   // <2>
+
+        def m1 = 'two words' =~ /^\S+\s+\S+$/
+        assert m1.size() == 1                          // <3>
+        def m2 = 'now three words' =~ /^\S+\s+\S+$/    // <4>
+        assert m2.size() == 0                          // <5>
+        def m3 = 'now three words' =~ /\S+\s+\S+/
+        assert m3.size() == 1                          // <6>
+        assert m3[0] == 'now three'
+        def m4 = ' leading space' =~ /\S+\s+\S+/
+        assert m4.size() == 1                          // <7>
+        assert m4[0] == 'leading space'
+        def m5 = 'and with four words' =~ /\S+\s+\S+/
+        assert m5.size() == 2                          // <8>
+        assert m5[0] == 'and with'
+        assert m5[1] == 'four words'
+        // end::pattern_find_vs_matcher[]
     }
 
     void testSpreadDotOperator() {