yoctonw.h File Reference

Functions for writing a Yocton file. More...

#include <inttypes.h>

Typedefs
typedef int(*	yoctonw_write) (void *buf, size_t nbytes, void *handle)
	Callback invoked to write more data to the output. More...
typedef struct yoctonw_writer	yoctonw_writer
	Writer object for generating Yocton-formatted output.

Functions
struct yoctonw_writer *	yoctonw_write_with (yoctonw_write callback, void *handle)
	Start writing a new stream of yocton-encoded data, using the given callback to write more data. More...
struct yoctonw_writer *	yoctonw_write_to (FILE *fstream)
	Start writing a new stream of yocton-encoded data, using the given FILE handle. More...
void	yoctonw_free (struct yoctonw_writer *w)
	Free the writer and stop writing the output stream. More...
void	yoctonw_prop (struct yoctonw_writer *w, const char *name, const char *value)
	Write a new property and value to the output. More...
void	yoctonw_printf (struct yoctonw_writer *w, const char *name, const char *fmt,...)
	Write a new property with the value constructed printf-style. More...
void	yoctonw_subobject (struct yoctonw_writer *w, const char *name)
	Start writing a new subobject. More...
void	yoctonw_end (struct yoctonw_writer *w)
	End the current subobject. More...
int	yoctonw_have_error (struct yoctonw_writer *w)
	Check if an error occurred. More...
void	yoctonw_flush (struct yoctonw_writer *w)
	Flush output buffer and write all pending data. More...

Detailed Description

Functions for writing a Yocton file.

The entrypoint is to use yoctonw_write_with or yoctonw_write_to.

Typedef Documentation

yoctonw_write

typedef int(* yoctonw_write) (void *buf, size_t nbytes, void *handle)

Callback invoked to write more data to the output.

Parameters

buf	Buffer containing data to write.
nbytes	Size of buffer in bytes.
handle	Arbitrary pointer, passed through from yoctonw_write_with.

Returns

1 for success; 0 for failure. If a failure status is returned, the callback will not be invoked again.

Function Documentation

yoctonw_end()

void yoctonw_end

(

struct yoctonw_writer *

w

)

End the current subobject.

See yoctonw_subobject for an example.

Parameters

w

Writer.

yoctonw_flush()

void yoctonw_flush

(

struct yoctonw_writer *

w

)

Flush output buffer and write all pending data.

Note that data is automatically flushed whenever a new top-level property is written, so the main use of this is to force any pending data to be written while writing a subobject.

Parameters

w

Writer.

yoctonw_free()

void yoctonw_free

(

struct yoctonw_writer *

w

)

Free the writer and stop writing the output stream.

Parameters

w	The yoctonw_writer.

yoctonw_have_error()

int yoctonw_have_error

(

struct yoctonw_writer *

w

)

Check if an error occurred.

Returns

Non-zero if an error occurred during output (ie. the output callback function returned zero).

yoctonw_printf()

void yoctonw_printf	(	struct yoctonw_writer *	w,
		const char *	name,
		const char *	fmt,
			...
	)

Write a new property with the value constructed printf-style.

For example, the following code:

yoctonw_printf(w, "string", "Here is a string: %s", "my string");
yoctonw_printf(w, "int", "%d", 1234);
yoctonw_printf(w, "float", "Here is a float: %.02f", 1234.5678);

will produce the following output:

string: "Here is a string: my string"
int: 1234
float: "Here is a float: 1234.57"

Parameters

w	Writer.
name	Property name.
fmt	Format string

yoctonw_prop()

void yoctonw_prop	(	struct yoctonw_writer *	w,
		const char *	name,
		const char *	value
	)

Write a new property and value to the output.

For example, the following code:

yoctonw_prop(w, "foo", "bar");
yoctonw_prop(w, "baz", "qux quux");

will produce the following output:

foo: bar
baz: "qux quux"

Parameters

w	Writer.
name	Property name.
value	Property value.

yoctonw_subobject()

void yoctonw_subobject	(	struct yoctonw_writer *	w,
		const char *	name
	)

Start writing a new subobject.

The yoctonw_end function should be called to end the subobject.

Example:

yoctonw_subobject(w, "subobj");
yoctonw_prop(w, "value", "my value");
yoctonw_end(w);

will produce the following output:

subobj {
    value: "my value"
}

Parameters

w	Writer.
name	Property name for subobject.

yoctonw_write_to()

struct yoctonw_writer * yoctonw_write_to

(

FILE *

fstream

)

Start writing a new stream of yocton-encoded data, using the given FILE handle.

Example:

FILE *fs = fopen("output.txt", "w");
assert(fs != NULL);
struct yocton_writer *w = yoctonw_write_to(fs);

Parameters

fstream

File handle.

Returns

A yoctonw_writer that can be used to output data.

yoctonw_write_with()

struct yoctonw_writer * yoctonw_write_with	(	yoctonw_write	callback,
		void *	handle
	)

Start writing a new stream of yocton-encoded data, using the given callback to write more data.

Example:

static int write_callback(void *buf, size_t nbytes, void *handle) {
    printf("Write callback to write %d bytes\n", nbytes);
    return 1;
}
 
w = yoctonw_write_with(write_callback, NULL);

Parameters

callback	Callback function to invoke to write data.
handle	Arbitrary pointer passed through when callback is invoked.

Returns

A yoctonw_writer that can be used to output data.