A browser based tool for conversion between fortran NAMELIST and XMLHTML

A browser based tool for conversion between Fortran NAMELIST and XML/HTML SoftwareX 6 (2017) 25–29 Contents lists available at ScienceDirect SoftwareX journal homepage www elsevier com/locate/softx A[.]

Trang 1

Contents lists available atScienceDirect

SoftwareX

journal homepage:www.elsevier.com/locate/softx

XML/HTML

O Naito

National Institutes for Quantum and Radiological Science and Technology, 801-1 Mukouyama, Naka, Ibaraki 311-0193, Japan

a r t i c l e i n f o

Article history:

Received 26 July 2016

Received in revised form

18 November 2016

Accepted 2 December 2016

Keywords:

Fortran namelist

XML

Web browser

JavaScript

a b s t r a c t

A browser-based tool for conversion between FortranNAMELISTand XML/HTML is presented It runs on

an HTML5 compliant browser and generates reusable XML files to aid interoperability It also provides a graphical interface for editing and annotating variables inNAMELIST, hence serves as a primitive code documentation environment Although the tool is not comprehensive, it could be viewed as a test bed for integrating legacy codes into modern systems

Code metadata

Permanent link to code/repository used for this code version https://github.com/ElsevierSoftwareX/SOFTX-D-16-00061

Software code languages, tools, and services used HTML5, JavaScript

Compilation requirements, operating environments & dependencies

If available Link to developer documentation/manual

1 Motivation and significance

Fortran is one of the oldest and most popular programming

languages in the field of scientific research Fortran has a standard

formatted Input/Output, which is suitable for routine data I/Os but

requires precise data formatting and data type specifications Aside

from this, it has a convenient way of setting input parameters

calledNAMELIST TheNAMELISTprovides an environment for

annotated input, in which the users can set parameters by

specifying key–value pairs The users can assign values to keys in

a fairly flexible manner For example, they can put spaces between

keys and values for readability, use the shorthand expression

r*c for r successive values of c, omit specifying some values by

assigning nulls (in this case, the default values are used), and

use commas or spaces for value separators This flexibility may,

however, be an obstacle for interoperability with software that is

E-mail address:naito.osamu@qst.go.jp.

not based on Fortran To share the information, the software will need a specific parser to analyze the contents inNAMELIST Although modern Fortran compilers accept long key names, it

is not practical to use lengthy names to express their meanings, because the key names are directly used as variables in the source codes and often used intensively in mathematical expressions On the other hand, there are legacy Fortran codes that were developed

at the time when the allowed length of variable names was rather short to convey their meanings For both cases, seasoned program users or developers will not have any difficulty in telling the meanings of variables But for occasional users, it would be of great help if they can instantly consult the description of variables while setting input without referring to long paper-based or electronic manuals That is, if we can integrate the description of variables into the parameter setting interface, it could improve data input efficiency as well as code documentation maintainability

In fact, there are already attempts to manipulateNAMELIST

with powerful modern languages like Python [1] However,

to make better use of NAMELIST with regard to the above-mentioned points, translatingNAMELIST to a standard markup

http://dx.doi.org/10.1016/j.softx.2016.12.001

Trang 2

26 O Naito / SoftwareX 6 (2017) 25–29

Fig 1 Flow chart of the data conversion process in this tool.

language such as XML [2] could be a highly versatile approach

Once the contents are converted to XML, further transformation

to other formats like HTML would be easily done through

XSLT (Extensible Stylesheet Language Transformations) [3] This

provides an efficient framework for preparing the interface for

and description of input parameters Also, many of the modern

programming languages and proprietary software products can

handle XML data, which helps to facilitate interoperability

Another benefit of employing XML is that it can handle a diverse

range of data with heterogeneous schemas as long as the data are

described in XML That is, even if there are differences in the precise

way of how the data are expressed, we can at least know what is

in the data and its structure, and therefore, what to do with the

data In that respect, there also exist elaborate tools to manipulate

XML directly from within Fortran [4], but it is necessary to program

specific Fortran codes for that purpose

In this paper, we present a software tool for translating Fortran

NAMELIST to XML/HTML and vice versa We only deal with

NAMELISTfiles and keep the original Fortran source codes intact

So we can safely apply this tool to legacy programs In order to

minimize the requirements for usage environment and maximize

the portability, the tool only assumes that the user has access to

