diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/sratom/sratom.h | 276 |
1 files changed, 175 insertions, 101 deletions
diff --git a/include/sratom/sratom.h b/include/sratom/sratom.h index 077adff..68bff33 100644 --- a/include/sratom/sratom.h +++ b/include/sratom/sratom.h @@ -21,11 +21,10 @@ #include "lv2/atom/atom.h" #include "lv2/atom/forge.h" +#include "lv2/atom/util.h" #include "lv2/urid/urid.h" #include "serd/serd.h" -#include "sord/sord.h" -#include <stdbool.h> #include <stdint.h> #if defined(_WIN32) && !defined(SRATOM_STATIC) && defined(SRATOM_INTERNAL) @@ -44,165 +43,240 @@ extern "C" { /** @defgroup sratom Sratom C API - This is the public C API of Sratom. + This is the complete public C API of sratom. @{ */ -/// Atom serializer -typedef struct SratomImpl Sratom; +/// Free memory allocated in the sratom library +SRATOM_API +void +sratom_free(void* ptr); /** - Mode for reading resources to LV2 Objects. - - This affects how resources (which are either blank nodes or have URIs) are - read by sratom_read(), since they may be read as simple references (a URI or - blank node ID) or a complete description (an atom "Object"). - - Currently, blank nodes are always read as Objects, but support for reading - blank node IDs may be added in the future. + @defgroup sratom_dumping Dumping Atoms + Writing atoms to a statement stream or a string. + @{ */ + +/// Flags to control how atoms are written as statements typedef enum { - /// Read blank nodes as Objects, and named resources as URIs - SRATOM_OBJECT_MODE_BLANK, + /** + 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. + */ + SRATOM_NAMED_SUBJECT = 1u << 1u, /** - Read blank nodes and the main subject as Objects. + Write pretty numeric literals in Turtle or TriG. - Any other named resources are read as URIs. The "main subject" is the - subject parameter passed to sratom_read(); if this is a resource it will - be read as an Object, but all other named resources encountered will be - read as URIs. + If set, numbers may be written as pretty literals instead of string + literals with explicit data types. Note that enabling this means that + types will not survive a round trip. */ - SRATOM_OBJECT_MODE_BLANK_SUBJECT -} SratomObjectMode; + SRATOM_PRETTY_NUMBERS = 1u << 2u, -/// Create a new Atom serializer -SRATOM_API -Sratom* -sratom_new(LV2_URID_Map* map); + /** + Write terse output without newlines. -/// Free an Atom serializer -SRATOM_API -void -sratom_free(Sratom* sratom); + If set, top level atoms will be written as a single long line. + */ + SRATOM_TERSE = 1u << 3u, +} SratomDumperFlag; -/** - Set the environment for reading or writing Turtle. +/// Bitwise OR of SratomDumperFlag values +typedef uint32_t SratomDumperFlags; - This can be used to set namespace prefixes and a base URI for - sratom_to_turtle() and sratom_from_turtle(). -*/ -SRATOM_API -void -sratom_set_env(Sratom* sratom, SerdEnv* env); +/// Dumper that writes atoms to a statement sink +typedef struct SratomDumperImpl SratomDumper; /** - Set the sink(s) where sratom will write its output. + Create a new atom dumper. + + @param world Serd world. + @param map URID mapper, only used during construction. + @param unmap URID unmapper, used while dumping to write URI strings. - This must be called before calling sratom_write(). + @return A newly allocated object which must be freed with + sratom_dumper_free(). */ SRATOM_API +SratomDumper* +sratom_dumper_new(SerdWorld* world, LV2_URID_Map* map, LV2_URID_Unmap* unmap); + +/// Free an atom dumper created with sratom_dumper_new() +SRATOM_API void -sratom_set_sink(Sratom* sratom, - const char* base_uri, - SerdStatementSink sink, - SerdEndSink end_sink, - void* handle); +sratom_dumper_free(SratomDumper* dumper); /** - Write pretty numeric literals. - - If `pretty_numbers` is true, numbers will be written as pretty Turtle - literals, rather than string literals with precise types. The cost of this - is that the types might get fudged on a round-trip to RDF and back. + 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 allow + writing atoms from data in memory that does not have an atom header. For + true atom pointers, the simpler sratom_dump_atom() can be used instead. + + Since all statements must be triples, a subject and predicate can be + provided to serialise literals like `subject predicate "literal"`. If + `subject` and `predicate` are null, resources will be written as the + subject, but literals will be written as the only element of an anonymous + list. A subject and predicate should always be given for lossless + round-tripping. This corresponds to using atoms as property values. + + @param dumper Dumper instance + @param env Environment defining the base URI and any prefixes + @param sink Sink which receives the serialised statements + @param subject Subject of first statement, or NULL + @param predicate Predicate of first statement, or NULL + @param type Type of the atom + @param size Size of the atom body in bytes + @param body Atom body + @param flags Option flags + @return Zero on success */ SRATOM_API -void -sratom_set_pretty_numbers(Sratom* sratom, bool pretty_numbers); +int +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); -/// Configure how resources will be read to form LV2 Objects +/** + Write an atom to a statement sink + + Convenience wrapper that takes a pointer to a complete atom, see the + sratom_dump() documentation for details. + + @param dumper Dumper instance + @param env Environment defining the base URI and any prefixes + @param sink Sink which receives the serialised statements + @param subject Subject of first statement, or NULL + @param predicate Predicate of first statement, or NULL + @param atom Atom to serialise + @param flags Option flags + @return Zero on success +*/ SRATOM_API -void -sratom_set_object_mode(Sratom* sratom, SratomObjectMode object_mode); +int +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 RDF. + Write an atom as a string. - The serialized atom is written to the sink set by sratom_set_sink(). + The returned string can be forged back into an atom using + sratom_from_string(). - @return 0 on success, or a non-zero error code otherwise. + @param dumper Dumper instance + @param env Environment for namespaces and relative URIs + @param atom Atom to serialise + @param flags Option flags + @return A string that must be freed using sratom_free(), or NULL on error. */ SRATOM_API -int -sratom_write(Sratom* sratom, - LV2_URID_Unmap* unmap, - uint32_t flags, - const SerdNode* subject, - const SerdNode* predicate, - uint32_t type_urid, - uint32_t size, - const void* body); +char* +sratom_to_string(SratomDumper* dumper, + const SerdEnv* env, + const LV2_Atom* atom, + SratomDumperFlags flags); /** - Read an Atom from RDF. + @} + @defgroup sratom_loading Loading Atoms + @{ +*/ + +/// Atom loader that reads atoms from a document +typedef struct SratomLoaderImpl SratomLoader; + +/** + Create a new loader for forging atoms from a document. - The resulting atom will be written to `forge`. + @param world RDF world + @param map URID mapper + @return A new object that must be freed with sratom_loader_free() */ SRATOM_API +SratomLoader* +sratom_loader_new(SerdWorld* world, LV2_URID_Map* map); + +/// Free an atom loader created with sratom_loader_new() +SRATOM_API void -sratom_read(Sratom* sratom, - LV2_Atom_Forge* forge, - SordWorld* world, - SordModel* model, - const SordNode* node); +sratom_loader_free(SratomLoader* loader); /** - Serialize an Atom to a Turtle string. + Load an atom from a model by forging the binary representation. - The returned string must be free()'d by the caller. + This reads `node` in `model` as an atom, constructing the result with + `forge`. + + @param loader Loader set up with the appropriate world and URID map. + + @param base_uri Base URI for making relative URI references. This is + typically used with file URIs to construct atoms with relative paths. Any + URI within the given base URI will be written to `forge` as a relative URI + reference. For example, with base URI <file:///my/data/>, the URI + <file:///my/data/dir/file.txt> will be written to the forge as the path + "dir/file.txt". + + @param forge Atom forge where the result is written. + + @param model Model that contains a description of the atom. + + @param node Node for the atom. This can be a simple literal node for + primitive atoms, or the subject resource for more complex structures like + objects and vectors. + + @return Zero on success. */ SRATOM_API -char* -sratom_to_turtle(Sratom* sratom, - LV2_URID_Unmap* unmap, - const char* base_uri, - const SerdNode* subject, - const SerdNode* predicate, - uint32_t type, - uint32_t size, - const void* body); +int +sratom_load(SratomLoader* loader, + const SerdNode* base_uri, + LV2_Atom_Forge* forge, + const SerdModel* model, + const SerdNode* node); /** - Read an Atom from a Turtle string. + Load an Atom from a Turtle string. The returned atom must be free()'d by the caller. */ SRATOM_API LV2_Atom* -sratom_from_turtle(Sratom* sratom, - const char* base_uri, - const SerdNode* subject, - const SerdNode* predicate, - const char* str); +sratom_from_string(SratomLoader* loader, SerdEnv* env, const char* str); /** - A convenient resizing sink for LV2_Atom_Forge. + Load an Atom from a model. - The handle must point to an initialized SerdChunk. + The returned atom must be free()'d by the caller. */ SRATOM_API -LV2_Atom_Forge_Ref -sratom_forge_sink(LV2_Atom_Forge_Sink_Handle handle, - const void* buf, - uint32_t size); - -/// The corresponding deref function for sratom_forge_sink -SRATOM_API LV2_Atom* -sratom_forge_deref(LV2_Atom_Forge_Sink_Handle handle, LV2_Atom_Forge_Ref ref); +sratom_from_model(SratomLoader* loader, + const SerdNode* base_uri, + const SerdModel* model, + const SerdNode* subject); /** @} + @} */ #ifdef __cplusplus |