ERAV.cpp

Go to the documentation of this file.

// ERAV.cpp         (C) 2010 adolfo@di-mare.com

#include "ERAV.h"

//* DELETE */ extern void dump_tuples( const std::list<ERAV::tuple>& L );
//* DELETE */ #include <iostream>

/// all : head docs;
void ERAV::parser::all() {
    head();
    docs();
}

/// head : "<?" "xml" args "?>" | /* empty */;
void ERAV::parser::head() {
    if ( *m_lookahead==token::LTQ ) { // "<?"
        match( token::LTQ );
            {{ pushContext(); }} // args() needs it
            {{ if ( m_lookahead->lexeme() != "xml") error( "Invalid XML header line" ); }}
        match( token::ID ); // ID == "xml"
        args();
        match( token::QGT );
            {{ popContext(); }}
    }
    else { /* empty */ }
}

/// docs : doc docs | /* empty */;
void ERAV::parser::docs() {
    if ( *m_lookahead=='<' ) {
        doc();
        docs();
    }
    else { /* empty */ }
}

/// doc : '<' ID args nest;
void ERAV::parser::doc() {
    std::string ID_val;
    if ( *m_lookahead=='<' ) {
        match( '<' );
            {{ ID_val = m_lookahead->lexeme(); }}
            {{ pushContext(); }}   {{ ;;;;;;;; }}
        match( token::ID );
        args();
        nest(ID_val);
    }
    else { error( "Missing '<' in XML document" ); }
}

/// nest : "/>" | '>' docs "</" ID "/>";
void ERAV::parser::nest(const std::string& lexeme) {
    std::string ID_val;
    if ( *m_lookahead==token::SGT ) {
        match( token::SGT ); // "/>"
            {{ emit(); }}
    }
    else if ( *m_lookahead=='>' ) {
        match( '>' );
            {{ emit(); }}
        docs();
        match( token::LTS ); // "</"
            {{ m_tag  = m_lookahead->getTag(); }}
            {{ popContext();  }}   {{ ;;;;;;;; }}
            {{ ID_val = m_lookahead->lexeme(); }}
        match( token::ID );
            {{ if ( ID_val != lexeme ) { error( "Non matching XML tag" ); } }}
        match( '>' );
    }
    else { error( "Not well formed XML document" ); }
}

/// args : arg args | /* empty */;
void ERAV::parser::args() {
    if ( *m_lookahead==token::ID ) {
        arg();
        args();
    }
    else { /* empty */ }
}

/// arg : ID '=' STRING;
void ERAV::parser::arg() {
        {{ setAttrib(); }}
    match( token::ID );
    if ( *m_lookahead=='=' ) {
        match( '=' );
            {{ setAttribVal(); }}
        match( token::STRING );
    }
    else { error( "Missing '=' in XML argument" ); }
}

void ERAV::parser::emit() {
    if ( (m_context==0) && (m_tag!=tag::descr) ) {
        return;
    }
    ERAV::tuple TUPLE;
    switch ( m_tag ) {
        case tag::attrib:
            TUPLE.ID_ENT = m_id;
            if ( m_context==0 ) {
                error( "<attrib> tag with no <record> context" );
            }
            else {
                TUPLE.REL.ID   =   m_context->REL_ID;
                TUPLE.REL.SUB  = ( m_context->prev == 0 ? 0 : m_context->prev->REL_ID );
            }
            TUPLE.REL.TYPE = m_rel_type;
            TUPLE.ATTRIB   = m_attrib_ref;
            TUPLE.VAL.BLOB = this->m_str_val;
            if (m_L!=0) { m_L->push_back( TUPLE ); }
            break;
        case tag::descr: {
                ERAV::WORD * p = ( m_inWord ? m_WORD : m_STRING );
                if ( p!=0 ) {
                    p->update( m_id_word , m_lang , m_str_val );
                }
            }
            break;
        case tag::head:
        case tag::erav:
        case tag::entity:
            // DO NOTHING
            break;
        case tag::record:
            TUPLE.ID_ENT   = m_id;
            TUPLE.REL.ID   =   m_context->REL_ID;
            TUPLE.REL.SUB  = ( m_context->prev == 0 ? 0 : m_context->prev->REL_ID );
            TUPLE.REL.TYPE = attrib::eREL_TYPE;
            TUPLE.ATTRIB   = m_attrib_ref;
            TUPLE.VAL.BLOB.clear();
            if (m_L!=0) { m_L->push_back( TUPLE ); }
            break;
        case tag::word:
        case tag::string: // do nothing
            break;
        default: error( "Non matching XML tag" );
    }
}

void ERAV::parser::pushContext() {
    m_tag = m_lookahead->getTag();
    if ( ! ( (tag::first<=m_tag) && (m_tag<=tag::last) ) ) {
        error( "Incorrect XML tag" );
    }

    if ( m_tag == tag::entity ) {
        m_nest_id = 0;
    }
    else if ( m_tag==tag::record || m_tag==tag::head ) {
        {   context* p; // get new context
            if ( m_context_old == 0 ) {
                p = new context();
            }
            else {
                p = m_context_old;
                m_context_old = m_context_old->prev;
            }
            p->prev   = m_context;
            m_context = p;
        }
        m_context->REL_ID = m_nest_id;
        if ( m_tag==tag::record ) { m_nest_id++; } // avoid <head> ++
    }
    else if ( m_tag==tag::word || m_tag==tag::string ) {
        m_inWord = (m_tag==tag::word);
    }
}

void ERAV::parser::popContext() {
    if ( m_tag==tag::record || m_tag==tag::head ) {
        context * toRelease = m_context;
        m_context = m_context->prev;

        toRelease->prev = m_context_old;
        m_context_old = toRelease;
        //  Only <record> && <head> tags pushContext() <==>
        //  Only <record> && <head> tags popContext()  <==>
    }
}

void ERAV::parser::setAttrib() {
    if ( m_tag==tag::head ) {
        return; // ignore all attribs for <?xml header ?>
    }
    m_attrib = m_lookahead->getAttrib();
    bool correct = ( attrib::FIRST <= m_attrib );
    correct      = correct &&       ( m_attrib <= attrib::LAST );
    if ( ! correct ) {
        error( "Incorrect XML attribute" );
    }
}

