The best packages make their options settable in multiple ways and have a defined hierarchy and visibility of options - by visibility I mean whether an option is editable in some way.
- When installing the package some checks are done/questions answered that become options and values in an options file in the install area. Ideally this should also have package default values.
I have only ever seen these types of files best done in windows .ini format, but I would think that YAML could also be used as it too is human readable/editable and supports comments (unlike JSON).
Comments should precede every entry and section with enough detail to be understood by someone who has been on the packages introductory course and read the documentation or marked for advance use only.
(Options should be of a single case although their expression as upper/lower case may depend on context)
- The first time a program from the package is run it creates a $HOME/.package file of all user specific and user changeable options with their site specific defaults (copied over at that time and with comments). This will be a subset of the site options.
- When an interactive program from the package is run from within a run directory a subset of options will be editable , set and reset within the program. On good program exit a run directory .package file should be created with both the normal program options used but augmented with aspects of the programs state so that on re-running the program from the same directory things like GUI window positions or database connections that were filled in on the previous invocation might start from those previous values.
(Warn when a program is run from the $HOME directory and ask before overwriting the $HOME/.package file).
- Some options will be able to be read from environment variables. Environment variable names should consist of a one-word prefix of the packages nick-name or name followed by the option name separated by a comma.
When a package contains a large sub-package then that sub-package nick-name may form the prefix instead.
Comments in the $HOME/.package file should state the environment variable name to use if an option is settable in the environment
- When invoking a program from the package the programs help should give help on all the options that are settable on the command line. In addition, those options settable on the command line should also appear in the $HOME/.package file and run directory .package file with the posix long format argument mentioned in the help text.
One should allow for a program argument short-form (single letter argument), that needs to appear in the programs help, but not necessarily in any .package file comments allowing for other package programs to reuse single character short options in what for them may be more idiomatic fashion.
Default values need to reflect values already set in the options processing mentioned in 6.1 to 6.3.
- There should be a clear hierarchy of options processing:
- Process the site .package file
- Process the run directory .package file if it exists, else if it does not exist then process the home directory .package file.
- Process environment variable options.
- Process command line options.
- Process options changes within a program.
- Options processing should also check to ensure that given options are allowed to be changed/viewed where stated.
- Options processing should impose a hierarchy whereby an option set later overrides values set earlier in the 6.1 to 6.5 stages mentioned.