carray-netcdf 1.0.13 → 2.0.0

data/lib/carray/netcdf.rb

@@ -0,0 +1,287 @@
+module CA
+  # NetCDF access for CArray. One module, two layers.
+  #
+  #   CA::NetCDF   ← this module
+  #
+  # Layer 1 (this module's functions): a CArray-flavored view of the netcdf
+  # gem's `nc_*` API. `extend self` exposes every method both as a module
+  # function and as an instance method, so it is usable two ways:
+  #
+  #   CA::NetCDF.nc_get_vara(ncid, varid, start, count)    # call style
+  #
+  #   class File
+  #     include CA::NetCDF                                 # mixin style
+  #     def read = nc_get_vara(@ncid, @varid, start, count)    # bare, CArray
+  #   end
+  #
+  # {::NetCDF} is included (not mutated), so every un-overridden `nc_*` and
+  # the `NC_*` constants pass through, and `CA::NetCDF` coexists with a
+  # future `Numo::NetCDF`. Only the array I/O functions are overridden to
+  # speak CArray; scalar (`var1`), definition, inquiry, attribute and group
+  # calls fall through to {::NetCDF} verbatim.
+  #
+  # Layer 1 is raw values only: no convention decoding, no mask handling.
+  # Reads return unmasked CArrays; writing a masked CArray raises. The mask
+  # / CF story lives in layer 2 (the {File} / {Var} / {Codec} classes).
+  module NetCDF
+
+    include ::NetCDF
+    extend self
+
+    # @!group Layer 1 — array reads
+
+    # Read an entire variable.
+    #
+    # Without a buffer: allocate a CArray of the variable's {NC_TO_CA} type
+    # and the requested shape, and read into it. With a buffer (a CArray or
+    # any MemoryView provider): read into it and return it.
+    #
+    # @param ncid [Integer] NetCDF file id
+    # @param varid [Integer] variable id
+    # @param buffer [CArray, MemoryView, nil] optional destination buffer
+    # @return [CArray] the read values (a fresh CArray, or `buffer`)
+    def nc_get_var(ncid, varid, buffer = nil)
+      buffer ||= new_buffer(ncid, varid,
+                            nc_inq_vardimid(ncid, varid).map { |d| nc_inq_dimlen(ncid, d) })
+      ::NetCDF.nc_get_var(ncid, varid, buffer)
+    end
+
+    # Read a hyperslab (contiguous block).
+    #
+    # @param ncid [Integer]
+    # @param varid [Integer]
+    # @param start [Array<Integer>] per-dim start index
+    # @param count [Array<Integer>] per-dim edge count
+    # @param buffer [CArray, MemoryView, nil]
+    # @return [CArray]
+    def nc_get_vara(ncid, varid, start, count, buffer = nil)
+      ::NetCDF.nc_get_vara(ncid, varid, start, count, buffer || new_buffer(ncid, varid, count))
+    end
+
+    # Read a strided hyperslab.
+    #
+    # @param ncid [Integer]
+    # @param varid [Integer]
+    # @param start [Array<Integer>]
+    # @param count [Array<Integer>]
+    # @param stride [Array<Integer>] per-dim stride (in on-disk elements)
+    # @param buffer [CArray, MemoryView, nil]
+    # @return [CArray]
+    def nc_get_vars(ncid, varid, start, count, stride, buffer = nil)
+      ::NetCDF.nc_get_vars(ncid, varid, start, count, stride, buffer || new_buffer(ncid, varid, count))
+    end
+
+    # Read a mapped hyperslab.
+    #
+    # @param ncid [Integer]
+    # @param varid [Integer]
+    # @param start [Array<Integer>]
+    # @param count [Array<Integer>]
+    # @param stride [Array<Integer>]
+    # @param imap [Array<Integer>] per-dim mapping (in memory elements)
+    # @param buffer [CArray, MemoryView, nil]
+    # @return [CArray]
+    def nc_get_varm(ncid, varid, start, count, stride, imap, buffer = nil)
+      ::NetCDF.nc_get_varm(ncid, varid, start, count, stride, imap,
+                           buffer || new_buffer(ncid, varid, count))
+    end
+
+    # @!endgroup
+
+    # @!group Layer 1 — array writes
+    #
+    # Accept a CArray as the buffer. netcdf requires a C-contiguous buffer,
+    # so non-entity views are materialized; masked input is rejected (fill
+    # encoding is layer 2's job).
+
+    # Write an entire variable.
+    #
+    # @param ncid [Integer]
+    # @param varid [Integer]
+    # @param ca [CArray] source values (must be unmasked)
+    # @return [void]
+    # @raise [ArgumentError] if `ca` carries a mask
+    def nc_put_var(ncid, varid, ca)
+      ::NetCDF.nc_put_var(ncid, varid, writable_buffer(ca))
+    end
+
+    # Write a hyperslab.
+    # @param (see #nc_get_vara)
+    # @param ca [CArray]
+    # @return [void]
+    def nc_put_vara(ncid, varid, start, count, ca)
+      ::NetCDF.nc_put_vara(ncid, varid, start, count, writable_buffer(ca))
+    end
+
+    # Write a strided hyperslab.
+    # @param (see #nc_get_vars)
+    # @param ca [CArray]
+    # @return [void]
+    def nc_put_vars(ncid, varid, start, count, stride, ca)
+      ::NetCDF.nc_put_vars(ncid, varid, start, count, stride, writable_buffer(ca))
+    end
+
+    # Write a mapped hyperslab.
+    # @param (see #nc_get_varm)
+    # @param ca [CArray]
+    # @return [void]
+    def nc_put_varm(ncid, varid, start, count, stride, imap, ca)
+      ::NetCDF.nc_put_varm(ncid, varid, start, count, stride, imap, writable_buffer(ca))
+    end
+
+    # @!endgroup
+
+    # A fresh CArray to read `shape` elements of the variable into, typed
+    # from its on-disk type through {NC_TO_CA} -- an enum through its base
+    # type. A scalar variable (shape []) reads into a 1-element array.
+    # @api private
+    private def new_buffer(ncid, varid, shape)
+      xtype = nc_inq_vartype(ncid, varid)
+      if xtype >= NC_FIRSTUSERTYPEID
+        _, _, base, _, klass = nc_inq_user_type(ncid, xtype)
+        xtype = base if klass == NC_ENUM
+      end
+      data_type = NC_TO_CA[xtype] or
+        raise NotImplementedError, "no CArray type to read nc_type #{xtype} into; pass a buffer"
+      CArray.new(data_type, shape.empty? ? [1] : shape)
+    end
+
+    # A C-contiguous, unmasked CArray ready to hand to libnetcdf:
+    # materialize non-entity views, refuse masked input (encoding a fill
+    # value is the convention layer's decision, not layer 1's).
+    # @api private
+    private def writable_buffer(ca)
+      return ca unless ca.is_a?(CArray)
+      if ca.has_mask?
+        raise ArgumentError,
+              "cannot write a masked CArray at layer 1; strip the mask " \
+              "(e.g. #strip_mask(fill)) in the convention layer first"
+      end
+      ca.entity? ? ca : ca.copy
+    end
+
+    # @!group Type maps (`nc_type` ↔ CArray `data_type`)
+
+    # On-disk `nc_type` → CArray `data_type` symbol.
+    # @return [Hash{Integer => Symbol}]
+    NC_TO_CA = {
+      NC_BYTE => :int8,    NC_UBYTE => :uint8,  NC_SHORT => :int16,
+      NC_USHORT => :uint16, NC_INT => :int32,   NC_UINT => :uint32,
+      NC_INT64 => :int64,  NC_UINT64 => :uint64, NC_FLOAT => :float32,
+      NC_DOUBLE => :float64, NC_CHAR => :uint8,
+    }.freeze
+
+    # {Group#def_var} type argument (Symbol or String) → `nc_type`.
+    # @return [Hash{Symbol => Integer}]
+    TYPE_TO_NC = {
+      double: NC_DOUBLE, float: NC_FLOAT, int: NC_INT, short: NC_SHORT,
+      byte: NC_BYTE, char: NC_CHAR, ubyte: NC_UBYTE, ushort: NC_USHORT,
+      uint: NC_UINT, int64: NC_INT64, uint64: NC_UINT64,
+      # CArray-style aliases
+      int8: NC_BYTE, uint8: NC_UBYTE, int16: NC_SHORT, uint16: NC_USHORT,
+      int32: NC_INT, uint32: NC_UINT, float32: NC_FLOAT, float64: NC_DOUBLE,
+    }.freeze
+
+    # Coerce a `def_var`-style type to its `nc_type` integer.
+    #
+    # An Integer is already an `nc_type` (e.g. from {Var#nc_type} on a
+    # template source). Pass it through so `def_var(..., template: v)` can
+    # preserve `NC_CHAR` vs `NC_UBYTE` — both map to `:uint8` in {NC_TO_CA}
+    # and the symbol round-trip would lose the distinction.
+    #
+    # @param type [Symbol, String, Integer]
+    # @return [Integer] an `NC_*` type constant
+    # @raise [ArgumentError] on an unrecognized type name
+    def nc_type_for(type)
+      return type if type.is_a?(Integer)
+      TYPE_TO_NC[type.to_s.to_sym] or
+        raise ArgumentError, "unknown NetCDF variable type: #{type.inspect}"
+    end
+
+    # `nc_type` → typed `nc_put_att_*` suffix.
+    # @return [Hash{Integer => Symbol}]
+    PUT_ATT_SUFFIX = {
+      NC_BYTE => :schar,  NC_UBYTE => :uchar,  NC_SHORT => :short,
+      NC_USHORT => :ushort, NC_INT => :int,    NC_UINT => :uint,
+      NC_INT64 => :longlong, NC_UINT64 => :ulonglong,
+      NC_FLOAT => :float, NC_DOUBLE => :double, NC_CHAR => :text,
+    }.freeze
+
+    # Attributes that NetCDF/CF require to be in the variable's (packed)
+    # type. `_FillValue` is enforced by libnetcdf; the rest match by
+    # convention and so that masked-value comparison in the codec works in
+    # packed space.
+    # @return [Array<String>]
+    PACKED_SPACE_ATTS = %w[_FillValue missing_value valid_range valid_min valid_max].freeze
+
+    # Write an attribute forced to `nc_type` (via the typed
+    # `nc_put_att_*`), falling back to the generic inference when the type
+    # has no typed writer.
+    #
+    # @param ncid [Integer]
+    # @param varid [Integer]
+    # @param name [String]
+    # @param value [Object] Ruby value or CArray
+    # @param nc_type [Integer] target `NC_*` type
+    # @return [void]
+    def put_att_typed(ncid, varid, name, value, nc_type)
+      suffix = PUT_ATT_SUFFIX[nc_type]
+      return nc_put_att(ncid, varid, name, value) unless suffix
+      fn = "nc_put_att_#{suffix}"
+      if put_att_takes_xtype?(fn)
+        __send__(fn, ncid, varid, name, nc_type, value)
+      else
+        __send__(fn, ncid, varid, name, value)
+      end
+    end
+
+    # A netcdf gem after 0.1.0 takes the on-disk xtype apart from the
+    # suffix's memory type, as C does; 0.1.0 has no xtype argument. Read
+    # the arity of the binding itself, past any `*args` wrapper prepended
+    # over it (a lock, say).
+    # @api private
+    PUT_ATT_XTYPE = Hash.new do |h, fn|
+      m = ::NetCDF.method(fn)
+      m = m.super_method while m.arity.negative? && m.super_method
+      h[fn] = m.arity == 5
+    end
+    private_constant :PUT_ATT_XTYPE
+
+    # @api private
+    private def put_att_takes_xtype?(fn) = PUT_ATT_XTYPE[fn]
+
+    # Write a variable attribute the way {Group#def_var} does:
+    #
+    # - a CArray keeps its own type (`_FillValue: CA_SHORT([-1])` on a
+    #   float variable is a short attribute);
+    # - a Ruby value for a {PACKED_SPACE_ATTS} name takes the variable's
+    #   on-disk type `var_type`, which libnetcdf requires of `_FillValue`;
+    # - anything else is left to the generic `nc_put_att` inference.
+    #
+    # @param ncid [Integer]
+    # @param varid [Integer]
+    # @param name [String]
+    # @param value [Object] Ruby value or CArray
+    # @param var_type [Integer] the variable's `NC_*` type
+    # @return [void]
+    # @api private
+    def put_var_att(ncid, varid, name, value, var_type)
+      if value.is_a?(CArray)
+        put_att_typed(ncid, varid, name, value.to_a, TYPE_TO_NC[value.data_type])
+      elsif PACKED_SPACE_ATTS.include?(name)
+        put_att_typed(ncid, varid, name, value, var_type)
+      else
+        nc_put_att(ncid, varid, name, value)
+      end
+    end
+
+    # @!endgroup
+  end
+end
+
+require_relative "netcdf/version"
+require_relative "netcdf/codec"
+require_relative "netcdf/dim"
+require_relative "netcdf/var"
+require_relative "netcdf/group"
+require_relative "netcdf/file"

