[groovy] branch master updated: Tweak GINQ user guide

[sunlan]

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

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


The following commit(s) were added to refs/heads/master by this push:
     new b7b26ee  Tweak GINQ user guide
b7b26ee is described below

commit b7b26ee01955482f318e6914d4c783ad54fe4156
Author: Daniel Sun <sun...@apache.org>
AuthorDate: Sun Jul 25 18:35:29 2021 +0800

    Tweak GINQ user guide
---
 .../src/main/groovy/groovy/ginq/transform/GQ.java      | 11 +++++++++++
 .../groovy-ginq/src/spec/doc/ginq-userguide.adoc       | 18 ++++++++++++++++++
 .../spec/test/org/apache/groovy/ginq/GinqTest.groovy   | 18 ++++++++++++++++++
 3 files changed, 47 insertions(+)

diff --git 
a/subprojects/groovy-ginq/src/main/groovy/groovy/ginq/transform/GQ.java 
b/subprojects/groovy-ginq/src/main/groovy/groovy/ginq/transform/GQ.java
index 535268c..683e857 100644
--- a/subprojects/groovy-ginq/src/main/groovy/groovy/ginq/transform/GQ.java
+++ b/subprojects/groovy-ginq/src/main/groovy/groovy/ginq/transform/GQ.java
@@ -38,7 +38,18 @@ import java.lang.annotation.Target;
 @Target({ElementType.METHOD})
 
@GroovyASTTransformationClass("org.apache.groovy.ginq.transform.GinqASTTransformation")
 public @interface GQ {
+    /**
+     * Whether to optimize the GINQ AST
+     */
     boolean optimize() default true;
+
+    /**
+     * Whether to enable parallel querying
+     */
     boolean parallel() default false;
+
+    /**
+     * Specify the GINQ AST walker to customize GINQ behaviour
+     */
     String astWalker() default 
"org.apache.groovy.ginq.provider.collection.GinqAstWalker";
 }
diff --git a/subprojects/groovy-ginq/src/spec/doc/ginq-userguide.adoc 
b/subprojects/groovy-ginq/src/spec/doc/ginq-userguide.adoc
index 9ed15c5..ebc9de3 100644
--- a/subprojects/groovy-ginq/src/spec/doc/ginq-userguide.adoc
+++ b/subprojects/groovy-ginq/src/spec/doc/ginq-userguide.adoc
@@ -87,6 +87,24 @@ def list = result.toList() // get the list from GINQ result
 [WARNING]
 Currently GINQ can not work well when STC is enabled.
 
+Also, GINQ could be written in a method marked with `@GQ`:
+```groovy
+@GQ
+def someGinqMethod() {
+    /* GINQ CODE */
+}
+```
+For example,
+[source, groovy]
+----
+include::../test/org/apache/groovy/ginq/GinqTest.groovy[tags=ginq_method_01,indent=0]
+----
+
+[source, groovy]
+----
+include::../test/org/apache/groovy/ginq/GinqTest.groovy[tags=ginq_method_02,indent=0]
+----
+
 === GINQ Syntax
 ==== Data Source
 The data source for GINQ could be specified by `from` clause, which is 
equivalent to SQL's `FROM`.
diff --git 
a/subprojects/groovy-ginq/src/spec/test/org/apache/groovy/ginq/GinqTest.groovy 
b/subprojects/groovy-ginq/src/spec/test/org/apache/groovy/ginq/GinqTest.groovy
index acff398..a15d946 100644
--- 
a/subprojects/groovy-ginq/src/spec/test/org/apache/groovy/ginq/GinqTest.groovy
+++ 
b/subprojects/groovy-ginq/src/spec/test/org/apache/groovy/ginq/GinqTest.groovy
@@ -6113,6 +6113,22 @@ class GinqTest {
     }
 
     @Test
+    void "testGinqMethod - GQ - 0"() {
+        assertScript '''
+// tag::ginq_method_01[]
+            @groovy.ginq.transform.GQ
+            def ginq(b, e) {
+                from n in [1, 2, 3, 4, 5, 6]
+                where b < n && n < e
+                select n
+            }
+            
+            assert [3, 4] == ginq(2, 5).toList()
+// end::ginq_method_01[]
+        '''
+    }
+
+    @Test
     void "testGinqMethod - GQ - 1"() {
         assertScript '''
             import groovy.ginq.transform.GQ
@@ -6185,6 +6201,7 @@ class GinqTest {
     @Test
     void "testGinqMethod - GQ - 5"() {
         assertScript '''
+// tag::ginq_method_02[]
             import groovy.ginq.transform.GQ
             
             @GQ(parallel=true)
@@ -6195,6 +6212,7 @@ class GinqTest {
             }
             
             assert [1] == ginq(2).toList()
+// end::ginq_method_02[]
         '''
     }