XML.h

/*
 
MIT License
 
Copyright (c) 2017 FMI Open Development / Markus Peura, first.last@fmi.fi
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
 
 */
/*
Part of Rack development has been done in the BALTRAD projects part-financed
by the European Union (European Regional Development Fund and European
Neighbourhood Partnership Instrument, Baltic Sea Region Programme 2007-2013)
 */
/*
 * TreeXML.h
 *
 *  Created on: Jun 24, 2012
 *      Author: mpeura
 */
 
 
 
#ifndef DRAIN_XML
#define DRAIN_XML
 
#include <ostream>
 
#include <drain/FlexibleVariable.h>
#include <drain/MapTools.h> // NEW
#include <drain/Sprinter.h>
#include <drain/StringTools.h>
 
#include "ClassXML.h"
#include "ReferenceMap.h"
#include "StyleXML.h"
 
namespace drain {
 
 
 
 
class XML :  protected std::map<std::string,FlexibleVariable> { // ReferenceMap2<FlexibleVariable> {
 
public:
 
    typedef int intval_t;
 
    // TODO:
    // static const intval_t flag_OPEN = 128;
    // static const intval_t flag_TEXT = 256;
 
    /*  "basetype" for COMMENTs and SCOPEs
     *  0 - XML
     *  1 - Style and C/C++
     *  2 - parentheses
     *  3 - braces
     */
protected:
    static const intval_t XML_LIKE = 0;
    static const intval_t CURLY       = 1; // || flag_TEXT
    static const intval_t PARENTHESES = 2; // || flag_TEXT
    static const intval_t BRACES      = 3; // || flag_EXPLICIT || flag_TEXT
 
 
public:
 
    static const intval_t UNDEFINED = 0;
    static const intval_t COMMENT   = 1; // || flag_TEXT
    static const intval_t CTEXT     = 2; // || flag_TEXT
    static const intval_t SCRIPT    = 3; // || flag_EXPLICIT || flag_TEXT
    static const intval_t STYLE     = 4; // || flag_EXPLICIT
    static const intval_t STYLE_SELECT = 5;
    static const intval_t JAVASCRIPT       = 6; // future extension
    static const intval_t SCOPE = 8;       // future extension
    static const intval_t SCOPE_CURLY = SCOPE|CURLY ; // JavaScript,
    static const intval_t XMLBASE = 10; // for debugging basic XML doc
 
    typedef std::map<std::string,FlexibleVariable> map_t;
 
protected:
 
    static
    const StyleXML curlyStyleXML;
 
    static const std::string SCOPE_BEGIN;
    static const std::string SCOPE_END;
    static const std::string COMMENT_BEGIN;
    static const std::string COMMENT_END;
 
public:
 
    map_t & getMap(){
        return *this;
    }
 
    const map_t & getMap() const {
        return *this;
    }
 
 
    enum entity_t {
        AMPERSAND = '&',
        LESS_THAN = '<',
        EQUAL_TO  = '=',
        GREATER_THAN = '>',
        NONBREAKABLE_SPACE = ' ',
        QUOTE = '"',
        CURLY_LEFT  = '{',
        CURLY_RIGHT = '}',
        // ---
        TAB = '\t',
        NEWLINE = '\n',
        // ---
        DEGREE = 176,
    };
 
    static
    const std::string USER_ATTR_PREFIX;
 
    /* Variants of entity map */
 
    static
    const std::map<char,std::string> & getKeyConversionMap();
 
    static
    const std::map<char,std::string> & getAttributeConversionMap();
 
    static
    const std::map<char,std::string> & getCTextConversionMap();
 
 
    inline
    XML(){};
 
    // TODO: CHECK: base std::map<std::string,FlexibleVariable> (the attribute map) is explicitly
    // default-constructed (empty) here, same as before, and the empty body means copying an XML
    // object silently drops all its attributes. See also the "RISKY!?" note in NodeXML's copy
    // constructor in TreeXML.h, which relies on this. Confirm intentional.
    inline
    XML(const XML &) : std::map<std::string,FlexibleVariable>(){
    };
 
    virtual inline
    ~XML(){};
 
