XML Input File Templates

FORTPY: XML Input

Here we describe how to create an XML template file for using XML input files in your program. As described in the interoperability package, Fortpy can handle automatic file conversions between XML and plain text files so that your code can support XML input files without needing to change your code or try and get Fortran to talk XML. Here are the advantages of XML input:

1. Named keywords for parameter values.
2. Keywords can appear in any order in the file.
3. Human-readable structure makes it easy to understand what the input file is doing.
4. Your code still gets to use the regular plain-text input files it does now.

Creating an XML Input Template

For an example of a real-life XML input template, see struct_enum.in.xml.

The root node in all XML input templates is <fortpy mode="template" direction="input" versions="1,2">. The mode and direction attributes are mandatory and should have the values of "template" and "input" respectively. The versions attribute is also necessary, and lists the number of file versions that this template file handles. Although you can tell the conversion scripts etc. to use specific template files, if you name the template file the same way as the input file (i.e. the plain-text file) and append a .xml on the end, Fortpy will automatically match it up to the input file for conversion.

There are only three possible tags that have meaning in the XML template:

• <comments>: specifies a character(s) to use for comments. Any comments that are added as comment attributes in the XML input file will be inserted in the plain text file after this symbol.
• <line>: represents a single line in the plain-text input file.
• <group>: represents a line in the plain text file that gets repeated a specific number of times.

We will look at the last two tags individually since they are a bit more complicated.

<line> Tag

The line tag translates an XML tag into a single line in the plain-text input file. The order that the <line> tags appear in the XML template is the same order they will be written to the plain-text file. All that Fortpy does is:

1. Step through the template one line at a time.
2. If the line applies to the target version of the plain-text file we are creating, include it.
3. Look for the tag in the XML input file whose tag name matches the id attribute of the line and insert its value plus any comments that were included.

Attributes

• id: the name of the tag in the XML input file whose value should be used for this line.
• type: a comma-separated list of data types for the input string being copied over. Supplying this information allows input validation to take place before the Fortran executable runs. As an example, if we have an Aluminum atom at vector (0,0,1), the input line might look like "Al 0. 0. 1.". Then the type attribute would be type="string,float". See also the values attribute documentation.
• values: specifies how many values of each type in the type attribute are present in the value string. Using the example from the previous line, we have one string value followed by three float values. So, for the values attribute we would use values="1,3".
• versions: which versions of the plain-text input file this line applies to. Specify multiple versions using a comma-separated list.
• comment: an optional comment to place in the input file on the line immediately preceding this line's value. The comment will be placed after the comment character(s) specified in the <comment> tag.
• from: when the value of a line depends on how many lines appear in a group, you can use from to instruct Fortpy where to get the value from. from should be the name of a group to get the value from.
• operator: in connection with using from, operator specifies how the value will be retrieved. The default value is "count" which says that the value for the line should be the number of items that appear in the group specified by from.

<group> Tag

An example of where the <group> tag is used is enumerating a list of items with the same structure. For example, imagine that you have four atoms in the unit cell of a crystal and you need to list them all in the input file. You could include a <group name="atoms"> to contain a single <line> tag that describes how to translate an atom from the XML input file to the plain-text input file.

When groups are used in the template, the corresponding structure in the XML input file is a tag with the group name that contains nested child tags that all have a tag name corresponding to the id attribute of the <line> tag in the group. To see how this works, compare the struct_enum.xin.xml file with its template file struct_enum.in.xml.

Attributes

• name: the name of the tag in the XML input file that is parent to the list of tags whose values will all be represented using the <line> tag in the group.
• versions: the versions of the plain-text input file that this group appears in.
• repeat: how many times to repeat the line definition on child nodes of the group tag in the XML input file. To repeat the definition for all children of the group tag, use repeat="*". For a finite, pre-defined number of child nodes, use an integer (e.g. repeat="3").
• comment: an optional comment to include in the plain-text file on the line immediately preceding the first item in the group that gets translated.