void ERAV::parser::setAttribVal() {
    if ( m_tag==tag::head ) {
        return; // ignore all attribs for <?xml header ?>
    }
    int int_val = atoi( m_lookahead->lexeme().c_str() ); // ansi atoi()
    bool isEntity, correct; // avoid cross initialization over case label
    switch ( m_attrib ) {
        case attrib::ATTRIB:
            if ( m_tag==tag::record || m_tag==tag::attrib ) {
                m_attrib_ref = int_val;
            }
            else { error( "Incorrect attribute: ATTRIB only for <record>&&<attrib> tags" ); }
            break;
        case attrib::DESCR:
            m_str_val = m_lookahead->lexeme();
            break;
        case attrib::ID_ENT:
            if ( m_tag==tag::entity ) {
                m_id = int_val;
            }
            else { error( "Incorrect attribute: ID_ENT only for <entity> tag" ); }
            break;
        case attrib::REL_ID:  // ignore value:
        case attrib::REL_SUB: // - use record nesting to determine these values
            break;
        case attrib::REL_TYPE:
            m_rel_type = tolower( m_lookahead->lexeme()[0] );
            isEntity =             m_tag==tag::entity;
            isEntity = isEntity || m_tag==tag::record;
            if ( (m_rel_type == attrib::eREL_TYPE) ) {
                if ( ! isEntity ) {
                    assert( (m_rel_type == attrib::eREL_TYPE) && (! isEntity) );
                    error( "Incorrect attribute REL_TYPE: not <entity> or <record> tag" );
                }
            }
            else if ( isEntity ) {
                assert( (m_rel_type != attrib::eREL_TYPE) && ( isEntity ) );
                error( "Incorrect attribute REL_TYPE in <entity> or <record>" );
            }
            break;
        case attrib::VAL:
            m_str_val = m_lookahead->lexeme();
            break;
        case attrib::ID_WORD:
            if ( m_tag==tag::word ) {
                m_id_word = int_val;
            }
            else {
                error( "Incorrect attribute ID_WORD: not for <word>" );
            }
            break;
        case attrib::ID_STRING:
            if ( m_tag==tag::string ) {
                m_id_word = int_val;
            }
            else {
                error( "Incorrect attribute ID_STRING: not for <string>" );
            }
            break;
        case attrib::LANG:
            correct =            ( m_tag==tag::string );
            correct = correct || ( m_tag!=tag::word   );
            if ( correct ) {
                m_lang[0] = tolower( m_lookahead->lexeme()[0] );
                m_lang[1] = tolower( m_lookahead->lexeme()[1] );
                m_lang[2] = 0; // EOS
            }
            else {
                error( "Incorrect LANG attribute: not in <word> or <string>" );
            }
            break;
        default:
            error( "Incorrect XML attribute" );
    }
}

void ERAV::parser::parse() {
    // m_L->clear();
    if ( m_XML==0 ) {
        return;
    }
    else {
        m_cursor = m_yytext = m_XML;
        int token = yylex( &m_cursor, &m_yytext, &m_yyleng, &m_yyline );
        m_lookahead->set(token, m_yytext, m_yyleng, m_yyline);
        all();
        if ( !(*m_lookahead==token::ZERO) ) {
            error( "Non XML document: trailer invalid" ); // didn´t process whole input
        }
    }
}

ERAV::parser::~parser() {
    if ( deleteXML  )       { delete [] m_XML;      }
    if ( m_context!=0 )     { delete m_context;     }
    if ( m_context_old!=0 ) { delete m_context_old; }
}

void ERAV::parser::real_set(
    const char* XML, std::list<ERAV::tuple> & L,
    ERAV::WORD & W,  ERAV::WORD & S,
    bool makeCopy
) {
    m_lookahead = &token1;
    m_yyline = 1;
    m_L = &L;  m_WORD = &W;  m_STRING = &S;  // parser's output appended to these

    if ( deleteXML ) {
        delete [] XML;
        deleteXML = false;
    }

    if ( makeCopy ) {
        size_t sz = strlen(XML)+1;
        try {
            m_XML = new char[sz];
        }
        catch ( ... ) {
            m_XML = 0;
            error( "Not enough memory to copy XML string" );
        }
        memcpy( const_cast<char*>(m_XML), XML, sz );
        deleteXML = true;
    }
    else {
        m_XML = XML;
    }
}

void ERAV::parser::match( int tkn ) {
    if ( *m_lookahead==tkn ) {
        int token_number = yylex( &m_cursor, &m_yytext, &m_yyleng, &m_yyline );
        m_lookahead = ( m_lookahead==&token1 ? &token2 : &token1 ); // flip
        m_lookahead->set(token_number, m_yytext, m_yyleng, m_yyline);
    }
    else {
        error( "Unexpected token" );
    }
}

#if 0
    #include <sstream> // std::basic_ostringstream<>
    #ifdef Spanish_dox
    /// Retorna una hilera \c std::string contruida desde el valor de \c val.
    /// - \c toString() with standard C++
    #endif
    #ifdef English_dox
    /// Returns a \c std::string constructed form value \c val.
    /// - \c toString() with standard C++
    #endif
    template <class T>
    std::string toString( const T & val ) {
    //  typedef basic_ostringstream<char> ostringstream;
        std::basic_ostringstream<char> temp; // ostringstream temp;
        temp << val;
        return temp.str( );
    }
#endif

/** Reverses in place all bytes in \c ptr.
    - Mnemonic: memrev() <==> memory-reverse.
    - Returns \c "ptr".
*/
void* memrev( void *ptr , size_t num ) {
    char  *l = (char*)(ptr);       // left
    char  *r = (char*)(ptr)+num-1; // right
    num /= 2;
    for ( size_t i=0; i<num; i++, l++, r-- ) {
        char tmp=*r; *r=*l; *l=tmp;
    }
    return ptr;
}

