Preserves schemas
This commit is contained in:
parent
7433ef3f94
commit
268c652f6b
|
@ -46,9 +46,9 @@
|
|||
|
||||
# Protocols and Schema Definitions
|
||||
|
||||
- [Preserves schemas]()
|
||||
- [Preserves Schema metaschema]()
|
||||
- [Preserves Path schema]()
|
||||
- [Preserves schemas](protocols/preserves/index.md)
|
||||
- [Preserves Schema metaschema](protocols/preserves/schema.md)
|
||||
- [Preserves Path schema](protocols/preserves/path.md)
|
||||
- [Syndicated Actor Model schemas]()
|
||||
- ["Observe" assertions]()
|
||||
- [Patterns over assertions]()
|
||||
|
|
|
@ -0,0 +1,4 @@
|
|||
# Preserves schemas
|
||||
|
||||
The following pages document schemas associated with the [Preserves](../../guide/preserves.md)
|
||||
data language and its tools.
|
|
@ -0,0 +1,108 @@
|
|||
# Preserves Path schema
|
||||
|
||||
[Preserves Path](https://preserves.dev/preserves-path.html) is a language for selecting and
|
||||
filtering portions of a Preserves value. It has an associated schema describing the various
|
||||
kinds of Path expressions as abstract syntax.
|
||||
|
||||
The schema source below is taken from
|
||||
[path/path.prs](https://gitlab.com/preserves/preserves/-/blob/main/path/path.prs) in the
|
||||
[Preserves source code repository](https://gitlab.com/preserves/preserves).
|
||||
|
||||
Preserves Path expressions come in several flavours: selectors, steps (axes and filters), and
|
||||
predicates. Each is described below along with its abstract syntax definitions.
|
||||
|
||||
## Selectors and Steps
|
||||
|
||||
*Selectors* are a sequence of *steps*, applied one after the other to the currently-selected
|
||||
value. Each step transforms an input into zero or more outputs. A step is an *axis* or a
|
||||
*filter*.
|
||||
|
||||
```preserves-schema
|
||||
Selector = [Step ...] .
|
||||
Step = Axis / Filter .
|
||||
```
|
||||
|
||||
## Axes: selecting portions of the input
|
||||
|
||||
Each *axis* step generally selects some sub-portion or -portions of the current document. An
|
||||
axis may also have a secondary filtering effect: for example, `label` only applies to Records,
|
||||
and will yield an empty result set when applied to any other kind of input.
|
||||
|
||||
```preserves-schema
|
||||
Axis =
|
||||
/ <values> ;; yields the immediate subvalues of the input nonrecursively
|
||||
/ <descendants> ;; recurses through all descendant subvalues of the input
|
||||
/ <at @key any> ;; extracts a subvalue named by the given key, if any
|
||||
/ <label> ;; extracts a Record's label, if any
|
||||
/ <keys> ;; extracts all keys (for subvalues) of the input, nonrecursively
|
||||
/ <length> ;; extracts the length/size of the input, if any
|
||||
/ <annotations> ;; extracts all annotations attached to the input
|
||||
/ <embedded> ;; moves into the representation of an embedded value, if any
|
||||
/ <parse @module [symbol ...] @name symbol> ;; parses using Preserves Schema
|
||||
/ <unparse @module [symbol ...] @name symbol> ;; unparses using Preserves Schema
|
||||
.
|
||||
```
|
||||
|
||||
The `parse` and `unparse` variants name [Schema](../../guide/preserves.md#schemas) definitions,
|
||||
to be resolved by the eventual surrounding context in which the expression will be executed. A
|
||||
`parse` axis parses the input using a Schema definition; if the parse succeeds, the axis moves
|
||||
into the parse result. Similarly, `unparse` expects an abstract parse result, transforming it
|
||||
back into a concrete value according to the Schema definition.
|
||||
|
||||
## Filters: rejecting inputs
|
||||
|
||||
Each *filter* step generally applies some test to the current document as a whole, either
|
||||
emitting it unchanged (with exceptions, detailed below) or emitting no outputs at all.
|
||||
|
||||
```preserves-schema
|
||||
Filter =
|
||||
/ <nop> ;; Always emit the input
|
||||
/ <compare @op Comparison @literal any> ;; Emit iff the comparison holds
|
||||
/ <regex @regex string> ;; Emit iff input is String and regex matches
|
||||
/ <test @pred Predicate> ;; Apply complex predicate
|
||||
/ <real> ;; Emit iff input is Float, Double, or Integer
|
||||
/ <int> ;; TRUNCATE and emit iff Float, Double or Integer
|
||||
/ <kind @kind ValueKind> ;; Emit iff input kind matches
|
||||
.
|
||||
```
|
||||
|
||||
### Complex predicates
|
||||
|
||||
The complex predicates in a `test` filter are built up from logical connectives over selectors.
|
||||
A `Selector` predicate evaluates to true whenever, applied to its input, it results in a
|
||||
non-empty output set.
|
||||
|
||||
```preserves-schema
|
||||
Predicate =
|
||||
/ Selector
|
||||
/ <not @pred Predicate>
|
||||
/ <or @preds [Predicate ...]>
|
||||
/ <and @preds [Predicate ...]>
|
||||
.
|
||||
```
|
||||
|
||||
### Comparison against a literal
|
||||
|
||||
Each `compare` filter includes a `Comparison` and a literal value to compare the input against.
|
||||
For example, `<compare eq 3>` only produces an output if the input is equal (according to the
|
||||
[Preserves semantic model](https://preserves.dev/preserves.html#starting-with-semantics)) to
|
||||
`3`.
|
||||
|
||||
```preserves-schema
|
||||
Comparison = =eq / =ne / =lt / =ge / =gt / =le .
|
||||
```
|
||||
|
||||
**NB.** For inequalities (`lt`/`ge`/`gt`/`le`), comparison between values of different kinds is
|
||||
undefined in the current draft specification.
|
||||
|
||||
### Filtering by value kind
|
||||
|
||||
Each `kind` filter selects only values from one of the kinds of Preserves value:
|
||||
|
||||
```preserves-schema
|
||||
ValueKind =
|
||||
/ =Boolean / =Float / =Double / =SignedInteger / =String / =ByteString / =Symbol
|
||||
/ =Record / =Sequence / =Set / =Dictionary
|
||||
/ =Embedded
|
||||
.
|
||||
```
|
|
@ -0,0 +1,8 @@
|
|||
# Preserves Schema metaschema
|
||||
|
||||
The Preserves Schema metaschema defines the structure of the abstract syntax (AST) of schemas.
|
||||
Every valid Preserves Schema document can be represented as an instance of the metaschema. (And
|
||||
of course the metaschema is itself a schema, which is in turn an instance of the metaschema!)
|
||||
|
||||
⟶ See [Appendix A: "Metaschema" of the Preserves Schema
|
||||
specification](https://preserves.dev/preserves-schema.html#appendix-metaschema).
|
Loading…
Reference in New Issue