From ed9525bb9bb085ee46d064cd8877521bd295ff27 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Thu, 19 Sep 2024 08:59:30 -0700 Subject: [PATCH 1/3] doc: RFQ: husht command line and top-level behavior --- README.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/README.md b/README.md index d5cbc27..392e6e6 100644 --- a/README.md +++ b/README.md @@ -23,3 +23,38 @@ 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`. -- 2.43.0 From 519da3ca45e39b94f3dcc0d384a0625e2c836b7a Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Mon, 14 Oct 2024 21:51:31 -0700 Subject: [PATCH 2/3] doc: Adjust proposed husht command-line option per feedback. --- README.md | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 392e6e6..c8cbda1 100644 --- a/README.md +++ b/README.md @@ -33,24 +33,19 @@ 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. +All files in the output 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. + - --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. 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 -- 2.43.0 From 703d92d925bb9103a3141333212519132cb7b1ab Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Tue, 22 Oct 2024 23:11:27 -0700 Subject: [PATCH 3/3] doc: Copy all non-hsh files, not just .toml; lay out examples --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 49 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index c8cbda1..ef8d983 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,14 @@ 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 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. +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 @@ -45,11 +49,45 @@ Options: 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. + 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, 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`. +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 +``` -- 2.43.0