LibXML2.cpp

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#include "Stroika/Foundation/StroikaPreComp.h"
 
#include <list>
 
#include <libxml/xmlmemory.h>
#include <libxml/xmlsave.h>
 
#include "Stroika/Foundation/Characters/String.h"
#include "Stroika/Foundation/DataExchange/BadFormatException.h"
#include "Stroika/Foundation/Debug/Trace.h"
#include "Stroika/Foundation/Execution/Throw.h"
#include "Stroika/Foundation/Memory/BlockAllocated.h"
#include "Stroika/Foundation/Memory/Common.h"
#include "Stroika/Foundation/Memory/MemoryAllocator.h"
#include "Stroika/Foundation/Streams/ToSeekableInputStream.h"
 
#include "LibXML2.h"
 
using namespace Stroika::Foundation;
using namespace Stroika::Foundation::Characters;
using namespace Stroika::Foundation::DataExchange;
using namespace Stroika::Foundation::DataExchange::XML;
using namespace Stroika::Foundation::DataExchange::XML::DOM;
using namespace Stroika::Foundation::DataExchange::XML::Schema;
using namespace Stroika::Foundation::DataExchange::XML::Providers::LibXML2;
using namespace Stroika::Foundation::Debug;
using namespace Stroika::Foundation::Execution;
using namespace Stroika::Foundation::Streams;
 
using std::byte;
 
using Memory::MakeSharedPtr;
 
// Comment this in to turn on aggressive noisy DbgTrace in this module
//#define   USE_NOISY_TRACE_IN_THIS_MODULE_       1
 
static_assert (qStroika_HasComponent_libxml2, "Don't compile this file if qStroika_HasComponent_libxml2 not set");
 
CompileTimeFlagChecker_SOURCE (Stroika::Foundation::DataExchange::XML, qStroika_HasComponent_libxml2, qStroika_HasComponent_libxml2);
 
// a schema compile's own resource loader (xmlSchemaSetResourceLoader) - so no process-global input callbacks - is libxml2 2.14's
static_assert (LIBXML_VERSION >= 21400, "Stroika needs libxml2 2.14 or later - configure --libxml2 use (the default) builds one");
 
namespace {
    // From https://www.w3.org/TR/xml-names/
    //      In a namespace declaration, the URI reference is the normalized value of the attribute, so replacement of XML
    //      character and entity references has already been done before any comparison.
    //
    //  Not 100% sure, but I think that means decode %x stuff too (at least that fixes bug I'm encountering with ASTM-CCR files)
    //      --LGP 2024-01-31
    constexpr auto kUseURIEncodingFlag_ = URI::StringPCTEncodedFlag::eDecoded;
}
 
namespace {
    /*
     *  What a schema compile loads - an xs:import's or xs:include's schemaLocation - through its Resource::ResolverPtr, as that
     *  compile's own loader (xmlSchemaSetResourceLoader): nothing process-global, so neither another thread nor another user of
     *  libxml2 in the process sees it. What the resolver does not have is loaded as libxml2 would, from its URL.
     */
    xmlParserErrors ResourceLoader_ (void* resolver, const char* url, const char* publicID, [[maybe_unused]] xmlResourceType type,
                                     xmlParserInputFlags flags, xmlParserInput** out) noexcept
    {
        RequireNotNull (resolver);
        RequireNotNull (url);
        RequireNotNull (out);
        try {
            // libxml2 gives no import's namespace here, so the URL is each of the resolver's keys - but a public ID, where there is one
            String u = String::FromUTF8 (url);
            if (optional<Resource::Definition> r = reinterpret_cast<const Resource::ResolverPtr*> (resolver)->Lookup (
                    Resource::Name{.fNamespace = u, .fPublicID = publicID == nullptr ? u : String::FromUTF8 (publicID), .fSystemID = u})) {
                *out = xmlNewInputFromMemory (url, r->fData.data (), r->fData.size (), flags);
                return *out == nullptr ? XML_ERR_NO_MEMORY : XML_ERR_OK;
            }
            return xmlNewInputFromUrl (url, flags, out);
        }
        catch (...) {
            // nothing may be thrown through libxml2, a C library
            DbgTrace ("resolving '{}' failed: {}"_f, String::FromUTF8 (url), current_exception ());
            return XML_ERR_INTERNAL_ERROR;
        }
    }
}
 
namespace {
    /*
     *  What libxml2 reports to a schema compile or validation, as its structured error handler (xmlSchemaSetParserStructuredErrors,
     *  xmlSchemaSetValidStructuredErrors): the first error - what it says, and where - for the BadFormatException that follows;
     *  warnings are only traced. Given no handler, libxml2 prints its diagnostics to stderr, which is not a library's business.
     *  Not the generic pair of callbacks (xmlSchemaSetParserErrors, xmlSchemaSetValidErrors - deprecated as of libxml2 2.15):
     *  libxml2 passes only a structured handler on to the parser of each document an xs:import or xs:include loads
     *  (xmlSchemaAddSchemaDoc), so with the pair, what that parser reports - a schemaLocation that would not load - goes to
     *  stderr; and an xmlError's message is UTF-8, where the pair's printf-style arguments say nothing of their character set.
     */
    struct SchemaErrors_ {
        String                 fWhatFailed; // the start of the exception's message
        String                 fFirstError;
        optional<unsigned int> fLine;
        optional<unsigned int> fColumn;
 
        static void Handler (void* userData, const xmlError* error) noexcept
        {
            auto useThis = reinterpret_cast<SchemaErrors_*> (userData);
            try {
                if (error->level == XML_ERR_WARNING) {
                    DbgTrace ("libxml2 warning ignored: {}"_f, String::FromUTF8 (error->message).Trim ());
                }
                else if (useThis->fFirstError.empty ()) {
                    useThis->fFirstError = String::FromUTF8 (error->message).Trim ();
                    if (error->line > 0) {
                        useThis->fLine = static_cast<unsigned int> (error->line);
                    }
                    if (error->int2 > 0) {
                        useThis->fColumn = static_cast<unsigned int> (error->int2);
                    }
                }
            }
            catch (...) {
                // nothing may be thrown through libxml2, a C library
            }
        }
        BadFormatException AsException () const
        {
            return BadFormatException{fFirstError.empty () ? fWhatFailed : fWhatFailed + ": "_k + fFirstError, fLine, fColumn, nullopt};
        }
    };
}
 
