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).
|
||||
|
||||
## 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
|
||||
* preserves_schema_nim
|
||||
* preserves_encode
|
||||
|
@ -7,7 +22,7 @@ Nim implementation of the [Preserves data language](https://preserves.gitlab.io/
|
|||
* preserves_from_json
|
||||
* preserves_to_json
|
||||
|
||||
## Installation
|
||||
### Installation
|
||||
`preserves_encode` is a multi-call binary that implements `preserves_encode`,
|
||||
`preserves_decode`, `preserves_from_json`, and `preserves_to_json`, so the
|
||||
appropriate symlinks should be created during packaging.
|
||||
|
|
|
@ -25,7 +25,7 @@ const
|
|||
compoundKinds* = {pkRecord, pkSequence, pkSet, pkDictionary}
|
||||
|
||||
type
|
||||
Preserve*[E = void] {.acyclic.} = object
|
||||
Preserve*[E = void] = object
|
||||
case kind*: PreserveKind
|
||||
of pkBoolean:
|
||||
bool*: bool
|
||||
|
@ -104,7 +104,7 @@ proc `<`(x, y: string | seq[byte]): bool =
|
|||
x.len < y.len
|
||||
|
||||
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:
|
||||
result = y.embedded
|
||||
elif x.kind != y.kind:
|
||||
|
@ -323,7 +323,7 @@ iterator items*(pr: Preserve): Preserve =
|
|||
func isBoolean*(pr: Preserve): bool {.inline.} = pr.kind == pkBoolean
|
||||
## 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``.
|
||||
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.
|
||||
## Any ``toPreserveHook`` that does not compile will be discarded;
|
||||
## *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
|
||||
elif T is E: result = embed(x)
|
||||
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`.
|
||||
## Any ``fromPreserveHook`` that does not compile will be discarded;
|
||||
## *Write tests for your hooks!*
|
||||
##
|
||||
## When `tracePreserves` is defined (`-d:tracePreserves`) a diagnostic
|
||||
## trace is printing during `fromPreserve`.
|
||||
# TODO: {.raises: [].}
|
||||
runnableExamples:
|
||||
import preserves, preserves/parse
|
||||
type Foo {.record: "foo".} = object
|
||||
type Foo {.preservesRecord: "foo".} = object
|
||||
x, y: int
|
||||
var foo: Foo
|
||||
assert(fromPreserve(foo, parsePreserves("""<foo 1 2>""")))
|
||||
|
@ -944,7 +950,7 @@ proc preserveTo*(pr: Preserve; T: typedesc): Option[T] =
|
|||
# TODO: {.raises: [].}
|
||||
runnableExamples:
|
||||
import std/options, preserves, preserves/parse
|
||||
type Foo {.record: "foo".} = object
|
||||
type Foo {.preservesRecord: "foo".} = object
|
||||
x, y: int
|
||||
|
||||
assert(parsePreserves("""<foo "abc">""").preserveTo(Foo).isNone)
|
||||
|
|
Loading…
Reference in New Issue