    virtual
    const std::string & getTag() const = 0;
 
 
    // Could be also internal, and only NodeXML<> declares this interface.
    template <class T> // "final"
    inline
    void setType(const T &t){ // DANGER, without cast?
        setType(static_cast<intval_t>(t));
    }
 
 
    void setType(intval_t t);
 
    inline
    const intval_t & getType() const {
        return type;
    };
 
 
    inline
    bool typeIsSet() const {
        return type != UNDEFINED;
    };
 
 
    template <class T2, class ...T3>
    inline
    bool typeIs(const T2 & arg, const T3... args) const {
        if (type == static_cast<intval_t>(arg)){
            return true;
        }
        else {
            return typeIs(args...);
        }
    }
 
 
 
    std::string ctext;
 
    // Could be templated, behind Static?
    static int nextID;
 
    static inline
    int getCount(){
        return nextID;
    }
 
    static inline
    int getNewIndex(){
        return ++nextID;
    }
 
 
    inline
    const std::string & setId(){
        if (id.empty()){
            id=drain::StringBuilder<>(getTag(), ++nextID);
        }
        getMap()["id"].link(id);
        return id;
    }
 
    inline
    const std::string & setId(const std::string & s){
        getMap()["id"].link(id=s);
        return id;
    }
 
    template <char C='\0', typename ...TT>
    inline
    const std::string & setId(const TT & ...args) {
        getMap()["id"].link(id=drain::StringBuilder<C>(args...));
        return id;
    }
 
    inline
    const std::string & getId() const {
        return id;
    }
 
    inline
    bool isUndefined() const {
        return type == UNDEFINED;
    }
 
    inline
    bool isComment() const {
        return type == COMMENT;
    }
 
    inline
    bool isCText() const {
        return type == CTEXT;
    }
 
    inline
    bool isStyle() const {
        return type == STYLE;
    }
 
    /* HTML Only
    inline
    bool isLink() const {
        return type == LINK;
    }
    */
 
    inline
    bool isScript() const {
        return type == SCRIPT;
    }
 
    inline
    bool isScopePlain() const {
        return type == SCOPE;
    }
 
    inline
    bool isScopeJS() const {
        return type == SCOPE_CURLY;
    }
 
    inline
    bool isScope() const {
        return isScopePlain() || isScopeJS();
    }
 
 
    virtual
    bool isSingular() const;
 
    virtual
    bool isExplicit() const;
 
 
    void reset();
    virtual
    void swapXML(XML & node);
 
 
    template <class ...T>
    inline
    void setComment(const T & ...args) {
        this->reset();
        //this->clear(); // what if also uncommenting needed?
        type = COMMENT;
        setText(args...);
    }
 
    template <class ...T>
    inline
    void setCommentSafe(const T & ...args) {
        this->reset();
        //this->clear(); // what if also uncommenting needed?
        type = COMMENT;
        setTextSafe(args...);
    }
 
 
    virtual // redef shows variadic args, below?
    void setText(const std::string & s);
 
    template <class ...T>
    void setText(const T & ...args) {
        setText(StringBuilder<>(args...).str()); // str() to avoid infinite loop
    }
 
 
    template <class ...T>
    void setTextSafe(const T & ...args) {
        std::string dst;
        StringTools::replace(StringBuilder<>(args...).str(), getCTextConversionMap(), dst); // str() to avoid infinite loop
        setText(dst);
        //setText(StringTools::replace(m, StringBuilder<>(args...).str(), ctext)); // str() to avoid infinite loop
    }
 
 
    template <class ...T>
    inline
    void setProgramComment(const T & ...args) {
        setText('/', '*', ' ', args..., ' ', '*', '/');
    }
 
 
    virtual inline
    const std::string & getText() const {
        return ctext;
    }
 
    inline
    const std::string & getUrl(){
        return url;
    }
 
    virtual inline
    void setUrl(const std::string & s){
        url = s;
        if (isScript()){
            getMap()["url"].link(url);
            //  link("url", url);
        }
    }
 
    template <class ...T>
    inline
    void setName(const T & ...args){
        setAttribute("data-name", drain::StringBuilder<>(args...).str());
    }
 
    inline
    const FlexibleVariable & getName() const {
        return MapTools::get(getMap(), std::string("data-name"));
        // return (*this)["data-name"];
    }
 
 
    // ---------------- Attributes ---------------
 
    virtual inline // shadows - consider virtual
    bool empty() const {
        return map_t::empty();
    }
 
