Changes between Version 2 and Version 3 of HemlockProgrammer/AlteringAndSearchingText


Ignore:
Timestamp:
01/14/08 18:19:34 (7 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]