Dumping Atoms

Writing atoms to a statement stream or a string.

enum SratomDumperFlag

Flags to control how atoms are written as statements.

enumerator SRATOM_NAMED_SUBJECT

Write the main subject with a label. If set, the main subject will be written using its blank node label, instead of as an anonymous node.

enumerator SRATOM_PRETTY_NUMBERS

Write pretty numeric literals in Turtle or TriG. If set, numbers may be written as “pretty” xsd:integer or xsd:decimal literals (without quoting or an explicit datatype) instead of string literals with explicit data types. It is best to leave this off in contexts where human readability doesn’t matter very much, since the explicit form is more consistent and likely to survive storage, transmission, and transformation with perfect fidelity.

enumerator SRATOM_TERSE

Write terse output without newlines. If set when writing to a string, top-level atoms will be written as a single long line. From a machine perspective, the output is identical, but this can be convenient in contexts where taking up less space for the representation of atoms is desirable, such as developer logs or transmission over a network.

typedef uint32_t SratomDumperFlags

Bitwise OR of SratomDumperFlag values.

typedef struct SratomDumperImpl SratomDumper

Dumper that writes atoms to a statement sink.

SratomDumper *sratom_dumper_new(SerdWorld *world, LV2_URID_Map *map, LV2_URID_Unmap *unmap)

Create a new atom dumper.

Parameters

  • world – Serd world.

  • map – URID mapper, only used during construction.

  • unmap – URID unmapper, used while dumping to write URI strings.

Returns

A newly allocated object which must be freed with sratom_dumper_free().

void sratom_dumper_free(SratomDumper *dumper)

Free an atom dumper created with sratom_dumper_new()

SratomStatus sratom_dump(SratomDumper *dumper, const SerdEnv *env, const SerdSink *sink, const SerdNode *subject, const SerdNode *predicate, LV2_URID type, uint32_t size, const void *body, SratomDumperFlags flags)

Write an atom body to a statement sink.

This is the fundamental write function that writes an atom to a sink as a series of statements. It can be used with any sink, such as a Turtle writer, model inserter, or a custom sink provided by the application.

This function takes the type, size, and body separately to enable writing values that are not a contiguous LV2_Atom in memory. For writing existing atoms, the simpler sratom_dump_atom() can be used instead.

A subject and predicate can be provided so that writing simple atoms will produce a statement like subject predicate "literal". If either subject or predicate are null, objects will be written as the subject, and literals will be written as the only element of an anonymous list. For example:

my:object some:property 42 .
[ some:property 42 ] .
( "literal" ) .

Generally, this function is intended for writing the value of some property (for example, the current value of a plugin parameter in a preset), and the appropriate subject and predicate for the context should always be provided. This avoids any ambiguities and guarantees lossless round-tripping.

Parameters

  • dumper – Dumper instance.

  • env – Environment defining the base URI and any prefixes.

  • sink – Sink which receives the statements describing the atom.

  • subject – Subject of first statement, or NULL.

  • predicate – Predicate of first statement, or NULL.

  • type – Type of the atom.

  • size – Size of the atom body in bytes.

  • body – Atom body.

  • flags – Option flags.

Returns

Zero on success.

SratomStatus sratom_dump_atom(SratomDumper *dumper, const SerdEnv *env, const SerdSink *sink, const SerdNode *subject, const SerdNode *predicate, const LV2_Atom *atom, SratomDumperFlags flags)

Write an atom to a statement sink.

Convenience wrapper that takes a pointer to a complete atom, see the sratom_dump() documentation for details.

Parameters

  • dumper – Dumper instance.

  • env – Environment defining the base URI and any prefixes.

  • sink – Sink which receives the statements describing the atom.

  • subject – Subject of first statement, or NULL.

  • predicate – Predicate of first statement, or NULL.

  • atom – Atom to write.

  • flags – Option flags.

Returns

Zero on success.

char *sratom_to_string(SratomDumper *dumper, const SerdEnv *env, const LV2_Atom *atom, SratomDumperFlags flags)

Write an atom as a string.

The returned string can be forged back into an atom using sratom_from_string().

Parameters

  • dumper – Dumper instance.

  • env – Environment for namespaces and relative URIs.

  • atom – Atom to write.

  • flags – Option flags.

Returns

A string that must be freed using sratom_free(), or NULL on error.