README.md.tmpl

Common Workflow Language experimental grammar.

This is an experimental human-friendly grammar that compiles to [CWL](http://commonwl.org) for execution.

Design principals:

* Don't repeat yourself
* Infer types where possible
* Inline declarations for things that are only used once
* Useful default behaviors when not specified
* Be fun to use

# Quickstart using Docker

Requires a [CWL implementation](https://www.commonwl.org/#Implementations).

Pulls the `commonworkflowlanguage/cwlex` Docker image.

Convert a self-contained (no imports) cwlex script to CWL:

```
$ cwl-runner cwlex.cwl --inp myscript.cwlex
```

Convert a cwlex script with imports to CWL:

```
$ cwl-runner cwlex.cwl --inpdir . --inpfile myscript.cwlex
```

The resulting script can be run with any [CWL implementation](https://www.commonwl.org/#Implementations):

```
$ cwl-runner myscript.cwl
```

# Installing & Usage

Easy install from npm.  Requires node.js.

```
$ npm install cwl-ex
```

Installs executable entry point `cwlex` in the npm `bin` directory.

```
$ cwlex myscript.cwlex > myscript.cwl
```

# Syntax

## Command line tools

### Define a command line tool

Define a tool called `reverse`.  It takes an input parameter called
`msg` which is a `File`.  Run the command `rev` with `msg` as an
argument.  Redirect to `reversed.txt` and return `reversed.txt` as the
output parameter `reversed`.

```
$include: reverse.cwlex
```

### Run a shell script

You can put an arbitrary script between `<<<` and `>>>`.  It will be
created at runtime in a temporary file and added to the command line.

```
$include: ex2.cwlex
```

### Run in a Docker container

Use `DockerRequirement` to run the tool in a Docker container.

```
$include: ex3.cwlex
```

### Define default parameters

You can set default values for input parameters.

```
$include: echo.cwlex
```

### Optional arguments

Optional parameters in the input have `?` after the parameter name.
After declaring the main command line, declare optional tool flags in
the form `? <prefix> <parameter>`.

```
$include: ex5.cwlex
```

### Array arguments

The `?` syntax is also used for array parameters.  `? for each in
<parameter>` will add each element in the array to the command line.
Use `? <prefix> for each in <parameter>` to add each item with a
leading option switch.

```
$include: ex6.cwlex
```

## Workflows

### Import and execute tools

Assign the output parameter `out` of `echo` to `e`.  Assign the output
parameter `reversed` of `reverse` to `r`.  The output of the workflow
is the output parameter `r`.

```
$include: ex7.cwlex
```

### Workflow with tools defined inline

When tools are defined inline, their outputs are implicitly added to
the scope, unless they are explicitly assigned (as in the example
above).  If there is no explicit `return`, the workflow will return
all parameters defined in the workflow.  In this example, the output
parameters are both `echoed` and `reversed`.

```
$include: ex8.cwlex
```

### Scatter a tool over an array

To run a parallel scatter over an array, use `scatter <parameter> do
...`.  The parameter named is added as in input to the tool.  The
output of the step will be an array of values consisting of the output
of each scatter step.

```
$include: ex9.cwlex
```

```
$include: ex10.cwlex
```

### Javascript expressions

Javascript expression tools can be declared and called.  Requires a type declaration after the inputs.

```
$include: ex11.cwlex
```

Use `run expr` to run a Javascript tool inline.  Requires a type declaration after the inputs.

```
$include: ex12.cwlex
```

### Constants and expressions in step inputs

Step inputs can assigned constant and expression values.

```
$include: ex13.cwlex
```

### Merging several parameters into a single parameter

```
$include: ex14.cwlex
```

# Developing

Regenerate the parser (requires antlr4):

```
$ cd src && cwl-runner antlr.cwl
```

Run tests:

```
$ cwl-runner cwlex.cwl --inpdir . --inpfile cwlex-tests.cwlex
$ cwl-runner cwlex-tests.cwl
```

Install dependencies (requires node.js and npm):

```
$ npm install
```

Build npm package:

```
$ npm pack
```

Install local npm package into a Docker image.
```
$ docker build -f cwlex.Dockerfile -t commonworkflowlanguage/cwlex .
```

Update README.md
```
$ cwl-runner cwlex.cwl --inp makereadme.cwlex
$ cwl-runner makereadme.cwl
```