namespace {
    struct SchemaRep_ final : ILibXML2SchemaRep {
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
        static inline atomic<unsigned int> sLiveCnt{0};
#endif
        SchemaRep_ (const shared_ptr<const void>& library, const Streams::InputStream::Ptr<byte>& schemaData, const Resource::ResolverPtr& resolver)
            : fLibrary_{library}
            , fResolver_{resolver}
            , fSchemaData{schemaData.ReadAll ()}
        {
            xmlSchemaParserCtxt* schemaParseContext =
                xmlSchemaNewMemParserCtxt (reinterpret_cast<const char*> (fSchemaData.data ()), static_cast<int> (fSchemaData.size ()));
            Execution::ThrowIfNull (schemaParseContext); // this one IS an allocation, so bad_alloc is what it means
            if (fResolver_ != nullptr) {
                xmlSchemaSetResourceLoader (schemaParseContext, &ResourceLoader_, &fResolver_);
            }
            /*
             *  What is WRONG with the schema comes only through the handler: xmlSchemaParse answers just nullptr - which before
             *  Stroika v3.0d25 went to Execution::ThrowIfNull, and so came out as std::bad_alloc.
             */
            SchemaErrors_ errors{.fWhatFailed = "Failed to compile schema"_k};
            xmlSchemaSetParserStructuredErrors (schemaParseContext, &SchemaErrors_::Handler, &errors);
            fCompiledSchema = xmlSchemaParse (schemaParseContext);
            xmlSchemaFreeParserCtxt (schemaParseContext);
            if (fCompiledSchema == nullptr) [[unlikely]] {
                Execution::Throw (errors.AsException ());
            }
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
            ++sLiveCnt;
#endif
        }
        SchemaRep_ (const SchemaRep_&) = delete;
        virtual ~SchemaRep_ ()
        {
            xmlSchemaFree (fCompiledSchema);
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
            Assert (sLiveCnt > 0);
            --sLiveCnt;
#endif
        }
        shared_ptr<const void> fLibrary_; // first, so destroyed last: libxml2 lasts while anything of it does
        Resource::ResolverPtr  fResolver_{nullptr};
        Memory::BLOB           fSchemaData;
        xmlSchema*             fCompiledSchema{nullptr};
 
        virtual const Providers::ISchemaProvider* GetProvider () const override
        {
            return &XML::Providers::LibXML2::kDefaultProvider;
        }
        virtual optional<URI> GetTargetNamespace () const override
        {
            Assert (fCompiledSchema != nullptr);
            if (fCompiledSchema->targetNamespace != nullptr) {
                return URI{libXMLString2String (fCompiledSchema->targetNamespace)};
            }
            return nullopt;
        }
        virtual Memory::BLOB GetData () override
        {
            return fSchemaData;
        }
        // not super useful, except if you want to clone
        virtual Resource::ResolverPtr GetResolver () override
        {
            return fResolver_;
        }
        virtual xmlSchema* GetSchemaLibRep () override
        {
            AssertNotNull (fCompiledSchema);
            return fCompiledSchema;
        }
    };
}
 
namespace {
    struct SAXReader_ final {
        using Name = StructuredStreamEvents::Name;
        xmlSAXHandler                      flibXMLSaxHndler_{};
        StructuredStreamEvents::IConsumer& fCallback_;
        xmlParserCtxtPtr                   fCtxt_{nullptr}; // SAXParse sets this, as soon as it has made the context
        // the consumer's exception, as thrown - so rethrown whole: a throw of *pointer-to-base would slice it
        exception_ptr fCapturedException_;
 
        /**
         *  Call an IConsumer from a libxml2 SAX callback. An IConsumer may throw - ObjectReader does, on data it cannot
         *  map - and the exception must not escape into libxml2, whose frames lie between here and SAXParse. libxml2 is
         *  C, so its functions are nounwind, and with -flto the unwind tables for them go away: the unwinder then finds
         *  no handler at all and terminates. (Without LTO it unwinds, which is why this stood for so long.) So catch it
         *  here, stop the parse, and let SAXParse rethrow it once libxml2's frames are gone.
         */
        template <typename CALL_CONSUMER>
        static void Invoke_ (void* ctx, CALL_CONSUMER&& callConsumer) noexcept
        {
            SAXReader_* thisReader = reinterpret_cast<SAXReader_*> (ctx);
            Assert (thisReader->flibXMLSaxHndler_.initialized == XML_SAX2_MAGIC); // assure ctx ptr passed through properly
            if (thisReader->fCapturedException_ == nullptr) [[likely]] {
                try {
                    callConsumer (thisReader->fCallback_);
                }
                catch (...) {
                    thisReader->fCapturedException_ = current_exception ();
                    xmlStopParser (thisReader->fCtxt_);
                }
            }
        }
        void ThrowIfCapturedException ()
        {
            if (fCapturedException_ != nullptr) [[unlikely]] {
                rethrow_exception (fCapturedException_);
            }
        }
 
        SAXReader_ (StructuredStreamEvents::IConsumer& callback)
            : fCallback_{callback}
        {
            flibXMLSaxHndler_.initialized   = XML_SAX2_MAGIC;
            flibXMLSaxHndler_.startDocument = [] (void* ctx) {
                Invoke_ (ctx, [] (StructuredStreamEvents::IConsumer& consumer) { consumer.StartDocument (); });
            };
            flibXMLSaxHndler_.endDocument = [] (void* ctx) {
                Invoke_ (ctx, [] (StructuredStreamEvents::IConsumer& consumer) { consumer.EndDocument (); });
            };
            flibXMLSaxHndler_.startElementNs = [] (void* ctx, const xmlChar* localname, [[maybe_unused]] const xmlChar* prefix, const xmlChar* URI,
                                                   [[maybe_unused]] int nb_namespaces, [[maybe_unused]] const xmlChar** namespaces,
                                                   int nb_attributes, [[maybe_unused]] int nb_defaulted, const xmlChar** attributes) {
                Invoke_ (ctx, [&] (StructuredStreamEvents::IConsumer& consumer) {
                    Mapping<Name, String> attrs;
                    if (attributes != nullptr) {
                        // Crazy way to decode attribute arguments - I would have never guessed --
                        // https://stackoverflow.com/questions/2075894/how-to-get-the-name-and-value-of-attributes-from-xml-when-using-libxml2-sax-pars
                        auto ai = attributes;
                        for (int i = 0; i < nb_attributes; ++i) {
                            // @todo fix must grab namespace, probably from namespaces, but will take some research to figure out how!!!
                            // libxml2 hands over the value decoded - except that, not replacing entities (which would expand external
                            // ones too), it leaves each '&' it decoded as the reference "&#38;"
                            attrs.Add (Name{"", libXMLString2String (ai[0]), Name::eAttribute},
                                       libXMLString2String (ai[3], static_cast<int> (ai[4] - ai[3])).ReplaceAll ("&#38;"sv, "&"sv));
                            ai += 5;
                        }
                    }
                    if (URI == nullptr) {
                        consumer.StartElement (Name{libXMLString2String (localname)}, attrs);
                    }
                    else {
                        consumer.StartElement (Name{libXMLString2String (URI), libXMLString2String (localname)}, attrs);
                    }
                });
            };
            flibXMLSaxHndler_.endElementNs = [] (void* ctx, const xmlChar* localname, [[maybe_unused]] const xmlChar* prefix, const xmlChar* URI) {
                Invoke_ (ctx, [&] (StructuredStreamEvents::IConsumer& consumer) {
                    if (URI == nullptr) {
                        consumer.EndElement (Name{libXMLString2String (localname)});
                    }
                    else {
                        consumer.EndElement (Name{libXMLString2String (URI), libXMLString2String (localname)});
                    }
                });
            };
            flibXMLSaxHndler_.characters = [] (void* ctx, const xmlChar* ch, int len) {
                Invoke_ (ctx, [&] (StructuredStreamEvents::IConsumer& consumer) {
                    // unclear how this handles 'continuations' and partial characters - may need a more sophisticated approach
                    consumer.TextInsideElement (String::FromUTF8 (span{reinterpret_cast<const char*> (ch), static_cast<size_t> (len)}));
                });
            };
        }
        SAXReader_ (const SAXReader_&) = delete;
    };
}
 
