livery.workshop._words¶
livery.workshop._words ¶
Steps in words: a tool and its arguments in a declaration, and their engine.
A step whose verdict is its tool's exit code needs no code. Its
declaration names the tool and the words it is called with: main
in its [phases.<phase>.<step>] table, and fix and safe-fix
for one that rewrites. The engine does the rest. It selects what the
run reaches, as the step's scope and narrowing say; puts the paths and
the words after -- on the step's verb where the template stands
them; splits a long path list into the fewest calls under the
command-line limit; and runs the tool through its toolroom handle,
which prints the tool's output. A non-zero exit refuses, and the
refusals of every call merge into one.
The template places both itself: {paths} stands where each batch
of the paths goes, and a template without it runs whole, once with no
path; {arguments} stands where the words after -- go, and a
template without it takes none. Each stands alone as one word, which
the engine expands into many.
A word may name a placeholder, {name}, answered per call:
{cache}, the step's own directory under .workshop/.cache/;
{package}, the directory of the package a call judges;
{compile-commands}, the directory of that package's compilation
database, without which the call does not run; and each key of
matrix, which runs one call per value in parallel, each its own
verdict. env gives every call variables over the run's own.
A step the words cannot say, one whose verdict is not its tool's exit
code or whose paths need reshaping first, declares a reference to its
code instead: main as a string, module:function.
Classes:
| Name | Description |
|---|---|
Words |
A step's words, as its declaration spells them. |
Command |
One mode of a step in words, called as the step's |
Functions:
| Name | Description |
|---|---|
run_words |
Run command over what the run reaches, as its step's scope and narrowing say. |
run_tool |
Call tool's toolroom handle with argv, from cwd; a non-zero exit refuses. |
explained |
The lines |
Attributes:
| Name | Type | Description |
|---|---|---|
PLACEHOLDERS |
|
|
PACKAGE_PLACEHOLDERS |
|
|
PATHS_WORD |
|
|
ARGUMENTS_WORD |
|
|
PLACED |
|
PLACEHOLDERS
module-attribute
¶
Words
dataclass
¶
Words(judge: tuple[str, ...], fix: tuple[str, ...] = (), safe_fix: tuple[str, ...] = (), env: tuple[tuple[str, str], ...] = (), matrix: tuple[tuple[str, tuple[str, ...]], ...] = ())
A step's words, as its declaration spells them.
Attributes:
| Name | Type | Description |
|---|---|---|
judge |
tuple[str, ...]
|
The tool's name, as the step's |
fix |
tuple[str, ...]
|
The tool and the arguments that rewrite under |
safe_fix |
tuple[str, ...]
|
The tool and the arguments that rewrite under
|
env |
tuple[tuple[str, str], ...]
|
The variables every call gets, over the run's own, by name. |
matrix |
tuple[tuple[str, tuple[str, ...]], ...]
|
Each placeholder the calls vary, with its values: one call per combination. |
Methods:
| Name | Description |
|---|---|
placeholders |
Every placeholder the words name, in any mode or variable. |
unanswered |
The placeholders neither the engine nor the matrix answers, sorted. |
unvaried |
The matrix keys no word names, in the matrix's order. |
placeholders ¶
Every placeholder the words name, in any mode or variable.
Source code in packages/workshop/src/livery/workshop/_words.py
unanswered ¶
The placeholders neither the engine nor the matrix answers, sorted.
Source code in packages/workshop/src/livery/workshop/_words.py
unvaried ¶
The matrix keys no word names, in the matrix's order.
Command
dataclass
¶
One mode of a step in words, called as the step's run or fix.
Attributes:
| Name | Type | Description |
|---|---|---|
words |
Words
|
The step's words. |
step |
str
|
The step's name, |
fixing |
bool
|
Whether this is the fix mode, which runs |
Methods:
| Name | Description |
|---|---|
argv |
The words this mode runs: the tool's name, then its arguments. |
__call__ |
Run this mode over what ctx reaches; a non-zero exit refuses. |
__str__ |
The words this mode runs, as the declaration spells them. |
argv ¶
The words this mode runs: the tool's name, then its arguments.
Source code in packages/workshop/src/livery/workshop/_words.py
__call__ ¶
__call__(ctx: PhaseContext) -> None
run_words ¶
run_words(command: Command, ctx: PhaseContext) -> None
Run command over what the run reaches, as its step's scope and narrowing say.
A package step calls the tool on the package's files the run reaches, from the package's directory, and calls nothing when there are none. A workspace step that narrows by paths calls it on the paths the run reaches, with none when the run is whole, and not at all when the run reaches nothing it reads; one that narrows by packages calls it once per package; any other calls it once, with no path.
Raises:
| Type | Description |
|---|---|
Failed
|
when a call exits non-zero, every call's reason merged. |
Source code in packages/workshop/src/livery/workshop/_words.py
run_tool ¶
run_tool(tool: str, argv: tuple[str, ...], *, cwd: Path, ctx: PhaseContext, env: dict[str, str]) -> None
Call tool's toolroom handle with argv, from cwd; a non-zero exit refuses.
The handle prints the tool's output. A call from the workspace root runs in the run's own directory, and one with no variables in the run's own environment, so neither is passed.
Raises:
| Type | Description |
|---|---|
Failed
|
when the tool exits non-zero, with the handle's reason. |
Source code in packages/workshop/src/livery/workshop/_words.py
explained ¶
explained(record: StepRecord) -> list[str]
The lines fm explain <step> prints: what the step runs, and over what.
A step in words shows each mode's command as the tool's handle
spells it, the placeholders left for the engine to answer, then
what the engine puts where {paths} and {arguments} stand;
a step that runs code names its references.