xmq.h

Go to the documentation of this file.

/* libxmq - Copyright (C) 2023-2026 Fredrik Öhrström (spdx: MIT)
 
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.
 
*/
 
#ifndef XMQ_H
#define XMQ_H
 
// #define XMQ_NO_XMQ_PRINTING
// #define XMQ_NO_LIBXML
// #define XMQ_NO_JSON
 
#define _hideLBfromEditor {
#define _hideRBfromEditor }
 
#ifdef __cplusplus
extern "C" _hideLBfromEditor
#endif
 
#include<stdarg.h>
#include<stdbool.h>
#include<stdlib.h>
#include<stdint.h>


typedef struct XMQDoc XMQDoc;

typedef struct XMQNode XMQNode;

typedef struct XMQAttr XMQAttr;

typedef struct XMQParseState XMQParseState;

typedef struct XMQParseCallbacks XMQParseCallbacks;

typedef struct XMQOutputSettings XMQOutputSettings;

typedef enum
{
    XMQ_CONTENT_UNKNOWN = 0,
    XMQ_CONTENT_DETECT = 1,
    XMQ_CONTENT_XMQ = 2,
    XMQ_CONTENT_HTMQ = 3,
    XMQ_CONTENT_XML = 4,
    XMQ_CONTENT_HTML = 5,
    XMQ_CONTENT_JSON = 6,
    XMQ_CONTENT_IXML = 7,
    XMQ_CONTENT_TEXT = 8,
    XMQ_CONTENT_CLINES = 9
} XMQContentType;

typedef enum
{
    XMQ_RENDER_PLAIN = 0,
    XMQ_RENDER_TERMINAL = 1,
    XMQ_RENDER_HTML = 2,
    XMQ_RENDER_HTMQ = 3,
    XMQ_RENDER_TEX = 4
} XMQRenderFormat;

typedef enum
{
    XMQ_FLAG_TRIM_NONE = 1,
    XMQ_FLAG_TRIM_HEURISTIC = 2,
    XMQ_FLAG_TRIM_EXACT = 4,
    XMQ_FLAG_NOMERGE = 8,
    XMQ_FLAG_IXML_ALL_PARSES = 16,
    XMQ_FLAG_IXML_TRY_TO_RECOVER = 32,
    XMQ_FLAG_IXML_FAIL_SILENT = 64,
} XMQFlagBits;

typedef enum XMQColorName {
    XMQ_COLOR_C,
    XMQ_COLOR_Q,
    XMQ_COLOR_E,
    XMQ_COLOR_NS,
    XMQ_COLOR_EN,
    XMQ_COLOR_EK,
    XMQ_COLOR_EKV,
    XMQ_COLOR_AK,
    XMQ_COLOR_AKV,
    XMQ_COLOR_CP,
    XMQ_COLOR_NSD,
    XMQ_COLOR_UW,
    XMQ_COLOR_XLS,
} XMQColorName;

struct XMQReader
{
    void *reader_state;
    size_t (*read)(void *reader_state, char *start, char *stop);
};
typedef struct XMQReader XMQReader;

typedef bool (*XMQWrite)(void *writer_state, const char *start, const char *stop);

struct XMQWriter
{
    void *writer_state;
    XMQWrite write;
};
typedef struct XMQWriter XMQWriter;

typedef enum
{
    XMQ_CONTINUE,
    XMQ_STOP,
} XMQProceed;

typedef XMQProceed (*XMQNodeCallback)(XMQDoc *doc, XMQNode *node, void *user_data);