/** Reverses in place all characters in \c str.
    Changes all the characters in \c "str" to reverse order,
    except for the terminating null.
    - Mnemonic: strrev() <==> string-reverse.
    - Returns \c "str".
*/
inline char* strrev(char *str) {
    size_t len = strlen(str);
    return (char*) memrev(str,len);
}

/** Convert integer \c int to string \c str(non-standard function).
    Converts an integer value to a null-terminated string
    using the specified \c base and stores the result in the
    array given by \c str parameter.

    If \c base is 10 and \c value is negative, the resulting
    string is preceded with a minus sign (-). With any
    other base, value is always considered unsigned.

    \c str should be an array long enough to contain any
    possible value: <code> (sizeof(int)*8+1) </code>
    for radix=2, i.e. 17 bytes in 16-bits platforms and
    33 in 32-bits platforms.
*/
char* itoa( int value, char *str, int base ) {
    char *r = str; // r -> result
    if ( base<2 || base>(10+('z'-'a'+1)) ) { // base>36
        *str = 0;
        return str;
    }
    unsigned val = value; // bitwise copy
    bool negBase10 = (value<0) && (base==10);
    if ( negBase10 ) { val = -value; }
    if ( val == 0 ) {
       *r = '0'; ++r;
    }
    else do {
        unsigned digit = (val % (unsigned)(base));
        val /= (unsigned)(base);
        *r = ( (digit>=10) ? ((digit-10)+'a') : ('0'+digit) );
        ++r;
    } while ( val !=0 );
    if ( negBase10 ) { *r = '-'; r++;}
    *r = 0; // EOS

    // strrev( str );
    r--;           // r -> right
    char *l = str; // l -> left
    while ( l<r ) {
        char tmp=*r; *r=*l; *l=tmp;
        l++; r--;
    }
    return str;

    const int its_36 = 10+('z'-'a'+1);
    struct ITS_36 { // compile time verify that it´s 36
        char its[ its_36==36 ? +1 : -1 ];
    };
}

/// <code> return itoa(i,my_itoa::static_buffer,10)</code>.
inline char* my_itoa( int i ) {
    static char itoa_buffer[ sizeof(int)*8+1 ];
    return itoa(i,itoa_buffer,10);
}

void ERAV::parser::error( const char* msg ) {
    std::string err = "*** ERROR *** ";
    if ( msg !=0 ) if ( *msg != 0 ) {
        err += "[ ";
        err += msg;
        err += " ]\n          *** ";
    }
    err += "line(";
    err += my_itoa(m_yyline);
    err += ") ";
    m_lookahead = ( m_lookahead==&token1 ? &token2 : &token1 ); // flip
    err += m_lookahead->lexeme() + ' ';
    m_lookahead = ( m_lookahead==&token1 ? &token2 : &token1 ); // flop
    const char *y=m_yytext;
    for (int i=0; i<m_yyleng; ++i,++y) { err += (*y); }
    err += '\n';
    {
        static char error_mem[128];
        size_t ln = err.length()+1;
        ln = ( sizeof(error_mem) <= ln ? sizeof(error_mem) : ln );
        ln--;
        err.copy(error_mem, ln);
        error_mem[ ln ] = 0;
        throw ERAV::exception( error_mem );
    }
}

/// cursor++ && (line++ <==> '\n')
#define nextChar(cursor,line) { if ('\n'==*(*cursor)) { (*line)++; } (*cursor)++; }

// scanner: scans from cursor and sets next token in yytext
int ERAV::yylex( char const** cursor, char const** yytext, int* yyleng, int* yyline ) {
    start_here: (*yytext) = (*cursor); (*yyleng) = 1;
    if ( isspace( *(*cursor) ) ) { // skip whitespace
        while ( isspace( *(*cursor) ) ) { nextChar(cursor,yyline); }
        #undef  USE_goto
        #define USE_goto
        #ifdef  USE_goto
           goto start_here; // avoid recursion
        #else
           return yylex( cursor, yytext, yyleng, yyline );
        #endif
    }
    else if ( *(*cursor)=='<' ) {
        if ( (*cursor)[1]=='/') { // "</" LTS
            (*yyleng) = 2; (*cursor) += 2;
            return ERAV::token::LTS;
        }
        else if ( (*cursor)[1]=='?') { // "<?" LTQ
            (*yyleng) = 2; (*cursor) += 2;
            return ERAV::token::LTQ;
        }
        if ( 0==memcmp( (*cursor),"<!--",4 ) ) { // skip commments
            (*cursor) +=4; (*yyleng) = 4; // 4 == strlen("<!--");
            for (;;) {
                while (*(*cursor) != '-') { nextChar(cursor,yyline); } // next '-'
                if ( 0==memcmp( (*cursor),"-->",3 ) ) {
                    (*cursor) += 3; // 3 == strlen("-->")
                    #ifdef  USE_goto
                       goto start_here; // avoid recursion
                    #else
                       return yylex( cursor, yytext, yyleng, yyline );
                    #endif
                }
                else {
                    nextChar(cursor,yyline); // keep trying
                }
            }
        }
        else {
            nextChar(cursor,yyline);
            return **yytext;
        }
    }
    else if ( *(*cursor)=='\'' ) { // single quoted string
        nextChar(cursor,yyline); *yyleng = 0; // count 1 less
        while ( *(*cursor)!='\'' ) { nextChar(cursor,yyline); (*yyleng)++; }
        (*yytext)++; nextChar(cursor,yyline); // skip quotes
        return ERAV::token::STRING;
    }
    else if ( *(*cursor)=='\"' ) { // double quoted string
        nextChar(cursor,yyline); *yyleng = 0; // count 1 less
        while ( *(*cursor)!='\"' ) { nextChar(cursor,yyline); (*yyleng)++; }
        (*yytext)++; nextChar(cursor,yyline); // skip quotes
        return ERAV::token::STRING;
    }
    else if ( isalpha(*(*cursor)) || *(*cursor)=='_' ) {
        *yyleng = 0; // count 1 less
        while (
            isalpha(*(*cursor)) || isdigit(*(*cursor)) ||
            *(*cursor)=='_'     || *(*cursor)==':' )
        {
            (*yyleng)++; nextChar(cursor,yyline);
        }
        return ERAV::token::ID;
    }
    else if ( *(*cursor)=='/' ) {
        if ( (*cursor)[1]=='>' ) { // "/>" SGT
            (*yyleng) = 2; (*cursor) += 2;
            return ERAV::token::SGT;
        }
        else {
            nextChar(cursor,yyline);
            return **yytext;
        }
    }
    else if ( *(*cursor)=='?' ) {
        if ( (*cursor)[1]=='>' ) {
            (*yyleng) = 2; (*cursor) += 2;
            return ERAV::token::QGT; // "?>"
        }
        else {
            nextChar(cursor,yyline);
            return **yytext;
        }
    }
#if 0
    else if ( *(*cursor)=='=' ) {
        nextChar(cursor,yyline);
        return **yytext;
    }
    else if ( *(*cursor)==0 ) {
        nextChar(cursor,yyline);
        return **yytext;
    }
#endif
    else {
        nextChar(cursor,yyline);
        return **yytext;
    }

    // make sure that token numbers never collide with ASCII
    struct LTQ_is_bigger_than_255 {
        int check[ (ERAV::token::LTQ > 255) ? +1 : -1 ];
    };
}

