Update docs

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,20 +362,41 @@ 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)
 
     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

doc/index.rst

@@ -22,6 +22,10 @@ The ckdl project also features simple "demo" bindings for the following language
 * :doc:`Python 3 <ckdl-py>`
 * :doc:`C++ 20 <kdlpp>`
 
+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.
 

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

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

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)