From b0396809c19f436e051430d5e81d59a725611195 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 24 Jul 2020 09:13:21 +0200 Subject: Convert to build2-based build Also add symbol exporting, missing const in a few places in the API, as well as a basic test. --- libgenx/libgenx/genx.h | 453 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 453 insertions(+) create mode 100644 libgenx/libgenx/genx.h (limited to 'libgenx/libgenx/genx.h') diff --git a/libgenx/libgenx/genx.h b/libgenx/libgenx/genx.h new file mode 100644 index 0000000..8c03e7e --- /dev/null +++ b/libgenx/libgenx/genx.h @@ -0,0 +1,453 @@ +/* + * genx - C-callable library for generating XML documents + */ + +/* + * Copyright (c) 2004 by Tim Bray and Sun Microsystems. + * Copyright (c) Code Synthesis Tools CC (see the LICENSE file). + * + * For copying permission, see the accompanying LICENSE file. + */ + +#ifndef GENX_H +#define GENX_H + +#include /* size_t */ + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* + * Note on error handling: genx routines mostly return + * GENX_SUCCESS (guaranteed to be zero) in normal circumstances, one of + * these other GENX_ values on a memory allocation or I/O failure or if the + * call would result in non-well-formed output. + * You can associate an error message with one of these codes explicitly + * or with the most recent error using genxGetErrorMessage() and + * genxLastErrorMessage(); see below. + */ +typedef enum +{ + GENX_SUCCESS = 0, + GENX_BAD_UTF8, + GENX_NON_XML_CHARACTER, + GENX_BAD_NAME, + GENX_ALLOC_FAILED, + GENX_BAD_NAMESPACE_NAME, + GENX_INTERNAL_ERROR, + GENX_DUPLICATE_PREFIX, + GENX_SEQUENCE_ERROR, + GENX_NO_START_TAG, + GENX_IO_ERROR, + GENX_MISSING_VALUE, + GENX_MALFORMED_COMMENT, + GENX_XML_PI_TARGET, + GENX_MALFORMED_PI, + GENX_DUPLICATE_ATTRIBUTE, + GENX_ATTRIBUTE_IN_DEFAULT_NAMESPACE, + GENX_DUPLICATE_NAMESPACE, + GENX_BAD_DEFAULT_DECLARATION +} genxStatus; + +/* character types */ +#define GENX_XML_CHAR 1 +#define GENX_LETTER 2 +#define GENX_NAMECHAR 4 + +/* The size of the character table. Valid values are 0x100 (first 255 + chars are checked) and 0x10000 (all chars are checked). */ +#ifndef GENX_CHAR_TABLE_SIZE +# define GENX_CHAR_TABLE_SIZE 0x100 +#endif + +/* a UTF-8 string */ +typedef unsigned char * utf8; +typedef const unsigned char * constUtf8; + +/* + * genx's own types + */ +typedef struct genxWriter_rec * genxWriter; +typedef struct genxNamespace_rec * genxNamespace; +typedef struct genxElement_rec * genxElement; +typedef struct genxAttribute_rec * genxAttribute; + +typedef void * (*genxAlloc) (void * userData, size_t bytes); +typedef void (*genxDealloc) (void * userData, void* data); + +/* + * Constructors, set/get + */ + +/* + * Create a new writer. For generating multiple XML documents, it's most + * efficient to re-use the same genx object. However, you can only write + * one document at a time with a writer. + * Returns NULL if it fails, which can only be due to an allocation failure. + */ +LIBGENX_SYMEXPORT +genxWriter genxNew(genxAlloc alloc, genxDealloc dealloc, void * userData); + +/* + * Reset the writer object back into usable state after an error or + * interruption. + */ +LIBGENX_SYMEXPORT +genxStatus genxReset (genxWriter w); + +/* + * Dispose of a writer, freeing all associated memory + */ +LIBGENX_SYMEXPORT +void genxDispose(genxWriter w); + +/* + * Set/get + */ + +/* + * The userdata pointer will be passed to memory-allocation + * and I/O callbacks. If not set, genx will pass NULL + */ +LIBGENX_SYMEXPORT +void genxSetUserData(genxWriter w, void * userData); + +LIBGENX_SYMEXPORT +void * genxGetUserData(genxWriter w); + +/* + * Set/get pretty-printing. If indentation is set to 0, then no pretty- + * printing is performed. + */ +LIBGENX_SYMEXPORT +genxStatus genxSetPrettyPrint(genxWriter w, int indentation); + +LIBGENX_SYMEXPORT +int genxGetPrettyPrint(genxWriter w); + +/* + * Suspend/resume pretty-printing. Pretty-printing can be suspended + * only inside an element and, unless explicitly resumed, it will + * remain suspended until the end of that element. You should only + * explicitly resume pretty-printing at the element nesting level + * of suspension. If pretty-printing is already suspended at an + * outer nesting level, then subsequent calls to suspend/resume + * are ignored. The PrettyPrintSuspended() function can be used + * to check if pretty-printing is currently suspended. If it is + * not, then this function returns 0. Otherwise, it returns the + * level at which pretty-printing was suspended, with root element + * being level 1. + */ +LIBGENX_SYMEXPORT +genxStatus genxSuspendPrettyPrint(genxWriter w); + +LIBGENX_SYMEXPORT +genxStatus genxResumePrettyPrint(genxWriter w); + +LIBGENX_SYMEXPORT +int genxPrettyPrintSuspended(genxWriter w); + + +/* + * Set/get canonicalization. If true, then output explicit closing + * tags and sort attributes. Default is false. + */ +LIBGENX_SYMEXPORT +genxStatus genxSetCanonical(genxWriter w, int flag); + +LIBGENX_SYMEXPORT +int genxGetCanonical(genxWriter w); + +/* + * User-provided memory allocator, if desired. For example, if you were + * in an Apache module, you could arrange for genx to use ap_palloc by + * making the pool accessible via the userData call. + * The "dealloc" is to be used to free memory allocated with "alloc". If + * alloc is provided but dealloc is NULL, genx will not attempt to free + * the memory; this would be appropriate in an Apache context. + * If "alloc" is not provided, genx routines use malloc() to allocate memory + */ +LIBGENX_SYMEXPORT +void genxSetAlloc(genxWriter w, genxAlloc alloc); + +LIBGENX_SYMEXPORT +void genxSetDealloc(genxWriter w, genxDealloc dealloc); + +LIBGENX_SYMEXPORT +genxAlloc genxGetAlloc(genxWriter w); + +LIBGENX_SYMEXPORT +genxDealloc genxGetDealloc(genxWriter w); + +/* + * Get the prefix associated with a namespace + */ +LIBGENX_SYMEXPORT +constUtf8 genxGetNamespacePrefix(genxNamespace ns); + +/* + * Declaration functions + */ + +/* + * Declare a namespace. The provided prefix is the default but can be + * overridden by genxAddNamespace. If no default prefiix is provided, + * genx will generate one of the form g-%d. + * On error, returns NULL and signals via statusp + */ +LIBGENX_SYMEXPORT +genxNamespace genxDeclareNamespace(genxWriter w, + constUtf8 uri, constUtf8 prefix, + genxStatus * statusP); + +/* + * Declare an element + * If something failed, returns NULL and sets the status code via statusP + */ +LIBGENX_SYMEXPORT +genxElement genxDeclareElement(genxWriter w, + genxNamespace ns, constUtf8 name, + genxStatus * statusP); + +/* + * Declare an attribute + */ +LIBGENX_SYMEXPORT +genxAttribute genxDeclareAttribute(genxWriter w, + genxNamespace ns, + constUtf8 name, genxStatus * statusP); + +/* + * Writing XML + */ + +/* + * Caller-provided I/O package. + * First form is for a null-terminated string. + * for second, if you have s="abcdef" and want to send "abc", you'd call + * sendBounded(userData, s, s + 3) + */ +typedef struct +{ + genxStatus (* send)(void * userData, constUtf8 s); + genxStatus (* sendBounded)(void * userData, constUtf8 start, constUtf8 end); + genxStatus (* flush)(void * userData); +} genxSender; + +LIBGENX_SYMEXPORT +genxStatus genxStartDocSender(genxWriter w, const genxSender * sender); + +/* + * End a document. Calls "flush". + */ +LIBGENX_SYMEXPORT +genxStatus genxEndDocument(genxWriter w); + +/* + * Write XML declaration. If encoding or standalone are NULL, then those + * attributes are omitted. + */ +LIBGENX_SYMEXPORT +genxStatus genxXmlDeclaration(genxWriter w, + constUtf8 version, + constUtf8 encoding, + constUtf8 standalone); +/* + * Write DOCTYPE declaration. If public_id is not NULL, then this is + * a PUBLIC DOCTYPE declaration, otherwise, if system_id is not NULL, + * then this is a SYSTEM DOCTYPE. If both are NULL, then a DOCTYPE + * that only contains the root element and, if not NULL, internal + * subset is written. + */ +LIBGENX_SYMEXPORT +genxStatus genxDoctypeDeclaration(genxWriter w, + constUtf8 root_element, + constUtf8 public_id, + constUtf8 system_id, + constUtf8 internal_subset); + +/* + * Write a comment + */ +LIBGENX_SYMEXPORT +genxStatus genxComment(genxWriter w, constUtf8 text); + +/* + * Write a PI + */ +LIBGENX_SYMEXPORT +genxStatus genxPI(genxWriter w, constUtf8 target, constUtf8 text); + +/* + * Start an element + */ +LIBGENX_SYMEXPORT +genxStatus genxStartElementLiteral(genxWriter w, + constUtf8 xmlns, constUtf8 name); + +/* + * Start a predeclared element + * - element must have been declared + */ +LIBGENX_SYMEXPORT +genxStatus genxStartElement(genxElement e); + +/* + * Get current element. The returned values are valid until this + * element ceases to be current (i.e., EndElement() is called). + * If the element is unqualified, then xmlns is set to NULL. + */ +LIBGENX_SYMEXPORT +genxStatus genxGetCurrentElement (genxWriter w, + constUtf8* xmlns, constUtf8* name); + +/* + * Write an attribute + */ +LIBGENX_SYMEXPORT +genxStatus genxAddAttributeLiteral(genxWriter w, constUtf8 xmlns, + constUtf8 name, constUtf8 value); + +/* + * Write a predeclared attribute + */ +LIBGENX_SYMEXPORT +genxStatus genxAddAttribute(genxAttribute a, constUtf8 value); + +/* + * Start an attribute + */ +LIBGENX_SYMEXPORT +genxStatus genxStartAttributeLiteral(genxWriter w, + constUtf8 xmlns, constUtf8 name); + +/* + * Start a predeclared attribute + */ +LIBGENX_SYMEXPORT +genxStatus genxStartAttribute(genxAttribute a); + +/* + * Get current attribute. The returned values are valid until this + * attribute ceases to be current (i.e., EndAttribute() is called). + * If the attribute is unqualified, then xmlns is set to NULL. + */ +LIBGENX_SYMEXPORT +genxStatus genxGetCurrentAttribute (genxWriter w, + constUtf8* xmlns, constUtf8* name); + +/* + * End an attribute + */ +LIBGENX_SYMEXPORT +genxStatus genxEndAttribute(genxWriter w); + +/* + * add a namespace declaration + */ +LIBGENX_SYMEXPORT +genxStatus genxAddNamespaceLiteral(genxWriter w, + constUtf8 uri, constUtf8 prefix); + +/* + * add a predefined namespace declaration + */ +LIBGENX_SYMEXPORT +genxStatus genxAddNamespace(genxNamespace ns, constUtf8 prefix); + +/* + * Clear default namespace declaration + */ +LIBGENX_SYMEXPORT +genxStatus genxUnsetDefaultNamespace(genxWriter w); + +/* + * Write an end tag + */ +LIBGENX_SYMEXPORT +genxStatus genxEndElement(genxWriter w); + +/* + * Write some text + * You can't write any text outside the root element, except with + * genxComment and genxPI. + */ +LIBGENX_SYMEXPORT +genxStatus genxAddText(genxWriter w, constUtf8 start); + +LIBGENX_SYMEXPORT +genxStatus genxAddCountedText(genxWriter w, constUtf8 start, size_t byteCount); + +LIBGENX_SYMEXPORT +genxStatus genxAddBoundedText(genxWriter w, constUtf8 start, constUtf8 end); + +/* + * Write one character. The integer value is the Unicode character + * value, as usually expressed in U+XXXX notation. + */ +LIBGENX_SYMEXPORT +genxStatus genxAddCharacter(genxWriter w, int c); + +/* + * Utility routines + */ + +/* + * Return the Unicode character encoded by the UTF-8 pointed-to by the + * argument, and advance the argument past the encoding of the character. + * Returns -1 if the UTF-8 is malformed, in which case advances the + * argument to point at the first byte past the point past the malformed + * ones. + */ +LIBGENX_SYMEXPORT +int genxNextUnicodeChar(constUtf8 * sp); + +/* + * Scan a buffer allegedly full of UTF-8 encoded XML characters; return + * one of GENX_SUCCESS, GENX_BAD_UTF8, or GENX_NON_XML_CHARACTER + */ +LIBGENX_SYMEXPORT +genxStatus genxCheckText(genxWriter w, constUtf8 s); + +/* + * return character status, the OR of GENX_XML_CHAR, + * GENX_LETTER, and GENX_NAMECHAR + */ +LIBGENX_SYMEXPORT +int genxCharClass(genxWriter w, int c); + +/* + * Silently wipe any non-XML characters out of a chunk of text. + * If you call this on a string before you pass it addText or + * addAttribute, you will never get an error from genx unless + * (a) there's a bug in your software, e.g. a malformed element name, or + * (b) there's a memory allocation or I/O error + * The output can never be longer than the input. + * Returns true if any changes were made. + */ +LIBGENX_SYMEXPORT +int genxScrubText(genxWriter w, constUtf8 in, utf8 out); + +/* + * return error messages + */ +LIBGENX_SYMEXPORT +const char * genxGetErrorMessage(genxWriter w, genxStatus status); + +LIBGENX_SYMEXPORT +const char * genxLastErrorMessage(genxWriter w); + +/* + * return version + */ +LIBGENX_SYMEXPORT +const char * genxGetVersion(); + +#ifdef __cplusplus +} +#endif + +#endif /* GENX_H */ -- cgit v1.1