-\1f
-File: lispref.info, Node: List Motion, Next: Skipping Characters, Prev: Screen Lines, Up: Motion
-
-Moving over Balanced Expressions
---------------------------------
-
- Here are several functions concerned with balanced-parenthesis
-expressions (also called "sexps" in connection with moving across them
-in XEmacs). The syntax table controls how these functions interpret
-various characters; see *Note Syntax Tables::. *Note Parsing
-Expressions::, for lower-level primitives for scanning sexps or parts of
-sexps. For user-level commands, see *Note Lists and Sexps:
-(emacs)Lists and Sexps.
-
- - Command: forward-list &optional arg
- This function moves forward across ARG balanced groups of
- parentheses. (Other syntactic entities such as words or paired
- string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
- is negative, move backward across that many groups of parentheses.
-
- - Command: backward-list &optional arg
- This function moves backward across ARG balanced groups of
- parentheses. (Other syntactic entities such as words or paired
- string quotes are ignored.) ARG defaults to 1 if omitted. If ARG
- is negative, move forward across that many groups of parentheses.
-
- - Command: up-list arg
- This function moves forward out of ARG levels of parentheses. A
- negative argument means move backward but still to a less deep
- spot.
-
- - Command: down-list arg
- This function moves forward into ARG levels of parentheses. A
- negative argument means move backward but still go deeper in
- parentheses (-ARG levels).
-
- - Command: forward-sexp &optional arg
- This function moves forward across ARG balanced expressions.
- Balanced expressions include both those delimited by parentheses
- and other kinds, such as words and string constants. ARG defaults
- to 1 if omitted. If ARG is negative, move backward across that
- many balanced expressions. For example,
-
- ---------- Buffer: foo ----------
- (concat-!- "foo " (car x) y z)
- ---------- Buffer: foo ----------
-
- (forward-sexp 3)
- => nil
-
- ---------- Buffer: foo ----------
- (concat "foo " (car x) y-!- z)
- ---------- Buffer: foo ----------
-
- - Command: backward-sexp &optional arg
- This function moves backward across ARG balanced expressions. ARG
- defaults to 1 if omitted. If ARG is negative, move forward across
- that many balanced expressions.
-
- - Command: beginning-of-defun &optional arg
- This function moves back to the ARGth beginning of a defun. If
- ARG is negative, this actually moves forward, but it still moves
- to the beginning of a defun, not to the end of one. ARG defaults
- to 1 if omitted.
-
- - Command: end-of-defun &optional arg
- This function moves forward to the ARGth end of a defun. If ARG
- is negative, this actually moves backward, but it still moves to
- the end of a defun, not to the beginning of one. ARG defaults to
- 1 if omitted.
-
- - User Option: defun-prompt-regexp
- If non-`nil', this variable holds a regular expression that
- specifies what text can appear before the open-parenthesis that
- starts a defun. That is to say, a defun begins on a line that
- starts with a match for this regular expression, followed by a
- character with open-parenthesis syntax.
-
-\1f
-File: lispref.info, Node: Skipping Characters, Prev: List Motion, Up: Motion
-
-Skipping Characters
--------------------
-
- The following two functions move point over a specified set of
-characters. For example, they are often used to skip whitespace. For
-related functions, see *Note Motion and Syntax::.
-
- - Function: skip-chars-forward character-set &optional limit buffer
- This function moves point in BUFFER forward, skipping over a given
- set of characters. It examines the character following point,
- then advances point if the character matches CHARACTER-SET. This
- continues until it reaches a character that does not match. The
- function returns `nil'. BUFFER defaults to the current buffer if
- omitted.
-
- The argument CHARACTER-SET is like the inside of a `[...]' in a
- regular expression except that `]' is never special and `\' quotes
- `^', `-' or `\'. Thus, `"a-zA-Z"' skips over all letters,
- stopping before the first non-letter, and `"^a-zA-Z'" skips
- non-letters stopping before the first letter. *Note Regular
- Expressions::.
-
- If LIMIT is supplied (it must be a number or a marker), it
- specifies the maximum position in the buffer that point can be
- skipped to. Point will stop at or before LIMIT.
-
- In the following example, point is initially located directly
- before the `T'. After the form is evaluated, point is located at
- the end of that line (between the `t' of `hat' and the newline).
- The function skips all letters and spaces, but not newlines.
-
- ---------- Buffer: foo ----------
- I read "-!-The cat in the hat
- comes back" twice.
- ---------- Buffer: foo ----------
-
- (skip-chars-forward "a-zA-Z ")
- => nil
-
- ---------- Buffer: foo ----------
- I read "The cat in the hat-!-
- comes back" twice.
- ---------- Buffer: foo ----------
-
- - Function: skip-chars-backward character-set &optional limit buffer
- This function moves point backward, skipping characters that match
- CHARACTER-SET, until LIMIT. It just like `skip-chars-forward'
- except for the direction of motion.
-
-\1f
-File: lispref.info, Node: Excursions, Next: Narrowing, Prev: Motion, Up: Positions
-
-Excursions
-==========
-
- It is often useful to move point "temporarily" within a localized
-portion of the program, or to switch buffers temporarily. This is
-called an "excursion", and it is done with the `save-excursion' special
-form. This construct saves the current buffer and its values of point
-and the mark so they can be restored after the completion of the
-excursion.
-
- The forms for saving and restoring the configuration of windows are
-described elsewhere (see *Note Window Configurations:: and *note Frame
-Configurations::).
-
- - Special Form: save-excursion forms...
- The `save-excursion' special form saves the identity of the current
- buffer and the values of point and the mark in it, evaluates
- FORMS, and finally restores the buffer and its saved values of
- point and the mark. All three saved values are restored even in
- case of an abnormal exit via `throw' or error (*note Nonlocal
- Exits::).
-
- The `save-excursion' special form is the standard way to switch
- buffers or move point within one part of a program and avoid
- affecting the rest of the program. It is used more than 500 times
- in the Lisp sources of XEmacs.
-
- `save-excursion' does not save the values of point and the mark for
- other buffers, so changes in other buffers remain in effect after
- `save-excursion' exits.
-
- Likewise, `save-excursion' does not restore window-buffer
- correspondences altered by functions such as `switch-to-buffer'.
- One way to restore these correspondences, and the selected window,
- is to use `save-window-excursion' inside `save-excursion' (*note
- Window Configurations::).
-
- The value returned by `save-excursion' is the result of the last of
- FORMS, or `nil' if no FORMS are given.
-
- (save-excursion
- FORMS)
- ==
- (let ((old-buf (current-buffer))
- (old-pnt (point-marker))
- (old-mark (copy-marker (mark-marker))))
- (unwind-protect
- (progn FORMS)
- (set-buffer old-buf)
- (goto-char old-pnt)
- (set-marker (mark-marker) old-mark)))
-
- - Special Form: save-current-buffer forms...
- This special form is similar to `save-excursion' but it only saves
- and restores the current buffer. Beginning with XEmacs 20.3,
- `save-current-buffer' is a primitive.
-
- - Special Form: with-current-buffer buffer forms...
- This special form evaluates FORMS with BUFFER as the current
- buffer. It returns the value of the last form.
-
- - Special Form: with-temp-file file forms...
- This special form creates a new buffer, evaluates FORMS there, and
- writes the buffer to FILE. It returns the value of the last form
- evaluated.
-
- - Special Form: save-selected-window forms...
- This special form is similar to `save-excursion' but it saves and
- restores the selected window and nothing else.
-
-\1f
-File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions
-
-Narrowing
-=========
-
- "Narrowing" means limiting the text addressable by XEmacs editing
-commands to a limited range of characters in a buffer. The text that
-remains addressable is called the "accessible portion" of the buffer.
-
- Narrowing is specified with two buffer positions which become the
-beginning and end of the accessible portion. For most editing commands
-and most Emacs primitives, these positions replace the values of the
-beginning and end of the buffer. While narrowing is in effect, no text
-outside the accessible portion is displayed, and point cannot move
-outside the accessible portion.
-
- Values such as positions or line numbers, which usually count from
-the beginning of the buffer, do so despite narrowing, but the functions
-which use them refuse to operate on text that is inaccessible.
-
- The commands for saving buffers are unaffected by narrowing; they
-save the entire buffer regardless of any narrowing.
-
- - Command: narrow-to-region start end &optional buffer
- This function sets the accessible portion of BUFFER to start at
- START and end at END. Both arguments should be character
- positions. BUFFER defaults to the current buffer if omitted.
-
- In an interactive call, START and END are set to the bounds of the
- current region (point and the mark, with the smallest first).
-
- - Command: narrow-to-page &optional move-count
- This function sets the accessible portion of the current buffer to
- include just the current page. An optional first argument
- MOVE-COUNT non-`nil' means to move forward or backward by
- MOVE-COUNT pages and then narrow. The variable `page-delimiter'
- specifies where pages start and end (*note Standard Regexps::).
-
- In an interactive call, MOVE-COUNT is set to the numeric prefix
- argument.
-
- - Command: widen &optional buffer
- This function cancels any narrowing in BUFFER, so that the entire
- contents are accessible. This is called "widening". It is
- equivalent to the following expression:
-
- (narrow-to-region 1 (1+ (buffer-size)))
-
- BUFFER defaults to the current buffer if omitted.
-
- - Special Form: save-restriction body...
- This special form saves the current bounds of the accessible
- portion, evaluates the BODY forms, and finally restores the saved
- bounds, thus restoring the same state of narrowing (or absence
- thereof) formerly in effect. The state of narrowing is restored
- even in the event of an abnormal exit via `throw' or error (*note
- Nonlocal Exits::). Therefore, this construct is a clean way to
- narrow a buffer temporarily.
-
- The value returned by `save-restriction' is that returned by the
- last form in BODY, or `nil' if no body forms were given.
-
- *Caution:* it is easy to make a mistake when using the
- `save-restriction' construct. Read the entire description here
- before you try it.
-
- If BODY changes the current buffer, `save-restriction' still
- restores the restrictions on the original buffer (the buffer whose
- restrictions it saved from), but it does not restore the identity
- of the current buffer.
-
- `save-restriction' does _not_ restore point and the mark; use
- `save-excursion' for that. If you use both `save-restriction' and
- `save-excursion' together, `save-excursion' should come first (on
- the outside). Otherwise, the old point value would be restored
- with temporary narrowing still in effect. If the old point value
- were outside the limits of the temporary narrowing, this would
- fail to restore it accurately.
-
- The `save-restriction' special form records the values of the
- beginning and end of the accessible portion as distances from the
- beginning and end of the buffer. In other words, it records the
- amount of inaccessible text before and after the accessible
- portion.
-
- This method yields correct results if BODY does further narrowing.
- However, `save-restriction' can become confused if the body widens
- and then make changes outside the range of the saved narrowing.
- When this is what you want to do, `save-restriction' is not the
- right tool for the job. Here is what you must use instead:
-
- (let ((beg (point-min-marker))
- (end (point-max-marker)))
- (unwind-protect
- (progn BODY)
- (save-excursion
- (set-buffer (marker-buffer beg))
- (narrow-to-region beg end))))
-
- Here is a simple example of correct use of `save-restriction':
-
- ---------- Buffer: foo ----------
- This is the contents of foo
- This is the contents of foo
- This is the contents of foo-!-
- ---------- Buffer: foo ----------
-
- (save-excursion
- (save-restriction
- (goto-char 1)
- (forward-line 2)
- (narrow-to-region 1 (point))
- (goto-char (point-min))
- (replace-string "foo" "bar")))
-
- ---------- Buffer: foo ----------
- This is the contents of bar
- This is the contents of bar
- This is the contents of foo-!-
- ---------- Buffer: foo ----------
-
-\1f
-File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top
-
-Markers
-*******
-
- A "marker" is a Lisp object used to specify a position in a buffer
-relative to the surrounding text. A marker changes its offset from the
-beginning of the buffer automatically whenever text is inserted or
-deleted, so that it stays with the two characters on either side of it.
-
-* Menu:
-
-* Overview of Markers:: The components of a marker, and how it relocates.
-* Predicates on Markers:: Testing whether an object is a marker.
-* Creating Markers:: Making empty markers or markers at certain places.
-* Information from Markers:: Finding the marker's buffer or character position.
-* Changing Markers:: Moving the marker to a new buffer or position.
-* The Mark:: How ``the mark'' is implemented with a marker.
-* The Region:: How to access ``the region''.
-
-\1f
-File: lispref.info, Node: Overview of Markers, Next: Predicates on Markers, Up: Markers
-
-Overview of Markers
-===================
-
- A marker specifies a buffer and a position in that buffer. The
-marker can be used to represent a position in the functions that
-require one, just as an integer could be used. *Note Positions::, for
-a complete description of positions.
-
- A marker has two attributes: the marker position, and the marker
-buffer. The marker position is an integer that is equivalent (at a
-given time) to the marker as a position in that buffer. But the
-marker's position value can change often during the life of the marker.
-Insertion and deletion of text in the buffer relocate the marker. The
-idea is that a marker positioned between two characters remains between
-those two characters despite insertion and deletion elsewhere in the
-buffer. Relocation changes the integer equivalent of the marker.
-
- Deleting text around a marker's position leaves the marker between
-the characters immediately before and after the deleted text. Inserting
-text at the position of a marker normally leaves the marker in front of
-the new text--unless it is inserted with `insert-before-markers' (*note
-Insertion::).
-
- Insertion and deletion in a buffer must check all the markers and
-relocate them if necessary. This slows processing in a buffer with a
-large number of markers. For this reason, it is a good idea to make a
-marker point nowhere if you are sure you don't need it any more.
-Unreferenced markers are garbage collected eventually, but until then
-will continue to use time if they do point somewhere.
-
- Because it is common to perform arithmetic operations on a marker
-position, most of the arithmetic operations (including `+' and `-')
-accept markers as arguments. In such cases, the marker stands for its
-current position.
-
- Note that you can use extents to achieve the same functionality, and
-more, as markers. (Markers were defined before extents, which is why
-they both continue to exist.) A zero-length extent with the
-`detachable' property removed is almost identical to a marker. (*Note
-Extent Endpoints::, for more information on zero-length extents.)
-
- In particular:
-
- * In order to get marker-like behavior in a zero-length extent, the
- `detachable' property must be removed (otherwise, the extent will
- disappear when text near it is deleted) and exactly one endpoint
- must be closed (if both endpoints are closed, the extent will
- expand to contain text inserted where it is located).
-
- * If a zero-length extent has the `end-open' property but not the
- `start-open' property (this is the default), text inserted at the
- extent's location causes the extent to move forward, just like a
- marker.
-
- * If a zero-length extent has the `start-open' property but not the
- `end-open' property, text inserted at the extent's location causes
- the extent to remain before the text, like what happens to markers
- when `insert-before-markers' is used.
-
- * Markers end up after or before inserted text depending on whether
- `insert' or `insert-before-markers' was called. These functions
- do not affect zero-length extents differently; instead, the
- presence or absence of the `start-open' and `end-open' extent
- properties determines this, as just described.
-
- * Markers are automatically removed from a buffer when they are no
- longer in use. Extents remain around until explicitly removed
- from a buffer.
-
- * Many functions are provided for listing the extents in a buffer or
- in a region of a buffer. No such functions exist for markers.
-
- Here are examples of creating markers, setting markers, and moving
-point to markers:
-
- ;; Make a new marker that initially does not point anywhere:
- (setq m1 (make-marker))
- => #<marker in no buffer>
-
- ;; Set `m1' to point between the 99th and 100th characters
- ;; in the current buffer:
- (set-marker m1 100)
- => #<marker at 100 in markers.texi>
-
- ;; Now insert one character at the beginning of the buffer:
- (goto-char (point-min))
- => 1
- (insert "Q")
- => nil
-
- ;; `m1' is updated appropriately.
- m1
- => #<marker at 101 in markers.texi>
-
- ;; Two markers that point to the same position
- ;; are not `eq', but they are `equal'.
- (setq m2 (copy-marker m1))
- => #<marker at 101 in markers.texi>
- (eq m1 m2)
- => nil
- (equal m1 m2)
- => t
-
- ;; When you are finished using a marker, make it point nowhere.
- (set-marker m1 nil)
- => #<marker in no buffer>
-
-\1f
-File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers
-
-Predicates on Markers
-=====================
-
- You can test an object to see whether it is a marker, or whether it
-is either an integer or a marker or either an integer, a character, or a
-marker. The latter tests are useful in connection with the arithmetic
-functions that work with any of markers, integers, or characters.
-
- - Function: markerp object
- This function returns `t' if OBJECT is a marker, `nil' otherwise.
- Note that integers are not markers, even though many functions
- will accept either a marker or an integer.
-
- - Function: integer-or-marker-p object
- This function returns `t' if OBJECT is an integer or a marker,
- `nil' otherwise.
-
- - Function: integer-char-or-marker-p object
- This function returns `t' if OBJECT is an integer, a character, or
- a marker, `nil' otherwise.
-
- - Function: number-or-marker-p object
- This function returns `t' if OBJECT is a number (either kind) or a
- marker, `nil' otherwise.
-
- - Function: number-char-or-marker-p object
- This function returns `t' if OBJECT is a number (either kind), a
- character, or a marker, `nil' otherwise.
-
-\1f
-File: lispref.info, Node: Creating Markers, Next: Information from Markers, Prev: Predicates on Markers, Up: Markers
-
-Functions That Create Markers
-=============================
-
- When you create a new marker, you can make it point nowhere, or point
-to the present position of point, or to the beginning or end of the
-accessible portion of the buffer, or to the same place as another given
-marker.
-
- - Function: make-marker
- This functions returns a newly created marker that does not point
- anywhere.
-
- (make-marker)
- => #<marker in no buffer>
-
- - Function: point-marker &optional dont-copy-p buffer
- This function returns a marker that points to the present position
- of point in BUFFER, which defaults to the current buffer. *Note
- Point::. For an example, see `copy-marker', below.
-
- Internally, a marker corresponding to point is always maintained.
- Normally the marker returned by `point-marker' is a copy; you may
- modify it with reckless abandon. However, if optional argument
- DONT-COPY-P is non-`nil', then the real point-marker is returned;
- modifying the position of this marker will move point. It is
- illegal to change the buffer of it, or make it point nowhere.
-
- - Function: point-min-marker &optional buffer
- This function returns a new marker that points to the beginning of
- the accessible portion of BUFFER, which defaults to the current
- buffer. This will be the beginning of the buffer unless narrowing
- is in effect. *Note Narrowing::.
-
- - Function: point-max-marker &optional buffer
- This function returns a new marker that points to the end of the
- accessible portion of BUFFER, which defaults to the current
- buffer. This will be the end of the buffer unless narrowing is in
- effect. *Note Narrowing::.
-
- Here are examples of this function and `point-min-marker', shown in
- a buffer containing a version of the source file for the text of
- this chapter.
-
- (point-min-marker)
- => #<marker at 1 in markers.texi>
- (point-max-marker)
- => #<marker at 15573 in markers.texi>
-
- (narrow-to-region 100 200)
- => nil
- (point-min-marker)
- => #<marker at 100 in markers.texi>
- (point-max-marker)
- => #<marker at 200 in markers.texi>
-
- - Function: copy-marker marker-or-integer
- If passed a marker as its argument, `copy-marker' returns a new
- marker that points to the same place and the same buffer as does
- MARKER-OR-INTEGER. If passed an integer as its argument,
- `copy-marker' returns a new marker that points to position
- MARKER-OR-INTEGER in the current buffer.
-
- If passed an integer argument less than 1, `copy-marker' returns a
- new marker that points to the beginning of the current buffer. If
- passed an integer argument greater than the length of the buffer,
- `copy-marker' returns a new marker that points to the end of the
- buffer.
-
- An error is signaled if MARKER is neither a marker nor an integer.
-
- (setq p (point-marker))
- => #<marker at 2139 in markers.texi>
-
- (setq q (copy-marker p))
- => #<marker at 2139 in markers.texi>
-
- (eq p q)
- => nil
-
- (equal p q)
- => t
-
- (point)
- => 2139
-
- (set-marker p 3000)
- => #<marker at 3000 in markers.texi>
-
- (point)
- => 2139
-
- (setq p (point-marker t))
- => #<marker at 2139 in markers.texi>
-
- (set-marker p 3000)
- => #<marker at 3000 in markers.texi>
-
- (point)
- => 3000
-
- (copy-marker 0)
- => #<marker at 1 in markers.texi>
-
- (copy-marker 20000)
- => #<marker at 7572 in markers.texi>
-
-\1f
-File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers
-
-Information from Markers
-========================
-
- This section describes the functions for accessing the components of
-a marker object.
-
- - Function: marker-position marker
- This function returns the position that MARKER points to, or `nil'
- if it points nowhere.
-
- - Function: marker-buffer marker
- This function returns the buffer that MARKER points into, or `nil'
- if it points nowhere.
-
- (setq m (make-marker))
- => #<marker in no buffer>
- (marker-position m)
- => nil
- (marker-buffer m)
- => nil
-
- (set-marker m 3770 (current-buffer))
- => #<marker at 3770 in markers.texi>
- (marker-buffer m)
- => #<buffer markers.texi>
- (marker-position m)
- => 3770
-
- Two distinct markers are considered `equal' (even though not `eq')
-to each other if they have the same position and buffer, or if they
-both point nowhere.
-
-\1f
-File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers
-
-Changing Marker Positions
-=========================
-
- This section describes how to change the position of an existing
-marker. When you do this, be sure you know whether the marker is used
-outside of your program, and, if so, what effects will result from
-moving it--otherwise, confusing things may happen in other parts of
-Emacs.
-
- - Function: set-marker marker position &optional buffer
- This function moves MARKER to POSITION in BUFFER. If BUFFER is
- not provided, it defaults to the current buffer.
-
- If POSITION is less than 1, `set-marker' moves MARKER to the
- beginning of the buffer. If POSITION is greater than the size of
- the buffer, `set-marker' moves marker to the end of the buffer.
- If POSITION is `nil' or a marker that points nowhere, then MARKER
- is set to point nowhere.
-
- The value returned is MARKER.
-
- (setq m (point-marker))
- => #<marker at 4714 in markers.texi>
- (set-marker m 55)
- => #<marker at 55 in markers.texi>
- (setq b (get-buffer "foo"))
- => #<buffer foo>
- (set-marker m 0 b)
- => #<marker at 1 in foo>
-
- - Function: move-marker marker position &optional buffer
- This is another name for `set-marker'.
-