Element: ident.xml_*

Types

Structure member xml elements:

numeric		ident.xml_base64
numeric		ident.xml_cdata
numeric		ident.xml_date_only
string		ident.xml_format
numeric		ident.xml_has_default_value
numeric		ident.xml_has_fixed_value
numeric		ident.xml_hex
numeric		ident.xml_ignore
numeric		ident.xml_is_attribute
numeric		ident.xml_is_boolean
numeric		ident.xml_is_geodata
numeric		ident.xml_is_integer
numeric		ident.xml_is_list
numeric		ident.xml_is_ptv
numeric		ident.xml_nillable
numeric		ident.xml_normalize
numeric		ident.xml_time_only
numeric		ident.xml_tokenize
numeric		ident.xml_2d

Structure class xml elements:

string		ident.xml_namespace
string		ident.xml_prefix
string		ident.xml_rti
string		ident.xml_xsd

Description

These generic elements provide xml characteristics, and are used when objects are read from or written to xml. Some elements apply only to members of structure classes, other elements apply only to structure classes.

Typically, such characteristics are set when a Fire structure class is created from an xml schema (via the xsdread command), but they can be set up manually at class definition time either via switches or post-creation by value assignments.

Input from xml is done by the xmlread command. Output to xml is done by the xmlwrite command.

Notes (Member Elements)

Parent Text Values

Fire structure objects have no concept of a "value", but xml complex elements do. Consider the following xml data:

<parent>TextValue<sub>ChildValue</sub></parent>

To ensure that Fire can retain the parent value (TextValue) it is nessary to create another member of the structure and mark it as a "parent text value" (ptv for short). So the Fire structure to hold the above data would be defined something like this:

structure parent_t {
   string tag_value,-ptv
   string sub
}

Conventially the ptv member is given the name "tag value" but any name can be used. For obvious reasons only 1 structure member can have this switch.

String Data

XML is pretty flexible when it comes to string data values. Usually schemas define string data to be supplied in one of three formats: string, normalizedString and token.

string (the default) implies that text data in the xml document is read as is without change, normalizedString implies that all occurrences of LF, CR and TAB are converted to spaces, token implies that all contiguous whitespace is reduced to 1 space.

When defining a Fire structure switches are available to ensure that xml string data is converted accordingly during the xmlread command. Like this:

structure strings_t {
   string my_string;               # XML string datatype
   string my_normalized_string,-sr;# XML normalizedString datatype
   string my_tokenized_string,-st; # XML token datatype
}

When writing string values to xml, values are output without change, irrespective of any input switches. Special characters (e.g. < & >) are "escaped". If raw output is required, the element can be marked with a -cd switch and the output will be enclosed within the special xml pairing of <![CDATA[ and ]]>. This pairing tells any xml reader not to do any conversion. This switch may also be used with text blobs.

structure rawdata_t {
   string commands,-cd
}

Numeric Data

When writing numeric data to xml documents, a common requirement is for the data to be integer or boolean. The -int or -boo switches ensure such values are output accordingly:

structure mydata_t {
   numeric idata,-int;# XML integer datatype
   numeric bdata,-boo;# XML boolean datatype
   numeric ddata;     # XML decimal datatype
}

Numeric data read from xml is automatically processed, so these 2 switches are for output only.

Formatted Output

When Fire values need to be written to XML in a special format, C language printf formatting can be used. Consider a numeric element which must always be output as 8 hexadecimal characters with prefix, it could be declared as follows:

structure mydata_t {
   numeric x,-fmt="0x%08lx"
}

Such formatting is used on output only. No formatting is available on input.

Point Data

XML has no inbuilt point type, so the -p2d switch is available to enable xml decimal data to be mapped to Fire points. Each pair of numeric xml values are converted into a point value on input, and vice versa for output. Although the 3rd (Z) ordinate value may be set within Fire, it will be ignored during xml output.

Consider some xml decimal data:

<coords>36.25 72.25 34.95 71.13333</coords>

By defining a Fire point element in a class like this:

structure myclass_t {
   point coords[],-p2d
}

The data would be read into 2 point values.

Time Data

By default Fire stores time/date values with both a time and a date component, but XML has the facility of storing date-only or time-only values. The 3 xml datatypes supported are date, time and dateTime. The switches -tdo and -tto are therefore available to ensure that the correct granularity for such data is maintained during input and output.

structure mytimes_t {
   time dt;        # XML dateTime datatype
   time donly,-tdo;# XML date datatype
   time tonly,-tto;# XML time datatype
}

All other XML time/date datatypes for which Fire has no equivalent, e.g. gYear and duration, are treated as strings.

Multiple Array Values

By default, XML data contains one value per element tag. However an XML type can be defined as a list, implying that the value is in fact a tokenized sequence of multiple values. The Fire structure -lis switch ensures that an element is treated as an array during both xml input and output.

Consider part of an xml schema which defines such a list element

