function [coeffs,connection,msg] = dfiltparse(dfilttype,varargin)
%DFILTPARSE  Generic parser for DFILT objects.
%   [COEFFS,CONNECTION,MSG] = DFILTPARSE(DFILTTYPESTR,...) parses
%   the input for all DFILT constructors, checks for valid
%   coefficients, possibly assigns default coefficients and returns
%   a cell array of coefficients, COEFFS, to be stored in the object.
%   DFILTTYPESTR can be any of DTF, SSD, LATCMA, etc.
%
%   The coefficients can be given as various input vectors or matrices, or
%   as a single cell array.  For example for DTF objects, the syntax is:
%   DFILTPARSE('dtf',B1,A1,B2,A2,...) or DFILTPARSE('dtf',{{B1,A1},{B2,A2},...}).
%   The numerator and denominator of the i-th section are given by the
%   coefficients in vectors Bi and Ai respectively.
%
%   CONNECTION is a string indicating the connection type, 'CAS' (cascaded)
%   or 'PAR' (parallel), of the sections of a DFILT object. To specify
%   a connection, a trailing string must be given to DFILTPARSE as an input
%   e.g. DFILTPARSE('dtf',B1,A1,B2,A2,'par').  If the string is omitted,
%   the default connection is 'CAS'.
%
%   MSG is a string indicating either a parsing error, or that a 
%   'conversion' is being attempted.  A conversion is assumed to be
%   requested when the first optional input argument of DFILTPARSE
%   is a DFILT object of the same type as dfilttype. 

%   Author(s): R. Losada
%   Copyright 1988-2000 The MathWorks, Inc.
%   $Revision: 1.6 $  $Date: 2000/06/13 21:22:44 $ 

% The API for DFILTPARSE is as follows:
% Every DFILT constructor must call dfiltparse (directly or indirectly)
% to parse its input args. There must exist a parser function for
% each object whose name is a string containing the constructor name followed
% by 'parse', e.g. DTFPARSE which DFILTPARSE will call expecting 3 function
% handles as output. These handles must point to 3 functions within DTFPARSE
% that do the following:
% 1. Generate default coefficients if needed.
% 2. Form a cell array of coefficients of the form {{B1,A1},{B2,A2},...} (or equivalent)
% 3. Check for valid coefficients and assign defaults when applicable
%    (e.g. when empties are given).

% Assign default outputs in case of early return
coeffs = [];
connection = 'cas';
msg = '';

% If input is already a DFILT object of the same type as dfilttype,
% a conversion is being requested
if nargin > 1 & nargin <= 3 & isa(varargin{1},dfilttype),
    if nargin == 3,
        varargin{1} = section(varargin{1},varargin{2});
    end
    coeffs = varargin{1};
    msg = 'conversion';
    return
end

% Strip the trailing string if it's there and assign the connection output
if nargin > 2 & ischar(varargin{end}),
    [connection,msg] = parseconnection(varargin{end});
    if ~isempty(msg),
        return
    end
    % Separate the coefficients
    varargin = {varargin{1:end-1}};
end


% Function handles are returned in a length 3 vector
fhndls = feval([dfilttype,'parse']);

% If no coefficients are given, create a default filter
if nargin == 1,
    coeffs = feval(fhndls(1));
end

% If coefficients are not already in a cell, create one
if nargin > 1,
    if ~iscell(varargin{1}),
        % Form cell of coefficients
        [coeffs,msg] = feval(fhndls(2),varargin{:});
        if ~isempty(msg),
            return
        end
    else
        coeffs = varargin{1};
    end
end

% If coefficients are specified, verify that they are valid
if nargin > 1,
    % Check for valid coefficients and replace empties if necessary
    for n = 1:length(coeffs),
        [coeffs{n},msg] = feval(fhndls(3),coeffs{n});
        if ~isempty(msg),
            return
        end
    end
end

%-------------------------------------------------------------------------
function [connection,msg] = parseconnection(connection)
%TESTCONNECTIONSTR  Test if string given is a valid connection.

msg = '';
connectionopts = {'cascaded','parallel'};
indx = strmatch(lower(connection),connectionopts);

if isempty(indx),
    msg = 'Connections must be ''cas''caded or ''par''allel.';
    return
end    

switch indx,
case 1,
    connection = 'cas';
case 2,
    connection = 'par';
end

% [EOF] - DFILTPARSE.M


