diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 3ee0ecd..9a6af65 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -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]() diff --git a/src/protocols/preserves/index.md b/src/protocols/preserves/index.md new file mode 100644 index 0000000..969be76 --- /dev/null +++ b/src/protocols/preserves/index.md @@ -0,0 +1,4 @@ +# Preserves schemas + +The following pages document schemas associated with the [Preserves](../../guide/preserves.md) +data language and its tools. diff --git a/src/protocols/preserves/path.md b/src/protocols/preserves/path.md new file mode 100644 index 0000000..2595c9f --- /dev/null +++ b/src/protocols/preserves/path.md @@ -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 = +/ ;; yields the immediate subvalues of the input nonrecursively +/ ;; recurses through all descendant subvalues of the input +/ ;; extracts a subvalue named by the given key, if any +/