/* Serd, an RDF serialisation library. * Copyright 2011 David Robillard * * Serd is free software: you can redistribute it and/or modify it under * the terms of the GNU Lesser General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * Serd is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public * License for details. * * You should have received a copy of the GNU Lesser General Public License * along with this program. If not, see . */ /* @file * Public Serd API. */ #ifndef SERD_SERD_H #define SERD_SERD_H #include #include #include #include #ifdef SERD_SHARED #if defined _WIN32 || defined __CYGWIN__ #define SERD_LIB_IMPORT __declspec(dllimport) #define SERD_LIB_EXPORT __declspec(dllexport) #else #define SERD_LIB_IMPORT __attribute__ ((visibility("default"))) #define SERD_LIB_EXPORT __attribute__ ((visibility("default"))) #endif #ifdef SERD_INTERNAL #define SERD_API SERD_LIB_EXPORT #else #define SERD_API SERD_LIB_IMPORT #endif #else #define SERD_API #endif #ifdef __cplusplus extern "C" { #endif /** @defgroup serd Serd * @brief A lightweight RDF Serialisation Library. * @{ */ typedef struct SerdNamespacesImpl* SerdNamespaces; ///< Set of namespaces typedef struct SerdReaderImpl* SerdReader; ///< RDF reader typedef struct SerdWriterImpl* SerdWriter; ///< RDF writer /** RDF syntax */ typedef enum { SERD_TURTLE = 1, SERD_NTRIPLES = 2 } SerdSyntax; /** Type of RDF node. */ typedef enum { BLANK = 1, ///< Blank node (resource with no URI) URI = 2, ///< URI (universal identifier) QNAME = 3, ///< CURIE/QName (URI shortened with a namespace) LITERAL = 4 ///< Literal string (with optional lang or datatype) } SerdNodeType; /** @name URI * Support for parsing and resolving URIs. * @{ */ /** A chunk of memory (non-terminated string). */ typedef struct { const uint8_t* buf; ///< Start of chunk size_t len; ///< Length of chunk in bytes } SerdChunk; /** A parsed URI. * This struct directly refers to chunks in other strings, it does not own * any memory itself. Thus, URIs can be parsed and/or resolved against a * base URI in-place without allocating memory. */ typedef struct { SerdChunk scheme; ///< Scheme SerdChunk authority; ///< Authority SerdChunk path_base; ///< Path prefix if relative SerdChunk path; ///< Path suffix SerdChunk query; ///< Query SerdChunk fragment; ///< Fragment } SerdURI; static const SerdURI SERD_URI_NULL = {{0,0},{0,0},{0,0},{0,0},{0,0},{0,0}}; /** Return true iff @a utf8 starts with a valid URI scheme. */ SERD_API bool serd_uri_string_has_scheme(const uint8_t* utf8); /** Parse @a utf8, writing result to @a out. */ SERD_API bool serd_uri_parse(const uint8_t* utf8, SerdURI* out); /** Resolve @a uri relative to @a base, writing result to @a out. */ SERD_API bool serd_uri_resolve(const SerdURI* uri, const SerdURI* base, SerdURI* out); /** Write @a uri to @a file. */ SERD_API bool serd_uri_write(const SerdURI* uri, FILE* file); /** Sink function for raw string output. */ typedef size_t (*SerdSink)(const void* buf, size_t len, void* stream); /** Serialise @a uri with a series of calls to @a sink. */ SERD_API size_t serd_uri_serialise(const SerdURI* uri, SerdSink sink, void* stream); /** @} */ /** @name String * @brief A measured UTF-8 string. * @{ */ /** Measured UTF-8 string. */ typedef struct { size_t n_bytes; ///< Size in bytes including trailing null byte size_t n_chars; ///< Length in characters uint8_t buf[]; ///< Buffer } SerdString; /** Create a new UTF-8 string from @a utf8. */ SERD_API SerdString* serd_string_new(const uint8_t* utf8); /** Copy @a string. */ SERD_API SerdString* serd_string_copy(const SerdString* str); /** Free @a str. */ SERD_API void serd_string_free(SerdString* str); /** Serialise @a uri to a string. */ SERD_API SerdString* serd_string_new_from_uri(const SerdURI* uri, SerdURI* out); /** @} */ /** @name Namespaces * @brief A dictionary of namespaces (names associated with URI strings) * @{ */ /** Create a new namespaces dictionary. */ SERD_API SerdNamespaces serd_namespaces_new(); /** Free @a ns. */ SERD_API void serd_namespaces_free(SerdNamespaces ns); /** Add namespace @a uri to @a ns using prefix @a name. */ SERD_API void serd_namespaces_add(SerdNamespaces ns, const SerdString* name, const SerdString* uri); /** Expand @a qname. */ SERD_API bool serd_namespaces_expand(const SerdNamespaces ns, const SerdString* qname, SerdChunk* uri_prefix, SerdChunk* uri_suffix); /** @} */ /** @name Reader * @brief Reader for RDF syntax. * @{ */ /** Sink for base URI changes. */ typedef bool (*SerdBaseSink)(void* handle, const SerdString* uri); /** Sink for namespace definitions. */ typedef bool (*SerdPrefixSink)(void* handle, const SerdString* name, const SerdString* uri); /** Sink for statements. */ typedef bool (*SerdStatementSink)(void* handle, const SerdString* graph, const SerdString* subject, SerdNodeType subject_type, const SerdString* predicate, SerdNodeType predicate_type, const SerdString* object, SerdNodeType object_type, const SerdString* object_lang, const SerdString* object_datatype); /** Create a new RDF reader. */ SERD_API SerdReader serd_reader_new(SerdSyntax syntax, void* handle, SerdBaseSink base_sink, SerdPrefixSink prefix_sink, SerdStatementSink statement_sink); /** Read @a file. */ SERD_API bool serd_reader_read_file(SerdReader reader, FILE* file, const uint8_t* name); /** Free @a reader. */ SERD_API void serd_reader_free(SerdReader reader); /** @} */ /** @name Writer * @brief Writer of RDF syntax. * @{ */ typedef enum { SERD_STYLE_ABBREVIATED = 1, SERD_STYLE_ASCII = 1 << 1, SERD_STYLE_ESCAPE_ } SerdStyle; /** Create a new RDF writer. */ SERD_API SerdWriter serd_writer_new(SerdSyntax syntax, SerdStyle style, SerdNamespaces ns, const SerdURI* base_uri, SerdSink sink, void* stream); /** Free @a writer. */ SERD_API void serd_writer_free(SerdWriter writer); /** Set the current output base URI. */ SERD_API void serd_writer_set_base_uri(SerdWriter writer, const SerdURI* uri); /** Set the current output base URI. */ SERD_API void serd_writer_set_prefix(SerdWriter writer, const SerdString* name, const SerdString* uri); /** Write a statement. */ SERD_API bool serd_writer_write_statement(SerdWriter writer, const SerdString* graph, const SerdString* subject, SerdNodeType subject_type, const SerdString* predicate, SerdNodeType predicate_type, const SerdString* object, SerdNodeType object_type, const SerdString* object_datatype, const SerdString* object_lang); /** Finish a write. */ SERD_API void serd_writer_finish(SerdWriter writer); /** @} */ /** @} */ #ifdef __cplusplus } /* extern "C" */ #endif #endif /* SERD_SERD_H */