Workflows

Entangled has a small build engine (similar to GNU Make) embedded, called Brei. You may give it a list of tasks (specified in TOML) that may depend on one another. Brei will run these when dependencies are newer than the target. Execution is lazy and in parallel. Brei supports:

• Running tasks by passing a script to any configured interpreter, e.g. Bash, Python, Lua etc.
• Redirecting stdout or stdin to or from files.
• Defining so called "phony" targets.
• Define template for programmable reuse.
• include other Brei files, even ones that need to be generated by another task.
• Variable substitution, including writing stdout to variables.

Brei is available as a separate package, see the Brei documentation.

Examples

To write out "Hello, World!" to a file msg.txt, we may do the following,

[[task]]
stdout = "secret.txt"
language = "Python"
script = """
print("Uryyb, Jbeyq!")
"""

To have this message decoded define a pattern,

[pattern.rot13]
stdout = "{stdout}"
stdin = "{stdin}"
language = "Bash"
script = """
tr a-zA-Z n-za-mN-ZA-M
"""

[[call]]
pattern = "rot13"
  [call.args]
  stdin = "secret.txt"
  stdout = "msg.txt"

To define a phony target "all",

[[task]]
name = "all"
requires = ["msg.txt"]

The brei hook

The following example uses both brei and quatro_attributes hooks. To add a Brei task, tag a code block with the .task class.

First we generate some data.

``` {.python #some-functions}
# define some functions
```

Now we show what that data would look like:

``` {.python .task}
#| description: Generate data
#| creates: data/data.npy

<<some-functions>>

# generate and save data
```

Then we plot in another task.

``` {.python .task}
#| description: Plot data
#| creates: docs/fig/plot.svg
#| requires: data/data.npy
#| collect: figures

# load data and plot
```

The collect attribute tells the Brei hook to add the docs/fig/plot.svg target to the figures collection. All figures can then be rendered as follows, having in entangled.toml

version = "2.0"
watch_list = ["docs/**/*.md"]
hooks = ["quatro_attributes", "brei"]

[brei]
include = [".entangled/tasks.json"]

And run

entangled brei figures

You can use ${variable} syntax inside Brei tasks just as you would in a stand-alone Brei script.