# module NumRu::GPhys::IO

A module to handle file IO regarding GPhys.

Many of the functionality of this module is implemented in the modules for specific file types such as NumRu::GPhys::NetCDF_IO, to which this module directs operations.

For example, GPhys::IO.open(file, name) simply calls GPhys::*_IO.open(file, name), where '*' is NetCDF, GrADS, or grib.

## Module functions

#### `open(files, varname)`

#### `write(file, gphys, name=nil)`

#### `write_grid(file, grid_or_gphys)`

#### `each_along_dims_write(gphyses, files, *loopdims){...} # a block is expected`

#### `var_names(file)`

#### `var_names_except_coordinates(file)`

  See the manual of NumRu::GPhys::NetCDF_IO for the methods listed above.

#### `file2type(file)`

  Figures out the file type supported in this module.

  ARGUMENTS

  - file (String, Regexp, NetCDF, Grib, or GrADS_Gridded) : What to return is of course obvious if it is NetCDF, Grib, or GrADS_Gridded. If it is a String, it is assumed to be a path of a file, and the file type is determined by its suffix when 'nc', 'ctl', or 'grib'; In other cases, the type is figured out by reading in a few bytes from the beginning. If Regexp, currently, a NetCDF is assumed, since only NetCDF_IO.open supports Regexp.

  RETURN VALUE

  - GPhys::IO::NETCDF, GPhys::IO::GRIB, or GPhys::IO::GRADS, which are string constants.

#### `file2specific_module(file)`

  Same as file2type, but returns GPhys::NetCDF_IO, GPhys::GrADS_IO, or GPhys::Grib_IO.

#### `file2file_class(file)`

  Same as file2type, but returns NetCDF, GrADS_Gridded, or Grib.

#### `parse_gturl(gturl)`

  Parses GTOOL4-type URLs to specify path, variable name, and optionally subsets, whose format is path@varname[,dimname=pos1[:pos2[:thinning_intv]][,dimname=...]]

  ARGUMENTS

  - gturl (String) GTOOL4 URL, whose format is path@varname[,dimname=pos1[:pos2[:thinning_intv]][,dimname=...]]

  RETURN VALUES

  - An Array consisting of [file, var, slice, cut_slice, thinning], where
    - file (String) : path
    - var (String) : variable name
    - slice (Array) : subset specifier by the grid numbers to be used as GPhys#[slice].
    - cut_slice (Array) : subset specifier in physical coordinate to be used as GPhys#cut[cut_slice].
    - thinning (Array) : additional subset specifier for thinning with uniform intervals if needed to be used GPhys#[thinning] after appling GPhys#cut.

#### `open_gturl(gturl)`

  a GPhys constructor from a Gtool4-type URL. See parse_gturl for its format.

  RETURN VALUE

  - a GPhys

#### `str2gphys(str)`

  Open a GPhys from a slash("/")-separated String such as "U.nc/U" and "U.nc".

  - Aimed to help quick jobs with interactive sessions -- This method do not handle a GPhys across multiple files.
  - if the variable path is ommited such as "U.nc", try to find the variable in it -- read the file and if only one variable is found, assume that is the variable specified; otherwise, an exception is raised.
  - URL is accepted, but it's only thru NetCDF assuming OPeNDAP.

  ARGUMENTS

  - a String (file_path[/variable_path]) e.g. "U.nc/U", "U.nc", "http://.../U.nc/U"

  RETURN VALUE

  - a GPhys

## Module constants

#### `GTURLfmt`

  The format of Gtool4URL.