AddingCommandLineOption

The complexity of implementing a new command line option (and corresponding feature) strongly depends on the required functionality. The logic may be described by as small as a few lines of code or may require rewriting large parts of ADDA. Here we describe a common part of any new command line option, which integrates it into command line parser, consistency tester, and internal help system. Corresponding changes in the code should be made in several places in param.c. These places are commented starting with TO ADD NEW COMMAND LINE OPTION and contain detailed description; the text below is less detailed. Added code should be analogous to command line parameters already present. The procedure is the following:

• Choose name for a new command line option: option_name.
• Add a function prototype PARSE_FUNC(option_name); to the existing list of prototypes. PARSE_FUNC(…) and PAR(…) are macros, which are defined in param.c and used for conciseness.
• Add a row to definition of static structure options, containing PAR(option_name), usage string (the description of possible input parameters), help string (it will be shown when -h option is used), number of arguments, pointer to suboption (if exist, NULL otherwise). If this command line option can accept variable number of parameters, use UNDEF instead of a number and then check the number of parameters explicitly in function PARSE_FUNC(option_name) (see below). A separate suboption structure is recommended only for large options such as -beam and -shape, and it should be defined as type static const struct subopt_struct in the beginning of param.c.
• Add a function definition starting with PARSE_FUNC(option_name) to the existing list of definitions. This function actually implements the necessary logic for the command line option or at least registers that it was met during parsing of the command line. Typically, this function should check number of parameters (if UNDEF was used in the option definition, see above), parse parameters and check them for consistency (if applicable), and set the values of some internal variables or flags. If a new command line option contains suboptions, you should also parse them using the suboption structure and check for consistency. For working with input parameters you are encouraged to use functions from param.h and param.c since they are designed to be overflow-safe and would automatically produce informative output in case of error.
• New variables required for implementation of the command line option should be defined in the beginning of param.c and initialized in function InitVariables. However, you may also define variables as semi-global or global if they are used in two or more than two source files respectively.
• If a new command line option may potentially conflict or interact with other options, address this issue in function VariablesInterconnect.
• If any output in log or stdout should be produced based on the presence of command line option or on the values of its parameters, it should be implemented in function PrintInfo.

If you add a new command line option to ADDA according to the described procedure, please consider contributing your code to be incorporated in future releases.