cmdr
Artifact Content
Not logged in

Artifact e94764dcca7c19ac038606108b590d484183939a:


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
	-------			-------------------	-----



==============================================================================