Changes between Version 1 and Version 2 of HemlockProgrammer/TheEchoArea


Ignore:
Timestamp:
Jan 15, 2008, 5:30:00 PM (13 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/TheEchoArea

    v1 v2  
     1[HemlockProgrammer Back to Table of Contents]
    12[[PageOutline]]
    23
    3 = 12. The Echo Area =
     4= 12. The Echo Area =#EchoArea
    45
    56Hemlock provides a number of facilities for displaying information and
    6 prompting the user for it.  Most of these work through a small window
    7 displayed at the bottom of the screen.  This is called the echo area
    8 and 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
    10 other buffers' modelines, is used to show general status about the
    11 editor, Lisp, or world.
    12 
    13 Default Status Line Fields [Hemlock Variable]
    14 
    15 This is the initial list of modeline-field objects stored in the echo
    16 area buffer.
    17 
    18 Echo Area Height (initial value 3) [Hemlock Variable]
    19 This variable determines the initial height in lines of the echo area window.
    20 
    21 == 12.1. Echo Area Functions ==
    22 
    23 It is considered poor taste to perform text operations on the echo
    24 area buffer to display messages; the message function should be used
    25 instead. A command must use this function or set buffer-modified (page
    26 12) for the Echo Area buffer to nil to cause Hemlock to leave text in the
    27 echo area after the command's execution.
    28 
    29 clear-echo-area [Function]
     7prompting the user for it.  Most of these work through a small area
     8displayed at the bottom of the screen, called the Echo Area.
     9
     10== 12.1. Echo Area Functions ==#EchoAreaFunctions
     11
     12`clear-echo-area` [Function]
    3013
    3114Clears the echo area.
    3215
    33 message control-string &rest format-arguments [Function]
    34 
    35 loud-message control-string &rest format-arguments [Function]
    36 
    37 Message Pause (initial value 0.5) [Hemlock Variable]
    38 
    39 Displays a message in the echo area.  The message is always displayed
    40 on a fresh line. message pauses for Message Pause seconds before
    41 returning to assure that messages are not displayed too briefly to be
    42 seen. Because of this, message is the best way to display text in the
    43 echo area.  loud-message is like message, but it first clears the echo
    44 area and beeps.
    45 
    46 *echo-area-window* [Variable]
    47 
    48 *echo-area-buffer* [Variable]
    49 
    50 echo-area-buffer contains the buffer object for the echo area, which
    51 is named Echo Area. This buffer is usually in Echo Area
    52 mode. echo-area-window contains a window displaying
    53 echo-area-buffer. Its modeline is the status line, see the beginning
    54 of this chapter.
    55 
    56 *echo-area-stream* [Variable]
    57 
    58 This is a buffered Hemlock output stream (59) which inserts text
    59 written to it at the point of the echo area buffer. Since this stream
    60 is buffered a force-output must be done when output is complete to
    61 assure that it is displayed.
    62 
    63 == 12.2. Prompting Functions ==
     16`message` control-string &rest format-arguments [Function][[BR]]
     17`loud-message` control-string &rest format-arguments [Function][[BR]]
     18
     19Displays a message in the echo area, replacing previous contents if any.
     20loud-message is like message, but it also beeps.
     21
     22== 12.2. Prompting Functions ==#PromptingFunctions
     23
     24Prompting functions can be used to obtain short one-line input from the user.
     25
     26Cocoa note: Because of implementation restrictions, only one buffer at
     27a time is allowed to read prompted input.  If a prompting function is
     28invoked while a prompting operation is already in effect in another
     29buffer, the attempt fails, telling the user "Buffer xxx is already
     30waiting for input".
    6431
    6532Most of the prompting functions accept the following keyword arguments:
    6633
    6734 :must-exist::
    68  If :must-exist has a non-nilvalue then the user is
     35 If :must-exist has a non-nil value then the user is
    6936 prompted until a valid response is obtained. If :must-exist is nil
    7037 then return as a string whatever is input.  The default is t.
     
    8552
    8653 :help::
    87  This is similar to:prompt, except that it is displayed when the help
     54 This is similar to :prompt, except that it is displayed when the help
    8855 command is typed during input.
    8956
     
    9259 action to help the user, returning nil.
    9360
    94 prompt-for-buffer &key :prompt :help :must-exist :default [Function]
    95 :default-string
     61`prompt-for-buffer` &key :prompt :help :must-exist :default :default-string [Function]
    9662
    9763Prompts with completion for a buffer name and returns the
     
    10369already existing buffer.
    10470
    105 command-case ({key value}*){({({tag}*) | tag} help {form}*)}* [Macro]
     71`prompt-for-key-event` &key :prompt :help [Function]
     72
     73This function prompts for a key-event returning immediately when the
     74user types the next key-event.  command-case (page 48) is more useful
     75for most purposes. When appropriate, use logical key-events (page 45).
     76
     77`prompt-for-key` &key :prompt :help :must-exist :default :default-string [Function]
     78
     79This function prompts for a key, a vector of key-events, suitable for
     80passing to any of the functions that manipulate key bindings (page
     8129).  If must-exist is true, then the key must be bound in the current
     82environment, and the command currently bound is returned as the second
     83value.
     84
     85`prompt-for-file` &key :prompt :help :must-exist :default :default-string [Function]
     86
     87This function prompts for an acceptable filename.  "Acceptable" means
     88that it is a legal filename, and it exists if must-exist is
     89non-nil. prompt-for-file returns a Common Lisp pathname.  If the file
     90exists as entered, then this returns it, otherwise it is merged with
     91default as by merge-pathnames.
     92
     93`prompt-for-integer` &key :prompt :help :must-exist :default :default-string [Function]
     94
     95This function prompts for a possibly signed integer. If must-exist is
     96nil, then prompt-for-integer returns the input as a string if it is
     97not a valid integer.
     98
     99`prompt-for-keyword` string-tables &key :prompt :help :must-exist :default :default-string [Function]
     100
     101This function prompts for a keyword with completion, using the string
     102tables in the list string-tables. If must-exist is non-nil, then the
     103result must be an unambiguous prefix of a string in one of the
     104string-tables, and the returns the complete string even if only a
     105prefix of the full string was typed.  In addition, this returns the
     106value of the corresponding entry in the string table as the second
     107value.
     108
     109If must-exist is nil, then this function returns the string exactly as
     110entered.  The difference between prompt-for-keyword with must-exist
     111nil, and prompt-for-string, is the user may complete the input using
     112the Complete Parse and Complete Field commands.
     113
     114`prompt-for-expression` &key :prompt :help :must-exist :default :default-string [Function]
     115
     116This function reads a Lisp expression.  If must-exist is nil, and a
     117read error occurs, then this returns the string typed.
     118
     119`prompt-for-string` &key :prompt :help :default :default-string [Function]
     120
     121This function prompts for a string; this cannot fail.
     122
     123`prompt-for-variable` &key :prompt :help :must-exist :default :default-string [Function]
     124
     125This function prompts for a variable name.  If must-exist is non-nil,
     126then the string must be a variable defined in the current environment,
     127in which case the symbol name of the variable found is returned as the
     128second value.
     129
     130`prompt-for-y-or-n` &key :prompt :help :must-exist :default :default-string [Function]
     131
     132This prompts for logical key events :Y or :N, returning t or nil without waiting for
     133confirmation.  When the user types a confirmation key, this returns
     134default if it is supplied.  If must-exist is nil, this returns
     135whatever key-event the user first types; however, if the user types
     136one of the above key-events, this returns t or nil. This is analogous to
     137the Common Lisp function y-or-n-p.
     138
     139`prompt-for-yes-or-no` &key :prompt :help :must-exist :default :default-string [Function]
     140
     141This function is to prompt-for-y-or-n as yes-or-no-p is to
     142y-or-n-p. "Yes" or "No" must be typed out in full and confirmation
     143must be given.
     144
     145`command-case` ({key value}*){({({tag}*) | tag} help {form}*)}* [Macro]
    106146
    107147This macro is analogous to the Common Lisp case macro. Commands such
    108 as Query Replace use this to get a key-event, translate it to a
     148as Help use this to get a key-event, translate it to a
    109149character, and then to dispatch on the character to some case.  In
    110150addition to character dispatching, this supports logical key-events
     
    114154{{{
    115155(defcommand "Save All Buffers" (p)
    116   "Give the User a chance to save each modified buffer."
    117156  "Give the User a chance to save each modified buffer."
    118157  (dolist (b *buffer-list*)
     
    125164         (save-file-command () b))
    126165        (: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))
    130166        ((:exit #\p) "Punt this silly loop."
    131167         (return nil))))))
     
    157193 :prompt::
    158194 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.
    165195
    166196 :bind::
     
    168198 input key-event. Any case may reference this variable.  If you wish
    169199 to know what character corresponds to the key-event, use
    170  ext:key-event-char.
     200 key-event-char.
    171201
    172202Instead of specifying a tag or list of tags, you may use t. This
     
    175205no helpstring, and the default :help case does not describe the default
    176206branch.  Every command-case has a default branch; if none is specified,
    177 the macro includes one that system:beep's and reprompt's (see below).
     207the macro includes one that beep's and reprompt's (see below).
    178208
    179209Within the body of command-case, there is a defined reprompt macro. It
     
    181211immediately repeat without further execution in the current branch.
    182212
    183 prompt-for-key-event &key :prompt :change-window [Function]
    184 
    185 This function prompts for a key-event returning immediately when the
    186 user types the next key-event.  command-case (page 48) is more useful
    187 for most purposes. When appropriate, use logical key-events (page 45).
    188 
    189 prompt-for-key &key :prompt :help :must-exist :default [Function]
    190 :default-string
    191 
    192 This function prompts for akey, a vector of key-events, suitable for
    193 passing to any of the functions that manipulate key bindings (page
    194 29).  If must-exist is true, then the key must be bound in the current
    195 environment, and the command currently bound is returned as the second
    196 value.
    197 
    198 prompt-for-file &key :prompt :help :must-exist :default [Function]
    199 :default-string
    200 
    201 This function prompts for an acceptable filename in some system
    202 dependent fashion.  "Acceptable" means that it is a legal filename,
    203 and it exists if must-exist is non-nil. prompt-for-file returns a Common
    204 Lisp pathname.  If the file exists as entered, then this returns it,
    205 otherwise it is merged with default as by merge-pathnames.
    206 
    207 prompt-for-integer &key :prompt :help :must-exist :default [Function]
    208 :default-string
    209 
    210 This function prompts for a possibly signed integer. If must-exist is
    211 nil, then prompt-for-integer returns the input as a string if it is
    212 not a valid integer.
    213 
    214 prompt-for-keywordstring-tables &key :prompt :help :must-exist [Function]
    215 :default :default-string
    216 
    217 This function prompts for a keyword with completion, using the string
    218 tables in the list string-tables. If must-exist is non-nil, then the
    219 result must be an unambiguous prefix of a string in one of the
    220 string-tables, and the returns the complete string even if only a
    221 prefix of the full string was typed.  In addition, this returns the
    222 value of the corresponding entry in the string table as the second
    223 value.
    224 
    225 If must-exist is nil, then this function returns the string exactly as
    226 entered.  The difference between prompt-for-keyword with must-exist
    227 nil, and prompt-for-string, is the user may complete the input using
    228 the Complete Parse and Complete Field commands.
    229 
    230 prompt-for-expression &key :prompt :help :must-exist :default [Function]
    231 :default-string
    232 
    233 This function reads a Lisp expression.  If must-exist is nil, and a
    234 read error occurs, then this returns the string typed.
    235 
    236 prompt-for-string &key :prompt :help :default :default-string [Function]
    237 
    238 This function prompts for a string; this cannot fail.
    239 
    240 prompt-for-variable &key :prompt :help :must-exist :default [Function]
    241 :default-string
    242 
    243 This function prompts for a variable name.  If must-exist is non-nil,
    244 then the string must be a variable defined in the current environment,
    245 in which case the symbol name of the variable found is returned as the
    246 second value.
    247 
    248 prompt-for-y-or-n &key :prompt :help :must-exist :default [Function]
    249 :default-string
    250 
    251 This prompts for y, Y, n, or N, returning t or nil without waiting for
    252 confirmation.  When the user types a confirmation key, this returns
    253 default if it is supplied.  If must-exist is nil, this returns
    254 whatever key-event the user first types; however, if the user types
    255 one of the above key-events, this returnstor nil. This is analogous to
    256 the Common Lisp function y-or-n-p.
    257 
    258 prompt-for-yes-or-no &key :prompt :help :must-exist :default [Function]
    259 :default-string
    260 
    261 This function is to prompt-for-y-or-n as yes-or-no-p is to
    262 y-or-n-p. "Yes" or "No" must be typed out in full and confirmation
    263 must be given.
    264 
    265 == 12.3. Control of Parsing Behavior ==
    266 
    267 Beep On Ambiguity (initial value t) [Hemlock Variable]
     213
     214== 12.3. Control of Parsing Behavior ==#ControlOfParsingBehavior
     215
     216`Beep On Ambiguity` (initial value t) [Hemlock Variable]
    268217
    269218If this variable is true, then an attempt to complete a parse which is
    270219ambiguous will result in a "beep".
    271220
    272 == 12.4. Defining New Prompting Functions ==
    273 
    274 Prompting functions are implemented as a recursive edit in the Echo
    275 Area buffer. Completion, help, and other parsing features are
    276 implemented by commands which are bound in Echo Area Mode.  A
    277 prompting function passes information down into the recursive edit by
    278 binding a collection of special variables.
    279 
    280 *parse-verification-function* [Variable]
    281 
    282 The system binds this to a function that Confirm Parse (page 52)
    283 calls.  It does most of the work when parsing prompted input. Confirm
    284 Parse (page 52) passes one argument, which is the string that was in
    285 *parse-input-region* when the user invokes the command.  The function
    286 should return a list of values which are to be the result of the
    287 recursive edit, or nil indicating that the parse failed.  In order to
    288 return zero values, a non-nil second value may be returned along with
    289 a nil first value.
    290 
    291 *parse-string-tables* [Variable]
    292 
    293 This is the list ofstring-tables, if any, that pertain to this parse.
    294 
    295 *parse-value-must-exist* [Variable]
    296 
    297 This is bound to the value of the :must-exist argument, and is referred
    298 to by the verification function, and possibly some of the commands.
    299 
    300 *parse-default* [Variable]
    301 
    302 When prompting the user, this is bound to a string representing the
    303 default object, the value supplied as the :default argument. Confirm
    304 Parse supplies this to the parse verification function when the
    305 *parse-input-region* is empty.
    306 
    307 *parse-default-string* [Variable]
    308 
    309 When prompting the user, if *parse-default* is nil, Hemlock displays
    310 this string as a representation of the default object; for example,
    311 when prompting for a buffer, this variable would be bound to the
    312 buffer name.
    313 
    314 *parse-type* [Variable]
    315 
    316 The kind of parse in progress, one of :file, :keyword or :string. This
    317 tells the completion commands how to do completion, with :string
    318 disabling completion.
    319 
    320 *parse-prompt* [Variable]
    321 
    322 The prompt being used for the current parse.
    323 
    324 *parse-help* [Variable]
    325 
    326 The help string or function being used for the current parse.
    327 
    328 *parse-starting-mark* [Variable]
    329 
    330 This variable holds a mark in the *echo-area-buffer* (page 47) which
    331 is the position at which the parse began.
    332 
    333 *parse-input-region* [Variable]
    334 
    335 This variable holds a region with *parse-starting-mark* as its start
    336 and the end of the echo-area buffer as its end.  When Confirm Parse is
    337 called, the text in this region is the text that will be parsed.
    338 
    339 == 12.5. Some Echo Area Commands ==
     221== 12.4. Defining New Prompting Functions ==#DefiningNewPromptingFunctions
     222
     223Prompting functionality is implemented by the function parse-for-something
     224in cooperation with commands defined in "Echo Area" mode on the buffer associated
     225with the echo area. You can implement new prompting functions by invoking
     226parse-for-something with appropriate arguments.
     227
     228`parse-for-something` &key [Function]
     229
     230This function enters a mode reading input from the user and echoing it in the echo area, and
     231returns a value when done.  The input is managed by commands bound in "Echo Area" mode on the
     232buffer associated with the echo area.  The following  keyword arguments are accepted:
     233
     234 `:verification-function`::
     235  This is invoked by the Confirm Parse command (page 52).  It does most of
     236  the work when parsing prompted input. Confirm Parse (page 52) calls it
     237  with one argument, which is the string that the user typed so far.
     238  The function should return a list of values which are to be the result
     239  of the recursive edit, or nil indicating that the parse failed.  In order
     240  to return zero values, a non-nil second value may be returned along with
     241  a nil first value.
     242
     243 `:string-tables`::
     244  This is the list of string-tables, if any, that pertain to this parse.
     245
     246 `:value-must-exist`::
     247  This is referred to by the verification function, and possibly some of the
     248  commands.
     249
     250 `:default`::
     251  The string representing the default object when prompting the user.
     252  Confirm Parse supplies this to the parse verification function when the
     253  user input is empty.
     254
     255 `:default-string`::
     256  When prompting the user, if :default is not specified, Hemlock displays
     257  this string as a representation of the default object; for example,
     258  when prompting for a buffer, this argument would be a default buffer name.
     259
     260 `:type`::
     261  The kind of parse, e.g. :file, :keyword, :string. This tells the completion
     262  commands how to do completion, with :string disabling completion.
     263
     264 `:prompt`::
     265  The prompt to display to the user.
     266
     267 `:help`::
     268  The help string or function being used for the current parse.
     269
     270== 12.5. Some Echo Area Commands ==#SomeEchoAreaCommands
    340271
    341272These are some of the Echo Area commands that coordinate with the
     
    344275the beginning of the line or deleting backwards a word.
    345276
    346 Help On Parse (bound to Home, C-_ in Echo Area mode) [Command]
     277`Help On Parse` (bound to Home, C-_ in Echo Area mode) [Command]
    347278
    348279Display the help text for the parse currently in progress.
    349280
    350 Complete Keyword (bound to Escape in Echo Area mode) [Command]
    351 
    352 This attempts to complete the current region as a keyword
    353 in*string-tables*. It signals an editor-error if the input is
    354 ambiguous or incorrect.
    355 
    356 Complete Field (bound to Space in Echo Area mode) [Command]
    357 
    358 Similar to Complete Keyword, but only attempts to complete up to and
     281`Complete Keyword` (bound to Escape in Echo Area mode) [Command]
     282
     283This attempts to complete the current region.
     284It signals an editor-error if the input is ambiguous or incorrect.
     285
     286`Complete Field` (bound to Space in Echo Area mode) [Command]
     287
     288Similar to `Complete Keyword`, but only attempts to complete up to and
    359289including the first character in the keyword with a non-zero
    360290:parse-field-separator attribute. If there is no field separator then
     
    362292then just self-insert.
    363293
    364 Confirm Parse (bound to Return in Echo Area mode) [Command]
    365 
    366 If *string-tables* is non-nil find the string in the region in them.
    367 Call *parse-verification-function* with the current input.  If it
     294`Confirm Parse` (bound to Return in Echo Area mode) [Command]
     295
     296Call the verification function with the current input.  If it
    368297returns a non-nil value then that is returned as the value of the
    369298parse.  A parse may return a nil value if the verification function
    370299returns a non-nil second value.
    371300
     301
     302[HemlockProgrammer Back to Table of Contents]