an HTML5 [5] compliant browser with JavaScript [6] enabled This

tool is not meant to be comprehensive—rather, it is equipped with

minimal functionalities and should be considered as a test bed for

sharing Fortran data with other systems

2 Software description

2.1 Software architecture

We first consider how to express the contents ofNAMELISTin

XML As described in the previous section,NAMELISTdata consist

of a series of key–value assignment statements This key is called

object or name or variable depending on the implementation of

compiler system In this paper we call it object An object can be

an array and, in which case it can be represented by a sequence of

values separated by commas or white spaces Apart from the data

length or size (i.e number of bytes), Fortran has five data types,

namely, logical, character, integer, real, and complex A complex

constant can be expressed by a pair of real or integer constants

separated by a comma and enclosed in parentheses An r-times repetition of a constant c can be represented by r*c Multiple

objects can be organized into a group.

Keeping these points in mind, we may map NAMELIST’s

group, object, value, repetition and complex respectively to XML

elements<group>, <object>, <value>, <repeat> and

<complex>, as in the following example:

NAMELIST:

&group1 object1 = value11, value12, value13, object2 = ( value21, value22 ),

&end

&group2 object3 = r * value3,

&end XML:

<value type="type11">value11</value>

</object>

<re>

</re>

<im>

</im>

</complex>

</object>

</group>

</repeat>

</group>

</namelist>

where<namelist>is the root element;typej denotes the data

type ofvaluej and is one of the following: logical, character,

integer, real, null The last one is for an omitted value, for which nothing is known about its property The reasons that complex is not used here as a choice oftypeattribute of<value>element but rather has its own element<complex>are: (1) A complex value consists of a pair of values that have an atomic data type of either real or integer; (2) In order to have only one text content in each<value>element; (3) Other programming languages such

as C, C++, Java, do not have complex as an intrinsic data type

We could have addedsizeattribute to<value>element to specify the data length in bytes as in

but we did not introduce this attribute, since FortranNAMELIST

generally accepts any numerical data types as its input and converts them into their appropriate internal types Therefore, an assignment statement inNAMELISTlike

variable1 = 1, 4.0e0, 8.0d0, 16.0q0,

works for variable1 of any of the following data types:

integer*2, integer*4, integer*8, real*4, real*8, real*16 That is, we cannot tell the correct data type and size

Trang 3

Fig 2 Window afterNAMELISTis loaded and converted to XML Files can be loaded with the file selector or, if supported, by drag and drop By clicking the ‘‘Translate to XML/Namelist’’ button, the contents are transformed back and forth For a browser that allows writing to local files, the contents in the text panes can be saved to the default download location.

only from aNAMELISTinput—although numerical calculations are

customarily done in double precision To know the exact data

types, we need to scan the whole Fortran source program, which

is not always easy, nor is our current intent Therefore, when we

scan theNAMELISTinput for the first time, we only assign the most

plausibletypeattribute to each<value>element and leave its

data size property undetermined

Next, we will think about the implementation of the mechanism

for parsing NAMELIST input A standard way of analyzing

NAMELIST contents would be pattern matching with regular

expressions In JavaScript, a regular expression pattern can be

represented by a RegExp object This tool first tokenizes the

contents ofNAMELISTand stores them as JavaScript objects by

using methods associated withRegExpandStringobjects Each

token object stores its original position in theNAMELISTinput; its

kind, i.e group, object, value etc.; its name; and its index value if the

token is for an array object that has an index Then these tokens are

converted to an XML string using JavaScriptStringmethods This

NAMELISTto XML conversion step is the cornerstone of this tool

After this conversion, further transformation to HTML or back

toNAMELISTcan be done straightforwardly with XSLT First, the

XML string is parsed into a DOM (Document Object Model) [7]

document with the DOM parsing functionality of JavaScript, and

then transformed to desired formats by using JavaScript XSLT

processor along with appropriate stylesheets These stylesheets

are embedded in the main body of the tool, which is an HTML

document They are normally hidden, but by clicking the toggle

buttons, they can be visible The stylesheets could have been

stored as external files, but here they are treated otherwise to

simplify the file handling process There is also a by-product of

adopting the current method: The user can edit the stylesheets and

see the results instantly on the browser, which is convenient for

debugging The flow chart of data conversion process in this tool is

shown inFig 1

