Capabilities, Flags and Errors

Data Structures
struct	SerPathFrame
struct	SerTraverseState

Typedefs
typedef struct SerPathFrame	SerPathFrame
typedef struct SerTraverseState	SerTraverseState

Enumerations
enum	SerCapabilitiesEnum {   SER_Cap_NonStringKeys = (1 << 0) , SER_Cap_Bytes = (1 << 1) , SER_Cap_TypeTags = (1 << 2) , SER_Cap_Refs = (1 << 3) ,   SER_Cap_ExactInt = (1 << 4) , SER_Cap_Skip = (1 << 5) , SER_Cap_Sizes = (1 << 6) }
enum	SerFlagsEnum {   SER_JSON_Pretty = 0x00000001 , SER_JSON_Compact = 0x00000002 , SER_Bin_Compact = 0x00000100 , SER_Bin_NoStringDedup = 0x00000200 ,   SER_EmitDefaults = 0x01000000 , SER_Refs = 0x02000000 , SER_Strict = 0x10000000 , SER_Collect = 0x20000000 }
	Per-document options, passed to a backend's create function. More...
enum	SerErrorCodeEnum { }
	Error codes reported through SerError::code. More...

Functions
void	serPathString (string *out, const SerTraverseState *ws)

Detailed Description

Typedef Documentation

SerPathFrame

typedef struct SerPathFrame SerPathFrame

One frame of the traverser's location within the document.

The traverser pushes a frame per level as it descends and materializes them into SerError::path only when an error is actually raised, so the common path costs a push and a pop and no allocation.

SerTraverseState

typedef struct SerTraverseState SerTraverseState

Traverser state shared by both directions.

Embedded in SerWriter and SerReader alike; the traverser's error and path helpers take a pointer to this rather than to one of the two.

Enumeration Type Documentation

SerCapabilitiesEnum

enum SerCapabilitiesEnum

What a backend can represent.

A backend advertises these in SerWriter::caps / SerReader::caps so the traverser, and any custom type with its own serialize/deserialize hook, can adapt – for example, writing a byte buffer as raw bytes if SER_Cap_Bytes is set, or as a base64 string otherwise.

Enumerator
SER_Cap_NonStringKeys	maps may be keyed by arbitrary values
SER_Cap_Bytes	native binary blob node
SER_Cap_TypeTags	type annotations are preserved
SER_Cap_Refs	SER_RefDef / SER_RefUse are honored.
SER_Cap_ExactInt	the full int64/uint64 range round-trips exactly
SER_Cap_Skip	the reader can skip over an unknown value
SER_Cap_Sizes	container counts are known before their contents

Definition at line 145 of file sertype.h.

SerErrorCodeEnum

enum SerErrorCodeEnum

Error codes reported through SerError::code.

Enumerator
SER_Err_Backend	the backend refused or failed to emit/consume a node
SER_Err_Type	a type cannot be serialized, or is not what the schema said
SER_Err_Schema	the schema is missing or malformed where one is required
SER_Err_Data	the data does not match what the schema expects
SER_Err_Unsupported	the backend lacks a capability this value needs
SER_Err_Overflow	a value does not fit the slot it is being read into

Definition at line 177 of file sertype.h.

SerFlagsEnum

enum SerFlagsEnum

Per-document options, passed to a backend's create function.

Enumerator
SER_JSON_Pretty	4-space indent
SER_JSON_Compact	single line
SER_Bin_Compact	omit type tags
SER_Bin_NoStringDedup	inline string values
SER_EmitDefaults	write members equal to their default
SER_Refs	enable reference dedup where supported
SER_Strict	unknown fields and lossy cases are errors
SER_Collect	Accumulate errors instead of stopping at the first one. Not yet fully implemented -- traversal currently still stops at the first error.

Definition at line 156 of file sertype.h.

Function Documentation

serPathString()

void serPathString	(	string *	out,
		const SerTraverseState *	ws
	)

Renders the current path stack as a document path string.

Parameters

out	Receives the path, e.g. "/config/servers[3]/port"; "/" at the document root
ws	Traverser state to read the path stack from