Changes between Initial Version and Version 1 of HemlockProgrammer/TheEchoArea


Ignore:
Timestamp:
Nov 4, 2007, 3:07:44 AM (13 years ago)
Author:
rme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/TheEchoArea

    v1 v1  
     1[[PageOutline]]
     2
     3= 12. The Echo Area =
     4
     5Hemlock provides a number of facilities for displaying information and
     6prompting the user for it.  Most of these work through a small window
     7displayed at the bottom of the screen.  This is called the echo area
     8and is supported by a buffer and a window.  This buffer's modeline
     9(see section 3.3) is referred to as the status line, which, unlike
     10other buffers' modelines, is used to show general status about the
     11editor, Lisp, or world.
     12
     13Default Status Line Fields [Hemlock Variable]
     14
     15This is the initial list of modeline-field objects stored in the echo
     16area buffer.
     17
     18Echo Area Height (initial value 3) [Hemlock Variable]
     19This variable determines the initial height in lines of the echo area window.
     20
     21== 12.1. Echo Area Functions ==
     22
     23It is considered poor taste to perform text operations on the echo
     24area buffer to display messages; the message function should be used
     25instead. A command must use this function or set buffer-modified (page
     2612) for the Echo Area buffer to nil to cause Hemlock to leave text in the
     27echo area after the command's execution.
     28
     29clear-echo-area [Function]
     30
     31Clears the echo area.
     32
     33message control-string &rest format-arguments [Function]
     34
     35loud-message control-string &rest format-arguments [Function]
     36
     37Message Pause (initial value 0.5) [Hemlock Variable]
     38
     39Displays a message in the echo area.  The message is always displayed
     40on a fresh line. message pauses for Message Pause seconds before
     41returning to assure that messages are not displayed too briefly to be
     42seen. Because of this, message is the best way to display text in the
     43echo area.  loud-message is like message, but it first clears the echo
     44area and beeps.
     45
     46*echo-area-window* [Variable]
     47
     48*echo-area-buffer* [Variable]
     49
     50echo-area-buffer contains the buffer object for the echo area, which
     51is named Echo Area. This buffer is usually in Echo Area
     52mode. echo-area-window contains a window displaying
     53echo-area-buffer. Its modeline is the status line, see the beginning
     54of this chapter.
     55
     56*echo-area-stream* [Variable]
     57
     58This is a buffered Hemlock output stream (59) which inserts text
     59written to it at the point of the echo area buffer. Since this stream
     60is buffered a force-output must be done when output is complete to
     61assure that it is displayed.
     62
     63== 12.2. Prompting Functions ==
     64
     65Most of the prompting functions accept the following keyword arguments:
     66
     67 :must-exist::
     68 If :must-exist has a non-nilvalue then the user is
     69 prompted until a valid response is obtained. If :must-exist is nil
     70 then return as a string whatever is input.  The default is t.
     71
     72 :default::
     73 If null input is given when the user is prompted then this
     74 value is returned. If no default is given then some input must be
     75 given before anything interesting will happen.
     76
     77 :default-string::
     78 If a :default is given then this is a string to be
     79 printed to indicate what the default is.  The default is some
     80 representation of the value for :default, for example for a buffer it
     81 is the name of the buffer.
     82
     83 :prompt::
     84 This is the prompt string to display.
     85
     86 :help::
     87 This is similar to:prompt, except that it is displayed when the help
     88 command is typed during input.
     89
     90 This may also be a function.  When called with no arguments, it
     91 should either return a string which is the help text or perform some
     92 action to help the user, returning nil.
     93
     94prompt-for-buffer &key :prompt :help :must-exist :default [Function]
     95:default-string
     96
     97Prompts with completion for a buffer name and returns the
     98corresponding buffer.  If must-exist is nil, then it returns the input
     99string if it is not a buffer name.  This refuses to accept the empty
     100string as input when :default and :default-string are
     101nil. :default-string may be used to supply a default buffer name
     102when:default is nil, but when :must-exist is non-nil, it must name an
     103already existing buffer.
     104
     105command-case ({key value}*){({({tag}*) | tag} help {form}*)}* [Macro]
     106
     107This macro is analogous to the Common Lisp case macro. Commands such
     108as Query Replace use this to get a key-event, translate it to a
     109character, and then to dispatch on the character to some case.  In
     110addition to character dispatching, this supports logical key-events
     111(page 45) by using the input key-event directly without translating it
     112to a character.  Since the description of this macro is rather
     113complex, first consider the following example:
     114{{{
     115(defcommand "Save All Buffers" (p)
     116  "Give the User a chance to save each modified buffer."
     117  "Give the User a chance to save each modified buffer."
     118  (dolist (b *buffer-list*)
     119    (select-buffer-command () b)
     120    (when (buffer-modified b)
     121      (command-case (:prompt "Save this buffer: [Y] "
     122                             :help "Save buffer, or do something else:")
     123        ((:yes :confirm)
     124         "Save this buffer and go on to the next."
     125         (save-file-command () b))
     126        (:no "Skip saving this buffer, and go on to the next.")
     127        (:recursive-edit
     128         "Go into a recursive edit in this buffer."
     129         (do-recursive-edit) (reprompt))
     130        ((:exit #\p) "Punt this silly loop."
     131         (return nil))))))
     132}}}
     133
     134command-case prompts for a key-event and then executes the code in the
     135first branch with a logical key-event or a character (called tags)
     136matching the input.  Each character must be a standard-character, one
     137that satisfies the Common Lisp standard-char-p predicate, and the
     138dispatching mechanism compares the input key-event to any character
     139tags by mapping the key-event to a character with
     140ext:key-event-char. If the tag is a logical key-event, then the search
     141for an appropriate case compares the key-event read with the tag
     142using logical-key-event-p.
     143
     144All uses of command-case have two default cases, :help and :abort. You
     145can override these easily by specifying your own branches that include
     146these logical key-event tags.  The :help branch displays in a pop-up
     147window the a description of the valid responses using the variously
     148specified help strings. The :abort branch signals an editor-error.
     149
     150The key/value arguments control the prompting.  The following are valid values:
     151
     152 :help::
     153 The default :help case displays this string in a pop-up window.  In
     154 addition it formats a description of the valid input including each
     155 case's help string.
     156
     157 :prompt::
     158 This is the prompt used when reading the key-event.
     159:change-window::
     160 If this is non-nil (the default), then the echo area window becomes
     161 the current window while the prompting mechanism reads a key-event.
     162 Sometimes it is desirable to maintain the current window since it may
     163 be easier for users to answer the question if they can see where the
     164 current point is.
     165
     166 :bind::
     167 This specifies a variable to which the prompting mechanism binds the
     168 input key-event. Any case may reference this variable.  If you wish
     169 to know what character corresponds to the key-event, use
     170 ext:key-event-char.
     171
     172Instead of specifying a tag or list of tags, you may use t. This
     173becomes the default branch, and its forms execute if no other branch
     174is taken, including the default :help and :abort cases. This option has
     175no helpstring, and the default :help case does not describe the default
     176branch.  Every command-case has a default branch; if none is specified,
     177the macro includes one that system:beep's and reprompt's (see below).
     178
     179Within the body of command-case, there is a defined reprompt macro. It
     180causes the prompting mechanism and dispatching mechanism to
     181immediately repeat without further execution in the current branch.
     182
     183prompt-for-key-event &key :prompt :change-window [Function]
     184
     185This function prompts for a key-event returning immediately when the
     186user types the next key-event.  command-case (page 48) is more useful
     187for most purposes. When appropriate, use logical key-events (page 45).
     188
     189prompt-for-key &key :prompt :help :must-exist :default [Function]
     190:default-string
     191
     192This function prompts for akey, a vector of key-events, suitable for
     193passing to any of the functions that manipulate key bindings (page
     19429).  If must-exist is true, then the key must be bound in the current
     195environment, and the command currently bound is returned as the second
     196value.
     197
     198prompt-for-file &key :prompt :help :must-exist :default [Function]
     199:default-string
     200
     201This function prompts for an acceptable filename in some system
     202dependent fashion.  "Acceptable" means that it is a legal filename,
     203and it exists if must-exist is non-nil. prompt-for-file returns a Common
     204Lisp pathname.  If the file exists as entered, then this returns it,
     205otherwise it is merged with default as by merge-pathnames.
     206
     207prompt-for-integer &key :prompt :help :must-exist :default [Function]
     208:default-string
     209
     210This function prompts for a possibly signed integer. If must-exist is
     211nil, then prompt-for-integer returns the input as a string if it is
     212not a valid integer.
     213
     214prompt-for-keywordstring-tables &key :prompt :help :must-exist [Function]
     215:default :default-string
     216
     217This function prompts for a keyword with completion, using the string
     218tables in the list string-tables. If must-exist is non-nil, then the
     219result must be an unambiguous prefix of a string in one of the
     220string-tables, and the returns the complete string even if only a
     221prefix of the full string was typed.  In addition, this returns the
     222value of the corresponding entry in the string table as the second
     223value.
     224
     225If must-exist is nil, then this function returns the string exactly as
     226entered.  The difference between prompt-for-keyword with must-exist
     227nil, and prompt-for-string, is the user may complete the input using
     228the Complete Parse and Complete Field commands.
     229
     230prompt-for-expression &key :prompt :help :must-exist :default [Function]
     231:default-string
     232
     233This function reads a Lisp expression.  If must-exist is nil, and a
     234read error occurs, then this returns the string typed.
     235
     236prompt-for-string &key :prompt :help :default :default-string [Function]
     237
     238This function prompts for a string; this cannot fail.
     239
     240prompt-for-variable &key :prompt :help :must-exist :default [Function]
     241:default-string
     242
     243This function prompts for a variable name.  If must-exist is non-nil,
     244then the string must be a variable defined in the current environment,
     245in which case the symbol name of the variable found is returned as the
     246second value.
     247
     248prompt-for-y-or-n &key :prompt :help :must-exist :default [Function]
     249:default-string
     250
     251This prompts for y, Y, n, or N, returning t or nil without waiting for
     252confirmation.  When the user types a confirmation key, this returns
     253default if it is supplied.  If must-exist is nil, this returns
     254whatever key-event the user first types; however, if the user types
     255one of the above key-events, this returnstor nil. This is analogous to
     256the Common Lisp function y-or-n-p.
     257
     258prompt-for-yes-or-no &key :prompt :help :must-exist :default [Function]
     259:default-string
     260
     261This function is to prompt-for-y-or-n as yes-or-no-p is to
     262y-or-n-p. "Yes" or "No" must be typed out in full and confirmation
     263must be given.
     264
     265== 12.3. Control of Parsing Behavior ==
     266
     267Beep On Ambiguity (initial value t) [Hemlock Variable]
     268
     269If this variable is true, then an attempt to complete a parse which is
     270ambiguous will result in a "beep".
     271
     272== 12.4. Defining New Prompting Functions ==
     273
     274Prompting functions are implemented as a recursive edit in the Echo
     275Area buffer. Completion, help, and other parsing features are
     276implemented by commands which are bound in Echo Area Mode.  A
     277prompting function passes information down into the recursive edit by
     278binding a collection of special variables.
     279
     280*parse-verification-function* [Variable]
     281
     282The system binds this to a function that Confirm Parse (page 52)
     283calls.  It does most of the work when parsing prompted input. Confirm
     284Parse (page 52) passes one argument, which is the string that was in
     285*parse-input-region* when the user invokes the command.  The function
     286should return a list of values which are to be the result of the
     287recursive edit, or nil indicating that the parse failed.  In order to
     288return zero values, a non-nil second value may be returned along with
     289a nil first value.
     290
     291*parse-string-tables* [Variable]
     292
     293This is the list ofstring-tables, if any, that pertain to this parse.
     294
     295*parse-value-must-exist* [Variable]
     296
     297This is bound to the value of the :must-exist argument, and is referred
     298to by the verification function, and possibly some of the commands.
     299
     300*parse-default* [Variable]
     301
     302When prompting the user, this is bound to a string representing the
     303default object, the value supplied as the :default argument. Confirm
     304Parse supplies this to the parse verification function when the
     305*parse-input-region* is empty.
     306
     307*parse-default-string* [Variable]
     308
     309When prompting the user, if *parse-default* is nil, Hemlock displays
     310this string as a representation of the default object; for example,
     311when prompting for a buffer, this variable would be bound to the
     312buffer name.
     313
     314*parse-type* [Variable]
     315
     316The kind of parse in progress, one of :file, :keyword or :string. This
     317tells the completion commands how to do completion, with :string
     318disabling completion.
     319
     320*parse-prompt* [Variable]
     321
     322The prompt being used for the current parse.
     323
     324*parse-help* [Variable]
     325
     326The help string or function being used for the current parse.
     327
     328*parse-starting-mark* [Variable]
     329
     330This variable holds a mark in the *echo-area-buffer* (page 47) which
     331is the position at which the parse began.
     332
     333*parse-input-region* [Variable]
     334
     335This variable holds a region with *parse-starting-mark* as its start
     336and the end of the echo-area buffer as its end.  When Confirm Parse is
     337called, the text in this region is the text that will be parsed.
     338
     339== 12.5. Some Echo Area Commands ==
     340
     341These are some of the Echo Area commands that coordinate with the
     342prompting routines. Hemlock binds other commands specific to the Echo
     343Area, but they are uninteresting to mention here, such as deleting to
     344the beginning of the line or deleting backwards a word.
     345
     346Help On Parse (bound to Home, C-_ in Echo Area mode) [Command]
     347
     348Display the help text for the parse currently in progress.
     349
     350Complete Keyword (bound to Escape in Echo Area mode) [Command]
     351
     352This attempts to complete the current region as a keyword
     353in*string-tables*. It signals an editor-error if the input is
     354ambiguous or incorrect.
     355
     356Complete Field (bound to Space in Echo Area mode) [Command]
     357
     358Similar to Complete Keyword, but only attempts to complete up to and
     359including the first character in the keyword with a non-zero
     360:parse-field-separator attribute. If there is no field separator then
     361attempt to complete the entire keyword.  If it is not a keyword parse
     362then just self-insert.
     363
     364Confirm Parse (bound to Return in Echo Area mode) [Command]
     365
     366If *string-tables* is non-nil find the string in the region in them.
     367Call *parse-verification-function* with the current input.  If it
     368returns a non-nil value then that is returned as the value of the
     369parse.  A parse may return a nil value if the verification function
     370returns a non-nil second value.
     371