Package: optionset
About OptionsetOptionset allows users to succinctly set up and conduct parameter studies for
applications that reference text-based dictionary files.AuthorMatthew C. Jonesmatt.c.jones.aoe@gmail.comInstallationThe easiest way to install Optionset is with the Python package managerpip:$pipinstalloptionsetTo install as a user (no root access required), use$pipinstall--useroptionsetDocumentationBasic UsageOptionset enables and disables user-predefined options in text-based
dictionary files in the base directory and below.  The user specifies the lines
in the files that will either be enabled or disabled by adding macro commands
as commented text.For example, suppose a parameter study involved varying fluid properties and
the kinematic viscosity was listed in a dictionary file as,// Inside notional dictionary filenu1.5e-5;// viscosity of air in units of [m^2/s]
//nu    1e-6; // viscosity of water in units of [m^2/s]In the above text, the property of water will be ignored, since the second line
is commented out.  To enable water instead of air, the user could simply switch
which line is commented.  However, this task is often inconvenient, especially
with numerous variable properties listed across multiple files.  Alternatively,
the following macro instructions can be added to the commented part of the text
to mark them as a parameters to be varied.// Inside notional dictionary filenu1.5e-5;// viscosity of air in units of [m^2/s] ~nu air
//nu    1e-6; // viscosity of water in units of [m^2/s] ~nu waterThis setup allows the user to easily switch between air and water simulations
without manually editing the dictionary file.  On the command line, simply run,$optionset~nuwaterand the dictionary file will be modified and re-written as,// Inside notional dictionary file
//nu    1.5e-5; // viscosity of air in units of [m^2/s] ~nu airnu1e-6;// viscosity of water in units of [m^2/s] ~nu waterso that water is now the active property. Within the prescribed macros,~nuis the ‘option’ whileairandwaterare the
‘settings’.  An unlimited number of arbitrary options and settings are allowed.
Each must be composed of alphanumerical words with dots, pluses, minuses, and
underscores, and the first 1+ characters in the option must be a symbol such as~@$^&=|?. Recognizable comments are denoted by//#%!or--.Useoptionset -ato view all of the options that you have set, or
evenoptionset -a ~nuto view all options that begin with~nu. Additionally,optionset -a -fwill show all options and
their associated files.Multi-line OptionsTo avoid comment clutter, multi-line options are encouraged by annotating*in front of the first and last options in a series.  For example,
suppose a dictionary file specified a series of functions to run.// Inside notional dictionary file
// // ~functions offfunctions// ~functions on{// ~functions on#include"cuttingPlane"// ~functions on#include"streamLines"// ~functions on}// ~functions onThe five repeated macros could instead be written more succinctly as,// Inside notional dictionary file
// // ~functions offfunctions// *~functions on{#include"cuttingPlane"#include"streamLines"}// *~functions onAnd runningoptionset ~functions offwould result in the following
modifications to the file, thereby disabling the functions.// Inside notional dictionary file// ~functions off
//functions                   // *~functions on
//{
//    #include "cuttingPlane"
//    #include "streamLines"
//}                           // *~functions onVariable OptionsAn additional feature is the variable option.  For variable options the macro
command must be formatted with a Perl-styled regular expression='<regex>'that matches the desired text to be changed with parentheses(), for example,// Inside notional dictionary filerho1.225;// ~density ='rho   (.*);'Here,(.*)matches1.225inrho   1.225;.  To change this to1025, runoptionset ~density 1025, and the line within the
file now becomes,// Inside notional dictionary filerho1025;// ~density ='rho   (.*);'Viewing Available Options and SettingsTo view all of the available options and settings that have been prescribed,
runoptionset -a.  To narrow the search to options that start with~nu, runoptionset -a ~nu. Additionally,optionset
-a -fwill list all associated file locations.Implementing the option/setting macros in the above examples, the following
output is generated from runningoptionset -a.Showingavailableoptionsandsettingsmatching'*'('  inactive  ','> active <','? both ?','= variable =')~functions>off<on~nuair>water<~density=1025=Bash Tab CompletionTo enable Bash shell tab completion, add the following to your~/.bashrc,# Inside ~/.bashrcfunctionos{optionset"$@"--bash-completion;source$HOME/.optionset/bash_completion;}and run the program usingosinstead ofoptionset.ScriptingUsing your favorite scripting language, it is convenient to glue this program
into more advanced option variation routines to create parameter sweeps and
case studies.  While this program is generally called as a shell command, it
is also possible to directly import this functionality into a Python script.# Inside notional Python scriptfromoptionsetimportoptionsetoptionset(['~nu','water'])# set kinematic viscosity to that of waterCommand-Line ArgumentsFor command line usage, the following arguments are permitted.positionalarguments:option'option'namesetting'setting'forgiven'option'optionalarguments:-h,--helpshowthishelpmessageandexit-H,--help-fullshowfullhelpmessageandexit-a,--availableshowavailableoption-settingcombinations;allowsforunix-styleglob-expressionsearching;'-a'isimplicitelyenabledwhenno'setting'isinput-f,--show-filesshowfilesassociatewithavailableoptions-v,--verboseturnonverboseoutput-q,--quietturnoffallstandardoutput-d,--debugturnondebugoutputinlogfile-n,--no-logdonotwritelogfileto'$HOME/.optionset/log_optionset'--rename-optionrenameinputoptioninallfiles--rename-settingrenameinputsettinginallfiles--bash-completionauto-generatebashtab-completionscript'$HOME/.optionset/bash_completion'--versionshowversionandexitTo view help from the terminal, run,$optionset-hLicenseOptionset is licensed under GNU GPLv3. See the LICENSE document.See AlsoGithub repository: for latest source code, unit tests, and examples.pyexpander: macro-processing with Python.