2.2 Software functionalities

Both the NAMELIST file and XML file can be loaded with JavaScript File API [8] and saved using JavaScript Blob object, though the save function does not work on some browser for security reason; in that case, the user can still copy the result and paste it to a text file using some editor

The user can view the HTML document, whose contents are equivalent to theNAMELIST, and edit the values of each object In

addition, editable areas for summary and detailed descriptions of

groups and objects, and the input areas for units of measurement

for objects are provided in the HTML document This is optional

but by editing these areas, the user can record useful information

about groups and objects for later reference The completed HTML

document is distilled into an XML document that holds only the necessary information, again by XSLT processor This extracted XML can be transformed back to aNAMELISTfile that can be used

as an input for the Fortran program Or the XML can be saved as

a template for the future inputs Next time this XML template is loaded and an HTML document is generated from it, the HTML

is populated with descriptions of groups and objects that were

annotated previously by the user These ancillary data stored in another template can be copied to the currently displayed HTML document by specifying the template XML file name and triggering the process by a button click

3 Illustrative examples

The tool consists of an HTML file and a JavaScript file After the tool is launched by opening the HTML file, the user can load the

NAMELISTwith the file selector or, if supported, by drag and drop

Fig 2shows an example window after theNAMELISTis loaded and converted to XML by clicking the✄

✂Translate to XML »✁button The generated XML can be transformed back toNAMELISTby clicking the✄

✂«Translate to Namelist✁button Both text panes are editable,

Trang 4

28 O Naito / SoftwareX 6 (2017) 25–29

Fig 3 Input data editing form generated from XML document and populated with summary and detailed descriptions for groups and objects as well as measurement units.

so the user can modify the contents and quickly see the results

If the browser allows writing to local files, the contents in those

panes can be saved to the default download location

Based on this XML document, further conversion to the HTML

input data editing form, as shown inFig 3, can be triggered by

pressing the✄

✂Generate HTML Form✁button The first part of it is

the index to groups and objects, with which the user can navigate

through this input form At the bottom of each group section, a link

labeledBack to topis provided to jump back to this top index In

each group section, its constituent objects are aligned with their

most plausible data type shown in the drop-down list followed

by an inferred data size in bytes If the automatically chosen data

type or data size is not correct, the user can amend it by selecting

the proper one from the drop-down list or edit the data size in

the framed box, although in practice, the change of data type

would be only possible between integer and real, or from null to

some specific type There is also an editable area for specifying

measurement units Right to the object name is a row of its value

cells Each cell is labeled with its sequential number followed by

its multiplicity (i.e how many times the same value is repeated)

enclosed in parentheses, supplied with a checkbox for selecting cells to be joined/disjoined, and an editable input box for the value Cells with repeated values are represented by raised pattern Cells

for complex objects consist of a pair of numerical values enclosed

in parentheses The data size for a complex object refers to its

constituent real and imaginary parts There are also editable spaces

for summary and detailed descriptions for each group and object By

clicking the toggle button (◃,▽) right to the summary, the detail can be shown or hidden

The user can bundle or undo the cells in an object as shown

inFig 4, where the statement inNAMELISTthat is equivalent to each cell representation is also given: (1) To undo the bundled cell (i.e the cell with multiplicity>1) to individual cells, mark the checkbox of the bundled cell and click the disjoin✄

✂ ✁«» button; (2) To combine the cells to a bundled cell with identical values, mark all the checkboxes to be combined and click the join✄

✂ ✁»«

button

When the form input is done, the user can extract the necessary contents from the HTML document by clicking the

✄

✂Distill XML from HTML✁button The resultant XML is augmented

Trang 5

Fig 4 Procedures to join/disjoin the value cells Raised patterns indicate that

the values are repeated multiple times as shown in the parentheses Equivalent

NAMELISTstatements are shown to the right.

with information that is supplied by the user via the input

form, such as group and object descriptions, data types, data

sizes, and measurement units, and can be viewed in its own

pane by pressing the ✄

✂Show Distilled XML✁ button Also, the user can copy the result to the top right pane by clicking the

✄

✂Copy Distilled XML to Right Pane✁ button and further convert

back toNAMELISTby clicking the✄

✂«Translate to Namelist✁button

If the template XML file is specified in the file selector for

‘‘Template XML file’’ and the✄

✂Now button is clicked, the ancillary✁

