94 lines
3.5 KiB
Markdown
94 lines
3.5 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.
|
|
All files in the output directory are ignored. Files that have
|
|
extension `.hsh` are transformed per the husht language specification into
|
|
Rust `.rs` files, which are written to the appropriate destination specified
|
|
by the options described below. All other files to process are copied
|
|
unchanged to the destination. The latter convention allows `.toml` files, and
|
|
potentially other associated files, to be co-located with the source and yet
|
|
end up in the appropriate place in an intermediate build location with the
|
|
generated Rust code.
|
|
|
|
Options:
|
|
- -h, --help -- Print a usage summary and exit
|
|
- --out-dir [dir] -- Specifies the output directory of the transformed
|
|
file(s), defaulting to `rust`. The transform of each source file is
|
|
written into the output 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, or the current directory if none.
|
|
The root of a file specified explicitly is the current directory. If a
|
|
file is not within the tree starting from what would otherwise be its
|
|
root, its root is considered to be its directory. (In other words, the
|
|
destination for that file will be the `--out-dir` itself.)
|
|
|
|
For example, suppose the current directory is the top-level directory of your
|
|
project and is laid out like so:
|
|
|
|
```
|
|
src
|
|
├─ main.hsh
|
|
├─ Cargo.toml
|
|
└─ sub
|
|
└─ crate.hsh
|
|
rust
|
|
└─ jnk.txt
|
|
```
|
|
|
|
Then after `husht src` the `rust` directory would look like:
|
|
|
|
```
|
|
rust
|
|
├─ jnk.txt
|
|
├─ main.rs
|
|
├─ Cargo.toml
|
|
└─ sub
|
|
└─ crate.rs
|
|
```
|
|
(Note that the `rust` directory does not have to exist prior to the `husht`
|
|
command; if it had not, the results would look the same, except that of course
|
|
`jnk.txt` would not be there.)
|
|
|
|
On the other hand, just `husht`, defaulting to `husht .`, would produce:
|
|
```
|
|
rust
|
|
├─ jnk.txt
|
|
└─ src
|
|
├─ main.rs
|
|
├─ Cargo.toml
|
|
└─ sub
|
|
└─ crate.rs
|
|
```
|