subject:"groovy git commit\: GROOVY\-7956\: Provide an AST transformation which improves named parameter support \(doco and support changing visibility\)"

groovy git commit: GROOVY-7956: Provide an AST transformation which improves named parameter support (doco and support changing visibility)

2018-02-21 Thread paulk

Repository: groovy
Updated Branches:
  refs/heads/GROOVY_2_5_X d11d56425 -> 488f42dd1


GROOVY-7956: Provide an AST transformation which improves named parameter 
support (doco and support changing visibility)


Project: http://git-wip-us.apache.org/repos/asf/groovy/repo
Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/488f42dd
Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/488f42dd
Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/488f42dd

Branch: refs/heads/GROOVY_2_5_X
Commit: 488f42dd182c530a1f8762b6191277c7ec184727
Parents: d11d564
Author: paulk 
Authored: Wed Feb 21 18:18:17 2018 +1000
Committer: paulk 
Committed: Wed Feb 21 18:18:17 2018 +1000

--
 .../groovy/groovy/transform/NamedVariant.java   |  63 +++
 .../groovy/transform/VisibilityOptions.java |  43 
 .../groovy/transform/options/Visibility.java|  27 +
 .../groovy/ast/tools/VisibilityUtils.java   | 110 +++
 .../NamedVariantASTTransformation.java  |   6 +-
 .../transform/NamedVariantTransformTest.groovy  |  32 +++---
 6 files changed, 265 insertions(+), 16 deletions(-)
--


http://git-wip-us.apache.org/repos/asf/groovy/blob/488f42dd/src/main/groovy/groovy/transform/NamedVariant.java
--
diff --git a/src/main/groovy/groovy/transform/NamedVariant.java 
b/src/main/groovy/groovy/transform/NamedVariant.java
index 8db0529..2a10470 100644
--- a/src/main/groovy/groovy/transform/NamedVariant.java
+++ b/src/main/groovy/groovy/transform/NamedVariant.java
@@ -26,9 +26,72 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Allows construction of a named-arg equivalent method or constructor.
+ * The method or constructor will have at least a first argument of type
+ * {@code Map} and may have more arguments. As such, it can be called
+ * using Groovy's named-arg syntax. The original method/constructor is retained
+ * and is called by the generated method/constructor.
+ *
+ * One benefit of this approach is the potential for improved type checking.
+ * The annotated "tuple" method/constructor can be type rich and will be 
checked
+ * as such during normal compilation. The generated method/constructor using
+ * the map argument will be named-argument friendly but the map also hides
+ * type information. The generated method however contains no business logic
+ * so the chance of errors is minimal.
+ *
+ * Any arguments identified as named arguments will be supplied as
+ * part of the map. Any additional arguments are supplied in the normal
+ * tuple style.
+ *
+ * Named arguments are identified in one of three ways:
+ * 
+ * Use one or more {@code @NamedParam} annotations to explicitly 
identify such arguments
+ * Use one or more {@code @NamedDelegate} annotations to explicitly 
identify such arguments as
+ * delegate arguments
+ * If no arguments with {@code @NamedParam} or {@code @NamedDelegate} 
annotations are found the
+ * first argument is assumed to be an implicit named delegate
+ * 
+ * Named arguments will be supplied via the map with their property name 
(configurable via
+ * annotation attributes within {@code @NamedParam}) being the key and value 
being the argument value.
+ * For named delegates, any properties of the delegate can become map keys. 
Duplicate keys across
+ * delegates or named parameters are not allowed. Delegate arguments must be
+ * compatible with Groovy's {@code as} cast operation from a {@code Map}.
+ *
+ * Here is an example using the implicit delegate approach.
+ * 
+ * import groovy.transform.*
+ *
+ * {@code @ToString(includeNames=true, includeFields=true)}
+ * class Color {
+ * Integer r, g, b
+ * }
+ *
+ * {@code @NamedVariant}
+ * String foo(Color shade) {
+ * shade
+ * }
+ *
+ * def result = foo(g: 12, b: 42, r: 12)
+ * assert result.toString() == 'Color(r:12, g:12, b:42)'
+ * 
+ * The generated method will be something like this:
+ * 
+ * String foo(Map args) {
+ * return foo(args as Color)
+ * }
+ * 
+ * The generated method/constructor retains the visibility and return type of 
the original
+ * but the {@code @VisibilityOptions} annotation can be added to the 
visibility. You could have the
+ * annotated method/constructor private for instance but have the generated 
one be public.
+ */
 @Incubating
 @Retention(RetentionPolicy.SOURCE)
 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
 
@GroovyASTTransformationClass("org.codehaus.groovy.transform.NamedVariantASTTransformation")
 public @interface NamedVariant {
+/**
+ * If specified, must match the "id" attribute in the VisibilityOptions 
annotation.
+ */
+String visibilityId() default Undefined.STRING;
 }
\ No newline at end of file

http://git-wi

groovy git commit: GROOVY-7956: Provide an AST transformation which improves named parameter support (doco and support changing visibility)

2018-02-21 Thread paulk

