re #476 clarify that Byte Order Marks are not accepted

.github/workflows/infra.yml

@@ -42,3 +42,53 @@ jobs:
           echo "ERROR: generated workflows are out of date"
         fi
         exit $status
+  check_doc:
+    if: always()
+    continue-on-error: false
+    runs-on: ubuntu-24.04
+    env:
+      DOXY_VERSION: 1.13.2
+      DOXY_DIR: /tmp/doxydir/bin
+    steps:
+    - name: checkout (action)
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+        fetch-depth: 0
+    - name: install python
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.9
+    - name: install requirements
+      run: pip install -r doc/requirements.txt
+    - name: install wget
+      run: |
+        apt-get update
+        apt install -y wget
+    - name: install doxygen
+      run: |
+        ver=$DOXY_VERSION
+        uver=$(echo $ver | sed "s:\.:_:g")
+        name=$(dirname $DOXY_DIR)
+        dst=$(dirname $name)
+        url="https://github.com/doxygen/doxygen/releases/download/Release_$uver/doxygen-$ver.linux.bin.tar.gz"
+        ( \
+          cd $dst ; \
+          wget $url ; \
+          tar xvfz $(basename $url) ; \
+          ls -lFhp | grep dox ; \
+          mv -v doxygen-$ver $name ; \
+        )
+    - name: doxygen version
+      run: |
+        export PATH=$DOXY_DIR:$PATH
+        which doxygen
+        doxygen --version
+    - name: check doxygen docs
+      run: |
+        export PATH=$DOXY_DIR:$PATH
+        make -C doc doxy
+    - name: check sphinx
+      run: |
+        export PATH=$DOXY_DIR:$PATH
+        make -C doc doc

.github/workflows/infra.ys

@@ -30,3 +30,48 @@ jobs:
             echo "ERROR: generated workflows are out of date"
           fi
           exit $status
+
+  check_doc:
+    :: setup-job('infra' 'check_doxygen')
+    runs-on: ubuntu-24.04
+    env:
+      DOXY_VERSION: 1.13.2
+      DOXY_DIR: /tmp/doxydir/bin
+    steps:
+      - :: checkout-action
+      - name: install python
+        uses: actions/setup-python@v5
+        with: {python-version: 3.9}
+      - name: install requirements
+        run: pip install -r doc/requirements.txt
+      - name: install wget
+        run: |
+          apt-get update
+          apt install -y wget
+      - name: install doxygen
+        run: |
+          ver=$DOXY_VERSION
+          uver=$(echo $ver | sed "s:\.:_:g")
+          name=$(dirname $DOXY_DIR)
+          dst=$(dirname $name)
+          url="https://github.com/doxygen/doxygen/releases/download/Release_$uver/doxygen-$ver.linux.bin.tar.gz"
+          ( \
+            cd $dst ; \
+            wget $url ; \
+            tar xvfz $(basename $url) ; \
+            ls -lFhp | grep dox ; \
+            mv -v doxygen-$ver $name ; \
+          )
+      - name: doxygen version
+        run: |
+          export PATH=$DOXY_DIR:$PATH
+          which doxygen
+          doxygen --version
+      - name: check doxygen docs
+        run: |
+          export PATH=$DOXY_DIR:$PATH
+          make -C doc doxy
+      - name: check sphinx
+        run: |
+          export PATH=$DOXY_DIR:$PATH
+          make -C doc doc

README.md

@@ -247,6 +247,7 @@ build and run this executable using any of the build samples, eg the
 
 ```cpp
 // Parse YAML code in place, potentially mutating the buffer:
+// (Byte Order Marks are not accepted)
 char yml_buf[] = "{foo: 1, bar: [2, 3], john: doe}";
 ryml::Tree tree = ryml::parse_in_place(yml_buf);
 

doc/Doxyfile

@@ -907,7 +907,7 @@ WARN_IF_UNDOC_ENUM_VAL = YES
 # Possible values are: NO, YES, FAIL_ON_WARNINGS and FAIL_ON_WARNINGS_PRINT.
 # The default value is: NO.
 
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = FAIL_ON_WARNINGS
 
 # The WARN_FORMAT tag determines the format of the warning messages that doxygen
 # can produce. The string should contain the $file, $line, and $text tags, which
@@ -959,6 +959,7 @@ INPUT                  = \
                          ../ext/c4core/src/c4/charconv.hpp \
                          ../ext/c4core/src/c4/format.hpp \
                          ../ext/c4core/src/c4/base64.hpp \
+                         ../ext/c4core/src/c4/utf.hpp \
                          ../ext/c4core/src/c4/std/string.hpp \
                          ../ext/c4core/src/c4/std/string_view.hpp \
                          ../ext/c4core/src/c4/std/vector.hpp \

doc/index.rst

@@ -72,11 +72,12 @@ API teaser
 Here's a short teaser from the API quickstart overview (`see on
 doxygen <doxygen/group__doc__quickstart.html>`_ / `see full code on
 github
