Ali Reference

Functions

ali_open ali_close ali_in ali_is_element_new ali_is_element_done ali_get_error ali_set_error

Types

ali_error ali_namespace_ref ali_element_ref ali_element_info ali_doc_info ali_element_function

Constants

ALI_OPTION_NONE ALI_OPTION_INPUT_XML_DECLARATION ALI_OPTION_EXP_CONVERT_UTF8_TO_ISO_8859_1 ALI_ERROR_BASE ALI_ERROR_NONE ALI_ERROR_TAG_MISSING ALI_ERROR_CONTENT_MISSING ALI_ERROR_FILE_MISSING ALI_ERROR_MEMORY_FAILURE ALI_ERROR_ELEMENT_INVALID ALI_ERROR_TAG_INVALID ALI_ERROR_NAMESPACE_INVALID ALI_ERROR_DATA_INCOMPLETE ALI_ERROR_ENCODING_UNSUPPORTED ALI_ERROR_XML_DECLARATION_INVALID ALI_ERROR_NOT_XML_DOCUMENT ALI_ERROR_UNKNOWN_XML_INSTRUCTION ALI_ERROR_NULL_TAG

Description

This is the reference documentation for using Ali to input XML documents. It is a simple to use library that reduces the amount of code needed to output XML.

The header file ali.h declares the Ali API. For more information and examples on using Ali, see the Tutorial.

Functions

ali_openTOP

Open an Ali document for input.

Prototype

ali_element_ref ali_open(ali_doc_info **doc, const char *file_name, uint32_t options, void *data)

Parameters

doc

the document to input from

file_name

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

options for inputing, like expecting xml declarations

data

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.

Returns

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.

Comments

Start input from the file named and return an ali_element_ref needed by all other Ali functions. Optionally parse a declaration.

See Also

ali_in
ali_close

ali_closeTOP

Close an Ali document.

Prototype

void ali_close(ali_doc_info *doc)

Parameters

doc

the document to input from

Comments

Stop input from the Ali document. Further use of the document is an error.

See Also

ali_open
ali_in

ali_inTOP

Input some XML formatted data.

Prototype

ali_element_ref ali_in(ali_doc_info *doc, ali_element_ref element, const char *format,...)

Parameters

doc

the document to input from

element

which XML element in the document to input from

format

C string containing the text and XML instructions to input. This indicates how to interpret all following arguments.

Returns

The ali_element_ref of the element being read, or 0.

Comments

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.

See Also

ali_open
ali_is_element_new
ali_close
ali_get_error

ali_is_element_newTOP

Is this the first time an element has been read?

Prototype

bool ali_is_element_new(const ali_doc_info *doc, ali_element_ref element)

Parameters

doc

the document to input from

element

which XML element in the document to input from

Returns

true if the element has been read once, false if read more than once.

Comments

This is often used to know when to allocate, initialize, or construct information for an element that contains lots of data.

See Also

ali_in

ali_is_element_doneTOP

Prototype

bool ali_is_element_done(const ali_doc_info *doc, ali_element_ref element)

Parameters

doc

the document to input from

element

which XML element in the document to input from

ali_get_errorTOP

Get the error status of an Ali document.

Prototype

ali_error ali_get_error(ali_doc_info *doc)

Parameters

doc

the document to input from

Returns

An ali_error code like ALI_ERROR_NONE.

Comments

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.

See Also

ali_in
ali_set_error

ali_set_errorTOP

Set the error status of an Ali document.

Prototype

void ali_set_error(ali_doc_info *doc, ali_error new_error)

Parameters

doc

the document to input from

new_error

the new error code to use.

Comments

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.

See Also

ali_in
ali_get_error

Types

ali_errorTOP

The success status of inputting the XML document.

Comments

Will be ALI_ERROR_NONE until a problem occurs, at which point it gets one of the other values.

Prototype

typedef int16_t ali_error

ali_namespace_refTOP

An ID number for the namespace.

Comments

Used to specify the namespace for an element input by Ali.

Prototype

typedef int16_t ali_namespace_ref

ali_element_refTOP

An ID number for the element.

Comments

Used to confirm operating at the right element.

Prototype

typedef int16_t ali_element_ref

ali_element_infoTOP

Where in the document to input information from.

Prototype

typedef struct ali_element_info ali_element_info

ali_doc_infoTOP

All information needed to read an XML document opened for input.

Prototype

typedef struct ali_doc_info ali_doc_info

ali_element_functionTOP

Called to handle matching XML elements.

Comments

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.

Prototype

typedef void ali_element_function(ali_doc_info *doc, ali_element_ref element, void *data)

Constants

ALI_OPTION_NONETOP

Comments

No options are needed to process the XML document.

ALI_OPTION_INPUT_XML_DECLARATIONTOP

Comments

The XML must have an XML declaration. Use this to ensure that the document is well formed.

ALI_OPTION_EXP_CONVERT_UTF8_TO_ISO_8859_1TOP

Convert input from UTF-8 to ISO-8859-1.

Comments

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.

ALI_ERROR_BASETOP

ALI_ERROR_NONETOP

There is no error.

Comments

The last API completed successfully.

ALI_ERROR_TAG_MISSINGTOP

A requested element or attribute is missing from the input.

Comments

Generally an app would want to reject the XML document.

ALI_ERROR_CONTENT_MISSINGTOP

The element is missing content.

Comments

The app requires the element to contain content like a number but it is empty.

ALI_ERROR_FILE_MISSINGTOP

The file to be opened for input is missing.

Comments

Try checking stdio's errno to determine the exact reason.

ALI_ERROR_MEMORY_FAILURETOP

There is insufficient memory to read this XML document.

ALI_ERROR_ELEMENT_INVALIDTOP

Comments

ali_in is requested to read data from an element that is no longer opened or never was.

ALI_ERROR_TAG_INVALIDTOP

Comments

The element or attributes name is invalid. The allowed names are document at http://www.w3.org/TR/REC-xml#NT-Stag and http://www.w3.org/TR/REC-xml#NT-Attribute

ALI_ERROR_NAMESPACE_INVALIDTOP

Comments

The namespace parameter is not supported. Put the entire qualified name in the local part parameter.

ALI_ERROR_DATA_INCOMPLETETOP

The XML document ended before all data was read.

ALI_ERROR_ENCODING_UNSUPPORTEDTOP

The XML document is encoded in a format not supported.

Comments

UTF-8, ISO-8859-X, and US-ASCII are supported. Others like UTF-16 are not.

ALI_ERROR_XML_DECLARATION_INVALIDTOP

The XML declaration, which starts the document, is not well-formed.

ALI_ERROR_NOT_XML_DOCUMENTTOP

The file is not an XML document, based on the missing XML declaration when one is expected.

ALI_ERROR_UNKNOWN_XML_INSTRUCTIONTOP

The XML Instruction is not known.

Comments

XML Instructions, like "^e", are passed to ali_in. The ali_in documentation lists all valid instructions.

ALI_ERROR_NULL_TAGTOP

The tag may not be NULL.

Comments

An XML Instruction, like "^e", was passed NULL for the tag name.

Copyright 2004, 2009 Roger Flores