Proposed changes to the basic_json_visitor interface in a future major release

[danielaparker]

Changes to _visit virtual function return values

The _visit virtual functions in basic_json_visitor currently return a bool value. Since release 1.3.1, these return values are ignored by the jsoncons functions that call them, jsoncons only looks at the ec error code returned as an output parameter.

In a future major release, we propose to change the return type to void, which by itself is a breaking change for users that have implemented their own visitor classes. To mitigate the impact of that change, we introduced two macros in 1.3.1, JSONCONS_VISITOR_RETURN_TYPE, which currently evaluates to bool, and JSONCONS_VISITOR_RETURN, which currently evaluates to return true.

Users that implement visitors using these macros, like this,

JSONCONS_VISITOR_RETURN_TYPE visit_bool(bool value,
   jsoncons::semantic_tag /*tag*/,
   const jsoncons::ser_context& /*context*/,
   std::error_code& ec) override {
       std::cout << "visit_bool() called\n";
       ec = jsoncons::make_error_code(jsoncons::json_errc::invalid_value);
       JSONCONS_VISITOR_RETURN;
}

should not have to concern themselves with this future change.

Changes to visit_byte_string virtual functions

Currently basic_json_visitor has two visit_byte_string functions with signatures

virtual JSONCONS_VISITOR_RETURN_TYPE visit_byte_string(const byte_string_view& value, 
    semantic_tag tag, 
    const ser_context& context,
    std::error_code& ec);

virtual JSONCONS_VISITOR_RETURN_TYPE visit_byte_string(const byte_string_view& value, 
    uint64_t raw_tag, 
    const ser_context& context,
    std::error_code& ec);

Currently, if a semantic_tag is supplied by the parser (CBOR or MessagePack), the raw tag is not also supplied. In the case in which a raw_tag is supplied, the semantic_tag is automatically set to semantic_tag::ext, indicating that it is set.

We propose to replace these two virtual functions with one

virtual JSONCONS_VISITOR_RETURN_TYPE visit_byte_string(const jsoncons::span<const uint8_t>& value, 
     semantic_tag tag, 
     uint64_t raw_tag, 
     const ser_context& context,
     std::error_code& ec);

With this change, the raw_tag is made available when we also have a semantic_tag. semantic_tag::ext will be removed, it's not really needed, a non-zero raw_tag tells us the same thing.

This change will be a breaking change for users that do not use the default but override visit_byte_string, however, we expect the number of users that fall into this category to be very small.