eXML

Call this SWI twice. First, with a null pointer in R0, to discover the required workspace size; then, having claimed a block of that size, call it again with a pointer to that block in R0. The second call clears the block to zero and fills in sensible default preferences. The resulting pointer (R0 on the second call) must be passed in R0 to every other eXML SWI for that session.

R1 gives the required size of the Content buffer used to hold parsed content data; the module imposes a minimum of 1KB if a smaller value (or a null pointer) is supplied.

This call supersedes SWI eXML_Init and should be used in its place.

This call is deprecated, and is supplied only for backwards compatibility. It assumes a fixed size for the Content buffer (10KB from version 0.18 onwards; 1KB in older versions). SWI eXML_InitBuffer allows the Content buffer size to be chosen and should be used in preference to this call.

As with SWI eXML_InitBuffer, call this SWI twice: once with a null pointer in R0 to discover the required size, and once with a pointer to a claimed block of that size to initialise it.

Once initialised, eXML uses sensible default values for every configurable preference. This call changes one of them for the workspace given in R0. The variable number in R1 behaves as a reason code, selecting which preference is changed and how R2 is interpreted; see each reason below.

To produce readable XML output, eXML indents nested elements. This preference sets the number of spaces used per nesting level; the default is 2. Setting it to 0 disables indenting entirely.

Readability can be further improved by inserting a blank line before the opening tag of higher-level elements. By default, extra lines are only inserted at the first nesting level; setting this to 2 or 3 extends that to deeper levels.

By default, every string returned by eXML is terminated with a 0x00 byte, suiting C and Assembler. BASIC programs need a 0x0D (Carriage Return) terminator instead; use this preference to change it. The change affects only later calls made with this workspace pointer in R0.

SWI eXML_Context, and the string form of context returned by SWI eXML_Parse, join element names with / by default, eg. /document/chapter/page/frame. This preference selects a different separator character. Avoid choosing a character that can legally appear inside an element name.

This preference works like Set the character used to separate element names in a context string, but for addressing an attribute within an element's opening tag, eg. /document/chapter/page@print to address the print attribute of that page element, once @ has been set as the attribute separator.

By default, XML files created by eXML are typed as Text (&FFF), so they can be checked in a standard text editor such as !Edit, !StrongEd or !Zap. This preference sets an alternative filetype, such as &F80 (XML), to be applied when the file is closed. It only affects files being created; it is ignored when reading an existing file.

SWI eXML_UpdateFile may need to create a temporary file. By default, eXML uses <Wimp$ScrapDir> (creating an eXML subdirectory within it), falling back to <eXML$Dir>.Scrap if that variable cannot be accessed. This preference selects a different directory.

Clears the stack of attributes accumulated by SWI eXML_Attribute. The stack is cleared automatically once a new element is created, so this call is rarely needed; it exists for the case where the state of the stack is uncertain, for example after an error.

The simplest way to parse an XML file is to load it entirely into a buffer in the application's own memory and hand that buffer to eXML with this call, then parse it with repeated calls to SWI eXML_Parse. This only works when the file's size is known and it is small enough to hold in memory, which is true of most everyday XML files.

Use this call instead of SWI eXML_ParseBuffer when a file is too large to hold in memory, or when its size is not known in advance, such as when parsing streamed data. The file is read a character at a time as parsing proceeds. As with SWI eXML_ParseBuffer, call SWI eXML_Parse repeatedly until parsing is finished.

Once the workspace has been initialised and a document has been presented with SWI eXML_ParseBuffer or SWI eXML_ParseFile, call this SWI repeatedly to parse it, until it returns the Finished or ERROR code. eXML tracks the exact position reached within the document; to restart parsing from the beginning, present the document again with SWI eXML_ParseBuffer or SWI eXML_ParseFile.

Your application need not respond to every return code - many can safely be ignored - but it must always respond to ERROR and Finished, so that the parsing loop terminates.