namespace ERAV {

/// (l<r)==>(-1)   (l==r)==>((0))   (l>r)==>(+1).
int  tplcmp( const ERAV::tuple& l, const ERAV::tuple& r );
/// (l<r) ???.
bool isLess( const ERAV::tuple& l, const ERAV::tuple& r );

#ifdef  USE_isLess

// Old implementation: I prefer tplcmp()
bool isLess( const ERAV::tuple& l, const ERAV::tuple& r ) {
    if ( l.ID_ENT < r.ID_ENT ) { // compare [ID_ENT]
        return true;
    }
    bool eq = (l.ID_ENT == r.ID_ENT);

    if ( eq && (l.REL.ID < r.REL.ID) ) { // compare [REL.ID]
        return true;
    }
    eq = eq && (l.REL.ID == r.REL.ID);

    if ( eq && (l.REL.SUB < r.REL.SUB) ) { // compare [REL.SUB]
        return true;
    }
    eq = eq && (l.REL.SUB == r.REL.SUB);

    char l_rel_type = tolower(l.REL.TYPE); // special case REL.TYPE == eREL_TYPE
    char r_rel_type = tolower(r.REL.TYPE);

    if ( eq && (l_rel_type != r_rel_type) ) {
        if ( r_rel_type==ERAV::attrib::eREL_TYPE ) { // eREL_TYPE is always bigger
            return false;
        }
        else if ( l_rel_type==ERAV::attrib::eREL_TYPE ) {
            return true;
        }
        else {
            return ( l_rel_type < r_rel_type );
        }
    }
    return false; // ( eq && (l_rel_type == r_rel_type) )
}

#else // USE_isLess ==> NOT defined

/* NOTE:
[] REL.TYPE == attrib::eREL_TYPE has precedence over the other TYPE's to
   have each record name appear before its attributes inlist<ERAV::tuple>.
   This ensures that <entity> and <record> tags come before <attrib> tags
   in list<ERAV::tuple>.
[] The implementations for functions tplcmp() && isLess() are inside the ERAV
   namespace to avoid naming conflicts.
[] When ordering a list of tuples using the ERAV::tuple_compare() funtor
   all tuples for each entity are contiguos. Furthermore, as attrib::eREL_TYPE
   REL_TYPE takes precedence, the first record of a new record entity
   comes first in the std::list<ERAV::tuple>.
[] Lexicographic Comparison for an \c "ERAV_Tuple".
    - Comparison criteria:
      <code> { ID_ENT ~ REL.ID ~ REL.SUB ~ REL.TYPE }</code>
    - REL.TYPE==attrib::eREL_TYPE has precedence and its always
      smaller than the rest.
    - This is the sort criteria used by list::sort() for sorting
      list<ERAV::tuple>.
*/
int tplcmp( const ERAV::tuple& l, const ERAV::tuple& r ) {
    enum { lt=-1, eq=0, gt=+1 };
    if ( l.ID_ENT < r.ID_ENT ) { // compare [ID_ENT]
        return lt;
    }
    else if ( l.ID_ENT > r.ID_ENT ) {
        return gt;
    }
    assert( l.ID_ENT == r.ID_ENT );

    if ( l.REL.ID < r.REL.ID ) { // compare [REL.ID]
        return lt;
    }
    else if ( l.REL.ID > r.REL.ID ) {
        return gt;
    }
    assert( l.REL.ID == r.REL.ID );

    if ( l.REL.SUB < r.REL.SUB ) { // compare [REL.SUB]
        return lt;
    }
    else if ( l.REL.SUB > r.REL.SUB ) {
        return gt;
    }
    assert( l.REL.SUB == r.REL.SUB );

    char l_rel_type = tolower(l.REL.TYPE); // special case REL.TYPE == eREL_TYPE
    char r_rel_type = tolower(r.REL.TYPE);
    {
        if ( l_rel_type==ERAV::attrib::eREL_TYPE ) {
            if ( r_rel_type==ERAV::attrib::eREL_TYPE ) {
                return eq;
            }
            else {
                return lt;
            }
        }
        else if ( r_rel_type==ERAV::attrib::eREL_TYPE ) {
            return gt;
        }
        else if ( l_rel_type < r_rel_type ) {
            return lt;
        }
        else if ( l_rel_type > r_rel_type ) {
            return gt;
        }
        assert( l_rel_type == r_rel_type );
        return eq;
    }
}

#endif

} // namespace ERAV


#define USE_algorithm
#undef  USE_algorithm

#ifdef  USE_algorithm
#include <algorithm>
/* NOTE:
    I didn´t want to include the <algorithm> header file to slim down the program.
    If you don´t care, just define macro USE_algorithm and the STL find_if()
    algorithm will be used instead of my straightforward loop implementation.
*/

template<class InputIterator, class Predicate>
InputIterator find_if( InputIterator first, InputIterator last, Predicate pred ) {
    for ( ; first!=last ; first++ ) {
        if ( pred(*first) ) {
            break;
        }
    }
    return first;
}