typedef enum
{
    XMQ_OK = 0,
    XMQ_ERROR_CANNOT_READ_FILE = 1,
    XMQ_ERROR_OOM = 2,
    XMQ_ERROR_NOT_XMQ = 3,
    XMQ_ERROR_QUOTE_NOT_CLOSED = 4,
    XMQ_ERROR_ENTITY_NOT_CLOSED = 5,
    XMQ_ERROR_COMMENT_NOT_CLOSED = 6,
    XMQ_ERROR_COMMENT_CLOSED_WITH_TOO_MANY_SLASHES = 7,
    XMQ_ERROR_BODY_NOT_CLOSED = 8,
    XMQ_ERROR_ATTRIBUTES_NOT_CLOSED = 9,
    XMQ_ERROR_COMPOUND_NOT_CLOSED = 10,
    XMQ_ERROR_COMPOUND_MAY_NOT_CONTAIN = 11,
    XMQ_ERROR_QUOTE_CLOSED_WITH_TOO_MANY_QUOTES = 12,
    XMQ_ERROR_UNEXPECTED_CLOSING_BRACE = 13,
    XMQ_ERROR_EXPECTED_CONTENT_AFTER_EQUALS = 14,
    XMQ_ERROR_UNEXPECTED_TAB = 15,
    XMQ_ERROR_INVALID_CHAR = 16,
    XMQ_ERROR_BAD_DOCTYPE = 17,
    XMQ_ERROR_JSON_INVALID_ESCAPE = 18,
    XMQ_ERROR_JSON_INVALID_CHAR = 19,
    XMQ_ERROR_CANNOT_HANDLE_XML = 20,
    XMQ_ERROR_CANNOT_HANDLE_HTML = 21,
    XMQ_ERROR_CANNOT_HANDLE_JSON = 22,
    XMQ_ERROR_EXPECTED_XMQ = 23,
    XMQ_ERROR_EXPECTED_HTMQ = 24,
    XMQ_ERROR_EXPECTED_XML = 25,
    XMQ_ERROR_EXPECTED_HTML = 26,
    XMQ_ERROR_EXPECTED_JSON = 27,
    XMQ_ERROR_PARSING_XML = 28,
    XMQ_ERROR_PARSING_HTML = 29,
    XMQ_ERROR_VALUE_CANNOT_START_WITH = 30,
    XMQ_ERROR_INVALID_NAMESPACE_URI = 31,
    XMQ_ERROR_INVALID_NAMESPACE_PREFIX = 32,
    XMQ_ERROR_NAMESPACE_PREFIX_ALREADY_TAKEN = 33,
    XMQ_ERROR_BAD_RANGE = 35,
    XMQ_ERROR_BAD_VALUE = 36,
    XMQ_ERROR_IXML_SYNTAX_ERROR = 50,
    XMQ_WARNING_QUOTES_NEEDED = 1000
} XMQStatus;
 
struct XMQReturnDoc
{
    XMQStatus status;
    XMQDoc    *doc;
};
typedef struct XMQReturnDoc XMQReturnDoc;
 
struct XMQReturnNode
{
    XMQStatus status;
    XMQNode   *node;
};
typedef struct XMQReturnNode XMQReturnNode;
 
struct XMQReturnAttr
{
    XMQStatus status;
    XMQAttr   *attr;
};
typedef struct XMQReturnAttr XMQReturnAttr;
 
struct XMQReturnString
{
    XMQStatus status;
    char *string;
};
typedef struct XMQReturnString XMQReturnString;
 
struct XMQReturnConstString
{
    XMQStatus status;
    const char *string;
};
typedef struct XMQReturnConstString XMQReturnConstString;

typedef enum
{
    XMQ_CORE_BOOL,
    XMQ_CORE_I8,
    XMQ_CORE_I16,
    XMQ_CORE_I32,
    XMQ_CORE_I64,
    XMQ_CORE_I128,
    XMQ_CORE_U8,
    XMQ_CORE_U16,
    XMQ_CORE_U32,
    XMQ_CORE_U64,
    XMQ_CORE_U128,

    XMQ_CORE_F32,
    XMQ_CORE_F64,

    XMQ_CORE_STRING,
    XMQ_CORE_EMAIL,
    XMQ_CORE_URI,
    XMQ_CORE_URL,

    XMQ_CORE_IP_ADDRESS,
    XMQ_CORE_IPV4_ADDRESS,
    XMQ_CORE_IPV6_ADDRESS,

    XMQ_BINARY_BASE64
 
} XMQCoreType;
 
typedef struct XMQLineConfig XMQLineConfig;


XMQContentType xmqDetectContentType(const char *start, const char *stop);

const char *xmqParseErrorToString(XMQStatus e);

XMQParseCallbacks *xmqNewParseCallbacks();

void xmqFreeParseCallbacks(XMQParseCallbacks *cb);

void xmqSetupParseCallbacksColorizeTokens(XMQParseCallbacks *state, XMQRenderFormat render_format);

void xmqSetupParseCallbacksDebugTokens(XMQParseCallbacks *state);

void xmqSetupParseCallbacksDebugContent(XMQParseCallbacks *state);

bool xmqTokenizeBuffer(XMQParseState *state, const char *start, const char *stop);

bool xmqTokenizeFile(XMQParseState *state, const char *file);

bool xmqTokenizeFileDescriptor(XMQParseState *state, int fd);

XMQParseState *xmqNewParseState(XMQParseCallbacks *callbacks, XMQOutputSettings *settings);

void xmqFreeParseState(XMQParseState *state);

void xmqSetStateSourceName(XMQParseState *state, const char *source_name);