    inline
    bool hasAttribute(const std::string & key){
        return MapTools::hasKey(getMap(), key);
    };
 
    inline
    bool hasUserAttribute(const std::string & key){
        return MapTools::hasKey(getMap(), USER_ATTR_PREFIX+key);
    };
 
    inline
    const map_t & getAttributes() const {
        return *this;
    };
 
    // Maybe controversial. Helps importing sets of variables.
    inline
    map_t & getAttributes(){
        return *this;
    };
 
    // Rename getAttribute?
    inline
    const drain::FlexibleVariable & getAttribute(const std::string & key) const {
        return MapTools::get(getMap(), key);
        //return (*this)[key];
    }
 
    // Rename getAttribute?
    inline
    drain::FlexibleVariable & getAttribute(const std::string & key){
        return MapTools::get(getMap(), key);
        // return (*this)[key];
    }
 
 
    // Rename getAttribute?
    template <class V>
    inline
    V getAttribute(const std::string & key, const V & defaultValue) const {
        return MapTools::get(getMap(), key, defaultValue);
        //return map_t::get(key, defaultValue);
    }
 
    // Rename getAttribute?
    inline
    std::string getAttribute(const std::string & key, const char * defaultValue) const {
        return MapTools::get(getMap(), key, defaultValue);
        //return map_t::get(key, defaultValue);
    }
 
    inline
    const drain::FlexibleVariable & getUserAttribute(const std::string & key) const {
        return getAttribute(USER_ATTR_PREFIX+key);
    }
 
    inline
    drain::FlexibleVariable & getUserAttribute(const std::string & key){
        return getAttribute(USER_ATTR_PREFIX+key);
    }
 
    template <class V>
    inline
    V getUserAttribute(const std::string & key, const V & defaultValue) const {
        return getAttribute(USER_ATTR_PREFIX+key, defaultValue);
    }
 
    inline
    std::string getUserAttribute(const std::string & key, const char *defaultValue) const {
        return getAttribute(USER_ATTR_PREFIX+key, defaultValue);
    }
 
    //   But otherways confusing?
    virtual inline
    void setAttribute(const std::string & key, const std::string &value){
        (*this)[key] = value;
    }
 
    //   But otherways confusing?
    virtual inline
    void setAttribute(const std::string & key, const char *value){
        (*this)[key] = value; // -> handleString()
    }
 
    /*
    template <class V>
    inline
    void setAttribute(const std::string & key, const V & value){
        (*this)[key] = value; // -> handleString()
    }
    */
 
    template <class ... TT>
    inline
    void setAttribute(const std::string & key, const TT &... args){
        (*this)[key] = StringBuilder<>(args...).str();
    }
 
    template <class ... TT>
    inline
    void setUserAttribute(const std::string & key, const TT &... args){
        setAttribute(USER_ATTR_PREFIX+key, args...);
    }
 
 
    inline
    void removeAttribute(const std::string & s){
        iterator it = this->find(s);
        if (it != this->end()){
            this->erase(it);
        }
    }
 
 
 
protected:
 
    inline
    bool typeIs() const {
        return false;
    };
 
    intval_t type = XML::UNDEFINED;
 
    // String, still easily allowing numbers through set("id", ...)
    std::string id;
    // Consider either/or
    std::string url;
 
    virtual inline
    void handleType(){}; // = 0;
 
 
public:
 
    // ------------------ Style ---------------
 
protected:
 
    StyleXML style;
 
public:
 
    inline
    const StyleXML & getStyle() const {
        return style;
    }
 
    Variable & getStyle(const std::string & key){
        return style[key];
    }
 
    /*
    const Variable & getStyle(const std::string & key) const {
        return style[key];
    }
    */
 
    template <class T>
    T getStyle(const std::string & key, const T & defaultValue) const {
        return MapTools::get(style, key, defaultValue);
        // return style[value];
    }
 
 
    inline
    void setStyle(const StyleXML & s){
        style.clear();
        MapTools::setValues(style, s);
    }
 
