fortio-namelist

This is a Ruby library for reading and writing Fortran's namelist. This library allows you to read a namelist string as a Hash object, or dump a Hash object to a namelist string.

Features

Flexible parsing of (too free) namelist format using Racc
Reading namelist string as a Ruby's Hash object
Converting a Hash object to a namelist string (specifying the format)

Installation

gem install fortio-namelist

To use the library in your Ruby script,

require "fortio-namelist"

Usage

Useful methods

To read and write a namelist, it is sufficient to use only the following two methods.

FortIO::Namelist.parse(input, group: nil)
FortIO::Namelist.dump(root, **format_options)

Reading namelist

To create a Hash object with namelist structure by reading a namelist string, use the following method.

FortIO::Namelist.parse(input, group: nil)

The argument input is given as a string, but it also accepts objects with a method #read which returns a string like an IO object ('duck typing').

To read only a specific group, give a group name to the keyword argument group. If group is omitted, all namelist groups included in input will be read. To load multiple groups, give an array of group names to group.

The Hash object of the return value has a two-level structure as follows.

{
  group1: {
     var11: value11,
     var12: value12, 
        :          :
  }
  group2: {
     var21: value21,
     var22: value22,
        :          :
  }
      :        
      :
}

The group and variable names are converted to lowercase Symbol objects and stored as keys in the hash. The value can be Ruby's String, Integer, Float, Complex, TrueClass, or FalseClass objects, depending on the literal in the namelist. In the case that the value is an array, it will be expressed as an Array in Ruby. We chose symbol as the key of the hash object because it is thought to be compatible with the pattern matching introduced in Ruby 2.7.

Example:

require 'fortio-namelist'

input = %{
&group1
  var1 = 11
  var2 = 12
/
&group2
  var1 = 12
  var2 = 22
/
&group3
  var1 = 31
  var2 = 32
/
}

### read all groups
root = FortIO::Namelist.parse(input)
# => {:group1=>{:var1=>11, :var2=>12},
#     :group2=>{:var1=>12, :var2=>22},
#     :group3=>{:var1=>31, :var2=>32}}

### read only "group2"
root = FortIO::Namelist.parse(input, group: "group2")
# => {:group2=>{:var1=>12, :var2=>22}}

### read only "group1" and "group3"
root = FortIO::Namelist.parse(input, group: ["group1", "group3"])
# => {:group1=>{:var1=>11, :var2=>12}, 
#     :group3=>{:var1=>31, :var2=>32}}

Generating namelist string from Hash object with namelist structure

To generate a namelist string from a Hash object with a namelist structure, use the following method.

FortIO::Namelist.dump(root, **format_options)

The argument root is given as a Hash object. The return value is a namelist string.

Example:

require 'fortio-namelist'

root = {group1: {var1: 11, var2: 12},
        group2: {var1: 12, var2: 22},
        group3: {var1: 31, var2: 32}}

puts FortIO::Namelist.dump(root)

This script print a namelist format string to stdout.

&group1
  var1 = 11,
  var2 = 12
/
&group2
  var1 = 12,
  var2 = 22
/
&group3
  var1 = 31,
  var2 = 32
/

Format options for `FortIO::Namelist.dump`

You can finely control the output namelist string with the following keyword arguments (the first one is the default).

array_style : the notation for array elements
logical_format : boolean literals
float_format : the notation for floating point numbers
alignment : how variable identifiers are aligned
uppercase : whether variable names, etc. should be uppercase or lowercase.
separator : the separator between variable definitions
group_end : the group terminator
indent : the indentation for variable definition

`array_style` specifies the notation for array elements

'stream' : (default)
'index' :

Example:

root = {group: {var1: [1,2,3], var2: ["a","b","c"]}}

puts FortIO::Namelist.dump(root, array_style: 'stream')
# =>
# &group
#   var1 = 1, 2, 3,
#   var2 = 'a', 'b', 'c'
# /

puts FortIO::Namelist.dump(root, array_style: 'index')
# =>
# &group
#   var1(1) = 1,
#   var1(2) = 2,
#   var1(3) = 3,
#   var2(1) = 'a',
#   var2(2) = 'b',
#   var2(3) = 'c'
# /

`logical_format` specifies boolean literals

'normal' : normal notation like .true., .false (default)
'short' : short notation like t, f

root = {group: {var1: true, var2: false}}

puts FortIO::Namelist.dump(root, logical_format: 'normal')
# =>
# &group
#   var1 = .true.,
#   var2 = .false.
# /

puts FortIO::Namelist.dump(root, logical_format: 'short')
# =>
# &group
#   var1 = t,
#   var2 = f
# /

`float_format` specifies the notation for floating point numbers

'normal' : format with "%g" (default)
'd0' : format with "%g" followed by 'd0'
'exp' : exponential notation

root = {group: {var1: 1.0, var2: 12.75, var3: 50.0e-8}}

puts FortIO::Namelist.dump(root, float_format: 'normal')
# =>
# &group
#   var1 = 1,
#   var2 = 12.75,
#   var3 = 5d-07
# /