int xmqStateErrno(XMQParseState *state);

const char *xmqStateErrorMsg(XMQParseState *state);

void xmqSetPrintAllParsesIXML(XMQParseState *state, bool all_parses);

void xmqSetTryToRecoverIXML(XMQParseState *state, bool try_recover);

XMQReturnDoc xmqNewDoc();

void xmqSetDocSourceName(XMQDoc *doq, const char *source_name);

const char *xmqGetDocSourceName(XMQDoc *doq);

XMQContentType xmqGetOriginalContentType(XMQDoc *doq);

size_t xmqGetOriginalSize(XMQDoc *doq);

void xmqSetOriginalSize(XMQDoc *doq, size_t size);

XMQNode *xmqGetRootNode(XMQDoc *doq);
 
typedef enum
{
    XMQ_NS_NONE,
    XMQ_NS_PARENT,
    XMQ_NS_HERE,
    XMQ_NS_ANCESTOR
}
NamespaceAction;
 
typedef struct XMQNS XMQNS;
struct XMQNS {
    NamespaceAction action;
    // A prefix (xyz) can be encoded into the uri: "{xyz}urn:myapp"
    const char *uri;
};

#define NS_NONE   ((XMQNS){XMQ_NS_NONE,NULL})
#define NS_PARENT ((XMQNS){XMQ_NS_PARENT,NULL})
#define NS_HERE(uri) ((XMQNS){XMQ_NS_HERE,uri})
#define NS_ANCESTOR(uri) ((XMQNS){XMQ_NS_ANCESTOR,uri})

XMQReturnNode xmqAddRootElement(XMQDoc *doq, const char *name, XMQNS ns);

XMQReturnNode xmqAddElement(XMQDoc *doq, XMQNode *parent, const char *name, XMQNS ns);

XMQReturnNode xmqAddKeyValue(XMQDoc *doq, XMQNode *parent, const char *key, const char *value, XMQNS ns);

XMQReturnAttr xmqSetAttribute(XMQDoc *doq, XMQNode *node, const char *name, const char *value, XMQNS ns);

XMQStatus xmqAddNamespace(XMQDoc *doq, XMQNode *node, XMQNS ns);

XMQReturnString xmqChangePrefix(XMQDoc *doq,
                                XMQNode *node,
                                const char *ns_uri,
                                const char *old_prefix,
                                const char *new_prefix);

void *xmqGetImplementationDoc(XMQDoc *doq);

void xmqSetImplementationDoc(XMQDoc *doq, void *doc);

void xmqClearDoc(XMQDoc *doc);

void xmqFreeDoc(XMQDoc *doc);

bool xmqParseFile(XMQDoc *doc, const char *file, const char *implicit_root, int flags);

bool xmqParseBuffer(XMQDoc *doc, const char *start, const char *stop, const char *implicit_root, int flags);

bool xmqParseReader(XMQDoc *doc, XMQReader *reader, void *reader_state, const char *implicit_root, int flags);

XMQOutputSettings *xmqNewOutputSettings();

void xmqFreeOutputSettings(XMQOutputSettings *os);
 
void xmqSetAddIndent(XMQOutputSettings *os, int add_indent);
void xmqSetCompact(XMQOutputSettings *os, bool compact);
void xmqSetUseColor(XMQOutputSettings *os, bool use_color);
void xmqSetTrueColor(XMQOutputSettings *os, bool truecolor);
void xmqSetBackgroundMode(XMQOutputSettings *os, bool bg_dark_mode);
void xmqSetPreferDoubleQuotes(XMQOutputSettings *os, bool prefer_double_quotes);
void xmqSetEscapeNewlines(XMQOutputSettings *os, bool escape_newlines);
void xmqSetEscapeNon7bit(XMQOutputSettings *os, bool escape_non_7bit);
void xmqSetEscapeTabs(XMQOutputSettings *os, bool escape_tabs);
void xmqSetOutputFormat(XMQOutputSettings *os, XMQContentType output_format);
void xmqSetOmitDecl(XMQOutputSettings *os, bool omit_decl);
void xmqSetRenderFormat(XMQOutputSettings *os, XMQRenderFormat render_to);
void xmqSetRenderTheme(XMQOutputSettings *os, const char *theme_spec);
void xmqSetRenderRaw(XMQOutputSettings *os, bool render_raw);
void xmqSetRenderOnlyStyle(XMQOutputSettings *os, bool only_style);
void xmqSetWriterContent(XMQOutputSettings *os, XMQWriter content);
void xmqSetWriterError(XMQOutputSettings *os, XMQWriter error);