A self-closing element, eg. <colour type="rgb" value="255,255,255" />, always produces a Start code immediately followed by an End code, so that calling code can track nesting depth itself without special-casing self-closing elements.

When content is found, R1 points to the data and R2 gives the number of bytes to read; a suitable terminator is always present at the byte immediately following the data, so a short string of content can be read directly as a terminated string. The content may arrive as a single block, or scattered across a series of Content events, depending on the available buffer space and the transport in use; calling code should be able to cope with content arriving in several pieces.

SWI eXML_Parse can return the current context as an array of element-name pointers (see context array); this call instead builds a single, user-readable context string on demand, useful when Content has just been reported and the calling code wants to know which series of elements it belongs to.

The returned string is terminated with the configured terminator (see Set the character used to terminate strings returned by the module). As with the context array, the name of the element currently being opened or closed is not included, since it is not yet (or no longer) part of the context at that point.

A well-formed XML document should contain a Document Type Declaration (DTD), usually near the start of the file, so that its structure and syntax can be verified against a set of rules, for example:

<!DOCTYPE svg PUBLIC "-//W3C//SVG//EN" "http://www.w3c.org/dtd/svg.dtd">

Because the syntax of a DTD line is quite free-form - it may, for instance, be spread over several lines - this call decodes it into the useful parts listed above. Document creation code is encouraged to build such lines with SWI eXML_DTD instead of constructing them by hand, as that ensures correct syntax.

There is no support at present for an embedded (in-line) DTD; only a reference to an external DTD file (whether local, SYSTEM, or public, PUBLIC) is decoded. As in-line DTDs are being phased out in favour of XML Schema, it is unlikely that support will be added.

The presence of the referenced DTD file is not checked by eXML: the URL is supplied purely for the benefit of an external XML validation tool, and by convention uses a .dtd filename extension.