namespace {
#if qStroika_Foundation_Debug_AssertionsChecked
    bool ValidNewNodeName_ (const String& n)
    {
        if (n.empty ()) {
            return false;
        }
        if (n.find (':') != wstring::npos) { // if triggered, you probably used XPath as arg for CreateElement call!!!
            return false;
        }
        return true;
    }
#endif
}
 
namespace {
    struct DocRep_;
    DocRep_* GetWrapperDoc_ (xmlDoc* d);
#if qStroika_Foundation_Debug_AssertionsChecked
    weak_ptr<Document::IRep> DocumentOf_ (xmlNode* n);
#endif
    DocRep_* GetWrapperDoc_ (xmlNode* n)
    {
        RequireNotNull (n);
        RequireNotNull (n->doc);
        return GetWrapperDoc_ (n->doc);
    }
    xmlNs* GetSharedReUsableXMLNSParentNamespace_ (xmlDoc* d);
    xmlNs* GetSharedReUsableXMLNSParentNamespace_ (xmlNode* n)
    {
        RequireNotNull (n);
        RequireNotNull (n->doc);
        return GetSharedReUsableXMLNSParentNamespace_ (n->doc);
    }
}
 
namespace {
    Node::Ptr WrapLibXML2NodeInStroikaNode_ (xmlNode* n);
}
 
namespace {
    struct NodeRep_ : ILibXML2NodeRep, Memory::UseBlockAllocationIfAppropriate<NodeRep_> {
    public:
        NodeRep_ (xmlNode* n)
            : fNode_{n}
#if qStroika_Foundation_Debug_AssertionsChecked
            , fOwningDoc_{DocumentOf_ (n)}
#endif
        {
            RequireNotNull (n);
        }
#if qStroika_Foundation_Debug_AssertionsChecked
        ~NodeRep_ ()
        {
            // a node is an internal pointer into its document (Node::Ptr): whoever holds it must hold the Document::Ptr longer -
            // so any use of this node after its document went would have read freed memory. Here catches every such use, but only
            // once it is too late: the same Require goes at any use worth the cost of checking too
            Require (not fOwningDoc_.expired ());
        }
#endif
        virtual const Providers::IDOMProvider* GetProvider () const override
        {
            return &Providers::LibXML2::kDefaultProvider;
        }
        virtual bool Equals (const IRep* rhs) const override
        {
            RequireNotNull (fNode_);
            RequireNotNull (rhs);
            return fNode_ == dynamic_cast<const NodeRep_*> (rhs)->fNode_;
        }
        virtual Node::Type GetNodeType () const override
        {
            AssertNotNull (fNode_);
            switch (fNode_->type) {
                case XML_ELEMENT_NODE:
                    return Node::eElementNT;
                case XML_ATTRIBUTE_NODE:
                    return Node::eAttributeNT;
                case XML_TEXT_NODE:
                    return Node::eTextNT;
                case XML_COMMENT_NODE:
                    return Node::eCommentNT;
                default:
                    return Node::eOtherNT;
            }
        }
        virtual NameWithNamespace GetName () const override
        {
            AssertNotNull (fNode_);
            Require (GetNodeType () == Node::eElementNT or GetNodeType () == Node::eAttributeNT);
            switch (fNode_->type) {
                case XML_ATTRIBUTE_NODE:
                case XML_ELEMENT_NODE: {
                    const xmlChar* ns = fNode_->ns == nullptr ? nullptr : fNode_->ns->href;
                    return NameWithNamespace{ns == nullptr ? optional<URI>{} : URI{libXMLString2String (ns)}, libXMLString2String (fNode_->name)};
                }
                default:
                    AssertNotReached ();
                    return NameWithNamespace{""sv};
            }
        }
        virtual void SetName (const NameWithNamespace& name) override
        {
            AssertNotNull (fNode_);
#if qStroika_Foundation_Debug_AssertionsChecked
            Require (ValidNewNodeName_ (name.fName));
#endif
            if (name.fNamespace) {
                AssertNotReached (); // pretty sure this is wrong...
                // see genNS2Use_
                // see SetAttribtues - simple now...
            }
            xmlNodeSetName (fNode_, BAD_CAST name.fName.AsUTF8 ().c_str ());
        }
        virtual String GetValue () const override
        {
            AssertNotNull (fNode_);
            auto                    r       = xmlNodeGetContent (fNode_);
            [[maybe_unused]] auto&& cleanup = Execution::Finally ([&] () noexcept { xmlFree (r); });
            return libXMLString2String (r);
        }
        virtual void SetValue (const String& v) override
        {
            AssertNotNull (fNode_);
            // @todo could optimize and avoid xmlEncodeSpecialChars for most cases, by scanning for &<> etc... Maybe imporve logic in WriterUtils.h! - so can use that
            bool mustEncode = true;
            if (mustEncode) {
                xmlChar*                p       = xmlEncodeSpecialChars (fNode_->doc, BAD_CAST v.AsUTF8 ().c_str ());
                [[maybe_unused]] auto&& cleanup = Execution::Finally ([&] () noexcept { xmlFree (p); });
                ::xmlNodeSetContent (fNode_, p);
            }
            else {
                ::xmlNodeSetContent (fNode_, BAD_CAST v.AsUTF8 ().c_str ());
            }
        }
        virtual void DeleteNode () override
        {
            RequireNotNull (fNode_);
            ::xmlUnlinkNode (fNode_);
            ::xmlFreeNode (fNode_);
            fNode_ = nullptr;
        }
        virtual Node::Ptr GetParentNode () const override
        {
            RequireNotNull (fNode_);
            if (fNode_->parent == nullptr) {
                return Node::Ptr{nullptr};
            }
            return WrapLibXML2NodeInStroikaNode_ (fNode_->parent);
        }
        virtual void Write (const Streams::OutputStream::Ptr<byte>& to, const SerializationOptions& options) const override
        {
            xmlBufferPtr            xmlBuf  = xmlBufferCreate ();
            [[maybe_unused]] auto&& cleanup = Execution::Finally ([&] () noexcept { ::xmlBufferFree (xmlBuf); });
            if (int dumpRes = ::xmlNodeDump (xmlBuf, fNode_->doc, fNode_, 0, options.fPrettyPrint); dumpRes == -1) {
                Execution::Throw (Execution::Exception<runtime_error>{"failed dumping node to text"sv});
            }
            const xmlChar* t = xmlBufferContent (xmlBuf);
            AssertNotNull (t);
            to.Write (span{reinterpret_cast<const byte*> (t), static_cast<size_t> (::strlen (reinterpret_cast<const char*> (t)))});
        }
        virtual xmlNode* GetInternalTRep () override
        {
            return fNode_;
        }
        /*
         *  For an ATTRIBUTE, which is in no namespace at all unless it carries a prefix - a default namespace declaration
         *  applies to elements only (XML Namespaces, section 6.2). So never the prefixless declaration that
         *  xmlSearchNsByHref hands back first: find a PREFIXED one for that href, or declare one.
         */
        static xmlNsPtr genPrefixedNS2Use_ (xmlNode* n, const URI& ns)
        {
            const string href = ns.As<String> (kUseURIEncodingFlag_).AsUTF8<string> ();
            for (xmlNode* i = n; i != nullptr and i->type == XML_ELEMENT_NODE; i = i->parent) {
                for (xmlNs* d = i->nsDef; d != nullptr; d = d->next) {
                    if (d->prefix != nullptr and ::xmlStrEqual (d->href, BAD_CAST href.c_str ())) {
                        return d;
                    }
                }
            }
            string   prefix2Try{"a"};
            xmlNsPtr ns2Use = nullptr;
            while (ns2Use == nullptr) {
                ns2Use = ::xmlNewNs (n, BAD_CAST href.c_str (), BAD_CAST prefix2Try.c_str ());
                if (ns2Use == nullptr) {
                    ++prefix2Try[0]; // that prefix is taken here, by another namespace - as genNS2Use_ has it
                }
            }
            return ns2Use;
        }
        /*
         *  The namespace a new element goes in: kNoNamespace none at all, kInheritNamespace (which is what a name built
         *  without one has) its parent's, and otherwise the one it names.
         */
        static xmlNsPtr elementNS2Use_ (xmlNode* parent, const NameWithNamespace& eltName)
        {
            if (eltName.fNamespace == kNoNamespace) {
                return nullptr;
            }
            return eltName.fNamespace ? genNS2Use_ (parent, *eltName.fNamespace) : parent->ns;
        }
        /*
         *  An element in no namespace, under one that declared a default, must SAY so - xmlns="" - or it reads back in that
         *  default. libxml2 writes what the node carries and reconciles nothing, so say it here.
         */
        static void undeclareDefaultNSIfInScope_ (xmlNode* newNode)
        {
            AssertNotNull (newNode);
            if (newNode->ns == nullptr) {
                xmlNs* inScope = ::xmlSearchNs (newNode->doc, newNode->parent, nullptr);
                if (inScope != nullptr and inScope->href != nullptr and *inScope->href != '\0') {
                    ::xmlSetNsProp (newNode, GetSharedReUsableXMLNSParentNamespace_ (newNode), BAD_CAST "xmlns", BAD_CAST "");
                }
            }
        }
        static xmlNsPtr genNS2Use_ (xmlNode* n, const URI& ns)
        {
            xmlNsPtr ns2Use = xmlSearchNsByHref (n->doc, n, BAD_CAST ns.As<String> (kUseURIEncodingFlag_).AsUTF8 ().c_str ());
            string   prefix2Try{"a"};
            while (ns2Use == nullptr) {
                // Need to hang the namespace declaration someplace? Could do it just on this element (xmlNewNs)
                // Or on the root doc (xmlNewGlobalNs).
                // For now - do on DOC, so we end up with a more terse overall document.
                // Also - sadly - must cons up SOME prefix, which doesn't conflict. No good way I can see todo that, so do a bad way.
                // OK - can do still manually using docs root elt - maybe - but do this way for now... cuz xmlNewGlobalNs deprecated
                ns2Use = xmlNewNs (n, BAD_CAST ns.As<String> (kUseURIEncodingFlag_).AsUTF8 ().c_str (), BAD_CAST prefix2Try.c_str ());
                if (ns2Use == nullptr) {
                    ++prefix2Try[0]; // if 'a' didn't work, try 'b' // @todo this could use better error handling, but pragmatically probably OK
                }
            }
            return ns2Use;
        }
        // not ref counted: freed with its document, which whoever holds this must keep (Node::Ptr) - checked in the DTOR
        xmlNode* fNode_;
#if qStroika_Foundation_Debug_AssertionsChecked
        weak_ptr<Document::IRep> fOwningDoc_;
#endif
    };
}
 