data/lib/carray-netcdf.rb

@@ -1,2 +1,4 @@
 require "carray"
-require "carray/io/netcdf"
+require "netcdf"
+
+require "carray/netcdf"

metadata

@@ -1,39 +1,95 @@
 --- !ruby/object:Gem::Specification
 name: carray-netcdf
 version: !ruby/object:Gem::Version
-  version: 1.0.13
+  version: 2.0.0
 platform: ruby
 authors:
-- Hiroki Motoyoshi
-autorequire: 
+- himotoyoshi
 bindir: bin
 cert_chain: []
-date: 2020-09-14 00:00:00.000000000 Z
-dependencies: []
-description: "    Extension for manipulating NetCDF3 file with CArray\n"
-email: ''
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: carray
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.1
+- !ruby/object:Gem::Dependency
+  name: netcdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: |
+  A NetCDF interface for CArray, built on the netcdf gem.  Data is
+  exchanged as CArray at every level, through Ruby's MemoryView protocol,
+  so libnetcdf works on the array's own memory.
+
+  Two layers do this.  Layer 1 turns the netcdf gem's MemoryView buffers
+  into CArray, keeping the nc_* functions as they are.  Layer 2 builds the
+  object-oriented interface on top, and returns data as the file's
+  conventions define it: _FillValue as a mask, scale_factor and add_offset
+  applied, CF time as CATime.  Pure Ruby, on CArray 3.0.
+email:
+- himotoyoshi@users.noreply.github.com
 executables:
-- ncdef2yaml
-extensions:
-- ext/extconf.rb
+- ncheader
+- ncvar
+extensions: []
 extra_rdoc_files: []
 files:
-- API.md
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
 - README.md
-- Rakefile
-- bin/ncdef2yaml
+- bin/ncheader
+- bin/ncvar
 - carray-netcdf.gemspec
-- examples/test.nc
-- examples/test.rb
-- examples/time.rb
-- ext/extconf.rb
-- ext/rb_netcdflib.c
+- docs/00_introduction.md
+- docs/01_getting_started.md
+- docs/02_reading.md
+- docs/03_writing.md
+- docs/04_codec.md
+- docs/05_groups.md
+- docs/06_layer1.md
+- docs/07_cookbook.md
+- docs/08_cheatsheet.md
+- docs/09_cli.md
 - lib/carray-netcdf.rb
-- lib/io/netcdf.rb
+- lib/carray/netcdf.rb
+- lib/carray/netcdf/codec.rb
+- lib/carray/netcdf/dim.rb
+- lib/carray/netcdf/file.rb
+- lib/carray/netcdf/group.rb
+- lib/carray/netcdf/var.rb
+- lib/carray/netcdf/version.rb
 homepage: https://github.com/himotoyoshi/carray-netcdf
-licenses: []
+licenses:
+- MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -41,15 +97,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.8.1
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 4.0.8
 specification_version: 4
