Function [sopt,fb] = optionmanip(sopt,instr,fopt)
[sopt,fb,msg] = optionmanip(sopt,instr,fopt)
[copt,...] = optionmanip(copt,instr,fopt)
returns a renewed option list, as a string sopt, after
applying the instruction instr.
A renewed cell-array copt is returned, if the first
input argument is a row cell-array, in which each option
of the option list is stored as a key-value pair.
The instructions in string instr may have the
following patterns:
-- "-key"
"-key args"
if the option with key "-key" exists already,
substitute its arguments by nothing or "args";
otherwise, append a new option with key "-key" and
possible arguments "args".
-- "-key __delete__"
delete the option with key "-key" and its possible
arguments;
-- "-key __append__"
"-key args __append__"
append a new option with key "-key" and its possible
arguments (if the option already exists, append another
one);
-- "-key ???"
return the argument(s) of the first occuring option
with key "-key" in the output argument fd; and do
not change the option;
-- "###i val"
(where i represents an integer)
if the keyless option i exists already, substitute its
value by "val"; if i equals to one plus the highest
keyless option i, append a new keyless option with
value "val";
-- "###i"
delete the keyless option i;
-- "###i ???"
(where i represents an integer)
return the argument the keyless option i in the output
argument fd; and do not change the option.
If keys with a suffixed argument are specified by fopt,
they are processed as expected, because suffixed values
are split off from their keys. So, e.g. the instruction
"-vth" will replace "-vtv" in the input, if "-vt" has been
listed in fopt as a key with a suffixed argument.
The second input argument instr may also be a cell-array.
In that case, each odd element, instr{iinstr}, contains a
string, which contains the first element (word) of
instruction iinstr; and each even element,
instr{iinstr+1}, contains the remainder of the same
instruction. An even element may be a string, a numerical
or something else; it will not be changed, if copt is
input and output.
Some feedback is given via the optional output argument
fb. It is a struct and each field contains a column vector
or column cell-array where each row corresponds to a
single instruction iinstr:
-- fb.nmatch[iinstr] holds the number of options which
have keys matching with the instruction;
-- fb.nmanip[iinstr] holds the number of options which
are changed, deleted or appended due to the
instruction;
-- fb.req{iinstr} holds a cell-array with the key and
value of the requested option, in case of an
instruction with "???";
-- fb.msg{iinstr} holds a comment or an error message.
The optional output argument msg is a string and contains
an error message or the concatenation of comments in
fb.msg(:). If the output argument is not requested, the
contents of msg is printed on screen, always via printf()
and never via error().
See the help text of m-file optioninfo.m for further
explanation.
The function internally calls the following
non-standard m-files:
-- optionformat_default.m;
-- optionsplit.m;
-- optionjoin.m;
-- optionfind.m;
-- strsplitchar.m;
-- strjoinnonempty.m.
(c) 2026 fabien van mook
2026.08.20 release of this file within package "fvm-optionmanip" under GNU GPLv3+
