aboutsummaryrefslogtreecommitdiffstats
path: root/include/serd
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2021-07-22 15:26:22 -0400
committerDavid Robillard <d@drobilla.net>2022-01-14 19:37:51 -0500
commitca3a7049506cd1ba91326a36fc02a7319657728c (patch)
tree7289c877d9dc6286ab1826fab45e8a1612e8bc20 /include/serd
parent21f17ad27b3e805003e50b0f5fcbe606bfef0f3b (diff)
downloadserd-ca3a7049506cd1ba91326a36fc02a7319657728c.tar.gz
serd-ca3a7049506cd1ba91326a36fc02a7319657728c.tar.bz2
serd-ca3a7049506cd1ba91326a36fc02a7319657728c.zip
Preserve long or short quoting from input documents
Diffstat (limited to 'include/serd')
-rw-r--r--include/serd/serd.h95
1 files changed, 45 insertions, 50 deletions
diff --git a/include/serd/serd.h b/include/serd/serd.h
index 9ffb16fe..ded613a9 100644
--- a/include/serd/serd.h
+++ b/include/serd/serd.h
@@ -87,12 +87,11 @@ extern "C" {
@{
*/
-/// Flags indicating certain string properties relevant to serialisation
+/// Flags that describe the details of a node
typedef enum {
- SERD_HAS_NEWLINE = 1u << 0u, ///< Contains line breaks ('\\n' or '\\r')
- SERD_HAS_QUOTE = 1u << 1u, ///< Contains quotes ('"')
- SERD_HAS_DATATYPE = 1u << 2u, ///< Literal node has datatype
- SERD_HAS_LANGUAGE = 1u << 3u ///< Literal node has language
+ SERD_IS_LONG = 1u << 0u, ///< Literal node should be triple-quoted
+ SERD_HAS_DATATYPE = 1u << 1u, ///< Literal node has datatype
+ SERD_HAS_LANGUAGE = 1u << 2u ///< Literal node has language
} SerdNodeFlag;
/// Bitwise OR of SerdNodeFlag values
@@ -255,17 +254,6 @@ serd_strerror(SerdStatus status);
*/
/**
- Measure a UTF-8 string.
-
- @return Length of `str` in bytes.
- @param str A null-terminated UTF-8 string.
- @param flags (Output) Set to the applicable flags.
-*/
-SERD_API
-size_t
-serd_strlen(const char* SERD_NONNULL str, SerdNodeFlags* SERD_NULLABLE flags);
-
-/**
Return `path` as a canonical absolute path.
This expands all symbolic links, relative references, and removes extra
@@ -614,10 +602,9 @@ typedef enum {
/**
Create a new "simple" node that is just a string.
- This can be used to create blank, CURIE, or URI nodes from an already
- measured string or slice of a buffer, which avoids a strlen compared to the
- friendly constructors. This may not be used for literals since those must
- be measured to set the SERD_HAS_NEWLINE and SERD_HAS_QUOTE flags.
+ A "simple" node has no associated language or datatype. This can be used to
+ efficiently create nodes from an already measured string or slice of a
+ buffer, which avoids a strlen compared to the friendly constructors.
*/
SERD_API
SerdNode* SERD_ALLOCATED
@@ -629,25 +616,31 @@ SerdNode* SERD_ALLOCATED
serd_new_string(SerdStringView string);
/**
- Create a new plain literal node from `str` with `lang`.
+ Create a new literal node with optional datatype or language.
- A plain literal has no datatype, but may have a language tag. The `lang`
- may be empty, in which case this is equivalent to `serd_new_string()`.
-*/
-SERD_API
-SerdNode* SERD_ALLOCATED
-serd_new_plain_literal(SerdStringView str, SerdStringView lang);
+ This can create more complex literals than serd_new_string() with an
+ associated datatype URI or language tag, as well as control whether a
+ literal should be written as a short or long (triple-quoted) string.
-/**
- Create a new typed literal node from `str`.
+ @param string The string value of the literal.
- A typed literal has no language tag, but may have a datatype. The
- `datatype` may be NULL, in which case this is equivalent to
- `serd_new_string()`.
+ @param flags Flags to describe the literal and its metadata. This must be a
+ valid combination of flags, in particular, at most one of #SERD_HAS_DATATYPE
+ and #SERD_HAS_LANGUAGE may be set.
+
+ @param meta The string value of the literal's metadata. If
+ #SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI. If
+ #SERD_HAS_LANGUAGE is set, then this must be a language tag like "en-ca".
+ Otherwise, it is ignored.
+
+ @return A newly allocated literal node that must be freed with
+ serd_node_free(), or null if the arguments are invalid or allocation failed.
*/
SERD_API
SerdNode* SERD_ALLOCATED
-serd_new_typed_literal(SerdStringView str, SerdStringView datatype_uri);
+serd_new_literal(SerdStringView string,
+ SerdNodeFlags flags,
+ SerdStringView meta);
/// Create a new blank node
SERD_API
@@ -989,31 +982,33 @@ const SerdNode* SERD_ALLOCATED
serd_nodes_string(SerdNodes* SERD_NONNULL nodes, SerdStringView string);
/**
- Return a plain literal node with an optional language.
+ Make a literal node with optional datatype or language.
- If the language is empty, then this is equivalent to serd_nodes_string().
+ This can create complex literals with an associated datatype URI or language
+ tag, and control whether a literal should be written as a short or long
+ (triple-quoted) string.
- A new node will be added if an equivalent node is not already in the set.
-*/
-SERD_API
-const SerdNode* SERD_ALLOCATED
-serd_nodes_plain_literal(SerdNodes* SERD_NONNULL nodes,
- SerdStringView string,
- SerdStringView language);
+ @param nodes The node set to get this literal from.
-/**
- Return a typed literal node with an datatype URI.
+ @param string The string value of the literal.
- If the datatype URI is empty, then this is equivalent to
- serd_nodes_string().
+ @param flags Flags to describe the literal and its metadata. Note that at
+ most one of #SERD_HAS_DATATYPE and #SERD_HAS_LANGUAGE may be set.
- A new node will be added if an equivalent node is not already in the set.
+ @param meta The string value of the literal's metadata. If
+ #SERD_HAS_DATATYPE is set, then this must be an absolute datatype URI. If
+ #SERD_HAS_LANGUAGE is set, then this must be an RFC 5646 language tag like
+ "en-ca". Otherwise, it is ignored.
+
+ @return A newly allocated literal node that must be freed with
+ serd_node_free(), or null if the arguments are invalid or allocation failed.
*/
SERD_API
const SerdNode* SERD_ALLOCATED
-serd_nodes_typed_literal(SerdNodes* SERD_NONNULL nodes,
- SerdStringView string,
- SerdStringView datatype_uri);
+serd_nodes_literal(SerdNodes* SERD_NONNULL nodes,
+ SerdStringView string,
+ SerdNodeFlags flags,
+ SerdStringView meta);
/**
Make a URI node.