The duologue Reference Manual

This is the duologue Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 05:08:15 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 duologue

High-level user interaction library for Common Lisp

Author

Mariano Montone <>

Home Page

https://github.com/mmontone/duologue

License

MIT

Long Description

# 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

Dependencies
  • anaphora (system).
  • alexandria (system).
  • clavier (system).
  • chronicity (system).
  • cl-ansi-text (system).
  • cl-fad (system).
Source

duologue.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 duologue/duologue.asd

Source

duologue.asd.

Parent Component

duologue (system).

ASDF Systems

duologue.


3.1.2 duologue/package.lisp

Source

duologue.asd.

Parent Component

duologue (system).

Packages

duologue.


3.1.3 duologue/nocompletion.lisp

Dependency

package.lisp (file).

Source

duologue.asd.

Parent Component

duologue (system).

Internals

complete-prompt (function).


3.1.4 duologue/duologue.lisp

Dependency

nocompletion.lisp (file).

Source

duologue.asd.

Parent Component

duologue (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 duologue

High-level interaction library for Common Lisp

Source

package.lisp.

Use List
  • anaphora.
  • common-lisp.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: while (msg (&rest options) &body body)

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

Package

duologue.

Source

duologue.lisp.


5.1.2 Ordinary functions

Function: ask (msg &key default if-wrong-answer color error-color)

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.

Package

duologue.

Source

duologue.lisp.

Function: choose (msg options &key if-wrong-option default print-options separator complete completer color 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

Package

duologue.

Source

duologue.lisp.

Function: choose-many (msg options &key if-wrong-option default print-options separator complete completer test color error-color)

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

Package

duologue.

Source

duologue.lisp.

Function: prompt (msg &key default required-p validator if-invalid parser completer type color error-color)

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.

Package

duologue.

Source

duologue.lisp.

Function: prompt-datetime (msg &key default required-p if-invalid color 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.

Package

duologue.

Source

duologue.lisp.

Function: prompt-email (msg &key default required-p validator if-invalid color error-color)

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.

Package

duologue.

Source

duologue.lisp.

Function: prompt-integer (msg &key default required-p if-invalid validator color error-color)

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

Package

duologue.

Source

duologue.lisp.

Function: prompt-pathname (msg &key default required-p if-invalid color error-color probe if-exists if-does-not-exist absolute-p file-type complete)

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.

Package

duologue.

Source

duologue.lisp.

Function: prompt-url (msg &key default required-p if-invalid color error-color probe if-exists if-does-not-exist)

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

Package

duologue.

Source

duologue.lisp.

Function: say (datum &rest args)

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

Package

duologue.

Source

duologue.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *prompt-color*

The default prompt color.

Package

duologue.

Source

duologue.lisp.

Special Variable: *prompt-error-color*

The default error color

Package

duologue.

Source

duologue.lisp.


5.2.2 Ordinary functions

Function: complete-prompt (prompt options completer)
Package

duologue.

Source

nocompletion.lisp.

Function: duologue-read-line ()
Package

duologue.

Source

duologue.lisp.

Function: find-option (args option)
Package

duologue.

Source

duologue.lisp.

Function: make-validator (thing)
Package

duologue.

Source

duologue.lisp.

Function: parse-if-invalid (spec &optional error-color)
Package

duologue.

Source

duologue.lisp.

Function: remove-options (args &rest keys)
Package

duologue.

Source

duologue.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   D   F   M   P   R   S   W  
Index Entry  Section

A
ask: Public ordinary functions

C
choose: Public ordinary functions
choose-many: Public ordinary functions
complete-prompt: Private ordinary functions

D
duologue-read-line: Private ordinary functions

F
find-option: Private ordinary functions
Function, ask: Public ordinary functions
Function, choose: Public ordinary functions
Function, choose-many: Public ordinary functions
Function, complete-prompt: Private ordinary functions
Function, duologue-read-line: Private ordinary functions
Function, find-option: Private ordinary functions
Function, make-validator: Private ordinary functions
Function, parse-if-invalid: Private ordinary functions
Function, prompt: Public ordinary functions
Function, prompt-datetime: Public ordinary functions
Function, prompt-email: Public ordinary functions
Function, prompt-integer: Public ordinary functions
Function, prompt-pathname: Public ordinary functions
Function, prompt-url: Public ordinary functions
Function, remove-options: Private ordinary functions
Function, say: Public ordinary functions

M
Macro, while: Public macros
make-validator: Private ordinary functions

P
parse-if-invalid: Private ordinary functions
prompt: Public ordinary functions
prompt-datetime: Public ordinary functions
prompt-email: Public ordinary functions
prompt-integer: Public ordinary functions
prompt-pathname: Public ordinary functions
prompt-url: Public ordinary functions

R
remove-options: Private ordinary functions

S
say: Public ordinary functions

W
while: Public macros