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[.]
SoftwareX (2017) 25–29 Contents lists available at ScienceDirect SoftwareX journal homepage: www.elsevier.com/locate/softx A browser-based tool for conversion between Fortran NAMELIST and XML/HTML O Naito National Institutes for Quantum and Radiological Science and Technology, 801-1 Mukouyama, Naka, Ibaraki 311-0193, Japan article info Article history: Received 26 July 2016 Received in revised form 18 November 2016 Accepted December 2016 Keywords: Fortran namelist XML Web browser JavaScript abstract A browser-based tool for conversion between Fortran NAMELIST and 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 in NAMELIST, 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 © 2016 The Author Published by Elsevier B.V This is an open access article under the CC BY license (http://creativecommons.org/licenses/by/4.0/) Code metadata Current code version Permanent link to code/repository used for this code version Legal Code License Code versioning system used Software code languages, tools, and services used Compilation requirements, operating environments & dependencies If available Link to developer documentation/manual Support email for questions 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 called NAMELIST The NAMELIST provides 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 v1 https://github.com/ElsevierSoftwareX/SOFTX-D-16-00061 GNU General Public License none HTML5, JavaScript naito.osamu@qst.go.jp not based on Fortran To share the information, the software will need a specific parser to analyze the contents in NAMELIST 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 manipulate NAMELIST with powerful modern languages like Python [1] However, to make better use of NAMELIST with regard to the abovementioned points, translating NAMELIST to a standard markup http://dx.doi.org/10.1016/j.softx.2016.12.001 2352-7110/© 2016 The Author Published by Elsevier B.V This is an open access article under the CC BY license (http://creativecommons.org/licenses/by/4.0/) 26 O Naito / SoftwareX (2017) 25–29 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 , , , and , as in the following example: NAMELIST: &group1 object1 = value11, value12, value13, object2 = ( value21, value22 ), &end &group2 object3 = r * value3, &end Fig 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 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 NAMELIST files 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 Software description 2.1 Software architecture We first consider how to express the contents of NAMELIST in XML As described in the previous section, NAMELIST data 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 XML: value11 value12 value13 value21 value22 value3 where is the root element; typej denotes the data type of valuej 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 of type attribute of element but rather has its own element 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 element; (3) Other programming languages such as C, C++, Java, not have complex as an intrinsic data type We could have added size attribute to element to specify the data length in bytes as in 1.23d4 but we did not introduce this attribute, since Fortran NAMELIST generally accepts any numerical data types as its input and converts them into their appropriate internal types Therefore, an assignment statement in NAMELIST like 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 O Naito / SoftwareX (2017) 25–29 27 Fig Window after NAMELIST is 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 a NAMELIST input—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 the NAMELIST input for the first time, we only assign the most plausible type attribute to each 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 of NAMELIST and stores them as JavaScript objects by using methods associated with RegExp and String objects Each token object stores its original position in the NAMELIST input; 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 JavaScript String methods This NAMELIST to XML conversion step is the cornerstone of this tool After this conversion, further transformation to HTML or back to NAMELIST can 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 in Fig 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 the NAMELIST, 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 a NAMELIST file 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 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 NAMELIST with the file selector or, if supported, by drag and drop Fig shows an example window after ✄ the NAMELIST is loaded and converted to XML by clicking the ✂Translate to XML » ✁button The generated XML can be transformed back to NAMELIST by clicking ✄ the ✂«Translate to Namelist ✁ button Both text panes are editable, 28 O Naito / SoftwareX (2017) 25–29 Fig 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 in Fig 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 labeled Back to top is 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 in Fig 4, where the statement in NAMELIST that 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 ✂ O Naito / SoftwareX (2017) 25–29 Fig Procedures to join/disjoin the value cells Raised patterns indicate that the values are repeated multiple times as shown in the parentheses Equivalent NAMELIST statements 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 to NAMELIST by 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 Impact The primary purpose of this tool is to convert NAMELIST to 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 in NAMELIST An orthodox and direct approach to getting precise details about all NAMELIST variables would be to scan the whole source codes and find all NAMELIST 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 existing NAMELIST and 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 the NAMELIST, there is no need to have access to the Fortran source codes, nor are requirements on their side If an entire list of NAMELIST variables is needed, it might still be 29 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 of NAMELIST input Anyway, in most cases, the variables that appear in the existing NAMELIST would 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 of NAMELIST 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 Conclusions In this paper, we have presented a tiny browser-based tool for converting Fortran NAMELIST to 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 translating NAMELIST to 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/ ... tool for translating Fortran NAMELIST to XML/HTML and vice versa We only deal with NAMELIST files and keep the original Fortran source codes intact So we can safely apply this tool to legacy programs... about all NAMELIST variables would be to scan the whole source codes and find all NAMELIST statements along with associated variable declarations Since there are many good source code analysis tools... documentation of the Fortran codes, this tool serves as a simple interface for annotating the contents of NAMELIST Minimal information on variables, such as their descriptions, data types, and measurement