    void setStyle(const std::string & value){
        drain::Logger mout(__FILE__, __FUNCTION__);
        if (type == UNDEFINED){
            mout.reject<LOG_WARNING>("setting style for UNDEFINED elem: ", value);
            mout.unimplemented<LOG_WARNING>("future option: set type to STYLE_SELECT");
        }
        else if (type == STYLE){
            mout.reject<LOG_WARNING>("not setting style for STYLE elem: ", value); // , *this);
        }
        else {
            MapTools::setValues(style, value, ';', ':', "; \t\n"); // sep, equal, trim (also ';' ?)
        }
    }
 
    inline
    void setStyle(const char *value){
        setStyle(std::string(value));
    }
 
    inline
    void setStyle(const std::string & key, const std::string & value){
        drain::Logger mout(__FILE__, __FUNCTION__);
        if (type == UNDEFINED){
            mout.reject<LOG_WARNING>("setting style for UNDEFINED elem: ", key, '=', value);
            mout.unimplemented<LOG_WARNING>("future option: set type to STYLE_SELECT");
        }
        else if (type == STYLE){
            mout.reject<LOG_WARNING>("not setting style for STYLE elem: ", value); // , *this);
        }
        else {
            this->style[key] = value;
        }
    }
 
 
 
    template <class V>
    inline
    void setStyle(const std::string & key, const std::initializer_list<V> &l){
        // const std::initializer_list<Variable::init_pair_t > &l
        if (type == STYLE){  // typeIs(STYLE) fails
            drain::Logger mout(__FILE__, __FUNCTION__);
            mout.warn("Setting style of STYLE?  initializer_list<", drain::TypeName<V>::str(), "> = ", sprinter(l)); // , StyleXML::styleLineLayout ?
        }
        this->style[key] = l;
    }
 
 
 
 
    template <class ... TT>
    inline
    void setStyle(const std::string & key, const TT &... args){
 
        if (type == STYLE){
            drain::Logger(__FILE__, __FUNCTION__).reject<LOG_WARNING>("Setting style of STYLE: ", key, "=", args...);
        }
        else {
            // In a variable map
            this->style[key] = StringBuilder<>(args...).str();
        }
    }
 
    inline
    void setStyle(const std::initializer_list<std::pair<const char *,const drain::Variable> > &args){
        //drain::SmartMapTools::setValues(style, args);
        drain::MapTools::setValues(style, args);
    }
 
    template <class V>
    void setStyle(const std::map<std::string, V> & args){
        drain::MapTools::setValues(style, args);
    }
 
 
 
protected:
 
    // ------------------ Style Class ---------------
 
    ClassListXML classList;
 
public:
 
    const ClassListXML & getClasses() const {
        return classList;
    }
 
    template <typename ... TT>
    inline
    void addClass(const TT &... args) {
        classList.add(args...);
    }
 
    inline
    void addClass(const ClassListXML & clist) {
        for (auto & cls: clist){
            addClass(cls);
        }
    }
 
    template <class V>
    inline
    bool hasClass(const V & cls) const {
        return classList.has(cls);
    }
 
 
    template <class V>
    inline
    void removeClass(const V & cls) {
        classList.remove(cls);
    }
 
    inline
    void clearClasses(){
        classList.clear();
    }
 
 
    virtual
    void specificAttributesToStream(std::ostream & ostr) const;
 
 
    enum tag_display_mode {
        FLEXIBLE_TAG = 0,  // <TAG>...</TAG> or <TAG/>
        OPENING_TAG= 1,   // <TAG>
        CLOSING_TAG = 2,   // </TAG>
        EMPTY_TAG = OPENING_TAG | CLOSING_TAG,  // element has no descendants:  <hr/>
        NON_EMPTY_TAG, // opening and closing tags must appear, even when empty: <script></script>
        NO_TAG, // New, for CTEXT
    };
 
 
    virtual
    std::ostream & nodeToStream(std::ostream & ostr, tag_display_mode mode=EMPTY_TAG) const = 0;
 
 
    /*
    template <class TR>
    static
    std::ostream & toStream(std::ostream & ostr, const TR & tree, const std::string & defaultTag="ELEM", int indent=0);
    */
 
    // , const std::string & defaultTag="ELEM" UnorderedMultiTree<N>
    template <class N>
    static
    std::ostream & toStream(std::ostream & ostr, const UnorderedMultiTree<N> & tree, int indent=0);
 
    template <class N>
    static
    std::ostream & styleToStream(std::ostream & ostr, const UnorderedMultiTree<N> & tree, int indent=0);
 