namespace {
    DISABLE_COMPILER_MSC_WARNING_START (4250) // inherits via dominance warning
    struct ElementRep_ : Element::IRep, Memory::InheritAndUseBlockAllocationIfAppropriate<ElementRep_, NodeRep_> {
        using inherited = Memory::InheritAndUseBlockAllocationIfAppropriate<ElementRep_, NodeRep_>;
        ElementRep_ (xmlNode* n)
            : inherited{n}
        {
            RequireNotNull (n);
            Require (n->type == XML_ELEMENT_NODE);
        }
        virtual Node::Type GetNodeType () const override
        {
            AssertNotNull (fNode_);
            Assert (fNode_->type == XML_ELEMENT_NODE);
            return Node::eElementNT;
        }
        virtual optional<String> GetAttribute (const NameWithNamespace& attrName) const override
        {
            auto r = attrName.fNamespace ? ::xmlGetNsProp (fNode_, BAD_CAST attrName.fName.AsUTF8 ().c_str (),
                                                           BAD_CAST attrName.fNamespace->As<String> (kUseURIEncodingFlag_).AsUTF8 ().c_str ())
                                         : ::xmlGetProp (fNode_, BAD_CAST attrName.fName.AsUTF8 ().c_str ());
            if (r == nullptr) {
                return nullopt;
            }
            [[maybe_unused]] auto&& cleanup = Execution::Finally ([&] () noexcept { xmlFree (r); });
            return ::libXMLString2String (r);
        }
        virtual void SetAttribute (const NameWithNamespace& attrName, const optional<String>& v) override
        {
            RequireNotNull (fNode_);
            Require (GetNodeType () == Node::eElementNT);
            // any attribute IN the xmlns namespace is a namespace declaration - xmlns itself, or xmlns:PREFIX - and the one
            // namespace no prefix may be bound to, so never the prefixing below
            if (attrName.fNamespace == kXMLNS.fNamespace and attrName.fName != kXMLNS.fName) {
                /*
                 *  xmlns:PREFIX - a prefix declaration, which to libxml2 is not an attribute at all but an xmlNs hung on
                 *  the node, and so is made with xmlNewNs. Written as an attribute instead it comes out named for the
                 *  prefix alone (s="..."), declaring nothing. Nothing undeclares a prefix, so a nullopt is no request.
                 */
                if (v) {
                    ::xmlNewNs (fNode_, BAD_CAST v->AsUTF8<string> ().c_str (), BAD_CAST attrName.fName.AsUTF8<string> ().c_str ());
                }
            }
            else if (attrName.fNamespace == kXMLNS.fNamespace) {
                /*
                 *  Queer, but libxml2 appears to require this attribute have the given namespace (fine) - but not provide a usable xmlNs object.
                 *  So we must create it on the document, and free it when we free the document.
                 *
                 *      \see https://github.com/SophistSolutions/Stroika/issues/1133 (STK-1001)
                 *
                 *  A nullopt here is NOT the delete below: xmlns="" is how XML undeclares a default namespace, which is
                 *  just what Element::Ptr::SetDefaultNamespace (nullopt) asks for.
                 */
                ::xmlSetNsProp (fNode_, GetSharedReUsableXMLNSParentNamespace_ (fNode_), BAD_CAST attrName.fName.AsUTF8 ().c_str (),
                                v == nullopt ? nullptr : (BAD_CAST v->AsUTF8 ().c_str ()));
            }
            else if (v == nullopt) {
                /*
                 *  nullopt deletes the attribute. xmlSetProp with a nullptr value does not: it leaves an empty attribute
                 *  behind, and creates one for a name that was never there. And genNS2Use_ would DECLARE a namespace to
                 *  delete through, so search for one instead - where none is declared, no attribute is in it.
                 */
                if (attrName.fNamespace) {
                    if (xmlNs* ns = ::xmlSearchNsByHref (fNode_->doc, fNode_,
                                                         BAD_CAST attrName.fNamespace->As<String> (kUseURIEncodingFlag_).AsUTF8 ().c_str ())) {
                        ::xmlUnsetNsProp (fNode_, ns, BAD_CAST attrName.fName.AsUTF8 ().c_str ());
                    }
                }
                else {
                    ::xmlUnsetProp (fNode_, BAD_CAST attrName.fName.AsUTF8 ().c_str ());
                }
            }
            else if (attrName.fNamespace) {
                // Lookup the argument ns and either add it to this node or use the existing one - a PREFIXED one, @see genPrefixedNS2Use_
                ::xmlSetNsProp (fNode_, genPrefixedNS2Use_ (fNode_, *attrName.fNamespace), BAD_CAST attrName.fName.AsUTF8 ().c_str (),
                                BAD_CAST v->AsUTF8 ().c_str ());
            }
            else {
                ::xmlSetProp (fNode_, BAD_CAST attrName.fName.AsUTF8 ().c_str (), BAD_CAST v->AsUTF8 ().c_str ());
            }
        }
        virtual Element::Ptr InsertElement (const NameWithNamespace& eltName, const Element::Ptr& afterNode) override
        {
#if qStroika_Foundation_Debug_AssertionsChecked
            Require (ValidNewNodeName_ (eltName.fName));
#endif
            Require (afterNode == nullptr or this->GetChildren ().Contains (afterNode));
            // when adding a child, if no NS specified, copy parents
            xmlNs*    useNS        = elementNS2Use_ (fNode_, eltName);
            xmlNode*  newNode      = ::xmlNewNode (useNS, BAD_CAST eltName.fName.AsUTF8 ().c_str ());
            NodeRep_* afterNodeRep = afterNode == nullptr ? nullptr : dynamic_cast<NodeRep_*> (afterNode.GetRep ().get ());
            if (afterNodeRep == nullptr) {
                // unfortunately complicated - no prepend api (just append). Can say xmlAddPrevSibling for first child though which amounts
                // to same thing (unless there is no first child)
                if (fNode_->children == nullptr) {
                    ::xmlAddChild (fNode_, newNode); // nothing to go before, so append=prepend
                }
                else {
                    ::xmlAddPrevSibling (fNode_->children, newNode);
                }
            }
            else {
                xmlAddNextSibling (afterNodeRep->fNode_, newNode);
            }
            undeclareDefaultNSIfInScope_ (newNode);
            return WrapLibXML2NodeInStroikaNode_ (newNode);
        }
        virtual Element::Ptr AppendElement (const NameWithNamespace& eltName) override
        {
#if qStroika_Foundation_Debug_AssertionsChecked
            Require (ValidNewNodeName_ (eltName.fName));
#endif
            // when adding a child, if no NS specified, copy parents
            xmlNs*   useNS   = elementNS2Use_ (fNode_, eltName);
            xmlNode* newNode = xmlNewNode (useNS, BAD_CAST eltName.fName.AsUTF8 ().c_str ());
            ::xmlAddChild (fNode_, newNode);
            undeclareDefaultNSIfInScope_ (newNode);
            return WrapLibXML2NodeInStroikaNode_ (newNode);
        }
        /*
         *  A deep COPY into this document - xmlDocCopyNode, never xmlAddChild of the original, which would move it out of
         *  the document it belongs to. xmlReconciliateNs then declares, on the copy, whatever namespaces it referred to
         *  through its old document's declarations - without which a grafted subtree points at an xmlNs that is not there.
         */
        xmlNode* CloneIntoThisDocument_ (const Node::Ptr& cloneFrom)
        {
            RequireNotNull (cloneFrom);
            const NodeRep_* fromRep = dynamic_cast<const NodeRep_*> (cloneFrom.GetRep ().get ());
            Require (fromRep != nullptr); // the caller's contract: both documents are the same provider
            xmlNode* copy = ::xmlDocCopyNode (fromRep->fNode_, fNode_->doc, 1 /*recursive, with attributes*/);
            Execution::ThrowIfNull (copy);
            return copy;
        }
        virtual Element::Ptr AppendImportedNode (const Node::Ptr& cloneFrom) override
        {
            xmlNode* copy = CloneIntoThisDocument_ (cloneFrom);
            ::xmlAddChild (fNode_, copy);
            ::xmlReconciliateNs (fNode_->doc, copy);
            return WrapLibXML2NodeInStroikaNode_ (copy);
        }
        virtual Element::Ptr InsertImportedNode (const Node::Ptr& cloneFrom, const Element::Ptr& afterNode) override
        {
            Require (afterNode == nullptr or this->GetChildren ().Contains (afterNode));
            xmlNode*  copy         = CloneIntoThisDocument_ (cloneFrom);
            NodeRep_* afterNodeRep = afterNode == nullptr ? nullptr : dynamic_cast<NodeRep_*> (afterNode.GetRep ().get ());
            if (afterNodeRep == nullptr) {
                if (fNode_->children == nullptr) {
                    ::xmlAddChild (fNode_, copy); // nothing to go before, so first is last
                }
                else {
                    ::xmlAddPrevSibling (fNode_->children, copy);
                }
            }
            else {
                ::xmlAddNextSibling (afterNodeRep->fNode_, copy);
            }
            ::xmlReconciliateNs (fNode_->doc, copy);
            return WrapLibXML2NodeInStroikaNode_ (copy);
        }
        virtual Iterable<Node::Ptr> GetChildren () const override
        {
            RequireNotNull (fNode_);
            // No reference counting possible here because these notes - i THINK - are owned by document, and the linked list not
            // reference counted (elts) - so just count on no changes during iteration
            return Traversal::CreateGenerator<Node::Ptr> ([curChild = fNode_->children] () mutable -> optional<Node::Ptr> {
                if (curChild == nullptr) {
                    return optional<Node::Ptr>{};
                }
                Node::Ptr r = WrapLibXML2NodeInStroikaNode_ (curChild);
                curChild    = curChild->next;
                return r;
            });
        }
        struct XPathLookupHelper_ final {
            xmlXPathContext* fCtx{nullptr};
            xmlXPathObject*  fResultNodeList{nullptr};
            XPathLookupHelper_ ()                          = delete;
            XPathLookupHelper_ (const XPathLookupHelper_&) = delete;
            XPathLookupHelper_ (xmlDoc* doc, xmlNode* contextNode, const XPath::Expression& e)
            {
                // based on code from http://www.xmlsoft.org/examples/xpath1.c
                RequireNotNull (doc);
                fCtx = xmlXPathNewContext (doc);
                Execution::ThrowIfNull (fCtx);
                fCtx->error = [] ([[maybe_unused]] void* userData, [[maybe_unused]] const xmlError* error) {
                    // default function prints to console; we capture 'lastError' later so no need to do anything here.
                };
                try {
                    auto namespaceDefs = e.GetOptions ().fNamespaces;
                    if (namespaceDefs.GetDefaultNamespace ()) {
                        // According to https://gitlab.gnome.org/GNOME/libxml2/-/issues/585, this is XPath 2 feature NYI in libxml2
                        Execution::Throw (XPath::XPathExpressionNotSupported::kThe);
                    }
                    for (Common::KeyValuePair ni : namespaceDefs.GetPrefixedNamespaces ()) {
                        xmlXPathRegisterNs (fCtx, BAD_CAST ni.fKey.AsUTF8 ().c_str (),
                                            BAD_CAST ni.fValue.As<String> (kUseURIEncodingFlag_).AsUTF8 ().c_str ());
                    }
                    fCtx->node      = contextNode;
                    fResultNodeList = xmlXPathEvalExpression (BAD_CAST e.GetExpression ().AsUTF8 ().c_str (), fCtx);
                    if (fCtx->lastError.level != XML_ERR_NONE and fCtx->lastError.level != XML_ERR_WARNING) {
                        // lookup domain in xmlErrorDomain, and lastError.code in xmlParserErrors
                        Execution::ThrowIfNull (fResultNodeList, Execution::Exception<runtime_error>{"Error parsing xpath {}: (domain {}, code {})"_f(
                                                                     e, fCtx->lastError.domain, fCtx->lastError.code)});
                    }
                    Execution::ThrowIfNull (fResultNodeList);
                }
                catch (...) {
                    if (fResultNodeList != nullptr) {
                        xmlXPathFreeObject (fResultNodeList);
                        fResultNodeList = nullptr;
                    }
                    if (fCtx != nullptr) {
                        xmlXPathFreeContext (fCtx);
                        fCtx = nullptr;
                    }
                    Execution::ReThrow ();
                }
            }
            ~XPathLookupHelper_ ()
            {
                AssertNotNull (fResultNodeList);
                xmlXPathFreeObject (fResultNodeList);
                AssertNotNull (fCtx);
                xmlXPathFreeContext (fCtx);
            }
            static optional<XPath::Result> ToResult (xmlNode* n)
            {
                if (n == nullptr) [[unlikely]] {
                    return nullopt;
                }
                // for now only support elements/attributes...
                switch (n->type) {
                    case XML_ATTRIBUTE_NODE:
                    case XML_ELEMENT_NODE: {
                        return WrapLibXML2NodeInStroikaNode_ (n);
                    }
                }
                return nullopt;
            }
        };
        virtual optional<XPath::Result> LookupOne (const XPath::Expression& e) override
        {
            RequireNotNull (fNode_);
            AssertNotNull (fNode_->doc);
            XPathLookupHelper_ helper{fNode_->doc, fNode_, e};
            xmlNodeSet*        resultSet = helper.fResultNodeList->nodesetval;
            size_t             size      = (resultSet) ? resultSet->nodeNr : 0;
            if (size > 0) {
                return XPathLookupHelper_::ToResult (resultSet->nodeTab[0]);
            }
            return nullopt;
        }
        virtual Traversal::Iterable<XPath::Result> Lookup (const XPath::Expression& e) override
        {
            // Could use generator, but little point since libxml2 has already done all the work inside
            // xmlXPathEvalExpression, and we'd just save the wrapping in Stroika Node::Rep object/shared_ptr
            // For now, KISS
            // So essentially treat as if e.GetOptions().fSnapshot == true
            // @todo - see if anything needed to support fOrdering???
            RequireNotNull (fNode_);
            AssertNotNull (fNode_->doc);
            XPathLookupHelper_      helper{fNode_->doc, fNode_, e};
            xmlNodeSet*             resultSet = helper.fResultNodeList->nodesetval;
            size_t                  size      = (resultSet) ? resultSet->nodeNr : 0;
            Sequence<XPath::Result> r;
            for (size_t i = 0; i < size; ++i) {
                r += Memory::ValueOf (XPathLookupHelper_::ToResult (resultSet->nodeTab[i]));
            }
            return r;
        }
    };
    DISABLE_COMPILER_MSC_WARNING_END (4250) // inherits via dominance warning
}
 
