LTFATARGHELPER  Parse arguments for LTFAT
   Usage: [flags,varargout]  = ltfatarghelper(posdepnames,definput,arglist,callfun);

   Input parameters:
      posdepnames : Names of the position dependant parameters.
      definput    : Struct to define the allowed input
      arglist     : Commandline of the calling function (varargin)
      callfun     : Name of calling function (optional)

   Output parameters:
      flags       : Struct with information about flags.
      keyvals     : Struct with key / values.
      varargout   : The position dependant pars. properly initialized

   `[flags,keyvals]=ltfatarghelper(posdepnames,definput,arglist)` assists in
   parsing input parameters for a function in LTFAT. Parameters come in
   four categories:
  
   * Position dependant parameters. These must not be strings. These are
     the first parameters passed to a function, and they are really just a
     short way of specifying key/value pairs. See below.

   * Flags. These are single string appearing after the position dependant
     parameters.

   * Key/value pairs. The key is always a string followed by the value,
     which can be anything.

   * Expansions. These appear as flags, that expand into a pre-defined list
     of parameters.  This is a short-hand way of specifying standard sets of
     flags and key/value pairs.

   The parameters are parsed in order, so parameters appearing later in
   varargin will override previously set values.

   The following example for calling `ltfatarghelper` is taken from |dgt|::
  
     definput.keyvals.L=[];
     definput.flags.phase={'freqinv','timeinv'};
     [flags,kv]=ltfatarghelper({'L'},definput,varargin);

   The first line defines a key/value pair with the key `'L'` having an
   initial value of `[]` (the empty matrix).

   The second line defines a group of flags by the name of `phase`.  The
   group `phase` contains the flags `'freqinv'` and `'timeinv'`, which can
   both be specified on the command line by the user. The group-name
   `phase` is just for internal use, and does not appear to the user. The
   flag mentioned first in the list will be selected by default, and only
   one flag in a group can be selected at any time. A group can contain as
   many flags as desired.
  
   The third line is the actual call to `ltfatarghelper` which defines the
   output `flags` and `kv`.  The input `{'L'}` indicates that the value of
   the parameter `'L'` can also be given as the very first value in
   varargin.

   The output struct `kv` contains the key/value pairs, so the value
   associated to `'L'` is stored in `kv.L`.

   The output struct `flags` contains information about the flags choosen
   by the user. The value of `flags.phase` will be set to the selected flag
   in the group `phase` and additionally, the value of `flags.do_timeinv`
   will be 1 if `'timeinv'` was selected and 0 otherwise, and similarly for
   `'freqinv'`. This allows for easy checking of selected flags.

   Advanced usage
   --------------
   
   Expansion `import` was introduced in order to allow sharing common
   flags and key/value pairs between functions. 
   
   The following example is taken from |plotdgt| and |tfplot|::

       definput.import={'ltfattranslate','tfplot'};
       [flags,kv,fs]=ltfatarghelper({'fs','dynrange'},definput,varargin);

   This code instructs `ltfatarghelper` to run functions 
   `arg_ltfattranslate` and `arg_tfplot` which define the flags and 
   the key/value pairs. The `arg_` functions must have the following signature::

       function definput=arg_name(definput)

   Moreover, a special flag `'argimport'` is used to pass the flags 
   and the key/value pairs from |plotdgt| to |tfplot|::

       coef=tfplot(...,'argimport',flags,kv);
   
   See also: ltfatgetdefaults, ltfatsetdefaults

Package: ltfat