interaction.md

Documentation for the functions in interaction.sh. A general overview is given in the project documentation.

Function documentation

If the pipes are not documented, the default is:

• stdin: piped input ignored
• stdout: empty

Parameters enclosed in brackets [ ] are optional.

read_and_validate()

Combined read and regex check.

Important read flags:

• -n <nb_chars> : read stops after nb_chars, which gives a "auto-return" UX
• -s : makes read hide the user input

Param.	$1	validation regex (if matched it leads to return status 0)
	[$2]	flags passed to read, defaults to an empty string
Pipes	stdin	piped input ignored; used via read
	stdout	the user input
Status	0	the user entered a $1 match
	1	the user input doesn't match $1
	2	if $1 is empty

get_user_confirmation()

Yes/no type questions. Blocks waiting for user input, returns as soon as one character is entered.

Param.	[$1]	confirmation character, defaults to y
Pipes	stdin	piped input ignored; used via read_and_validate()
	stdout	a newline control sequence to reset the cursor which stands just after the user input
Status	0	if the user entered $1
	1	if the user entered something else

get_user_choice()

The function behaves as if it ignores input as long as it doesn't match the regex $1. It may hence be used as "option selector". As soon as the input matches $1 the function returns with status 0 and provides the selected option on stdout.

The way it works is that it uses read's -s flag to keep the entered input hidden; if the input doesn't match $1, read_and_validate() returns 1, the function loops and calls read_and_validate() again.

Example: the user is offered 3 choices numbered 1 to 3, $1 should be ^[1-3]$

Param.	$1	options regex
Pipes	stdin	piped input ignored; used via read_and_validate()
	stdout	the selected option
Status	0