The duologue Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The duologue Reference Manual

This is the duologue Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:43:04 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

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

(&optional (msg "Yes or no: ") &key (default nil default-p) if-wrong-answer
 (color *prompt-color*) (error-color *prompt-error-color*))

Ask for yes or no.

choose

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

Example:

(choose "Choose: " (list "foo" "bar" "baz") :default "baz")

Tags: menu, choose

choose-many

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

(choose-many "Choose: " (list "foo" "bar" "baz") :default "baz")

Tags: menu, choose

make-list-completer

(options)

Makes a default completer from a list of options

prompt

(&optional 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.

prompt-datetime

(&optional 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

(&optional 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

(&optional 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

(&optional 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.

prompt-url

(&optional 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.

Returns: the entered url

say

(datum &rest args)

Prints a message on the screen.

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

Macros

while

(msg (&rest options) &body body)

Asks to repeat a task several times and collects its result.

Returns: A list of collected task results

Example: ```lisp (while "Add item?: " (:default t) (prompt "Item: "))

**Tags**: flow


## Generic-Functions
## Slot-Accessors
## Variables
## Classs
## Conditions
## Constants

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


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

2.1 duologue

Author

Mariano Montone <marianomontone@gmail.com>

License

MIT

Description

High-level user interaction library for Common Lisp

Dependencies
Source

duologue.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


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

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 duologue.asd

Location

duologue.asd

Systems

duologue (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 duologue/package.lisp

Parent

duologue (system)

Location

package.lisp

Packages

duologue


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 duologue/duologue.lisp

Dependency

package.lisp (file)

Parent

duologue (system)

Location

duologue.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


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

4.1 duologue

High-level interaction library for Common Lisp

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


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

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [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 (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: ask &optional 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 (file)

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

“(choose "Choose: " (list "foo" "bar" "baz") :default "baz")“

Tags: menu, choose

Package

duologue

Source

duologue.lisp (file)

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

“(choose-many "Choose: " (list "foo" "bar" "baz") :default "baz")“

Tags: menu, choose

Package

duologue

Source

duologue.lisp (file)

Function: make-list-completer OPTIONS

Makes a default completer from a list of options

Package

duologue

Source

duologue.lisp (file)

Function: prompt &optional MSG &key DEFAULT REQUIRED-P VALIDATOR IF-INVALID PARSER COMPLETER 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.
- color: Prompt color
- error-color: Prompt error color.

Package

duologue

Source

duologue.lisp (file)

Function: prompt-datetime &optional 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 (file)

Function: prompt-email &optional MSG &key DEFAULT REQUIRED-P 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 (file)

Function: prompt-integer &optional MSG &key DEFAULT REQUIRED-P IF-INVALID 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 (file)

Function: prompt-pathname &optional MSG &key DEFAULT REQUIRED-P IF-INVALID COLOR ERROR-COLOR PROBE IF-EXISTS IF-DOES-NOT-EXIST ABSOLUTE-P FILE-TYPE DIRECTORY-P 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 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.

Package

duologue

Source

duologue.lisp (file)

Function: prompt-url &optional 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 (file)

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 (file)


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

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *prompt-color*

The default prompt color.

Package

duologue

Source

duologue.lisp (file)

Special Variable: *prompt-error-color*

The default error color

Package

duologue

Source

duologue.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: find-option ARGS OPTION
Package

duologue

Source

duologue.lisp (file)

Function: remove-options ARGS &rest KEYS
Package

duologue

Source

duologue.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   D   F   L  
Index Entry  Section

D
duologue.asd: The duologue<dot>asd file
duologue/duologue.lisp: The duologue/duologue<dot>lisp file
duologue/package.lisp: The duologue/package<dot>lisp file

F
File, Lisp, duologue.asd: The duologue<dot>asd file
File, Lisp, duologue/duologue.lisp: The duologue/duologue<dot>lisp file
File, Lisp, duologue/package.lisp: The duologue/package<dot>lisp file

L
Lisp File, duologue.asd: The duologue<dot>asd file
Lisp File, duologue/duologue.lisp: The duologue/duologue<dot>lisp file
Lisp File, duologue/package.lisp: The duologue/package<dot>lisp file

Jump to:   D   F   L  

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

A.2 Functions

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

A
ask: Exported functions

C
choose: Exported functions
choose-many: Exported functions

F
find-option: Internal functions
Function, ask: Exported functions
Function, choose: Exported functions
Function, choose-many: Exported functions
Function, find-option: Internal functions
Function, make-list-completer: Exported functions
Function, prompt: Exported functions
Function, prompt-datetime: Exported functions
Function, prompt-email: Exported functions
Function, prompt-integer: Exported functions
Function, prompt-pathname: Exported functions
Function, prompt-url: Exported functions
Function, remove-options: Internal functions
Function, say: Exported functions

M
Macro, while: Exported macros
make-list-completer: Exported functions

P
prompt: Exported functions
prompt-datetime: Exported functions
prompt-email: Exported functions
prompt-integer: Exported functions
prompt-pathname: Exported functions
prompt-url: Exported functions

R
remove-options: Internal functions

S
say: Exported functions

W
while: Exported macros

Jump to:   A   C   F   M   P   R   S   W  

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

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*prompt-color*: Internal special variables
*prompt-error-color*: Internal special variables

S
Special Variable, *prompt-color*: Internal special variables
Special Variable, *prompt-error-color*: Internal special variables

Jump to:   *  
S  

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

A.4 Data types

Jump to:   D   P   S  
Index Entry  Section

D
duologue: The duologue system
duologue: The duologue package

P
Package, duologue: The duologue package

S
System, duologue: The duologue system

Jump to:   D   P   S