-<https://github.com/biojppm/rapidyaml/blob/v0.5.0/samples/quickstart.cpp>`_):
+<https://github.com/biojppm/rapidyaml/blob/v0.7.2/samples/quickstart.cpp>`_):
 
 .. code-block:: c++
 
     // Parse YAML code in place, potentially mutating the buffer:
+    // (Byte Order Marks are not accepted)
     char yml_buf[] = "{foo: 1, bar: [2, 3], john: doe}";
     ryml::Tree tree = ryml::parse_in_place(yml_buf);
 

samples/quickstart.cpp

@@ -16,6 +16,7 @@
     // For this sample, we will be using std interop, so...
     #include <ryml_std.hpp> // optional header, provided for std:: interop
     #include <c4/format.hpp> // needed for the examples below
+    #include <c4/utf.hpp> // needed for the examples below
 #endif
 
 // these are needed for the examples below
@@ -269,6 +270,7 @@ struct ScopedErrorHandlerExample : public ErrorHandlerExample
 void sample_lightning_overview()
 {
     // Parse YAML code in place, potentially mutating the buffer:
+    // (NOTE: Byte Order Marks are not accepted)
     char yml_buf[] = "{foo: 1, bar: [2, 3], john: doe}";
     ryml::Tree tree = ryml::parse_in_place(yml_buf);
 
@@ -317,6 +319,7 @@ void sample_lightning_overview()
 void sample_quick_overview()
 {
     // Parse YAML code in place, potentially mutating the buffer:
+    // (NOTE: Byte Order Marks are not accepted)
     char yml_buf[] = R"(
 foo: 1
 bar: [2, 3]
@@ -1731,8 +1734,8 @@ void sample_substr()
  *
  *  ryml offers no overload to directly parse files from disk; it only
  *  parses source buffers (which may be mutable or immutable). It is
- *  up to the caller to load the file contents into a buffer before
- *  parsing with ryml.
+ *  up to the caller to load the file contents **without Byte Order
+ *  Marks** into a buffer before parsing with ryml.
  *
  *  But that does not mean that loading a file is unimportant. There
  *  are many ways to achieve this in C++, but for convenience and to
@@ -1751,17 +1754,19 @@ void sample_parse_file()
 
     // now we can load it into a std::string (for example):
     {
-        std::string contents = file_get_contents<std::string>(filename);
-        ryml::Tree tree = ryml::parse_in_arena(ryml::to_csubstr(contents)); // immutable (csubstr) overload
+        std::string buffer = file_get_contents<std::string>(filename);
+        ryml::csubstr contents = ryml::skip_bom(ryml::to_csubstr(buffer)); // skip any Byte Order Marks
+        ryml::Tree tree = ryml::parse_in_arena(contents); // immutable (csubstr) overload
         CHECK(tree["foo"].val() == "1");
         CHECK(tree["bar"][0].val() == "2");
         CHECK(tree["bar"][1].val() == "3");
     }
 
     // or we can use a vector<char> instead:
     {
-        std::vector<char> contents = file_get_contents<std::vector<char>>(filename);
-        ryml::Tree tree = ryml::parse_in_place(ryml::to_substr(contents)); // mutable (csubstr) overload
+        std::vector<char> buffer = file_get_contents<std::vector<char>>(filename);
+        ryml::substr contents = ryml::skip_bom(ryml::to_substr(buffer)); // skip any Byte Order Marks
+        ryml::Tree tree = ryml::parse_in_place(contents); // mutable (csubstr) overload
         CHECK(tree["foo"].val() == "1");
         CHECK(tree["bar"][0].val() == "2");
         CHECK(tree["bar"][1].val() == "3");
@@ -5302,7 +5307,9 @@ void ErrorHandlerExample::check_effect(bool committed) const
 // helper functions for sample_parse_file()
 
 C4_SUPPRESS_WARNING_MSVC_WITH_PUSH(4996) // fopen: this function may be unsafe
-/** load a file from disk into an existing CharContainer */
+/** load a file from disk into an existing CharContainer. Note that
+ * rapidyaml does not accept Byte Order Marks; use @ref c4::skip_bom()
+ * if the file may contain a Byte Order Mark. */
 template<class CharContainer>
 size_t file_get_contents(const char *filename, CharContainer *v)
 {
@@ -5321,7 +5328,10 @@ size_t file_get_contents(const char *filename, CharContainer *v)
     return v->size();
 }
 
-/** load a file from disk and return a newly created CharContainer */
+/** load a file from disk and return a newly created
+ * CharContainer. Note that rapidyaml does not accept Byte Order
+ * Marks; use @ref c4::skip_bom() if the file may contain a Byte Order
+ * Mark. */
 template<class CharContainer>
 CharContainer file_get_contents(const char *filename)
 {