From 0b68bcb8eaea72b06b718cfe3e13e7f37143aa66 Mon Sep 17 00:00:00 2001 From: Thomas Jollans Date: Sun, 26 May 2024 15:48:29 +0200 Subject: [PATCH] Update docs --- doc/ckdl-api.rst | 50 ++++++++++++++++++++++++++++++++----- doc/index.rst | 16 +++++++++--- include/kdl/common-macros.h | 5 ++++ include/kdl/common.h | 2 ++ src/utils/ckdl-cat.c | 2 +- 5 files changed, 64 insertions(+), 11 deletions(-) diff --git a/doc/ckdl-api.rst b/doc/ckdl-api.rst index f95c708..4714ef0 100644 --- a/doc/ckdl-api.rst +++ b/doc/ckdl-api.rst @@ -131,18 +131,32 @@ by the KDL spec. For generating the escapes, there are a few options: "Sensible" default: escape tabs, newlines, and other control characters, but leave most non-ASCII Unicode intact. -.. c:function:: kdl_owned_string kdl_escape(kdl_str const* s, kdl_escape_mode mode) +String behaviour varies by KDL version: + +.. c:type:: enum kdl_version kdl_version + + .. c:enumerator:: KDL_VERSION_1 + + KDL 1.0.0 rules (e.g. ``\/`` is a valid escape sequence) + + .. c:enumerator:: KDL_VERSION_2 + + KDL 2.0.0 rules (e.g. ``\s`` escapes the space character) + +.. c:function:: kdl_owned_string kdl_escape_v(kdl_version version, kdl_str const* s, kdl_escape_mode mode) Escape special characters in a string. + :param version: The KDL version to use :param s: The original string :param mode: How to escape :return: A string that could be surrounded by ``""`` in a KDL file -.. c:function:: kdl_owned_string kdl_unescape(kdl_str const* s) +.. c:function:: kdl_owned_string kdl_unescape_v(kdl_version version, kdl_str const* s) Resolve backslash escape sequences + :param version: The KDL version to use :param s: A string that might have been surrounded by ``""`` in a KDL file :return: The string with all backslash escapes replaced @@ -280,7 +294,6 @@ The events produced by the ckdl parser are: been commented out using a slashdash (``/-``) are rendered as their original type ORed with :c:enumerator:`KDL_EVENT_COMMENT` (e.g., ``KDL_EVENT_COMMENT | KDL_EVENT_START_NODE``) - Each event is associated with certain event data: .. c:type:: struct kdl_event_data kdl_event_data @@ -349,12 +362,33 @@ If you wish, you may configure the parser to emit comments in addition to "regul .. c:enumerator:: KDL_DEFAULTS - By default, ignore all comments + By default, support KDL 1.0.0 only and ignore all comments .. c:enumerator:: KDL_EMIT_COMMENTS Produce events for comments and events deleted using ``/-`` + + .. c:enumerator:: KDL_READ_VERSION_1 + + Use KDL version 1.0.0 (this is the default) + + .. c:enumerator:: KDL_READ_VERSION_2 + + Use KDL version 2.0.0 (draft) + + .. c:enumerator:: KDL_DETECT_VERSION + + Allow both KDL v2 and KDL v1. This will be the default in future. + + This mode aims to produce entirely correct output for all KDLv2 documents as well as + for *almost* all KDLv1 documents. If you need complete KDLv1 compliance, use + ``KDL_READ_VERSION_1`` instead. + + If you're not reading from a stream (and can afford to parse the document twice), + consider running the parser in both ``KDL_READ_VERSION_2`` mode and ``KDL_READ_VERSION_1`` + mode for maximum standard compliance. + The parser object provides one method: .. c:function:: kdl_event_data* kdl_parser_next_event(kdl_parser* parser) @@ -362,7 +396,7 @@ The parser object provides one method: Get the next event in the document from a KDL parser :param parser: The parser - :return: A pointer to a parse event structure. This pointer is valid until the next call to + :return: A pointer to a parse event structure. This pointer is valid until the next call to :c:func:`kdl_parser_next_event` for this parser. The next call also invalidates all :c:type:`kdl_str` pointers which may be contained in the event data. @@ -433,10 +467,14 @@ text. How should identifiers (i.e., node names, type annotations and property keys) be rendered? (default: :c:enumerator:`KDL_PREFER_BARE_IDENTIFIERS`) - .. c:member::kdl_float_printing_options float_mode + .. c:member:: kdl_float_printing_options float_mode How exactly should doubles be formatted? + .. c:member:: kdl_version version + + KDL version to use. + .. c:type:: enum kdl_identifier_emission_mode kdl_identifier_emission_mode .. c:enumerator:: KDL_PREFER_BARE_IDENTIFIERS diff --git a/doc/index.rst b/doc/index.rst index 8a4c672..74bebe8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -22,6 +22,10 @@ The ckdl project also features simple "demo" bindings for the following language * :doc:`Python 3 ` * :doc:`C++ 20 ` +ckdl supports KDL version 1.0.0 and has preliminary support for KDL 2.0.0 (draft spec). +KDL 2 support has to be explicitly enabled. When the KDL 2 spec is finalized, future +versions of ckdl will default to parsing both KDL 2 and KDL 1 documents. + Building ckdl ------------- @@ -35,12 +39,17 @@ ckdl is written in portable modern C, and it should ideally run anywhere you hav modern C compiler with at least a minimal standard library. The only really platform-dependent code is in the test suite, which you don't have to build if you can't. -ckdl has been tested with: +ckdl is routinely tested on recent versions of: + +* Linux (x86_64, x86) with glibc +* Windows (x64), with Microsoft Visual C++ +* MacOS (arm64, x86_64) + +ckdl has in the past additionally been tested with: * Linux (x86_64, x86, arm64, arm32v7l), with glibc and musl libc - going back as far as CentOS 6 -* MacOS (arm64, x86_64) -* Windows 10 (x86_64, x86), using Microsoft Visual C++ and Mingw-w64 +* Windows wih Mingw-w64 * FreeBSD 12 on x86_64 * NetBSD 5 on x86_64 * Illumos (OmniOS) on x86_64 @@ -76,7 +85,6 @@ The CMake scripts support a few options, including: library * ``-DBUILD_KDLPP=OFF``: Disable building the C++20 bindings * ``-DBUILD_TESTS=OFF``: Disable building the test suite -* ``-DDOWNLOAD_TEST_DATA=OFF``: Don't download test data from GitHub during configure To run the test suite, run ``make test`` or ``ctest`` in the build directory. diff --git a/include/kdl/common-macros.h b/include/kdl/common-macros.h index c3c1c32..c404244 100644 --- a/include/kdl/common-macros.h +++ b/include/kdl/common-macros.h @@ -4,8 +4,13 @@ // define attributes for functions #if defined(__cplusplus) # define KDL_NODISCARD [[nodiscard]] +# define KDL_DEPRECATED(reason) [[deprecated(reason)]] #elif defined(__GNUC__) # define KDL_NODISCARD __attribute__((warn_unused_result)) +# define KDL_DEPRECATED(reason) __attribute__((deprecated)) +#elif defined(_MSC_VER) +# define KDL_NODISCARD +# define KDL_DEPRECATED(reason) __declspec(deprecated(reason)) #else # define KDL_NODISCARD #endif diff --git a/include/kdl/common.h b/include/kdl/common.h index 67f6813..4b104e5 100644 --- a/include/kdl/common.h +++ b/include/kdl/common.h @@ -68,8 +68,10 @@ KDL_NODISCARD KDL_EXPORT kdl_owned_string kdl_escape_v(kdl_version version, kdl_ KDL_NODISCARD KDL_EXPORT kdl_owned_string kdl_unescape_v(kdl_version version, kdl_str const* s); // Escape special characters in a string according to KDLv1 string rules (subject to change) +KDL_DEPRECATED("Use kdl_escape_v instead") KDL_NODISCARD KDL_EXPORT kdl_owned_string kdl_escape(kdl_str const* s, kdl_escape_mode mode); // Resolve backslash escape sequences according to KDLv1 rules (subject to change) +KDL_DEPRECATED("Use kdl_unescape_v instead") KDL_NODISCARD KDL_EXPORT kdl_owned_string kdl_unescape(kdl_str const* s); #ifdef __cplusplus diff --git a/src/utils/ckdl-cat.c b/src/utils/ckdl-cat.c index 79fbc2f..9c9284e 100644 --- a/src/utils/ckdl-cat.c +++ b/src/utils/ckdl-cat.c @@ -32,7 +32,7 @@ bool kdl_cat_file_to_file(FILE* in, FILE* out) bool kdl_cat_file_to_file_opt(FILE* in, FILE* out, kdl_emitter_options const* opt) { - kdl_cat_file_to_file_ex(in, out, KDL_DEFAULTS, opt); + return kdl_cat_file_to_file_ex(in, out, KDL_DEFAULTS, opt); } bool kdl_cat_file_to_file_ex(FILE* in, FILE* out, kdl_parse_option parse_opt, kdl_emitter_options const* emit_opt)