struct DESCR_cmp {
    typedef ERAV::WORD::DESCR::const_iterator iter;
    DESCR_cmp( std::string value ) : m_value(value) { }
    bool operator()( const std::pair<std::string,std::string>& l ) {
        return ( l.first == m_value );
    }
private:
    std::string m_value;
};
#endif

#ifdef USE_algorithm
inline
#endif
ERAV::WORD::DESCR::iterator ERAV::WORD::lFind(
    DESCR& L,
    const std::string& lang
) {
    #ifdef USE_algorithm
        // lFind() should be inline
        return std::find_if( L.begin(), L.end(), DESCR_cmp(lang) );
    #else
        DESCR::iterator jt = L.begin();
        while ( jt!=L.end() ) {
            if ( jt->first == lang ) {
                break;
            }
            ++jt;
        }
        return jt;
    #endif
}

std::string ERAV::WORD::lookUp( int n , const std::string& lang ) const {
    MAP::const_iterator it; // search with ID_WORD
    it = m_WORD.find(n);
    if ( it == m_WORD.end() ) {
        return std::string();
    }
    else { // seach with LANG ( 'es' 'en' '**' etc )
        DESCR::const_iterator jt;
        jt = lFind( it->second, lang );
        if ( jt != it->second.end() ) {
            return jt->second;
        }
        jt = lFind( it->second, "**" );
        if ( jt != it->second.end() ) {
            return jt->second;
        }
        return std::string();
    }
}

bool ERAV::WORD::update( int n , const std::string& lang , const std::string& descr ) {
    MAP::iterator it; // search with ID_WORD
    it = m_WORD.find(n);
    if ( it == m_WORD.end() ) {
        std::pair<MAP::iterator,bool> ins;
        ins = m_WORD.insert( MAP::value_type(n,DESCR()) );
        if ( ins.second ) {
            ins.first->second.push_back( DESCR::value_type(lang,descr) );
        }
        return ins.second;
    }
    else {
        DESCR::iterator jt;
        jt = lFind( it->second, lang );
        if ( jt == it->second.end() ) {
            it->second.push_back( DESCR::value_type(lang,descr) );
        }
        else {
            jt->second = descr; // write over
        }
        return true;
    }
}

void ERAV::WORD::erase( int n ) {
    MAP::iterator it = m_WORD.find(n); // search with ID_WORD
    if ( it != m_WORD.end() ) {
        m_WORD.erase( it );
    }
}

void ERAV::WORD::toList( std::list<ERAV::WORD_tuple>& L ) const {
    WORD_tuple tuple;
    ERAV::WORD::MAP::const_iterator   it;
    ERAV::WORD::DESCR::const_iterator jt;
    for ( it=m_WORD.begin(); it!=m_WORD.end() ; ++it ) {
        for ( jt=it->second.begin(); jt!=it->second.end() ; ++jt ) {
            tuple.ID_WORD = it->first;
            tuple.LANG[0] = jt->first[0];
            tuple.LANG[1] = jt->first[1];
            tuple.DESCR   = jt->second;
            L.push_back( tuple );
        }
    }
}

// Exclude from Doxygen Documentation
// http://www.doxygen.org/commands.html#cmdcond
/// @cond
// {

// toupper( lexeme ) == str ???
// - Requires str == toupper( str )
bool upCMP( const std::string& lexeme, const char* str ) {
    std::string::const_iterator it, end;
    it  = lexeme.begin();
    end = lexeme.end();
    while ( (*str!=0) && (it!=end) ) {
        if ( toupper(*it) != *str ) {
            return false;
        }
        ++str; ++it;
    }
    return (it==end) && (*str==0);
    // for_each( LEXEME.begin(), LEXEME.end(), toupper );
}

// keywords                            // toupper( keywords )
const char sErav     []  ="erav";      const char sERAV   []  ="ERAV";
const char sID_ENT   [] = "ID_ENT";
const char sREL_ID   [] = "REL_ID";
const char sREL_SUB  [] = "REL_SUB";
const char sREL_TYPE [] = "REL_TYPE";
const char sAttrib   [] = "attrib";    const char sATTRIB [] = "ATTRIB";
const char sVAL      [] = "VAL";
const char sID_WORD  [] = "ID_WORD";
const char sID_STRING[] = "ID_STRING";
const char sLANG     [] = "LANG";
const char sDescr    [] = "descr";     const char sDESCR  [] = "DESCR";
const char sEntity   [] = "entity";    const char sENTITY [] = "ENTITY";
const char sRecord   [] = "record";    const char sRECORD [] = "RECORD";
const char sWord     [] = "word";      const char sWORD   [] = "WORD";
const char sString   [] = "string";    const char sSTRING [] = "STRING";
const char sXml      [] = "xml";       const char sXML    [] = "XML";

