doc: RFQ: husht command line and top-level behavior

This commit is contained in:
Glen Whitney 2024-09-19 08:59:30 -07:00
parent 35363eb267
commit ed9525bb9b

View File

@ -23,3 +23,38 @@ into the Rust code.
Documentation of specific syntax features of husht will be added as they are Documentation of specific syntax features of husht will be added as they are
implemented. implemented.
## Usage
`husht [options] [sources]`
Transforms some files from husht to Rust. The source specification `sources`
is a list of files, directories or glob patterns, defaulting to `.`. A
directory `dir` is interpreted the same way as the glob pattern `dir/**` --
in other words, all files recursively within that directory. Glob patterns
are matched and all matching files are added to the list of files to process.
If there is a destination directory (see below), all files in the destination
directory are ignored. Files that do not have extension `.toml` or `.hsh` are
ignored. The former are copied unchanged; the latter are transformed per the
husht language specification into Rust `.rs` files.
Options:
- -h, --help -- Print a usage summary and exit
- -o, --destination [dir/file] -- Specifies the destination of the
transformed file(s). If the destination is a single file, the sources must
be as well, and the one file is transformed into the other. A destination
specification without an extension is assumed to be a directory. The
default destination is `rust`.
If the destination is a directory, then the transform of each source file
is written into that directory, preserving its relative path to its "root".
The root of a file added by virtue of a glob is the top level directory
of that glob pattern. The root of a file specified explicitly is the
current directory.
For example, if the `src` directory contains `main.hsh`, `sub/crate.hsh`, and
`Cargo.toml` (and there are no other .hsh or .toml files in the directory
tree), then `husht src` would write `rust/main.rs`, `rust/sub/crate.rs`, and
`rust/Cargo.toml`. On the other hand just `husht`, defaulting to `husht .`,
would write `rust/src/main.rs`, `rust/src/sub/crate.rs`, and
`rust/src/Cargo.toml`.