All Downloads are FREE. Search and download functionalities are using the official Maven repository.

groovy.lang.Newify Maven / Gradle / Ivy

There is a newer version: 1.0.1437
Show newest version
/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 */
package groovy.lang;

import org.codehaus.groovy.transform.GroovyASTTransformationClass;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Annotation that supports writing constructor call expressions without the 'new'
 * keyword. Instead they can be written "Ruby-style" as a method call to a 'new'
 * method or "Python-style" by just omitting the 'new' keyword.
 * 

* It allows you to write code snippets like this ("Python-style"): *

 * {@code @Newify([Tree,Leaf])} class MyTreeProcessor {
 *     def myTree = Tree(Tree(Leaf("A"), Leaf("B")), Leaf("C"))
 *     def process() { ... }
 * }
 * 
* or this ("Ruby-style"): *
 * {@code @Newify} class MyTreeProcessor {
 *     def myTree = Tree.new(Tree.new(Leaf.new("A"), Leaf.new("B")), Leaf.new("C"))
 *     def process() { ... }
 * }
 * 
* * After the AST transformation, the following code is passed on for further compilation: *
 * class MyTreeProcessor {
 *     def myTree = new Tree(new Tree(new Leaf("A"), new Leaf("B")), new Leaf("C"))
 *     def process() { ... }
 * }
 * 
* The annotation can be used on a whole class as shown above or selectively on a particular * method, constructor or field. *

* The "Ruby-style" new conversions occur automatically unless the 'auto=false' * flag is given when using the annotation. You might do this if you create a new method * using meta programming. *

* The "Python-style" conversions require you to specify each class on which you want them * to apply. The transformation then works by matching the basename of the provided classes to any * similarly named instance method calls not specifically bound to an object, i.e. associated * with the 'this' object. In other words Leaf("A") would be transformed to * new Leaf("A") but x.Leaf("A") would not be touched. *

* An example showing how to use the annotation at different levels: *

 * {@code @Newify(auto=false, value=Foo)}
 * class Main {
 *     {@code @Newify} // turn auto on for field
 *     def field1 = java.math.BigInteger.new(42)
 *     def field2, field3, field4
 *
 *     {@code @Newify(Bar)}
 *     def process() {
 *         field2 = Bar("my bar")
 *     }
 *
 *     {@code @Newify(Baz)}
 *     Main() {
 *         field3 = Foo("my foo")
 *         field4 = Baz("my baz")
 *     }
 * }
 * 
* * The annotation is intended to be used sparingly; perhaps in DSL scenarios or when * using deeply nested structural types. In particular, there is no support for using * the facility with two similarly named classes from different packages at the same time. * Though it is OK to have different packages in different contexts. Also, there is * no support for turning "Ruby-style" conversions off at the method, constructor or * field level if already turned on at the class level. * * @author Paul King */ @java.lang.annotation.Documented @Retention(RetentionPolicy.SOURCE) @Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE, ElementType.FIELD, ElementType.LOCAL_VARIABLE}) @GroovyASTTransformationClass("org.codehaus.groovy.transform.NewifyASTTransformation") public @interface Newify { Class[] value() default {}; /** * @return if automatic conversion of "Ruby-style" new method calls should occur */ boolean auto() default true; }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy