This is the reference documentation for using Ali to input XML documents. It is a simple to use C library that reduces the amount of code needed to parse XML.
The header file ali.h declares the Ali API. For more information and examples on using Ali, see the Tutorial and explore the provided test code.
Open an Ali document for input.
ali_element_ref ali_open(ali_doc_info **doc, const char *file_name, uint32_t options, void *data)
the document to input from
the name of the XML file that the document inputs data from. The file may be encoded using UTF-8, ISO-8859-1 or US-ASCII. The encodings UTF-16 and UTF-32 are rejected. Others will be tried and should work if they are like C strings (nul terminated).
options for inputing, like expecting xml declarations
data passed to callbacks. Usually a pointer to an app structure used to store the document's data. Set to NULL if your app does not need it.
A non zero value is a valid ali_element_ref which means the XML document was successfully opened for reading. Use the ali_element_ref to read from the XML document by passing it to ali_in. A zero indicates an error opening the document. Check stdio's errno to determine the error's cause.
Start input from the file named and return an ali_element_ref needed by all other Ali functions. Optionally parse a declaration.
Close an Ali document.
void ali_close(ali_doc_info *doc)
the document to input from
Stop input from the Ali document. Further use of the document is an error.
Input some XML formatted data.
ali_element_ref ali_in(ali_doc_info *doc, ali_element_ref element, const char *format,...)
the document to input from
which XML element in the document to input from
C string containing the text and XML instructions to input. This indicates how to interpret all following arguments.
The ali_element_ref of the element being read, or 0.
Input data from doc at element according to the format specified. The format is a C string containing text, XML instructions to read XML structures, and scanf like rules to input the document text and save in the arguments.
Text is input as is, except the XML entities for &<>" are converted.
The syntax of an XML instruction is:
format is a string that consists of a repeatable set that lists what data to find and then parsing instructions: [XML Instructions[Parsing Instructions]*]*
XML Instructions = '^' [o]?[eac]
If a XML instruction is not matched (because the document contains no matching XML data) then the following parsing instruction is skipped.
Parsing Instructions = prefix_chars*%[lh]?[a]?[width]?[scdiux]suffix_chars*
If the element is not the current element, then the elements are closed until the correct element is reached. If the correct element is not reached, then DOLATER.
Is this the first time an element has been read?
bool ali_is_element_new(const ali_doc_info *doc, ali_element_ref element)
the document to input from
which XML element in the document to input from
true if the element has been read once, false if read more than once.
This is often used to know when to allocate, initialize, or construct information for an element that contains lots of data.
Is this the final time an element will be read?
bool ali_is_element_done(const ali_doc_info *doc, ali_element_ref element)
the document to input from
which XML element in the document to input from
false if the element will be read more, true if not.
This is generally used to see if all the data is read so that a structure or object can be created or closed or finalized.
Get the error status of an Ali document.
ali_error ali_get_error(ali_doc_info *doc)
the document to input from
An ali_error code like ALI_ERROR_NONE.
A successfully read document will always have the status ALI_ERROR_NONE. Once the status is set to another code, it will remain set until the document is closed.
Set the error status of an Ali document.
void ali_set_error(ali_doc_info *doc, ali_error new_error)
the document to input from
the new error code to use.
Often used by the app to set the error status to ALI_ERROR_MEMORY_FAILURE when it cannot allocate neccesary structures to store the XML document's data.
The success status of inputting the XML document.
Will be ALI_ERROR_NONE until a problem occurs, at which point it gets one of the other values.
typedef int16_t ali_error
An ID number for the namespace.
Used to specify the namespace for an element input by Ali.
typedef int16_t ali_namespace_ref
An ID number for the element.
Used to confirm operating at the right element.
typedef int16_t ali_element_ref
Where in the document to input information from.
typedef struct ali_element_info ali_element_info
All information needed to read an XML document opened for input.
typedef struct ali_doc_info ali_doc_info
Called to handle matching XML elements.
The app provided function takes control of the input and should read all important data within the element, storing it in app data structures as appropriate. It is one technique to read elements that occur multiple times, and it can be used to factor code into smaller pieces.
typedef void ali_element_function(ali_doc_info *doc, ali_element_ref element, void *data)
The XML must have an XML declaration. Use this to ensure that the document is well formed.
Convert input from UTF-8 to ISO-8859-1.
Useful to read XML in code running in legacy environments.
Status of it's inclusion into the API is experimental until experience shows enough apps justify permanent inclusion.
A requested element or attribute is missing from the input.
Generally an app would want to reject the XML document.
The element is missing content.
The app requires the element to contain content like a number but it is empty.
The file to be opened for input is missing.
Try checking stdio's errno to determine the exact reason.
There is insufficient memory to read this XML document.
ali_in is requested to read data from an element that is no longer opened or never was.
The element or attributes name is invalid. The allowed names are document at https://www.w3.org/TR/REC-xml#NT-Stag and https://www.w3.org/TR/REC-xml#NT-Attribute
The namespace parameter is not supported. Put the entire qualified name in the local part parameter.
The XML document ended before all data was read.
The XML document is encoded in a format not supported.
UTF-8, ISO-8859-X, and US-ASCII are supported. Others like UTF-16 are not.
The XML declaration, which starts the document, is not well-formed.
The file is not an XML document, based on the missing XML declaration when one is expected.
The XML Instruction is not known.
XML Instructions, like "^e", are passed to ali_in. The ali_in documentation lists all valid instructions.
The tag may not be NULL.
An XML Instruction, like "^e", was passed NULL for the tag name.