wxml
is a general Fortran XML output library. It offers a Fortran interface, in the form of a number of subroutines, to generate well-formed XML documents. Almost all of the XML features described in XML11 and Namespaces are available, and wxml
will diagnose almost all attempts to produce an invalid document. Exceptions below describes where wxml
falls short of these aims.
First, Conventions describes the conventions use in this document.
Then, Functions lists all of wxml
's publically exported functions, in three sections:
monospace
Note that where strings are passed in, they will be passed through entirely unchanged to the output file - no truncation of whitespace will occur.
It is strongly recommended that the functions be used with keyword arguments rather than replying on implicit ordering.
xmlf_t
This is an opaque type representing the XML file handle. Each function requires this as an argument, so it knows which file to operate on. (And it is an output of the xml_OpenFile subroutine) Since all subroutines require it, it is not mentioned below.
xml_OpenFile
Open a file for writing XML
By default, the XML will have no extraneous text nodes. This has the effect of it looking slightly ugly, since there will be no newlines inserted between tags.
This behaviour can be changed to produce slightly nicer looking XML, by switching on broken_indenting. This will insert newlines and spaces between some tags where they are unlikely to carry semantics. Note, though, that this does result in the XML produced being not quite what was asked for, since extra characters and text nodes have been inserted.
NB: The replace option should be noted. By default, xml_OpenFile will fail with a runtime error if you try and write to an existing file. If you are sure you want to continue on in such a case, then you can specify **replace**=.true.
and any existing files will be overwritten. If finer granularity is required over how to proceed in such cases, use the Fortran inquire
statement in your code. There is no 'append' functionality by design - any XML file created by appending to an existing file would almost certainly be invalid.
xml_Close
Close an opened XML file, closing all still-opened tags so that it is well-formed.
xml_NewElement
Open a new element tag
xml_EndElement
Close an open tag
xml_AddAttribute
Add an attribute to the currently open tag.
By default, if the attribute value contains markup characters, they will be escaped automatically by wxml before output.
However, in some cases you may not wish this to happen - for example if you wish to output Unicode
characters, or entity references. In this case, you should set escape=.false.
for the relevant
subroutine call.
The value to be added may be of any type; it will be converted to text according to FoX's formatting rules, and if it is a 1- or 2-dimensional array, the elements will all be output, separated by spaces (except if it is a character array, in which case the delimiter may be changed to any other single character using an optional argument).
xml_AddCharacters
Add text data. The data to be added may be of any type; they will be converted to text according to FoX's formatting rules, and if they are a 1- or 2-dimensional array, the elements will all be output, separated by spaces (except if it is a character array, in which case the delimiter may be changed to any other single character using an optional argument).
xml_DeclareNamespace
Add an XML Namespace declaration. This function may be called at any time, and its precise effect depends on when it is called; see below
xml_UndeclareNamespace
Undeclare an XML namespace. This is equivalent to declaring an namespace with an empty URI, and renders the namespace ineffective for the scope of the declaration. For explanation of its scope, see below.
NB Use of xml_UndeclareNamespace implies that the resultant document will be compliant with XML Namespaces 1.1, but not 1.0
If xml_[Un]declareNamespace
is called immediately prior to an xml_NewElement call, then the namespace will be declared in that next element, and will therefore take effect in all child elements.
If it is called prior to an xml_NewElement call, but that element has namespaced attributes
To explain by means of example: In order to generate the following XML output:
<cml:cml xmlns:cml="http://www.xml-cml.org/schema"/>
then the following two calls are necessary, in the prescribed order:
xml_AddNamespace(xf, 'cml', 'http://www.xml-cml.org')
xml_NewElement(xf, 'cml:cml')
However, to generate XML input like so:
xml_AddNamespace
call is made before the element tag is closed (either by xml_EndElement
, or by a new element tag being opened, or some text being added etc.) the correct XML will be generated.
Two previously mentioned functions are affected when used in a namespace-aware fashion.
xml_NewElement
, xml_AddAttribute
The element or attribute name is checked, and if it is a QName (ie if it is of the form prefix:tagName) then wxml will check that prefix is a registered namespace prefix, and generate an error if not.
If you don't know the purpose of any of these, then you don't need to.
xml_AddXMLDeclaration
Add XML declaration to the first line of output. If used, then the file must have been opened with addDecl = .false.
, and this must be the first wxml call to the document.o
NB Note that if the encoding is specified, and is specified to not be UTF-8, then if the specified encoding does not match that supported by the Fortran processor, you may end up with output you do not expect.
xml_AddDOCTYPE
Add an XML document type declaration. If used, this must be used prior to first xml_NewElement
call, and only one such call must be made.
xml_AddInternalEntity
Define an internal entity for the document. If used, this call must be made after xml_AddDOCTYPE
and before the first xml_NewElement
call.
xml_AddExternalEntity
Define an external entity for the document. If used, this call must be made after xml_AddDOCTYPE
and before the first xml_NewElement
call.
xml_AddParameterEntity
Define a parameter entity for the document. If used, this call must be made after xml_AddDOCTYPE
and before the first xml_NewElement
call.
xml_AddNotation
Define a notation for the document. If used, this call must be made after xml_AddDOCTYPE
and before the first xml_NewElement
call.
xml_AddStringToDTD
Since there is no other method of adding ELEMENT or ATTLIST declarations to the DTD, this function provides a method to output arbitrary data to the DTD if such declarations are needed. Note that no checking at all is performed on the validity of string. Use this function with a great deal of care.
If used, this call must be made after xml_AddDOCTYPE
and before the first xml_NewElement
call.
xml_AddXMLStylesheet
Add XML stylesheet processing instruction, as described in [Stylesheets]. If used, this call must be made before the first xml_NewElement
call.
xml_AddXMLPI
Add an XML Processing Instruction.
If data is present, nothing further can be added to the PI. If it is not present, then pseudoattributes may be added using the call below.
Normally, the name is checked to ensure that it is XML-compliant. This requires that PI targets not start with [Xx][Mm][Ll]
, because such names are reserved. However, some are defined by later W3 specificataions. If you wish to use such PI targets, then set xml=.true.
when outputting them.
The output PI will look like:
<?name data?>
xml_AddPseudoAttribute
Add a pseudoattribute to the currently open PI
xml_AddComment
Add an XML comment
xml_AddEntityReference
This may be used anywhere that xml_AddCharacters may be, and will insert an entity reference into the contents of the XML document at that point.
Below is a list of areas where wxml fails to implement the whole of XML 1.1; numerical references below are to the sections in [XML11]]
xml_NewElement
(In principle it should be possible to start the root element from within an entity reference). Furthermore, when an entity reference is added to the document, no check is made of its validity or its contents. (In general, validating all entity references is impossible, but even where possible wxml does not attempt it.) This means that if an entity reference is output, wxml offers no guarantees on the well-formedness of the document, and it will emit a warning to this effect.**indenting**=.false.
to xml_OpenFile, at the risk of file output failing on sufficiently long lines.wxml will try very hard to ensure that output is well-formed. However, it is possible to fool wxml into producing ill-formed XML documents. Avoid doing so if possible; for completeness these ways are listed here.
Finally, it should be noted (although it is obvious from the above) that wxml makes no attempt at all to ensure that output documents are valid XML (by any definition of valid.)
[XML11]: W3C Recommendation, http://www.w3.org/TR/xml11
[Namespaces]: W3C Recommendation, http://www.w3.org/TR/xml-names11
[Stylesheets]: W3C Recommendation, http://www.w3.org/TR/xml-stylesheet