carray-netcdf 1.0.14 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a33ee27fee3615ab311f92d48aa49e072bf980f1847a0c5690909312a3844d5
-  data.tar.gz: b436d42abf2cd7d313a1b8b76e63ec4f0cf5cdf00ef8da80f50e0f56e131e71f
+  metadata.gz: 71bb04b44cd8c06925d970fb1e69ebdea46b7320aeec1e3c542aca3668a66cfc
+  data.tar.gz: 864e70e40ec87e90200e74ca97590e7449808dd8e5d012ce64aac8805182733f
 SHA512:
-  metadata.gz: c69f23298b520f0386660c82b278134e43dce3f80e1399af0b461a718ddf01ca733bfa83254cc06e3b3b9ce167336db047ece595da0323d8e7fcca2a0aabdea7
-  data.tar.gz: ce08df0cca958ef3b5450aedadd0fe4216caa05b3ee7557655541ce50d43683fb82832340364c56f7906e02369ecd766e0981b22cffdb3b298eb79281b05e0da
+  metadata.gz: 99b7b5824c461197bbdb4b7161d59728d095976c207964d34208d560a7a14ef4c9a432ef8a76ee974ad97095fe4b89e611dd5b9e262cf25b20f734c30eb0d737
+  data.tar.gz: d9ef82a43aaacdb8d9e0b83786d3f0d222f4738feb3fc2b3b785cc01cbcf7117ae83c5f51372831c3b80e4bfb503ab84e231917568adc9c2551133d09fab65f9

