groovy.lang

## Class Closure

- java.lang.Object
- - groovy.lang.GroovyObjectSupport
  - - groovy.lang.Closure

- All Implemented Interfaces:
    GroovyObject, Serializable, Cloneable, Runnable
  Direct Known Subclasses:
    CurriedClosure, IteratorClosureAdapter, MethodClosure

      public abstract class Closure
      extends GroovyObjectSupport
      implements Cloneable, Runnable, Serializable

  Represents any closure object in Groovy.

  Groovy allows instances of Closures to be called in a short form. For example:

         def a = 1
         def c = {a}
         assert c() == 1

  To be able to use a Closure in this way with your own subclass, you need to provide a doCall method with any signature you want to. This ensures that `getMaximumNumberOfParameters()` and `getParameterTypes()` will work too without any additional code. If no doCall method is provided a closure must be used in its long form like

         def a = 1
         def c = {a}
         assert c.call() == 1

  Version:
    $Revision: 21242 $
  Author:
    James Strachan, John Wilson, Jochen Theodorou, Graeme Rocher
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DELEGATE_FIRST` With this resolveStrategy set the closure will attempt to resolve property references to the delegate first
    `static int` | `DELEGATE_ONLY` With this resolveStrategy set the closure will resolve property references to the delegate only and entirely bypass the owner
    `static int` | `DONE`
    `protected int` | `maximumNumberOfParameters`
    `static int` | `OWNER_FIRST` With this resolveStrategy set the closure will attempt to resolve property references to the owner first
    `static int` | `OWNER_ONLY` With this resolveStrategy set the closure will resolve property references to the owner only and not call the delegate at all
    `protected Class[]` | `parameterTypes`
    `static int` | `SKIP`
    `static int` | `TO_SELF` With this resolveStrategy set the closure will resolve property references to itself and go through the usual MetaClass look-up process.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Closure(Object owner)` Constructor used when the "this" object for the Closure is null.
    `Closure(Object owner, Object thisObject)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Closure` | `asWritable()`
    `Object` | `call()` Invokes the closure without any parameters, returning any value if applicable.
    `Object` | `call(Object arguments)` Invokes the closure, returning any value if applicable.
    `Object` | `call(Object[] args)`
    `Object` | `clone()`
    `Closure` | `curry(Object[] arguments)` Support for Closure currying.
    `Object` | `getDelegate()`
    `int` | `getDirective()`
    `int` | `getMaximumNumberOfParameters()`
    `Object` | `getOwner()`
    `Class[]` | `getParameterTypes()`
    `Object` | `getProperty(String property)` Retrieves a property value.
    `int` | `getResolveStrategy()` Gets the strategy which the closure users to resolve methods and properties
    `Object` | `getThisObject()`
    `boolean` | `isCase(Object candidate)`
    `Closure` | `ncurry(int n, Object[] arguments)` Support for Closure currying at a given index.
    `Closure` | `rcurry(Object[] arguments)` Support for Closure "right" currying.
    `void` | `run()`
    `void` | `setDelegate(Object delegate)` Allows the delegate to be changed such as when performing markup building
    `void` | `setDirective(int directive)`
    `void` | `setProperty(String property, Object newValue)` Sets the given property to the new value.
    `void` | `setResolveStrategy(int resolveStrategy)` Sets the strategy which the closure uses to resolve property references.
    `protected static Object` | `throwRuntimeException(Throwable throwable)`

    - ### Methods inherited from class groovy.lang.GroovyObjectSupport

      `getMetaClass, invokeMethod, setMetaClass`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### OWNER_FIRST

          public static final int OWNER_FIRST

      With this resolveStrategy set the closure will attempt to resolve property references to the owner first
      See Also:
        Constant Field Values

    - #### DELEGATE_FIRST

          public static final int DELEGATE_FIRST

      With this resolveStrategy set the closure will attempt to resolve property references to the delegate first
      See Also:
        Constant Field Values

    - #### OWNER_ONLY

          public static final int OWNER_ONLY

      With this resolveStrategy set the closure will resolve property references to the owner only and not call the delegate at all
      See Also:
        Constant Field Values

    - #### DELEGATE_ONLY

          public static final int DELEGATE_ONLY

      With this resolveStrategy set the closure will resolve property references to the delegate only and entirely bypass the owner
      See Also:
        Constant Field Values

    - #### TO_SELF

          public static final int TO_SELF

      With this resolveStrategy set the closure will resolve property references to itself and go through the usual MetaClass look-up process. This allows the developer to override getProperty using ExpandoMetaClass of the closure itself
      See Also:
        Constant Field Values

    - #### DONE

          public static final int DONE

      See Also:
        Constant Field Values

    - #### SKIP

          public static final int SKIP

      See Also:
        Constant Field Values

    - #### parameterTypes

          protected Class[] parameterTypes

    - #### maximumNumberOfParameters

          protected int maximumNumberOfParameters

  - ### Constructor Detail

    - #### Closure

          public Closure(Object owner,
                 Object thisObject)

    - #### Closure

          public Closure(Object owner)

      Constructor used when the "this" object for the Closure is null. This is rarely the case in normal Groovy usage.
      Parameters:
        `owner` - the Closure owner

  - ### Method Detail

    - #### setResolveStrategy

          public void setResolveStrategy(int resolveStrategy)

      Sets the strategy which the closure uses to resolve property references. The default is Closure.OWNER_FIRST
      Parameters:
        `resolveStrategy` - The resolve strategy to set
      See Also:
        `DELEGATE_FIRST`, `DELEGATE_ONLY`, `OWNER_FIRST`, `OWNER_ONLY`, `TO_SELF`

    - #### getResolveStrategy

          public int getResolveStrategy()

      Gets the strategy which the closure users to resolve methods and properties
      Returns:
        The resolve strategy
      See Also:
        `DELEGATE_FIRST`, `DELEGATE_ONLY`, `OWNER_FIRST`, `OWNER_ONLY`, `TO_SELF`

    - #### getThisObject

          public Object getThisObject()

    - #### getProperty

          public Object getProperty(String property)

      Description copied from interface: `GroovyObject`
      Retrieves a property value.
      Specified by:
        `getProperty` in interface `GroovyObject`
      Overrides:
        `getProperty` in class `GroovyObjectSupport`
      Parameters:
        `property` - the name of the property of interest
      Returns:
        the given property

    - #### setProperty

          public void setProperty(String property,
                         Object newValue)

      Description copied from interface: `GroovyObject`
      Sets the given property to the new value.
      Specified by:
        `setProperty` in interface `GroovyObject`
      Overrides:
        `setProperty` in class `GroovyObjectSupport`
      Parameters:
        `property` - the name of the property of interest
        `newValue` - the new value for the property

    - #### isCase

          public boolean isCase(Object candidate)

    - #### call

          public Object call()

      Invokes the closure without any parameters, returning any value if applicable.
      Returns:
        the value if applicable or null if there is no return statement in the closure

    - #### call

          public Object call(Object[] args)

    - #### call

          public Object call(Object arguments)

      Invokes the closure, returning any value if applicable.
      Parameters:
        `arguments` - could be a single value or a List of values
      Returns:
        the value if applicable or null if there is no return statement in the closure

    - #### throwRuntimeException

          protected static Object throwRuntimeException(Throwable throwable)

    - #### getOwner

          public Object getOwner()

      Returns:
        the owner Object to which method calls will go which is typically the outer class when the closure is constructed

    - #### getDelegate

          public Object getDelegate()

      Returns:
        the delegate Object to which method calls will go which is typically the outer class when the closure is constructed

    - #### setDelegate

          public void setDelegate(Object delegate)

      Allows the delegate to be changed such as when performing markup building
      Parameters:
        `delegate` - the new delegate

    - #### getParameterTypes

          public Class[] getParameterTypes()

      Returns:
        the parameter types of the longest doCall method of this closure

    - #### getMaximumNumberOfParameters

          public int getMaximumNumberOfParameters()

      Returns:
        the maximum number of parameters a doCall method of this closure can take

    - #### asWritable

          public Closure asWritable()

      Returns:
        a version of this closure which implements Writable. Note that the returned Writable also overrides `Object.toString()` in order to allow rendering the result directly to a String.

    - #### run

          public void run()

      Specified by:
        `run` in interface `Runnable`

    - #### curry

          public Closure curry(Object[] arguments)

      Support for Closure currying.

      Typical usage:

           def multiply = { a, b -> a * b }
           def doubler = multiply.curry(2)
           assert doubler(4) == 8

      Note: special treatment is given to Closure vararg-style capability. If you curry a vararg parameter, you don't consume the entire vararg array but instead the first parameter of the vararg array as the following example shows:

           def a = { one, two, Object[] others -> one + two + others.sum() }
           assert a.parameterTypes.name == ['java.lang.Object', 'java.lang.Object', '[Ljava.lang.Object;']
           assert a(1,2,3,4) == 10
           def b = a.curry(1)
           assert b.parameterTypes.name == ['java.lang.Object', '[Ljava.lang.Object;']
           assert b(2,3,4) == 10
           def c = b.curry(2)
           assert c.parameterTypes.name == ['[Ljava.lang.Object;']
           assert c(3,4) == 10
           def d = c.curry(3)
           assert d.parameterTypes.name == ['[Ljava.lang.Object;']
           assert d(4) == 10
           def e = d.curry(4)
           assert e.parameterTypes.name == ['[Ljava.lang.Object;']
           assert e() == 10
           assert e(5) == 15

      Parameters:
        `arguments` - the arguments to bind
      Returns:
        the new closure with its arguments bound

    - #### rcurry

          public Closure rcurry(Object[] arguments)

      Support for Closure "right" currying. Parameters are supplied on the right rather than left as per the normal curry() method. Typical usage:

           def divide = { a, b -> a / b }
           def halver = divide.rcurry(2)
           assert halver(8) == 4

      Parameters:
        `arguments` - the arguments to bind
      Returns:
        the new closure with its arguments bound
      See Also:
        `curry(Object[])`

    - #### ncurry

          public Closure ncurry(int n,
                       Object[] arguments)

      Support for Closure currying at a given index. Parameters are supplied from index position "n". Typical usage:

           def caseInsensitive = { a, b -> a.toLowerCase() <=> b.toLowerCase() } as Comparator
           def caseSensitive = { a, b -> a <=> b } as Comparator
           def animals1 = ['ant', 'dog', 'BEE']
           def animals2 = animals1 + ['Cat']
           // curry middle param of this utility method:
           // Collections#binarySearch(List list, Object key, Comparator c)
           def catSearcher = Collections.&binarySearch.ncurry(1, "cat")
           [[animals1, animals2], [caseInsensitive, caseSensitive]].combinations().each{ a, c ->
             def idx = catSearcher(a.sort(c), c)
             print a.sort(c).toString().padRight(22)
             if (idx < 0) println "Not found but would belong in position ${-idx - 1}"
             else println "Found at index $idx"
           }
           // =>
           // [ant, BEE, dog]       Not found but would belong in position 2
           // [ant, BEE, Cat, dog]  Found at index 2
           // [BEE, ant, dog]       Not found but would belong in position 2
           // [BEE, Cat, ant, dog]  Not found but would belong in position 3

      Parameters:
        `n` - the index from which to bind parameters (may be -ve in which case it will be normalized)
        `arguments` - the arguments to bind
      Returns:
        the new closure with its arguments bound
      See Also:
        `curry(Object[])`

    - #### clone

          public Object clone()

      Overrides:
        `clone` in class `Object`

    - #### getDirective

          public int getDirective()

      Returns:
        Returns the directive.

    - #### setDirective

          public void setDirective(int directive)

      Parameters:
        `directive` - The directive to set.