src/main/resources/Documentation/task_expression.md

<a id="task_expression"/>
Task Expression
--------------

The tasks in subtask and preload-task can be defined using a Task Expression.
Each task expression can contain multiple tasks (all can be optional). Tasks
from other files can be referenced using [Task Reference](#task_reference).

```
TASK_EXPR = TASK_REFERENCE [ WHITE_SPACE * '|' [ WHITE_SPACE * TASK_EXPR ] ]
```

To define a task that may not exist and that will not cause the task referencing
it to be INVALID, follow the task name with pipe (`|`) character. This feature
is particularly useful when a property is used in the task name.

```
    preload-task = Optional task {$_name} |
```

To define an alternate task to load when an optional task does not exist,
list the alternate task name after the pipe (`|`) character. This feature
may be chained together as many times as needed.

```
    subtask = Optional Subtask {$_name} |
              Backup Optional Subtask {$_name} Backup |
              Default Subtask # Must exist if the above two don't!
```

<a id="task_reference"/>
Task Reference
---------

Tasks reference can be a simple task name when the defined task is intended to be in
the same file, tasks from other files can also be referenced by syntax explained below.

```
TASK_REFERENCE = [ [ TASK_FILE_PATH ] '^' ] TASK_NAME
```

To reference a task from root task.config (top level task.config file of a repository)
on the current ref, prefix the task name with `^`.

Example:

task/.../<any>.config
```
    ...
    preload-task = ^Task in root task config
    ...
```

task.config
```
    ...
    [task "Task in root task config"]
    ...
```

To provide an absolute reference to a task under the `task` folder, provide the subpath starting
from `task` directory with a leading `/` followed by a `^` and then task name.

Example:

task.config
```
    ...
    subtask =  /foo/bar/baz.config^Absolute Example Task
    ...
```

task/foo/bar/baz.config
```
    ...
    [task "Absolute Example Task"]
    ...
```

Similarly, to provide reference to tasks which are in a subdirectory of the file containing the
current task avoid the leading `/`.

Example:

task/foo/file.config
```
    ...
    subtask = bar/baz.config^Relative Example Task
    ...
```

task/foo/bar/baz.config
```
    ...
    [task "Relative Example Task"]
    ...
```

Relative tasks specified in a root task.config would look for a file path under the task directory.

Example:

task.config
```
    ...
    subtask = foo/bar.config^Relative from Root Example Task
    ...
```

task/foo/bar.config
```
    ...
    [task "Relative from Root Example Task"]
    ...
```