<xsd:simpleType name='listOfIntegers'>
   <xsd:list itemType='integer'/>
</xsd:simpleType>
<xsd:element name="intlist" type="listOfIntegers"/>

This would appear in a Fire structure as follows:

structure whatever_t {
   numeric intlist,-lis
}

Blob Data

XML supports binary data in one of 2 flavors: base64Binary and hexBinary. Both by default are mapped to a Fire blob with the switches -b64 and -hex indicating how the xmlread command should decode the text in the xml document binary, and how the xmlwrite command should encode the binary for xml output. Without one of these switches an XML binary element will be read verbatim as a text blob.

In addition it is common to map XML a string element which contains an extensive block of data (e.g. raw CDATA-type data) into a text blob, so that Fire can process it as file contents if required. This entails making sure the corresponding Fire structure element is declared as a blob rather than as a string, which is the default XML to Fire mapping.

Consider the following XML elements from an xsd schema, and how a Fire structure could accommodate them:

<xsd:element name="binary64" type="xsd:base64Binary"/>
<xsd:element name="binaryhex" type="xsd:hexBinary"/>
<xsd:element name="datablock" type="xsd:string"/>

structure myblobs_t {
   blob binary64,-b64;    # XML base64Binary datatype
   blob binaryhex,-hex;   # XML hexBinary datatype
   blob datablock,-cd;    # XML string datatype
}

Georss Data (Point/Entity Data)

A common format for live feeds of geographic information is the georss format (see here) which enables geographic data to be supplied in one of 3 formats:

1. W3C - 2 numeric values, e.g.

<geo:lat>55.732</geo:lat>
<geo:long>-1.5763</geo:long>

<geo:Point>
   <geo:lat>55.732</geo:lat>
   <geo:long>-1.5763</geo:long>
</geo:Point>

2. Georss simple - a point, line, polygon or box, e.g.

<georss:point>55.732 -1.5763</georss:point>

<georss:where>
   <georss:line>55.732 -1.5763 55.874 -1.5766</geo:line>
</georss:where>

3. Georss GML - a point, line, polygon or box, e.g.

<georss:where>
   <gml:Point>
      <gml:pos>55.732 -1.5763</gml:pos>
   </gml:Point>
</georss:where>

<georss:where>
   <gml:lineString>
      <gml:posList>55.732 -1.5763 55.874 -1.5766</gml:posList>
   </gml:lineString>
</georss:where>

Another format (numbered 4) enables geographic format in simple gml, similar to format 3 but within the tag of the relevant member:

4. Simple GML - a point, line, polygon or box, e.g.

<shape>
   <gml:Polygon>
      <gml:exterior>
         <gml:LinearRing>
            <gml:posList>10 10 10 20 20 20 10 10</gml:posList>
         </gml:LinearRing>
      </gml:exterior>
   </gml:Polygon>
</shape>

Such data can be read into Fire point or entity variables by means of the -geo switch attached to the Fire structure member.

structure myclass_t {
   epointer geo,-geo=2
}

On input (reading from XML), a structure member marked with the -geo switch valued 1 through 3 (i.e. a georss member) will accept any of the first 3 above forms of geographic xml format. On output (writing to XML), the value of the switch (1 through 4) is used to determine the relevant xml output format.

When an epointer is specified, an entity is created and the epointer is then made to point to it. So a subsequent destruction of the Fire structure object will not remove the entity, this must be done manually, typically in a class destructor (i.e. structure.delete) or by adding the entity to a group and deleting the group. e.g.

myclass_t.delete = {
   args me=myclass_t
   kill me.geo
}

Notes (Class Elements)

Class element characteristics are attached to structure classes rather than to individual members of a class. They are set automatically when classes are created from xml schemas (see the xsdread command), although they can be set manually. The characteristics are subsequently utilized when an object of the class is written to output by the xmlwrite command as a root element.

The characteristics include urls pointing to the web addresses of the class schema, a namespace prefix which can be used to differentiate xml elements in multiple schemas, and a general customizable element (-rti) which can be used to append any other required xml attributes to the root element of an xml document.

Consider an xsd schema (only the initial header lines).

<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns:xmarc="http://www.xmarc.net/"
   targetNamespace="http://www.xmarc.net/"
   elementFormDefault="unqualified"
   attributeFormDefault="unqualified">
   ...
</xsd:schema>

When processed by an xsdread command, this might create the following top level structure class:

structure ServicesType_t,-tag="services",-pre="xmarc",-ns="http://www.xmarc.net/",\
     -xsd="http://www.xmarc.net/services.xsd" {
   ...
}

Any required access to the class xml characteristics would be something like:

tell ServicesType_t.xml_prefix
xmarc
tell ServicesType_t.xml_namespace
http://www.xmarc.net/
tell ServicesType_t.xml_xsd
http://www.xmarc.net/services.xsd

See Also