Repository: groovy
Updated Branches:
  refs/heads/GROOVY_2_6_X 5ad98acc2 -> 17d3feb31


GROOVY-7956: Provide an AST transformation which improves named parameter 
support (doco and support changing visibility)


Project: http://git-wip-us.apache.org/repos/asf/groovy/repo
Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/17d3feb3
Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/17d3feb3
Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/17d3feb3

Branch: refs/heads/GROOVY_2_6_X
Commit: 17d3feb3180d570113883281d3c513bebae3cfbb
Parents: 5ad98ac
Author: paulk 
Authored: Wed Feb 21 18:18:17 2018 +1000
Committer: paulk 
Committed: Wed Feb 21 18:19:17 2018 +1000

--
 .../groovy/groovy/transform/NamedVariant.java   |  63 +++
 .../groovy/transform/VisibilityOptions.java |  43 
 .../groovy/transform/options/Visibility.java|  27 +
 .../groovy/ast/tools/VisibilityUtils.java   | 110 +++
 .../NamedVariantASTTransformation.java  |   6 +-
 .../transform/NamedVariantTransformTest.groovy  |  32 +++---
 6 files changed, 265 insertions(+), 16 deletions(-)
--


http://git-wip-us.apache.org/repos/asf/groovy/blob/17d3feb3/src/main/groovy/groovy/transform/NamedVariant.java
--
diff --git a/src/main/groovy/groovy/transform/NamedVariant.java 
b/src/main/groovy/groovy/transform/NamedVariant.java
index 8db0529..2a10470 100644
--- a/src/main/groovy/groovy/transform/NamedVariant.java
+++ b/src/main/groovy/groovy/transform/NamedVariant.java
@@ -26,9 +26,72 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Allows construction of a named-arg equivalent method or constructor.
+ * The method or constructor will have at least a first argument of type
+ * {@code Map} and may have more arguments. As such, it can be called
+ * using Groovy's named-arg syntax. The original method/constructor is retained
+ * and is called by the generated method/constructor.
+ *
+ * One benefit of this approach is the potential for improved type checking.
+ * The annotated "tuple" method/constructor can be type rich and will be 
checked
+ * as such during normal compilation. The generated method/constructor using
+ * the map argument will be named-argument friendly but the map also hides
+ * type information. The generated method however contains no business logic
+ * so the chance of errors is minimal.
+ *
+ * Any arguments identified as named arguments will be supplied as
+ * part of the map. Any additional arguments are supplied in the normal
+ * tuple style.
+ *
+ * Named arguments are identified in one of three ways:
+ * 
+ * Use one or more {@code @NamedParam} annotations to explicitly 
identify such arguments
+ * Use one or more {@code @NamedDelegate} annotations to explicitly 
identify such arguments as
+ * delegate arguments
+ * If no arguments with {@code @NamedParam} or {@code @NamedDelegate} 
annotations are found the
+ * first argument is assumed to be an implicit named delegate
+ * 
+ * Named arguments will be supplied via the map with their property name 
(configurable via
+ * annotation attributes within {@code @NamedParam}) being the key and value 
being the argument value.
+ * For named delegates, any properties of the delegate can become map keys. 
Duplicate keys across
+ * delegates or named parameters are not allowed. Delegate arguments must be
+ * compatible with Groovy's {@code as} cast operation from a {@code Map}.
+ *
+ * Here is an example using the implicit delegate approach.
+ * 
+ * import groovy.transform.*
+ *
+ * {@code @ToString(includeNames=true, includeFields=true)}
+ * class Color {
+ * Integer r, g, b
+ * }
+ *
+ * {@code @NamedVariant}
+ * String foo(Color shade) {
+ * shade
+ * }
+ *
+ * def result = foo(g: 12, b: 42, r: 12)
+ * assert result.toString() == 'Color(r:12, g:12, b:42)'
+ * 
+ * The generated method will be something like this:
+ * 
+ * String foo(Map args) {
+ * return foo(args as Color)
+ * }
+ * 
+ * The generated method/constructor retains the visibility and return type of 
the original
+ * but the {@code @VisibilityOptions} annotation can be added to the 
visibility. You could have the
+ * annotated method/constructor private for instance but have the generated 
one be public.
+ */
 @Incubating
 @Retention(RetentionPolicy.SOURCE)
 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
 
@GroovyASTTransformationClass("org.codehaus.groovy.transform.NamedVariantASTTransformation")
 public @interface NamedVariant {
+/**
+ * If specified, must match the "id" attribute in the VisibilityOptions 
annotation.
+ */
+String visibilityId() default Undefined.STRING;
 }
\ No newline at end of file

http://git-wi

groovy git commit: GROOVY-7956: Provide an AST transformation which improves named parameter support (doco and support changing visibility)

2018-02-21 Thread paulk

Repository: groovy
Updated Branches:
  refs/heads/master 965bd6ee3 -> 0110400db


GROOVY-7956: Provide an AST transformation which improves named parameter 
support (doco and support changing visibility)


