duologue

2023-02-15

High-level user interaction library for Common Lisp

Upstream URL

github.com/mmontone/duologue

Author

Mariano Montone <marianomontone@gmail.com>

License

MIT, GPL v3
README

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

(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

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

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

  • 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

prompt

(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

(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

(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

(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

(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

(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

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

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

  • 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 (9)

  • alexandria
  • anaphora
  • chronicity
  • cl-ansi-text
  • clavier
  • cl-fad
  • cl-readline
  • drakma
  • stefil

Dependents (2)

  • GitHub
  • Quicklisp