void ERAV::token::setTagAttrib() {
    // all comparisons are made with the uppercase version of each string
    if      ( upCMP( m_lexeme , sATTRIB    ) ) { m_tag_attrib = attrib::ATTRIB;    }
    else if ( upCMP( m_lexeme , sVAL       ) ) { m_tag_attrib = attrib::VAL;       }
    else if ( upCMP( m_lexeme , sREL_TYPE  ) ) { m_tag_attrib = attrib::REL_TYPE;  }
    else if ( upCMP( m_lexeme , sRECORD    ) ) { m_tag_attrib = tag::record;       }

    else if ( upCMP( m_lexeme , sLANG      ) ) { m_tag_attrib = attrib::LANG;      }
    else if ( upCMP( m_lexeme , sDESCR     ) ) { m_tag_attrib = attrib::DESCR;     }

    else if ( upCMP( m_lexeme , sWORD      ) ) { m_tag_attrib = tag::word;         }
    else if ( upCMP( m_lexeme , sSTRING    ) ) { m_tag_attrib = tag::string;       }

    else if ( upCMP( m_lexeme , sENTITY    ) ) { m_tag_attrib = tag::entity;       }
    else if ( upCMP( m_lexeme , sID_ENT    ) ) { m_tag_attrib = attrib::ID_ENT;    }

    else if ( upCMP( m_lexeme , sID_WORD   ) ) { m_tag_attrib = attrib::ID_WORD;   }
    else if ( upCMP( m_lexeme , sID_STRING ) ) { m_tag_attrib = attrib::ID_STRING; }

    else if ( upCMP( m_lexeme , sREL_ID    ) ) { m_tag_attrib = attrib::REL_ID;    }
    else if ( upCMP( m_lexeme , sREL_SUB   ) ) { m_tag_attrib = attrib::REL_SUB;   }
    else if ( upCMP( m_lexeme , sERAV      ) ) { m_tag_attrib = tag::erav;         }
    else if ( upCMP( m_lexeme , sXML       ) ) { m_tag_attrib = tag::head;         }
    else                                       { m_tag_attrib = attrib::NONE;      }
    // the more used tags are tested for first

/* The SAME code values are used for these record tag and attrib codes:
   - attrib::NONE   == tag::none
   - attrib::DESCR  == tag::desc
   - attrib::ATTRIB == tag::attrib
   This helps because a token::setTagAttrib() method can be used to set both
    attrib and record tag codes. The following code insures at compile time
    that these equalities hold.
*/
    // Compile time ensure attrib::NONE == tag::none, etc.
    struct NONE_DESCR_ATTRIB {
        int vec_NONE[   0==(attrib::NONE-tag::none)     ? +1 : -1 ];
        int vec_DESCR[  0==(attrib::DESCR-tag::descr)   ? +1 : -1 ];
        int vec_ATTRIB[ 0==(attrib::ATTRIB-tag::attrib) ? +1 : -1 ];
        int LAST_gt_last[0<( attrib::LAST-tag::last )   ? +1 : -1 ];
    };
    #define isEqual(a,b)  ( 0 ==(a)-(b) ? +1 : -1 )
    #define myAbs(a)      ( (a)>0 ? (a) : -(a) )
    #define isBigger(a,b) ( 0 <myAbs(a)-myAbs(b) ? +1 : -1 )
    struct none_descr_attrib {
        int vec_NONE[     isEqual( attrib::NONE   , tag::none   ) ];
        int vec_DESCR[    isEqual( attrib::DESCR  , tag::descr  ) ];
        int vec_ATTRIB[   isEqual( attrib::ATTRIB , tag::attrib ) ];
        int LAST_gt_last[ isBigger( attrib::LAST  , tag::last   ) ];
        int eREL_TYPE_islower[ isBigger( 'z'-'a' , attrib::eREL_TYPE-'a' ) ];
    };
    #undef isBigger
    #undef  myAbs
    #undef isEqual  // @cond @endcond tells Doxygen not to document this
}

/// Tree->node [ erav2xml() ].
class node {
    friend void erav2xml(std::list<ERAV::tuple>& L, std::string& XML );
    friend void recursive_store( std::string& XML, node * root , int indent,
                                 std::list<ERAV::tuple>::const_iterator stop);
    std::list<ERAV::tuple>::const_iterator it; ///< Tree->data
    std::list< node* >                      L; ///< Tree->children
    node() : it(), L() { } ///< Constructor
    ~node(); ///< Destructor
};

node::~node() {
    if ( ! L.empty() ) {
        std::list< node* >::iterator jt;
        for ( jt=L.begin(); jt!=L.end(); ++jt ) {
            delete (*jt);
        }
        L.clear();
    }
}

void recursive_store( std::string& XML, node *root , int indent ,
    std::list<ERAV::tuple>::const_iterator stop
) {
    using std::string;
    std::list<ERAV::tuple>::const_iterator jt = root->it;
    //* DELETE */ ERAV::tuple view = *jt;
    char rel_type = tolower(jt->REL.TYPE);
    if ( rel_type!=ERAV::attrib::eREL_TYPE ) {
        return; // error( "first tuple must be eREL_TYPE <record>" )
    }
//* DELETE */ int rel_id = jt->REL.ID;

    std::string STR;
    {   // <record>
        for (int i=0; i<indent; ++i) { STR += '\t'; }
        STR  += string() + '<' + sRecord + ' ';
    #if 0
        STR  += string() + sREL_ID + "=\"" + my_itoa( jt->REL.ID ) + "\" ";
    #endif
        STR  += string() + sREL_TYPE + "=\"" + ERAV::attrib::eREL_TYPE + "\" ";
        STR  += string() + sATTRIB + "=\"" + my_itoa( jt->ATTRIB ) + "\" >\n";
        XML += STR; STR.clear();
        ++jt;
        //* DELETE */ if (jt!=stop) { view = *jt; } // can´t view the last tuple
    }
    bool done = (jt==stop);  // root->[ it, std::list<node*> ]
    while ( ! done ) {
        rel_type = tolower(jt->REL.TYPE);
        if ( rel_type==ERAV::attrib::eREL_TYPE ) // next <record> reached
#if 1
        {
            done = true;
        }
#else
        {
            if ( rel_id == jt->REL.ID ) {
                ++jt; // skip duplicate record
                done = (jt==stop);
            }
            else {
                done = true;
            }
        }
#endif
        else { // <attrib>
            for (int i=0; i<indent; ++i) { STR += '\t'; }
            STR  += string() + "\t<" + sAttrib + ' ';
            STR  += string() + sREL_TYPE + "=\"" + rel_type + "\" ";
            STR  += string() + sATTRIB   + "=\"" + my_itoa( jt->ATTRIB ) + "\" ";
            STR  += string() + sVAL      + "=\"" + jt->VAL.BLOB + "\" />\n";
            XML += STR; STR.clear();
            ++jt;
            //* DELETE */ if (jt!=stop) { view = *jt; } // can´t view the last tuple
            done = (jt==stop);
        }
    }
    {   // recursive store of every child
        std::list< node* >::const_iterator it, end;
        end = root->L.end();
        it  = root->L.begin();
        for ( ; it!=end; ++it ) {
            recursive_store( XML, *it, indent+1 , stop );
        }
    }

    // </record>
    for (int i=0; i<indent; ++i) { STR += '\t'; }
    STR += string() + "</" + sRecord + ">\n";
    //* DELETE */ std::cout << STR;
    XML += STR;
//  STR.clear(); // not necessary
}

// }
/// @endcond

