diff --git a/README.md b/README.md index f03fc4e..89f2ab5 100644 --- a/README.md +++ b/README.md @@ -63,9 +63,7 @@ Implementations of the data model, plus Syrup transfer syntax: ### Preserves Schema documents and codegen - - [preserves-schemac](doc/preserves-schemac.html), generic Schema reader and linter - - [preserves-schema-rkt](doc/preserves-schema-rkt.html), Racket code generator - - [preserves-schema-ts](doc/preserves-schema-ts.html), TypeScript code generator + - [Tools for working with Preserves Schema](doc/schema-tools.html) ## Additional resources diff --git a/doc/preserves-schema-rs.md b/doc/preserves-schema-rs.md new file mode 100644 index 0000000..aa205ed --- /dev/null +++ b/doc/preserves-schema-rs.md @@ -0,0 +1,71 @@ +--- +title: preserves-schema-rs +--- + +The `preserves-schema-rs` program reads +[Preserves Schema](../preserves-schema.html) AST input files (such as +are produced by [`preserves-schemac`]({% link doc/preserves-schemac.md +%})). It produces a collection of Rust source files providing parsers, +unparsers, and Rust data structures reflecting the definitions in the +inputs. + +## Using the compiler from `build.rs` instead + +You will usually not need to use the `preserves-schema-rs` +command-line program. Instead, access the preserves-schema compiler +API from your `build.rs`. The following example is taken from +[`build.rs` for the `preserves-path` crate](https://gitlab.com/preserves/preserves/-/blob/18ac9168996026073ee16164fce108054b2a0ed7/implementations/rust/preserves-path/build.rs): + + use preserves_schema::compiler::*; + + use std::io::Error; + use std::path::PathBuf; + + fn main() -> Result<(), Error> { + let buildroot = PathBuf::from(std::env::var_os("OUT_DIR").unwrap()); + + let mut gen_dir = buildroot.clone(); + gen_dir.push("src/schemas"); + + let mut c = CompilerConfig::new(gen_dir, "crate::schemas".to_owned()); + + let inputs = expand_inputs(&vec!["path.bin".to_owned()])?; + c.load_schemas_and_bundles(&inputs)?; + + compile(&c) + } + +This approach also requires an `include!` from your main, hand-written +source tree. The following is a snippet from +[`preserves-path/src/lib.rs`](https://gitlab.com/preserves/preserves/-/blob/18ac9168996026073ee16164fce108054b2a0ed7/implementations/rust/preserves-path/src/lib.rs): + + pub mod schemas { + include!(concat!(env!("OUT_DIR"), "/src/schemas/mod.rs")); + } + +## Installation + +The tool is +[written in Rust](https://crates.io/crates/preserves-schema). +[Install `cargo`.](https://doc.rust-lang.org/cargo/getting-started/installation.html) +Then, `cargo install preserves-schema`. + +## Usage + + preserves-schema 1.0.0 + + USAGE: + preserves-schema-rs [OPTIONS] --output-dir --prefix [--] [input-glob]... + + FLAGS: + -h, --help Prints help information + -V, --version Prints version information + + OPTIONS: + --module ... + -o, --output-dir + -p, --prefix + --support-crate + + ARGS: + ... diff --git a/doc/preserves-tool.md b/doc/preserves-tool.md index f687105..08c84b0 100644 --- a/doc/preserves-tool.md +++ b/doc/preserves-tool.md @@ -2,56 +2,185 @@ title: preserves-tool --- -The `preserves-tool` program is a swiss army knife for translating -Preserves document syntax to and from various surface syntaxes, for -stripping annotations, and for pretty-printing. +The `preserves-tool` program is a swiss army knife for working with +Preserves documents. -It reads Preserves `Value`s (either a fixed number (`--count`) or -until EOF (`--all`)) from `stdin`, autodetecting binary or text syntax -for each by default, and prints the same `Value`s either using the -same or a different Preserves syntax on `stdout`. By default, it will -print using text syntax with pretty-printing. + preserves-tools 1.0.0 + + USAGE: + preserves-tool + + FLAGS: + -h, --help Print help information + -V, --version Print version information + + SUBCOMMANDS: + completions + convert + help Print this message or the help of the given subcommand(s) + quote ## Installation -Install Racket. Then, `raco pkg install preserves`. +The tool is +[written in Rust](https://crates.io/crates/preserves-tools). +[Install `cargo`.](https://doc.rust-lang.org/cargo/getting-started/installation.html) +Then, `cargo install preserves-tools`. -## Usage +## Subcommands - usage: preserves-tool [