# [xml_base.h] XML Base Library

## contents

#include "standard.h"
#include "symbols.h"
#include "hmap.h"
#include "hset.h"
#include "ptm.h"
#include "xml_dfn.h"

       The module [xml_base] provides an reentrant interface for the parsing,
       interpretation and transformation of XML documents.

## Types and macros

XmlApp_T | Abstract XML application type

XmlCtx_T | Abstract XML parser type

## Init & Quit

    XmlApp_T XML_app_init
             (
               XMLHDL_io_init           io_init,
               XMLHDL_io_cleanup        io_quit,
               XMLHDL_io_create_handle  io_create,
               XMLHDL_io_drop_handle    io_drop,
               XMLHDL_io_download       io_download
             )
| init XML application; optional I/O handler: 'io_init' = init download module 'io_quit' = cleanup download module 'io_create' = create download handle 'io_drop' = drop download handle 'io_download' = download URL to (string) stream
    void XML_app_quit(XmlApp_T xmlapp)
| quit XML application; release resources
    XmlCtx_T XML_init
          (
            XmlApp_T xmlapp,
            void (*prMsg)(c_string msg), c_bool verbose, c_bool diagnose
          )
| init XML parsing; 'prMsg' --> print function or NULL 'verbose' --> (de)activate progress information 'diagnose' --> (de)activate diagnose information
    void XML_quit(XmlCtx_T xmlctx)
| quit XML compilation; release resources

## Set & Get

    void XML_set_verbose(XmlCtx_T xmlctx, c_bool verbose)
| (de)activate progress information
    void XML_set_diagnose(XmlCtx_T xmlctx, c_bool diagnose)
| (de)activate diagnose information
    void XML_set_context(XmlCtx_T xmlctx, Any_T extctx)
| set external context information
    Any_T XML_get_context(XmlCtx_T xmlctx)
| get external context information
    void XML_get_trees(XmlCtx_T xmlctx, symbol* root, MAP(symbol,PT_Term)* trees)
| get document trees

## Parsing & Tree construction

    int XML_load_file
        (
          XmlCtx_T xmlctx, c_string xmldoc, c_string cset, c_bool dtd, c_bool all
        )
| parses XML/DTD definition in file 'xmldoc' and constructs the corresponding tree; 'cset' = character set name ( UCS4, UTF-8, MS:CodePage / GNU:iconv-based ) 'dtd' = True --> 'xmldoc' contains DTD definitions 'all' = True --> loads all referenced documents RC > 0: number of (syntax and semantic) errors RC = -1: tree construction failed RC = 0: successful load
    int XML_load_string
        (
          XmlCtx_T xmlctx, c_string xmldoc, unsigned int len,
          c_string cset, c_bool dtd, c_bool all
        )
| parses XML definition in string 'xmldoc' and constructs the corresponding tree; 'len' = string size in bytes, inclusive terminating bytes 'cset' = character set name ( UCS4, UTF-8, MS:CodePage / GNU:iconv-based ) 'dtd' = True --> 'xmldoc' contains DTD definitions 'all' = True --> loads all referenced documents RC > 0: number of syntax and semantic errors RC = -1: tree construction failed RC = 0: successful load
    int XML_load_url
        (
          XmlCtx_T xmlctx, c_string xmldoc,
          c_string cset, c_string auth, c_bool dtd, c_bool all
        )
| parses XML definition identified by URL 'xmldoc' and constructs the corresponding tree; 'cset' = character set name ( UCS4, UTF-8, MS:CodePage / GNU:iconv-based ) 'auth' = optional user authentification ( format: user:passwd ) 'dtd' = True --> 'xmldoc' contains DTD definitions 'all' = True --> loads all referenced documents RC > 0: number of syntax and semantic errors RC = -1: tree construction failed RC = 0: successful load assertion: valid I/O handler