Some tool docs; improve help message of preserves-tool
This commit is contained in:
parent
f14b902f24
commit
c05180c492
12
README.md
12
README.md
|
|
@ -54,6 +54,18 @@ Implementations of the data model, plus Syrup transfer syntax:
|
|||
- [Syrup for JavaScript](https://github.com/zarutian/agoric-sdk/blob/zarutian/captp_variant/packages/captp/lib/syrup.js)
|
||||
- [Syrup for Haskell](https://github.com/zenhack/haskell-preserves)
|
||||
|
||||
## Tools
|
||||
|
||||
### Preserves documents
|
||||
|
||||
- [preserves-tool](doc/preserves-tool.html), generic syntax translation and pretty-printing
|
||||
|
||||
### 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
|
||||
|
||||
## Additional resources
|
||||
|
||||
- Some [conventions for common data types](conventions.html)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,10 @@
|
|||
version 1 .
|
||||
JSON =
|
||||
/ @string string
|
||||
/ @integer int
|
||||
/ @double double
|
||||
/ @boolean JSONBoolean
|
||||
/ @null =null
|
||||
/ @array [JSON ...]
|
||||
/ @object { string: JSON ...:... } .
|
||||
JSONBoolean = =true / =false .
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
---
|
||||
title: preserves-schema-rkt
|
||||
---
|
||||
|
||||
The `preserves-schema-rkt` program reads
|
||||
[Preserves Schema](../preserves-schema.html) DSL input files. For each
|
||||
input file, it produces a Racket source file of the same name but
|
||||
with `.rkt` in place of `.prs`.
|
||||
|
||||
Instead of using this tool, you may prefer to use `#lang
|
||||
preserves-schema` to use Schema DSL syntax in an ordinary Racket
|
||||
module source file.
|
||||
|
||||
## Installation
|
||||
|
||||
Install Racket. Then, `raco pkg install preserves`.
|
||||
|
||||
## Usage
|
||||
|
||||
usage: preserves-schema-rkt [ <option> ... ] [<input-glob>] ...
|
||||
|
||||
<option> is one of
|
||||
|
||||
--output <directory>
|
||||
Output directory for modules (default: next to sources)
|
||||
--stdout
|
||||
Prints each module to stdout one after the other instead of writing them to files in the `--output` directory
|
||||
--no-write-files
|
||||
Disables generation of output to the filesystem
|
||||
--base <directory>
|
||||
Base directory for sources (default: common prefix)
|
||||
* --module <namespace=path>
|
||||
Additional Namespace=path import
|
||||
* --plugin-lib <lib-path>, -l <lib-path>
|
||||
Load compiler plugin library
|
||||
* --plugin-file <rkt-file-path>, -f <rkt-file-path>
|
||||
Load compiler plugin source file
|
||||
--help, -h
|
||||
Show this help
|
||||
--
|
||||
Do not treat any remaining argument as a switch (at this level)
|
||||
|
||||
* Asterisks indicate options allowed multiple times.
|
||||
|
||||
Multiple single-letter switches can be combined after
|
||||
one `-`. For example, `-h-` is the same as `-h --`.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
title: preserves-schema-ts
|
||||
---
|
||||
|
||||
The `preserves-schema-ts` program reads
|
||||
[Preserves Schema](../preserves-schema.html) DSL input files. For each
|
||||
input file, it produces a TypeScript source file of the same name but
|
||||
with `.ts` in place of `.prs`.
|
||||
|
||||
## Installation
|
||||
|
||||
Install node.js v12 or newer. Then, `yarn global add @preserves/schema`.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: preserves-schema-ts [options] [input...]
|
||||
|
||||
Compile Preserves schema definitions to TypeScript
|
||||
|
||||
Arguments:
|
||||
input Input filename or glob
|
||||
|
||||
Options:
|
||||
--output <directory> Output directory for modules (default: next to sources)
|
||||
--stdout Prints each module to stdout one after the other instead of writing them to files in the `--output`
|
||||
directory
|
||||
--base <directory> Base directory for sources (default: common prefix)
|
||||
--core <path> Import path for @preserves/core (default: "@preserves/core")
|
||||
--watch Watch base directory for changes
|
||||
--traceback Include stack traces in compiler errors
|
||||
--module <namespace=path> Additional Namespace=path import (default: [])
|
||||
-h, --help display help for command
|
||||
|
|
@ -0,0 +1,136 @@
|
|||
---
|
||||
title: preserves-schemac
|
||||
---
|
||||
|
||||
The `preserves-schemac` program reads
|
||||
[Preserves Schema](../preserves-schema.html) DSL input files and
|
||||
outputs a binary-syntax Preserves document conforming to the
|
||||
[metaschema](https://gitlab.com/preserves/preserves/-/blob/main/schema/schema.prs).
|
||||
|
||||
It can either output single `Schema` records (corresponding to a
|
||||
single input file), or a `Bundle` of `Schema`s (corresponding to a
|
||||
directory tree of files).
|
||||
|
||||
## Installation
|
||||
|
||||
Install node.js v12 or newer. Then, `yarn global add @preserves/schema`.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: preserves-schemac [options] [input...]
|
||||
|
||||
Compile textual Preserves schema definitions to binary format
|
||||
|
||||
Arguments:
|
||||
input Input filename or glob
|
||||
|
||||
Options:
|
||||
--no-bundle Emit a single Schema instead of a schema Bundle
|
||||
--base <directory> Base directory for sources (default: common prefix)
|
||||
-h, --help display help for command
|
||||
|
||||
## Examples
|
||||
|
||||
### Single file (non-bundle)
|
||||
|
||||
Given a file [`demo.prs`](demo.prs) containing:
|
||||
|
||||
version 1 .
|
||||
JSON =
|
||||
/ @string string
|
||||
/ @integer int
|
||||
/ @double double
|
||||
/ @boolean JSONBoolean
|
||||
/ @null =null
|
||||
/ @array [JSON ...]
|
||||
/ @object { string: JSON ...:... } .
|
||||
JSONBoolean = =true / =false .
|
||||
|
||||
running the following:
|
||||
|
||||
preserves-schemac --no-bundle demo.prs
|
||||
|
||||
will produce the following binary file on `stdout`:
|
||||
|
||||
00000000: b4b3 0673 6368 656d 61b7 b307 7665 7273 ...schema...vers
|
||||
00000010: 696f 6e91 b30b 6465 6669 6e69 7469 6f6e ion...definition
|
||||
00000020: 73b7 b304 4a53 4f4e b4b3 026f 72b5 b5b1 s...JSON...or...
|
||||
00000030: 0673 7472 696e 67b4 b304 6174 6f6d b306 .string...atom..
|
||||
00000040: 5374 7269 6e67 8484 b5b1 0769 6e74 6567 String.....integ
|
||||
00000050: 6572 b4b3 0461 746f 6db3 0d53 6967 6e65 er...atom..Signe
|
||||
00000060: 6449 6e74 6567 6572 8484 b5b1 0664 6f75 dInteger.....dou
|
||||
00000070: 626c 65b4 b304 6174 6f6d b306 446f 7562 ble...atom..Doub
|
||||
00000080: 6c65 8484 b5b1 0762 6f6f 6c65 616e b4b3 le.....boolean..
|
||||
00000090: 0372 6566 b584 b30b 4a53 4f4e 426f 6f6c .ref....JSONBool
|
||||
000000a0: 6561 6e84 84b5 b104 6e75 6c6c b4b3 036c ean.....null...l
|
||||
000000b0: 6974 b304 6e75 6c6c 8484 b5b1 0561 7272 it..null.....arr
|
||||
000000c0: 6179 b4b3 0573 6571 6f66 b4b3 0372 6566 ay...seqof...ref
|
||||
000000d0: b584 b304 4a53 4f4e 8484 84b5 b106 6f62 ....JSON......ob
|
||||
000000e0: 6a65 6374 b4b3 0664 6963 746f 66b4 b304 ject...dictof...
|
||||
000000f0: 6174 6f6d b306 5374 7269 6e67 84b4 b303 atom..String....
|
||||
00000100: 7265 66b5 84b3 044a 534f 4e84 8484 8484 ref....JSON.....
|
||||
00000110: b30b 4a53 4f4e 426f 6f6c 6561 6eb4 b302 ..JSONBoolean...
|
||||
00000120: 6f72 b5b5 b104 7472 7565 b4b3 036c 6974 or....true...lit
|
||||
00000130: b304 7472 7565 8484 b5b1 0566 616c 7365 ..true.....false
|
||||
00000140: b4b3 036c 6974 b305 6661 6c73 6584 8484 ...lit..false...
|
||||
00000150: 8484 b30c 656d 6265 6464 6564 5479 7065 ....embeddedType
|
||||
00000160: 8084 84 ...
|
||||
|
||||
Piping the output to [`preserves-tool`](./preserves-tool.html) to
|
||||
pretty-print it produces:
|
||||
|
||||
<schema {
|
||||
version: 1,
|
||||
embeddedType: #f,
|
||||
definitions: {
|
||||
JSONBoolean: <or [
|
||||
[
|
||||
"true",
|
||||
<lit true>
|
||||
],
|
||||
[
|
||||
"false",
|
||||
<lit false>
|
||||
]
|
||||
]>,
|
||||
JSON: <or [
|
||||
[
|
||||
"string",
|
||||
<atom String>
|
||||
],
|
||||
[
|
||||
"integer",
|
||||
<atom SignedInteger>
|
||||
],
|
||||
[
|
||||
"double",
|
||||
<atom Double>
|
||||
],
|
||||
[
|
||||
"boolean",
|
||||
<ref [] JSONBoolean>
|
||||
],
|
||||
[
|
||||
"null",
|
||||
<lit null>
|
||||
],
|
||||
[
|
||||
"array",
|
||||
<seqof <ref [] JSON>>
|
||||
],
|
||||
[
|
||||
"object",
|
||||
<dictof <atom String> <ref [] JSON>>
|
||||
]
|
||||
]>
|
||||
}
|
||||
}>
|
||||
|
||||
### Multiple file (bundle)
|
||||
|
||||
Given a directory tree containing multiple `*.prs` files, running
|
||||
|
||||
preserves-schemac '**.prs'
|
||||
|
||||
will produce a binary `Bundle` on `stdout` containing one `Schema` for
|
||||
each input file in the tree.
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Installation
|
||||
|
||||
Install Racket. Then, `raco pkg install preserves`.
|
||||
|
||||
## Usage
|
||||
|
||||
usage: preserves-tool [ <option> ... ]
|
||||
|
||||
<option> is one of
|
||||
|
||||
--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)
|
||||
|
||||
Multiple single-letter switches can be combined after
|
||||
one `-`. For example, `-h-` is the same as `-h --`.
|
||||
|
|
@ -15,7 +15,7 @@
|
|||
["--atob" "Text to binary"
|
||||
(begin (set! input-format 'text)
|
||||
(set! output-format 'binary))]
|
||||
["--all" "Read until EOF"
|
||||
["--all" "Read until EOF (default)"
|
||||
(set! count +inf.0)]
|
||||
["--count" n "Read n items"
|
||||
(set! count (string->number n))]
|
||||
|
|
@ -30,15 +30,15 @@
|
|||
(set! input-format 'text)]
|
||||
[("--ob" "--output-binary") "Set binary output mode"
|
||||
(set! output-format 'binary)]
|
||||
[("--ot" "--output-text") "Set text output mode"
|
||||
[("--ot" "--output-text") "Set text output mode (default)"
|
||||
(set! output-format 'text)]
|
||||
["--indent" "Enable indent and set text output mode"
|
||||
["--indent" "Enable indent and set text output mode (default)"
|
||||
(set! output-format 'text)
|
||||
(set! indent? #t)]
|
||||
["--no-indent" "Disable indent and set text output mode"
|
||||
(set! output-format 'text)
|
||||
(set! indent? #f)]
|
||||
["--annotations" "Output annotations"
|
||||
["--annotations" "Output annotations (default)"
|
||||
(set! annotations? #t)]
|
||||
["--no-annotations" "Strip annotations"
|
||||
(set! annotations? #f)])
|
||||
|
|
|
|||
Loading…
Reference in New Issue