    template <class N>
    static
    std::ostream & textToStream(std::ostream & ostr, const UnorderedMultiTree<N> & tree, int indent=0);
 
 
 
    static
    const std::map<char,std::string> & getEntityMap();
 
 
    // core utility (not to be external)
    template <class V>
    static inline
    void xmlAttribToStream(std::ostream &ostr, const std::string & key, const V &value){
        //StringTools::replace(XML::encodingMap, data.ctext, ostr);
        //ostr << ' ' << key << '=' << '"' << value << '"'; // << ' ';
 
        static const std::map<char,char> keyMap = {
                {' ','_'},
                {'"','_'},
                {'=','_'},
        };
        ostr << ' ';
        StringTools::replace(key, keyMap, ostr); // XML::encodingMap
        //StringTools::replace(getEntityMap(), key, ostr); // XML::encodingMap
 
        static const std::map<char,std::string> valueMap = {
                {entity_t::QUOTE, "'"},
                {entity_t::LESS_THAN,"(("},
                {entity_t::GREATER_THAN,"))"},
        };
        ostr << '=' << '"';
        StringTools::replace(value, valueMap, ostr); // XML::encodingMap
        //StringTools::replace(getEntityMap(), value, ostr); // XML::encodingMap
        ostr << '"';
        //<< key << '=' << '"' << value << '"'; // << ' ';
    }
 
 
 
    template <typename N>
    static inline
    N & xmlAssignNode(N & dst, const N & src){
 
        if (&src != &dst){
            //dst.clear(); // clear attributes,
            //if (!dst.typeIs(src.getNativeType())){
            if (dst.getType() != src.getType()){
                dst.reset(); // clear attributes, style, cstring and type.
                // Warning: does not create links.
                dst.setType(src.getType());
            }
            // dst.getAttributes().importMap(src.getAttributes());
            MapTools::setValues(dst.getAttributes(), src.getAttributes());
            dst.setStyle(src.getStyle());
            // dst.setText(src.ctext); // wrong! set type to CTEXT
            dst.ctext = src.ctext;
        }
 
        return dst;
    }
 
 
 
