refactor error API: update docs

Author: biojppm

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

@@ -1,9 +1,30 @@
+### Improvements
+
+- [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()`.
+
 
 ### Fixes
 
 - Fix [#400](https://github.com/biojppm/rapidyaml/issues/400) ([PR#506](https://github.com/biojppm/rapidyaml/pull/506)): clear anchors after resolving.
 - Fix [#484](https://github.com/biojppm/rapidyaml/issues/484) ([PR#506](https://github.com/biojppm/rapidyaml/pull/506)): fix merge key order for last element to be overriden.
-- [PR#503](https://github.com/biojppm/rapidyaml/pull/503): ensure parse error on `a: b: c` and similar cases containing nested maps opening on the same line.
+- [PR#504](https://github.com/biojppm/rapidyaml/pull/504): ensure parse error on `a: b: c` and similar cases containing nested maps opening on the same line.
 - [PR#502](https://github.com/biojppm/rapidyaml/pull/502): fix parse errors or missing tags:
   - missing tags in empty documents:
     ```yaml

doc/Doxyfile

@@ -949,20 +949,21 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = \
-                         ./doxy_main.md \
-                         ../src \
-                         ../test/test_suite/test_suite_event_handler.hpp \
-                         ../test/test_suite/test_suite_event_handler.cpp \
-                         ../samples/quickstart.cpp \
-                         ../ext/c4core/src/c4/substr.hpp \
-                         ../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 \
+INPUT = \
+  ./doxy_main.md \
+  ./doxy_changelog.md \
+  ../src \
+  ../test/test_suite/test_suite_event_handler.hpp \
+  ../test/test_suite/test_suite_event_handler.cpp \
+  ../samples/quickstart.cpp \
+  ../ext/c4core/src/c4/substr.hpp \
+  ../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 \
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1099,7 +1100,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
@@ -1223,7 +1224,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/