// Stores tuples from L as an XML document in string XML

// L<tuple> ==> XML ((append))
void erav2xml( std::list<ERAV::tuple>& L, std::string& XML ) {
    using std::string;
    L.sort( );
    L.unique( ); // remove duplicates
//* DELETE */ dump_tuples( L );

    std::list<ERAV::tuple>::const_iterator itB;
    std::list<ERAV::tuple>::const_iterator it,endE; // itB ~ it BIG loop
    typedef std::map< int, node* > M_type;
    std::pair<M_type::iterator,bool> ret; // for M_type.insert()
    M_type::iterator mt;
    M_type M; // M[id_red]==>root(node*)

    for ( itB=L.begin(); itB != L.end(); itB=endE ) {

        node *root = 0;
        // make nodes && find end of current <entity> && build M[#]->list<node*>
        it=itB; bool done = (it==L.end());
        while ( ! done ) {
//* DELETE */ ERAV::tuple view = *it;
            node *p;
            if ( it->REL.TYPE==ERAV::attrib::eREL_TYPE ) { // creates the nodes for the tree
                mt = M.find(it->REL.ID);
                if ( mt==M.end() ) {
                    p = new node();
                    p->it = it;
                    ret = M.insert( M_type::value_type(it->REL.ID, p) );
//* DELETE */        std::cout << it->REL.ID << ' ';

                     // sets root's field
                    if ( it->REL.ID == it->REL.SUB ) {
                        // only the root node has these 2 fields equal
                        if ( root == 0 ) { root = p; }
                    }
                }
                else { /* IGNORE: duplicate <record> tuple */ }
                // The numbering used for REL.ID && REL.SUB is arbitrary;
                // this implies that:
                // - The first record is NOT always the root record.
                // - Parent nodes don´t necessarily come before child nodes.
            }

            ++it;
            endE = it; // marks past last tupple for this <entity>
            if ( it==L.end() ) { break; }
            done = ( it->ID_ENT != itB->ID_ENT );
        }

//* DELETE */ std::cout << std::endl;
        // create the list of children for each node
        for ( mt=M.begin(); mt!=M.end(); ++mt ) {
            int rel_id  = mt->second->it->REL.ID;    assert( M.find(rel_id)  != M.end() );
            int rel_sub = mt->second->it->REL.SUB;   assert( M.find(rel_sub) != M.end() );
            if ( rel_id != rel_sub ) { // avoid root cycle
                M[rel_sub]->L.push_back( M[rel_id] );
//* DELETE */    std::cout << "M["<<rel_sub<<"]->L.push_back( M["<<rel_id <<"] )" << std::endl;
            }
        }
//* DELETE */ std::cout << "M.size() == " << M.size() << std::endl;
        M.clear(); // cleanup asap

        // store
        {   // <entity>
            XML += string() + "\t<" +sEntity+'\t'+sID_ENT + "=\"";
            XML += string() + my_itoa( itB->ID_ENT ) + "\">\n";
            { // <record> && <attrib>
                recursive_store( XML, root , 2 , L.end() );
            }
            XML += string() + "\t</" + sEntity + ">\n";
        }

        {
            delete root; // cleanup tree
        }
    } // for() ~ itB
}

void erav2xml_enclose( std::string& XML ) {
    using std::string;
    XML  = string()
         + "<?" + sXml  + " version=\"1.0\" encoding=\"Windows-1252\"?>\n"
         + "<"  + sErav + ">\n"
         + XML;
    XML += string()+"</"+sErav+">\n";
}

void erav2xml( const std::list<ERAV::WORD_tuple>& L, ERAV::WORD& W ) {
    typedef std::list<ERAV::WORD_tuple>::const_iterator iter;
    iter it, end = L.end();
    for ( it=L.begin(); it!=end ; ++it ) {
        W.update( it->ID_WORD , std::string(it->LANG,ERAV::LANG_LEN), it->DESCR );
    }
}

void erav2xml( const std::list<ERAV::WORD_tuple>& L, std::string& XML ) {
    ERAV::WORD W;
    erav2xml( L,W );
    erav2xml( W,XML );
}

void erav2xml( const ERAV::WORD& W , std::string& XML, bool isWORD ) {
    using std::string;
    const char* sTag = ( isWORD ? sWord    : sString    );
    const char* sID  = ( isWORD ? sID_WORD : sID_STRING );
    ERAV::WORD::MAP::const_iterator   it, wend=W.m_WORD.end();
    ERAV::WORD::DESCR::const_iterator jt, lend;
    for ( it=W.m_WORD.begin(); it!= wend; ++it ) {
        XML += string() + "\t<" + sTag + '\t' + sID + "=\"";
        XML += string() + my_itoa(it->first) + "\" >\n";
        lend = it->second.end();
        for ( jt=it->second.begin(); jt!= lend; ++jt ) {
            XML += string() + "\t\t<" + sDescr + ' ';
            XML += string() + sLANG + "=\"" + jt->first + "\" ";
            XML += string() + sDESCR + "=\"" + jt->second + "\" />\n";
        }
        XML += string() + "\t</" + sTag +">\n";
    }
}

// Load L from FROM skipping duplicates.
// - Skips duplicate ID_ENT records already in L
// - Duplicates remain in FROM
// - Does not copy: uses std::list<>::splice()
void ERAV::merge_into( std::list<ERAV::tuple>& L, std::list<ERAV::tuple>& FROM ) {
    if ( &L == &FROM ) { return; } // avoid auto-copy
    L.sort();    L.unique();
    FROM.sort(); FROM.unique();
    std::list<ERAV::tuple>::iterator itL = L.begin();
    std::list<ERAV::tuple>::iterator itF = FROM.begin();
    std::list<ERAV::tuple>::iterator stop;

    while ( itL!=L.end() && itF!=FROM.end() ) {
        if ( itL->ID_ENT < itF->ID_ENT ) { // advance in L
            for ( stop=itL ; stop->ID_ENT==itL->ID_ENT ; ++stop ) {
                if ( stop==L.end() ) { break; }
            }
            itL = stop;
        }
        else if ( itL->ID_ENT > itF->ID_ENT ) { // splice chunk into L
            for ( stop=itF ; stop->ID_ENT==itF->ID_ENT ; ++stop ) {
                if ( stop==FROM.end() ) { break; }
            }
            L.splice( itL, FROM, itF, stop );
            itF = stop;
        }
        else { // skip duplicate in FROM
            assert( itL->ID_ENT == itF->ID_ENT );
            for ( stop=itF ; stop->ID_ENT==itF->ID_ENT ; ++stop ) {
                if ( stop==FROM.end() ) { break; }
            }
            itF = stop;
        }
    }

    if (itL != L.end() ) {
        return;
    }
    if (itF != FROM.end() ) {
        L.splice( L.end(), FROM, itF, FROM.end() );
        return;
    }
}