namespace {
    Node::Ptr WrapLibXML2NodeInStroikaNode_ (xmlNode* n)
    {
        RequireNotNull (n);
        if (n->type == XML_ELEMENT_NODE) [[likely]] {
            return Node::Ptr{MakeSharedPtr<ElementRep_> (n)};
        }
        else {
            return Node::Ptr{MakeSharedPtr<NodeRep_> (n)};
        }
    }
}
 
namespace {
    struct MyLibXML2StructuredErrGrabber_ final {
        xmlParserCtxtPtr fCtx;
        // the first error, as thrown - so rethrown whole: a throw of *pointer-to-base would slice it
        exception_ptr fCapturedException;
 
        MyLibXML2StructuredErrGrabber_ (xmlParserCtxtPtr ctx)
            : fCtx{ctx}
        {
            xmlCtxtSetErrorHandler (ctx, xmlStructuredErrorFunc_, this);
        }
        ~MyLibXML2StructuredErrGrabber_ ()
        {
            xmlCtxtSetErrorHandler (fCtx, nullptr, nullptr);
        }
        MyLibXML2StructuredErrGrabber_& operator= (const MyLibXML2StructuredErrGrabber_&) = delete;
 
        void ThrowIf ()
        {
            if (fCapturedException != nullptr) {
                Execution::ReThrow (fCapturedException);
            }
        }
 
