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.

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.

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

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

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

package.lisp (file).
nocompletion.lisp (file).
duologue.lisp (file).

Next: Packages, Previous: Systems, Up: The duologue Reference Manual [Contents][Index]

3 Files

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

Lisp

Previous: Files, Up: Files [Contents][Index]

Next: duologue/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]

3.1.1 `duologue/duologue.asd`

Source: duologue.asd.
Parent Component: duologue (system).
ASDF Systems: duologue.

Next: duologue/nocompletion.lisp, Previous: duologue/duologue.asd, Up: Lisp [Contents][Index]

3.1.2 `duologue/package.lisp`

Source: duologue.asd.
Parent Component: duologue (system).
Packages: duologue.

Next: duologue/duologue.lisp, Previous: duologue/package.lisp, Up: Lisp [Contents][Index]

3.1.3 `duologue/nocompletion.lisp`

Dependency: package.lisp (file).
Source: duologue.asd.
Parent Component: duologue (system).
Internals: complete-prompt (function).

Previous: duologue/nocompletion.lisp, Up: Lisp [Contents][Index]

3.1.4 `duologue/duologue.lisp`

Dependency

nocompletion.lisp (file).

Source

duologue.asd.

Parent Component

duologue (system).

Public Interface

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

Internals

*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).

Next: Definitions, Previous: Files, Up: The duologue Reference Manual [Contents][Index]

4 Packages

Packages are listed by definition order.

duologue

Previous: Packages, Up: Packages [Contents][Index]

4.1 `duologue`

High-level interaction library for Common Lisp

Source

package.lisp.

Use List

anaphora.
common-lisp.

Public Interface

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

Internals

*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).

Next: Indexes, Previous: Packages, Up: The duologue Reference Manual [Contents][Index]

5 Definitions

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

Public Interface
Internals

Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]

5.1 Public Interface

Macros
Ordinary functions

Next: Ordinary functions, Previous: Public Interface, Up: Public Interface [Contents][Index]

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.

Previous: Macros, Up: Public Interface [Contents][Index]

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.

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.

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.

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.

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.

Previous: Public Interface, Up: Definitions [Contents][Index]

5.2 Internals

Special variables
Ordinary functions

Next: Ordinary functions, Previous: Internals, Up: Internals [Contents][Index]

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.

Previous: Special variables, Up: Internals [Contents][Index]

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.

Previous: Definitions, Up: The duologue Reference Manual [Contents][Index]

Appendix A Indexes

Concepts
Functions
Variables
Data types

Next: Functions, Previous: Indexes, Up: Indexes [Contents][Index]

A.1 Concepts

Next: Variables, Previous: Concepts, Up: Indexes [Contents][Index]

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

Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]

A.3 Variables

Jump to:	* S

	Index Entry	Section

*
	`prompt-color`:	Private special variables
	`prompt-error-color`:	Private special variables

S
	`Special Variable, prompt-color`:	Private special variables
	`Special Variable, prompt-error-color`:	Private special variables

Previous: Variables, Up: Indexes [Contents][Index]

A.4 Data types

Jump to:	D F N P S

	Index Entry	Section

D
	`duologue`:	The duologue system
	`duologue`:	The duologue package
	`duologue.asd`:	The duologue/duologue․asd file
	`duologue.lisp`:	The duologue/duologue․lisp file

F
	`File, duologue.asd`:	The duologue/duologue․asd file
	`File, duologue.lisp`:	The duologue/duologue․lisp file
	`File, nocompletion.lisp`:	The duologue/nocompletion․lisp file
	`File, package.lisp`:	The duologue/package․lisp file

N
	`nocompletion.lisp`:	The duologue/nocompletion․lisp file

P
	`Package, duologue`:	The duologue package
	`package.lisp`:	The duologue/package․lisp file

S
	`System, duologue`:	The duologue system

The duologue Reference Manual

Table of Contents

1 Introduction

2 Systems

2.1 duologue

3 Files

3.1 Lisp

3.1.1 duologue/duologue.asd

3.1.2 duologue/package.lisp

3.1.3 duologue/nocompletion.lisp

3.1.4 duologue/duologue.lisp

4 Packages

4.1 duologue

5 Definitions

5.1 Public Interface

5.1.1 Macros

5.1.2 Ordinary functions

5.2 Internals

5.2.1 Special variables

5.2.2 Ordinary functions

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

2.1 `duologue`

3.1.1 `duologue/duologue.asd`

3.1.2 `duologue/package.lisp`

3.1.3 `duologue/nocompletion.lisp`

3.1.4 `duologue/duologue.lisp`

4.1 `duologue`