function self = netcdf(theFilename, thePermission)

% netcdf/netcdf -- Constructor for netcdf class.
%
%  netcdf (no arguments) shows extensive "help".
%  netcdf('version') shows the present version number.
%
%  netcdf('theFilename', 'thePermission') creates and/or
%   opens 'theFilename' if 'thePermission' is one of
%   {'clobber', 'noclobber', 'write', 'nowrite'} or a
%   unique abbreviation thereof.  The "netcdf" object
%   is assigned silently to "ans" if no output argument
%   is provided.
%
%  netcdf('thePermission') invokes Matlab's "uiputfile"
%   or "uigetfile" dialog for selecting the file to create
%   or open, respectively, depending on 'thePermission'
%   (default = 'nowrite' if possible, then 'noclobber').
%
%  netcdf('random') creates a NetCDF file with a unique,
%   random name, suitable for use as a temporary file.
%
%  self = netcdf (no argument) calls "netcdf('nowrite')",
%   which invokes matlab's "uigetfile" dialog.  The returned
%   "self" is the "netcdf" object that was opened.
%
%  netcdf(theNCid) returns a "netcdf" object corresponding
%   to theNCid of an open NetCDF file.  This function does
%   not re-open the file.  TheNCid is the formal identification
%   number that would be returned ordinarily by a call to the
%   NetCDF "nccreate" or "ncopen" function.
%
%  Other permissions: The word 'readonly' is a synonym for 'nowrite'.
%   The word 'define' can be used to open an existing file in 'define'
%   mode, although this is not strictly necessary, since the "NetCDF
%   Toolbox" switches context automatically, as needed.
%
% <<<<<<<<<< Language Synopsis of the NetCDF Toolbox >>>>>>>>>>
%
%   [...] denotes default value.
%
%   Create or open a NetCDF file:
%      f = netcdf('myNetCDF.nc', 'clobber | noclobber')
%      f = netcdf('myNetCDF.nc', 'write | [nowrite]')
%         where f is the returned "netcdf" object.
%      f = netcdf('clobber | noclobber') for "uiputfile" dialog.
%      f = netcdf('write | [nowrite]') for "uigetfile" dialog.
%      f = netcdf('random') to create a randomly named file.
%
%   Define a NetCDF global attribute:
%      f.myGlobalAttribute = [myGlobalAttributeDoubleData]
%      f.myGlobalAttribute = 'myGlobalAttributeCharData'
%      f.myGlobalAttribute = nctype(myGlobalAttributeData)
%         where nctype = [ncdouble] | ncfloat | nclong | ...
%                         ncint | ncshort | ncbyte | [ncchar]
%         (N.B. default depends on context.)
%         (See "NetCDF User's Guide" for datatype definitions.)
%         
%      f.myGlobalAttribute = [] deletes the attribute.
%      g = f.myGlobalAttribute is the object.
%      g(:) = [] deletes the attribute.
%
%   Define a NetCDF record-dimension:
%      f('myRecordDimension') = 0 defines a record-dimension.
%      f('myRecordDimension') = [] deletes the dimension.
%      r = f('myRecordDimension') is the object.
%      r(:) = [] deletes the dimension.
%      r(:) = newSize resizes the dimension.
%
%   Define a NetCDF dimension:
%      f('myDimension') = myDimensionLength
%      f('myDimension') = [] deletes the dimension.
%      d = f('myDimension') is the object.
%      d(:) = [] deletes the dimension.
%      d(:) = newSize resizes the dimension.
%      isrecdim(d) determines whether d is the record-dimension.
%      iscoord(v) determines whether d is a coordinate-dimension.
%
%   Define a NetCDF variable:
%      f{'myVariable'} = nctype(myRecordDimension, myDimension, ...)
%      f{'myVariable'} = nctype(myDimension, ...)
%      f{'myVariable'} = nctype(r, d, ...)
%      f{'myVariable'} = nctype(d, ...)
%      f('myVariable') = [] deletes the variable.
%      v = f{'myVariable'} returns the object.
%      v = f{'myVariable', 1} returns the object -- auto-scaling enabled.
%      v(:) = [] deletes the variable.
%      iscoord(v) determines whether v is a coordinate-variable.
%      isscalar(v) determines whether v is a scalar-variable.
%
%   Define a NetCDF attribute:
%      f{'myVariable'}.myAttribute = [myAttributeDoubleData]
%      f{'myVariable'}.myAttribute = 'myAttributeCharData'
%      f{'myVariable'}.myAttribute = nctype(myAttributeData)
%      f{'myVariable'}.myAttribute = [] deletes the attribute.
%      v.myAttribute = [myAttributeDoubleData]
%      v.myAttribute = 'myAttributeCharData'
%      v.myAttribute = nctype(myAttributeData)
%      v.myAttribute = [] deletes the attribute.
%      a = f{'myVariable'}.myAttribute is the object.
%      a = v.myAttribute is the object.
%      a(:) = [] deletes the attribute.
%
%   Store and retrieve NetCDF variable data:
%      f{'myVariable'}(i, j, ...) = myVariableData
%      f{'myVariable', 1}(i, j, ...) = myVariableData -- auto-scaling enabled.
%      v(i, j, ...) = myVariableData
%      myVariableData = f{'myVariable'}(i, j, ...)
%      myVariableData = f{'myVariable', 1}(i, j, ...) -- auto-scaling enabled.
%      myVariableData = v(i, j, ...)
%
%   Store and retrieve NetCDF attribute data: (always a row vector)
%      f.myGlobalAttribute(i) = myGlobalAttributeData
%      g(i) = myGlobalAttributeData
%      f{'myVariable'}.myAttribute(i) = myAttributeData
%      v.myAttribute(i) = myAttributeData
%      a(i) = myAttributeData
%      myGlobalAttributeData = f.myGlobalAttribute(i)
%      myGlobalAttributeData = g(i)
%      myAttributeData = f{'myVariable'}.myAttribute(i)
%      myAttributeData = v.myAttribute(i)
%      myAttributeData = a(i)
%      EXCEPTION: v.FillValue_ references the "_FillValue" attribute.
%                 Use the "fillval(v, ...)" method to avoid confusion.
%
%   Store and retrieve NetCDF record data:
%      s = f(0) returns the object.
%      t = s(0) returns the record template as a struct.
%      u = r(i) returns the i-th record data as a struct.
%      x = r(i).field(...) returns a subset of a field (variable).
%      s(i) = t sets the i-th record to the struct data.
%
%   Indexing defaults for NetCDF variables and attributes:
%      ":" means 'all', including unstated indices to the right.
%         Otherwise, unstated indices to the right default to 1.
%         Note: ":" does NOT impose columnization on the result.
%
%   Last index:
%      The keyword "end" can serve as the last index for any
%         dimensional direction, as in "v(1:2:end, ...)".
%
%   Duplication of NetCDF objects via "<" operator:
%         (Also see use of "copy" below.)
%      f < myObject copies the complete myObject into NetCDF
%         file f, where myObject represents a dimension,
%         variable, attribute, or another NetCDF file.
%      f < myRecord copies the data of myRecord object into f.
%      v < myVariable copies the data and attributes of myVariable into v.
%      v < myAttribute copies myAttribute into variable v.
%      v < myArray copies myArray into the data of v.
%      a < myAttribute copies the contents of myAttribute into attribute a.
%      a < myArray copies myArray into attribute a.
%
%   Duplication of NetCDF objects via "copy":
%      copy(f, myNetCDF) copies netcdf f into myNetCDF.
%      copy(d, f) copies dimension d into netcdf f.
%      copy(a, f) copies attribute a into netcdf f.
%      copy(a, v) copies attribute a into variable v.
%      copy(v, f, copyData, copyAttributes) copies variable v into
%         netcdf f, as directed by the flags (defaults = 0).
%      copy(v, myVariable, copyData, copyAttributes) copies the
%         contents of variable v into variable myVariable, as
%         directed by the flags (defaults = 0).
%
%   Deletion of objects.
%      delete(myObject1, myObject2, ...) deletes the objects.
%
%   Lists of objects:
%      dim(f) returns the dimension objects of f in a cell-array.
%      var(f) returns the variable objects of f in a cell-array.
%      att(f) returns the global attribute objects of f in a cell-array.
%      dim(v) returns the dimension objects of v in a cell-array.
%      att(v) returns the attribute objects of v in a cell-array.
%      coord(f) returns the coordinate-variable objects of f.
%      recdim(f) returns the record-dimension object of f.
%      recdim(v) returns the record-dimension object of v.
%      recvar(f) returns the record-variable objects of f in a cell-array.
%
%   Basic properties of NetCDF objects:
%      name(x) returns the name of object x.
%      name(x, 'newname') renames object x to 'newname'.
%      ncnames({list_of_objects}) returns the names of the objects.
%      size(x) returns the Matlab-like size of object x.
%      size(x, k) returns the k-th element of the size of object x.
%      ncsize(x) returns the NetCDF-like size of object x.
%      ncsize(x, k) returns the k-th element of the ncsize of object x.
%      length(x) returns the Matlab-like length of object x.
%      datatype(x) returns the datatype of object x.
%      class(x) returns the class of x.
%      ncclass(x) returns the netcdf parent class of derived x.
%      parent(x) returns the parent (netcdf or ncvar) of object x.
%      permission(x) returns the parent file's create/open permission.
%      mode(x) returns the parent file's current "define" mode.
%      fillval(v, ...) manipulates the "_FillValue" attribute.
%      setfill(f, ...) manipulates the "fill-mode" of f.
%      orient(v, ...) manipulates the get/put orientation of v.
%      resize(d, newsize) resizes dimension d to the newsize.
%      resize(v, [newsize]) resizes variable v to the [newsize].
%
%   Unsigned interpretation of integer data:
%      unsigned(v) returns the "unsigned" flag of variable v.
%      unsigned(v, isUnsigned) sets the "unsigned" flag of variable v.
%      unsigned(a) returns the "unsigned" flag of attribute a.
%      unsigned(a, isUnsigned) sets the "unsigned" flag of attribute v.
%
%   Automatic scaling of variable data:
%      autoscale(v, isAutoScaling) sets the "autostate" state of variable v.
%      autoscale(v) returns the current "autoscale" state of variable v.
%
%   Automatic substitution of fill-value by NaN:
%      autonan(v, isAutoNaNing) sets the "autonan" state of variable v.
%      autonan(v) returns the current "autonan" state of variable v.
%
%   Quick-mode for variable input/output:
%      quick(v, isQuick) sets the variable v to "quick" mode.
%      quick(v) returns the current "quick" state of variable v.
%
%   Arithmetic operators with NetCDF objects (right-side only):
%      y = d op x returns d(:) op x for operator op, such as "-".
%      y = v op x returns v(:) op x for operator op, such as "-".
%      y = a op x returns a(:) op x for operator op, such as "-".
%      y = op d returns op d(:) for unary operator op, such as '-'.
%      y = op v returns op v(:) for unary operator op, such as '-'.
%      y = op a returns op a(:) for unary operator op, such as '-'.
%
%   NetCDF Conventions:
%      v.FillValue_ references the "_FillValue" attribute.
%         (Matlab cannot parse a beginning under-score.)
%
%   Save/Load NetCDF Variables (no attributes transfered):
%      ncsave('myNetCDF.nc', ...) updates variables in 'myNetCDF.nc'.
%      ncload('myNetCDF.nc', ...) loads variables from 'myNetCDF.nc'.
%
%   Composite-Variables: (Not for the faint-of-heart!)
%      v = var(v1, s1, d1, v2, s2, d2, ...) returns a composite-
%         variable using NetCDF variables v1, ..., whose s1, ...
%         source-indices map to the d1, ... destination-indices
%         in the composite output array.  See "help ncvar/var".
%
%   Miscellaneous:
%      isepic(v) determines whether v is an EPIC variable.
%      fatnames(f) invokes the "fatnames" facility.
%      ncweb() links to the WWW home-page of the NetCDF Toolbox.
%
%   Example M-Files: