Writers

Data Structures
struct	SerWriterOps
struct	SerWriter

Macros
#define	serWriterCaps(w)   ((w)->caps)
#define	serWriterCan(w, capname)   (((w)->caps & SER_Cap_##capname) != 0)
#define	serWrite(w, type, val)   _serWrite(w, stExt(type), stArg(type, val))

Typedefs
typedef struct SerWriter	SerWriter
typedef struct SerWriterOps	SerWriterOps

Functions
SerWriter *	_serWriterAlloc (size_t size, const SerWriterOps *ops, flags_t caps, flags_t flags)
bool	serWriterFinish (SerWriter *w)
void	serWriterDestroy (SerWriter **w)
bool	serWriterFail (SerWriter *w, int32 code, strref msg)

Detailed Description

Macro Definition Documentation

serWrite

#define serWrite	(		w,
			type,
			val
	)		_serWrite(w, stExt(type), stArg(type, val))

bool serWrite(SerWriter *w, type, value)

Writes a value to the given backend (JSON, binary, etc.).

The type name supplies both what the value is at runtime and what it is declared to be on the wire, so nested struct members and array/hashtable element types come along with it.

Parameters

w	Backend to write to
type	Type name of the value
val	The value

Returns

true on success; on failure the error is left in w->err

Example:

SerWriter *w = serSsdWriterCreate(0);
serWrite(w, MyStruct, val);
serWriterFinish(w);

Definition at line 188 of file serwriter.h.

serWriterCan

#define serWriterCan	(		w,
			capname
	)		(((w)->caps & SER_Cap_##capname) != 0)

bool serWriterCan(SerWriter *w, capname)

Tests one capability of a writer.

Parameters

w	Writer to query
capname	Capability name without the SER_Cap_ prefix, e.g. Bytes

Example:

if (serWriterCan(w, Bytes))
    serWriteBytes(w, data, len);

Definition at line 123 of file serwriter.h.

serWriterCaps

#define serWriterCaps

(

w

)

((w)->caps)

flags_t serWriterCaps(SerWriter *w)

The capabilities this writer's backend advertises.

Definition at line 109 of file serwriter.h.

Typedef Documentation

SerWriter

typedef struct SerWriter SerWriter

A handle for an in-progress write, returned by a backend's create function (e.g. serJsonWriterCreate). Opaque to callers – pass it to serWrite() and the other functions in this header without needing to know which backend produced it.

Definition at line 15 of file serwriter.h.

SerWriterOps

typedef struct SerWriterOps SerWriterOps

A serialization format, defined as a set of operations for writing each kind of value.

Implement this once to add a new backend (JSON, binary, etc.). Every operation returns false on failure and leaves a description in w->err.

Function Documentation

_serWriterAlloc()

SerWriter * _serWriterAlloc	(	size_t	size,
		const SerWriterOps *	ops,
		flags_t	caps,
		flags_t	flags
	)

Allocates a writer of the given total size and fills in the generic header.

Shared by every backend's create function, which supplies sizeof its own private struct and then only has to write its own fields.

Parameters

size	Total size of the backend's private struct, whose first member must be a SerWriter
ops	The backend's vtable
caps	Capabilities this backend advertises
flags	Per-document options

Returns

A zero-filled writer; never NULL

serWriterDestroy()

void serWriterDestroy

(

SerWriter **

w

)

Releases the writer and sets the handle to NULL.

The free is left to the backend's destroy rather than done here, so a backend stays free to allocate from somewhere other than xalloc.

Parameters

w	Pointer to the writer handle; set to NULL on return

serWriterFail()

bool serWriterFail	(	SerWriter *	w,
		int32	code,
		strref	msg
	)

Records an error against a writer and aborts the traversal.

Materializes the current path from the traverser's frame stack, which is why this is the only supported way to fail out of a custom-type write hook.

Parameters

w	Writer to fail
code	SerErrorCodeEnum
msg	Human-readable description; copied

Returns

always false, so a failing op can return serWriterFail(...)

serWriterFinish()

bool serWriterFinish

(

SerWriter *

w

)

Completes the document.

Separate from destroy because this is the backend's last chance to fail: destroy returns void and cannot report an error, and closing out a document can. A writer destroyed without being finished has produced an incomplete document.

Parameters

w	Writer to finish

Returns

true if the document is complete