Performs the reverse operation to SWI eXML_EncodeString: it copies the source string to the destination, translating each escape sequence (<, >, &, ', ") back into the corresponding ISO Latin-1 character.

Added in version 0.36. This call reads the parser's current position, allowing an application to record the start and end points of the content held within an element, so that the sub-content between those points can be parsed or otherwise processed again later.

Creates a new XML file ready for further calls (such as SWI eXML_StartElement) to write its content; eXML tracks correct opening and closing of elements, attributes and content as they are written. Call SWI eXML_Close once the file is complete.

As part of opening the file, this call writes the XML declaration as the first line of the file, eg. <?xml version="1.0" encoding="UTF-8"?>. The version and encoding attributes may be supplied directly in R3 and R4 (the common case, since both are more or less mandatory), or as ordinary attributes in the array pointed to by R2 - or a mixture of the two, though R2 may be 0 if only version and encoding are required. R2, R3 and R4 are all optional and should be 0 if not used.

The call returns the handle of the newly opened file (or 0 on failure), so that the caller can track it and close it if an error occurs partway through writing.

This call behaves identically to SWI eXML_Open; see that entry for its registers and use.

Works in the same way as SWI eXML_Open, except that all further output is written into the supplied memory buffer rather than to a file. This is useful, for example, when building a header for streamed (eg. internet) communication that does not need to be saved to disc first.

Closes the file most recently opened with SWI eXML_Open or SWI eXML_OpenBuffer, and clears the module's internal pointers to it. If it was opened as a file, the filetype given in R1 (or the configured default, Text &FFF, if R1 is 0) is applied. The filetype is only used when writing; it has no effect when reading an existing XML file.

Not yet implemented.

In some situations, an application needs to update only part of an existing XML file, for example one that several applications share. This call opens an existing file (creating a new output file alongside it) so that its content can be scanned for a required element; the caller's own data can then be inserted, the original element skipped, and scanning continued. Once opened, call SWI eXML_Update repeatedly until parsing is finished, in the same way as SWI eXML_Parse.

Call this SWI repeatedly, after opening a file with SWI eXML_UpdateBuffer or SWI eXML_UpdateFile, until parsing has finished. Once the expanded context string in R3 matches the element you were looking for, set bit 0 of the flags on the next call to claim that element (and everything nested within it): it is skipped, and no further elements within it are reported, until it has closed.

Writes the opening tag of a new element to the file (or buffer) opened by SWI eXML_Open or SWI eXML_OpenBuffer. A StartElement should normally be followed by optional content, optional nested elements, and finally a matching SWI eXML_EndElement.

An element may instead be marked empty (self-closing), in which case it may still hold attributes but cannot hold content or nested elements, and a / is inserted before the tag's closing >, eg. <colour red="255" green="128" blue="44"/>. An element can be marked self-closing in any of three ways: by setting bit 0 of the flags on entry; by prefixing the element name in R1 with /, eg. R1 -> /colour; or by supplying a content string in R3 (see below). In every case, do not call SWI eXML_EndElement for the element - it is closed automatically.

A single short line of text can be inserted as content by pointing R3 at it: the StartElement is written, the content is inserted, and the EndElement is written automatically, so no separate call to SWI eXML_EndElement is required. For example:

SYS "eXML_StartElement",xml%,"comment",attr%,"Just a line of text."

produces:

<comment>Just a line of text.</comment>

If more than one line of text is needed, omit the string in R3 and use SWI eXML_Content between matching SWI eXML_StartElement and SWI eXML_EndElement calls instead.

Closes an element previously opened with SWI eXML_StartElement - except an element that was marked self-closing, which must not be closed explicitly. Every other opened element must eventually be closed, and elements must be closed in the correct (nested) order; XML does not permit overlapping elements.

eXML checks the element name given in R1 against its internal stack of open elements, and produces an error if the wrong element is closed. Supplying 0 in R1 closes the most recently opened element without this check, but this is not recommended, since it prevents eXML from verifying that elements are being closed in the correct order.

Inserts content inside the element most recently opened with SWI eXML_StartElement. A single short line can also be supplied directly to SWI eXML_StartElement; use this call instead for larger blocks of text, multiple lines, or any number of bytes. Content may contain line feed and/or carriage return characters, and these are preserved (unlike in HTML).

Content may only be written once an element is open; writing content without an open element produces the Error_eXML_FileNotOpen error.

An attribute takes the form name="value", and an element may carry any number of them. Rather than building an attribute array by hand, call this SWI once for each attribute to be added to the pending stack, then pass the returned pointer to SWI eXML_StartElement, SWI eXML_Open, or SWI eXML_Declaration. The stack is cleared automatically once the element is created, so it rarely needs to be cleared explicitly (see SWI eXML_ClearAttributes).

Declarations are typically used near the start of a document; the most common is the <?xml?> declaration, which must be present for a document to be considered valid. This call produces output similar to SWI eXML_StartElement, but the line begins with <? and ends with ?>. Declarations do not need to be (and cannot be) closed with SWI eXML_EndElement, and are not considered part of the document body.

The content and processing of a declaration is entirely up to the application reading it; eXML places no further interpretation on it.

Writes a comment to the output document, in the standard form <!-- comment text -->.

Writes a DOCTYPE line at the start of a document, after the <?xml?> declaration but before the first element. A DTD describes the structure of a document, and the possible values for each attribute, so that a validation tool can check the document against it; it is also used by the XML File Dispatcher to identify a document's type when it is double-clicked.

There are three kinds of DTD. A SYSTEM DTD is stored locally, and needs only a relative URL to the DTD file in R3. A PUBLIC DTD is stored externally (for example on the internet); it needs a URL in R3 and an identifier string in R2 describing the publisher, format and language of the document, and is selected by setting bit 4 of the flags. An in-line DTD embeds its information directly in the DOCTYPE declaration, but this is not currently supported by eXML.

The document-type in R1 identifies the kind of document, eg. svg; where an application uses several document types, including the application's own name as a prefix, eg. artworks:svg, allows an unlimited number of distinct types to be created without clashing with anyone else's.

The identifier in R2 (PUBLIC DTDs only) should describe the publisher, the document format and version, and the language, separated by double forward-slashes, eg. -//XAT//CableNews Edition 4.0//EN. A leading - indicates a publisher that is not ISO certified; a leading + indicates one that is. A SYSTEM DTD has no identifier; if one is supplied it is ignored, so that XML checkers and browsers do not report an error over it.

The URL in R3 is not used by eXML's own parser: it exists purely for an external XML validation tool. For a SYSTEM DTD, use a relative path, eg. edition.dtd or files/edition.dtd; for a PUBLIC DTD, use an absolute URL, eg. http://www.xat.nl/dtd/cablenews/edition.dtd. In both cases the filename should carry a .dtd extension, and the path should be given in URL form rather than RISC OS pathname form.

Inserts a Processing Instruction into the output document, used to pass information directly to whatever XML processor reads the document (for example, the parser inside your own application). Processing instructions are not considered part of the document body, and their syntax is not checked by eXML. Only the opening (<?) and closing (?>) delimiters are added; the data in R1 is inserted between them exactly as supplied.

The XML standard allows raw data - including reserved characters such as < and > - to be inserted into a document without escaping, inside a CDATA section. The only sequence a CDATA section cannot contain is ]]>, which marks its end. A CDATA section is opened with <![CDATA[ and closed with ]]>.

