Something went wrong. Try again.
A literate programming tool.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109== Command-line interface
=== Name, synopsis, and description
*loom* extracts generated files from annotated source fences.Invocation is `loom [--help|--version] [directory]`; the default directory is`.`. The description below is defined once as format-neutral text and includedin both Clojure's help message and the manual page. It must remain safe insidea Clojure string and as ordinary roff prose: no quotes, backslashes, or leadingroff control characters. Whole-line inclusions preserve indentation; inlineinclusions must expand to exactly one logical line.
```text#| id: loom-cli-help-descriptionRead loom.edn and tangle named code blocks in watched source files.```
Follow `<<loom-cli-usage>>` for the Clojure assembly. It trims the deliberatemultiline string boundaries around this shared text, retaining the existinghelp output rather than adding blank lines.
=== Options and arguments
- `--help` or `-h` prints usage and succeeds; help is checked first, anywhere in the argument list.- `--version` prints `loom 0.1.0` and succeeds when help was not requested.- Otherwise the first argument selects the project directory. Current code is not a strict option parser: additional arguments are not interpreted and an unrecognised option in first position is treated as a directory name.- A project failure prints `loom:` and contextual error data to stderr and exits with status 1. Successful invocations return normally.
=== Files and configuration
The directory must contain `loom.edn`. `watch` is a required vector of regexstrings matched against entire relative source paths. Optional `source-roots`restricts traversal; source paths are sorted and deduplicated before reading.See `<<loom.edn>>` for this repository's actual configuration and`<<loom-config-load>>` for validation.
Leading fence annotations accept `file`, `id`, `executable`, and `presentation`.Only a file annotation creates an output target; ID-only fragments are reusable,and anonymous examples are ignored by the executable index. An explicit IDwins over the file path for naming; last repeated annotations win. Presentationis checked and discarded by the CLI. Executable values must be `true` or `false`and require a file annotation. Closing fences need at least the opening countof backticks. Syntax is a small fixed convention, not a general Markdown parser.
`:annotation` defaults to `:standard`. `:naked` emits only expanded source;`:supplemented` currently behaves like standard. Extension overrides match thefinal suffix, case-sensitively; dotfiles and extensionless files use the default.See the adoption guide for choosing modes, not a second configuration listing.
=== Output, diagnostics, and guarantees
`Writing` identifies a new or changed target. `Unchanged` means byte-identicalcontent was not replaced, preserving modification time, inode, and permissions.No targets prints `No target files found.` without starting workers. A sharedtarget ID warns that references include all named blocks; root bodies remainseparate per output path.
Missing configuration, invalid annotations, unterminated fences, missing orcyclic inclusions, zero-line or multiline inline expansions, escaping/symlinkoutput paths, aliased targets, and stagingfailures are errors. Validation precedes staging, all staging precedespublication, and replacements occur in target order. Replacement is atomic perfile where supported, *not* a multi-file transaction: a later move failure canleave earlier outputs updated. Existing modes survive regeneration; onlyexplicitly requested new files gain an executable bit.
=== A generated brief manual page
This root uses naked `.1` output and includes the same description ID as theCLI. View it locally with `man -l tangled/man/loom.1`. The Nix package installs itunder `share/man/man1`; no separate manpage generator is required.
```roff#| file: tangled/man/loom.1.TH LOOM 1 "" "Loom 0.1.0" "User Commands".SH NAMEloom \- extract files from literate sources.SH SYNOPSIS.B loom.RI [ --help | --version ].RI [ directory ].SH DESCRIPTION<<loom-cli-help-description>>.SH OPTIONS.TP.B --help, -hPrint usage and exit. Takes precedence wherever it appears..TP.B --versionPrint the version and exit unless help was requested..TP.I directoryProject directory, defaulting to the current directory..SH FILES.TP.I loom.ednSource selection, annotation modes, and extension overrides..SH OUTPUTWriting identifies new or changed files; Unchanged preserves identical files.Existing permissions are retained. New files are executable only when declared..SH EXIT STATUSZero on success or help/version; one on a project failure.Publication is atomic per replacement, not a multi-file transaction.```