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 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)
|
- [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
|
## Additional resources
|
||||||
|
|
||||||
- Some [conventions for common data types](conventions.html)
|
- 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"
|
["--atob" "Text to binary"
|
||||||
(begin (set! input-format 'text)
|
(begin (set! input-format 'text)
|
||||||
(set! output-format 'binary))]
|
(set! output-format 'binary))]
|
||||||
["--all" "Read until EOF"
|
["--all" "Read until EOF (default)"
|
||||||
(set! count +inf.0)]
|
(set! count +inf.0)]
|
||||||
["--count" n "Read n items"
|
["--count" n "Read n items"
|
||||||
(set! count (string->number n))]
|
(set! count (string->number n))]
|
||||||
|
@ -30,15 +30,15 @@
|
||||||
(set! input-format 'text)]
|
(set! input-format 'text)]
|
||||||
[("--ob" "--output-binary") "Set binary output mode"
|
[("--ob" "--output-binary") "Set binary output mode"
|
||||||
(set! output-format 'binary)]
|
(set! output-format 'binary)]
|
||||||
[("--ot" "--output-text") "Set text output mode"
|
[("--ot" "--output-text") "Set text output mode (default)"
|
||||||
(set! output-format 'text)]
|
(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! output-format 'text)
|
||||||
(set! indent? #t)]
|
(set! indent? #t)]
|
||||||
["--no-indent" "Disable indent and set text output mode"
|
["--no-indent" "Disable indent and set text output mode"
|
||||||
(set! output-format 'text)
|
(set! output-format 'text)
|
||||||
(set! indent? #f)]
|
(set! indent? #f)]
|
||||||
["--annotations" "Output annotations"
|
["--annotations" "Output annotations (default)"
|
||||||
(set! annotations? #t)]
|
(set! annotations? #t)]
|
||||||
["--no-annotations" "Strip annotations"
|
["--no-annotations" "Strip annotations"
|
||||||
(set! annotations? #f)])
|
(set! annotations? #f)])
|
||||||
|
|
Loading…
Reference in New Issue