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:
%      ncexample() creates, populates, and reads a NetCDF file.
%      tnetcdf() exercizes the NetCDF Toolbox extensively.
%
%   WWW: <http://crusty.er.usgs.gov/~cdenham/MexCDF/nc4ml5.html>.
%
% <<<<<<<<<<<<<<<<< End of NetCDF Language Synopsis >>>>>>>>>>>>>>>>>
 
% Copyright (C) 1996-7 Dr. Charles R. Denham, ZYDECO.
%  All Rights Reserved.
%   Disclosure without explicit written consent from the
%    copyright owner does not constitute publication.

% Updated    18-Aug-1997 09:39:52.
% Updated    20-May-1999 09:33:04.
% Updated    24-Aug-1999 09:12:11.
% Updated    10-Apr-2000 21:07:48.

ncwhatsnew

if nargin == 1 & nargout < 1 & isequal(theFilename, 'version')
	version(ncitem)
	return
end

if nargin < 1 & nargout < 1
   help(mfilename)
   ncversion
   disp(' ')
   return
end

if nargout > 0, self = []; end

% Open with dialog as 'nowrite'.

if nargout > 0 & nargin < 1
   result = netcdf('nowrite');
   if ~isempty(result)
      ncregister(result)
      result = ncregister(result);
   end
   self = result;
   return
end

if nargin < 2, thePermission = ''; end

result = [];

% Randomly named file.

if nargin == 1 & strcmp(theFilename, 'random')
   result = [];
   count = 0;
   while isempty(result) & count < 32
		thePWD = pwd;
		if thePWD(length(thePWD)) ~= filesep
			thePWD = [thePWD filesep];
		end
      theFilename = [thePWD 'temp' int2str(rand(1, 1) .* 10000) '.nc'];
      result = netcdf(theFilename, 'noclobber');
   end
   if ~isempty(result)
      ncregister(result)
      result = ncregister(result);
   end
   if nargout > 0
      self = result;
   else
      ncans(result)
   end
   return
end

if nargin == 1
   switch class(theFilename)
   case 'double'
      theNCid = theFilename;
      theStruct.itsPermission = 'unknown';
      theStruct.itsDefineMode = 'unknown';
      theStruct.itsFillMode = 'unknown';
      theStruct.itsMaxNameLen = 0;
      result = class(theStruct, 'netcdf', ncitem('', theNCid));
      result = ncregister(result);
      if nargout > 0
         self = result;
      else
         ncans(result)
      end
      return
   case 'char'
      thePermission = '';
      thePerm = ncpermission(theFilename);
      switch thePerm
      case {'nowrite', 'write', 'noclobber', 'clobber', ...
            'readonly', 'define'}
         thePermission = thePerm;
         theFilename = '*';
      otherwise
         thePermission = 'nowrite';
      end
   otherwise
      return
   end
end

if isempty(thePermission), thePermission = 'nowrite'; end

if any(theFilename == '*')
   switch thePermission
   case {'noclobber', 'clobber'}
		theSuggested = theFilename;
		if isequal(theFilename, '*')
			theSuggested = 'unnamed.nc';
		else
			theSuggested(theSuggested == '*') = '';
		end
      [theFile, thePath] = uiputfile(theSuggested, 'Save NetCDF As');
      if ~any(theFile), return, end
   case {'nowrite', 'write', 'readonly', 'define'}
      [theFile, thePath] = uigetfile(theFilename, 'Select NetCDF File');
      if ~any(theFile), return, end
   otherwise
      return
   end
   theFilename = [thePath theFile];
   result = netcdf(theFilename, thePermission);
   if ~isempty(result)
      ncregister(result)
      result = ncregister(result);
   end
   if nargout > 0
      self = result;
   else
      ncans(result)
   end
   return
end

thePermission = ncpermission(thePermission);

switch thePermission
case 'define'
   result = netcdf(theFilename, 'write');
   if ~isempty(result), redef(result), end
   if nargout > 0
      self = result;
   else
      ncans(result)
   end
   return
otherwise
end

theDefineMode = '';
theFillMode = 'fill';   % The NetCDF default.
theMaxNameLen = 0;

theStruct.itsPermission = thePermission;
theStruct.itsDefineMode = theDefineMode;
theStruct.itsFillMode = theFillMode;
theStruct.itsMaxNameLen = theMaxNameLen;

result = class(theStruct, 'netcdf', ncitem(theFilename));

switch thePermission
case {'clobber', 'noclobber'}
   result = create(result, thePermission);
   if ncid(result) >= 0, theDefineMode = 'define'; end
case {'write', 'nowrite'}
   result = open(result, thePermission);
   if ncid(result) >= 0
      theDefineMode = 'data';
     elseif exist(name(result)) ~= 2
      result = open(result, 'clobber');
      if ncid(result) >= 0, theDefineMode = 'define'; end
   end
otherwise
   help netcdf
   warning([' ## No such permission: ' thePermission])
end

if ncid(result) >= 0
   result.itsDefineMode = theDefineMode;
   ncregister(result)
   result = ncregister(result);
  else
   disp([' ## NetCDF file not opened: ' theFilename])
   result = [];
end

if nargout > 0
   self = result;
else
   ncans(result)
end

function theResult = ncpermission(thePermission)

% netcdf/ncpermission -- Resolve permission string.
%  netcdf/ncpermission('thePermission') returns the NetCDF permission
%   string corresponding to 'thePermission', which may be uniquely
%   abbreviated.

thePerm = lower(thePermission);

% Lists of shortened permissions: must pre-allocate.

clobber = [];
noclobber = [];
write = [];
nowrite = [];
readonly = [];
define = [];

perms = {'clobber', 'noclobber', 'write', 'nowrite', 'readonly', 'define'};
for j = 1:length(perms)
   p = perms{j};
   c = cell(1, length(p));
   for i = 1:length(perms{j})
      c{i} = p;
      p(length(p)) = '';
   end
   eval([perms{j} ' = c;']);
end

% Formal name of thePermission.

switch thePerm
case clobber
   thePermission = 'clobber';
case noclobber
   thePermission = 'noclobber';
case write
   thePermission = 'write';
case [nowrite readonly]
   thePermission = 'nowrite';
case [define]
   thePermission = 'define';
otherwise
end

if nargout > 0, theResult = thePermission; end