fortio-namelist 1.0.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eec83d1e80ab4d715f85a1e51d57a233995612e323f2729018756cd773b907e2
-  data.tar.gz: 97f524e2c0cfaae551c79fa48154c58e3ec5c1871f7e3544779fa49bc1333714
+  metadata.gz: aa95f21c798ef2256d484af31914c2688bd6b210f2a0704b69b13646eb16b338
+  data.tar.gz: 18f9dac9edbe377bc934985b703b34793737476d143c9787852b84564ca011b4
 SHA512:
-  metadata.gz: cf29f5ab82c904800ced9c0e4a61672e536fc9ba58c9e30b96b0ed4ffbed6b4b2a9b371a3f5ce6ec5c5fbc9f6af7269a9661aeb45f1f46a5c1a3653316d313f5
-  data.tar.gz: 32101d550a483bd675f2b350f022357d4784ded6bdc944cc92449f6e6c9aaa53e1a41ea26b6816284d2b96777ade58fad0f75275964089d1e87d83a2b44a89ee
+  metadata.gz: a841ab206370ee553dd92850da27009ed9dbd97ce43545843e5ff190afc5ae46407d30440f7f900708088de95c01598b4b0550c17a48b5b69a4ce205fc0fca14
+  data.tar.gz: f9f6da26c88005cd5c49ad8bb6a916d0731e98c0fd34f6f360d7760cb1fc9727209c4b313d33d4c3adfafbee2bcc8bf09c849dcbdb3a1901c2118e540d3e99d8

data/NOTE.md

@@ -0,0 +1,33 @@
+
+NOTE
+----
+
+### グループ名のプレフィックス
+
+'&'と'$'が使える。グループの終端を表す'end'のプレフィックスも同様であるが、
+始端と終端のプレフィックスのペアのチェックはしない。
+
+### 文字列の配列
+ 
+    v1 = "a", "b", 'c'  ! 引用符あり文字列の配列
+    v2 = a, b, c        ! 引用符なし文字列の配列
+    v3 = a, 0_b, _c     ! 引用符なし文字列の配列
+
+ただし、引用符あり文字列と引用符なし文字列を混在させることはできない。
+
+    v4 = "a", b, "c"    ! エラー 
+    v5 = "a", 0_b, c    ! エラー
+
+### 論理型リテラル
+
+    v1 = .true.         ! true
+    v2 = .t             ! true
+    v3 = .t_1           ! true
+    v4 = t              ! true
+    
+    v4 = .false.        ! false
+    v5 = .f             ! false
+    v5 = .f_1           ! false
+    v6 = f              ! false
+
+もちろん大文字でもよい。

data/README.md

@@ -1,7 +1,16 @@
 fortio-namelist
 ===============
 
-This is a library for reading and writing data in Fortran namelist format. With this library, you can read Fortran namelist format data from Ruby and convert it to Hash objects, and vice versa. Once the namelist format is read as a Hash object, it is easy to modify the contents or convert it to another format such as JSON, YAML, etc. When converting from a Hash object to namelist format, options can be specified to specify the case of variable names and the format of logical values and floating point numbers. The namelist format is often used as a configuration file to control a calculation program using Fortran. This library can be especially useful for batch processing by sequentially changing the settings of a calculation program. It can also improve the appearance of the namelist output from a Fortran program to make it easier to check. Since the namelist format and JSON (or YAML) can be converted to each other, it is also a good idea to use it to create web interfaces that facilitate the configuration of programs.
+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
 ------------
@@ -14,51 +23,374 @@ To use the library in your Ruby script,
 require "fortio-namelist"
 ```
 
-Description
------------
+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`.
 
-# Reading namelist data 
+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:
+
+```ruby
+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}}
+
+```
 
-    FortIO::Namelist.read(input, name: nil)
+### Generating namelist string from Hash object with namelist structure
 
-# Generate namelist format from Hash object
-    FortIO::Namelist.generate(hash, name: "namelist", array_format: 'stream')
+To generate a namelist string from a Hash object with a namelist structure, use the following method.
 
-# 複数のデータセットを含むHashからnamelist形式を生成する
     FortIO::Namelist.dump(root, **format_options)
 
-# namelistデータを読み込み、blockで評価して、結果をnamelistに変換する
-    FortIO::Namelist.filter(input, **format_options) { |hash| ... }
+The argument `root` is given as a Hash object. The return value is a namelist string. 
 
-# generate, dump, filterが受け付けるオプション
+Example:
 
-    array_style:    'index'   
-                    'stream'
+```ruby
+require 'fortio-namelist'
 
-    logical_format: 'normal'
-                    'short'
+root = {group1: {var1: 11, var2: 12},
+        group2: {var1: 12, var2: 22},
+        group3: {var1: 31, var2: 32}}
 
-    float_format:   'normal'
-                    'd0'
+puts FortIO::Namelist.dump(root)
+```
 
-    alignment:      'compact'
-                    'left'
-                    'right'
-                    Integer
+This script print a namelist format string to stdout.
 
-    uppercase:      false
-                    true
-    
-    comma:          false
-                    true
-                    
-    slash:          true
-                    false
-                    
-    indent:         ' '*2
+    &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:
 
+```ruby
+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`
+
+```ruby
+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
+
+```ruby
+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'
+
+```ruby
+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  :  
+
+```ruby
+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
+
+```ruby
+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`
+
+```ruby
+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)
+
+```ruby
+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.
+# /
+```