The text-query Reference Manual

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

The text-query Reference Manual

This is the text-query Reference Manual, version 1.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 06:00:33 2022 GMT+0.

Table of Contents


1 Introduction

Short Description
-----------------

This is a generalized form of Y-OR-N-P and YES-OR-NO-P, adding more
generality and the ability to time out with a default value.


Author's Description
--------------------

The QUERY package generalizes the capabilities of the Lisp functions
Y-OR-N-P and YES-OR-NO-P, and is similar in many ways to the Symbolics
FQUERY function. There are several major differences, one of which is QUERY's
ability to timeout with a default value. In addition to redefining Y-OR-N-P
and YES-OR-NO-P in terms of QUERY, this package defines Y-OR-N-P-WAIT and
YES-OR-NO-P-WAIT to illustrate the timeout capability. More complicated
queries are possible using the QUERY function.


Packager's Notes
----------------

This is old code, from 1993, but it is good ANSI Common Lisp. It compiles
and runs well under SBCL and should work in any modern Lisp implementation.

Please see the source code for documentation, since it contains plenty
of comments, docstrings, and examples.

-Peter Scott, October 2004


Acknowledgements
----------------

This code was entirely written by Mark Kantrowitz and made available to us
because of his generosity. Peter Scott, the maintainer of this package, would
not be so presumptious to take credit for anything other than the asdf
packaging.

2 Systems

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


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

2.1 text-query

A general text-based system for querying the user.

Maintainer

Peter Scott <sketerpot@gmail.com>

Author

Mark Kantrowitz

License

Free use, modification, and distribution. Copyright 1993 by Mark Kantrowitz.

Version

1.1

Source

text-query.asd.

Child Components

3 Files

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


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

3.1 Lisp


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

3.1.1 text-query/text-query.asd

Source

text-query.asd.

Parent Component

text-query (system).

ASDF Systems

text-query.

Packages

text-query-system.


3.1.2 text-query/text-query.lisp

Source

text-query.asd.

Parent Component

text-query (system).

Packages

text-query.

Public Interface
Internals

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

3.2 Doc


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

3.2.1 text-query/README

Source

text-query.asd.

Parent Component

text-query (system).


4 Packages

Packages are listed by definition order.


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

4.1 text-query-system

Source

text-query.asd.

Use List
  • asdf/interface.
  • common-lisp.

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

4.2 text-query

Source

text-query.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


5.1.1 Ordinary functions

Function: query (options &optional format-string &rest format-arguments)

QUERY is used for asking questions of the user. OPTIONS is a property-list containing the following keywords:
:TYPE :char or :line (how *query-io* is read)
:CHOICES A list containing entries of the form
(<value> . <key>*) or ((<value> <print>) . <key>*), where <value> is the value to be returned, <key> is a character or string, as the case may be, that is used to select the <value>, and <print> is printed when the value is selected.
:BEEP Specifies whether to ring the bell.
:CLEAR-INPUT If T, does a clear-input before querying. :FRESH-LINE If T, starts on a fresh line before printing
the prompt.
:LIST-CHOICES If T, prints a list of the choices after the prompt. :HELP-STRING A string to be printed if the user asks for help. :TIMEOUT The number of seconds to wait, if using timeouts. :TIMEOUT-DEFAULT The default value to use if the query times out. :STREAM The stream to use. Defaults to *query-io* :SIGNAL-CONDITION If T, will signal a condition of type QUERY-ERROR before proceeding. If non-NIL but not T, uses the value as the name of the condition. :EOF-ERROR-P If T (the default), signals an error if eof is reached. If NIL, returns EOF-VALUE upon reaching eof :EOF-VALUE Value returned if eof is reached and eof-error-p is NIL.

Package

text-query.

Source

text-query.lisp.

Function: y-or-n-p (&optional format-string &rest format-arguments)

Y-OR-N-P prints the message, if supplied, and reads a character from *QUERY-IO* until the user types a Y or an N, returning T and NIL, respectively. Repeats the request if the user typed anything else. Also, if a H or ? is enterred, prints a brief help message. If you want a question mark at the end of the message, you must put it there yourself; Y-OR-N-P will not add it.

Package

text-query.

Source

text-query.lisp.

Function: y-or-n-p-wait (&optional default timeout format-string &rest format-arguments)

Y-OR-N-P-WAIT is like Y-OR-N-P, but will timeout after TIMEOUT seconds with DEFAULT as the default value.

Package

text-query.

Source

text-query.lisp.

Function: yes-or-no-p (&optional format-string &rest format-arguments)

YES-OR-NO-P prints the message, if supplied, rings the bell, and reads a line from *QUERY-IO* (ignoring whitespace) until the user types YES or NO, returning T and NIL, respectively. Repeats the request if the user typed anything else. Also, if HELP, H or ? is enterred, prints a brief help message. If you want a question mark at the end of the message, you must put it there yourself; YES-OR-NO-P will not add it.

Package

text-query.

Source

text-query.lisp.

Function: yes-or-no-p-wait (&optional default timeout format-string &rest format-arguments)

YES-OR-NO-P-WAIT is like YES-OR-NO-P, but will timeout after TIMEOUT seconds with DEFAULT as the default value.

Package

text-query.

Source

text-query.lisp.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *sleep-amount*

Amount of time to sleep between checking query-io. In multiprocessing Lisps, this allows other processes to continue while we busy-wait. If 0, skips call to SLEEP.

Package

text-query.

Source

text-query.lisp.

Special Variable: *timeout*
Package

text-query.

Source

text-query.lisp.

Special Variable: *y-or-n-p-choices*
Package

text-query.

Source

text-query.lisp.

Special Variable: *y-or-n-p-wait-default*
Package

text-query.

Source

text-query.lisp.

Special Variable: *yes-or-no-p-choices*
Package

text-query.

Source

text-query.lisp.

Special Variable: *yes-or-no-p-wait-default*
Package

text-query.

Source

text-query.lisp.


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

5.2.2 Ordinary functions

Function: internal-real-time-in-seconds ()
Package

text-query.

Source

text-query.lisp.

Function: query-internal (&key format-string format-arguments type choices beep clear-input fresh-line list-choices help-string timeout timeout-default stream signal-condition eof-error-p eof-value)
Package

text-query.

Source

text-query.lisp.

Function: read-char-wait (&optional timeout input-stream eof-error-p eof-value)
Package

text-query.

Source

text-query.lisp.

Function: read-line-wait (&optional timeout input-stream eof-error-p eof-value)
Package

text-query.

Source

text-query.lisp.


Appendix A Indexes


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

A.1 Concepts