../lib/numru/gdir.rb

# class NumRu::GDir

A class to represent diretories and data files for GPhys.

## Overview

A GDir object represents a directory, or a file (such as a NetCDF file or GrADS control file), for which GPhys objects can be defined for the variables in it. This means that a NetCDF file, for example, is treated a directory, rather than a plain file.

GDir serves a directory tree under a root (top) directory, which can be set as a class variable with GDir.top=. All the absolute path of GDir is actually relative to the root directory, and to access outside the root directory is prohibited. Furthermore, it has a working directory as a class variable, whose initial value is the top directory and can be changed by GDir.cd.

NEW(2005/06): Now GDir can accept DODS URL as a path. Also, the top directory can be set to a DODS URL.

## Class Methods

#### `GDir.top=(top)`

  Sets the root directory. This should be done before making any GDir objects by GDir.new. The default root directory is the root directory of the local file system ('/').

  ARGUMENTS

  - top (String): path of the top directory

  RETURN VALUE

  - absolute path of the top directory (String) (followed by a '/')

#### `GDir.top`

  RETURN VALUE

  - absolute path of the top directory (String) (followed by a '/')

#### `GDir.new(path)`

  Constructor.

  ARGUMENTS

  - path (String): path of the directory to open as a GDir. The path is expressed in terms of the top directory.

  RETURN VALUE

  - a GDir

  ERRORS

  - ArgumentError if path is out of the directory tree (originated at the top directory).

  EXAMPLES

  - If the top directory is "/hoge", you can open "/hoge/ho" directory by any of the following.

        gdir = GDir.new("/ho")
        gdir = GDir.new("./ho")

    If you want to open "/hoge" (the top directly), then

        gdir = GDir.new("/")
        gdir = GDir.new(".")

    To open a NetCDF file or GrADS control file,

        gdir = GDir.new("/ho/data.nc")
        gdir = GDir.new("/ho/data.ctl")

#### `GDir.set_text_pattern(*regexps)`

  Sets regular expressions to match the file name of text files. The default is /\.txt$/ and /^\w*$/.

  ARGUMENTS

  - zero or more Regular expressions (zero means no file will be treated as a NetCDF file).

  RETURN VALUE

  - nil

  ERRORS

  - TypeError if any of the arguments is not a Regexp

#### `GDir.add_text_pattern(regexp [, regexp [, ...]])`

  Similar to GDir.set_text_pattern, but adds regular expressions instead of replacing existing ones.

  RETURN VALUE

  - nil

  ERRORS

  - TypeError if any of the arguments is not a Regexp

#### `GDir.cd(path)`

  Changes the working directory of the class.

  RETURN VALUE

  - a GDir

#### `GDir.cwd=(path)`

  Aliased to GDir.cd.

#### `GDir.cwd`

  Returns the current working directory as a GDir. The initial value of the working directory is the top directory.

  RETURN VALUE

  - a GDir

#### `GDir.cd(path)`

  Changes the working directory to path

  RETURN VALUE

  - a GDir (current working directory changed by path)

#### `GDir[]`

#### `GDir.data`

#### `GDir.text`

#### `GDir.list_dirs`

#### `GDir.list_dirs_v`

#### `GDir.list_data`

#### `GDir.list_data_v`

#### `GDir.list_texts`

#### `GDir.list_texts_v`

#### `GDir.ls`

#### `GDir.ls_v`

  All of these are dispatched to the current working directory. Thus, GDir.show is equivalent to GDir.cwd.show, for example.

## Instance Methods

#### `close`

  Closes the file/directory objects in the GDir.

#### `path`

  Returns the path (relative to the top directory)

  RETURN VALUE

  - a String

#### `name`

  Name of the GDir

  RETURN VALUE

  - a String

#### `inspect`

  Returns the path

  RETURN VALUE

  - a String

#### `[path]`

  Returns a GDir, GPhys, or File (text), by calling dir, data, or text depending on path.

  ARGUMENTS

  - path (String): Either relative or absolute.

  RETURN VALUE

  - a GDir, GPhys, or File (text assumed)

  ERROR

  - an exception is raised if path is not appropriate.

#### `dir(path)`

  Returns a GDir specified the path.

  ARGUMENTS

  - path (String): Either relative or absolute.

  RETURN VALUE

  - a GDir

  ERROR

  - an exception is raised if path is invalid as a GDir.

