preserves.dev

This commit is contained in:
Tony Garnock-Jones 2022-05-24 14:04:03 +02:00
parent 3f70c7a256
commit 4a93ede771
6 changed files with 25 additions and 25 deletions

View File

@ -308,7 +308,7 @@ language, the Preserves concept of an *embedded value* is used in the SAM to rel
portions of a datum referring to SAM entities. portions of a datum referring to SAM entities.
Concretely, in [Preserves text Concretely, in [Preserves text
syntax](https://preserves.gitlab.io/preserves/preserves.html#textual-syntax), embedded values syntax](https://preserves.dev/preserves.html#textual-syntax), embedded values
appear prepended with `#!`. In messages transferred across links using the [Syndicate network appear prepended with `#!`. In messages transferred across links using the [Syndicate network
protocol][], references might appear as `#![0 123]`, `#![1 555]`, etc. etc. protocol][], references might appear as `#![0 123]`, `#![1 555]`, etc. etc.
@ -664,7 +664,7 @@ schema is as a specification of the allowable shapes for data to be used in a pa
context. context.
Synit, and many programs making use of the [Syndicated Actor Model][], uses [Preserves][]' Synit, and many programs making use of the [Syndicated Actor Model][], uses [Preserves][]'
[schema language](https://preserves.gitlab.io/preserves/preserves-schema.html) to define [schema language](https://preserves.dev/preserves-schema.html) to define
schemas for many different applications. schemas for many different applications.
For more, see [the section on schemas in the chapter on For more, see [the section on schemas in the chapter on

View File

@ -3,9 +3,9 @@
Synit makes **extensive** use of *Preserves*, a programming-language-independent language for Synit makes **extensive** use of *Preserves*, a programming-language-independent language for
data. data.
- [Preserves homepage](https://preserves.gitlab.io/) - [Preserves homepage](https://preserves.dev/)
- [Preserves specification](https://preserves.gitlab.io/preserves/preserves.html) - [Preserves specification](https://preserves.dev/preserves.html)
- [Preserves Schema specification](https://preserves.gitlab.io/preserves/preserves-schema.html) - [Preserves Schema specification](https://preserves.dev/preserves-schema.html)
- [Source code](https://gitlab.com/preserves/preserves) for many (not all) of the implementations - [Source code](https://gitlab.com/preserves/preserves) for many (not all) of the implementations
- Implementations for - Implementations for
[Nim](https://git.sr.ht/~ehmry/preserves-nim), [Nim](https://git.sr.ht/~ehmry/preserves-nim),
@ -17,7 +17,7 @@ data.
The Preserves data language is in many ways comparable to JSON, XML, S-expressions, CBOR, ASN.1 The Preserves data language is in many ways comparable to JSON, XML, S-expressions, CBOR, ASN.1
BER, and so on. From the [specification BER, and so on. From the [specification
document](https://preserves.gitlab.io/preserves/preserves.html): document](https://preserves.dev/preserves.html):
> Preserves supports *records* with user-defined *labels*, embedded *references*, and the usual > Preserves supports *records* with user-defined *labels*, embedded *references*, and the usual
> suite of atomic and compound data types, including *binary* data as a distinct type from text > suite of atomic and compound data types, including *binary* data as a distinct type from text
@ -64,7 +64,7 @@ is a syntactic superset of JSON, and a completely equivalent compact binary synt
the definition of [canonical form](#canonical-form) for Preserves values.[^syrup] the definition of [canonical form](#canonical-form) for Preserves values.[^syrup]
Here are a few example values, written using the text syntax (see [the Here are a few example values, written using the text syntax (see [the
specification](https://preserves.gitlab.io/preserves/preserves.html#textual-syntax) for the specification](https://preserves.dev/preserves.html#textual-syntax) for the
grammar): grammar):
Boolean : #t #f Boolean : #t #f
@ -85,8 +85,8 @@ Commas are optional in sequences, sets, and dictionaries.
### Canonical form ### Canonical form
Every Preserves value can be serialized into a *canonical form* using the [binary Every Preserves value can be serialized into a *canonical form* using the [binary
syntax](https://preserves.gitlab.io/preserves/preserves.html#compact-binary-syntax) along with syntax](https://preserves.dev/preserves.html#compact-binary-syntax) along with
[a few simple rules](https://preserves.gitlab.io/preserves/canonical-binary.html) about [a few simple rules](https://preserves.dev/canonical-binary.html) about
serialization ordering of elements in sets and keys in dictionaries. serialization ordering of elements in sets and keys in dictionaries.
Having a canonical form means that, for example, a cryptographic hash of a value's canonical Having a canonical form means that, for example, a cryptographic hash of a value's canonical
@ -140,7 +140,7 @@ rewriting capability references happens when an in-memory value is serialized fo
Preserves comes with a schema language suitable for defining protocols among actors/programs in Preserves comes with a schema language suitable for defining protocols among actors/programs in
Synit. Because Preserves is a superset of JSON, its schemas can be used for parsing JSON just Synit. Because Preserves is a superset of JSON, its schemas can be used for parsing JSON just
as well as for native Preserves values.[^you-have-to-use-a-preserves-reader] From the [schema as well as for native Preserves values.[^you-have-to-use-a-preserves-reader] From the [schema
specification](https://preserves.gitlab.io/preserves/preserves-schema.html): specification](https://preserves.dev/preserves-schema.html):
> A Preserves schema connects Preserves Values to host-language data > A Preserves schema connects Preserves Values to host-language data
> structures. Each definition within a schema can be processed by a > structures. Each definition within a schema can be processed by a
@ -325,7 +325,7 @@ Here's the Preserves value equivalent to the example above, expressed using the
can't reliably tell whether two values are the same or different, how are you supposed to can't reliably tell whether two values are the same or different, how are you supposed to
use them to look things up in anything database-like? use them to look things up in anything database-like?
Languages like JSON, which [don't have a well-defined equivalence Languages like JSON, which [don't have a well-defined equivalence
relation](https://preserves.gitlab.io/preserves/why-not-json.html#json-syntax-doesnt-mean-anything), relation](https://preserves.dev/why-not-json.html#json-syntax-doesnt-mean-anything),
aren't good enough. When programs communicate with each other, they need to be sure that aren't good enough. When programs communicate with each other, they need to be sure that
their peers will understand the information they receive exactly as it was sent. their peers will understand the information they receive exactly as it was sent.

View File

@ -1,9 +1,9 @@
# Working with schemas # Working with schemas
- [Preserves schema specification](https://preserves.gitlab.io/preserves/preserves-schema.html) - [Preserves schema specification](https://preserves.dev/preserves-schema.html)
- [Index of Preserves schema tools](https://preserves.gitlab.io/preserves/doc/schema-tools.html) - [Index of Preserves schema tools](https://preserves.dev/doc/schema-tools.html)
[preserves-schemac]: https://preserves.gitlab.io/preserves/doc/preserves-schemac.html [preserves-schemac]: https://preserves.dev/doc/preserves-schemac.html
## Schema source code: *.prs files ## Schema source code: *.prs files
@ -26,7 +26,7 @@ above is placed in `simpleChatProtocol.prs`.
Many of the code generator tools for Preserves schemas require not source code, but instances Many of the code generator tools for Preserves schemas require not source code, but instances
of the [Preserves of the [Preserves
metaschema](https://preserves.gitlab.io/preserves/preserves-schema.html#appendix-metaschema). metaschema](https://preserves.dev/preserves-schema.html#appendix-metaschema).
To compile schema source code to metaschema instances, use To compile schema source code to metaschema instances, use
[preserves-schemac][]: [preserves-schemac][]:
@ -141,7 +141,7 @@ Generate Rust definitions corresponding to a metaschema instance with [preserves
The best way to use it is to integrate it into your `build.rs` (see [the The best way to use it is to integrate it into your `build.rs` (see [the
docs][preserves-schema-rs]), but you can also use it as a standalone command-line tool. docs][preserves-schema-rs]), but you can also use it as a standalone command-line tool.
[preserves-schema-rs]: https://preserves.gitlab.io/preserves/doc/preserves-schema-rs.html [preserves-schema-rs]: https://preserves.dev/doc/preserves-schema-rs.html
The following command generates a directory `./rs/chat` containing rust sources for a module The following command generates a directory `./rs/chat` containing rust sources for a module
that expects to be called `chat` in Rust code: that expects to be called `chat` in Rust code:
@ -179,7 +179,7 @@ Generate TypeScript definitions from schema **sources** (not metaschema instance
[preserves-schema-ts][]. Unlike other code generators, this one understands schema source code [preserves-schema-ts][]. Unlike other code generators, this one understands schema source code
directly. directly.
[preserves-schema-ts]: https://preserves.gitlab.io/preserves/doc/preserves-schema-ts.html [preserves-schema-ts]: https://preserves.dev/doc/preserves-schema-ts.html
The following command generates a directory `./ts/gen` containing TypeScript sources: The following command generates a directory `./ts/gen` containing TypeScript sources:

View File

@ -11,7 +11,7 @@ Synit builds upon many existing technologies, but primarily relies on the follow
- [PostmarketOS](https://postmarketos.org/). Synit builds on PostmarketOS, replacing only a - [PostmarketOS](https://postmarketos.org/). Synit builds on PostmarketOS, replacing only a
few core packages. All of PostmarketOS and Alpine Linux are available underneath Synit. few core packages. All of PostmarketOS and Alpine Linux are available underneath Synit.
- [Preserves](https://preserves.gitlab.io/). The Preserves data language and its associated - [Preserves](https://preserves.dev/). The Preserves data language and its associated
schema and query languages are central to Synit. schema and query languages are central to Synit.
- [Syndicate](https://syndicate-lang.org/). Syndicate is an umbrella project for tools and - [Syndicate](https://syndicate-lang.org/). Syndicate is an umbrella project for tools and
@ -53,7 +53,7 @@ overview of the contents of the repository.
Synit depends on published packages for Preserves and Syndicate support in each of the many Synit depends on published packages for Preserves and Syndicate support in each of the many
programming languages it uses. These will be automatically found and downloaded during the programming languages it uses. These will be automatically found and downloaded during the
Synit build process, but you can find details on the [Preserves](https://preserves.gitlab.io/) Synit build process, but you can find details on the [Preserves](https://preserves.dev/)
and [Syndicate](https://syndicate-lang.org/) homepages, respectively. and [Syndicate](https://syndicate-lang.org/) homepages, respectively.
For the Smalltalk-based phone-management and UI part of the system, you will need a number of For the Smalltalk-based phone-management and UI part of the system, you will need a number of

View File

@ -31,13 +31,13 @@ name](#the-active-target).
*Program* = *Instruction* ... *Program* = *Instruction* ...
A configuration source file is a file whose name ends in `.pr` that contains zero or more A configuration source file is a file whose name ends in `.pr` that contains zero or more
Preserves [text-syntax](https://preserves.gitlab.io/preserves/preserves.html#textual-syntax) Preserves [text-syntax](https://preserves.dev/preserves.html#textual-syntax)
values, which are together interpreted as a sequence of *Instruction*s. values, which are together interpreted as a sequence of *Instruction*s.
**Comments.** [Preserves **Comments.** [Preserves
comments](https://preserves.gitlab.io/preserves/conventions.html#comments) are ignored. One comments](https://preserves.dev/conventions.html#comments) are ignored. One
unfortunate wart is that because Preserves comments are really unfortunate wart is that because Preserves comments are really
[annotations](https://preserves.gitlab.io/preserves/preserves.html#annotations), they are [annotations](https://preserves.dev/preserves.html#annotations), they are
required by the Preserves data model to be attached to some other value. Syntactically, this required by the Preserves data model to be attached to some other value. Syntactically, this
manifests as the need for *some non-comment following every comment*. In scripts written to manifests as the need for *some non-comment following every comment*. In scripts written to
date, often an empty *SequencingInstruction* serves to anchor comments at the end of a file: date, often an empty *SequencingInstruction* serves to anchor comments at the end of a file:

View File

@ -686,13 +686,13 @@ care should be taken in the case of non-cryptographic transport protocols like p
To use such a transport for this protocol, establish a connection and begin transmitting To use such a transport for this protocol, establish a connection and begin transmitting
[`Packet`s](#packet-definitions) encoded as Preserves values using either the Preserves [text [`Packet`s](#packet-definitions) encoded as Preserves values using either the Preserves [text
syntax](https://preserves.gitlab.io/preserves/preserves.html#textual-syntax) or the Preserves syntax](https://preserves.dev/preserves.html#textual-syntax) or the Preserves
[binary syntax](https://preserves.gitlab.io/preserves/preserves.html#compact-binary-syntax). [binary syntax](https://preserves.dev/preserves.html#compact-binary-syntax).
The session starts with the first packet and ends with transport disconnection. If either peer The session starts with the first packet and ends with transport disconnection. If either peer
in a connection detects a syntax error, it MUST disconnect the transport. A responding server in a connection detects a syntax error, it MUST disconnect the transport. A responding server
MUST support the binary syntax, and MAY also support the text syntax. It can autodetect the MUST support the binary syntax, and MAY also support the text syntax. It can autodetect the
syntax variant by following [the rules in the syntax variant by following [the rules in the
specification](https://preserves.gitlab.io/preserves/preserves.html#appendix-autodetection-of-textual-or-binary-syntax): specification](https://preserves.dev/preserves.html#appendix-autodetection-of-textual-or-binary-syntax):
the first byte of a valid binary-syntax Preserves document is guaranteed not to be the first byte of a valid binary-syntax Preserves document is guaranteed not to be
interpretable as the start of a valid UTF-8 sequence. interpretable as the start of a valid UTF-8 sequence.