-summary: Extension for manipulating NetCDF3 file with CArray
+summary: A NetCDF interface for CArray
 test_files: []

data/API.md

@@ -1,270 +0,0 @@
-CArray/NetCDF library API document
-==================================
-
-1. Loading library
-------------------
-
-    gem install carray-netcdf
-    
-    require "carray-netcdf"
-
-2. Methods 
-----------
-
-This API provides the way of calling functions
-
-    include NC
-    nc_funcname(...)
-    
-    NC.funcname(...)
-
-### 2.1. Data types
-
-    data_type = NC.ca_type(xtype)
-    xtype     = NC.nc_type(data_type)
-
-### 2.2. NetCDF File
-
-    fd = nc_create(FILENAME[, mode=NC_CLOBBER])
-       
-       mode : NC_CLOBBER   - permit overwrite 
-              NC_NOCLOBBER - inhibit overwrite
-              NC_SHARE     - no buffering
-    
-    fd = nc_open(FILENAME[, mode=NC_NOWRITE])
-       
-       mode : NC_NOWRITE   - readonly
-              NC_WRTIE     - writable
-              NC_SHARE     - no buffering
-    
-    nc_close(fd)
-    
-    nc_redef(fd)
-    nc_enddef(fd)
-    
-    nc_sync(fd)
-    
-    ndims    = nc_inq_ndims(fd)
-    nvars    = nc_inq_nvars(fd)
-    natts    = nc_inq_natts(fd)
-    unlimdim = nc_inq_unlimdim(fd)
-    
-    oldmode  = nc_set_fill(mode)
-    
-       mode : NC_FILL
-              NC_NOFILL
-
-### 2.3. NetCDF Dimension
-
-    dimid    = nc_def_dim(fd, dimname, len)
-    dimid    = nc_inq_dimid(fd, dimname)    => Integer | nil
-    
-    dimname  = nc_inq_dimname(fd, dimid)
-    dimlen   = nc_inq_dimlen(fd, dimid)
-    
-    nc_rename_dim(fd, dimid, newname)
-
-### 2.4. NetCDF Variable
-
-    varid    = nc_def_var(fd, varname, type, dim)
-    varid    = nc_inq_varid(fd, varname)    => Integer | nil
-    
-    vartype  = nc_inq_vartype(fd, varid)
-    varndims = nc_inq_varndims(fd, varid)
-    vardimid = nc_inq_varndimid(fd, varid)  => Array of dimids
-    
-    nc_put_var1(fd, varid, [i,j,..], val)
-    nc_put_var(fd, varid, ca)
-    nc_put_vara(fd, varid, start, count, ca)
-    nc_put_vars(fd, varid, start, count, stride, ca)
-    nc_put_varm(fd, varid, start, count, stride, imap, ca)
-    
-      + with data_type conversion
-    
-    val = nc_get_var1(fd, varid, [i,j,..])
-    ca = nc_get_var(fd, varid)                              [useful]
-    ca = nc_get_vara(fd, varid, start, count)               [useful]
-    ca = nc_get_vars(fd, varid, start, count, stride)       [useful]
-    ca = nc_get_varm(fd, varid, start, count, stride, imap) [useful]
-    
-      + no data_type conversion
-    
-    nc_get_var(fd, varid, ca)                               [pedantic]
-    nc_get_vara(fd, varid, start, count, ca)                [pedantic]
-    nc_get_vars(fd, varid, start, count, stride, ca)        [pedantic]
-    nc_get_varm(fd, varid, start, count, stride, imap, ca)  [pedantic]
-    
-      + with data_type conversion.
-    
-    nc_rename_var(fd, varid, newname)
-
-### 2.5. NetCDF Attribute
-
-    varnatts = nc_inq_varnatts(fd, varid)
-    attid    = nc_inq_attid(fd, varid, attname)
-    
-    attname  = nc_inq_attname(fd, varid, attid)
-    atttype  = nc_inq_atttype(fd, varid, attname)
-    attlen   = nc_inq_attlen(fd, varid, attname)
-    
-    nc_put_att(fd, varid, attname, val)
-    
-      varid : NC_GLOBAL for global att
-      val   : String  -> NC_CHAR
-              Integer -> NC_INT
-              Float   -> NC_DOUBLE
-              CArray  -> NC.nc_type(val.data_type)
-    
-    
-    val = nc_get_att(fd, varid, attname)  => String | Numeric | CArray | nil
-    
-      varid : NC_GLOBAL for global att
-    
-    nc_get_att(fd, varid, attname, ca)                 [pedantic]
-    
-    nc_rename_att(fd, varid, attname, newname)
-    nc_del_att(fd, varid, attname)
-    
-    nc_copy_att(fd1, varid1, attname, fd2, varid2)
-
-### 2.6 Constants
-
-    NC_NAT 
-    NC_BYTE
-    NC_SHORT
-    NC_INT
-    NC_FLOAT
-    NC_DOUBLE
-    
-    NC_NOERR        - status of API routines
-    
-    NC_CLOBBER      - permit overwrite  [nc_create]
-    NC_NOCLOBBER    - inhibit overwrite [nc_create]
-    NC_NOWRITE      - readonly [nc_open]
-    NC_WRITE        - writable [nc_open]
-    NC_SHARE        - no buffering [nc_create, nc_open]
-    
-    NC_GLOBAL       - varid for global attributes
-    
-    NC_NOFILL       - nc_set_fill(fd, varid, NC_NOFILL)
-    NC_FILL         - nc_set_fill(fd, varid, NC_FILL)
-    
-    NC_MAX_NAME
-    NC_MAX_VAR_DIMS
-    NC_MAX_DIMS
-    
-    NC_LOCK         - ???
-    NC_SIZEHINT_DEFAULT - ???
-
-3. NCFile interface
--------------------
-
-NCFile interface provides the way of *READ-ONLY* access to the netcdf file.
-
-### 3.1. NCFile 
-
-    nc = NCFile.open(FILENAME)
-    
-    nc = NCFile.new(file_id)
-           file_id: return value of nc_open in read-only mode
-
-### 3.2. Dimensions 
-
-    nc.has_dim?(DIMNAME)
-    nc.dims               - Array of dimension
-    
-    dim = nc.dim(DIMNAME) - NCDim object or nil
-    dim.to_i              - size of dimension
-    dim.to_ca             
-
-### 3.3. Variables
-
-    nc.has_var?(VARNAME)
-    nc.vars               - Array of variables
-    
-    var = nc.var(VARNAME) - NCVar object or nil
-    var.is_dim?           - true if dimension variable
-    var.to_ca             - get array as CArray object
-    var[...]              - Cooked value array with CArray-like indexing
-    var.get!(...)         - same as [...]
-    var.get(...)          - Non-cooked value array with CArray-like indexing
-    
-    var.get_var1(...)     - interface to original get function 
-    var.get_var()
-    var.get_vara(start, count)
-    var.get_vars(start, count, stride)
-    var.get_varm(start, count, stride, imap)
-    var.get_var1!(...)
-    var.get_var!()
-    var.get_vara!(start, count)
-    var.get_vars!(start, count, stride)
-    var.get_varm!(start, count, stride, imap)
-
-### 3.4. Attributes 
-
-All attributes are already read in initializing process of NCFile object.
-
-    nc.attributes           - Hash
-    dim.attributes          
-    var.attributes          
-    
-    nc.attribute(ATTNAME)   - accessor
-    dim.attribute(ATTNAME)
-    var.attribute(ATTNAME)
-
-
-### 3.5. Iteration
-
-No iteration methods is provided, but accessor methods for dims, vars, attributes can be used.
-
-    ex)
-    
-      nc.attributes.each {|key, value| ... }
-      nc.dims.each {|dim| ... }
-      nc.vars.each {|var| ... }
-
-4. NCFileWriter interface
--------------------------
-
-It provides simple interface to create netcdf file.
-If you want the detailed controling to create netcdf, use nc_function API.
-
-    out = NCFileWrite.new("test.nc")
-    
-    out.define(
-      dimensions: {                      ### dimension
-        lon: 230,                        ###   name: Integer
-        lat: 120,
-        time: 24
-      },
-      variables: {                            ### variables
-        temp: {                                name: definition
-          type: int,                           type: Integer or string (default NC::NC_FLOAT)
-                                                  one of byte,short,int,float,double
-          dim: ["time", "lat", "lon"],         dim: Array of dim names
-          long_name: "air temperature",        attributes for variable are parallel with type, dim
-          units: "degC"
-          param1: { float: 1.2 }
-          param2: { int: 10 }
-        }
-      },
-      attributes: {
-        creator: "foobar"                  ### global attributes (Hash)
-      }
-    )
-    
-    out["lon"]  = lon
-    out["lat"]  = lat
-    out["time"] = time
-    out["temp"][nil] = temp                  ### CArray index can be used
-    out.write                            ### call nc_close 
-    
-    nc = NCFile.open("test.nc")
-    nc.definition                        ### return definition Hash 
-
-
-### template with CDL
-
-    out = NCFileWrite.new("test.nc", template: cdl_text)
-    
-