    /*
    UNUSED!
    template <typename T>
    static
    T & xmlGuessType(const typename T::node_data_t & parentNode, T & child){
        typedef typename T::node_data_t::xml_default_elem_map_t map_t;
        const typename map_t::const_iterator it = T::node_data_t::xml_default_elems.find(parentNode.getNativeType());
        if (it != T::node_data_t::xml_default_elems.end()){
            child->setType(it->second);
            drain::Logger(__FILE__, __FUNCTION__).experimental<LOG_WARNING>("Default type set: ", child->getTag());
        }
        return child;
    }
    */
 
 
 
};
 
 
// template <> const drain::Enum<XML::entity_t>::dict_t drain::Enum<XML::entity_t>::dict;
DRAIN_ENUM_DICT(XML::entity_t);
DRAIN_ENUM_OSTREAM(XML::entity_t)
 
template <class N>
std::ostream & XML::textToStream(std::ostream & ostr, const UnorderedMultiTree<N> & tree, int indent){
 
    drain::Logger mout(__FILE__,__FUNCTION__);
 
    std::string fill(2*indent, ' ');
 
    typedef UnorderedMultiTree<N> TR;
    const typename TR::node_data_t & data = tree.data;
 
    char sep = 0;
 
    // if (!data.ctext.empty()){
    ostr << fill << data.ctext;
    // }
 
    if (data.isScopeJS()){
        ostr << "{";
        if (tree.hasChildren()){
            ostr << '\n';
        }
        sep = '\n';
    }
 
    if (indent > 0){
        indent += 2;
    }
 
    for (const auto & entry: tree.getChildren()){
        textToStream(ostr, entry.second, indent);
        if (sep){
            ostr << sep;
        }
 
    }
 
    if (data.isScopeJS()){
        ostr << fill << "}"; // Note: semicolon not supported at end of argument, consider: .forEach( elem => {});
    }
 
    return ostr;
}
 
 
template <class N>
std::ostream & XML::styleToStream(std::ostream & ostr, const UnorderedMultiTree<N> & tree, int indent){
 
    drain::Logger mout(__FILE__,__FUNCTION__);
 
    std::string fill(2*indent, ' ');
 
    typedef UnorderedMultiTree<N> TR;
    const typename TR::node_data_t & data = tree.data;
 
    if (!data.ctext.empty()){
        // TODO: indent
        ostr << fill << data.ctext;
        StyleXML::commentToStream(ostr, " TEXT ");
        ostr << '\n';
    }
 
    if (!data.getAttributes().empty()){
        mout.warn("STYLE elem ", data.getId()," contains attributes, probably meant as style: ", sprinter(data.getAttributes()));
        ostr << "\n\t /" << "* <!-- DISCARDED attribs ";
        Sprinter::toStream(ostr, data.getAttributes()); //, StyleXML::styleRecordLayout
        ostr << " /--> *" << "/" << '\n';
    }
 
    if (!data.style.empty()){
        ostr << fill;
        StyleXML::commentToStream(ostr, "STYLE OBJ");
        ostr << '\n';
        for (const auto & attr: data.style){
            ostr << fill << "  ";
            Sprinter::pairToStream(ostr, attr, StyleXML::styleRecordLayout); // {" :;"}
            //attr.first << ':' attr.first << ':';
            ostr << '\n';
        }
        // ostr << fill << "}\n";
        // Sprinter::sequenceToStream(ostr, entry.second->getAttributes(), StyleXML::styleRecordLayoutActual);
        // ostr << '\n';
    }
    ostr << '\n';
 
    ostr << fill;
    StyleXML::commentToStream(ostr, "style ELEMS");
    ostr << '\n';
 
    for (const auto & entry: tree.getChildren()){
 
        if (entry.second->isComment()){
            // StringTools::replace();
            ostr << fill << "/* "<< entry.second->ctext << " */" << '\n';
            // XML::toStream(ostr, entry.second, defaultTag, indent); // indent not used?
            continue;
        }
 
        if (!entry.second->ctext.empty()){
            //ostr << fill << "<!-- elem("<< entry.first << ") ctext /-->" << '\n';
            ostr << fill << "  " << entry.first << " {" << entry.second->ctext << "} /* CTEXT */ \n";
        }
 
        if (!entry.second->getAttributes().empty()){
            ostr << fill << "  " << entry.first << " {\n";
            for (const auto & attr: entry.second->getAttributes()){
                ostr << fill  << "    ";
                if (attr.first == "id"){
                    StyleXML::commentToStream(ostr, "id=", attr.second);
                    // mout.suspicious("Style elem has id (", attr.second, ")");
                }
                else {
                    ostr << attr.first << ':' << attr.second << ';';
                }
                ostr << '\n';
            }
            ostr << fill << "  }\n";
            ostr << '\n';
        }
 
    }
    ostr << "\n"; // end CTEXT
    // ostr << " ]]>\n"; // end CTEXT
    // end STYLE defs
    ostr << fill;
 
    return ostr;
}
 
// drain::UnorderedMultiTree<NodeSVG,false, NodeXML<>::path_t> TreeSVG;
// , const std::string & defaultTag
// template <class TR>
template <class N>
std::ostream & XML::toStream(std::ostream & ostr, const UnorderedMultiTree<N> & tree, int indent){
 
    drain::Logger mout(__FILE__,__FUNCTION__);
 
    typedef UnorderedMultiTree<N> TR;
 
    const typename TR::container_t & children = tree.getChildren();
 
    // const XML & data = tree.data; // template type forcing, keep here for programming aid.
    const typename TR::node_data_t & data = tree.data; // template used
 
    tag_display_mode mode = EMPTY_TAG;
 
    if (data.isCText()){ // this can be true only at root, and rarely so...? (because recursive call not reached, if ctext)
        textToStream(ostr, tree, indent);
        return ostr;
    }
    else if (data.isScopeJS()){ // this can be true only at root, and rarely so...? (because recursive call not reached, if ctext)
        // ostr << '{';
        textToStream(ostr, tree, indent);
        // ostr << '}' << ';' << '\n';
        return ostr;
    }
    else if (data.isCText()){ // this can be true only at root, and rarely so...? (because recursive call not reached, if ctext)
        // data.nodeToStream(ostr, mode);
        // ostr << "<!--TX-->";
        // NEW
        mode = NO_TAG;
        // return ostr;
    }
    else {
        if (!data.ctext.empty()){
            // mout.warn("Non-CTEXT-elem with ctext: <", data.getTag(), " id='", data.getId(), "' ...>, text='", data.ctext, "'");
            if (data.isSingular()){
                // mout.warn("Skipping CTEXT of a singular element <", tree->getTag(), " id='", data.getId(), "' ...> , CTEXT: '", data.ctext, "'");
                mode = EMPTY_TAG;
            }
            else {
                mode = OPENING_TAG;
            }
        }
 
        if (!children.empty()){
            mode = OPENING_TAG;
            if (data.isSingular()){
                mout.warn("Singular (hence normally empty) element <", tree->getTag(), " id='", data.getId(), "' ...> has ", children.size(), " children?");
            }
        }
 
        // mout.attention("Hey! ", TypeName<TR>::str(), " with ", TypeName<typename TR::node_data_t>::str(), "Explicit ", data.isExplicit(), " or implicit ", data.isSingular());
        if (data.isExplicit()){ // explicit
            mode = OPENING_TAG;
        }
        else if (data.isSingular()){ // <br/> <hr/>
            mode = EMPTY_TAG;
        }
 
        // Hence, is flexible, "bimodal", supports empty and open-close mode.
 
    }
 
 
 
    // Indent
    std::string fill(2*indent, ' ');
    if (!data.isScopeJS()){
        ostr << fill;
    }
 
 
    // Print opening tag and attributes.
    // NEW: js scope print also its CTEXT
    data.nodeToStream(ostr, mode);
 
    // Note: if tree has attributes, empty() == false.
    //if (data.isScript() && !(tree.empty() && data.ctext.empty())){ // (mode==OPENING_TAG)
    const bool SCRIPT_NONEMPTY = data.isScript() && (tree.hasChildren() || !data.ctext.empty());
    //if (data.isScript() && (tree.hasChildren() || !data.ctext.empty())){
    if (SCRIPT_NONEMPTY){
        //std::string fill(2*indent, ' ');
        ostr << "//<![CDATA[\n";
    }
 
    // TODO: consider unintended, "packed" class for TSPAN etc.
 
    if (mode == EMPTY_TAG){
        // ostr << "<!--ET-->";
        // if (!SCRIPT_NONEMPTY){
        ostr << '\n';
        // }
        return ostr;
    }
    else if (data.isStyle()){
 
        styleToStream(ostr, tree, indent);
 
        // https://www.w3.org/TR/xml/#sec-cdata-sect
        // ostr << "<![CDATA[ \n";
        // ostr << "<!-- STYLE -->"; WRONG!
        /*
        if (!data.ctext.empty()){
            // TODO: indent
            ostr << fill << data.ctext;
            StyleXML::commentToStream(ostr, " TEXT ");
            ostr << '\n';
        }
 
        if (!data.getAttributes().empty()){
            mout.warn("STYLE elem ", data.getId()," contains attributes, probably meant as style: ", sprinter(data.getAttributes()));
            ostr << "\n\t /" << "* <!-- DISCARDED attribs ";
            Sprinter::toStream(ostr, data.getAttributes()); //, StyleXML::styleRecordLayout
            ostr << " /--> *" << "/" << '\n';
        }
 
        if (!data.style.empty()){
            ostr << fill;
            StyleXML::commentToStream(ostr, "STYLE OBJ");
            ostr << '\n';
            for (const auto & attr: data.style){
                ostr << fill << "  ";
                Sprinter::pairToStream(ostr, attr, StyleXML::styleRecordLayout); // {" :;"}
                //attr.first << ':' attr.first << ':';
                ostr << '\n';
            }
            // ostr << fill << "}\n";
            // Sprinter::sequenceToStream(ostr, entry.second->getAttributes(), StyleXML::styleRecordLayoutActual);
            // ostr << '\n';
        }
        ostr << '\n';
 
        ostr << fill;
        StyleXML::commentToStream(ostr, "style ELEMS");
        ostr << '\n';
 
        for (const auto & entry: tree.getChildren()){
 
            if (entry.second->isComment()){
                // StringTools::replace();
                ostr << fill << "/ * "<< entry.second->ctext << " * /" << '\n';
                // XML::toStream(ostr, entry.second, defaultTag, indent); // indent not used?
                continue;
            }
 
            if (!entry.second->ctext.empty()){
                //ostr << fill << "<!-- elem("<< entry.first << ") ctext /-->" << '\n';
                ostr << fill << "  " << entry.first << " {" << entry.second->ctext << "} / * CTEXT * / \n";
            }
 
            if (!entry.second->getAttributes().empty()){
                ostr << fill << "  " << entry.first << " {\n";
                for (const auto & attr: entry.second->getAttributes()){
                    ostr << fill  << "    ";
                    if (attr.first == "id"){
                        StyleXML::commentToStream(ostr, "id=", attr.second);
                        // mout.suspicious("Style elem has id (", attr.second, ")");
                    }
                    else {
                        ostr << attr.first << ':' << attr.second << ';';
                    }
                    ostr << '\n';
                }
                ostr << fill << "  }\n";
                ostr << '\n';
            }
 
        }
        ostr << "\n"; // end CTEXT
        // ostr << " ]]>\n"; // end CTEXT
        // end STYLE defs
        ostr << fill;
         */
    }
    else {
 
        // Elements "own" CTEXT will be always output first -> check for problems, if other elements added first.
        // ostr << data.ctext;
        /*
        if (data.isScript()){
            ostr << data.ctext; // let < and > pass through
        }
        else {
            ostr << data.ctext; // let < and > pass through
            // StringTools::replace(XML::encodingMap, data.ctext, ostr); // sometimes an issue? // any time issue?
        }
        */
 
        /*
        if (!data.isCText()){
            ostr << data.ctext;
        }
        */
 
        ostr << data.ctext;
        /*
        if (!data.isScopeJS()){
            if (!data.ctext.empty()){
                //ostr << data.ctext << '\n'; // newline nice in scripts, but else where?
            }
        }
        */
 
        // Detect if all the children are of type CTEXT, to be rendered in a single line.
        // Note: potential re-parsing will probably detect them as a single CTEXT element.
        bool ALL_CTEXT = true; // (!data.ctext.empty()) || !children.empty();
 
        for (const auto & entry: children){
            // New: if CTEXT has children, ensure recursion by skipping ALL_TEXT handler
            if (entry.second.hasChildren() || !entry.second->isCText()){
                ALL_CTEXT = false;
                break;
            }
        }
 
        if (ALL_CTEXT){
            // ostr << "<!--ALL_CTEXT-->";
            char sep=0;
            for (const auto & entry: children){
                if (sep){
                    ostr << sep;
                }
                else {
                    sep = ' '; // consider global setting?
                }
 
                if (data.isScript()){
                    // Unfiltered
                    ostr << entry.second->getText();
                }
                else {
                    StringTools::replace(entry.second->getText(), getEntityMap(), ostr); // any time issue?
                }
 
            }
        }
        else {
            //ostr << "<!-- RECURSION -->";
            if (!data.isScopeJS()){
                ostr << '\n';
            }
            for (const auto & entry: children){
                //toStream(ostr, entry.second, entry.first, indent+1); // Notice, no ++indent
                toStream(ostr, entry.second, indent+1); // Notice, no ++indent
                // "implicit" newline
            }
            ostr << fill; //  for CLOSING tag
        }
 
        if (data.isCText())
            return ostr;
    }
 
    // ostr << "<!-- END "<< data.getId() << ' ' << data.getTag() << '(' << data.getType() << ')' << "-->";
    // Note: if tree has attributes, empty() == false.
    // Write terminting escape sequence only if there was some content
    if (SCRIPT_NONEMPTY){
        // if (data.isScript() && (tree.hasChildren() || !data.ctext.empty())){
        // if (data.isScript() && !(tree.empty() && data.ctext.empty())){
        ostr << '\n';
        std::string fill(2*indent, ' ');
        ostr << "//]]>";
    }
 
 
    data.nodeToStream(ostr, CLOSING_TAG);
    // if (!data.isScopeJS()){
    ostr << '\n';  // Always after closing tag!
    //}
 
 
    return ostr;
}
 
#define DRAIN_XML_NODE_SWAP(tree_t) template <> inline void tree_t::swapData(tree_t::node_data_t & node){ this->data.swapXML(node); }
 
 
}  // drain::
 
#endif /* DRAIN_XML */