Update documentation
This commit is contained in:
parent
ae5f4b78ac
commit
0387cbc7eb
17
README.md
17
README.md
|
@ -1,5 +1,20 @@
|
||||||
|
# Preserves
|
||||||
|
|
||||||
Nim implementation of the [Preserves data language](https://preserves.gitlab.io/preserves/preserves.html).
|
Nim implementation of the [Preserves data language](https://preserves.gitlab.io/preserves/preserves.html).
|
||||||
|
|
||||||
|
## Library
|
||||||
|
|
||||||
|
To parse or produce Preserves one should write a
|
||||||
|
[schema](https://preserves.gitlab.io/preserves/preserves-schema.html) and
|
||||||
|
generate a Nim module using the `preserves_schema_nim` utility. This module will
|
||||||
|
contain Nim types corresponding to schema definitions. The `toPreserve` and
|
||||||
|
`fromPreserve` routines will convert Nim types to and from Preserves. The
|
||||||
|
`decodePreserves`, `parsePreserves`, `encode`, and `$` routines will convert
|
||||||
|
`Preserve` objects to and from binary and textual encoding.
|
||||||
|
|
||||||
|
To debug the `toPreserves` and `fromPreserves` routines compile with
|
||||||
|
`-d:tracePreserves`.
|
||||||
|
|
||||||
## Utilities
|
## Utilities
|
||||||
* preserves_schema_nim
|
* preserves_schema_nim
|
||||||
* preserves_encode
|
* preserves_encode
|
||||||
|
@ -7,7 +22,7 @@ Nim implementation of the [Preserves data language](https://preserves.gitlab.io/
|
||||||
* preserves_from_json
|
* preserves_from_json
|
||||||
* preserves_to_json
|
* preserves_to_json
|
||||||
|
|
||||||
## Installation
|
### Installation
|
||||||
`preserves_encode` is a multi-call binary that implements `preserves_encode`,
|
`preserves_encode` is a multi-call binary that implements `preserves_encode`,
|
||||||
`preserves_decode`, `preserves_from_json`, and `preserves_to_json`, so the
|
`preserves_decode`, `preserves_from_json`, and `preserves_to_json`, so the
|
||||||
appropriate symlinks should be created during packaging.
|
appropriate symlinks should be created during packaging.
|
||||||
|
|
|
@ -25,7 +25,7 @@ const
|
||||||
compoundKinds* = {pkRecord, pkSequence, pkSet, pkDictionary}
|
compoundKinds* = {pkRecord, pkSequence, pkSet, pkDictionary}
|
||||||
|
|
||||||
type
|
type
|
||||||
Preserve*[E = void] {.acyclic.} = object
|
Preserve*[E = void] = object
|
||||||
case kind*: PreserveKind
|
case kind*: PreserveKind
|
||||||
of pkBoolean:
|
of pkBoolean:
|
||||||
bool*: bool
|
bool*: bool
|
||||||
|
@ -104,7 +104,7 @@ proc `<`(x, y: string | seq[byte]): bool =
|
||||||
x.len < y.len
|
x.len < y.len
|
||||||
|
|
||||||
proc `<`*[A, B](x: Preserve[A]; y: Preserve[B]): bool =
|
proc `<`*[A, B](x: Preserve[A]; y: Preserve[B]): bool =
|
||||||
## Preserves have a total order over Values. Check if `x` is ordered before `y`.
|
## Preserves have a total order over values. Check if `x` is ordered before `y`.
|
||||||
if x.embedded != y.embedded:
|
if x.embedded != y.embedded:
|
||||||
result = y.embedded
|
result = y.embedded
|
||||||
elif x.kind != y.kind:
|
elif x.kind != y.kind:
|
||||||
|
@ -323,7 +323,7 @@ iterator items*(pr: Preserve): Preserve =
|
||||||
func isBoolean*(pr: Preserve): bool {.inline.} = pr.kind == pkBoolean
|
func isBoolean*(pr: Preserve): bool {.inline.} = pr.kind == pkBoolean
|
||||||
## Check if ``pr`` is a Preserve boolean.
|
## Check if ``pr`` is a Preserve boolean.
|
||||||
|
|
||||||
func isFalse*(pr: Preserve): bool =
|
func isFalse*(pr: Preserve): bool {.inline.} =
|
||||||
## Check if ``pr`` is equivalent to the zero-initialized ``Preserve``.
|
## Check if ``pr`` is equivalent to the zero-initialized ``Preserve``.
|
||||||
pr.kind == pkBoolean and pr.bool == false
|
pr.kind == pkBoolean and pr.bool == false
|
||||||
|
|
||||||
|
@ -646,6 +646,9 @@ proc toPreserve*[T](x: T; E = void): Preserve[E] =
|
||||||
## ``toPreserveHook(x: T; E: typedesc)`` in the calling scope.
|
## ``toPreserveHook(x: T; E: typedesc)`` in the calling scope.
|
||||||
## Any ``toPreserveHook`` that does not compile will be discarded;
|
## Any ``toPreserveHook`` that does not compile will be discarded;
|
||||||
## *Write tests for your hooks!*
|
## *Write tests for your hooks!*
|
||||||
|
##
|
||||||
|
## When `tracePreserves` is defined (`-d:tracePreserves`) a diagnostic
|
||||||
|
## trace is printing during `toPreserve`.
|
||||||
when (T is Preserve[E]): result = x
|
when (T is Preserve[E]): result = x
|
||||||
elif T is E: result = embed(x)
|
elif T is E: result = embed(x)
|
||||||
elif compiles(toPreserveHook(x, E)):
|
elif compiles(toPreserveHook(x, E)):
|
||||||
|
@ -764,10 +767,13 @@ proc fromPreserve*[T, E](v: var T; pr: Preserve[E]): bool =
|
||||||
## Can be customized with `fromPreserveHook[E](x: T; var pr: Preserve[E]): bool`.
|
## Can be customized with `fromPreserveHook[E](x: T; var pr: Preserve[E]): bool`.
|
||||||
## Any ``fromPreserveHook`` that does not compile will be discarded;
|
## Any ``fromPreserveHook`` that does not compile will be discarded;
|
||||||
## *Write tests for your hooks!*
|
## *Write tests for your hooks!*
|
||||||
|
##
|
||||||
|
## When `tracePreserves` is defined (`-d:tracePreserves`) a diagnostic
|
||||||
|
## trace is printing during `fromPreserve`.
|
||||||
# TODO: {.raises: [].}
|
# TODO: {.raises: [].}
|
||||||
runnableExamples:
|
runnableExamples:
|
||||||
import preserves, preserves/parse
|
import preserves, preserves/parse
|
||||||
type Foo {.record: "foo".} = object
|
type Foo {.preservesRecord: "foo".} = object
|
||||||
x, y: int
|
x, y: int
|
||||||
var foo: Foo
|
var foo: Foo
|
||||||
assert(fromPreserve(foo, parsePreserves("""<foo 1 2>""")))
|
assert(fromPreserve(foo, parsePreserves("""<foo 1 2>""")))
|
||||||
|
@ -944,7 +950,7 @@ proc preserveTo*(pr: Preserve; T: typedesc): Option[T] =
|
||||||
# TODO: {.raises: [].}
|
# TODO: {.raises: [].}
|
||||||
runnableExamples:
|
runnableExamples:
|
||||||
import std/options, preserves, preserves/parse
|
import std/options, preserves, preserves/parse
|
||||||
type Foo {.record: "foo".} = object
|
type Foo {.preservesRecord: "foo".} = object
|
||||||
x, y: int
|
x, y: int
|
||||||
|
|
||||||
assert(parsePreserves("""<foo "abc">""").preserveTo(Foo).isNone)
|
assert(parsePreserves("""<foo "abc">""").preserveTo(Foo).isNone)
|
||||||
|
|
Loading…
Reference in New Issue