Project: http://git-wip-us.apache.org/repos/asf/groovy/repo
Commit: http://git-wip-us.apache.org/repos/asf/groovy/commit/0110400d
Tree: http://git-wip-us.apache.org/repos/asf/groovy/tree/0110400d
Diff: http://git-wip-us.apache.org/repos/asf/groovy/diff/0110400d

Branch: refs/heads/master
Commit: 0110400dbb637e19755c39e21a3cfd74e777b872
Parents: 965bd6e
Author: paulk 
Authored: Wed Feb 21 18:18:17 2018 +1000
Committer: paulk 
Committed: Wed Feb 21 18:19:51 2018 +1000

--
 .../groovy/groovy/transform/NamedVariant.java   |  63 +++
 .../groovy/transform/VisibilityOptions.java |  43 
 .../groovy/transform/options/Visibility.java|  27 +
 .../groovy/ast/tools/VisibilityUtils.java   | 110 +++
 .../NamedVariantASTTransformation.java  |   6 +-
 .../transform/NamedVariantTransformTest.groovy  |  32 +++---
 6 files changed, 265 insertions(+), 16 deletions(-)
--


http://git-wip-us.apache.org/repos/asf/groovy/blob/0110400d/src/main/groovy/groovy/transform/NamedVariant.java
--
diff --git a/src/main/groovy/groovy/transform/NamedVariant.java 
b/src/main/groovy/groovy/transform/NamedVariant.java
index 8db0529..2a10470 100644
--- a/src/main/groovy/groovy/transform/NamedVariant.java
+++ b/src/main/groovy/groovy/transform/NamedVariant.java
@@ -26,9 +26,72 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Allows construction of a named-arg equivalent method or constructor.
+ * The method or constructor will have at least a first argument of type
+ * {@code Map} and may have more arguments. As such, it can be called
+ * using Groovy's named-arg syntax. The original method/constructor is retained
+ * and is called by the generated method/constructor.
+ *
+ * One benefit of this approach is the potential for improved type checking.
+ * The annotated "tuple" method/constructor can be type rich and will be 
checked
+ * as such during normal compilation. The generated method/constructor using
+ * the map argument will be named-argument friendly but the map also hides
+ * type information. The generated method however contains no business logic
+ * so the chance of errors is minimal.
+ *
+ * Any arguments identified as named arguments will be supplied as
+ * part of the map. Any additional arguments are supplied in the normal
+ * tuple style.
+ *
+ * Named arguments are identified in one of three ways:
+ * 
+ * Use one or more {@code @NamedParam} annotations to explicitly 
identify such arguments
+ * Use one or more {@code @NamedDelegate} annotations to explicitly 
identify such arguments as
+ * delegate arguments
+ * If no arguments with {@code @NamedParam} or {@code @NamedDelegate} 
annotations are found the
+ * first argument is assumed to be an implicit named delegate
+ * 
+ * Named arguments will be supplied via the map with their property name 
(configurable via
+ * annotation attributes within {@code @NamedParam}) being the key and value 
being the argument value.
+ * For named delegates, any properties of the delegate can become map keys. 
Duplicate keys across
+ * delegates or named parameters are not allowed. Delegate arguments must be
+ * compatible with Groovy's {@code as} cast operation from a {@code Map}.
+ *
+ * Here is an example using the implicit delegate approach.
+ * 
+ * import groovy.transform.*
+ *
+ * {@code @ToString(includeNames=true, includeFields=true)}
+ * class Color {
+ * Integer r, g, b
+ * }
+ *
+ * {@code @NamedVariant}
+ * String foo(Color shade) {
+ * shade
+ * }
+ *
+ * def result = foo(g: 12, b: 42, r: 12)
+ * assert result.toString() == 'Color(r:12, g:12, b:42)'
+ * 
+ * The generated method will be something like this:
+ * 
+ * String foo(Map args) {
+ * return foo(args as Color)
+ * }
+ * 
+ * The generated method/constructor retains the visibility and return type of 
the original
+ * but the {@code @VisibilityOptions} annotation can be added to the 
visibility. You could have the
+ * annotated method/constructor private for instance but have the generated 
one be public.
+ */
 @Incubating
 @Retention(RetentionPolicy.SOURCE)
 @Target({ElementType.METHOD, ElementType.CONSTRUCTOR})
 
@GroovyASTTransformationClass("org.codehaus.groovy.transform.NamedVariantASTTransformation")
 public @interface NamedVariant {
+/**
+ * If specified, must match the "id" attribute in the VisibilityOptions 
annotation.
+ */
+String visibilityId() default Undefined.STRING;
 }
\ No newline at end of file

http://git-wip-us.apache.

groovy git commit: GROOVY-7956: Provide an AST transformation which improves named parameter support (doco and support changing visibility)

groovy git commit: GROOVY-7956: Provide an AST transformation which improves named parameter support (doco and support changing visibility)

groovy git commit: GROOVY-7956: Provide an AST transformation which improves named parameter support (doco and support changing visibility)

3 matches

Site Navigation

Mail list logo

Footer information