Mercurial > repo
diff interps/cfunge/cfunge-src/lib/genx/genx.h @ 996:859f9b4339e6
<Gregor> tar xf egobot.tar.xz
author | HackBot |
---|---|
date | Sun, 09 Dec 2012 19:30:08 +0000 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/interps/cfunge/cfunge-src/lib/genx/genx.h Sun Dec 09 19:30:08 2012 +0000 @@ -0,0 +1,320 @@ +/** + * @file + * genx - C-callable library for generating XML documents + */ + +#ifndef GENX_H +#define GENX_H + +/* + * Copyright (c) 2004 by Tim Bray and Sun Microsystems. For copying + * permission, see http://www.tbray.org/ongoing/genx/COPYING + */ + +#include "../../src/global.h" + +#if !defined(CFUN_NO_FLOATS) && !defined(CFUN_NO_TURT) + +#include <stdio.h> + +/** + * @defgroup genx Genx - XML generation functions + * A library for writing XML. + */ +/*@{*/ + +/** + * 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 +/** character types */ +#define GENX_LETTER 2 +/** character types */ +#define GENX_NAMECHAR 4 + +/** + * @defgroup genx_types Genx's types + */ +/*@{*/ +/** An UTF-8 string */ +typedef unsigned char * utf8; +/** A const UTF-8 string */ +typedef const unsigned char * constUtf8; + +/// A writer, the main struct. +typedef struct genxWriter_rec * genxWriter; +/// A namespace. +typedef struct genxNamespace_rec * genxNamespace; +/// An element. +typedef struct genxElement_rec * genxElement; +/// An attribute. +typedef struct genxAttribute_rec * genxAttribute; +/*@}*/ + +/* + * 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. + * @return NULL if it fails, which can only be due to an allocation failure. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_MALLOC FUNGE_ATTR_WARN_UNUSED +genxWriter genxNew(void); + +/** + * Dispose of a writer, freeing all associated memory + */ +FUNGE_ATTR_FAST +void genxDispose(genxWriter w); + +/* + * Set/get + */ + +/** + * Get the prefix associated with a namespace + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +utf8 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 + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +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 + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxElement genxDeclareElement(genxWriter w, + genxNamespace ns, constUtf8 type, + genxStatus * statusP); + +/** + * Declare an attribute + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxAttribute genxDeclareAttribute(genxWriter w, + genxNamespace ns, + constUtf8 name, genxStatus * statusP); + +/* + * Writing XML + */ + +/** + * Start a new document. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxStartDocFile(genxWriter w, FILE * file); + +/** + * 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; + +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxStartDocSender(genxWriter w, genxSender * sender); + +/** + * End a document. Calls "flush" + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxEndDocument(genxWriter w); + +/** + * Write a comment + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxComment(genxWriter w, constUtf8 text); + +/** + * Write a PI + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxPI(genxWriter w, constUtf8 target, constUtf8 text); + +/** + * Start an element + */ +FUNGE_ATTR_FAST +genxStatus genxStartElementLiteral(genxWriter w, + constUtf8 xmlns, constUtf8 type); + +/** + * Start a predeclared element + * - element must have been declared + */ +FUNGE_ATTR_FAST +genxStatus genxStartElement(genxElement e); + +/** + * Write an attribute + */ +FUNGE_ATTR_FAST +genxStatus genxAddAttributeLiteral(genxWriter w, constUtf8 xmlns, + constUtf8 name, constUtf8 value); + +/** + * Write a predeclared attribute + */ +FUNGE_ATTR_FAST +genxStatus genxAddAttribute(genxAttribute a, constUtf8 value); + +/** + * Add a namespace declaration + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxAddNamespace(genxNamespace ns, utf8 prefix); + +/** + * Clear default namespace declaration + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxUnsetDefaultNamespace(genxWriter w); + +/** + * Write an end tag + */ +FUNGE_ATTR_FAST +genxStatus genxEndElement(genxWriter w); + +/** + * Write some text + * You can't write any text outside the root element, except with + * genxComment and genxPI + */ +FUNGE_ATTR_FAST +genxStatus genxAddText(genxWriter w, constUtf8 start); +FUNGE_ATTR_FAST +genxStatus genxAddCountedText(genxWriter w, constUtf8 start, int byteCount); +FUNGE_ATTR_FAST +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. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +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. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +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 + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +genxStatus genxCheckText(const genxWriter restrict w, constUtf8 s); + +/** + * Return character status, the OR of GENX_XML_CHAR, + * GENX_LETTER, and GENX_NAMECHAR + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +int genxCharClass(const genxWriter restrict 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. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +int genxScrubText(const genxWriter restrict w, constUtf8 in, utf8 out); + +/** + * Return a specific error message. + * @param w The genxWriter in question. + * @param status What status to look up. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +const char * genxGetErrorMessage(const genxWriter restrict w, genxStatus status); +/** + * Return last error message. + * @param w The genxWriter in question. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +const char * genxLastErrorMessage(const genxWriter restrict w); + +/** + * Return version of genx. + */ +FUNGE_ATTR_FAST FUNGE_ATTR_WARN_UNUSED +const char * genxGetVersion(void); + +/*@}*/ + +#ifdef GENX_INTERNAL +FUNGE_ATTR_FAST void genxSetCharProps(char * restrict p); +#endif + +#endif /* !defined(CFUN_NO_FLOATS) && !defined(CFUN_NO_TURT) */ + +#endif /* GENX_H */