    private:
        static void xmlStructuredErrorFunc_ (void* userData, const xmlError* error)
        {
            // nice to throw but this is 'C' land, so probably not safe
            MyLibXML2StructuredErrGrabber_* useThis = reinterpret_cast<MyLibXML2StructuredErrGrabber_*> (userData);
            // save first error
            if (useThis->fCapturedException == nullptr) {
                switch (error->level) {
                    case XML_ERR_NONE:
                        AssertNotReached ();
                        break;
                    case XML_ERR_WARNING:
                        DbgTrace ("libxml2 (xmlStructuredErrorFunc_): Ignore warnings for now: {}"_f, String::FromUTF8 (error->message));
                        break;
                    case XML_ERR_ERROR:
                    case XML_ERR_FATAL:
                        DbgTrace ("libxml2 (xmlStructuredErrorFunc_): Capturing Error {}"_f, String::FromUTF8 (error->message));
                        // thrown and caught at once - never through libxml2's C - so Throw stamps it with the current Activities
                        try {
                            Execution::Throw (DataExchange::BadFormatException{
                                "Failure Parsing XML: {}, line {}"_f(String::FromUTF8 (error->message), error->line),
                                static_cast<unsigned int> (error->line), nullopt, nullopt});
                        }
                        catch (...) {
                            useThis->fCapturedException = current_exception ();
                        }
                        break;
                }
            }
        };
    };
}
 