#ifdef Spanish_dox
/// Construye \c S una hilera XML a partir de los valores \c ERAV almacenados en  una copia \c L.
/// - Usa el diccionario \c W de palabras \c ERAV_WORD para interpretar los valores de la lista \c L.
#endif
#ifdef English_dox
/// Builds \c S an XML string from the \c ERAV values stored in a copy of \c L.
/// - Uses diccionary \c W of \c ERAV_WORD to interpret values from list \c L.
#endif
/** \dontinclude test_ERAV.cpp
    \skipline    test::erav2xml()
    \until       }}
    \see         test_ERAV::test_erav2xml()
*/
/// \fn void erav2xml( std::list<ERAV_tuple> L , std::string& XML , const ERAV_WORD& W );

/***************\
|*             *|
|*   DOXYGEN   *|
|*             *|
\***************/

#ifdef Spanish_dox
/** \file  ERAV.h
    \brief Biblioteca para manipular Relaciones Jerárquicas Anidadas.
    \author Adolfo Di Mare <adolfo@di-mare.com>
    \date   2010
    - Why English names??? ==> http://www.di-mare.com/adolfo/binder/c01.htm#sc04
*/
#endif
#ifdef English_dox
/** \file  ERAV.h
    \brief Library to handle Nested Hierarchical Relations.
    \author Adolfo Di Mare <adolfo@di-mare.com>
    \date   2010
    - Why English names??? ==> http://www.di-mare.com/adolfo/binder/c01.htm#sc04
*/
#endif

#ifdef Spanish_dox
/** \file   ERAV.cpp
    \brief  Implementaciones para \c ERAV.h.
    \author Adolfo Di Mare <adolfo@di-mare.com>
    \date   2010
    - Why English names??? ==> http://www.di-mare.com/adolfo/binder/c01.htm#sc04
*/
#endif
#ifdef English_dox
/** \file   ERAV.cpp
    \brief  Implementation for \c ERAV.h.
    \author Adolfo Di Mare <adolfo@di-mare.com>
    \date   2010
    - Why English names??? ==> http://www.di-mare.com/adolfo/binder/c01.htm#sc04
*/
#endif

#ifdef Spanish_dox
/// Estos son los campos de la relación \c ERAV en la base de datos.
#endif
#ifdef English_dox
/// These are the fields for the \c ERAV relation in the data base.
#endif
/// \class class ERAV_tuple;

#ifdef Spanish_dox
/// Diccionario que contiene los tuples de la tabla \c WORD del \c ERAV.
#endif
#ifdef English_dox
/// Diccionary that contians the tuples from the \c WORD in the \c ERAV.
#endif
/// \class class WORD;

#ifdef Spanish_dox
/// Valores almacenados en relación \c WORD de la base de datos \c ERAV.
#endif
#ifdef English_dox
/// Values stored in the \c WORD table of the \c ERAV.
#endif
/// \class class WORD_tuple;


#ifdef Spanish_dox
/// Utilizando los tuples de \c "L" llena \c "XML" en formato de documento XML.
#endif
#ifdef English_dox
/// Uses tuples in \c L" to fill \c "XML" in XML document format.
#endif
/// \fn erav2xml( std::list<ERAV::tuple>& L, std::string& XML );



/* IMPLEMENTATION notes
   ====================
[] parser::m_lookahead is a pointer to preserve the previous token to be
   printed on error. It looks nice to see the last token and the next
   one on error().
[] parser::m_lookahead cannot be a reference because it would not be
   posible to change it after initialization.
[] parser::deleteXML is used to ensure deletion of the copy of the string
   made when it was detected that method string::c_str() was used, because
   it returns a pointer into a global static area which would hinder using
   c_str() in this implementation. Programmer should know this, but its
   better to be safe than sorry.
[] Two implementations of the WORD::lookup() method are needed, but they
   use the same algorithm. A [[ lFind( *const_cast<DESCR*>(&L), lang ) ]]
   trick is used to have them share the same implementation.
[] parser::m_lang[4] has 4 bytes to help in alignment Ughhh???
[] Macro [[[ #define ID_val const std::string & lexeme ]]] was used to put
   the XML grammar in the declaration of the methods that recognize each
   non-terminal. It's a harmless quirk.
[] Instead of using template function toString() the non-ansii itoa()
   function was used. This avoids including all the <sstream> parafernalia
   in this module. I further use my_itoa() that uses a global buffer.
[] Upper and lower case string constants sString && sSTRING, etc where
   used to avoid converting them to uppercase in function upCMP().
[] Both parser( const parser& ); && void operator= ( const parser& );
   (copy constructor && copy operator) are declared for the parser class,
   but none is implemented. It never makes sense to copy a parser object.
[] As 2 fields parser::m_id && parser::m_id_word exist, its is posible to
   mix [ <word> && <string> ] XML values within <record> values. Perhaps
   that should not be permited, but it more fun to intermix those values
   in the XML document (and it's easier to program).
[] Even when REL_ID && REL_SUB fields are included in the XML document,
   the hierarchical relationshiep between record values is determined by
   their relative nesting in the XML document. Field parser::m_nest_id
   holds the next REL_ID that gets used, ignoring the values that where
   written the REL_ID && REL_SUB fields of the XML document.
[] Field parser::m_context_old is used to hold deleted context objects to
   reuse them later. This is easy to do and speeds up execution a little
   bit.
*/


// EOF: ERAV.cpp