--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/m-toolbox/classes/@plist/append.m	Wed Nov 23 19:22:13 2011 +0100
@@ -0,0 +1,196 @@
+% APPEND append a param-object, plist-object or a key/value pair to the parameter list.
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% DESCRIPTION: APPEND append a param-object, plist-object or a key/value pair to
+%              the parameter list.
+%
+% CALL:        pl = append(pl, param-object);
+%              pl = append(pl, plist-object);
+%              pl = append(pl, 'key1', 'value1');
+%
+%              pl = append(pl, combination of the examples above)
+%
+% REMARK:      It is not possible to append an key/value pair if the key exist
+%              in the parameter list. Tn this case an error is thrown.
+%
+% <a href="matlab:utils.helper.displayMethodInfo('plist', 'append')">Parameters Description</a>
+%
+% VERSION:     $Id: append.m,v 1.31 2011/04/08 08:56:21 hewitson Exp $
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+function varargout = append(varargin)
+
+  import utils.const.*
+
+  %===  short cuts for simple calls
+  
+  % pl.append(p)
+  if nargout == 0 && nargin == 2 && isa(varargin{2}, 'param') && numel(varargin{2})==1
+    pl = varargin{1};
+    p  = varargin{2};
+    if ~isempty(pl.params) && any(strcmpi(p.key, {pl.params.key}))
+      error('\n### The key [%s] exist in the parameter list.\n### Please use the function pset.',p.key);
+    end
+    pl.params = [pl.params p];
+    return
+  end  
+  
+  % pl.append('key', value)
+  if nargout == 0 && nargin == 3
+    pl = varargin{1};
+    key = varargin{2};
+    if ~isempty(pl.params) && any(strcmpi(key, {pl.params.key}))
+      error('\n### The key [%s] exist in the parameter list.\n### Please use the function pset.',key);
+    end
+    pl.params = [pl.params param(key, varargin{3})];
+    return
+  end
+  
+  %%% Check if this is a call for parameters
+  if utils.helper.isinfocall(varargin{:})
+    varargout{1} = getInfo(varargin{3});
+    return
+  end
+      
+
+  [objs, invars, rest] = utils.helper.collect_objects(varargin(:), 'plist');
+  [pps,  invars, rest] = utils.helper.collect_objects(rest(:), 'param');
+
+  %%% Decide on a deep copy or a modify
+  pls = copy(objs, nargout);
+
+  %%% REMARK: If the rest is an single string and the number of plist is two
+  %%%         then we assume that the rest and the second plist are a key/value
+  %%%         pair.
+  if numel(rest) == 1 && ischar(rest{1}) && numel(objs) == 2
+    rest{2} = objs(2);
+    pls(2) = [];
+  end
+
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %%%%%%%%%%             First Case: Append plist-objects              %%%%%%%%%%
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+  pl = pls(1);
+
+  %%% If we found more than one plist then append the parameters
+  %%% of the second, third, ... plist to the first plist
+  if numel (pls) > 1
+    for kk = 2:numel(pls)
+      for jj = 1:length(pls(kk).params)
+        add_param(pl, pls(kk).params(jj));
+      end
+    end
+  end
+
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %%%%%%%%%%             Second Case: Append param-objects             %%%%%%%%%%
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+  if ~isempty(pps)
+    for kk = 1:numel(pps)
+      add_param(pl, pps(kk));
+    end
+  end
+
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  %%%%%%%%%%             Third Case: Append key/value pairs            %%%%%%%%%%
+  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+  if ~isempty(rest)
+    if mod(numel(rest),2)
+      error('### Please define a ''key'' AND a ''value''%s### to append this pair.', char(10));
+    end
+    while ~isempty(rest)
+      if iscell(rest{1})
+        key = rest{1}{1};
+        desc = rest{1}{2};
+      else
+        desc = '';
+        key = rest{1};
+      end
+      val = rest{2};
+
+      %%% Remove the first two objects from the 'rest' variable
+      rest(1) = [];
+      rest(1) = [];
+      
+      % does the key exist?
+      if isempty(pl.params)
+        idx = [];
+      else
+        idx = find(strcmpi(key, {pl.params.key}));
+      end
+      
+      if isempty(idx)
+        % add a new param
+        if isempty(desc)
+          pl.params = [pl.params param(key,val)];
+        else
+          if ~ischar(desc)
+            error('### The description for a parameter must be a string but it is from the class [%s]', class(desc));
+          else
+            pl.params = [pl.params param({key, desc},val)];
+          end
+        end
+      else
+        error('\n### The key [%s] exist in the parameter list.\n### Please use the function pset.',key);
+      end
+            
+    end
+  end
+
+  varargout{1} = pl;
+end
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%                               Local Functions                               %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% DESCRIPTION: The input parameter will only be added if the key doesn't exist
+%              in the plist. Throw an error if the key exist in the plist.
+function add_param(pl, pp)
+  
+  if ~isempty(pl.params) && any(strcmpi({pl.params.key}, pp.key))
+    error('\n### The key [%s] exist in the parameter list.\n### Please use the function pset.', pp.key);
+    return  
+  end
+  pl.params = [pl.params pp];
+end
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% FUNCTION:    getInfo
+%
+% DESCRIPTION: Get Info Object
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+function ii = getInfo(varargin)
+  if nargin == 1 && strcmpi(varargin{1}, 'None')
+    sets = {};
+    pl   = [];
+  else
+    sets = {'Default'};
+    pl   = getDefaultPlist;
+  end
+  % Build info object
+  ii = minfo(mfilename, 'plist', 'ltpda', utils.const.categories.helper, '$Id: append.m,v 1.31 2011/04/08 08:56:21 hewitson Exp $', sets, pl);
+  ii.setArgsmin(1);
+end
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% FUNCTION:    getDefaultPlist
+%
+% DESCRIPTION: Get Default Plist
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+function plo = getDefaultPlist()
+  plo = plist();
+end
+