puts FortIO::Namelist.dump(root, float_format: 'd0')
# =>
# &group
#   var1 = 1d0,
#   var2 = 12.75d0,
#   var3 = 5d-07
# /

puts FortIO::Namelist.dump(root, float_format: 'exp')
# =>
# &group
#   var1 = 1d+00,
#   var2 = 1.275d+01,
#   var3 = 5d-07
# /

`alignment` specifies how variable identifiers are aligned

'left' : aligned, left-justified, position of '=' can be specified by number eg. 'left:7' (default)
'right' : aligned, right-justified, position of '=' can be specified by number eg. 'right:7'
'none' : not aligned
'stream' : not aligned, stream style, length of each line can be specified by number eg. 'stream:70'

root = {group: {var1: 1, variable2: [1,2,3], v3: true}}

puts FortIO::Namelist.dump(root, alignment: 'left')
# =>
# &group
#   var1      = 1,
#   variable2 = 1, 2, 3,
#   v3        = .true.
# /

puts FortIO::Namelist.dump(root, alignment: 'left:7')
# =>
# &group
#   var1  = 1,
#   variable2 = 1, 2, 3,
#   v3    = .true.
# /

puts FortIO::Namelist.dump(root, alignment: 'right')
# =>
# &group
#        var1 = 1,
#   variable2 = 1, 2, 3,
#          v3 = .true.
# /

puts FortIO::Namelist.dump(root, alignment: 'right:7')
# =>
# &group
#    var1 = 1,
#   variable2 = 1, 2, 3,
#      v3 = .true.
# /

puts FortIO::Namelist.dump(root, alignment: 'none')
# =>
# &group
#   var1 = 1,
#   variable2 = 1, 2, 3,
#   v3 = .true.
# /

puts FortIO::Namelist.dump(root, alignment: 'stream')
# =>
# &group
#   var1 = 1, variable2 = 1, 2, 3, v3 = .true.,
# /

`uppercase` specifies whether variable names, etc. should be uppercase or lowercase.

false : (default)
true :

root = {group: {var1: 1, var2: "a"}}

puts FortIO::Namelist.dump(root, uppercase: false)
# =>
# &group
#   var1 = 1,
#   val2 = 'a'
# /

puts FortIO::Namelist.dump(root, uppercase: true)
# =>
# &GROUP
#   VAR1 = 1,
#   VAL2 = 'a'
# /

`separator` specifies the separator between variable definitions

"comma", "," : comma + NL separeted (default)
"nl", "\n" : NL separated

root = {group1: {var1: 1, var2: "a", var3: true},
        group2: {var1: 2, var2: "b", var3: false}}

puts FortIO::Namelist.dump(root, separator: "comma")
# =>
# &group1
#   var1 = 1,
#   var2 = 'a',
#   var3 = .true.
# /
# &group2
#   var1 = 2,
#   var2 = 'b',
#   var3 = .false.
# /

puts FortIO::Namelist.dump(root, separator: "nl")
# =>
# &group1
#   var1 = 1
#   var2 = 'a'
#   var3 = .true.
# /
# &group2
#   var1 = 2
#   var2 = 'b'
#   var3 = .false.
# /

`group_end` specifies the group terminator

"slash", "/" : end with / (default)
"end" : end with &end

root = {group: {var1: true, var2: false}}

puts FortIO::Namelist.dump(root, group_end: 'slash')
# =>
# &group
#   var1 = .true.,
#   var2 = .false.
# /

puts FortIO::Namelist.dump(root, group_end: 'end')
# =>
# &group
#   var1 = .true.,
#   var2 = .false.
# &end

`indent` specifies the indentation for variable definition

' '*2 : two spaces (default)

root = {group: {var1: true, var2: false}}

puts FortIO::Namelist.dump(root, indent: ' '*2)
# =>
# &group
#   var1 = .true.,
#   var2 = .false.
# /

puts FortIO::Namelist.dump(root, indent: ' '*4)
# =>
# &group
#     var1 = .true.,
#     var2 = .false.
# /

fortio-namelist

Features

Installation

Usage

Useful methods

Reading namelist

Generating namelist string from Hash object with namelist structure

Format options for FortIO::Namelist.dump

array_style specifies the notation for array elements

logical_format specifies boolean literals

float_format specifies the notation for floating point numbers

alignment specifies how variable identifiers are aligned

uppercase specifies whether variable names, etc. should be uppercase or lowercase.

separator specifies the separator between variable definitions

group_end specifies the group terminator

indent specifies the indentation for variable definition

Format options for `FortIO::Namelist.dump`

`array_style` specifies the notation for array elements

`logical_format` specifies boolean literals

`float_format` specifies the notation for floating point numbers

`alignment` specifies how variable identifiers are aligned

`uppercase` specifies whether variable names, etc. should be uppercase or lowercase.

`separator` specifies the separator between variable definitions

`group_end` specifies the group terminator

`indent` specifies the indentation for variable definition