data/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+Releases are recorded here from 2.0.0, the first release of the rewrite.
+There is no separate NEWS file: this is where to look for what changed
+between the version you have and a newer one. The 1.x series was a
+different codebase and is not covered.
+
+<!-- Newest first, at both levels: a new release section goes above the
+     ones below it, and a new entry goes directly under its own release
+     heading -- not at the end of the section. The kind of change is
+     carried by the `- Fix:` / `- Change:` / `- New:` that opens the
+     entry; there are no per-kind subheadings.
+
+     A section is written newest-first while the release is open, and
+     sorted into New, Change, Fix when it closes -- in the same commit
+     that drops `(unreleased)`. Within Change, the ones that ask the
+     reader to change code come first.
+
+     An entry says three things and stops: what changed, what to do about
+     it (the migration, the replacement, the condition under which nothing
+     changes), and what is excluded. It does not say how the code was
+     broken or name the internals that were fixed -- those belong in the
+     commit message. Two to six lines.
+
+     It is written for someone using the library, not someone working on
+     it: with no NEWS file, this is what a reader consults before
+     upgrading.
+
+     The version here is this gem's own and is neither CArray's nor the
+     netcdf gem's. Which of those a release needs is said in the gemspec,
+     and an entry says so only when the answer changes. -->
+
+## 2.0.0
+
+A ground-up rewrite. Nothing from 1.x is carried over, so read this as a
+new library that happens to keep the name rather than as an upgrade.
+
+- Change: the gem is pure Ruby and no longer builds a C extension of its
+  own. libnetcdf is reached through the [netcdf](https://github.com/himotoyoshi/netcdf)
+  gem, and CArray 3.0 hands it memory through the MemoryView protocol, so
+  nothing is copied on the way in or out. Installing it therefore needs
+  libnetcdf present for that gem to build against, not for this one.
+
+- Change: NetCDF-4 files are read and written, where 1.x was NetCDF-3
+  only. That brings groups, `NC_STRING`, per-variable chunking and
+  compression, and the unlimited dimension in its NetCDF-4 form.
+
+- Change: everything lives in `CA::NetCDF`, and `::NetCDF` — the thin
+  binding — is included rather than modified, so a future `Numo::NetCDF`
+  can sit beside it. Code written against 1.x's names does not run here.
+
+- New: layer 1, `CA::NetCDF`'s own `nc_*` functions. They are the
+  netcdf gem's API with the array I/O overridden to take and return
+  CArrays; definition, inquiry, attribute, and group calls pass through
+  verbatim. Usable as module functions or by `include CA::NetCDF`.
+
+- New: layer 2, the object-oriented surface — `File`, `Group`, `Var`,
+  `Dim`. `File.open` / `File.create`, `nc[:temp]` to read a variable,
+  `nc[:temp, 0..9] = data` to write a hyperslab, lazy hyperslab reads,
+  file-wide variable option defaults, and atomic writes through a
+  visible `.tmp` name.
+
+- New: pluggable conventions. CF and COARDS codecs decode `_FillValue`
+  into a CArray mask and apply `scale_factor` / `add_offset`, CF time
+  becomes `CATime`, and `valid_range` masking is available opt-in.
+  `Identity` is the codec that does none of it.
+
+- New: `File.create` takes a template, so a file can be generated with
+  another file's dimensions, attributes, and variable definitions —
+  copied, overridden, or skipped per item.
+
+- New: `ncheader` and `ncvar` on the command line. `ncheader` prints a
+  file's header as CDL, JSON, or YAML; `ncvar` streams a variable, or a
+  hyperslab of one, as raw native-endian bytes, text, or JSON.
+
+- New: Zarr stores open and create through `File.open` / `File.create`
+  given a URL such as `"file:///data/t.zarr#mode=zarr,file"`, when
+  libnetcdf was built with NCZarr. `atomic:` and `clobber: false` /
+  `:skip` take a file path only and raise `ArgumentError` with a URL.

data/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to carray-netcdf
+
+Thanks for looking. The short version: an issue is easier to act on here than a pull request.
+
+## What to send
+
+| What you have | How to send it |
+|---|---|
+| **A bug report or a feature request** | Open an issue. |
+| **A small, self-contained bug fix** | Open a pull request. |
+| **Anything larger** | Open an issue first. |
+
+carray-netcdf was built the way the README describes: designed and reviewed by me, implemented in collaboration with AI coding tools. That has a consequence worth saying plainly, because it is not visible from outside. Code here gets rewritten as a matter of course — mine included. A patch that touches the internals is likely to be reimplemented rather than merged, and not because anything is wrong with it. That is simply how work moves through this repository.
+
+So a description travels further than a diff. An issue saying what you were trying to do, what happened, and what you expected can be acted on directly.
+
+A small, self-contained bug fix is the exception. Send it as a pull request.
+
+## Which repository a bug belongs to
+
+Three gems are stacked here, and the layer decides where the issue goes:
+
+- **carray-netcdf** — anything about `CA::NetCDF`: the codecs, the mask, `File` / `Group` / `Var` / `Dim`, how a hyperslab is addressed.
+- **[netcdf](https://github.com/himotoyoshi/netcdf)** — a bare `nc_*` call that misbehaves, a libnetcdf feature that is missing, a build failure against libnetcdf.
+- **[carray](https://github.com/himotoyoshi/carray)** — arithmetic, slicing, or masks going wrong on an array once it is in hand.
+
+When you are not sure, open it here. Being told which of three repos to use is not a reasonable thing to ask of a reporter.
+
+## Opening an issue
+
+Issues in English or Japanese are both fine.
+
+For a bug, include:
+
+- carray-netcdf version (`CA::NetCDF::VERSION`), CArray version (`CArray::VERSION`), netcdf gem version (`NetCDF::VERSION`), libnetcdf version (`NetCDF.nc_inq_libvers`), Ruby version, and OS
+- The smallest script that shows the problem
+- What you expected and what you got
+
+And, where they apply, the things most bugs here turn on:
+
+- the **codec** in force. Unless you named one, it was chosen from the file's `Conventions` attribute, so two files can read differently through the same code. A value wrong by exactly `scale_factor` is a codec question rather than an I/O one — say what `codec: :identity` gives for the same read
+- whether elements came back **masked**, and what the variable's `_FillValue` / `valid_range` attributes are
+- the variable's **NetCDF type** against the CArray type you got, when the complaint is about values rather than shape
+- whether the dimension involved is **unlimited**
+- the file itself, or what `ncdump -h` says about it. A file that one writer produced and another cannot read is the common case, and the header settles it
+
+## Sending a fix
+
+Ruby 3.1 or later, CArray and the netcdf gem in the ranges the gemspec declares. Sibling checkouts of `carray` and `netcdf` beside this one are picked up automatically when they are there; otherwise the installed gems are used.
+
+```sh
+rake spec               # the whole suite (also the default task)
+rake dependency_check   # do the gems in use fall inside the gemspec's ranges
+```
+
+`rake spec` must report no failures.
+
+The tests are hand written, one file per area, and a test for your fix goes beside the ones it belongs with. They write real NetCDF files into a temporary directory and read them back: a change is considered tested when the values survive the round trip, not when the call returns without raising.
+
+Then, in the same pull request:
+
+- If you changed what a public method does or accepts, update its documentation comment in `lib/` and the page in `docs/` that covers it. [docs/08_cheatsheet.md](docs/08_cheatsheet.md) lists the entry points and goes stale first.
+- Add an entry to [CHANGELOG.md](CHANGELOG.md), at the top of the unreleased section, opening with `- Fix:`. Write it for someone who hit the bug: what behaves differently now, not how the code was wrong.
+
+Keep the commit message to a subject line and a line or two of context. Anything a user needs to know belongs in the changelog entry rather than in the commit.
+
+## Working on the code
+
+`docs/` is the guide and is written to be read in order. The code is one file per class under `lib/carray/netcdf/`, with layer 1 — the `nc_*` functions that speak CArray — in `lib/carray/netcdf.rb` itself.
+
+The line worth holding while working here: layer 1 is raw values only. No convention decoding, no mask handling; reads come back unmasked and writing a masked CArray raises. Everything about `_FillValue`, `scale_factor`, and time belongs to the codecs in layer 2.
+
+## License
+
+By submitting a pull request, you agree that your contribution is licensed under the MIT License, the same terms as the rest of the project.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 himotoyoshi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,3 +1,109 @@
-This directory contains the plugin library used as the interface to NetCDF 
-from Ruby/CArray. 
+# carray-netcdf
 
+A NetCDF interface for [CArray](https://github.com/himotoyoshi/carray), built on the [netcdf](https://github.com/himotoyoshi/netcdf) gem.
+
+Data is exchanged as CArray at every level: reads return a CArray and writes accept one. Both go through Ruby's MemoryView protocol, so libnetcdf reads and writes the array's own memory, with no intermediate representation of the data.
+
+Two layers do this, both in the `CA::NetCDF` module. 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: `File`, `Group`, `Var`, `Dim` and the codecs. Both are pure Ruby, on CArray 3.0; every libnetcdf call goes through the netcdf gem.
+
+Layer 2 gives you data as the file's conventions define it. For a file declaring CF or COARDS, values are decoded on the way out: `_FillValue` becomes a mask, `scale_factor` and `add_offset` are applied, and time coordinates become CATime. Variables are indexed like CArrays, and only the elements you index are read — `nc["temp"][0..9, nil, nil]` reads ten days, not the whole variable.
+
+## Status
+
+2.0 still moves: its own surface is not settled yet, so behaviour can change between releases.
+
+## Features
+
+* **Object-oriented access to NetCDF data.** A file, a group, a variable and a dimension are objects: `File.open`, `nc["temp"]`, `var.dims`, `var.atts`, and a block form that closes the file for you.
+* **CArray in and out.** Reads return a CArray and writes accept one. A variable is indexed the way a CArray is, so only the slab you ask for is read, and libnetcdf works on the array's own memory rather than a copy of it.
+* **Conventions are decoded — CF, COARDS, or none.** Under CF or COARDS, `_FillValue` becomes a mask, `scale_factor` and `add_offset` are applied, and a time axis becomes CATime. `codec: :identity` gives you the stored values instead, and a codec of your own can take their place.
+* **NetCDF-4 groups.** Variables are addressed by path (`nc["/obs/temp"]`), dimensions are inherited from the groups above, and the file's codec applies inside them.
+* **Writing is a schema and an assignment.** `def_dim`, `def_var`, `def_att`, then `nc["temp"] = ca`. Attributes that CF requires to match the variable's type are written in that type, so other tools read the file as intended.
+* **Atomic writes.** `File.create(atomic: true)` writes to a temporary file in the same directory and renames it into place only when the block completes, so a failed run leaves no half-written file behind.
+
+## Install
+
+libnetcdf and its headers have to be present first, because the netcdf gem underneath is built against them:
+
+```
+brew install netcdf          # macOS
+apt install libnetcdf-dev    # Debian / Ubuntu
+dnf install netcdf-devel     # Fedora / RHEL
+```
+
+Then:
+
+```
+gem install carray-netcdf
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "carray-netcdf"
+```
+
+Requires:
+
+- Ruby >= 3.1
+- carray >= 3.0.1
+- the netcdf gem, installed as a dependency
+
+## Example
+
+```ruby
+require "carray-netcdf"
+
+NC = CA::NetCDF
+
+# --- write ---
+NC::File.create("out.nc") do |nc|
+  nc.def_dim("time", :unlimited)
+  nc.def_dim("lat", 73)
+  nc.def_dim("lon", 144)
+
+  nc.def_var("temp", :float, ["time", "lat", "lon"],
+             units: "K", _FillValue: -999.9)
+
+  nc.def_att("Conventions", "CF-1.7")
+
+  nc["temp"] = CArray.float32(1, 73, 144) { rand * 30 + 260 }
+end
+
+# --- read ---
+NC::File.open("out.nc") do |nc|
+  t = nc["temp"]
+  t.shape                     #  => [1, 73, 144]
+  t.dims.map(&:name)          #  => ["time", "lat", "lon"]
+
+  day = t[0, nil, nil]        #  a 2-D CArray; only this slab is read
+  day.mean                    #  CF decoding has already been applied
+end
+```
+
+## Documentation
+
+* [Introduction](docs/00_introduction.md) — why there are two layers, and what the gem leaves to CArray
+* [Getting started](docs/01_getting_started.md) — install, then read and write a first file
+* [Reading files](docs/02_reading.md) — opening a file, finding a variable, reading all or part of it
+* [Writing files](docs/03_writing.md) — declaring the schema, writing data, changing a file later
+* [Codecs and CF conventions](docs/04_codec.md) — what gets decoded, how a codec is chosen, writing your own
+* [Groups](docs/05_groups.md) — NetCDF-4 groups, and what they inherit
+* [Layer 1](docs/06_layer1.md) — the `nc_*` functions with CArray in and out
+* [Cookbook](docs/07_cookbook.md) — worked solutions to real tasks
+* [Cheatsheet](docs/08_cheatsheet.md) — every method and constant of the gem on one page
+* [Command-line tools](docs/09_cli.md) — `ncheader` and `ncvar`, which ship with the gem
+
+## Contributing
+
+Bug reports and feature requests are welcome — please open an issue.
+
+**An issue is easier to act on here than a pull request.** [CONTRIBUTING.md](CONTRIBUTING.md) says why, and what to put in one.
+
+## Credits
+
+carray-netcdf was designed and reviewed by a human developer; the implementation was produced in collaboration with AI coding tools.
+
+## License
+
+MIT

data/bin/ncheader

@@ -0,0 +1,223 @@
+#!/usr/bin/env ruby
+# ncheader — dump a NetCDF file's header in CDL (ncdump -h style), JSON,
+# or YAML.  Header only: dimensions, variables, attributes, groups, and
+# user-defined types — data values are not printed.
+#
+#   $ ncheader FILE.nc            # CDL (default)
+#   $ ncheader -f json FILE.nc
+#   $ ncheader -f yaml FILE.nc
+
+require "netcdf"
+require "json"
+require "yaml"
+require "optparse"
+
+PRIMITIVE_TYPE_NAMES = {
+  NetCDF::NC_BYTE   => "byte",
+  NetCDF::NC_CHAR   => "char",
+  NetCDF::NC_SHORT  => "short",
+  NetCDF::NC_INT    => "int",
+  NetCDF::NC_FLOAT  => "float",
+  NetCDF::NC_DOUBLE => "double",
+  NetCDF::NC_UBYTE  => "ubyte",
+  NetCDF::NC_USHORT => "ushort",
+  NetCDF::NC_UINT   => "uint",
+  NetCDF::NC_INT64  => "int64",
+  NetCDF::NC_UINT64 => "uint64",
+  NetCDF::NC_STRING => "string",
+}
+
+def type_name(ncid, xtype)
+  PRIMITIVE_TYPE_NAMES[xtype] || NetCDF.nc_inq_type(ncid, xtype).first
+end
+
+def collect_attrs(ncid, varid, natts)
+  natts.times.map do |i|
+    name  = NetCDF.nc_inq_attname(ncid, varid, i)
+    xtype, _len = NetCDF.nc_inq_att(ncid, varid, name)
+    {
+      "name"  => name,
+      "type"  => type_name(ncid, xtype),
+      "value" => NetCDF.nc_get_att(ncid, varid, name),
+    }
+  end
+end
+
+def collect_user_types(ncid)
+  typeids = NetCDF.nc_inq_typeids(ncid)
+  typeids.map do |tid|
+    name, _size, base_type, _nfields, klass = NetCDF.nc_inq_user_type(ncid, tid)
+    info = { "name" => name, "typeid" => tid }
+    case klass
+    when NetCDF::NC_ENUM
+      _, _, _, nmembers = NetCDF.nc_inq_enum(ncid, tid)
+      info["kind"]    = "enum"
+      info["base"]    = type_name(ncid, base_type)
+      info["members"] = nmembers.times.map { |i|
+        mname, mvalue = NetCDF.nc_inq_enum_member(ncid, tid, i)
+        { "name" => mname, "value" => mvalue }
+      }
+    when NetCDF::NC_OPAQUE
+      _, osize = NetCDF.nc_inq_opaque(ncid, tid)
+      info["kind"] = "opaque"
+      info["size"] = osize
+    when NetCDF::NC_VLEN
+      _, _dsize, btype = NetCDF.nc_inq_vlen(ncid, tid)
+      info["kind"] = "vlen"
+      info["base"] = type_name(ncid, btype)
+    when NetCDF::NC_COMPOUND
+      info["kind"] = "compound"   # field metadata not yet exposed by gem
+    end
+    info
+  end
+end
+
+def inspect_group(ncid)
+  _, _, natts, unlimid = NetCDF.nc_inq(ncid)
+
+  dims = NetCDF.nc_inq_dimids(ncid, false).map { |id|
+    name, len = NetCDF.nc_inq_dim(ncid, id)
+    { "name" => name, "length" => len, "unlimited" => (id == unlimid) }
+  }
+
+  vars = NetCDF.nc_inq_varids(ncid).map { |vid|
+    vname, xtype, _ndims, vdimids, vnatts = NetCDF.nc_inq_var(ncid, vid)
+    {
+      "name"       => vname,
+      "type"       => type_name(ncid, xtype),
+      "dimensions" => vdimids.map { |d| NetCDF.nc_inq_dimname(ncid, d) },
+      "attributes" => collect_attrs(ncid, vid, vnatts),
+    }
+  }
+
+  subgroups = NetCDF.nc_inq_grps(ncid).map { |gid|
+    inspect_group(gid).merge("name" => NetCDF.nc_inq_grpname(gid))
+  }
+
+  {
+    "types"      => collect_user_types(ncid),
+    "dimensions" => dims,
+    "variables"  => vars,
+    "attributes" => collect_attrs(ncid, NetCDF::NC_GLOBAL, natts),
+    "groups"     => subgroups,
+  }
+end
+
+# ---- CDL formatter ----
+
+TYPE_SUFFIX = {
+  "byte" => "b", "ubyte" => "UB",
+  "short" => "s", "ushort" => "US",
+  "int"   => "",  "uint"   => "U",
+  "int64" => "LL", "uint64" => "ULL",
+  "float" => "f", "double" => "",
+}
+
+def cdl_escape(s)
+  s.to_s.gsub(/[\\"\n\r\t]/, "\\" => '\\\\', '"' => '\\"',
+                              "\n" => '\\n', "\r" => '\\r', "\t" => '\\t')
+end
+
+def cdl_value(type, value)
+  return %("#{cdl_escape(value)}") if type == "char"
+  arr = Array(value)
+  if type == "string"
+    return arr.map { |s| %("#{cdl_escape(s)}") }.join(", ")
+  end
+  suffix = TYPE_SUFFIX[type] || ""
+  arr.map { |v|
+    if v.is_a?(Float)
+      type == "float" ? "#{v}f" : v.to_s
+    else
+      "#{v}#{suffix}"
+    end
+  }.join(", ")
+end
+
+def emit_cdl(io, group, name, indent = 0)
+  pre  = "  " * indent
+  head = indent.zero? ? "netcdf #{name} {" : "group: #{name} {"
+  io.puts "#{pre}#{head}"
+
+  unless group["types"].empty?
+    io.puts "#{pre}types:"
+    group["types"].each { |t|
+      case t["kind"]
+      when "enum"
+        members = t["members"].map { |m| "#{m["name"]} = #{m["value"]}" }.join(", ")
+        io.puts "#{pre}  #{t["base"]} enum #{t["name"]} {#{members}} ;"
+      when "opaque"
+        io.puts "#{pre}  opaque(#{t["size"]}) #{t["name"]} ;"
+      when "vlen"
+        io.puts "#{pre}  #{t["base"]}(*) #{t["name"]} ;"
+      when "compound"
+        io.puts "#{pre}  compound #{t["name"]} { /* fields not exposed */ } ;"
+      end
+    }
+  end
+
+  unless group["dimensions"].empty?
+    io.puts "#{pre}dimensions:"
+    group["dimensions"].each { |d|
+      if d["unlimited"]
+        io.puts "#{pre}  #{d["name"]} = UNLIMITED ; // (#{d["length"]} currently)"
+      else
+        io.puts "#{pre}  #{d["name"]} = #{d["length"]} ;"
+      end
+    }
+  end
+
+  unless group["variables"].empty?
+    io.puts "#{pre}variables:"
+    group["variables"].each { |v|
+      dims = v["dimensions"].empty? ? "" : "(#{v["dimensions"].join(", ")})"
+      io.puts "#{pre}  #{v["type"]} #{v["name"]}#{dims} ;"
+      v["attributes"].each { |a|
+        io.puts "#{pre}    #{v["name"]}:#{a["name"]} = #{cdl_value(a["type"], a["value"])} ;"
+      }
+    }
+  end
+
+  unless group["attributes"].empty?
+    io.puts
+    label = indent.zero? ? "global attributes" : "group attributes"
+    io.puts "#{pre}// #{label}:"
+    group["attributes"].each { |a|
+      io.puts "#{pre}    :#{a["name"]} = #{cdl_value(a["type"], a["value"])} ;"
+    }
+  end
+
+  group["groups"].each { |g|
+    io.puts
+    emit_cdl(io, g, g["name"], indent + 1)
+  }
+
+  io.puts indent.zero? ? "#{pre}}" : "#{pre}} // group #{name}"
+end
+
+# ---- Main ----
+
+format = "cdl"
+OptionParser.new { |o|
+  o.banner = "usage: ncheader [-f cdl|json|yaml] FILE.nc"
+  o.on("-f FMT", "--format FMT", %w[cdl json yaml],
+       "output format (default: cdl)") { |v| format = v }
+}.parse!
+
+path = ARGV[0] or abort "usage: ncheader [-f cdl|json|yaml] FILE.nc"
+
+ncid = NetCDF.nc_open(path, NetCDF::NC_NOWRITE)
+begin
+  tree = inspect_group(ncid).merge(
+    "name"   => File.basename(path, ".nc"),
+    "format" => NetCDF.nc_inq_format(ncid),
+  )
+ensure
+  NetCDF.nc_close(ncid)
+end
+
+case format
+when "cdl"  then emit_cdl($stdout, tree, tree["name"])
+when "json" then puts JSON.pretty_generate(tree)
+when "yaml" then puts YAML.dump(tree)
+end

data/bin/ncvar

@@ -0,0 +1,160 @@
+#!/usr/bin/env ruby
+# ncvar — dump a single variable's data from a NetCDF file.
+#
+# Default output is a raw flat byte stream on $stdout, in the variable's
+# native nc_type and the host's native byte order.  Pipe it into
+# tools that read binary directly (od, hexdump, numpy.fromfile, ...).
+#
+#   $ ncvar FILE.nc temperature                       # raw binary
+#   $ ncvar -f text FILE.nc temperature               # one value per line
+#   $ ncvar -f json FILE.nc temperature               # {shape, type, data}
+#
+# Hyperslab (zero-based, like libnetcdf):
+#
+#   $ ncvar -s 0,0 -c 10,20 FILE.nc temperature       # 10x20 corner
+#   $ ncvar -s 0,0 -c 10,20 -S 1,2 FILE.nc temperature
+#
+# Groups: variable name may be a slash-path, e.g. "/observation/temp".
+
+require "carray-netcdf"
+require "json"
+require "optparse"
+
+TYPE_NAMES = {
+  NetCDF::NC_BYTE   => "byte",
+  NetCDF::NC_UBYTE  => "ubyte",
+  NetCDF::NC_CHAR   => "char",
+  NetCDF::NC_SHORT  => "short",
+  NetCDF::NC_USHORT => "ushort",
+  NetCDF::NC_INT    => "int",
+  NetCDF::NC_UINT   => "uint",
+  NetCDF::NC_INT64  => "int64",
+  NetCDF::NC_UINT64 => "uint64",
+  NetCDF::NC_FLOAT  => "float",
+  NetCDF::NC_DOUBLE => "double",
+  NetCDF::NC_STRING => "string",
+}
+
+def parse_int_list(s)
+  return nil if s.nil?
+  s.split(",").map { |x| Integer(x) }
+end
+
+# Resolve "/grp/sub/varname" (or bare "varname") to [grpid, varid].
+def resolve_var(ncid, spec)
+  if spec.include?("/")
+    grp_path, _, name = spec.rpartition("/")
+    grp_path = "/" if grp_path.empty?
+    gid = NetCDF.nc_inq_grp_full_ncid(ncid, grp_path)
+    raise "group not found: #{grp_path}" if gid.nil?
+  else
+    gid  = ncid
+    name = spec
+  end
+  vid = NetCDF.nc_inq_varid(gid, name)
+  raise "variable not found: #{spec}" if vid.nil?
+  [gid, vid]
+end
+
+format = "bin"
+start_arg = count_arg = stride_arg = nil
+OptionParser.new { |o|
+  o.banner = "usage: ncvar [options] FILE.nc VAR"
+  o.on("-f FMT", "--format FMT", %w[bin text json],
+       "output format: bin (default), text, json") { |v| format = v }
+  o.on("-s LIST", "--start LIST",  "comma-separated start indices")  { |v| start_arg  = v }
+  o.on("-c LIST", "--count LIST",  "comma-separated counts")          { |v| count_arg  = v }
+  o.on("-S LIST", "--stride LIST", "comma-separated strides")         { |v| stride_arg = v }
+}.parse!
+
+path, varspec = ARGV
+abort "usage: ncvar [options] FILE.nc VAR" unless path && varspec
+
+ncid = NetCDF.nc_open(path, NetCDF::NC_NOWRITE)
+begin
+  gid, vid = resolve_var(ncid, varspec)
+  _, xtype, _, dimids, _ = NetCDF.nc_inq_var(gid, vid)
+  shape_full = dimids.map { |d| NetCDF.nc_inq_dimlen(gid, d) }
+
+  start  = parse_int_list(start_arg)  || [0] * shape_full.size
+  count  = parse_int_list(count_arg)  || shape_full.zip(start).map { |full, s| full - s }
+  stride = parse_int_list(stride_arg)
+
+  abort "start/count/stride rank mismatch (var has #{shape_full.size} dims)" \
+    unless start.size == shape_full.size &&
+           count.size == shape_full.size &&
+           (stride.nil? || stride.size == shape_full.size)
+
+  shape = count.dup
+
+  # An NC_STRING read returns a nested Array<String> and takes no buffer.
+  # Anything else comes back as a CArray: layer 1 types it from the
+  # variable (an enum by its base type, NC_CHAR as bytes).  Opaque has no
+  # CArray type, so it is read into bytes, opaque_size to an element.
+  nc = xtype == NetCDF::NC_STRING ? NetCDF : CA::NetCDF
+  opaque = xtype >= NetCDF::NC_FIRSTUSERTYPEID &&
+           NetCDF.nc_inq_user_type(gid, xtype)[4] == NetCDF::NC_OPAQUE
+  buf = opaque ? [CArray.uint8(*(count.empty? ? [1] : count), NetCDF.nc_inq_type(gid, xtype)[1])] : []
+  data =
+    if stride
+      nc.nc_get_vars(gid, vid, start, count, stride, *buf)
+    elsif start.all?(&:zero?) && count == shape_full
+      nc.nc_get_var(gid, vid, *buf)
+    else
+      nc.nc_get_vara(gid, vid, start, count, *buf)
+    end
+
+  if xtype == NetCDF::NC_STRING
+    # data is an Array (possibly nested per ndim) of Ruby Strings.
+    flat = data.is_a?(Array) ? data.flatten : [data]
+    case format
+    when "bin"
+      $stdout.binmode
+      $stdout.write(flat.join("\0"))
+    when "text"
+      flat.each { |s| puts s }
+    when "json"
+      puts JSON.pretty_generate({
+        "name"  => varspec,
+        "type"  => "string",
+        "shape" => shape,
+        "start" => start,
+        "data"  => data,
+      })
+    end
+  else
+    # data is a CArray; its bytes are the native-endian stream.
+    bytes = data.dump_binary
+    case format
+    when "bin"
+      $stdout.binmode
+      $stdout.write(bytes)
+    when "text"
+      if xtype == NetCDF::NC_CHAR
+        $stdout.write(bytes)
+        puts unless bytes.end_with?("\n")
+      else
+        abort "type #{xtype} not supported for text output" if opaque
+        data.to_a.flatten.each { |v| puts v }
+      end
+    when "json"
+      payload =
+        if xtype == NetCDF::NC_CHAR
+          bytes
+        else
+          abort "type #{xtype} not supported for json output" if opaque
+          data.to_a.flatten
+        end
+      out = {
+        "name"  => varspec,
+        "type"  => TYPE_NAMES[xtype] || NetCDF.nc_inq_type(gid, xtype).first,
+        "shape" => shape,
+        "start" => start,
+        "data"  => payload,
+      }
+      puts JSON.pretty_generate(out)
+    end
+  end
+ensure
+  NetCDF.nc_close(ncid)
+end