61 lines
3.0 KiB
Markdown
61 lines
3.0 KiB
Markdown
# husht
|
|
|
|
All the Rust, just with less syntax
|
|
|
|
You can think of husht as a preprocessor for Rust, or as a
|
|
indentation-significant "quiet syntax" language that compiles to Rust.
|
|
In any case, the idea is that .hsh files will transform 1-1 into .rs files,
|
|
and that all Rust language features will be available in a straightforward
|
|
way in husht. Along the way, we will likely add some additional syntactic
|
|
sugar in husht to easy some of the more common language patterns in Rust.
|
|
In particular, we plan to add more familiar syntax for closures.
|
|
|
|
One less common feature of husht is that we will maintain its ability to
|
|
perform "disassembly" of Rust into recommended husht abbreviated form. Thus,
|
|
one can test husht by performing round trips, and in particular, Rust ->
|
|
husht -> Rust should have essentially the same behavior as prettyprinting the
|
|
original Rust code with rustfmt.
|
|
|
|
The base source code of husht is written in husht, but for (relatively clear)
|
|
bootstrapping purposes, it ships with the transformed Rust, and one key
|
|
end-to-end test is that the shipped husht code for husht indeed transforms
|
|
into the Rust code.
|
|
|
|
Documentation of specific syntax features of husht will be added as they are
|
|
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`.
|