The prompt-for Reference Manual

This is the prompt-for Reference Manual, version 3.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:14:34 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 prompt-for

Type safe user input.

Author

SATO Shinichi

Source Control

(GIT git@github.com:hyotang666/prompt-for)

Bug Tracker

https://github.com/hyotang666/prompt-for/issues

License

MIT

Long Description

# PROMPT-FOR 2.0.0
## What is this?
Type safe user input.

## Alternatives and differences.

| | [duologue] | prompt-for |
| — | ———- | ———- |
| coloring | \* | |
| completion | \* | |
| choosing | \* | |
| email | \* | |
| url | \* | |
| datetime | \* | |
| secret | | sbcl with unix os only |
| types | integer pathname | any-lisp-types |
| interact | standard-io | query-io |

### See also.
* [query-repl]
* [text-query]

## Usage

“‘lisp
* (prompt-for:prompt-for ’integer "~&Input integer> ")

Input integer> not-integer

NOT-INTEGER is type of SYMBOL, not INTEGER
Input integer> 0
0
“‘
For detail, see [spec file.](spec/prompt-for.lisp)

### TIPS

PROMPT-FOR is a generic function.
If the first argument is a function, it checks user input with it.

“‘lisp
* (prompt-for:prompt-for #’evenp "~&Input even integer>> ")

Input even integer>> 1

1 is type of BIT, not satisfies #<FUNCTION EVENP>.
Input even integer>> 2
2
“‘

Note that the lambda function will be useless as a message for users when failed.

“‘lisp
* (prompt-for:prompt-for (lambda (x) (evenp x)) "~&Input even integer>> ")

Input even integer>> 1

1 is type of BIT, not satisfies #<FUNCTION (LAMBDA (X)) {...}>.
“‘

In such a case, the local function may help you.

“‘lisp
* (flet ((my-evenp (x) (evenp x)))
(prompt-for:prompt-for #’my-evenp "~&Input even integer>> "))

Input even integer>> 1

1 is type of BIT, not satisfies #<FUNCTION (FLET MY-EVENP) {...}>.
“‘

Note that these examples are in SBCL.
Other implementations may prints function in other ways.

If you want maximum portability, or customize the message,
you need to use the intermediate object and override method.

“‘lisp
(defstruct fun sym)

(defmethod prompt-for:prompt-for ((f fun) &rest args)
(loop :for input = (progn (apply #’uiop:format! *query-io* args)
(read *query-io*))
:when (funcall (fun-sym f) input)
:return input
:else :do (format *query-io* "~&WTF dude! It does not satisfy ~S!" (fun-sym f))))

* (prompt-for:prompt-for (make-fun :sym ’evenp) "~&Input even integer>> ")

Input even integer>> 1

WTF dude! It does not satisfy EVENP!
Input even integer>>
“‘

### TIPS
‘prompt-for‘ returns user input.

“‘lisp
* (prompt-for:prompt-for #’find-class "~&Input class name >> ")
Input class name >> stream
STREAM
“‘

If you want e.g. stream object rather than a name even if user input is a class name, you can use ‘prompt-for:*default-reader*‘.

“‘lisp
* (let ((prompt-for:*default-reader*
(lambda (input) (find-class (read input)))))
(prompt-for:prompt-for t "~&Input class name >> "))
Input class name >> stream
#<SB-PCL:SYSTEM-CLASS COMMON-LISP:STREAM>
“‘

## From developer

### Product’s goal
Already?
### License
MIT

### Tested with
* SBCL/2.2.4
* CCL/1.12
* CLISP/2.49
* ECL/21.2.1
* Allegro/10.1
* CMUCL/21D
* ABCL/1.9.0

<!– Links –>
[query-repl]:https://github.com/hyotang666/query-repl
[text-query]:https://www.cliki.net/text-query
[duologue]:https://github.com/mmontone/duologue/

Version

3.1.0

Dependencies
  • sb-posix (system)., required, for feature :sbcl
  • uiop (system).
Source

prompt-for.asd.

Child Component

prompt-for.lisp (file).


3 Files

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


3.1 Lisp


3.1.1 prompt-for/prompt-for.asd

Source

prompt-for.asd.

Parent Component

prompt-for (system).

ASDF Systems

prompt-for.


3.1.2 prompt-for/prompt-for.lisp

Source

prompt-for.asd.

Parent Component

prompt-for (system).

Packages

prompt-for.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 prompt-for

Source

prompt-for.lisp.

Use List

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 Special variables

Special Variable: *default-reader*
Package

prompt-for.

Source

prompt-for.lisp.


5.1.2 Macros

Macro: do-with-prompt-input (((out format-args) (var reader)) &body body)

(DO-WITH-PROMPT-INPUT ((out { format-args }*) (var reader)) { body }*)
out := SYMBOL which will be bound by the output stream.
format-args := An expression to generate a list of format control and its arguments for prompt. var := SYMBOL which will be bound by the return value of the READER.
reader := An expression to generate (FUNCTION (STREAM) T) to read user input.
body := implicit progn.
Achieving the context to handle any errors, especially about user input,
evaluate the body form iteratively until CL:RETURN is successfully called.

Package

prompt-for.

Source

prompt-for.lisp.


5.1.3 Generic functions

Generic Function: prompt-for (target &rest args)
Package

prompt-for.

Source

prompt-for.lisp.

Methods
Method: prompt-for ((s (eql :secret)) &rest args)

Get user input string silently.

Method: prompt-for ((pred function) &rest args)

Ensure user input satisfies PRED.

Method: prompt-for ((target list) &rest args)

Ensure user input is type of TARGET.

Method: prompt-for ((target symbol) &rest args)

Ensure user input is type of TARGET.

Method: prompt-for :around (target &rest args)

5.2 Internals


5.2.1 Ordinary functions

Function: echo-off ()
Package

prompt-for.

Source

prompt-for.lisp.

Function: echo-on ()
Package

prompt-for.

Source

prompt-for.lisp.

Function: retrieve-keyword-arg (key args &optional default)

Return two values.
1. The value of the KEY in ARGS if exists, otherwise DEFAULT.
2. ARGS which is lacking the KEY value pair.
NOTE: Only check last two conses. Any KEY in front of it is ignored. e.g. (retrieve-keyword-arg :by ’(:by 1 :by 2 :by 3)) => 3, (:by 1 :by 2)

Package

prompt-for.

Source

prompt-for.lisp.

Function: secret-reader (reader)
Package

prompt-for.

Source

prompt-for.lisp.


5.2.2 Generic functions

Generic Reader: key (condition)
Package

prompt-for.

Methods
Reader Method: key ((condition deprecated))
Source

prompt-for.lisp.

Target Slot

key.


5.2.3 Conditions

Condition: deprecated
Package

prompt-for.

Source

prompt-for.lisp.

Direct superclasses

style-warning.

Direct methods

key.

Direct slots
Slot: key
Initargs

:key

Readers

key.

Writers

This slot is read-only.


Appendix A Indexes


A.1 Concepts


A.3 Variables