DSL for the specification of a single parameter (value). ======================================================== (R1) All parameters are uniquely named, for proper identification within the system. (R2) All parameters additionally have a descriptive, humand readable text. (R3) Parameters come in three kinds: Arguments, Options, and State. (R4) Arguments and options are supplied from the command line, state is not. (R5) The values of arguments are filled in order, whereas the option's values are specified in any order, through, well, options. The last three rules can be modeled with two boolean flags: cmdline, and ordered, with following the mapping to kinds: cmdline ordered kind ------- ------- ---- y y argument y n option n - state ------- ------- ---- (R6) Instead of using a don't-care for ordered we declare 'state' parameters as unordered, and the last possible combination is forbidden. This raises the constraint (C1) !cmdline => !ordered [R6] <=> ordered => cmdline <=> cmdline || !ordered and the full mapping becomes cmdline ordered kind ------- ------- ---- y y argument y n option n y FORBIDDEN [C1] n n state ------- ------- ---- (R7) Another property of all parameters is whether they must be specified by the user or not, i.e. if they are required, or not. This is another boolean flag. (R8) Arguments can be both, required or not. (R9) Options are never required. (R10) State is always required. These last two rules raise two associated constraints: (C2) cmdline && !ordered => !required [R9] <=> required => !cmdline || ordered <=> !required || !cmdline || ordered (C3) !cmdline => required [R10] <=> !required => cmdline <=> cmdline || required cmdline ordered required kind ------- ------- -------- ---- y y y required argument y y n optional argument y n y FORBIDDEN [C2] y n n option n y y FORBIDDEN [C1] n y n FORBIDDEN [C1] n n y state n n n FORBIDDEN [C3] ------- ------- ---- (R11) For all parameters we may not just collect a single value, but a list. This is another boolean property, without any constraints on it. For list arguments we actually have one constraint: only one such argument is allowed, and if present it has to be the last argument. (C4) list && cmdline && ordered => is-last() (R12) Now, given that we want all parameters to have a value, even the optional ones we need some way of defining a value for these latter. Actually we have three methods: (R12.1) A fixed default value. (R12.2) A command prefix to generate (compute) the value. (R12.3) Allowing the system to prompt the user for the value, outside of the command line. (R12.4) Of these methods [.1] and [.2] exclude each other, and one must be specified. (R12.5) Method [.3] is independent of [.1] and [.2], sitting on top. (R13) The above method also apply to state parameters, as they will not get a value from the command line, like optional arguments might. (R14) Required arguments are not allowed to have any of these methods. The relevant and associated constraints are: (C5) (!required || !cmdline) => (default || generate || interact) <=> (required && cmdline) || default || generate || interact (C6) (default || generate || interact) => (!required || !cmdline) <=> (!default && !generate && !interact) || !required || !cmdline <=> (!default || !required || !cmdline) && (!generate || !required || !cmdline) && (!interact || !required || !cmdline) (C7) Under the precondition of (default || generate): default => !generate <=> generate => !default <=> !(default && generate) cmdline ordered required kind ------- ------- -------- ---- y y y required argument !default && !generate && !interact y y n optional argument default || generate || interact y n y FORBIDDEN [C2] y n n option default || generate || interact n y y FORBIDDEN [C1] n y n FORBIDDEN [C1] n n y state default || generate || interact n n n FORBIDDEN [C3] ------- ------- ---- (R15) One thing we wish to do for the parameter value is validation, i.e. ensuring that it has the proper type. For this each parameter has a command prefix. (R16) Sometimes it is advantageous to perform an action the moment a parameter (value) is defined. For this each parameter has a command prefix. (R17) Sometimes it is advantageous to perform an action the moment a parameter (user-string) is set. For this each parameter has a command prefix. (R18) An application command can have parameters which are not for regular use, but for debugging, possibly requiring raw access. Such parameters should be excluded from documentation. Modeled by a boolean property. (R19) Depending on how the backend used by the framework is constructed it can make sense for specific parameters to be defined before the actual command is invoked. I.e. to force the invokation of the when-complete callbacks and their side-effects before the implementation takes over. A use case would be for options to configure low-level parts of the system, so that the implementations do not have to, and thus not have to care about these options. On the other hand, by putting this into the implementations we can more easily handle ordering requirements between option values and side-effects. -- force -- remove -- -- auto-force always -- in order of declaration => set order properly for dependencies -- and cannot have cycles by definition (R20) A special kind of option to support are those not taking an argument, but simply triggering behaviour through their very presence on the command line. These can be modeled with a flag and are otherwise boolean options with a fixed default ('no'). Because of the latter such options cannot have a different custom default, generator command, nor other validation type. All in all the following contraints are raised: (C8) presence => cmdline && !ordered && !required <=> !presence | (cmdline && !ordered && !required) (C9) presence => (!default && !generate && !validate) <=> default|generate|validate => !presence <=> (!default | !presence) && (!generate | !presence) && (!validate | !presence) Collected parameter attributes (properties) =========================================== --------- ---- ----------- Attribute Type Description --------- ---- ----------- [R1] name TEXT Parameter name. [R2] description TEXT Human readable description. --------- ---- ----------- [R3,4,5,6] ordered BOOL Filled in order, vs. by name. [R3,4,5,6] cmdline BOOL Filled from the command line. --------- ---- ----------- [R7,8,9,10] required BOOL parameter is required vs. optional. --------- ---- ----------- [R11] list BOOL Single value versus list of values. --------- ---- ----------- [R12.1,13,14] default TEXT Default value to use (raw, validate on use) [R12.2,13,14] generate CMD Command to generate default [R12.3,13,14] interactive BOOL Allow user interaction to set value [R12.3,13,14] prompt TEXT Text for the interactive prompt --------- ---- ----------- [R15] validate CMD Command to validate and transform user input [R16] when-complete CMD Command to run when the parameter value is defined. [R17] when-set CMD Command to run when the parameter string! is set. --------- ---- ----------- [R18] undocumented BOOL If true, exclude the parameter from generated help. [R19] [R20] --------- ---- ----------- flags list(TEXT) List of flags to recognize. Collected property contraints ============================= (C1) !cmdline => !ordered [R6] <=> ordered => cmdline <=> cmdline || !ordered (C2) cmdline && !ordered => !required [R9] <=> required => !cmdline || ordered <=> !required || !cmdline || ordered (C3) !cmdline => required [R10] <=> !required => cmdline <=> cmdline || required (C4) list && cmdline && ordered => is-last() (C5) (!required || !cmdline) => (default || generate || interact) <=> (required && cmdline) || default || generate || interact <=> (required || default || generate || interact) && (cmdline || default || generate || interact) (C6) (default || generate || interact) => (!required || !cmdline) <=> (!default && !generate && !interact) || !required || !cmdline (C7) Under the precondition of (default || generate): default => !generate <=> generate => !default <=> !(default && generate) Legend: x <=> defined (x) !x <=> undefined (x) A => B <==> !A || B ============================================================================== Definition commands. See also "notes_arguments.txt" The properties below are the starting values. input ordered, !hidden, required, !list, !interactive, !generate, !default, !validate, !on, !prompt option !ordered, !hidden, !required, !list, !interactive, !generate, !default, !validate, !on, !prompt state !ordered, hidden, required, !list, !interactive, !generate, !default, !validate, !on, !prompt ============================================================================== Property commands. Command Affected properties Notes ------- ------------------- ----- alias NAME flags cmdline && !ordered default DATA default (set) [R12,13,14], [C5,6,7,8,9] generate CMD generate (set) [R12,13,14], [C5,6,7,8,9] interact ?TEXT? interactive, prompt [R12,13,14], [C5,6,7] list list (set) [R11], [C4] optional required (reset) [R7,8,9,10], [C2,3,5,6] validate CMD validate (set) [R15], [C8,9] when-complete CMD when-complete (set) [R16] when-set CMD when-set (set) [R17] ------- ------------------- ----- test undocumented undocumented [R18] (-) force forced [R19] presence onlypresence [R20], [C8,9] lock locker ------- ------------------- ----- ==============================================================================