Update docs
This commit is contained in:
parent
18ac916899
commit
66e7af491f
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <output-dir> --prefix <prefix> [--] [input-glob]...
|
||||
|
||||
FLAGS:
|
||||
-h, --help Prints help information
|
||||
-V, --version Prints version information
|
||||
|
||||
OPTIONS:
|
||||
--module <module>...
|
||||
-o, --output-dir <output-dir>
|
||||
-p, --prefix <prefix>
|
||||
--support-crate <support-crate>
|
||||
|
||||
ARGS:
|
||||
<input-glob>...
|
||||
|
|
@ -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 <SUBCOMMAND>
|
||||
|
||||
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 [ <option> ... ]
|
||||
The tool includes three subcommands.
|
||||
|
||||
<option> is one of
|
||||
### `preserves-tool convert`
|
||||
|
||||
--atob
|
||||
Text to binary
|
||||
--all
|
||||
Read until EOF (default)
|
||||
--count <n>
|
||||
Read n items
|
||||
--btoa
|
||||
Binary to text
|
||||
--ia, --input-any
|
||||
Autodetect input mode (default)
|
||||
--ib, --input-binary
|
||||
Set binary input mode
|
||||
--it, --input-text
|
||||
Set text input mode
|
||||
--ob, --output-binary
|
||||
Set binary output mode
|
||||
--ot, --output-text
|
||||
Set text output mode (default)
|
||||
--indent
|
||||
Enable indent and set text output mode (default)
|
||||
--no-indent
|
||||
Disable indent and set text output mode
|
||||
--annotations
|
||||
Output annotations (default)
|
||||
--no-annotations
|
||||
Strip annotations
|
||||
--help, -h
|
||||
Show this help
|
||||
--
|
||||
Do not treat any remaining argument as a switch (at this level)
|
||||
This is the main tool. It can
|
||||
|
||||
Multiple single-letter switches can be combined after
|
||||
one `-`. For example, `-h-` is the same as `-h --`.
|
||||
- translate between the various Preserves text and binary document
|
||||
syntaxes;
|
||||
- strip annotations;
|
||||
- pretty-print; and
|
||||
- break down and filter documents using [preserves path]({{
|
||||
site.baseurl }}{% link preserves-path.md %}) selectors.
|
||||
|
||||
#### Usage
|
||||
|
||||
preserves-tool-convert
|
||||
|
||||
USAGE:
|
||||
preserves-tool convert [FLAGS] [OPTIONS]
|
||||
|
||||
FLAGS:
|
||||
--collect
|
||||
--escape-spaces
|
||||
-h, --help Print help information
|
||||
-V, --version Print version information
|
||||
|
||||
OPTIONS:
|
||||
--annotations <on/off>
|
||||
|
||||
[default: on] [possible values: disabled, no, n, off, 0, false,
|
||||
enabled, yes, y, on, 1, true]
|
||||
|
||||
-i, --input-format <INPUT_FORMAT>
|
||||
[default: auto-detect] [possible values: auto-detect, text, binary]
|
||||
|
||||
--indent <on/off>
|
||||
[default: on] [possible values: disabled, no, n, off, 0, false,
|
||||
enabled, yes, y, on, 1, true]
|
||||
|
||||
--limit <LIMIT>
|
||||
|
||||
|
||||
-o, --output-format <OUTPUT_FORMAT>
|
||||
[default: text] [possible values: text, binary, unquoted]
|
||||
|
||||
--select <SELECT>
|
||||
[default: *]
|
||||
|
||||
--select-output <SELECT_OUTPUT>
|
||||
[default: sequence] [possible values: sequence, set]
|
||||
|
||||
### `preserves-tool quote`
|
||||
|
||||
This subcommand reads chunks from standard input and outputs each one
|
||||
as a Preserves `String`, `Symbol`, or `ByteString` using either the
|
||||
text or binary Preserves surface syntax.
|
||||
|
||||
This is useful when writing shell scripts that interact with other
|
||||
programs using Preserves as an interchange format.
|
||||
|
||||
It defaults to taking the entirety of standard input as a single large
|
||||
chunk, but it can also work with newline- or `nul`-delimited chunks.
|
||||
|
||||
#### Usage
|
||||
|
||||
```
|
||||
preserves-tool-quote
|
||||
|
||||
USAGE:
|
||||
preserves-tool quote [OPTIONS] <SUBCOMMAND>
|
||||
|
||||
FLAGS:
|
||||
-h, --help Print help information
|
||||
-V, --version Print version information
|
||||
|
||||
OPTIONS:
|
||||
-o, --output-format <OUTPUT_FORMAT> [default: text] [possible values: text, binary, unquoted]
|
||||
|
||||
SUBCOMMANDS:
|
||||
byte-string
|
||||
help Print this message or the help of the given subcommand(s)
|
||||
string
|
||||
symbol
|
||||
```
|
||||
|
||||
```
|
||||
preserves-tool-quote-string
|
||||
|
||||
USAGE:
|
||||
preserves-tool quote string [FLAGS] [OPTIONS]
|
||||
|
||||
FLAGS:
|
||||
--escape-spaces
|
||||
-h, --help Print help information
|
||||
--include-terminator
|
||||
-V, --version Print version information
|
||||
|
||||
OPTIONS:
|
||||
--input-terminator <INPUT_TERMINATOR> [default: eof] [possible values: eof, newline, nul]
|
||||
```
|
||||
|
||||
```
|
||||
preserves-tool-quote-symbol
|
||||
|
||||
USAGE:
|
||||
preserves-tool quote symbol [FLAGS] [OPTIONS]
|
||||
|
||||
FLAGS:
|
||||
--escape-spaces
|
||||
-h, --help Print help information
|
||||
--include-terminator
|
||||
-V, --version Print version information
|
||||
|
||||
OPTIONS:
|
||||
--input-terminator <INPUT_TERMINATOR> [default: eof] [possible values: eof, newline, nul]
|
||||
```
|
||||
|
||||
```
|
||||
preserves-tool-quote-byte-string
|
||||
|
||||
USAGE:
|
||||
preserves-tool quote byte-string
|
||||
|
||||
FLAGS:
|
||||
-h, --help Print help information
|
||||
-V, --version Print version information
|
||||
```
|
||||
|
||||
### `preserves-tool completions`
|
||||
|
||||
This subcommand outputs Bash completion code to stdout, for sourcing
|
||||
at shell startup time.
|
||||
|
||||
#### Usage
|
||||
|
||||
Add the following to your `.profile` or similar:
|
||||
|
||||
eval "$(preserves-tool completions bash 2>/dev/null)"
|
||||
|
||||
Multiple shell dialects are supported (courtesy of
|
||||
[`clap`](https://crates.io/crates/clap)):
|
||||
|
||||
```
|
||||
preserves-tool-completions
|
||||
|
||||
USAGE:
|
||||
preserves-tool completions <dialect>
|
||||
|
||||
ARGS:
|
||||
<dialect> [possible values: bash, zsh, power-shell, fish, elvish]
|
||||
|
||||
FLAGS:
|
||||
-h, --help Print help information
|
||||
-V, --version Print version information
|
||||
```
|
||||
|
|
|
|||
|
|
@ -0,0 +1,11 @@
|
|||
---
|
||||
title: Tools for working with Preserves Schema
|
||||
---
|
||||
|
||||
A number of tools for working with [Preserves Schema]({{ site.baseurl
|
||||
}}{% link preserves-schema.md %}) exist:
|
||||
|
||||
- [preserves-schemac](preserves-schemac.html), generic Schema reader and linter
|
||||
- [preserves-schema-rkt](preserves-schema-rkt.html), Racket code generator
|
||||
- [preserves-schema-rs](preserves-schema-rs.html), Rust code generator
|
||||
- [preserves-schema-ts](preserves-schema-ts.html), TypeScript code generator
|
||||
Loading…
Reference in New Issue