refactor error API: update docs

changelog/0.8.0.md

@@ -1,4 +1,4 @@
-## Breaking changes
+### Breaking changes
 
 - [BREAKING] Fix [#480](https://github.com/biojppm/rapidyaml/issues/480) ([PR#489](https://github.com/biojppm/rapidyaml/pull/489)):
   - Deserializing an empty quoted string *will not* cause an error.
@@ -9,7 +9,7 @@
 - [BREAKING] Fix [#477](https://github.com/biojppm/rapidyaml/issues/477) ([PR#479](https://github.com/biojppm/rapidyaml/pull/479)): changed `read<std::map>()` to overwrite existing entries. The provided implementations had an inconsistency between `std::map` (which wasn't overwriting) and `std::vector` (which *was* overwriting).
 
 
-## Fixes
+### Fixes
 
 - [PR#488](https://github.com/biojppm/rapidyaml/pull/488):
   - add workarounds for problems with codegen of gcc 11,12,13.
@@ -36,7 +36,7 @@
 - [PR#499](https://github.com/biojppm/rapidyaml/pull/499): fix warnings with `-Wundef`.
 
 
-## Thanks
+### Thanks
 
 - @ingydotnet
 - @perlpunk

changelog/current.md

@@ -33,3 +33,22 @@
                                 # there is no longer any risk of it being deallocated
   ```
   - improve behavior of `Tree` methods accepting scalars: all standard buffer types are now accepted (ie, `str`, `bytes`, `bytearray` and `memoryview`).
+- [PR#503](https://github.com/biojppm/rapidyaml/pull/503) (fixes [#399](https://github.com/biojppm/rapidyaml/issues/399)): change error callbacks.
+  - Errors in ryml now have one of these types:
+    - parse error: when parsing YAML/JSON. See: `pfn_error_parse`,  `ErrorDataParse`, `ExceptionParse`, `err_parse_format()`, `sample_error_parse`.
+    - visit error: when visiting a tree (reading or writing). See: `pfn_error_visit`,  `ErrorDataVisit`, `ExceptionVisit`, `err_visit_format()`, `sample_error_visit`.
+    - basic error: other, non specific errors. See: `pfn_error_basic`,  `ErrorDataBasic`, `ExceptionBasic`, `err_basic_format()`, `sample_error_basic`.
+    - parse and visit errors/exceptions can be treated/caught as basic errors/exceptions
+  - Add message formatting functions to simplify implementation of error callbacks:
+    - `err_parse_format()`: format/print a full error message for a parse error
+    - `err_visit_format()`: format/print a full error message for a visit error
+    - `err_basic_format()`: format/print a full error message for a basic error
+    - `location_format()`: format/print a location
+    - `location_format_with_context()`: useful to create a rich error message showing the YAML region causing the error, maybe even for a visit error if the source is kept and locations are enabled.
+  - See the new header `c4/yml/error.hpp` (and `c4/yml/error.def.hpp` for definitions of the functions in `c4/yml/error.hpp`)
+  - See the relevant sample functions in the quickstart sample: `sample_error_basic`, `sample_error_parse` and `sample_error_visit`.
+  - There are breaking user-facing changes in the `Callbacks` structure:
+    - Removed member `m_error `
+    - Added members `m_error_basic`, `m_error_parse`, `m_error_visit`
+    - Added methods `.set_error_basic()`, `.set_error_parse()` and `.set_error_visit()`.
+

doc/Doxyfile

@@ -954,6 +954,7 @@ INPUT                  = \
                          ../src \
                          ../src_extra \
                          ../samples/quickstart.cpp \
+                         ../samples/quickstart-ints.cpp \
                          ../ext/c4core/src/c4/substr.hpp \
                          ../ext/c4core/src/c4/charconv.hpp \
                          ../ext/c4core/src/c4/format.hpp \
@@ -1098,7 +1099,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = ../changelog
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -1222,7 +1223,7 @@ STRIP_CODE_COMMENTS    = NO
 # entity all documented functions referencing it will be listed.
 # The default value is: NO.
 
-REFERENCED_BY_RELATION = YES
+REFERENCED_BY_RELATION = NO
 
 # If the REFERENCES_RELATION tag is set to YES then for each documented function
 # all documented entities called/used by that function will be listed.

doc/Makefile

@@ -7,6 +7,9 @@ SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
+CLANG         ?= clang++
+DOXYGEN       ?= doxygen #/home/jpmag/proj/doxygen/install/linux-x86_64-gxx14.2-Release/bin/doxygen
+DOXYGEN_OPTS  ?= #-t
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -28,7 +31,11 @@ doxy:
 	@# ensure submodules are checked out
 	if [ ! -f $(shell pwd)/../ext/c4core/cmake/c4Project.cmake ] ; then echo "ERROR: submodules not present" ; exit 1 ; fi
 	if [ ! -f $(shell pwd)/../ext/c4core/src/c4/charconv.hpp ] ; then echo "ERROR: submodules not present" ; exit 1 ; fi
-	doxygen Doxyfile
+	## use cmake to generate a compile database
+	#cmake -S .. -B "$(BUILDDIR)/proj" -DCMAKE_CXX_COMPILER=$(CLANG) -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+	#ln -fs "$(BUILDDIR)/proj/compile_commands.json" .
+	## finally, run doxygen
+	$(DOXYGEN) $(DOXYGEN_OPTS) Doxyfile
 
 clean:
 	rm -rf doxygen/

doc/doxy_main.md

@@ -16,8 +16,7 @@
   * @ref doc_callbacks - how to set up error/allocation/deallocation
     callbacks either globally for the library, or for specific objects
     such as @ref c4::yml::Tree or @ref c4::yml::Parser 
-* rapidyaml uses these facilities from [c4core](https://github.com/biojppm/c4core), so their documentation
-  is also shown here:
+* rapidyaml uses these facilities from [c4core](https://github.com/biojppm/c4core), so their documentation is also shown here:
   * @ref doc_substr
   * @ref doc_charconv
   * @ref doc_format_utils