function file "optioninfo.m"

Function optioninfo()

returns this help text which gives general information
about the assumptions and the formats of variables for
these accompanying non-standard m-files:
-- optionformat_default.m;
-- optionsplit.m;
-- optionjoin.m;
-- optionvaluetoarr.m;
-- optionvaluetostr.m;
-- optionsort.m;
-- optionmanip.m;
-- optionfind.m.

By these m-files, one can manipulate options and arguments
typically given in an option list in unix shell commands.

The options and arguments should have a fairly simple
format, and an option list may look like e.g.:
-- "-a -b 7", where there are two options and "7" is an
   argument to the option "-b";
-- "-n --default", where there are two options, one
   indicated by "-" and the other indicated by two "-";
-- "pqr stu", where two options without prefixed "-" may
   also be considered as options if they have been
   specified as keys;
-- "10 20 30 -t0", where there are four options: the
   first three options are "unbound" or "keyless"
   arguments because they have not been specified, and the
   last option is a key with a "suffixed" argument "0";
-- "--abc1 2 3", where there is one option which has one
   suffixed argument "1" and two "free" arguments "2" and
   "3".

All of the above formats can be mixed, and there can be
an infinite number of options and arguments. Which
elements in a command are keys of options and how many
arguments an option has, is specified by a struct <fopt>,
explained in the help text of m-file
optionformat_default.m.

By struct <fopt>, we specify:
-- keys, by giving explicitly a string for each key,
   including the occurring prefixed "-" and excluding the
   occurring suffixed argument;
-- whether there may be a suffixed argument to the key;
-- how many free (i.e. non-suffixed) arguments must
   follow the key.

The following types of elements in an option list are
distinguished:
-- (known) key: a key specified in <fopt>, including the
   occuring prefixed "-";
-- unknown key: a key prefixed with one or two "-", but
   not specified in <fopt>
-- keybound value: an argument to a known key;
-- keyless or unbound value: an other element (considered
   as an option without a key and without arguments).

Several general assumptions are taken into account:
-- options and arguments are separated by spaces and the
   number of subsequent spaces is not significant;
-- spaces which do not separate options, should be
   escaped with backslashes: "\ ". So, e.g. the option
   "-a hello\ world", has "hello\ world" (with an escapted
   space) as its argument;
-- unknown keys are only recognised by optionsplit(), if
   the character after the dash(es) is a letter (!). After
   this letter may appear zero or more any other
   characters, until an unescaped space is detected;
-- one should take care with nested options, i.e. an
   option which holds a nested command e.g.. A trick is to
   escape spaces within the nested option and to make
   nested options starting with "-" invisible by preceding
   it with an escaped space.

The following types of variables are distinguished in the
m-files:
-- <sopt>: an option list, given as a single string;
-- <copt>: an option list, given as a row cell-array of
   strings. It is obtained after splitting each option of
   the respective <sopt> into a pair of strings, and has
   the following features:
   -- an option with a known or unknown key is split into
      a string containing the key and a string containing
      all the suffixed and free values (space-separated):
        {key,all_values_spaceseparated};
   -- an option considered as a keyless or unbound value
      is represented by an empty string and a string
      containing the value:
        {"",keylessvalue};
   -- the split is determined by the specifications in
      <fopt>. Moreover, two extra rules are applied:
      -- first, the elements in <sopt> are detected which
         are known and unknown keys; secondly, the other
         elements are examined whether they are free
         values or keyless values;
      -- when an unknown key is detected, each element
         which appears after it and until the next known
         or unknown key, will be considered as its
         argument;
-- <csopt>: a list of option lists, given as a cell-array
   of strings <sopt>
-- <ccopt>: a list of option lists, given as a cell-array
   of cell-arrays <copt>.


(c) 2026 fabien van mook

2026.08.20 release of this file within package "fvm-optionmanip" under GNU GPLv3+