Skip to content

Serialization extensions docs #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nitely wants to merge 1 commit into
base: main
Choose a base branch
from
+25 −0
Open

Serialization extensions docs #9

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/src/extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# (De)Serialization Extensions

### Cbor specific

- `isFieldExpected*(T: type): bool`. Overload to return whether the type is an optional obj field. Used for deserializing.
- `shouldWriteObjectField[T](field: T): bool`. Overload to return whether the obj field should be written based on the field-value. Used for serializing. If `true` the field will be omited when `omitOptionalFields` is `true` for the created flavor.
- `writeObjectField(...)` serializes an obj field name and value. Note: Only internal usages found.

### nim-serialization specific

- `writeValue`/`readValue` the main way to overload the (de)serialization for a value type of a given flavor(s).

- `useDefaultSerializationIn(T: untyped, Flavor: type)` generates `writeValue`/`readValue` for a specific type `T`. It only supports `object | ref object | ptr object` types. Relies on `writeRecordValue`/`readRecordValue`.
- `writeRecordValue(w: var FormatWriter, value: object | tuple)`. Overload to write a specific object/tuple.
- `readRecordValue(r: var FormatReader, value: var (object | tuple))`. Overload to read a specific object/tuple.

- `useCustomSerialization(Format: typed, field: untyped, body: untyped)` generates `readFieldIMPL` and `writeFieldIMPL` overloads for the format (flavor or default), `MyObjType` (or `MyObjType.myField`) and (de)serializer body. The difference with `writeValue`/`readValue` is it can be specific to an object field.
- `writeFieldIMPL`. Overload serialize a flavor, object field and value. Otherwise `writeValue` is used.
- `readFieldIMPL`. Overload to deserialize a flavor, object field and value. Otherwise `readValue` is used.
- Note: this is used in `ssz_serialization`, but the usage can be replaced by overloading writeValue/readValue instead as the "field" provided is a `distinct MyType` and not an `objType.field`.

- `generateAutoSerializationAddon(FLAVOR: typed)`. Generates some functions to enable/disable (de)serialization for a flavor. The serialization library needs to check whether the value type is enabled/disable before (de)serializing it.
- `setAutoSerialize(F: type FLAVOR, T: distinct type, val: bool)`. Enable/disable the flavor (de)serialization for type `T`.
- `typeClassOrMemberAutoSerialize(F: type FLAVOR, TC: distinct type, TM: distinct type): bool`. Check whether a type or its parent type class have automatic serialization flag.
- `typeAutoSerialize(F: type FLAVOR, TM: distinct type): bool`. Check if a type has automatic serialization flag.