Changes between Version 3 and Version 4 of HemlockProgrammer/Buffers


Ignore:
Timestamp:
Jan 14, 2008, 1:36:48 PM (12 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/Buffers

    v3 v4  
     1[HemlockProgrammer Back to Table of Contents]
    12[[PageOutline]]
    23
    34= 3. Buffers =
    45
    5 A buffer is an environment within Hemlock consisting of:
     6A buffer is an object consisting of:
    67 1. A name.
    78 2. A piece of text.
    8  3. A current focus of attention, the point.
     9 3. The insertion point.
    910 4. An associated file (optional).
    1011 5. A write protect flag.
    11  6. Some variables (page 23).
    12  7. Some key bindings (page 29).
    13  8. Some collection of modes (page 35).
    14  9. Some windows in which it is displayed (page 41).
     12 6. Some [HemlockProgrammer/HemlockVariables variables].
     13 7. Some [HemlockProgrammer/Commands key bindings].
     14 8. A collection of [HemlockProgrammer/Modes modes].
    1515 10. A list of modeline fields (optional).
    16  11. An associated NSDocument reference (optional).
    17 
    18 == 3.1. The Current Buffer ==
    19 current-buffer  [Function]
    20 
    21 Set Buffer Hook [Hemlock Variable]
    22 
    23 After Set Buffer Hook [Hemlock Variable]
    24 
    25 current-buffer returns the current buffer object.  Usually this is the
    26 buffer that current-window (page 41) is displaying.  This value may be
    27 changed with setf, and the setf method invokes Set Buffer Hook before
    28 the change occurs with the new value.  After the change occurs, the
    29 method invokes After Set Buffer Hook with the old value.
    30 
    31 current-point [Function]
    32 
    33 This function returns the buffer-poin tof the current buffer . This is
     16
     17Because of the way Hemlock is currently integrated in Cocoa, all modifications
     18to buffer contents must take place in the GUI thread.  Hemlock commands always
     19run in the GUI thread, so most of the time you do not need to worry about it.
     20If you are running code in another thread that needs to modify a buffer, you
     21should perform that action using `gui::execute-in-gui` or `gui::queue-for-gui`.
     22
     23There are no intrinsic limitations on examining buffers from any thread,
     24however, Hemlock currently does no locking, so you risk seeing the buffer
     25in an inconsistent state if you look at it outside the GUI thread.
     26
     27
     28== 3.1. The Current Buffer ==#CurrentBuffer
     29
     30Hemlock has the concept of the "current buffer".  The current buffer
     31is defined during Hemlock commands as the buffer of the hemlock view
     32that received the key events that invoked the command.  Many hemlock
     33function operate on the current buffer rather than taking an explicit
     34buffer argument.  In effect, the current buffer is an implicit argument
     35to many text manipulation functions.
     36
     37`current-buffer`  [Function][[BR]]
     38
     39Returns the current buffer, which, during command execution, is the
     40buffer that is the target of the command.
     41
     42`current-point` [Function]
     43
     44This function returns the buffer-point of the current buffer . This is
    3445such a common idiom in commands that it is defined despite its trivial
    3546implementation.
    3647
    37 current-mark [Function]
    38 
    39 pop-buffer-mark [Function]
    40 push-buffer-mark mark &optional activate-region [Function]
    41 
    42 current-mark returns the top of the current buffer's mark stack.
     48`current-point-collapsing-selection` [Function]
     49
     50This function returns the buffer-point of the current buffer, after first
     51deactivating any active region.
     52
     53`current-point-extending-selection` [Function]
     54
     55This function returns the buffer-point of the current buffer, after first
     56making sure there is an active region - if the region is already active,
     57keeps it active, otherwise it establishes a new (empty) region at point.
     58
     59`current-point-for-insertion` [Function]
     60
     61This function checks to see if the current buffer can be modified at its
     62current point, and errors if not.  Otherwise, it deletes the current
     63selection if any, and returns the current point.
     64
     65
     66`current-point-for-deletion` [Function]
     67
     68This function checks to see if the current buffer can be modified at its
     69current point and errors if not.  Otherwise, if there is a section
     70in the current buffer, it deletes it and returns NIL.  If there is no
     71selection, it returns the current point.
     72
     73`current-point-unless-selection` [Function]
     74
     75This function checks to see if the current buffer can be modified at its
     76current point and errors if not.  Otherwise, if there's a selection in the
     77current buffer, returns NIL.  If there is no selection, it returns the
     78current point.
     79
     80`current-mark` [Function]
     81
     82This function returns the top of the current buffer's mark stack.
    4383There always is at least one mark at the beginning of the buffer's
    4484region, and all marks returned are right-inserting.
    4585
    46 pop-buffer-mark pops the current buffer's mark stack, returning the
     86
     87`pop-buffer-mark` [Function]
     88
     89This function pops the current buffer's mark stack, returning the
    4790mark.  If the stack becomes empty, this pushes a new mark on the stack
    4891pointing to the buffer's start.  This always deactivates the current
    49 region (see section 4.4).
    50 
    51 push-buffer-mark pushes mark into the current buffer's mark stack,
     92region (see [HemlockProgrammer/AlteringAndSearchingText#ActiveRegions Active Regions]).
     93
     94`push-buffer-mark` mark &optional activate-region [Function]
     95
     96This function pushes mark into the current buffer's mark stack,
    5297ensuring that the mark is right-inserting. If mark does not point into
    5398the current buffer, this signals an error.  Optionally, the current
    5499region is made active, but this never deactivates the current region
    55 (see section 4.4). Mark is returned.
    56 
    57 *buffer-list* [Variable]
    58 
    59 This variable holds a list of all the buffer objects made
    60 withmake-buffer .
    61 
    62 *buffer-names* [Variable]
    63 
    64 This variable holds a string-table (page 69) of all the names of the
    65 buffers in *buffer-list*.  The values of the entries are the
    66 corresponding buffer objects.
    67 
    68 *buffer-history* [Variable]
    69 
    70 This is a list of buffer objects ordered from those most recently
    71 selected to those selected farthest in the past. When someone makes a
    72 buffer, an element of Make Buffer Hook adds this buffer to the end of
    73 this list. When someone deletes a buffer, an element of Delete Buffer
    74 Hook removes the buffer from this list. Each buffer occurs in this
    75 list exactly once, but it never contains the *echo-area-buffer*.
    76 
    77 change-to-buffer  buffer  [Function]
    78 
    79 This switches to buffer in the current-window maintaining buffer-history.
    80 
    81 previous-buffer   [Function]
    82 
    83 This returns the first buffer from *buffer-history* that is not the
    84 current-buffer. If none can be found, then this returns nil.
    85 
    86 == 3.2. Buffer  Functions ==
    87 make-buffer  name &key :modes :modeline-fields :delete-hook [Function]
    88 
    89 Make Buffer  Hook [Hemlock Variable]
    90 
    91 Default Modeline Fields [Hemlock Variable]
    92 
    93 make-buffer creates and returns a buffer with the givenname. If a
     100(see [HemlockProgrammer/AlteringAndSearchingText#ActiveRegions Active Regions]).
     101Mark is returned.
     102
     103`push-new-buffer-mark` mark &optional activate-region [Function]
     104
     105This function pushes a new mark onto the mark stack, at the position of `mark`.
     106It's equivalent to calling `push-buffer-mark` on `(copy-mark mark)`.
     107
     108`all-buffers` [Function]
     109
     110This function returns a list of all the buffer objects made with make-buffer.
     111
     112`*buffer-names*` [Variable]
     113
     114This variable holds a [HemlockProgrammer/Utilities#StringTables string-table]
     115mapping the name of a buffer to the corresponding buffer object.
     116
     117== 3.2. Buffer  Functions ==#BufferFunctions
     118`make-buffer`  name &key :modes :modeline-fields :delete-hook [Function]
     119
     120`Default Modes` [Hemlock Variable][[BR]]
     121`Default Modeline Fields` [Hemlock Variable][[BR]]
     122`Make Buffer Hook` [Hemlock Variable][[BR]]
     123
     124make-buffer creates and returns a buffer with the given name. If a
    94125buffer named name already exists, nil is returned. Modes is a list of
    95126modes which should be in effect in the buffer, major mode first,
     
    102133
    103134Buffers created with make-buffer are entered into the list
    104 *buffer-list*, and their names are inserted into the string-table
     135(all-buffers), and their names are inserted into the string-table
    105136*buffer-names*. When a buffer is created the hook Make Buffer Hook is
    106137invoked with the new buffer.
    107138
    108 bufferp buffer  [Function]
     139`bufferp` buffer  [Function]
    109140
    110141Returns t if buffer is a buffer object, otherwise nil.
    111142
    112 buffer-name buffer  [Function]
    113 
    114 Buffer Name Hook [Hemlock Variable]
    115 
    116 buffer-name returns the name, which is a string, of the given buffer
    117 . The corresponding setf method invokes Buffer Name Hook with buffer
     143`buffer-name` buffer  [Function][[BR]]
     144Buffer Name Hook [Hemlock Variable][[BR]]
     145
     146buffer-name returns the name, which is a string, of the given buffer.
     147The corresponding setf method invokes Buffer Name Hook with buffer
    118148and the new name and then sets the buffer's name.  When the user
    119149supplies a name for which a buffer already exists, the setf method
    120150signals an error.
    121151
    122 buffer-region buffer  [Function]
    123 
    124 Returns the buffer's region.  This can be set with setf. Note, this
    125 returns the region that contains all the text in a buffer , not the
    126 current-region (page 19).
    127 
    128 buffer-pathname buffer  [Function]
    129 
    130 Buffer  Pathname Hook [Hemlock Variable]
     152`buffer-region` buffer  [Function]
     153
     154Returns the buffer's region.  Note this is the region that contains all
     155the text in a buffer, not the current-region (page 19).
     156
     157This can be set with setf to replace the buffer's text.
     158
     159`buffer-pathname` buffer  [Function][[BR]]
     160`Buffer Pathname Hook` [Hemlock Variable][[BR]]
    131161
    132162buffer-pathname returns the pathname of the file associated with the
     
    137167buffer and new value.
    138168
    139 buffer-write-date buffer  [Function]
     169`buffer-write-date` buffer  [Function]
    140170
    141171Returns the write date for the file associated with the buffer in
     
    144174unknown or there is no file.
    145175
    146 buffer-point buffer  [Function]
     176`buffer-point` buffer  [Function]
    147177
    148178Returns the mark which is the current location within buffer. To move
    149 the point, use move-mark or move-to-position (page 5) rather than
    150 setting buffer-point with setf.
    151 
    152 buffer-mark buffer  [Function]
     179the point, use move-mark or move-to-position (page 5).
     180
     181`buffer-mark` buffer  [Function]
    153182
    154183This function returns the top of buffer's mark stack.  There always is
     
    156185returned are right-inserting.
    157186
    158 buffer-start-mark buffer  [Function]
    159 
    160 buffer-end-mark buffer  [Function]
     187`buffer-start-mark` buffer  [Function]
     188
     189`buffer-end-mark` buffer  [Function]
    161190
    162191These functions return the start and end marks of buffer's region:
    163192{{{
    164 (buffer-start-mark buffer )  <==>
    165   (region-start (buffer-region buffer))
     193(buffer-start-mark buffer )  <==>  (region-start (buffer-region buffer))
    166194}}}
    167195and
    168196{{{
    169 (buffer-end-mark buffer )  <==>
    170   (region-end (buffer-region buffer))
     197(buffer-end-mark buffer )  <==>  (region-end (buffer-region buffer))
    171198}}}
    172199
    173 buffer-writable buffer  [Function]
    174 
    175 Buffer Writable Hook [Hemlock Variable]
     200`buffer-writable` buffer  [Function][[BR]]
     201`Buffer Writable Hook` [Hemlock Variable][[BR]]
    176202
    177203This function returns t if you can modify the buffer, nil if you
     
    179205in the buffer results in an error.  There is a setf method to change
    180206this value.  The setf method invokes the functions in Buffer Writable
    181 Hookon the buffer and new value before storing the new value.
    182 
    183 buffer-modified buffer  [Function]
    184 
    185 Buffer Modified Hook [Hemlock Variable]
    186 
    187 buffer-modified returns t if thebuffer has been modified, nil if it
     207Hook on the buffer and new value before storing the new value.
     208
     209`buffer-modified` buffer  [Function][[BR]]
     210`Buffer Modified Hook` [Hemlock Variable][[BR]]
     211
     212buffer-modified returns t if the buffer has been modified, nil if it
    188213hasn't.  This attribute is set whenever a text-altering operation is
    189214performed on a buffer.  There is a setf method to change this value.
    190 The setf method invokes the functions in Buffer Modified Hookwith the
     215The setf method invokes the functions in Buffer Modified Hook with the
    191216buffer whenever the value of the modified flag changes.
    192217
    193 with-writable-buffer   (buffer ) &restforms [Macro]
     218`with-writable-buffer` (buffer) &body body [Macro]
    194219
    195220This macro executes forms with buffer's writable status set.  After
    196221forms execute, this resets the buffer's writable and modified status.
    197222
    198 buffer-signature buffer  [Function]
     223`buffer-signature` buffer  [Function]
    199224
    200225This function returns an arbitrary number which reflects the buffer's
     
    202227the buffer has not been modified between the calls.
    203228
    204 buffer-variables buffer  [Function]
     229`buffer-variables` buffer  [Function]
    205230
    206231This function returns a string-table (page 69) containing the names of
    207232the buffer's local variables.  See chapter 6.
    208233
    209 buffer-modes buffer  [Function]
     234`buffer-modes` buffer  [Function]
    210235
    211236This function returns the list of the names of the modes active in
     
    213238chapter 8.
    214239
    215 buffer-windows buffer  [Function]
    216 
    217 This function returns the list of all the windows in which the buffer  may be displayed.  This list may
    218 include windows which are not currently visible.  See page 41 for a discussion of windows.
    219 
    220 buffer-delete-hook buffer  [Function]
     240`buffer-delete-hook` buffer  [Function]
    221241
    222242This function returns the list of buffer specific functions
    223243delete-buffer invokes when deleting a buffer . This is setf-able.
    224244
    225 delete-buffer  buffer  [Function]
    226 
    227 Delete Buffer  Hook [Hemlock Variable]
    228 
    229 delete-buffer removes buffer from *buffer-list* (page 10) and its name
     245`delete-buffer`  buffer  [Function][[BR]]
     246`Delete Buffer Hook` [Hemlock Variable][[BR]]
     247
     248delete-buffer removes buffer from (all-buffers) (page 10) and its name
    230249from *buffer-names* (page 10).  Before buffer is deleted, this invokes
    231250the functions on buffer returned by buffer-delete-hook and those found
    232251in Delete Buffer Hook. If buffer is the current-buffer, or if it is
    233 displayed in any windows, then this function signals an error.
    234 
    235 delete-buffer-if-possible buffer [Function] This uses delete-buffer to
    236 delete buffer if at all possible.  If buffer is the current-buffer,
    237 then this sets the current-buffer to the first distinct buffer in
    238 buffer-history. If buffer is displayed in any windows, then this makes
    239 each window display the same distinct buffer .
    240 
    241 buffer-document buffer [Function]
    242 
    243 This function returns the NSDocument instance associated with the buffer.  If
    244 the buffer isn't associated with an NSDocument instance, it returns nil.
    245 
    246 == 3.3. Modelines ==
     252displayed in any view, then this function signals an error.
     253
     254
     255== 3.3. Modelines ==#Modelines
    247256
    248257A Buffer may specify a modeline, a line of text which is displayed
    249 across the bottom of a window to indicate status information.
    250 Modelines are described as a list of modeline-field objects which have
     258across the bottom of a view to indicate status information.
     259Modelines are described by a list of modeline-field objects which have
    251260individual update functions and are optionally fixed-width. These have
    252261an eql name for convenience in referencing and updating, but the name
    253 must be unique for all created modeline-field objects.  When creating
     262must be unique for all created modeline-field objects.  All modeline-field
     263functions must take a buffer as an
     264argument and return a string.  When displaying
    254265a modeline-field with a specified width, the result of the update
    255266function is either truncated or padded on the right to meet the
    256 constraint.  All modeline-field functions must return simple strings
    257 with standard characters, and these take a buffer and a window as
    258 arguments. Modeline-field objects are typically shared amongst, or
    259 aliased by, different buffers' modeline fields lists. These lists are
    260 unique allowing fields to behave the same wherever they occur, but
    261 different buffers may display these fields in different arrangements.
     267constraint.
    262268
    263269Whenever one of the following changes occurs, all of a buffer's
     
    269275 * A buffer's pathname changes.
    270276 * A buffer's modified status changes.
    271  * A window's buffer  is changed.
    272277
    273278The policy is that whenever one of these changes occurs, it is
     
    276281modeline-field objects the user has added whose update functions rely
    277282on these values, or how he has changed Default Modeline Fields, we must
    278 update all the fields.  When any but the last occurs, the
    279 modeline-field update function is invoked once for each window into
    280 the buffer .  When a window's buffer changes, each modeline-field
    281 update function is invoked once; other windows' modeline fields should
    282 not be affected due to a given window's buffer changing.
     283update all the fields. 
    283284
    284285The user should note that modelines can be updated at any time, so
     
    286287example, waiting for a local area network to determine information).
    287288
    288 make-modeline-field &key :name :width :function [Function]
    289 
    290 modeline-field-p modeline-field [Function]
    291 
    292 modeline-field-name modeline-field [Function]
    293 
    294 make-modeline-field returns a modeline-field object with name, width,
     289`make-modeline-field` &key :name :width :function [Function]
     290
     291This function returns a modeline-field object with name, width,
    295292and function. Width defaults to nil meaning that the field is variable
    296293width; otherwise, the programmer must supply this as a positive
    297 integer. Function must take a buffer and window as arguments and
    298 return a simple-string containing only standard characters.  If name
    299 already names a modeline-field object, then this signals an error.
    300 
    301 modeline-field-name returns the name field of a modeline-field object.
     294integer. Function must take a buffer as an arguments and
     295return a string.  If name already names a modeline-field object,
     296then this signals an error.
     297
     298`modeline-field-name` modeline-field [Function]
     299
     300This function returns the name field of a modeline-field object.
    302301If this is set with setf, and the new name already names a
    303302modeline-field, then the setf method signals an error.
    304303
    305 modeline-field-p returns t or nil, depending on whether its argument
    306 is a modeline-field object.
    307 
    308 modeline-field name [Function]
     304`modeline-field-p` modeline-field [Function]
     305
     306This function returns t if its argument is a modeline-field object, nil
     307otherwise.
     308
     309`modeline-field` name [Function]
    309310
    310311This returns the modeline-field object named name. If none exists, this
    311312returns nil.
    312313
    313 modeline-field-function modeline-field [Function]
     314`modeline-field-function` modeline-field [Function]
    314315
    315316Returns the function called when updating the modeline-field. When this
    316 is set with setf, the setf method updates modeline-field for all windows
     317is set with setf, the setf method updates modeline-field for all views
    317318on all buffers that contain the given field, so the next trip through
    318319redisplay will reflect the change.  All modeline-field functions must
    319 return simple strings with standard characters, and they take a buffer
    320 and a window as arguments.
    321 
    322 modeline-field-width modeline-field [Function]
     320take a buffer as an argument and return a string.
     321
     322`modeline-field-width` modeline-field [Function]
    323323
    324324Returns the width to which modeline-field is constrained, or nil
    325325indicating that it is variable width.  When this is set with setf, the
    326 setf method updates all modeline-fields for all windows on all buffers
     326setf method updates all modeline-fields for all views on all buffers
    327327that contain the given field, so the next trip through redisplay will
    328 reflect the change.  All the fields for any such modeline display must
    329 be updated, which is not the case when setting a modeline-field's
    330 function.
    331 
    332 buffer-modeline-fields buffer  [Function]
     328reflect the change.
     329
     330`buffer-modeline-fields` buffer  [Function]
    333331
    334332Returns a copy of the list of buffer's modeline-field objects. This
     
    337335(for example, width or function) causes the changes to be reflected
    338336the next trip through redisplay in every modeline display that uses
    339 the modified modeline-field.  When this is set with setf,
    340 update-modeline-fields is called for each window into buffer .
    341 
    342 buffer-modeline-field-pbuffer  field [Function]
     337the modified modeline-field.  When this is set with setf, the setf
     338method method updates all modeline-fields on all views on the buffer,
     339so next trip through the redisplay will reflect the change.
     340
     341`buffer-modeline-field-p` buffer field [Function]
    343342
    344343If field, a modeline-field or the name of one, is in buffer's list of
    345344modeline-field objects, it is returned; otherwise, this returns nil.
    346345
    347 update-modeline-fields buffer window [Function]
    348 
    349 This invokes each modeline-field object's function from buffer's list,
    350 passing buffer and window. The results are collected regarding each
    351 modeline-field object's width as appropriate, and the window is marked
    352 so the next trip through redisplay will reflect the changes. If window
    353 does not display modelines, then no computation occurs.
    354 
    355 update-modeline-field buffer window field-or-name [Function]
    356 
    357 This invokes the modeline-field object's function for field-or-name,
    358 which is a modeline-field object or the name of one for buffer . This
    359 passes buffer and window to the update function.  The result is
    360 applied to the window's modeline display using the modeline-field
    361 object's width, and the window is marked so the next trip through
    362 redisplay will reflect the changes.  If the window does not display
    363 modelines, then no computation occurs.  If field-or-name is not found
    364 in buffer's list of modeline-field objects, then this signals an
    365 error.  See buffer-modeline-field-p above.
    366 
     346`update-modeline-fields` buffer [Function]
     347
     348Arranges so that the modeline display is updated with the latest values
     349at the end of current command.
     350
     351
     352[HemlockProgrammer Back to Table of Contents]