X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-28;h=88a5f6d53ed264b5e9d3c253ad82683e8ba8e0c2;hb=16d0840d3eada757f529c34fddc0c2fb8f17b9de;hp=5fb922867c0e581ad3b78c98bd537bddc8a29881;hpb=430e0db85cc37821320fe27da9feeacc7961003f;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-28 b/info/lispref.info-28 index 5fb9228..88a5f6d 100644 --- a/info/lispref.info-28 +++ b/info/lispref.info-28 @@ -1,5 +1,5 @@ -This is Info file ../../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref.texi. +This is ../info/lispref.info, produced by makeinfo version 4.0b from +lispref/lispref.texi. INFO-DIR-SECTION XEmacs Editor START-INFO-DIR-ENTRY @@ -50,1130 +50,1200 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -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. +File: lispref.info, Node: Finding All Frames, Next: Frames and Windows, Prev: Deleting Frames, Up: Frames + +Finding All Frames +================== + + - Function: frame-list + The function `frame-list' returns a list of all the frames that + have not been deleted. It is analogous to `buffer-list' for + buffers. The list that you get is newly created, so modifying the + list doesn't have any effect on the internals of XEmacs. + + - Function: device-frame-list &optional device + This function returns a list of all frames on DEVICE. If DEVICE + is `nil', the selected device will be used. + + - Function: visible-frame-list &optional device + This function returns a list of just the currently visible frames. + If DEVICE is specified only frames on that device will be returned. + *Note Visibility of Frames::. (TTY frames always count as + "visible", even though only the selected one is actually + displayed.) + + - Function: next-frame &optional frame which-frames which-devices + The function `next-frame' lets you cycle conveniently through all + the frames from an arbitrary starting point. It returns the "next" + frame after FRAME in the cycle. If FRAME defaults to the selected + frame. + + The second argument, WHICH-FRAMES, says which frames to consider: + + `visible' + Consider only frames that are visible. + + `iconic' + Consider only frames that are iconic. + + `invisible' + Consider only frames that are invisible (this is different + from iconic). + + `visible-iconic' + Consider frames that are visible or iconic. + + `invisible-iconic' + Consider frames that are invisible or iconic. + + `nomini' + Consider all frames except minibuffer-only ones. + + `visible-nomini' + Like `visible' but omits minibuffer-only frames. + + `iconic-nomini' + Like `iconic' but omits minibuffer-only frames. + + `invisible-nomini' + Like `invisible' but omits minibuffer-only frames. + + `visible-iconic-nomini' + Like `visible-iconic' but omits minibuffer-only frames. + + `invisible-iconic-nomini' + Like `invisible-iconic' but omits minibuffer-only frames. + + `nil' + Identical to `nomini'. + + WINDOW + Consider only the window WINDOW's frame and any frame now + using WINDOW as the minibuffer. + + any other value + Consider all frames. + + The optional argument WHICH-DEVICES further clarifies on which + devices to search for frames as specified by WHICH-FRAMES. + + `nil' + Consider all devices on the selected console. + + DEVICE + Consider only the one device DEVICE. + + CONSOLE + Consider all devices on CONSOLE. + + DEVICE-TYPE + Consider all devices with device type DEVICE-TYPE. + + `window-system' + Consider all devices on window system consoles. + + anything else + Consider all devices without restriction. + + - Function: previous-frame &optional frame which-frames which-devices + Like `next-frame', but cycles through all frames in the opposite + direction. + + See also `next-window' and `previous-window', in *Note Cyclic Window +Ordering::.  -File: lispref.info, Node: Narrowing, Prev: Excursions, Up: Positions +File: lispref.info, Node: Frames and Windows, Next: Minibuffers and Frames, Prev: Finding All Frames, Up: Frames -Narrowing -========= +Frames and Windows +================== - "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. + Each window is part of one and only one frame; you can get the frame +with `window-frame'. - 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. + - Function: frame-root-window &optional frame + This returns the root window of frame FRAME. FRAME defaults to + the selected frame if not specified. - 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. + - Function: window-frame &optional window + This function returns the frame that WINDOW is on. WINDOW + defaults to the selected window if omitted. - The commands for saving buffers are unaffected by narrowing; they -save the entire buffer regardless of any narrowing. + All the non-minibuffer windows in a frame are arranged in a cyclic +order. The order runs from the frame's top window, which is at the +upper left corner, down and to the right, until it reaches the window at +the lower right corner (always the minibuffer window, if the frame has +one), and then it moves back to the top. - - 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. + - Function: frame-highest-window &optional frame position + This function returns the topmost, leftmost window of frame FRAME + at position POSITION. - In an interactive call, START and END are set to the bounds of the - current region (point and the mark, with the smallest first). + If omitted, FRAME defaults to the currently selected frame. - - 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::.). + POSITION is used to distinguish between multiple windows that abut + the top of the frame: 0 means the leftmost window abutting the top + of the frame, 1 the next-leftmost, etc. POSITION can also be less + than zero: -1 means the rightmost window abutting the top of the + frame, -2 the next-rightmost, etc. If omitted, POSITION defaults + to 0, i.e. the leftmost highest window. If there is no window at + the given POSITION, `nil' is returned. - In an interactive call, MOVE-COUNT is set to the numeric prefix - argument. + The following three functions work similarly. - - 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: + - Function: frame-lowest-window &optional frame position + This function returns the lowest window on FRAME which is at + POSITION. - (narrow-to-region 1 (1+ (buffer-size))) + - Function: frame-leftmost-window &optional frame position + This function returns the leftmost window on FRAME which is at + POSITION. - BUFFER defaults to the current buffer if omitted. + - Function: frame-rightmost-window &optional frame position + This function returns the rightmost window on FRAME which is at + POSITION. - - 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': + At any time, exactly one window on any frame is "selected within the +frame". The significance of this designation is that selecting the +frame also selects this window. You can get the frame's current +selected window with `frame-selected-window'. - ---------- 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 ---------- + - Function: frame-selected-window &optional frame + This function returns the window on FRAME that is selected within + FRAME. FRAME defaults to the selected frame if not specified. + + Conversely, selecting a window for XEmacs with `select-window' also +makes that window selected within its frame. *Note Selecting Windows::. + + Another function that (usually) returns one of the windows in a +frame is `minibuffer-window'. *Note Minibuffer Misc::.  -File: lispref.info, Node: Markers, Next: Text, Prev: Positions, Up: Top +File: lispref.info, Node: Minibuffers and Frames, Next: Input Focus, Prev: Frames and Windows, Up: Frames -Markers -******* +Minibuffers and Frames +====================== - 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. + Normally, each frame has its own minibuffer window at the bottom, +which is used whenever that frame is selected. If the frame has a +minibuffer, you can get it with `minibuffer-window' (*note Minibuffer +Misc::). -* Menu: + However, you can also create a frame with no minibuffer. Such a +frame must use the minibuffer window of some other frame. When you +create the frame, you can specify explicitly the minibuffer window to +use (in some other frame). If you don't, then the minibuffer is found +in the frame which is the value of the variable +`default-minibuffer-frame'. Its value should be a frame which does +have a minibuffer. -* 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". + - Variable: default-minibuffer-frame + This variable specifies the frame to use for the minibuffer + window, by default.  -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)) - => # - - ;; Set `m1' to point between the 99th and 100th characters - ;; in the current buffer: - (set-marker m1 100) - => # - - ;; Now insert one character at the beginning of the buffer: - (goto-char (point-min)) - => 1 - (insert "Q") - => nil - - ;; `m1' is updated appropriately. - m1 - => # - - ;; Two markers that point to the same position - ;; are not `eq', but they are `equal'. - (setq m2 (copy-marker m1)) - => # - (eq m1 m2) - => nil - (equal m1 m2) - => t - - ;; When you are finished using a marker, make it point nowhere. - (set-marker m1 nil) - => # +File: lispref.info, Node: Input Focus, Next: Visibility of Frames, Prev: Minibuffers and Frames, Up: Frames + +Input Focus +=========== + + At any time, one frame in XEmacs is the "selected frame". The +selected window always resides on the selected frame. As the focus +moves from device to device, the selected frame on each device is +remembered and restored when the focus moves back to that device. + + - Function: selected-frame &optional device + This function returns the selected frame on DEVICE. If DEVICE is + not specified, the selected device will be used. If no frames + exist on the device, `nil' is returned. + + The X server normally directs keyboard input to the X window that the +mouse is in. Some window managers use mouse clicks or keyboard events +to "shift the focus" to various X windows, overriding the normal +behavior of the server. + + Lisp programs can switch frames "temporarily" by calling the +function `select-frame'. This does not override the window manager; +rather, it escapes from the window manager's control until that control +is somehow reasserted. + + When using a text-only terminal, there is no window manager; +therefore, `select-frame' is the only way to switch frames, and the +effect lasts until overridden by a subsequent call to `select-frame'. +Only the selected terminal frame is actually displayed on the terminal. +Each terminal screen except for the initial one has a number, and the +number of the selected frame appears in the mode line after the word +`XEmacs' (*note Modeline Variables::). + + - Function: select-frame frame + This function selects frame FRAME, temporarily disregarding the + focus of the X server if any. The selection of FRAME lasts until + the next time the user does something to select a different frame, + or until the next time this function is called. + + Note that `select-frame' does not actually cause the window-system + focus to be set to this frame, or the `select-frame-hook' or + `deselect-frame-hook' to be run, until the next time that XEmacs is + waiting for an event. + + Also note that when the variable `focus-follows-mouse' is + non-`nil', the frame selection is temporary and is reverted when + the current command terminates, much like the buffer selected by + `set-buffer'. In order to effect a permanent focus change use + `focus-frame'. + + - Function: focus-frame frame + This function selects FRAME and gives it the window system focus. + The operation of `focus-frame' is not affected by the value of + `focus-follows-mouse'. + + - Special Form: save-selected-frame forms... + This special form records the selected frame, executes FORMS in + sequence, then restores the earlier selected frame. The value + returned is the value of the last form. + + - Special Form: with-selected-frame frame forms... + This special form records the selected frame, then selects FRAME + and executes FORMS in sequence. After the last form is finished, + the earlier selected frame is restored. The value returned is the + value of the last form.  -File: lispref.info, Node: Predicates on Markers, Next: Creating Markers, Prev: Overview of Markers, Up: Markers +File: lispref.info, Node: Visibility of Frames, Next: Raising and Lowering, Prev: Input Focus, Up: Frames + +Visibility of Frames +==================== + + An frame on a window system may be "visible", "invisible", or +"iconified". If it is visible, you can see its contents. If it is +iconified, the frame's contents do not appear on the screen, but an icon +does. If the frame is invisible, it doesn't show on the screen, not +even as an icon. -Predicates on Markers -===================== + Visibility is meaningless for TTY frames, since only the selected +one is actually displayed in any case. - 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: make-frame-visible &optional frame + This function makes frame FRAME visible. If you omit FRAME, it + makes the selected frame visible. - - 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: make-frame-invisible &optional frame force + This function makes frame FRAME invisible. - - Function: integer-or-marker-p OBJECT - This function returns `t' if OBJECT is an integer or a marker, - `nil' otherwise. + - Command: iconify-frame &optional frame + This function iconifies frame FRAME. - - Function: integer-char-or-marker-p OBJECT - This function returns `t' if OBJECT is an integer, a character, or - a marker, `nil' otherwise. + - Function: Command deiconify-frame &optional frame + This function de-iconifies frame FRAME. Under a window system, + this is equivalent to `make-frame-visible'. - - Function: number-or-marker-p OBJECT - This function returns `t' if OBJECT is a number (either kind) or a - marker, `nil' otherwise. + - Function: frame-visible-p &optional frame + This returns whether FRAME is currently "visible" (actually in use + for display). A frame that is not visible is not updated, and, if + it works through a window system, may not show at all. - - 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. + - Function: frame-iconified-p &optional frame + This returns whether FRAME is iconified. Not all window managers + use icons; some merely unmap the window, so this function is not + the inverse of `frame-visible-p'. It is possible for a frame to + not be visible and not be iconified either. However, if the frame + is iconified, it will not be visible. (Under FSF Emacs, the + functionality of this function is obtained through + `frame-visible-p'.) + + - Function: frame-totally-visible-p &optional frame + This returns whether FRAME is not obscured by any other X windows. + On TTY frames, this is the same as `frame-visible-p'.  -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) - => # - - - 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) - => # - (point-max-marker) - => # - - (narrow-to-region 100 200) - => nil - (point-min-marker) - => # - (point-max-marker) - => # - - - 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)) - => # - - (setq q (copy-marker p)) - => # - - (eq p q) - => nil - - (equal p q) - => t - - (point) - => 2139 - - (set-marker p 3000) - => # - - (point) - => 2139 - - (setq p (point-marker t)) - => # - - (set-marker p 3000) - => # - - (point) - => 3000 - - (copy-marker 0) - => # - - (copy-marker 20000) - => # +File: lispref.info, Node: Raising and Lowering, Next: Frame Configurations, Prev: Visibility of Frames, Up: Frames + +Raising and Lowering Frames +=========================== + + The X Window System uses a desktop metaphor. Part of this metaphor +is the idea that windows are stacked in a notional third dimension +perpendicular to the screen surface, and thus ordered from "highest" to +"lowest". Where two windows overlap, the one higher up covers the one +underneath. Even a window at the bottom of the stack can be seen if no +other window overlaps it. + + A window's place in this ordering is not fixed; in fact, users tend +to change the order frequently. "Raising" a window means moving it +"up", to the top of the stack. "Lowering" a window means moving it to +the bottom of the stack. This motion is in the notional third +dimension only, and does not change the position of the window on the +screen. + + You can raise and lower XEmacs's X windows with these functions: + + - Command: raise-frame &optional frame + This function raises frame FRAME. + + - Command: lower-frame &optional frame + This function lowers frame FRAME. + + You can also specify auto-raise (raising automatically when a frame +is selected) or auto-lower (lowering automatically when it is +deselected). Under X, most ICCCM-compliant window managers will have +an option to do this for you, but the following variables are provided +in case you're using a broken WM. (Under FSF Emacs, the same +functionality is provided through the `auto-raise' and `auto-lower' +frame properties.) + + - Variable: auto-raise-frame + This variable's value is `t' if frames will be raised to the top + when selected. + + - Variable: auto-lower-frame + This variable's value is `t' if frames will be lowered to the + bottom when no longer selected. + + Auto-raising and auto-lowering is implemented through functions +attached to `select-frame-hook' and `deselect-frame-hook' (*note Frame +Hooks::). Under normal circumstances, you should not call these +functions directly. + + - Function: default-select-frame-hook + This hook function implements the `auto-raise-frame' variable; it + is for use as the value of `select-frame-hook'. + + - Function: default-deselect-frame-hook + This hook function implements the `auto-lower-frame' variable; it + is for use as the value of `deselect-frame-hook'.  -File: lispref.info, Node: Information from Markers, Next: Changing Markers, Prev: Creating Markers, Up: Markers +File: lispref.info, Node: Frame Configurations, Next: Frame Hooks, Prev: Raising and Lowering, Up: Frames -Information from Markers -======================== +Frame Configurations +==================== - This section describes the functions for accessing the components of -a marker object. + A "frame configuration" records the current arrangement of frames, +all their properties, and the window configuration of each one. - - Function: marker-position MARKER - This function returns the position that MARKER points to, or `nil' - if it points nowhere. + - Function: current-frame-configuration + This function returns a frame configuration list that describes + the current arrangement of frames and their contents. - - Function: marker-buffer MARKER - This function returns the buffer that MARKER points into, or `nil' - if it points nowhere. + - Function: set-frame-configuration configuration &optional nodelete + This function restores the state of frames described by + CONFIGURATION, which should be the return value from a previous + call to `current-frame-configuration'. - (setq m (make-marker)) - => # - (marker-position m) - => nil - (marker-buffer m) - => nil - - (set-marker m 3770 (current-buffer)) - => # - (marker-buffer m) - => # - (marker-position m) - => 3770 + Each frame listed in CONFIGURATION has its position, size, window + configuration, and other properties set as specified in + CONFIGURATION. - 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. + Ordinarily, this function deletes all existing frames not listed in + CONFIGURATION. But if optional second argument NODELETE is + non-`nil', the unwanted frames are iconified instead.  -File: lispref.info, Node: Changing Markers, Next: The Mark, Prev: Information from Markers, Up: Markers +File: lispref.info, Node: Frame Hooks, Prev: Frame Configurations, Up: Frames + +Hooks for Customizing Frame Behavior +==================================== + + XEmacs provides many hooks that are called at various times during a +frame's lifetime. *Note Hooks::. -Changing Marker Positions -========================= + - Variable: create-frame-hook + This hook is called each time a frame is created. The functions + are called with one argument, the newly-created frame. - 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. + - Variable: delete-frame-hook + This hook is called each time a frame is deleted. The functions + are called with one argument, the about-to-be-deleted frame. - - 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. + - Variable: select-frame-hook + This is a normal hook that is run just after a frame is selected. + The function `default-select-frame-hook', which implements + auto-raising (*note Raising and Lowering::), is normally attached + to this hook. - 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. + Note that calling `select-frame' does not necessarily set the + focus: The actual window-system focus will not be changed until + the next time that XEmacs is waiting for an event, and even then, + the window manager may refuse the focus-change request. - The value returned is MARKER. + - Variable: deselect-frame-hook + This is a normal hook that is run just before a frame is deselected + (and another frame is selected). The function + `default-deselect-frame-hook', which implements auto-lowering + (*note Raising and Lowering::), is normally attached to this hook. - (setq m (point-marker)) - => # - (set-marker m 55) - => # - (setq b (get-buffer "foo")) - => # - (set-marker m 0 b) - => # + - Variable: map-frame-hook + This hook is called each time a frame is mapped (i.e. made + visible). The functions are called with one argument, the newly + mapped frame. - - Function: move-marker MARKER POSITION &optional BUFFER - This is another name for `set-marker'. + - Variable: unmap-frame-hook + This hook is called each time a frame is unmapped (i.e. made + invisible or iconified). The functions are called with one + argument, the newly unmapped frame.  -File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers - -The Mark -======== - - One special marker in each buffer is designated "the mark". It -records a position for the user for the sake of commands such as `C-w' -and `C-x '. Lisp programs should set the mark only to values that -have a potential use to the user, and never for their own internal -purposes. For example, the `replace-regexp' command sets the mark to -the value of point before doing any replacements, because this enables -the user to move back there conveniently after the replace is finished. - - Once the mark "exists" in a buffer, it normally never ceases to -exist. However, it may become "inactive", and usually does so after -each command (other than simple motion commands and some commands that -explicitly activate the mark). When the mark is active, the region -between point and the mark is called the "active region" and is -highlighted specially. - - Many commands are designed so that when called interactively they -operate on the text between point and the mark. Such commands work -only when an active region exists, i.e. when the mark is active. (The -reason for this is to prevent you from accidentally deleting or -changing large chunks of your text.) If you are writing such a command, -don't examine the mark directly; instead, use `interactive' with the -`r' specification. This provides the values of point and the mark as -arguments to the command in an interactive call, but permits other Lisp -programs to specify arguments explicitly, and automatically signals an -error if the command is called interactively when no active region -exists. *Note Interactive Codes::. - - Each buffer has its own value of the mark that is independent of the -value of the mark in other buffers. (When a buffer is created, the mark -exists but does not point anywhere. We consider this state as "the -absence of a mark in that buffer.") However, only one active region can -exist at a time. Activating the mark in one buffer automatically -deactivates an active mark in any other buffer. Note that the user can -explicitly activate a mark at any time by using the command -`activate-region' (normally bound to `M-C-z') or by using the command -`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the -side effect of activating the mark. - - Some people do not like active regions, so they disable this behavior -by setting the variable `zmacs-regions' to `nil'. This makes the mark -always active (except when a buffer is just created and the mark points -nowhere), and turns off the highlighting of the region between point -and the mark. Commands that explicitly retrieve the value of the mark -should make sure that they behave correctly and consistently -irrespective of the setting of `zmacs-regions'; some primitives are -provided to ensure this behavior. - - In addition to the mark, each buffer has a "mark ring" which is a -list of markers containing previous values of the mark. When editing -commands change the mark, they should normally save the old value of the -mark on the mark ring. The variable `mark-ring-max' specifies the -maximum number of entries in the mark ring; once the list becomes this -long, adding a new element deletes the last element. - - - Function: mark &optional FORCE BUFFER - This function returns BUFFER's mark position as an integer. - BUFFER defaults to the current buffer if omitted. +File: lispref.info, Node: Consoles and Devices, Next: Positions, Prev: Frames, Up: Top + +Consoles and Devices +******************** + + A "console" is an object representing a single input connection to +XEmacs, such as an X display or a TTY connection. It is possible for +XEmacs to have frames on multiple consoles at once (even on +heterogeneous types--you can simultaneously have a frame on an X +display and a TTY connection). Normally, there is only one console in +existence. + + A "device" is an object representing a single output device, such as +a particular screen on an X display. (Usually there is exactly one +device per X console connection, but there may be more than one if you +have a multi-headed X display. For TTY connections, there is always +exactly one device per console.) + + Each device has one or more "frames" in which text can be displayed. +For X displays and the like, a frame corresponds to the normal +window-system concept of a window. Frames can overlap, be displayed at +various locations within the display, be resized, etc. For TTY, only +one frame can be displayed at a time, and it occupies the entire TTY +display area. + + However, you can still define multiple frames and switch between +them. Their contents are entirely separate from each other. These +sorts of frames resemble the "virtual console" capability provided +under Linux or the multiple screens provided by the multiplexing program +`screen' under Unix. + + When you start up XEmacs, an initial console and device are created +to receive input and display frames on. This will either be an X +display or a TTY connection, depending on what mode you started XEmacs +in (this is determined by the `DISPLAY' environment variable, the +`-nw', `-t' and `-display' command-line options, etc.). + + You can connect to other X displays and TTY connections by creating +new console objects, and to other X screens on an existing display by +creating new device objects, as described below. Many functions (for +example the frame-creation functions) take an optional device argument +specifying which device the function pertains to. If the argument is +omitted, it defaults to the selected device (see below). + + - Function: consolep object + This returns non-`nil' if OBJECT is a console. + + - Function: devicep object + This returns non-`nil' if OBJECT is a device. - If the mark is inactive, `mark' normally returns `nil'. However, - if FORCE is non-`nil', then `mark' returns the mark position - anyway--or `nil', if the mark is not yet set for the buffer. - - (Remember that if ZMACS-REGIONS is `nil', the mark is always - active as long as it exists, and the FORCE argument will have no - effect.) - - If you are using this in an editing command, you are most likely - making a mistake; see the documentation of `set-mark' below. - - - Function: mark-marker INACTIVE-P BUFFER - This function returns BUFFER's mark. BUFFER defaults to the - current buffer if omitted. This is the very marker that records - the mark location inside XEmacs, not a copy. Therefore, changing - this marker's position will directly affect the position of the - mark. Don't do it unless that is the effect you want. - - If the mark is inactive, `mark-marker' normally returns `nil'. - However, if FORCE is non-`nil', then `mark-marker' returns the - mark anyway. - (setq m (mark-marker)) - => # - (set-marker m 100) - => # - (mark-marker) - => # - - Like any marker, this marker can be set to point at any buffer you - like. We don't recommend that you make it point at any buffer - other than the one of which it is the mark. If you do, it will - yield perfectly consistent, but rather odd, results. - - - Function: set-mark POSITION &optional BUFFER - This function sets `buffer''s mark to POSITION, and activates the - mark. BUFFER defaults to the current buffer if omitted. The old - value of the mark is *not* pushed onto the mark ring. - - *Please note:* Use this function only if you want the user to see - that the mark has moved, and you want the previous mark position to - be lost. Normally, when a new mark is set, the old one should go - on the `mark-ring'. For this reason, most applications should use - `push-mark' and `pop-mark', not `set-mark'. - - Novice XEmacs Lisp programmers often try to use the mark for the - wrong purposes. The mark saves a location for the user's - convenience. An editing command should not alter the mark unless - altering the mark is part of the user-level functionality of the - command. (And, in that case, this effect should be documented.) - To remember a location for internal use in the Lisp program, store - it in a Lisp variable. For example: - - (let ((beg (point))) - (forward-line 1) - (delete-region beg (point))). - - - Command: exchange-point-and-mark &optional DONT-ACTIVATE-REGION - This function exchanges the positions of point and the mark. It - is intended for interactive use. The mark is also activated - unless DONT-ACTIVATE-REGION is non-`nil'. - - - Function: push-mark &optional POSITION NOMSG ACTIVATE BUFFER - This function sets BUFFER's mark to POSITION, and pushes a copy of - the previous mark onto `mark-ring'. BUFFER defaults to the - current buffer if omitted. If POSITION is `nil', then the value - of point is used. `push-mark' returns `nil'. - - If the last global mark pushed was not in BUFFER, also push - POSITION on the global mark ring (see below). - - The function `push-mark' normally *does not* activate the mark. - To do that, specify `t' for the argument ACTIVATE. - - A `Mark set' message is displayed unless NOMSG is non-`nil'. - - - Function: pop-mark - This function pops off the top element of `mark-ring' and makes - that mark become the buffer's actual mark. This does not move - point in the buffer, and it does nothing if `mark-ring' is empty. - It deactivates the mark. - - The return value is not meaningful. - - - Variable: mark-ring - The value of this buffer-local variable is the list of saved former - marks of the current buffer, most recent first. - - mark-ring - => (# - # - ...) - - - User Option: mark-ring-max - The value of this variable is the maximum size of `mark-ring'. If - more marks than this are pushed onto the `mark-ring', `push-mark' - discards an old mark when it adds a new one. - - In additional to a per-buffer mark ring, there is a "global mark -ring". Marks are pushed onto the global mark ring the first time you -set a mark after switching buffers. - - - Variable: global-mark-ring - The value of this variable is the list of saved former global - marks, most recent first. - - - User Option: mark-ring-max - The value of this variable is the maximum size of - `global-mark-ring'. If more marks than this are pushed onto the - `global-mark-ring', `push-mark' discards an old mark when it adds - a new one. - - - Command: pop-global-mark - This function pops a mark off the global mark ring and jumps to - that location. +* Menu: + +* Basic Console Functions:: Functions for working with consoles. +* Basic Device Functions:: Functions for working with devices. +* Console Types and Device Classes:: + I/O and color characteristics. +* Connecting to a Console or Device:: +* The Selected Console and Device:: +* Console and Device I/O:: Controlling input and output.  -File: lispref.info, Node: The Region, Prev: The Mark, Up: Markers - -The Region -========== - - The text between point and the mark is known as "the region". -Various functions operate on text delimited by point and the mark, but -only those functions specifically related to the region itself are -described here. - - When `zmacs-regions' is non-`nil' (this is the default), the concept -of an "active region" exists. The region is active when the -corresponding mark is active. Note that only one active region at a -time can exist - i.e. only one buffer's region is active at a time. -*Note The Mark::, for more information about active regions. - - - User Option: zmacs-regions - If non-`nil' (the default), active regions are used. *Note The - Mark::, for a detailed explanation of what this means. - - A number of functions are provided for explicitly determining the -bounds of the region and whether it is active. Few programs need to use -these functions, however. A command designed to operate on a region -should normally use `interactive' with the `r' specification to find -the beginning and end of the region. This lets other Lisp programs -specify the bounds explicitly as arguments and automatically respects -the user's setting for ZMACS-REGIONS. (*Note Interactive Codes::.) - - - Function: region-beginning &optional BUFFER - This function returns the position of the beginning of BUFFER's - region (as an integer). This is the position of either point or - the mark, whichever is smaller. BUFFER defaults to the current - buffer if omitted. +File: lispref.info, Node: Basic Console Functions, Next: Basic Device Functions, Up: Consoles and Devices + +Basic Console Functions +======================= + + - Function: console-list + This function returns a list of all existing consoles. + + - Function: console-device-list &optional console + This function returns a list of all devices on CONSOLE. If + CONSOLE is `nil', the selected console will be used. + + +File: lispref.info, Node: Basic Device Functions, Next: Console Types and Device Classes, Prev: Basic Console Functions, Up: Consoles and Devices + +Basic Device Functions +====================== + + - Function: device-list + This function returns a list of all existing devices. + + - Function: device-or-frame-p object + This function returns non-`nil' if OBJECT is a device or frame. + This function is useful because devices and frames are similar in + many respects and many functions can operate on either one. + + - Function: device-frame-list &optional device + This function returns a list of all frames on DEVICE. DEVICE + defaults to the currently selected device. + + - Function: frame-device &optional frame + This function returns the device that FRAME is on. FRAME defaults + to the currently selected frame. + + +File: lispref.info, Node: Console Types and Device Classes, Next: Connecting to a Console or Device, Prev: Basic Device Functions, Up: Consoles and Devices + +Console Types and Device Classes +================================ + + Every device is of a particular "type", which describes how the +connection to that device is made and how the device operates, and a +particular "class", which describes other characteristics of the device +(currently, the color capabilities of the device). + + The currently-defined device types are + +`x' + A connection to an X display (such as `willow:0'). + +`tty' + A connection to a tty (such as `/dev/ttyp3'). + +`stream' + A stdio connection. This describes a device for which input and + output is only possible in a stream-like fashion, such as when + XEmacs in running in batch mode. The very first device created by + XEmacs is a terminal device and is used to print out messages of + various sorts (for example, the help message when you use the + `-help' command-line option). + + The currently-defined device classes are +`color' + A color device. + +`grayscale' + A grayscale device (a device that can display multiple shades of + gray, but no color). - If the mark does not point anywhere, an error is signaled. Note - that this function ignores whether the region is active. +`mono' + A device that can only display two colors (e.g. black and white). - - Function: region-end &optional BUFFER - This function returns the position of the end of BUFFER's region - (as an integer). This is the position of either point or the mark, - whichever is larger. BUFFER defaults to the current buffer if + - Function: device-type &optional device + This function returns the type of DEVICE. This is a symbol whose + name is one of the device types mentioned above. DEVICE defaults + to the selected device. + + - Function: device-or-frame-type device-or-frame + This function returns the type of DEVICE-OR-FRAME. + + - Function: device-class &optional device + This function returns the class (color behavior) of DEVICE. This + is a symbol whose name is one of the device classes mentioned + above. + + - Function: valid-device-type-p device-type + This function returns whether DEVICE-TYPE (which should be a + symbol) specifies a valid device type. + + - Function: valid-device-class-p device-class + This function returns whether DEVICE-CLASS (which should be a + symbol) specifies a valid device class. + + - Variable: terminal-device + This variable holds the initial terminal device object, which + represents XEmacs's stdout. + + +File: lispref.info, Node: Connecting to a Console or Device, Next: The Selected Console and Device, Prev: Console Types and Device Classes, Up: Consoles and Devices + +Connecting to a Console or Device +================================= + + - Function: make-device type connection &optional props + This function creates a new device. + + The following two functions create devices of specific types and are +written in terms of `make-device'. + + - Function: make-tty-device &optional tty terminal-type + This function creates a new tty device on TTY. This also creates + the tty's first frame. TTY should be a string giving the name of + a tty device file (e.g. `/dev/ttyp3' under SunOS et al.), as + returned by the `tty' command issued from the Unix shell. A value + of `nil' means use the stdin and stdout as passed to XEmacs from + the shell. If TERMINAL-TYPE is non-`nil', it should be a string + specifying the type of the terminal attached to the specified tty. + If it is `nil', the terminal type will be inferred from the + `TERM' environment variable. + + - Function: make-x-device &optional display argv-list + This function creates a new device connected to DISPLAY. Optional + argument ARGV-LIST is a list of strings describing command line + options. + + - Function: delete-device device &optional force + This function deletes DEVICE, permanently eliminating it from use. + This disconnects XEmacs's connection to the device. + + - Variable: create-device-hook + This variable, if non-`nil', should contain a list of functions, + which are called when a device is created. + + - Variable: delete-device-hook + This variable, if non-`nil', should contain a list of functions, + which are called when a device is deleted. + + - Function: console-live-p object + This function returns non-`nil' if OBJECT is a console that has + not been deleted. + + - Function: device-live-p object + This function returns non-`nil' if OBJECT is a device that has not + been deleted. + + - Function: device-x-display device + This function returns the X display which DEVICE is connected to, + if DEVICE is an X device. + + +File: lispref.info, Node: The Selected Console and Device, Next: Console and Device I/O, Prev: Connecting to a Console or Device, Up: Consoles and Devices + +The Selected Console and Device +=============================== + + - Function: select-console console + This function selects the console CONSOLE. Subsequent editing + commands apply to its selected device, selected frame, and selected + window. The selection of CONSOLE lasts until the next time the + user does something to select a different console, or until the + next time this function is called. + + - Function: selected-console + This function returns the console which is currently active. + + - Function: select-device device + This function selects the device DEVICE. + + - Function: selected-device &optional console + This function returns the device which is currently active. If + optional CONSOLE is non-`nil', this function returns the device + that would be currently active if CONSOLE were the selected + console. + + +File: lispref.info, Node: Console and Device I/O, Prev: The Selected Console and Device, Up: Consoles and Devices + +Console and Device I/O +====================== + + - Function: console-disable-input console + This function disables input on console CONSOLE. + + - Function: console-enable-input console + This function enables input on console CONSOLE. + + Each device has a "baud rate" value associated with it. On most +systems, changing this value will affect the amount of padding and +other strategic decisions made during redisplay. + + - Function: device-baud-rate &optional device + This function returns the output baud rate of DEVICE. + + - Function: set-device-baud-rate device rate + This function sets the output baud rate of DEVICE to RATE. + + +File: lispref.info, Node: Positions, Next: Markers, Prev: Consoles and Devices, Up: Top + +Positions +********* + + A "position" is the index of a character in the text of a buffer. +More precisely, a position identifies the place between two characters +(or before the first character, or after the last character), so we can +speak of the character before or after a given position. However, we +often speak of the character "at" a position, meaning the character +after that position. + + Positions are usually represented as integers starting from 1, but +can also be represented as "markers"--special objects that relocate +automatically when text is inserted or deleted so they stay with the +surrounding characters. *Note Markers::. + +* Menu: + +* Point:: The special position where editing takes place. +* Motion:: Changing point. +* Excursions:: Temporary motion and buffer changes. +* Narrowing:: Restricting editing to a portion of the buffer. + + +File: lispref.info, Node: Point, Next: Motion, Up: Positions + +Point +===== + + "Point" is a special buffer position used by many editing commands, +including the self-inserting typed characters and text insertion +functions. Other commands move point through the text to allow editing +and insertion at different places. + + Like other positions, point designates a place between two characters +(or before the first character, or after the last character), rather +than a particular character. Usually terminals display the cursor over +the character that immediately follows point; point is actually before +the character on which the cursor sits. + + The value of point is a number between 1 and the buffer size plus 1. +If narrowing is in effect (*note Narrowing::), then point is constrained +to fall within the accessible portion of the buffer (possibly at one end +of it). + + Each buffer has its own value of point, which is independent of the +value of point in other buffers. Each window also has a value of point, +which is independent of the value of point in other windows on the same +buffer. This is why point can have different values in various windows +that display the same buffer. When a buffer appears in only one window, +the buffer's point and the window's point normally have the same value, +so the distinction is rarely important. *Note Window Point::, for more +details. + + - Function: point &optional buffer + This function returns the value of point in BUFFER, as an integer. + BUFFER defaults to the current buffer if omitted. + + (point) + => 175 + + - Function: point-min &optional buffer + This function returns the minimum accessible value of point in + BUFFER. This is normally 1, but if narrowing is in effect, it is + the position of the start of the region that you narrowed to. + (*Note Narrowing::.) BUFFER defaults to the current buffer if omitted. - If the mark does not point anywhere, an error is signaled. Note - that this function ignores whether the region is active. - - - Function: region-exists-p - This function is non-`nil' if the region exists. If active regions - are in use (i.e. `zmacs-regions' is true), this means that the - region is active. Otherwise, this means that the user has pushed - a mark in this buffer at some point in the past. If this function - returns `nil', a function that uses the `r' interactive - specification will cause an error when called interactively. - - - Function: region-active-p - If `zmacs-regions' is true, this is equivalent to - `region-exists-p'. Otherwise, this function always returns false. - This function is used by commands such as - `fill-paragraph-or-region' and `capitalize-region-or-word', which - operate either on the active region or on something else (e.g. the - word or paragraph at point). - - - Variable: zmacs-region-stays - If a command sets this variable to true, the currently active - region will remain activated when the command finishes. (Normally - the region is deactivated when each command terminates.) If - ZMACS-REGIONS is false, however, this has no effect. Under normal - circumstances, you do not need to set this; use the interactive - specification `_' instead, if you want the region to remain active. - - - Function: zmacs-activate-region - This function activates the region in the current buffer (this is - equivalent to activating the current buffer's mark). This will - normally also highlight the text in the active region and set - ZMACS-REGION-STAYS to `t'. (If ZMACS-REGIONS is false, however, - this function has no effect.) - - - Function: zmacs-deactivate-region - This function deactivates the region in the current buffer (this is - equivalent to deactivating the current buffer's mark). This will - normally also unhighlight the text in the active region and set - ZMACS-REGION-STAYS to `nil'. (If ZMACS-REGIONS is false, however, - this function has no effect.) - - - Function: zmacs-update-region - This function updates the active region, if it's currently active. - (If there is no active region, this function does nothing.) This - has the effect of updating the highlighting on the text in the - region; but you should never need to call this except under rather - strange circumstances. The command loop automatically calls it - when appropriate. Calling this function will call the hook - `zmacs-update-region-hook', if the region is active. - - - Variable: zmacs-activate-region-hook - This normal hook is called when a region becomes active. (Usually - this happens as a result of a command that activates the region, - such as `set-mark-command', `activate-region', or - `exchange-point-and-mark'.) Note that calling - `zmacs-activate-region' will call this hook, even if the region is - already active. If ZMACS-REGIONS is false, however, this hook - will never get called under any circumstances. - - - Variable: zmacs-deactivate-region-hook - This normal hook is called when an active region becomes inactive. - (Calling `zmacs-deactivate-region' when the region is inactive will - *not* cause this hook to be called.) If ZMACS-REGIONS is false, - this hook will never get called. - - - Variable: zmacs-update-region-hook - This normal hook is called when an active region is "updated" by - `zmacs-update-region'. This normally gets called at the end of - each command that sets ZMACS-REGION-STAYS to `t', indicating that - the region should remain activated. The motion commands do this. + - Function: point-max &optional buffer + This function returns the maximum accessible value of point in + BUFFER. This is `(1+ (buffer-size buffer))', unless narrowing is + in effect, in which case it is the position of the end of the + region that you narrowed to. (*note Narrowing::). BUFFER defaults + to the current buffer if omitted. + + - Function: buffer-end flag &optional buffer + This function returns `(point-min buffer)' if FLAG is less than 1, + `(point-max buffer)' otherwise. The argument FLAG must be a + number. BUFFER defaults to the current buffer if omitted. + + - Function: buffer-size &optional buffer + This function returns the total number of characters in BUFFER. + In the absence of any narrowing (*note Narrowing::), `point-max' + returns a value one larger than this. BUFFER defaults to the + current buffer if omitted. + + (buffer-size) + => 35 + (point-max) + => 36 + + - Variable: buffer-saved-size + The value of this buffer-local variable is the former length of the + current buffer, as of the last time it was read in, saved or + auto-saved.  -File: lispref.info, Node: Text, Next: Searching and Matching, Prev: Markers, Up: Top - -Text -**** - - This chapter describes the functions that deal with the text in a -buffer. Most examine, insert, or delete text in the current buffer, -often in the vicinity of point. Many are interactive. All the -functions that change the text provide for undoing the changes (*note -Undo::.). - - Many text-related functions operate on a region of text defined by -two buffer positions passed in arguments named START and END. These -arguments should be either markers (*note Markers::.) or numeric -character positions (*note Positions::.). The order of these arguments -does not matter; it is all right for START to be the end of the region -and END the beginning. For example, `(delete-region 1 10)' and -`(delete-region 10 1)' are equivalent. An `args-out-of-range' error is -signaled if either START or END is outside the accessible portion of -the buffer. In an interactive call, point and the mark are used for -these arguments. - - Throughout this chapter, "text" refers to the characters in the -buffer, together with their properties (when relevant). +File: lispref.info, Node: Motion, Next: Excursions, Prev: Point, Up: Positions + +Motion +====== + + Motion functions change the value of point, either relative to the +current value of point, relative to the beginning or end of the buffer, +or relative to the edges of the selected window. *Note Point::. * Menu: -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* Comparing Text:: Comparing substrings of buffers. -* Insertion:: Adding new text to a buffer. -* Commands for Insertion:: User-level commands to insert text. -* Deletion:: Removing text from a buffer. -* User-Level Deletion:: User-level commands to delete text. -* The Kill Ring:: Where removed text sometimes is saved for later use. -* Undo:: Undoing changes to the text of a buffer. -* Maintaining Undo:: How to enable and disable undo information. - How to control how much information is kept. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Sorting:: Functions for sorting parts of the buffer. -* Columns:: Computing horizontal positions, and using them. -* Indentation:: Functions to insert or adjust indentation. -* Case Changes:: Case conversion of parts of the buffer. -* Text Properties:: Assigning Lisp property lists to text characters. -* Substitution:: Replacing a given character wherever it appears. -* Registers:: How registers are implemented. Accessing the text or - position stored in a register. -* Transposition:: Swapping two portions of a buffer. -* Change Hooks:: Supplying functions to be run when text is changed. -* Transformations:: MD5 and base64 support. +* Character Motion:: Moving in terms of characters. +* Word Motion:: Moving in terms of words. +* Buffer End Motion:: Moving to the beginning or end of the buffer. +* Text Lines:: Moving in terms of lines of text. +* Screen Lines:: Moving in terms of lines as displayed. +* List Motion:: Moving by parsing lists and sexps. +* Skipping Characters:: Skipping characters belonging to a certain set.  -File: lispref.info, Node: Near Point, Next: Buffer Contents, Up: Text +File: lispref.info, Node: Character Motion, Next: Word Motion, Up: Motion -Examining Text Near Point -========================= +Motion by Characters +-------------------- - Many functions are provided to look at the characters around point. -Several simple functions are described here. See also `looking-at' in -*Note Regexp Search::. + These functions move point based on a count of characters. +`goto-char' is the fundamental primitive; the other functions use that. - Many of these functions take an optional BUFFER argument. In all -such cases, the current buffer will be used if this argument is -omitted. (In FSF Emacs, and earlier versions of XEmacs, these functions -usually did not have these optional BUFFER arguments and always -operated on the current buffer.) + - Command: goto-char position &optional buffer + This function sets point in `buffer' to the value POSITION. If + POSITION is less than 1, it moves point to the beginning of the + buffer. If POSITION is greater than the length of the buffer, it + moves point to the end. BUFFER defaults to the current buffer if + omitted. - - Function: char-after POSITION &optional BUFFER - This function returns the character in the buffer at (i.e., - immediately after) position POSITION. If POSITION is out of range - for this purpose, either before the beginning of the buffer, or at - or beyond the end, then the value is `nil'. If optional argument - BUFFER is `nil', the current buffer is assumed. + If narrowing is in effect, POSITION still counts from the + beginning of the buffer, but point cannot go outside the accessible + portion. If POSITION is out of range, `goto-char' moves point to + the beginning or the end of the accessible portion. - In the following example, assume that the first character in the - buffer is `@': + When this function is called interactively, POSITION is the + numeric prefix argument, if provided; otherwise it is read from the + minibuffer. - (char-to-string (char-after 1)) - => "@" + `goto-char' returns POSITION. - - Function: following-char &optional BUFFER - This function returns the character following point in the buffer. - This is similar to `(char-after (point))'. However, if point is at - the end of the buffer, then the result of `following-char' is 0. - If optional argument BUFFER is `nil', the current buffer is - assumed. + - Command: forward-char &optional count buffer + This function moves point COUNT characters forward, towards the + end of the buffer (or backward, towards the beginning of the + buffer, if COUNT is negative). If the function attempts to move + point past the beginning or end of the buffer (or the limits of + the accessible portion, when narrowing is in effect), an error is + signaled with error code `beginning-of-buffer' or `end-of-buffer'. + BUFFER defaults to the current buffer if omitted. - Remember that point is always between characters, and the terminal - cursor normally appears over the character following point. - Therefore, the character returned by `following-char' is the - character the cursor is over. + In an interactive call, COUNT is the numeric prefix argument. - In this example, point is between the `a' and the `c'. + - Command: backward-char &optional count buffer + This function moves point COUNT characters backward, towards the + beginning of the buffer (or forward, towards the end of the + buffer, if COUNT is negative). If the function attempts to move + point past the beginning or end of the buffer (or the limits of + the accessible portion, when narrowing is in effect), an error is + signaled with error code `beginning-of-buffer' or `end-of-buffer'. + BUFFER defaults to the current buffer if omitted. - ---------- Buffer: foo ---------- - Gentlemen may cry ``Pea-!-ce! Peace!,'' - but there is no peace. - ---------- Buffer: foo ---------- - - (char-to-string (preceding-char)) - => "a" - (char-to-string (following-char)) - => "c" - - - Function: preceding-char &optional BUFFER - This function returns the character preceding point in the buffer. - See above, under `following-char', for an example. If point is at - the beginning of the buffer, `preceding-char' returns 0. If - optional argument BUFFER is `nil', the current buffer is assumed. - - - Function: bobp &optional BUFFER - This function returns `t' if point is at the beginning of the - buffer. If narrowing is in effect, this means the beginning of the - accessible portion of the text. If optional argument BUFFER is - `nil', the current buffer is assumed. See also `point-min' in - *Note Point::. - - - Function: eobp &optional BUFFER - This function returns `t' if point is at the end of the buffer. - If narrowing is in effect, this means the end of accessible - portion of the text. If optional argument BUFFER is `nil', the - current buffer is assumed. See also `point-max' in *Note Point::. - - - Function: bolp &optional BUFFER - This function returns `t' if point is at the beginning of a line. - If optional argument BUFFER is `nil', the current buffer is - assumed. *Note Text Lines::. The beginning of the buffer (or its - accessible portion) always counts as the beginning of a line. - - - Function: eolp &optional BUFFER - This function returns `t' if point is at the end of a line. The - end of the buffer is always considered the end of a line. If - optional argument BUFFER is `nil', the current buffer is assumed. - The end of the buffer (or of its accessible portion) is always - considered the end of a line. + In an interactive call, COUNT is the numeric prefix argument.  -File: lispref.info, Node: Buffer Contents, Next: Comparing Text, Prev: Near Point, Up: Text +File: lispref.info, Node: Word Motion, Next: Buffer End Motion, Prev: Character Motion, Up: Motion + +Motion by Words +--------------- -Examining Buffer Contents -========================= + These functions for parsing words use the syntax table to decide +whether a given character is part of a word. *Note Syntax Tables::. - This section describes two functions that allow a Lisp program to -convert any portion of the text in the buffer into a string. + - Command: forward-word &optional count buffer + This function moves point forward COUNT words (or backward if + COUNT is negative). Normally it returns `t'. If this motion + encounters the beginning or end of the buffer, or the limits of the + accessible portion when narrowing is in effect, point stops there + and the value is `nil'. - - Function: buffer-substring START END &optional BUFFER - - Function: buffer-string START END &optional BUFFER - These functions are equivalent and return a string containing a - copy of the text of the region defined by positions START and END - in the buffer. If the arguments are not positions in the - accessible portion of the buffer, `buffer-substring' signals an - `args-out-of-range' error. If optional argument BUFFER is `nil', - the current buffer is assumed. + COUNT defaults to `1' and BUFFER defaults to the current buffer. - If the region delineated by START and END contains duplicable - extents, they will be remembered in the string. *Note Duplicable - Extents::. + In an interactive call, COUNT is set to the numeric prefix + argument. - It is not necessary for START to be less than END; the arguments - can be given in either order. But most often the smaller argument - is written first. + - Command: backward-word &optional count buffer + This function is just like `forward-word', except that it moves + backward until encountering the front of a word, rather than + forward. BUFFER defaults to the current buffer if omitted. - ---------- Buffer: foo ---------- - This is the contents of buffer foo - - ---------- Buffer: foo ---------- - - (buffer-substring 1 10) - => "This is t" - (buffer-substring (point-max) 10) - => "he contents of buffer foo - " + In an interactive call, COUNT is set to the numeric prefix + argument. + + - Variable: words-include-escapes + This variable affects the behavior of `forward-word' and everything + that uses it. If it is non-`nil', then characters in the "escape" + and "character quote" syntax classes count as part of words. + Otherwise, they do not. + + +File: lispref.info, Node: Buffer End Motion, Next: Text Lines, Prev: Word Motion, Up: Motion + +Motion to an End of the Buffer +------------------------------ + + To move point to the beginning of the buffer, write: + + (goto-char (point-min)) + +Likewise, to move to the end of the buffer, use: + + (goto-char (point-max)) + + Here are two commands that users use to do these things. They are +documented here to warn you not to use them in Lisp programs, because +they set the mark and display messages in the echo area. + + - Command: beginning-of-buffer &optional count + This function moves point to the beginning of the buffer (or the + limits of the accessible portion, when narrowing is in effect), + setting the mark at the previous position. If COUNT is non-`nil', + then it puts point COUNT tenths of the way from the beginning of + the buffer. + + In an interactive call, COUNT is the numeric prefix argument, if + provided; otherwise COUNT defaults to `nil'. + + Don't use this function in Lisp programs! + + - Command: end-of-buffer &optional count + This function moves point to the end of the buffer (or the limits + of the accessible portion, when narrowing is in effect), setting + the mark at the previous position. If COUNT is non-`nil', then it + puts point COUNT tenths of the way from the end of the buffer. + + In an interactive call, COUNT is the numeric prefix argument, if + provided; otherwise COUNT defaults to `nil'. + + Don't use this function in Lisp programs!  -File: lispref.info, Node: Comparing Text, Next: Insertion, Prev: Buffer Contents, Up: Text +File: lispref.info, Node: Text Lines, Next: Screen Lines, Prev: Buffer End Motion, Up: Motion + +Motion by Text Lines +-------------------- + + Text lines are portions of the buffer delimited by newline +characters, which are regarded as part of the previous line. The first +text line begins at the beginning of the buffer, and the last text line +ends at the end of the buffer whether or not the last character is a +newline. The division of the buffer into text lines is not affected by +the width of the window, by line continuation in display, or by how +tabs and control characters are displayed. + + - Command: goto-line line + This function moves point to the front of the LINEth line, + counting from line 1 at beginning of the buffer. If LINE is less + than 1, it moves point to the beginning of the buffer. If LINE is + greater than the number of lines in the buffer, it moves point to + the end of the buffer--that is, the _end of the last line_ of the + buffer. This is the only case in which `goto-line' does not + necessarily move to the beginning of a line. + + If narrowing is in effect, then LINE still counts from the + beginning of the buffer, but point cannot go outside the accessible + portion. So `goto-line' moves point to the beginning or end of the + accessible portion, if the line number specifies an inaccessible + position. + + The return value of `goto-line' is the difference between LINE and + the line number of the line to which point actually was able to + move (in the full buffer, before taking account of narrowing). + Thus, the value is positive if the scan encounters the real end of + the buffer. The value is zero if scan encounters the end of the + accessible portion but not the real end of the buffer. + + In an interactive call, LINE is the numeric prefix argument if one + has been provided. Otherwise LINE is read in the minibuffer. + + - Command: beginning-of-line &optional count buffer + This function moves point to the beginning of the current line. + With an argument COUNT not `nil' or 1, it moves forward COUNT-1 + lines and then to the beginning of the line. BUFFER defaults to + the current buffer if omitted. + + If this function reaches the end of the buffer (or of the + accessible portion, if narrowing is in effect), it positions point + there. No error is signaled. + + - Command: end-of-line &optional count buffer + This function moves point to the end of the current line. With an + argument COUNT not `nil' or 1, it moves forward COUNT-1 lines and + then to the end of the line. BUFFER defaults to the current + buffer if omitted. + + If this function reaches the end of the buffer (or of the + accessible portion, if narrowing is in effect), it positions point + there. No error is signaled. + + - Command: forward-line &optional count buffer + This function moves point forward COUNT lines, to the beginning of + the line. If COUNT is negative, it moves point -COUNT lines + backward, to the beginning of a line. If COUNT is zero, it moves + point to the beginning of the current line. BUFFER defaults to + the current buffer if omitted. + + If `forward-line' encounters the beginning or end of the buffer (or + of the accessible portion) before finding that many lines, it sets + point there. No error is signaled. + + `forward-line' returns the difference between COUNT and the number + of lines actually moved. If you attempt to move down five lines + from the beginning of a buffer that has only three lines, point + stops at the end of the last line, and the value will be 2. + + In an interactive call, COUNT is the numeric prefix argument. -Comparing Text -============== + - Function: count-lines start end &optional ignore-invisible-lines-flag + This function returns the number of lines between the positions + START and END in the current buffer. If START and END are equal, + then it returns 0. Otherwise it returns at least 1, even if START + and END are on the same line. This is because the text between + them, considered in isolation, must contain at least one line + unless it is empty. - This function lets you compare portions of the text in a buffer, -without copying them into strings first. + With optional IGNORE-INVISIBLE-LINES-FLAG non-`nil', lines + collapsed with selective-display are excluded from the line count. - - Function: compare-buffer-substrings BUFFER1 START1 END1 BUFFER2 - START2 END2 - This function lets you compare two substrings of the same buffer - or two different buffers. The first three arguments specify one - substring, giving a buffer and two positions within the buffer. - The last three arguments specify the other substring in the same - way. You can use `nil' for BUFFER1, BUFFER2, or both to stand for - the current buffer. + *Note:* The expression to return the current line number is not + obvious: - The value is negative if the first substring is less, positive if - the first is greater, and zero if they are equal. The absolute - value of the result is one plus the index of the first differing - characters within the substrings. + (1+ (count-lines 1 (point-at-bol))) - This function ignores case when comparing characters if - `case-fold-search' is non-`nil'. It always ignores text - properties. + Here is an example of using `count-lines': - Suppose the current buffer contains the text `foobarbar - haha!rara!'; then in this example the two substrings are `rbar ' - and `rara!'. The value is 2 because the first substring is greater - at the second character. + (defun current-line () + "Return the vertical position of point..." + (+ (count-lines (window-start) (point)) + (if (= (current-column) 0) 1 0) + -1)) - (compare-buffer-substring nil 6 11 nil 16 21) - => 2 + Also see the functions `bolp' and `eolp' in *Note Near Point::. +These functions do not move point, but test whether it is already at the +beginning or end of a line.  -File: lispref.info, Node: Insertion, Next: Commands for Insertion, Prev: Comparing Text, Up: Text - -Inserting Text -============== - - "Insertion" means adding new text to a buffer. The inserted text -goes at point--between the character before point and the character -after point. - - Insertion relocates markers that point at positions after the -insertion point, so that they stay with the surrounding text (*note -Markers::.). When a marker points at the place of insertion, insertion -normally doesn't relocate the marker, so that it points to the -beginning of the inserted text; however, certain special functions such -as `insert-before-markers' relocate such markers to point after the -inserted text. - - Some insertion functions leave point before the inserted text, while -other functions leave it after. We call the former insertion "after -point" and the latter insertion "before point". - - If a string with non-`nil' extent data is inserted, the remembered -extents will also be inserted. *Note Duplicable Extents::. - - Insertion functions signal an error if the current buffer is -read-only. - - These functions copy text characters from strings and buffers along -with their properties. The inserted characters have exactly the same -properties as the characters they were copied from. By contrast, -characters specified as separate arguments, not part of a string or -buffer, inherit their text properties from the neighboring text. - - - Function: insert &rest ARGS - This function inserts the strings and/or characters ARGS into the - current buffer, at point, moving point forward. In other words, it - inserts the text before point. An error is signaled unless all - ARGS are either strings or characters. The value is `nil'. - - - Function: insert-before-markers &rest ARGS - This function inserts the strings and/or characters ARGS into the - current buffer, at point, moving point forward. An error is - signaled unless all ARGS are either strings or characters. The - value is `nil'. - - This function is unlike the other insertion functions in that it - relocates markers initially pointing at the insertion point, to - point after the inserted text. - - - Function: insert-string STRING &optional BUFFER - This function inserts STRING into BUFFER before point. BUFFER - defaults to the current buffer if omitted. This function is - chiefly useful if you want to insert a string in a buffer other - than the current one (otherwise you could just use `insert'). - - - Function: insert-char CHARACTER COUNT &optional BUFFER - This function inserts COUNT instances of CHARACTER into BUFFER - before point. COUNT must be a number, and CHARACTER must be a - character. The value is `nil'. If optional argument BUFFER is - `nil', the current buffer is assumed. (In FSF Emacs, the third - argument is called INHERIT and refers to text properties.) - - - Function: insert-buffer-substring FROM-BUFFER-OR-NAME &optional - START END - This function inserts a portion of buffer FROM-BUFFER-OR-NAME - (which must already exist) into the current buffer before point. - The text inserted is the region from START and END. (These - arguments default to the beginning and end of the accessible - portion of that buffer.) This function returns `nil'. - - In this example, the form is executed with buffer `bar' as the - current buffer. We assume that buffer `bar' is initially empty. +File: lispref.info, Node: Screen Lines, Next: List Motion, Prev: Text Lines, Up: Motion + +Motion by Screen Lines +---------------------- + + The line functions in the previous section count text lines, +delimited only by newline characters. By contrast, these functions +count screen lines, which are defined by the way the text appears on +the screen. A text line is a single screen line if it is short enough +to fit the width of the selected window, but otherwise it may occupy +several screen lines. + + In some cases, text lines are truncated on the screen rather than +continued onto additional screen lines. In these cases, +`vertical-motion' moves point much like `forward-line'. *Note +Truncation::. + + Because the width of a given string depends on the flags that control +the appearance of certain characters, `vertical-motion' behaves +differently, for a given piece of text, depending on the buffer it is +in, and even on the selected window (because the width, the truncation +flag, and display table may vary between windows). *Note Usual +Display::. + + These functions scan text to determine where screen lines break, and +thus take time proportional to the distance scanned. If you intend to +use them heavily, Emacs provides caches which may improve the +performance of your code. *Note cache-long-line-scans: Text Lines. + + - Function: vertical-motion count &optional window pixels + This function moves point to the start of the frame line COUNT + frame lines down from the frame line containing point. If COUNT + is negative, it moves up instead. The optional second argument + WINDOW may be used to specify a window other than the selected + window in which to perform the motion. + + Normally, `vertical-motion' returns the number of lines moved. The + value may be less in absolute value than COUNT if the beginning or + end of the buffer was reached. If the optional third argument, + PIXELS is non-`nil', the vertical pixel height of the motion which + took place is returned instead of the actual number of lines + moved. A motion of zero lines returns the height of the current + line. + + Note that `vertical-motion' sets WINDOW's buffer's point, not + WINDOW's point. (This differs from FSF Emacs, which buggily always + sets current buffer's point, regardless of WINDOW.) + + - Function: vertical-motion-pixels count &optional window how + This function moves point to the start of the frame line PIXELS + vertical pixels down from the frame line containing point, or up if + PIXELS is negative. The optional second argument WINDOW is the + window to move in, and defaults to the selected window. The + optional third argument HOW specifies the stopping condition. A + negative integer indicates that the motion should be no more than + PIXELS. A positive value indicates that the motion should be at + least PIXELS. Any other value indicates that the motion should be + as close as possible to PIXELS. + + - Command: move-to-window-line count &optional window + This function moves point with respect to the text currently + displayed in WINDOW, which defaults to the selected window. It + moves point to the beginning of the screen line COUNT screen lines + from the top of the window. If COUNT is negative, that specifies a + position -COUNT lines from the bottom (or the last line of the + buffer, if the buffer ends above the specified screen position). + + If COUNT is `nil', then point moves to the beginning of the line + in the middle of the window. If the absolute value of COUNT is + greater than the size of the window, then point moves to the place + that would appear on that screen line if the window were tall + enough. This will probably cause the next redisplay to scroll to + bring that location onto the screen. + + In an interactive call, COUNT is the numeric prefix argument. + + The value returned is the window line number point has moved to, + with the top line in the window numbered 0. + + +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: +(xemacs)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 count + This function moves backward across COUNT balanced groups of + parentheses. (Other syntactic entities such as words or paired + string quotes are ignored.) COUNT defaults to 1 if omitted. If + COUNT is negative, move forward across that many groups of + parentheses. + + - Command: up-list &optional count + This function moves forward out of COUNT levels of parentheses. A + negative argument means move backward but still to a less deep + spot. + + - Command: down-list &optional count + This function moves forward into COUNT levels of parentheses. A + negative argument means move backward but still go deeper in + parentheses (-COUNT levels). + + - Command: forward-sexp &optional count + This function moves forward across COUNT balanced expressions. + Balanced expressions include both those delimited by parentheses + and other kinds, such as words and string constants. COUNT + defaults to 1 if omitted. If COUNT is negative, move backward + across that many balanced expressions. For example, ---------- Buffer: foo ---------- - We hold these truths to be self-evident, that all + (concat-!- "foo " (car x) y z) ---------- Buffer: foo ---------- - (insert-buffer-substring "foo" 1 20) + (forward-sexp 3) => nil - ---------- Buffer: bar ---------- - We hold these truth-!- - ---------- Buffer: bar ---------- + ---------- Buffer: foo ---------- + (concat "foo " (car x) y-!- z) + ---------- Buffer: foo ---------- + + - Command: backward-sexp &optional count + This function moves backward across COUNT balanced expressions. + COUNT defaults to 1 if omitted. If COUNT is negative, move + forward across that many balanced expressions. + + - Command: beginning-of-defun &optional count + This function moves back to the COUNTth beginning of a defun. If + COUNT is negative, this actually moves forward, but it still moves + to the beginning of a defun, not to the end of one. COUNT + defaults to 1 if omitted. + + - Command: end-of-defun &optional count + This function moves forward to the COUNTth end of a defun. If + COUNT is negative, this actually moves backward, but it still + moves to the end of a defun, not to the beginning of one. COUNT + 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.