This is the duologue Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 17:58:40 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
duologue
High-level user interaction library for Common Lisp
Mariano Montone <marianomontone@gmail.com>
MIT
# DUOLOGUE
Duologue is high-level interaction library for Common Lisp. Command line interaction is implemented at the moment. It features coloured printing via cl-ansi-text and readline completion.
## Functions
### ask
“‘lisp
(msg &key (default nil default-p) if-wrong-answer
(color *prompt-color*) (error-color *prompt-error-color*))
“‘
Ask for yes or no.
- **msg**: (string) The prompt to use.
- **default**: Default value. It gets selected if the user enters the empty string. Default: nil.
- **if-wrong-answer**: (function) Function to execute if a wrong answer is given.
- **color**: Prompt color.
- **error-color**: Prompt error color.
### choose
“‘lisp
(msg options &key if-wrong-option default (print-options t) (separator "~%")
complete completer (color *prompt-color*) (error-color *prompt-error-color*))
“‘
Asks the user to choose one of the given options.
- **msg**: (string) The prompt message.
- **options**: (list) The list of options the user can choose from.
- **if-wrong-option**: (function) When present, this function is run if the user enters a wrong option. Default: nil.
- **default**: The default value. The default value is selected if the user just hits the ENTER key. Default: nil.
- **print-options**: (boolean) Print the options on the screen. Default: T.
- **separator**: (string) Separation string to use when printing the options. Default: ’~%’
- **complete**: If T, then readline completion is enabled. Default: nil.
- **completer**: A custom completer. If NIL, then the default completer is used.
- **color**: Color to use at prompt. Default: *prompt-color*
- **error-color**: Color to use when error ocurrs. Default: *prompt-error-color*
Example:
“‘lisp
(choose "Choose: " (list "foo" "bar" "baz") :default "baz")
“‘
**Tags**: menu, choose
### choose-many
“‘lisp
(msg options &key if-wrong-option default (print-options t) (separator "~%")
complete completer (test #’eql) (color *prompt-color*)
(error-color *prompt-error-color*))
“‘
Asks the user to choose many of the given options.
- **msg**: (string) The prompt message.
- **options**: (list) The list of options the user can choose from.
- **if-wrong-option**: (function) When present, this function is run if the user enters a wrong option. Default: nil.
- **default**: The default value. The default value is selected if the user just hits the ENTER key. Default: nil.
- **print-options**: (boolean) Print the options on the screen. Default: T.
- **separator**: (string) Separation string to use when printing the options. Default: ’~%’
- **complete**: If T, then readline completion is enabled. Default: nil.
- **completer**: A custom completer. If NIL, then the default completer is used.
- **color**: Color to use at prompt. Default: *prompt-color*
- **error-color**: Color to use when error ocurrs. Default: *prompt-error-color*
Example:
“‘lisp
(choose-many "Choose: " (list "foo" "bar" "baz") :default ’("baz"))
“‘
**Tags**: menu, choose
### prompt
“‘lisp
(msg &key (default nil default-p) (required-p t) validator if-invalid
parser completer (color *prompt-color*) (error-color *prompt-error-color*))
“‘
Prompt for a string.
- **msg**: The prompt.
- **default**: Default value. This is returned if the user enters the empty string. Default: nil.
- **required-p**: (boolean) If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- **validator**: (function) A function to use to validate the input. Should return T if the input is valid, or NIL otherwise.
- **if-invalid**: (function) Function to execute if the validator fails.
- **parser**: (function) A function to parse the input string.
- **completer**: A custom completer. Default: no completion.
- **color**: Prompt color
- **error-color**: Prompt error color.
### prompt-datetime
“‘lisp
(msg &key default (required-p t) if-invalid (color *prompt-color*)
(error-color *prompt-error-color*))
“‘
Prompts for a timestamp.
- **msg**: The prompt.
- **default**: Default value. This is returned if the user enters the empty string. Default: nil.
- **required-p**: (boolean) If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- **if-invalid**: (function) Function to execute if the validator fails.
- **color**: Prompt color
- **error-color**: Prompt error color.
**Returns**: the parsed local-time
The input is parsed with chronicity library and transformed to a local-time.
The input is validated and the process does not stop until the user enters a valid timestamp address.
### prompt-email
“‘lisp
(msg &key default (required-p t) if-invalid (color *prompt-color*)
(error-color *prompt-error-color*))
“‘
Prompts for an email.
- **msg**: The prompt.
- **default**: Default value. This is returned if the user enters the empty string. Default: nil.
- **required-p**: (boolean) If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- **if-invalid**: (function) Function to execute if the validator fails.
- **color**: Prompt color
- **error-color**: Prompt error color.
**Returns**: the entered email
The email is validated and the process does not stop until the user enters a valid email address.
### prompt-integer
“‘lisp
(msg &key default (required-p t) if-invalid (color *prompt-color*)
(error-color *prompt-error-color*))
“‘
Prompts for an integer.
- **msg**: The prompt.
- **default**: Default value. This is returned if the user enters the empty string. Default: nil.
- **required-p**: (boolean) If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- **if-invalid**: (function) Function to execute if the validator fails.
- **color**: Prompt color
- **error-color**: Prompt error color.
**Returns**: the entered number
### prompt-pathname
“‘lisp
(msg &key default (required-p t) if-invalid (color *prompt-color*)
(error-color *prompt-error-color*) probe if-exists (if-does-not-exist :error)
absolute-p file-type directory-p (complete t))
“‘
Prompts for a pathname.
- **msg**: The prompt.
- **default**: Default value. This is returned if the user enters the empty string. Default: nil.
- **required-p**: (boolean) If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- **if-invalid**: (function) Function to execute if the validator fails.
- **color**: Prompt color
- **error-color**: Prompt error color.
- **complete**: If T, then uses readline path completion. Default: T.
- probe. If T, checks that the file exists on the filesystem.
- **if-exists**: Function to call if the probe is successful.
- **if-does-not-exist**: (keyword) One of:
* :error : Tries again until the pathname can be accessed.
* :warn : Warns the user the pathname could not be accessed and asks for continuing.
* :warn-and-continue: Warns the user the pathname could not be accessed and continues.
### prompt-url
“‘lisp
(msg &key default (required-p t) if-invalid (color *prompt-color*)
(error-color *prompt-error-color*) probe if-exists (if-does-not-exist :error))
“‘
Prompts for an url.
- **msg**: The prompt.
- **default**: Default value. This is returned if the user enters the empty string. Default: nil.
- **required-p**: (boolean) If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- **if-invalid**: (function) Function to execute if the validator fails.
- **color**: Prompt color
- **error-color**: Prompt error color
- **probe**: (boolean) If T, then url is accessed and verified.
- **if-exists**: (function) A function to call if the url exists (can be accessed).
- **if-does-not-exist**: (keyword) One of:
* :error : Tries again until the url can be accessed.
* :warn : Warns the user the url could not be accessed and asks for continuing.
* :warn-and-continue: Warns the user the url could not be accessed and continues.
**Returns**: the entered url
### say
“‘lisp
(datum &rest args)
“‘
Prints a message on the screen.
- **datum**: (string) A format like string.
- **args**: Format arguments or :color, :newline options
- **color**: (keyword) An ansi-text color. One of ansi-colors (.i.e :red, :green, :yellow)
- **newline**: (boolean) If t, forces a newline after printing
A newline is printed iff either newline parameter is T or datum doesn’t end with a space. That is, if datum ends in a space, then no newline is printed.
Example:
“‘lisp
(say "Hello ~A" "John" :color :blue)
“‘
**Categories**: printing
**Tags**: printing
## Macros
### while
“‘lisp
(msg (&rest options) &body body)
“‘
Asks to repeat a task several times and collects its result.
- **msg**: The thing to ask to confirm the task
- **options**: Options of the ask operation
- **body**: The task to execute while the user confirms it.
**Returns**: A list of collected task results
Example:
“‘lisp
(while "Add item?: " (:default t)
(prompt "Item: "))
“‘
**Tags**: flow
anaphora
(system).
alexandria
(system).
clavier
(system).
chronicity
(system).
cl-ansi-text
(system).
cl-fad
(system).
package.lisp
(file).
nocompletion.lisp
(file).
duologue.lisp
(file).
Files are sorted by type and then listed depth-first from the systems components trees.
duologue/nocompletion.lisp
package.lisp
(file).
duologue
(system).
complete-prompt
(function).
duologue/duologue.lisp
nocompletion.lisp
(file).
duologue
(system).
ask
(function).
choose
(function).
choose-many
(function).
prompt
(function).
prompt-datetime
(function).
prompt-email
(function).
prompt-integer
(function).
prompt-pathname
(function).
prompt-url
(function).
say
(function).
while
(macro).
*prompt-color*
(special variable).
*prompt-error-color*
(special variable).
duologue-read-line
(function).
find-option
(function).
make-validator
(function).
parse-if-invalid
(function).
remove-options
(function).
Packages are listed by definition order.
duologue
High-level interaction library for Common Lisp
anaphora
.
common-lisp
.
ask
(function).
choose
(function).
choose-many
(function).
prompt
(function).
prompt-datetime
(function).
prompt-email
(function).
prompt-integer
(function).
prompt-pathname
(function).
prompt-url
(function).
say
(function).
while
(macro).
*prompt-color*
(special variable).
*prompt-error-color*
(special variable).
complete-prompt
(function).
duologue-read-line
(function).
find-option
(function).
make-validator
(function).
parse-if-invalid
(function).
remove-options
(function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Asks to repeat a task several times and collects its result.
Args: - msg: The thing to ask to confirm the task
- options: Options of the ask operation
- body: The task to execute while the user confirms it.
Returns: A list of collected task results
Example:
“(while "Add item?: " (:default t)
(prompt "Item: "))“
Tags: flow
Ask for yes or no.
Args: - msg(string): The prompt to use. Default: ’Yes or no: ’.
- default: Default value. It gets selected if the user enters the empty string. Default: nil.
- if-wrong-answer(function): Function to execute if a wrong answer is given.
- color: Prompt color.
- error-color: Prompt error color.
Asks the user to choose one of the given options.
Args: - msg(string): The prompt message.
- options(list): The list of options the user can choose from.
- if-wrong-option(function): When present, this function is run if the user enters a wrong option. Default: nil.
- default: The default value. The default value is selected if the user just hits the ENTER key. Default: nil.
- print-options(boolean): Print the options on the screen. Default: T.
- separator(string): Separation string to use when printing the options. Default: ’~%’
- complete: If T, then completion is enabled. Default: nil.
- completer: A custom completer. If NIL, then the default completer is used.
- color: Color to use at prompt. Default: *prompt-color*
- error-color: Color to use when error ocurrs. Default: *prompt-error-color*
Example:
“(choose "Choose: " (list "foo" "bar" "baz") :default "baz")“
Tags: menu, choose
Asks the user to choose many of the given options.
Args: - msg(string): The prompt message.
- options(list): The list of options the user can choose from.
- if-wrong-option(function): When present, this function is run if the user enters a wrong option. Default: nil.
- default: The default value. The default value is selected if the user just hits the ENTER key. Default: nil.
- print-options(boolean): Print the options on the screen. Default: T.
- separator(string): Separation string to use when printing the options. Default: ’~%’
- complete: If T, then completion is enabled. Default: nil.
- completer: A custom completer. If NIL, then the default completer is used.
- color: Color to use at prompt. Default: *prompt-color*
- error-color: Color to use when error ocurrs. Default: *prompt-error-color*
Example:
“(choose-many "Choose: " (list "foo" "bar" "baz") :default ’("baz"))“
Tags: menu, choose
Prompt for a string.
Args: - msg: The prompt.
- default: Default value. This is returned if the user enters the empty string. Default: nil.
- required-p(boolean): If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- validator(function): A function to use to validate the input. Should return T if the input is valid, or NIL otherwise.
- if-invalid(function): Function to execute if the validator fails.
- parser (function): A function to parse the input string.
- completer: A custom completer. Default: no completion.
- type: Type expected.
- color: Prompt color
- error-color: Prompt error color.
Prompts for a timestamp.
Args: - msg: The prompt.
- default: Default value. This is returned if the user enters the empty string. Default: nil.
- required-p(boolean): If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- if-invalid(function): Function to execute if the validator fails.
- color: Prompt color
- error-color: Prompt error color.
Returns: the parsed local-time
The input is parsed with chronicity library and transformed to a local-time.
The input is validated and the process does not stop until the user enters a valid timestamp address.
Prompts for an email.
Args: - msg: The prompt.
- default: Default value. This is returned if the user enters the empty string. Default: nil.
- required-p(boolean): If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- if-invalid(function): Function to execute if the validator fails.
- color: Prompt color
- error-color: Prompt error color.
Returns: the entered email
The email is validated and the process does not stop until the user enters a valid email address.
Prompts for an integer.
Args: - msg: The prompt.
- default: Default value. This is returned if the user enters the empty string. Default: nil.
- required-p(boolean): If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- if-invalid(function): Function to execute if the validator fails.
- color: Prompt color
- error-color: Prompt error color.
Returns: the entered number
Prompts for a pathname.
Args: - msg: The prompt.
- default: Default value. This is returned if the user enters the empty string. Default: nil.
- required-p(boolean): If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- if-invalid(function): Function to execute if the validator fails.
- color: Prompt color
- error-color: Prompt error color.
- complete: If T, then uses path completion. Default: T.
- probe. If T, checks that the file exists on the filesystem.
- if-exists: Function to call if the probe is successful.
- if-does-not-exist(keyword): One of:
* :error : Tries again until the pathname can be accessed.
* :warn : Warns the user the pathname could not be accessed and asks for continuing.
* :warn-and-continue: Warns the user the pathname could not be accessed and continues.
Prompts for an url.
Args: - msg: The prompt.
- default: Default value. This is returned if the user enters the empty string. Default: nil.
- required-p(boolean): If T, then the empty string is not allowed as a valid input, and the user is asked again for input. Default: t.
- if-invalid(function): Function to execute if the validator fails.
- color: Prompt color
- error-color: Prompt error color
- probe(boolean): If T, then url is accessed and verified.
- if-exists(function): A function to call if the url exists (can be accessed).
- if-does-not-exist(keyword): One of:
* :error : Tries again until the url can be accessed.
* :warn : Warns the user the url could not be accessed and asks for continuing.
* :warn-and-continue: Warns the user the url could not be accessed and continues.
Returns: the entered url
Prints a message on the screen.
Args: - datum(string): A format like string.
- args: Format arguments or :color, :newline options
- color(keyword): An ansi-text color. One of ansi-colors (.i.e :red, :green, :yellow)
- newline(boolean): If t, forces a newline after printing
A newline is printed iff either newline parameter is T or datum doesn’t end with a space. That is, if datum ends in a space, then no newline is printed.
Example:
“(say "Hello ~A" "John" :color :blue)“
Categories: printing
Tags: printing
The default prompt color.
The default error color
Jump to: | A C D F M P R S W |
---|
Jump to: | A C D F M P R S W |
---|
Jump to: | *
S |
---|
Jump to: | *
S |
---|
Jump to: | D F N P S |
---|
Jump to: | D F N P S |
---|