Changes between Version 2 and Version 3 of HemlockProgrammer/AlteringAndSearchingText


Ignore:
Timestamp:
Jan 14, 2008, 6:19:34 PM (12 years ago)
Author:
gz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • HemlockProgrammer/AlteringAndSearchingText

    v2 v3  
     1[HemlockProgrammer Back to Table of Contents]
    12[[PageOutline]]
    23
    34= 4. Altering and Searching Text =
    45
    5 == 4.1. Altering Text ==
    6 
    76A note on marks and text alteration: :temporary marks are invalid
    8 after any change has been made to the text the mark points to; it is
     7after any change has been made to the buffer the mark points to; it is
    98an error to use a temporary mark after such a change has been made.
     9
    1010If text is deleted which has permanent marks pointing into it then
    1111they are left pointing to the position where the text was.
    1212
    13 insert-character mark character [Function]
    14 
    15 insert-string mark string [Function]
    16 
    17 insert-region mark region [Function]
    18 
    19 Inserts character, string or region at mark. insert-character signals
    20 an error if character is not string-char-p. If string or region is
     13
     14== 4.1. Altering Text ==#AlteringText
     15
     16`insert-character` mark character [Function]
     17
     18`insert-string` mark string [Function]
     19
     20`insert-region` mark region [Function]
     21
     22Inserts character, string or region at mark. `insert-character` signals
     23an error if character is not `string-char-p`. If string or region is
    2124empty, and mark is in some buffer, then Hemlock leaves buffer-modified of
    22 marks buffer unaffected.
    23 
    24 ninsert-region mark region [Function]
    25 
    26 Like insert-region, inserts the region at the mark’s position,
     25mark's buffer unaffected.
     26
     27`ninsert-region` mark region [Function]
     28
     29Like `insert-region`, inserts the region at the mark's position,
    2730destroying the source region.  This must be used with caution, since
    2831if anyone else can refer to the source region bad things will
    2932happen. In particular, one should make sure the region is not linked
    3033into any existing buffer.  If region is empty, and mark is in some
    31 buffer, then Hemlock leaves buffer-modified of marks buffer unaffected.
    32 
    33 delete-characters mark n [Function]
     34buffer, then Hemlock leaves buffer-modified of mark's buffer unaffected.
     35
     36`delete-characters` mark n [Function]
    3437
    3538This deletes n characters after the mark (or -n before if n is
     
    3740exist, then this returns nil; otherwise, it returns t. If n is zero,
    3841and mark is in some buffer, then Hemlock leaves buffer-modified of
    39 marks buffer unaffected.
    40 
    41 delete-region region  [Function]
     42mark's buffer unaffected.
     43
     44`delete-region` region  [Function]
    4245
    4346This deletes region. This is faster than delete-and-save-region
    4447(below) because no lines are copied. If region is empty and contained
    45 in some buffers buffer-region, then Hemlock leaves buffer-modified of
     48in some buffer's buffer-region, then Hemlock leaves buffer-modified of
    4649the buffer unaffected.
    4750
    48 delete-and-save-region region  [Function]
     51`delete-and-save-region` region  [Function]
    4952
    5053This deletes region and returns a region containing the original
    51 region’s text. If region is empty and contained in some buffer’s
     54region's text. If region is empty and contained in some buffer's
    5255buffer-region, then Hemlock leaves buffer-modified of the buffer
    5356unaffected. In this case, this returns a distinct empty region.
    5457
    55 filter-region function region [Function]
     58`filter-region` function region [Function]
    5659
    5760Destructively modifies region by replacing the text of each line with
     
    6164 1. The argument may not be destructively modified.
    6265 2. The return value may not contain newline characters.
    63  3. The return value may not be destructively modified after it is returned fromfunction.
    64 
    65 The strings are passed in order, and are always simple strings.
     66 3. The return value may not be destructively modified after it is returned from function.
     67
     68The strings are passed in order.
    6669
    6770Using this function, a region could be uppercased by doing:
    68 {{{
    69 (filter-region #’string-upcase region)
    70 }}}
    71 
    72 == 4.2. Text Predicates ==
    73 
    74 start-line-p mark [Function]
     71`(filter-region #'string-upcase region)`
     72
     73== 4.2. Text Predicates ==#TextPredicates
     74
     75`start-line-p` mark [Function]
    7576
    7677Returns t if the mark points before the first character in a line, nil
    7778otherwise.
    7879
    79 end-line-p mark [Function]
     80`end-line-p` mark [Function]
    8081
    8182Returns t if the mark points after the last character in a line and
    8283before the newline, nil otherwise.
    8384
    84 empty-line-p mark [Function]
     85`empty-line-p` mark [Function]
    8586Return t if the line which mark points to contains no characters.
    8687
    87 blank-line-p line [Function]
     88`blank-line-p` line [Function]
    8889
    8990Returns t if line contains only characters with a Whitespace attribute
    9091of 1.  See chapter 9 for discussion of character attributes.
    9192
    92 blank-before-p mark [Function]
    93 
    94 blank-after-p mark [Function]
     93`blank-before-p` mark [Function][[BR]]
     94`blank-after-p` mark [Function]
    9595
    9696These functions test if all the characters preceding or following mark
    9797on the line it is on have a Whitespace attribute of 1.
    9898
    99 same-line-p mark1 mark2 [Function]
     99`same-line-p` mark1 mark2 [Function]
    100100
    101101Returns t if mark1 and mark2 point to the same line, or nil otherwise; That is,
     
    104104}}}
    105105
    106 mark< mark1 mark2 [Function]
    107 
    108 mark<= mark1 mark2 [Function]
    109 
    110 mark= mark1 mark2 [Function]
    111 
    112 mark/= mark1 mark2 [Function]
    113 
    114 mark>= mark1 mark2 [Function]
    115 
    116 mark> mark1 mark2 [Function]
     106`mark<` mark1 mark2 [Function][[BR]]
     107`mark<=` mark1 mark2 [Function][[BR]]
     108`mark=` mark1 mark2 [Function][[BR]]
     109`mark/=` mark1 mark2 [Function][[BR]]
     110`mark>=` mark1 mark2 [Function][[BR]]
     111`mark>` mark1 mark2 [Function][[BR]]
    117112
    118113These predicates test the relative ordering of two marks in a piece of
    119114text, that is a mark is mark> another if it points to a position after
    120 it. If the marks point into different, non-connected pieces of text,
    121 such as different buffers, then it is an error to test their ordering;
    122 for such marks mark= is always false and mark/= is always true.
    123 
    124 line< line1 line2 [Function]
    125 
    126 line<= line1 line2 [Function]
    127 
    128 line>= line1 line2 [Function]
    129 
    130 line> line1 line2 [Function]
    131 
    132 These predicates test the ordering of line1 and line2. If the lines
    133 are in unconnected pieces of text it is an error to test their
    134 ordering.
    135 
    136 lines-related line1 line2 [Function]
    137 
    138 This function returns t if line1 and line2 are in the same piece of
    139 text, or nil otherwise.
    140 
    141 first-line-p mark [Function]
    142 
    143 last-line-p mark [Function]
    144 
    145 first-line-p returns t if there is no line before the line mark is on,
    146 and nil otherwise. Last-line-p similarly tests tests whether there is
     115it. An error is signalled if the marks do not point into the same buffer,
     116except that for such marks mark= is always false and mark/= is always true.
     117
     118`line<` line1 line2 [Function][[BR]]
     119`line<=` line1 line2 [Function][[BR]]
     120`line>=` line1 line2 [Function][[BR]]
     121`line>` line1 line2 [Function][[BR]]
     122
     123These predicates test the ordering of line1 and line2. An error is signalled
     124if the lines are not in the same buffer.
     125
     126`lines-related` line1 line2 [Function]
     127
     128This function returns t if line1 and line2 are in the same buffer, nil
     129nil otherwise.
     130
     131`first-line-p` mark [Function][[BR]]
     132`last-line-p` mark [Function][[BR]]
     133
     134`first-line-p` returns t if there is no line before the line mark is on,
     135and nil otherwise. `Last-line-p` similarly tests tests whether there is
    147136no line after mark.
    148137
    149 == 4.3. Kill Ring ==
    150 
    151 *kill-ring* [Variable]
    152 
    153 This is a ring (see section 16.2) of regions deleted from buffers.
     138== 4.3. Kill Ring ==#KillRing
     139
     140There is a global ring (see section 16.2) of regions deleted from buffers.
    154141Some commands save affected regions on the kill ring before performing
    155142modifications.  You should consider making the command undoable (see
     
    157144satisfactory means for the user to recover.
    158145
    159 kill-region region  current-type [Function]
    160 
    161 This kills region saving it in *kill-ring*. Current-type is either
     146`kill-region` region  current-type [Function]
     147
     148This kills region saving it in the kill ring. Current-type is either
    162149:kill-forward or :kill-backward. When the last-command-type (page 31)
    163150is one of these, this adds region to the beginning or end,
    164 respectively, of the top of *kill-ring*. The result of calling this is
    165 undoable using the command Undo (see the Hemlock Users Manual). This
     151respectively, of the top of the kill ring. The result of calling this is
     152undoable using the command Undo (see the Hemlock User's Manual). This
    166153sets last-command-type to current-type, and it interacts with
    167154kill-characters.
    168155
    169 kill-characters mark count [Function]
    170 
    171 Character Deletion Threshold (initial value 5) [Hemlock Variable]
     156`kill-characters` mark count [Function]
     157
     158`Character Deletion Threshold` (initial value 5) [Hemlock Variable]
    172159
    173160kill-characters kills count characters after mark if count is
    174161positive, otherwise before mark if count is negative.  When count is
    175162greater than or equal to Character Deletion Threshold, the killed
    176 characters are saved on *kill-ring*. This may be called multiple times
     163characters are saved on the kill ring. This may be called multiple times
    177164contiguously (that is, without last-command-type (page 31) being set)
    178165to accumulate an effective count for purposes of comparison with the
     
    180167
    181168This sets last-command-type, and it interacts with kill-region. When
    182 this adds a new region to *kill-ring*, it sets last-command-type to
     169this adds a new region to the kill ring, it sets last-command-type to
    183170:kill-forward (if count is positive) or :kill-backward (if count is
    184171negative).  When last-command-type is :kill-forward or :kill-backward,
    185172this adds the killed characters to the beginning (if count is
    186 negative) or the end (if count is positive) of the top of *kill-ring*,
    187 and it sets last-command-type as if it added a new region to
    188 *kill-ring*. When the kill ring is unaffected, this sets
     173negative) or the end (if count is positive) of the top of the kill ring,
     174and it sets last-command-type as if it added a new region to the
     175kill ring. When the kill ring is unaffected, this sets
    189176last-command-type to :char-kill-forward or :char-kill-backward
    190177depending on whether count is positive or negative, respectively.
     
    193180characters in the appropriate direction, this returns nil.
    194181
    195 == 4.4. Active Regions ==
     182== 4.4. Active Regions ==#ActiveRegions
    196183
    197184Every buffer has a mark stack (page 9) and a mark known as the point
    198185where most text altering nominally occurs.  Between the top of the
    199 mark stack, the current-mark, and the current-buffers point, the
     186mark stack, the current-mark, and the current-buffer's point, the
    200187current-point, is what is known as the current-region . Certain
    201188commands signal errors when the user tries to operate on the
     
    224211 * or the user types C-g.
    225212
    226 Active Regions Enabled (initial value t) [Hemlock Variable]
     213`Active Regions Enabled` (initial value t) [Hemlock Variable]
    227214
    228215When this variable is non-nil, some primitives signal an editor-error
     
    230217traditional Emacs region semantics.
    231218
    232 *ephemerally-active-command-types* [Variable]
     219`*ephemerally-active-command-types*` [Variable]
    233220
    234221This is a list of command types (see section 7.3), and its initial
    235222value is the list of :ephemerally-active and :unkill. When the
    236 previous commands type is one of these, the current-region is active
     223previous command's type is one of these, the current-region is active
    237224for the currently executing command only, regardless of whether it
    238225does something to deactivate the region.  However, the current command
     
    242229Rotate Kill Ring (what users typically think of as C-y and M-y).
    243230
    244 activate-region [Function]
     231`activate-region` [Function]
    245232
    246233This makes the current-region active.
    247234
    248 deactivate-region [Function]
     235`deactivate-region` [Function]
    249236
    250237After invoking this the current-region is no longer active.
    251238
    252 region-active-p [Function]
     239`region-active-p` [Function]
    253240
    254241Returns whether the current-region is active, including
    255242ephemerally. This ignores Active Regions Enabled.
    256243
    257 check-region-active [Function]
     244`check-region-active` [Function]
    258245
    259246This signals an editor-error when active regions are enabled, and the
    260247current-region is not active.
    261248
    262 current-region &optional error-if-not-active deactivate-region [Function]
     249`current-region` &optional error-if-not-active deactivate-region [Function]
    263250
    264251This returns a region formed with current-mark and current-point,
     
    271258is convenient.
    272259
    273 == 4.5. Searching and Replacing ==
     260== 4.5. Searching and Replacing ==#SearchingAndReplacing
    274261
    275262Before using any of these functions to do a character search, look at
     
    279266in various modes.
    280267
    281 search-char-code-limit [Constant]
    282 
    283 An exclusive upper limit for the char-code of characters given to the
    284 searching functions.  The result of searches for characters with a
    285 char-code greater than or equal to this limit is ill-defined, but it
    286 is not an error to do such searches.
    287 
    288 new-search-pattern kind direction pattern &optional result-search-pattern [Function]
     268`new-search-pattern` kind direction pattern &optional result-search-pattern [Function]
    289269
    290270Returns a search-pattern object which can be given to the find-pattern
     
    296276of pattern being made.  Currently defined kinds of search pattern are:
    297277
    298 :string-insensitive Does a case-insensitive string search,patternbeing
    299 the string to search for.
    300 
    301 :string-sensitive Does a case-sensitive string search forpattern.
    302 
    303 :character Finds an occurrence of the characterpattern. This is case
    304 sensitive.
    305 
    306 :not-character Find a character which is not the characterpattern.
    307 
    308 :test Finds a character which satisfies the function pattern. This
    309 function may not be applied an any particular fashion, so it should
    310 depend only on what its argument is, and should have no side-effects.
    311 
    312 :test-not Similar to :test, except it finds a character that fails the test.
    313 
    314 :any Finds a character that is in the stringpattern.
    315 
    316 :not-any Finds a character that is not in the stringpattern.
     278 :string-insensitive:: Does a case-insensitive string search for pattern
     279
     280 :string-sensitive:: Does a case-sensitive string search for pattern.
     281
     282 :character:: Finds an occurrence of the character pattern. This is case sensitive.
     283
     284 :not-character:: Find a character which is not the character pattern.
     285
     286 :test:: Finds a character which satisfies the function pattern. This function may not be applied an any particular fashion, so it should depend only on what its argument is, and should have no side-effects.
     287
     288 :test-not:: Similar to :test, except it finds a character that fails the test.
     289
     290 :any:: Finds a character that is in the string pattern.
     291
     292 :not-any:: Finds a character that is not in the string pattern.
    317293
    318294result-search-pattern, if supplied, is a search-pattern to
     
    321297involve large data structures.
    322298
    323 search-pattern-p search-pattern [Function]
     299`search-pattern-p` search-pattern [Function]
    324300
    325301Returns t if search-pattern is a search-pattern object, otherwise nil.
    326302
    327 get-search-pattern string direction [Function]
    328 
    329 *last-search-pattern* [Variable]
    330 
    331 *last-search-string* [Variable]
     303`get-search-pattern` string direction [Function]
    332304
    333305get-search-pattern interfaces to a default search string and pattern
     
    335307a default when prompting for what to search or replace, and save on
    336308consing a search pattern each time they execute.  This uses Default
    337 Search Kind (see the  Hemlock  User’s Manual) when updating the pattern
    338 object.  This returns the pattern, so you probably don’t need to refer
    339 to *last-search-pattern*, but *last-search-string* is useful when
    340 prompting.
    341 
    342 find-pattern mark search-pattern [Function]
     309Search Kind (see the  Hemlock  User's Manual) when updating the pattern
     310object.
     311
     312*last-search-string* [Variable]
     313
     314Returns the last string searched for, useful when prompting.
     315
     316`find-pattern` mark search-pattern [Function]
    343317
    344318Find the next match of search-pattern starting at mark. If a match is
     
    347321nil is returned and mark is not modified.
    348322
    349 replace-pattern mark search-pattern replacement &optional n [Function]
     323`replace-pattern` mark search-pattern replacement &optional n [Function]
     324
    350325Replace n matches of search-pattern with the string replacement
    351326starting at mark. If n is nil (the default) then replace all matches.
    352327A mark pointing before the last replacement done is returned.
    353328
     329
     330[HemlockProgrammer Back to Table of Contents]