void xmqSetupPrintStdOutStdErr(XMQOutputSettings *ps);

void xmqSetupPrintFile(XMQOutputSettings *ps, const char *file);

void xmqSetupPrintFileDescriptor(XMQOutputSettings *ps, int fd);

void xmqSetupPrintMemory(XMQOutputSettings *ps, char **start, char **stop);

void xmqSetupPrintSkip(XMQOutputSettings *ps, size_t *skip);

void xmqPrint(XMQDoc *doc, XMQOutputSettings *settings);

void xmqAnnotateOffsets(XMQDoc *doc, const char *attribute_name, const char *ns);

void xmqTrimWhitespace(XMQDoc *doc, int flags);

char *xmqCompactQuote(const char *content);

const char *xmqDocError(XMQDoc *doc);

XMQStatus xmqDocErrno(XMQDoc *doc);

const char *xmqGetName(XMQNode *node);

const char *xmqGetContent(XMQNode *node);

void xmqSetContent(XMQNode *node, const char *raw_content);

XMQNode *xmqGetNode(XMQDoc *doc, const char *xpath);

XMQNode *xmqGetNodeRel(XMQDoc *doc, const char *xpath, XMQNode *relative);

int32_t xmqGetInt(XMQDoc *doc, const char *xpath);

int32_t xmqGetIntRel(XMQDoc *doc, const char *xpath, XMQNode *relative);

int64_t xmqGetLong(XMQDoc *doc, const char *xpath);

int64_t xmqGetLongRel(XMQDoc *doc, const char *xpath, XMQNode *relative);

double xmqGetDouble(XMQDoc *doc, const char *xpath);

double xmqGetDoubleRel(XMQDoc *doc, const char *xpath, XMQNode *relative);

const char *xmqGetString(XMQDoc *doc, const char *xpath);

const char *xmqGetStringRel(XMQDoc *doc, const char *xpath, XMQNode *relative);

int xmqForeach(XMQDoc *doq, const char *xpath, XMQNodeCallback cb, void *user_data);

int xmqForeachRel(XMQDoc *doq, const char *xpath, XMQNodeCallback cb, void *user_data, XMQNode *relative);

int xmqReplaceEntity(XMQDoc *doq, const char *entity, const char *content);

int xmqReplaceEntityWithNode(XMQDoc *doq, const char *entity, XMQDoc *idoq, XMQNode *inode);

const char *xmqVersion();

void xmqSetVerbose(bool e);

void xmqSetDebug(bool e);

void xmqSetTrace(bool e);

void xmqLogFilter(const char *log_filter);

bool xmqDebugging();

bool xmqTracing();

void xmqSetLogHumanReadable(bool e);

bool xmqLoggingXMQ();

bool xmqParseBufferWithType(XMQDoc *doc,
                            const char *start,
                            const char *stop,
                            const char *implicit_root,
                            XMQContentType ct,
                            int flags);

bool xmqParseFileWithType(XMQDoc *doc,
                          const char *file,
                          const char *implicit_root,
                          XMQContentType ct,
                          int flags);

bool xmqParseBufferWithIXML(XMQDoc *doc,
                            const char *start,
                            const char *stop,
                            XMQDoc *ixml_grammar,
                            int flags);

bool xmqParseFileWithIXML(XMQDoc *doc,
                          const char *file,
                          XMQDoc *ixml_grammar,
                          int flags);

void xmqSetupDefaultColors(XMQOutputSettings *settings);

void xmqOverrideSettings(XMQOutputSettings *settings,
                         const char *indentation_space,
                         const char *explicit_space,
                         const char *explicit_tab,
                         const char *explicit_cr,
                         const char *explicit_nl);

void xmqRenderHtmlSettings(XMQOutputSettings *settings,
                           const char *use_id,
                           const char *use_class);

void xmqOverrideColor(XMQOutputSettings *settings,
                      const char *render_style,
                      XMQColorName cn,
                      const char *pre,
                      const char *post,
                      const char *ns);
 

XMQLineConfig *xmqNewLineConfig();

void xmqFreeLineConfig(XMQLineConfig *lc);

void xmqSetLineHumanReadable(XMQLineConfig *lc, bool enable);

char *xmqLineDoc(XMQLineConfig *lc, XMQDoc *doc);

char *xmqLinePrintf(XMQLineConfig *lc, const char *element_name, ...);
char *xmqLineVPrintf(XMQLineConfig *lc, const char *element_name, va_list ap);
 
#ifdef __cplusplus
_hideRBfromEditor
#endif
 
#endif