namespace {
    // enable_shared_from_this is only to give each node a weak_ptr to its document (DocumentOf_, from the DocRep_* libxml2 keeps
    // in _private - a weak_ptr can be had from a raw pointer no other way): its DTOR check, so nothing without assertions
    struct DocRep_ final : ILibXML2DocRep
#if qStroika_Foundation_Debug_AssertionsChecked
        ,
                           enable_shared_from_this<DocRep_>
#endif
    {
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
        static inline atomic<unsigned int> sLiveCnt{0};
#endif
    public:
        DocRep_ (const shared_ptr<const void>& library, const Streams::InputStream::Ptr<byte>& in)
            : fLibrary_{library}
        {
            if (in == nullptr) {
                fLibRep_             = xmlNewDoc (BAD_CAST "1.0");
                fLibRep_->standalone = true;
            }
            else {
                xmlParserCtxtPtr ctxt = xmlCreatePushParserCtxt (nullptr, nullptr, nullptr, 0, "in-stream.xml" /*filename*/);
                Execution::ThrowIfNull (ctxt);
                // failing, the document it began is not kept: freed too (xmlFreeParserCtxt does not free its myDoc)
                [[maybe_unused]] auto&&              cleanup = Execution::Finally ([&] () noexcept {
                    if (fLibRep_ == nullptr and ctxt->myDoc != nullptr) {
                        xmlFreeDoc (ctxt->myDoc);
                    }
                    xmlFreeParserCtxt (ctxt);
                });
                MyLibXML2StructuredErrGrabber_       errCatcher{ctxt};
                Stroika_ATTRIBUTE_INDETERMINATE byte buf[1024];
                while (auto n = in.ReadBlocking (span{buf}).size ()) {
                    if (xmlParseChunk (ctxt, reinterpret_cast<char*> (buf), static_cast<int> (n), 0)) {
                        AssertNotNull (errCatcher.fCapturedException); // double check I understood API properly - and error handler getting called
                    }
                    errCatcher.ThrowIf ();
                }
                xmlParseChunk (ctxt, nullptr, 0, 1); // indicate the parsing is finished
                errCatcher.ThrowIf ();
                if (not ctxt->wellFormed) {
                    Execution::Throw (BadFormatException{"not well formed"sv}); // get good error message and throw that BadFormatException
                }
                fLibRep_ = ctxt->myDoc;
            }
            /*
             *  From https://opensource.apple.com/source/libxml2/libxml2-7/libxml2/doc/html/libxml-tree.html
             * 
             *              void *  _private    : For user data, libxml won't touch it (sometimes it says 'application data' - which is a bit less clear)
             */
            fLibRep_->_private = this;
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
            ++sLiveCnt;
#endif
        }
        DocRep_ (const DocRep_& from)
            : fLibrary_{from.fLibrary_}
        {
            fLibRep_ = xmlCopyDoc (from.fLibRep_, 1); // unclear if this does the right thing with the xmlns???? if any pointers to it??? --LGP 2024-02-04
            fLibRep_->_private = this;
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
            ++sLiveCnt;
#endif
        }
        DocRep_ (DocRep_&&)           = delete;
        DocRep_& operator= (DocRep_&) = delete;
        ~DocRep_ ()
        {
            AssertNotNull (fLibRep_);
            Assert (fLibRep_->_private == this);
            xmlFreeDoc (fLibRep_);
            for (auto i : fNSs2Free_) {
                xmlFreeNs (i);
            }
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
            Assert (sLiveCnt > 0);
            --sLiveCnt;
#endif
        }
        virtual xmlDoc* GetLibXMLDocRep () override
        {
            return fLibRep_;
        }
        virtual const Providers::IDOMProvider* GetProvider () const override
        {
            return &Providers::LibXML2::kDefaultProvider;
        }
        virtual bool GetStandalone () const override
        {
            return !!fLibRep_->standalone;
        }
        virtual void SetStandalone (bool standalone) override
        {
            fLibRep_->standalone = standalone;
        }
        virtual Element::Ptr ReplaceRootElement (const NameWithNamespace& newEltName, const optional<String>& namespacePrefix) override
        {
            // This API is very confusing. I could find no examples online, or clear documentation on how to handle
            // create a prefixed namespace and default namespace.
            // I only came upon this series of hacks after looking carefully at the code and alot of experimenting...
            //      --LGP 2024-02-29
            xmlNsPtr ns{nullptr};
            if (newEltName.fNamespace) {
                const string href = newEltName.fNamespace->As<String> (kUseURIEncodingFlag_).AsUTF8<string> ();
                // a prefix declares xmlns:PREFIX and the element is written with it; none declares the default namespace
                ns = namespacePrefix == nullopt
                         ? xmlNewNs (nullptr, BAD_CAST href.c_str (), nullptr)
                         : xmlNewNs (nullptr, BAD_CAST href.c_str (), BAD_CAST namespacePrefix->AsUTF8<string> ().c_str ());
            }
            xmlNodePtr n = xmlNewDocNode (fLibRep_, ns, BAD_CAST newEltName.fName.AsUTF8 ().c_str (), nullptr);
            Assert (n->nsDef == nullptr);
            if (newEltName.fNamespace) {
                n->nsDef = ns; // UGH - the declaration must hang on the element, prefixed or not, or nothing declares it
            }
            // the root it replaces comes back unlinked - so no longer freed with the document - and goes, as Replace's does
            if (xmlNodePtr oldRoot = xmlDocSetRootElement (fLibRep_, n)) {
                xmlFreeNode (oldRoot);
            }
            auto r = WrapLibXML2NodeInStroikaNode_ (n);
            Ensure (r.GetName () == newEltName);
            return r;
        }
        virtual void Write (const Streams::OutputStream::Ptr<byte>& to, const SerializationOptions& options) const override
        {
            TraceContextBumper ctx{"LibXML2::Doc::Write"};
            AssertNotNull (fLibRep_);
            xmlBufferPtr            xmlBuf          = xmlBufferCreate ();
            [[maybe_unused]] auto&& cleanup1        = Execution::Finally ([&] () noexcept { xmlBufferFree (xmlBuf); });
            constexpr char          kTxtEncoding_[] = "UTF-8";
            int                     useOptions      = XML_SAVE_AS_XML;
            if (options.fPrettyPrint) {
                useOptions |= XML_SAVE_FORMAT | XML_SAVE_WSNONSIG;
            }
            // use xmlSaveToBuffer instead of xmlDocDumpFormatMemoryEnc () since that has options to control XML_SAVE_NO_EMPTY which changed in libxml2 2.13.1
            xmlSaveCtxtPtr          saveCtx  = xmlSaveToBuffer (xmlBuf, kTxtEncoding_, useOptions);
            [[maybe_unused]] auto&& cleanup2 = Execution::Finally ([&] () noexcept { xmlSaveClose (saveCtx); });
#if LIBXML_VERSION >= 21400
            if (options.fPrettyPrint and options.fIndent) {
                (void)xmlSaveSetIndentString (saveCtx, string (*options.fIndent, ' ').c_str ()); // one it rejects (0, over 60) leaves its default
            }
#endif
            // could check for > 0 but bug in incomplete iml in current impl as libxml2 2.13.2
            if (xmlSaveDoc (saveCtx, fLibRep_) >= 0 and xmlSaveFlush (saveCtx) >= 0) {
                to.Write (span{reinterpret_cast<const byte*> (xmlBufferContent (xmlBuf)), static_cast<size_t> (xmlBufferLength (xmlBuf))});
            }
            else {
                Execution::Throw (Execution::Exception<runtime_error>{"failed dumping documented to text"});
                return;
            }
        }
        virtual Iterable<Node::Ptr> GetChildren () const override
        {
            AssertExternallySynchronizedChecker::ReadContext declareContext{fThisAssertExternallySynchronized_};
            return Traversal::CreateGenerator<Node::Ptr> ([curChild = fLibRep_->children] () mutable -> optional<Node::Ptr> {
                if (curChild == nullptr) {
                    return optional<Node::Ptr>{};
                }
                Node::Ptr r = WrapLibXML2NodeInStroikaNode_ (curChild);
                curChild    = curChild->next;
                return r;
            });
        }
        virtual void Validate (const Schema::Ptr& schema) const override
        {
            TraceContextBumper ctx{"LibXML2::Doc::Validate"};
            RequireNotNull (schema);
            Require (schema.GetRep ()->GetProvider () == &XML::Providers::LibXML2::kDefaultProvider);
            xmlSchema* libxml2Schema = dynamic_pointer_cast<ILibXML2SchemaRep> (schema.GetRep ())->GetSchemaLibRep ();
            RequireNotNull (libxml2Schema);
            xmlSchemaValidCtxtPtr   validateCtx = xmlSchemaNewValidCtxt (libxml2Schema);
            [[maybe_unused]] auto&& cleanup     = Execution::Finally ([&] () noexcept { xmlSchemaFreeValidCtxt (validateCtx); });
            SchemaErrors_           errors{.fWhatFailed = "Failed schema validation"_k};
            xmlSchemaSetValidStructuredErrors (validateCtx, &SchemaErrors_::Handler, &errors);
            if (xmlSchemaValidateDoc (validateCtx, fLibRep_) != 0) {
                Assert (not errors.fFirstError.empty ()); // guessing we only get validation error if error callback called?
                Execution::Throw (errors.AsException ());
            }
        }
        shared_ptr<const void> fLibrary_; // first, so destroyed last: libxml2 lasts while anything of it does
        xmlDoc*                fLibRep_{nullptr};
        xmlNs* fXmlnsNamespace2Use{nullptr}; // some APIs require this existing, but not sure where to put it??? and dont want to create a bunch of them... --LGP 2024-02-04
        list<xmlNsPtr> fNSs2Free_; // There probably is a better way with limxml2, but I cannot see how to avoid leaking these namespaces without this
        Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE Debug::AssertExternallySynchronizedChecker fThisAssertExternallySynchronized_;
    };
    DocRep_* GetWrapperDoc_ (xmlDoc* d)
    {
        RequireNotNull (d);
        DocRep_* wrapperDoc = reinterpret_cast<DocRep_*> (d->_private);
        Assert (wrapperDoc->fLibRep_ == d); // else grave disorder
        return wrapperDoc;
    }
#if qStroika_Foundation_Debug_AssertionsChecked
    // the document a node belongs to - empty if it has none, or none a shared_ptr owns yet (while one is being built)
    weak_ptr<Document::IRep> DocumentOf_ (xmlNode* n)
    {
        RequireNotNull (n);
        if (n->doc == nullptr or n->doc->_private == nullptr) {
            return {};
        }
        return GetWrapperDoc_ (n->doc)->weak_from_this ();
    }
#endif
    xmlNs* GetSharedReUsableXMLNSParentNamespace_ (xmlDoc* d)
    {
        auto wrapperDoc = GetWrapperDoc_ (d);
        if (wrapperDoc->fXmlnsNamespace2Use == nullptr) {
            // lazy create, since not always needed
            wrapperDoc->fXmlnsNamespace2Use =
                xmlNewNs (nullptr, BAD_CAST kXMLNS.fNamespace->As<String> (kUseURIEncodingFlag_).AsUTF8 ().c_str (), nullptr);
            wrapperDoc->fNSs2Free_.push_front (wrapperDoc->fXmlnsNamespace2Use);
        }
        return wrapperDoc->fXmlnsNamespace2Use;
    }
}
 