#### `data(path)`

  Returns a GPhys specified the path.

  ARGUMENTS

  - path (String): Either relative or absolute.

  RETURN VALUE

  - a GPhys

  ERROR

  - an exception is raised if path is invalid as a GPhys.

#### `text(path)`

  Returns a text file object specified the path.

  ARGUMENTS

  - path (String): Either relative or absolute.

  RETURN VALUE

  - a File

  ERROR

  - an exception is raised if path is invalid as a text file (based on the pattern: see above).

#### `find_dir( filt )`

  Recursively search a GDir whose name match filt..

  ARGUMENTS

  - filt (Regexp or String) If String, converted to Regexp with Regexp.new(filt).

  RETURN VALUE

  - an Array holding pathes (String) that matched.

#### `find_data( name=nil,long_name=nil,units=nil )`

  Recursively search data variables under the directory. Mathces are by taking "AND" for non-nil arguments. (At least one of the three arguments must be non-nil.)

  ARGUMENTS

  - name (Regexp or String or nil) Variable name. If String, converted to Regexp with Regexp.new(name).
  - long_name (Regexp or String or nil) long_name. If String, converted to Regexp with Regexp.new(long_name).
  - long_name (Units or String or nil) long_name. If String, converted to Units with Units.new(units).

  RETURN VALUE

  - an Array holding the path and variable name that matched (two-element Array of String; [path, variable_name] ).

#### `list_dirs(path=nil)`

  Returns the names of the directories.

  See also ls.

  ARGUMENTS

  - path (nil or String): if nil, the method is applied to the current directory. If specified, listing is made for the directory designated by it. Either relative or absolute.

  RETURN VALUE

  - an Array of String

#### `list_dirs_v(path=nil)`

  Verbose version of list_dirs, showing size and mtime like 'ls -l'.

  See also ls_l.

  ARGUMENTS

  - See list_dirs.

  RETURN VALUE

  - an Array of String

    Example of a string:

        275492  Apr 12 19:15 hogehoge_data.nc/

#### `list_data(path=nil)`

  Returns the names of the data (variables on which GPhys objects can be defined.) Returns a non-empty array if the GDir (current or at the path) is actually a file recognized by GPhys (i.e., NetCDF or GrADS control file).

  ARGUMENTS

  - path (nil or String): if nil, the method is applied to the current directory. If specified, listing is made for the directory designated by it. Either relative or absolute.

  RETURN VALUE

  - an Array of String

#### `list_data_v(path=nil)`

  Verbose version of list_data, showing shape, long_name, and units.

  See also ls_l.

  ARGUMENTS

  - See list_data.

  RETURN VALUE

  - an Array of String

    Example of a string:

        u     [lon=120,lat=120,z=40,t=73]     'x components of velocity'      (m/s)

#### `list_texts(path=nil)`

  Returns the names of the text files. Whether a file is a text file or not is judged based on the name of the file: That matched the predefined patters is judged as a text file regardless whether it is really so. The default pattern is /\.txt$/ and /^\w*$/. The patterns can be customized by set_text_patterns or add_text_patterns.

  ARGUMENTS

  - path (nil or String): if nil, the method is applied to the current directory. If specified, listing is made for the directory designated by it. Either relative or absolute.

  RETURN VALUE

  - an Array of String

#### `list_texts_v(path=nil)`

  Verbose version of list_texts, showing size and mtime like 'ls -l'.

  See also ls_l.

  ARGUMENTS

  - See list_texts.

  RETURN VALUE

  - an Array of String

#### `ls(path=nil)`

  Prints the results of list_dirs, list_data, and list_texts on the standard output.

  RETURN VALUE

  - nil

#### `each_dir`

  Iterator for each directory (GDir) under self.

#### `each_data`

  Iterator for each GPhys under self.

#### `ls_l(path=nil)`

  Verbose version of ls. Prints the results of list_dirs_v, list_data_v, and list_texts_v on the standard output.

  RETURN VALUE

  - nil

#### `mtime`

  Returns the last modified time.

  RETURN VALUE

  - a Time

#### `atime`

  Returns the last accessed time.

  RETURN VALUE

  - a Time

#### `ctime`

  Returns ctime.

  RETURN VALUE

  - a Time

#### `mtime_like_ls_l`

  Returns the last modified time formated as in ls -l. That is, if the time of last modification is greater than six months ago, it is shown in the format 'month date year'; otherwise, 'month date time'.

  RETURN VALUE

  - a String.