## ProcBlocks Syntax
### YAML Basics:
Mind your margins. YAML syntax depends on margins to identify grouping.
```yaml
# Comments: Everything right of a # is ignored.
- block: # Blocks begin the line with a hyphen and a space to denote a YAML list.
key: "value" # Children indented deeper than the text above.
section: # A block is broken into sections
key: "value" # Section items require one further indent level (same size as your block indent).
- block:
key: # invalid. must be indented more than the text above.
```
#### **Important:** YAML List items, denoted by a hyphen, must be indented at least 3 spaces to be recognized as children. This applies to all blocks.
[For more on YAML](https://yaml.org)
### **Blocks, Sections, and Key-value Pairs:**
```yaml
- block:
key: "value" # Key-value pair
section: # List of items
key: "value" # Key-value pair
```
---
### Blocks
Each block represents a "step" in the pipeline and is defined at the outermost indent.
Blocks can be one of three types:
```yaml
- assign: # Define vars, init, and overrides
params: # Indent
myparam: "value" # Indent 2+ more spaces
- processor: "" # Perform image processing
...
- job: # Nested job block
...
```
### Standard Block Properties
| Property | Required? | Description |
| ------------- | :-------: | ------------------------------------------------------- |
| **step** | No | Identifier for this block (defaults to block type name) |
| **condition** | No | Skip block if false |
---
### Assign Blocks
Assign blocks let you define variables, route files, and declare overrides for subsequent steps.
```yaml
- assign:
step: "prepare-assets"
inputs:
src: "input/photo.png" # vars.src = "input/photo.png"
meta: "input/photo.json"
outputs:
src: "mem/photo.png" # copy input/photo.png → mem/photo.png
meta: "mem/photo.json"
vars:
src_width: "{width:src}" # inline‐parsed metadata from the `src` image
retries: "3"
init:
quality: "85" # only if `quality` not already set
overrides:
- key: "size"
value: "1024"
```
### Assign Block Properties
| Property | Required? | Description |
| ------------- | :-------: | --------------------------------------------------------- |
| **step** | No | Block identifier (defaults to `"assign"`) |
| **condition** | No | Expression to skip block if false (e.g. `"True"`, `"0"`) |
| **inputs** | No | `key: "filepath"` → sets `vars[key] = filepath` |
| **outputs** | No | `key: "filepath"` → copies `inputs[key]` → `outputs[key]` |
| **vars** | No | `var: "expr"` → inline‐parsed, assigned to `vars[var]` |
| **init** | No | Like `vars`, but only if not already defined |
| **overrides** | No | List of `{step?, section?, key, value}` scoped overrides |
---
### Processor Blocks
Processor blocks perform image processing and include sections for inputs, params, outputs, and optional var assignments.
```yaml
- processor:
processor: "trim"
step: "trimmed" # Optional name; defaults to processor name.
condition: "True" # Block is skipped if condition is false.
inputs:
source: "input/input.png"
params:
padding: "10"
trim_color: "transparent"
outputs:
target: "mem/trimmed.png"
assigns: # Optional; assigns values to variables.
left: "trim_left"
top: "trim_top"
right: "trim_right"
bottom: "trim_bottom"
width: "trim_width"
height: "trim_height"
```
### Processor Block Properties
| Property | Required? | Description |
| ------------- | :-------: | ---------------------------------------------------- |
| **processor** | Yes | Processor name (e.g. `"trim"`) |
| **step** | No | Identifier (defaults to processor name) |
| **condition** | No | Skip block if false |
| **inputs** | No | Input file mappings |
| **params** | No | Processor-specific parameters |
| **outputs** | No | Output file mappings |
| **assigns** | No | Map processor results back into variables (optional) |
---
### Job Blocks (Nested Jobs)
Job blocks enable nesting of job definitions, allowing reuse of pipelines or job fragments as subjobs. Nested jobs inherit copies of the parent job's variables and overrides so changes in the nested context do not affect the parent.
```yaml
- job:
job: "somejob" # Specifies the external job definition.
step: "nested" # Optional; defaults to "nestedjob" if omitted.
condition: "True" # Block is skipped if condition is false.
```
### Job Block Properties
| Property | Required? | Description |
| ------------- | :-------: | -------------------------------------- |
| **job** | Yes | Name of nested job definition |
| **step** | No | Identifier (defaults to `"nestedjob"`) |
| **condition** | No | Skip block if false |