Proposal for tightening specification of implementation-defined options

[Mark Miller]

This may be a bit pre-mature but I am sending now because I've spent
some conscious cpu cycles on it and I wanted to capture it while things
are fresh in my mind.

Proposal:
---------
If an iMesh implementation supports implementation-defined options in
any of the functions admitting them (iMesh_newMesh, iMesh_save and
iMesh_load), the options must handled according the following
requirements:
   o option strings must be INsensitive to case.
   o option strings must be pre-pended with the implementation name
     followed by a special character called the separator character.
   o the separator character shall be a colon, ':'.
   o multiple options existing in a single option string must be
     separated by a special character called the delimiter character.
   o the delimiter character shall be a space, ' '.
   o the effect of multiple options in a single option string must be
     INsensitive to order of occurrence in the string.
   o by default, implementations must silently ignore any options
     that do not match on the implementation name part (everything
     before the separator character).
   o implementations may (or may not) warn or error for option strings
     that match on implementation name part but are found to be in
     error for other reasons the implementation decides.

Example:
---------
iMesh_load(..., "grummp:silant FMDB:TwoPhaseIO moab:hdf5-sec2-vfd"...

In the above example, the space serves as the delimiter character
between multiple options in the string. The colon serves as the
implementation-name/option separator character. Because things are
required to be insensitive to case, the caller is free to use case as a
word separator as in 'TwoPhaseIO' and even in the implementation name,
as in 'FMDB:', although 'fmdb:twophaseio' and 'fmdb:TWOPHASEIO' would
all have the same effect.

GRUMMP must silently ignore the FMDB: and moab: options because they do
NOT match on the implementation name part. However, GRUMMP can
optionally error out, or warn or silently ignore 'grummp:silant' (it was
supposed to be spelled 'silent') as an invalid option.

Rational:
---------
What happens if we have multiple implementations define the same option
string but for totally different purposes? By pre-pending the
implementation's name to the option string, we eliminate that
possibility. Pre-pending the implementation name also allows us to
distinguish between options we should and should not ignore. In
addition, it improves an implementation's ability to catch misspellings
or other inconsistencies in options

By making things insensitive to case, we alleviate the user from having
to worry about how to spell 'Grummp', 'GRUMMP' or 'grummp' or to worry
about option strings that differ only in case.

Differences from current specification:
---------------------------------------
For the most part, this proposal merely serves to tighten down the
current specification where implementation-defined options strings are
concerned.

However, in one respect, this proposal differs from the current
specification. That is in the handling of the delimiter character (the
character used to delimit different options in a string containing
multiple options).

This proposal fixes that character to a space. The current specification
says that character is 'programmable' and is be defined by the caller as
the first character in the options string. My rationale for doing away
with that is to simplify the specification and use.


-- 
Mark C. Miller, Lawrence Livermore National Laboratory
================!!LLNL BUSINESS ONLY!!================
miller86 at llnl.gov      urgent: miller86 at pager.llnl.gov
T:8-6 (925)-423-5901    M/W/Th:7-12,2-7 (530)-753-8511