Reading CDATA sections is not currently supported by eXML.

This call is not really specific to XML, but is provided because it is useful for building structures (such as large menus) from data received elsewhere, for example a WIMP message. It copies a string terminated by any control character into the caller's own buffer, applying whichever terminator the caller's software requires.

There are many ways to express a colour in an XML document - some inherited from HTML, some specific to XML - and converting between them can be tedious, especially when the user should be free to choose their preferred colour model. SWI eXML_ColourOp converts between these formats, and reads or writes colours directly. Every reason code operates on a colour data block held in the caller's own memory (except reason codes 3 and 4, which use the module's own internal workspace instead - see below). R0 selects the operation; the meaning of the other registers depends on the reason code.

It is recommended that colour be expressed as an attribute on an existing element rather than as an element of its own, eg. <background colour="rgb(255,255,255)"/> rather than <background><colour value="rgb(255,255,255)"/></background>.

Before a colour data block is used with any other reason code, it should be set to a defined state by calling this reason code with a pointer to it in R1. To find the required size of the block, call with a null pointer in R1; the size is returned in R2. The size should always be requested first, since it may grow in a future version of the module.

Parses the colour definition string in R2, in any of the formats described under colour data block, and updates the block pointed to by R1 with the resulting colour, colour model, and format.

Formats the colour held in the data block pointed to by R1 as text, in either the colour's original format or the format requested in bits 8-15 of the flags, and writes it to the buffer in R2. This is typically used directly to produce XML output.

Equivalent to Read a colour from a text string into a colour data block, but uses the module's own internal workspace for the conversion rather than a caller-supplied colour data block, so no block needs to be created first.

Equivalent to Write a colour data block out as a formatted text string, but uses the module's own internal workspace for the conversion rather than a caller-supplied colour data block.

The official XML standard specifies dates in reverse (year-month-date) order, separated by dashes, eg. 2014-06-31, optionally followed by a time, separated by an optional space and the letter T, eg. 2014-06-31 T14:23:01. The part following T gives hours, minutes and seconds, each separated by a colon.

Reading is implemented: this call reads an existing date (and optional time) from a text string, either in a specific format selected in R0, or automatically (format 0), in which case XML and EUR dates are assumed to be separated by dashes and USA dates by slashes. Writing a date is not yet implemented.

Copies a NULL-terminated string from the source in R0 to the destination in R1, translating any of the reserved characters (<, >, &, ', ") into the corresponding XML escape sequence (<, >, &, ', ").

Not implemented.