/*
 ********************************************************************************
 ******************* Provider::Xerces::libXMLString2String **********************
 ********************************************************************************
 */
String Providers::LibXML2::libXMLString2String (const xmlChar* s, int len)
{
    return String::FromUTF8 (span{reinterpret_cast<const char*> (s), static_cast<size_t> (len)});
}
String Providers::LibXML2::libXMLString2String (const xmlChar* t)
{
    return String::FromUTF8 (reinterpret_cast<const char*> (t));
}
 
/*
 ********************************************************************************
 ***************** Provider::Xerces::Providers::LibXML2::Provider ***************
 ********************************************************************************
 */
namespace {
    // libxml2 itself: the provider, and each schema and document it makes, hold one of these (as a shared_ptr<const void>), so
    // xmlCleanupParser runs once the last of them is gone, in whatever order they go
    struct Library_ {
        Library_ ()
        {
            LIBXML_TEST_VERSION;
        }
        Library_ (const Library_&) = delete;
        ~Library_ ()
        {
            TraceContextBumper ctx{"LibXML2::Library_::DTOR"};
#if qStroika_Foundation_DataExchange_XML_DebugMemoryAllocations
            Assert (SchemaRep_::sLiveCnt == 0); // each holds this, so none can be left
            Assert (DocRep_::sLiveCnt == 0);    // ""
#endif
            xmlCleanupParser ();
        }
    };
}
 
Providers::LibXML2::Provider::Provider ()
    : fLibrary_{MakeSharedPtr<Library_> ()}
{
    TraceContextBumper ctx{"LibXML2::Provider::CTOR"};
#if qStroika_Foundation_Debug_AssertionsChecked
    static unsigned int sNProvidersCreated_{0}; // don't create multiple of these - will lead to confusion
    Assert (++sNProvidersCreated_ == 1);
#endif
}
 
shared_ptr<Schema::IRep> Providers::LibXML2::Provider::SchemaFactory (const InputStream::Ptr<byte>& schemaData, const Resource::ResolverPtr& resolver) const
{
    return MakeSharedPtr<SchemaRep_> (fLibrary_, schemaData, resolver);
}
 
shared_ptr<DOM::Document::IRep> Providers::LibXML2::Provider::DocumentFactory (const Streams::InputStream::Ptr<byte>& in,
                                                                               const Schema::Ptr& schemaToValidateAgainstWhileReading) const
{
    auto r = MakeSharedPtr<DocRep_> (fLibrary_, in);
    if (schemaToValidateAgainstWhileReading != nullptr) {
        r->Validate (schemaToValidateAgainstWhileReading);
    }
    return r;
}
 
void Providers::LibXML2::Provider::SAXParse (const Streams::InputStream::Ptr<byte>& in, StructuredStreamEvents::IConsumer* callback,
                                             const Schema::Ptr& schema) const
{
    Streams::InputStream::Ptr<byte>   useInput = in;
    optional<Streams::SeekOffsetType> seek2;
    if (schema != nullptr and callback != nullptr) {
        // @todo --- at least for now this is needed - cuz we read twice - maybe can fix...
        useInput = Streams::ToSeekableInputStream::New (in);
        seek2    = useInput.GetOffset ();
    }
    if (schema != nullptr) {
        DocRep_ dr{fLibrary_, useInput};
        dr.Validate (schema);
    }
    if (callback != nullptr) {
        SAXReader_       handler{*callback};
        xmlParserCtxtPtr ctxt = xmlCreatePushParserCtxt (&handler.flibXMLSaxHndler_, &handler, nullptr, 0, nullptr);
        Execution::ThrowIfNull (ctxt);
        handler.fCtxt_                         = ctxt; // so a callback that throws can stop the parse (see SAXReader_::Invoke_)
        [[maybe_unused]] auto&&        cleanup = Execution::Finally ([&] () noexcept { xmlFreeParserCtxt (ctxt); });
        MyLibXML2StructuredErrGrabber_ errCatcher{ctxt};
        byte                           buf[1024];
        if (seek2) {
            useInput.Seek (*seek2);
        }
        while (auto n = useInput.ReadBlocking (span{buf}).size ()) {
            if (xmlParseChunk (ctxt, reinterpret_cast<char*> (buf), static_cast<int> (n), 0)) {
                // a consumer that threw stopped the parse itself, so its exception is the error - not whatever libxml2 made of being stopped
                handler.ThrowIfCapturedException ();
                AssertNotNull (errCatcher.fCapturedException); // double check I understood API properly - and error handler getting called
            }
            handler.ThrowIfCapturedException ();
            errCatcher.ThrowIf ();
        }
        xmlParseChunk (ctxt, nullptr, 0, 1);
        handler.ThrowIfCapturedException ();
        errCatcher.ThrowIf ();
    }
}