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 Schema documents and codegen
|
||||||
|
|
||||||
- [preserves-schemac](doc/preserves-schemac.html), generic Schema reader and linter
|
- [Tools for working with Preserves Schema](doc/schema-tools.html)
|
||||||
- [preserves-schema-rkt](doc/preserves-schema-rkt.html), Racket code generator
|
|
||||||
- [preserves-schema-ts](doc/preserves-schema-ts.html), TypeScript code generator
|
|
||||||
|
|
||||||
## Additional resources
|
## 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
|
title: preserves-tool
|
||||||
---
|
---
|
||||||
|
|
||||||
The `preserves-tool` program is a swiss army knife for translating
|
The `preserves-tool` program is a swiss army knife for working with
|
||||||
Preserves document syntax to and from various surface syntaxes, for
|
Preserves documents.
|
||||||
stripping annotations, and for pretty-printing.
|
|
||||||
|
|
||||||
It reads Preserves `Value`s (either a fixed number (`--count`) or
|
preserves-tools 1.0.0
|
||||||
until EOF (`--all`)) from `stdin`, autodetecting binary or text syntax
|
|
||||||
for each by default, and prints the same `Value`s either using the
|
USAGE:
|
||||||
same or a different Preserves syntax on `stdout`. By default, it will
|
preserves-tool <SUBCOMMAND>
|
||||||
print using text syntax with pretty-printing.
|
|
||||||
|
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
|
## 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
|
This is the main tool. It can
|
||||||
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)
|
|
||||||
|
|
||||||
Multiple single-letter switches can be combined after
|
- translate between the various Preserves text and binary document
|
||||||
one `-`. For example, `-h-` is the same as `-h --`.
|
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