Custom Task Variables

Attila Kelemen edited this page Jun 29, 2013 · 10 revisions

For any Gradle command, you may define custom variables to be queried when actually executing the command. This works for custom tasks and built-in commands as well. Custom variables are just like standard variables (e.g.: ${project}) but instead of automatic replacement, you will be asked to provide their value when executing the Gradle command.

The variable definition takes the following form: ${variableName[typeDefinition]:DisplayName}. In typeDefinition and DisplayName, you may escape any specially treated character (e.g.: ']' and '}') by prepending it with a \ (backward slash) character. Both the type definition and the display name is optional, so you may write ${variableName[typeDefinition]}, ${variableName:DisplayName}, or even ${variableName}.

Type definitions

Type definitions take the following form: typeName:typeArguments, or simply typeName to go with the default arguments.

String variables

Type name: "string".

Characters to escape in the type argument: ']', '}'.

String variables are requested in a simple text field. If you specify a type argument, the type argument will be entered into the text field by default. What you type into the text field will replace the variable.

Enum variables

Type name: "enum"

Characters to escape in the type argument: ']', '}', ',', ':'.

Enum variables are requested in a combobox. The type argument has a special format, listing the enumerated values: "value1:DisplayNameOfValue1, value2:DisplayNameOfValue2, ...". You may add an * (asterisk) character before one of the values to mark it as the one selected by default. If a value need to start with an asterisk, you have to escape the asterisk (\*). The value (e.g.: value1 in the previous example) of the selected item will replace the variable in the command.

Note, you should always specify the type argument for enum variables.

Boolean variables

Type name: "bool"

Characters to escape in the type argument: ']', '}', ','.

Boolean variables are requested in a checkbox. The type argument has the following format "no, yes". The first value will replace the variable in the script if the checkbox is unchecked, while the second if it is checked. The default type argument is "false, true" (unchecked by default). If you want the checkbox to be checked by default start the second value with an * (asterisk) character (e.g.: "no, *yes").

Example

You may specify variables in task names, arguments and JVM arguments as well. Assume the following variables listed in the arguments:

-Pvar1A=${var1}
-Pvar1B=${var1[string:DefaultValue of Var1]: Caption of Var1}
-Pvar1C=${var1}
-Pvar2=${var2[bool]: false/true}
-Pvar3=${var3[bool:no, yes]: no/yes}
-Pvar4=${var4[bool:no, *yes]: no/yes, checked by default}
-Pvar5=${var5[enum:value1, value2: Value2 Display, value3:Value3 Display]: Enum variable}
-Pvar6=${var6[bool:no,\*yes]:no/*yes}

These definitions will cause a dialog to be displayed before executing the task:

Notice that "var1" is requested only once and that only one of the "var1" definition contains details on how to display the variable. If there are multiple different details for the same variable, one is chosed and other descriptions are ignored.

Hitting enter on the above dialog will effectively replace the above mentioned variable definitions with:

-Pvar1A=DefaultValue of Var1
-Pvar1B=DefaultValue of Var1
-Pvar1C=DefaultValue of Var1
-Pvar2=false
-Pvar3=no
-Pvar4=yes
-Pvar5=value1
-Pvar6=no

Ideas for what this feature can be used

  1. You may create a task which creates a subproject based on project properties. In Gradle, you may define properties via the command line. For example: -PnewProjectName=MyProject. The tasks then may use the newProjectName property of the Project instance. Which in most contexts can be simply referenced as a newProjectName variable.

  2. Add a simple checkbox to prevent accidentally running tasks, making changes inconvenient to revert (e.g.: deploying artifacts).

  3. If a task of the project depends on a property defined in the command line arguments. You may let the user choose it from a GUI. This is especially handy, if there is only a finite set of choices.

  4. If you are currently querying anything from the console, you may optionally allow users to define it as a property and skip reading from the console if the property is available. This will allow you to define a custom task in NetBeans from which the user might specify these (note that the console is unavailable, if you run tasks from the IDE). Also, this is especially handy if there is only a finite set of possible choices.

Variable definition syntax

The semi-formal BNF grammar definition is described below. Note that it contains regular expressions and some informal description as well (for more clarity). Also, before and after constant characters in the grammar (except between the initial "${"), you may add as many white space characters as you want.

ReplacedVariableDef:
    '$' '{' VariableDef '}'

VariableDef:
    VariableName '[' TypeDefinition ']' ':' DisplayName
    VariableName '[' TypeDefinition ']'
    VariableName ':' DisplayName
    VariableName

VariableName:
    regexp([A-Za-z0-9\-_\.]+)

DisplayName:
    A string containing any character but '\' and '}' must be escaped.

TypeDefinition:
    StringDefinition
    EnumDefinition
    BoolDefinition

StringDefinition:
    "string"
    "string:" StringArgument

EnumDefinition:
    "enum"
    "enum:" EnumArgument

BoolDefinition:
    "bool"
    "bool:" BoolArgument

StringArgument:
    A string containing any character but '\', '}' and ']' must be escaped.

EnumArgument:
    MarkableEnumValueDef
    MarkableEnumValueDef ',' EnumArgument

MarkableEnumValueDef:
    EnumValueDef
    '*' EnumValueDef

EnumValueDef:
    EnumVarReplaceValue
    EnumVarReplaceValue ':' EnumVarDisplayName

EnumVarReplaceValue:
    A string containing any character but '\', '}', ']', '*', ':' and ',' must be escaped.

EnumVarDisplayName:
    A string containing any character but '\', '}', ']', and ',' must be escaped.

BoolArgument:
    UncheckedValue ',' CheckedValue

UncheckedValue:
    BoolValue

CheckedValue:
    BoolValue

BoolValue:
    BoolConstant
    '*' BoolConstant

BoolConstant:
    A string containing any character but '\', '}', ']', '*' and ',' must be escaped.
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.