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.