data in the template are copied to the currently displayed HTML

document If the ‘‘Auto’’ checkbox is marked, the template is

applied automatically to the HTML document every time it is

generated When values with invalid data types are entered into

the value cells, or detected while the validation is executed after

clicking the✞

✝

☎

✆

Check Inputs button, an alert box pops up, and the

values are reverted to the original ones

4 Impact

The primary purpose of this tool is to convertNAMELISTto

a reusable format and share its contents with other software

that is not based on Fortran Many of the proven simulation

codes that have been developed and used for years tend to have

many input parameters inNAMELIST An orthodox and direct

approach to getting precise details about allNAMELISTvariables

would be to scan the whole source codes and find allNAMELIST

statements along with associated variable declarations Since there

are many good source code analysis tools nowadays, obtaining

such information might be done without much difficulty However

assembling those pieces of information into a reusable format

might not be so trivial In contrast, the current tool is easy to use

in that it refers only to an existingNAMELISTand renders the

contents into a format shareable with other systems Although

the tool can only infer the likeliest data types of the variables

that appear in theNAMELIST, there is no need to have access to

the Fortran source codes, nor are requirements on their side If

an entire list ofNAMELISTvariables is needed, it might still be

possible to add a small Fortran subroutine that outputs all objects

of every group with their current values, though the sequence of

groups should be consistent with the reading order ofNAMELIST

input Anyway, in most cases, the variables that appear in the existingNAMELISTwould virtually be all of the necessary control parameters of interest Once the resultant XML file is obtained, transferring it to other systems or triggering other programs from within the browser using the XML data should not be difficult From the viewpoint of providing a graphical interface for parameter input, this tool could be an easily accessible prototype Since this is a stand-alone tool on the client side, it can be used

to prepare input data off-line The completed input data can be sent to the computing machine either manually or automatically via client–server communication Since the actual implementation

of such mechanisms differs considerably depending on the operational and computational environments, we will not discuss this subject here

As for documentation of the Fortran codes, this tool serves

as a simple interface for annotating the contents ofNAMELIST Minimal information on variables, such as their descriptions, data types, and measurement units, can be entered and stored for later use Although we could have added facilities to specify restrictions

on the range of values that can be assigned to each object, they

were not included since that could make the input window too messy

5 Conclusions

In this paper, we have presented a tiny browser-based tool for converting FortranNAMELISTto XML/HTML and vice versa Since this tool only uses the intrinsic functions of a web browser, its ability is rather limited but it runs on various platforms By translatingNAMELISTto XML, the information can

be used more easily among different systems By providing a graphical interface for entering parameter values and annotating properties of parameters, the tool can serve as a very simple code documentation system as well as an easy-to-use input data editor

A possible extension of the current tool would be to visualize the data using SVG (Scalable Vector Graphics) [9] to help the user check the input in real time This tool is far from comprehensive, rather it should be viewed as a prototype for integrating legacy (and often big) codes into modern systems

References

[1] A Python module for parsing Fortran namelist files, http://github.com/ marshallward/f90nml/.

[2] Extensible Markup Language (XML) 1.0, 5th ed., http://www.w3.org/TR/xml/ [3] XSL Transformations (XSLT) Version 1.0, http://www.w3.org/TR/xslt/ [4] White TOH, Bruin RP, Chiang G-T, Dove MT, Tyer RP, Walker AM Lessons in scientific data interoperability: XML and the eMinerals project Phil Trans R Soc

A 2009; 367:1041-9.

[5] HTML5, http://www.w3.org/TR/html5/.

[6] Zakas NC Professional javascript for web developers 3rd ed Indianapolis: John Wiley & Sons, Inc.; 2012.

[7] Document Object Model (DOM), http://www.w3.org/DOM/.

[8] File API, http://www.w3.org/TR/FileAPI/.

[9] Scalable vector graphics (SVG) 1.1, 2nd ed., http://www.w3.org/TR/SVG11/.

Tiêu đề	A browser-based tool for conversion between Fortran NAMELIST and XML/HTML
Tác giả	Osamu Naito
Trường học	National Institutes for Quantum and Radiological Science and Technology
Chuyên ngành	Scientific computing
Thể loại	Article
Năm xuất bản	2017
Thành phố	Naka, Ibaraki

Định dạng
Số trang	5
Dung lượng	1,43 MB