Mercurial > hg > xemacs-beta
annotate man/lispref/os.texi @ 5353:38e24b8be4ea
Improve the lexical scoping in #'block, #'return-from.
lisp/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el:
* bytecomp.el (byte-compile-initial-macro-environment):
Shadow `block', `return-from' here, we implement them differently
when byte-compiling.
* bytecomp.el (byte-compile-active-blocks): New.
* bytecomp.el (byte-compile-block-1): New.
* bytecomp.el (byte-compile-return-from-1): New.
* bytecomp.el (return-from-1): New.
* bytecomp.el (block-1): New.
These are two aliases that exist to have their own associated
byte-compile functions, which functions implement `block' and
`return-from'.
* cl-extra.el (cl-macroexpand-all):
Fix a bug here when macros in the environment have been compiled.
* cl-macs.el (block):
* cl-macs.el (return):
* cl-macs.el (return-from):
Be more careful about lexical scope in these macros.
* cl.el:
* cl.el ('cl-block-wrapper): Removed.
* cl.el ('cl-block-throw): Removed.
These aren't needed in code generated by this XEmacs. They
shouldn't be needed in code generated by XEmacs 21.4, but if it
turns out the packages do need them, we can put them back.
2011-01-30 Mike Sperber <mike@xemacs.org>
* font-lock.el (font-lock-fontify-pending-extents): Don't fail if
`font-lock-mode' is unset, which can happen in the middle of
`revert-buffer'.
2011-01-23 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete):
* cl-macs.el (delq):
* cl-macs.el (remove):
* cl-macs.el (remq):
Don't use the compiler macro if these functions were given the
wrong number of arguments, as happens in lisp-tests.el.
* cl-seq.el (remove, remq): Removed.
I added these to subr.el, and forgot to remove them from here.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-setq, byte-compile-set):
Remove kludge allowing keywords' values to be set, all the code
that does that is gone.
* cl-compat.el (elt-satisfies-test-p):
* faces.el (set-face-parent):
* faces.el (face-doc-string):
* gtk-font-menu.el:
* gtk-font-menu.el (gtk-reset-device-font-menus):
* msw-font-menu.el:
* msw-font-menu.el (mswindows-reset-device-font-menus):
* package-get.el (package-get-installedp):
* select.el (select-convert-from-image-data):
* sound.el:
* sound.el (load-sound-file):
* x-font-menu.el (x-reset-device-font-menus-core):
Don't quote keywords, they're self-quoting, and the
win from backward-compatibility is sufficiently small now that the
style problem overrides it.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (block, return-from): Require that NAME be a symbol
in these macros, as always documented in the #'block docstring and
as required by Common Lisp.
* descr-text.el (unidata-initialize-unihan-database):
Correct the use of non-symbols in #'block and #'return-from in
this function.
2011-01-15 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (concatenate): Accept more complicated TYPEs in this
function, handing the sequences over to #'coerce if we don't
understand them here.
* cl-macs.el (inline): Don't proclaim #'concatenate as inline, its
compiler macro is more useful than doing that.
2011-01-11 Aidan Kehoe <kehoea@parhasard.net>
* subr.el (delete, delq, remove, remq): Move #'remove, #'remq
here, they don't belong in cl-seq.el; move #'delete, #'delq here
from fns.c, implement them in terms of #'delete*, allowing support
for sequences generally.
* update-elc.el (do-autoload-commands): Use #'delete*, not #'delq
here, now the latter's no longer dumped.
* cl-macs.el (delete, delq): Add compiler macros transforming
#'delete and #'delq to #'delete* calls.
2011-01-10 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box): Correct a misplaced parenthesis
here, thank you Mats Lidell in 87zkr9gqrh.fsf@mail.contactor.se !
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box):
* list-mode.el (display-completion-list):
These functions used to use cl-parsing-keywords; change them to
use defun* instead, fixing the build. (Not sure what led to me
not including this change in d1b17a33450b!)
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (define-star-compiler-macros):
Make sure the form has ITEM and LIST specified before attempting
to change to calls with explicit tests; necessary for some tests
in lisp-tests.el to compile correctly.
(stable-union, stable-intersection): Add compiler macros for these
functions, in the same way we do for most of the other functions
in cl-seq.el.
2011-01-01 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (dolist, dotimes, do-symbols, macrolet)
(symbol-macrolet):
Define these macros with defmacro* instead of parsing the argument
list by hand, for the sake of style and readability; use backquote
where appropriate, instead of calling #'list and and friends, for
the same reason.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* x-misc.el (device-x-display):
Provide this function, documented in the Lispref for years, but
not existing previously. Thank you Julian Bradfield, thank you
Jeff Mincy.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl-seq.el:
Move the heavy lifting from this file to C. Dump the
cl-parsing-keywords macro, but don't use defun* for the functions
we define that do take keywords, dynamic scope lossage makes that
not practical.
* subr.el (sort, fillarray): Move these aliases here.
(map-plist): #'nsublis is now built-in, but at this point #'eql
isn't necessarily available as a test; use #'eq.
* obsolete.el (cl-delete-duplicates): Make this available for old
compiler macros and old code.
(memql): Document that this is equivalent to #'member*, and worse.
* cl.el (adjoin, subst): Removed. These are in C.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* simple.el (assoc-ignore-case): Remove a duplicate definition of
this function (it's already in subr.el).
* iso8859-1.el (char-width):
On non-Mule, make this function equivalent to that produced by
(constantly 1), but preserve its docstring.
* subr.el (subst-char-in-string): Define this in terms of
#'substitute, #'nsubstitute.
(string-width): Define this using #'reduce and #'char-width.
(char-width): Give this a simpler definition, it makes far more
sense to check for mule at load time and redefine, as we do in
iso8859-1.el.
(store-substring): Implement this in terms of #'replace, now
#'replace is cheap.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* update-elc.el (lisp-files-needed-for-byte-compilation)
(lisp-files-needing-early-byte-compilation):
cl-macs belongs in the former, not the latter, it is as
fundamental as bytecomp.el.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl.el:
Provde the Common Lisp program-error, type-error as error
symbols. This doesn't nearly go far enough for anyone using the
Common Lisp errors.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete-duplicates):
If the form has an incorrect number of arguments, don't attempt a
compiler macroexpansion.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (cl-safe-expr-p):
Forms that start with the symbol lambda are also safe.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
For these functions' compiler macros, the optimisation is safe
even if the first and the last arguments have side effects, since
they're only used the once.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (inline-side-effect-free-compiler-macros):
Unroll a loop here at macro-expansion time, so these compiler
macros are compiled. Use #'eql instead of #'eq in a couple of
places for better style.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (notany, notevery): Avoid some dynamic scope
stupidity with local variable names in these functions, when they
weren't prefixed with cl-; go into some more detail in the doc
strings.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns): #'remove, #'remq are
free of side-effects.
(side-effect-and-error-free-fns):
Drop dot, dot-marker from the list.
2010-11-17 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (coerce):
In the argument list, name the first argument OBJECT, not X; the
former name was always used in the doc string and is clearer.
Handle vector type specifications which include the length of the
target sequence, error if there's a mismatch.
* cl-macs.el (cl-make-type-test): Handle type specifications
starting with the symbol 'eql.
2010-11-14 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (eql): Don't remove the byte-compile property of this
symbol. That was necessary to override a bug in bytecomp.el where
#'eql was confused with #'eq, which bug we no longer have.
If neither expression is constant, don't attempt to handle the
expression in this compiler macro, leave it to byte-compile-eql,
which produces better code anyway.
* bytecomp.el (eq): #'eql is not the function associated with the
byte-eq byte code.
(byte-compile-eql): Add an explicit compile method for this
function, for cases where the cl-macs compiler macro hasn't
reduced it to #'eq or #'equal.
2010-10-25 Aidan Kehoe <kehoea@parhasard.net>
Add compiler macros and compilation sanity-checking for various
functions that take keywords.
* byte-optimize.el (side-effect-free-fns): #'symbol-value is
side-effect free and not error free.
* bytecomp.el (byte-compile-normal-call): Check keyword argument
lists for sanity; store information about the positions where
keyword arguments start using the new byte-compile-keyword-start
property.
* cl-macs.el (cl-const-expr-val): Take a new optional argument,
cl-not-constant, defaulting to nil, in this function; return it if
the expression is not constant.
(cl-non-fixnum-number-p): Make this into a separate function, we
want to pass it to #'every.
(eql): Use it.
(define-star-compiler-macros): Use the same code to generate the
member*, assoc* and rassoc* compiler macros; special-case some
code in #'add-to-list in subr.el.
(remove, remq): Add compiler macros for these two functions, in
preparation for #'remove being in C.
(define-foo-if-compiler-macros): Transform (remove-if-not ...) calls to
(remove ... :if-not) at compile time, which will be a real win
once the latter is in C.
(define-substitute-if-compiler-macros)
(define-subst-if-compiler-macros): Similarly for these functions.
(delete-duplicates): Change this compiler macro to use
#'plists-equal; if we don't have information about the type of
SEQUENCE at compile time, don't bother attempting to inline the
call, the function will be in C soon enough.
(equalp): Remove an old commented-out compiler macro for this, if
we want to see it it's in version control.
(subst-char-in-string): Transform this to a call to nsubstitute or
nsubstitute, if that is appropriate.
* cl.el (ldiff): Don't call setf here, this makes for a load-time
dependency problem in cl-macs.el
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* term/vt100.el:
Refer to XEmacs, not GNU Emacs, in permissions.
* term/bg-mouse.el:
* term/sup-mouse.el:
Put copyright notice in canonical "Copyright DATE AUTHOR" form.
Refer to XEmacs, not GNU Emacs, in permissions.
* site-load.el:
Add permission boilerplate.
* mule/canna-leim.el:
* alist.el:
Refer to XEmacs, not APEL/this program, in permissions.
* mule/canna-leim.el:
Remove my copyright, I've assigned it to the FSF.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* gtk.el:
* gtk-widget-accessors.el:
* gtk-package.el:
* gtk-marshal.el:
* gtk-compose.el:
* gnome.el:
Add copyright notice based on internal evidence.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* easymenu.el: Add reference to COPYING to permission notice.
* gutter.el:
* gutter-items.el:
* menubar-items.el:
Fix typo "Xmacs" in permissions notice.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* auto-save.el:
* font.el:
* fontconfig.el:
* mule/kinsoku.el:
Add "part of XEmacs" text to permission notice.
2010-10-14 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns):
* cl-macs.el (remf, getf):
* cl-extra.el (tailp, cl-set-getf, cl-do-remf):
* cl.el (ldiff, endp):
Tighten up Common Lisp compatibility for #'ldiff, #'endp, #'tailp;
add circularity checking for the first two.
#'cl-set-getf and #'cl-do-remf were Lisp implementations of
#'plist-put and #'plist-remprop; change the names to aliases,
changes the macros that use them to using #'plist-put and
#'plist-remprop directly.
2010-10-12 Aidan Kehoe <kehoea@parhasard.net>
* abbrev.el (fundamental-mode-abbrev-table, global-abbrev-table):
Create both these abbrev tables using the usual
#'define-abbrev-table calls, rather than attempting to
special-case them.
* cl-extra.el: Force cl-macs to be loaded here, if cl-extra.el is
being loaded interpreted. Previously other, later files would
redundantly call (load "cl-macs") when interpreted, it's more
reasonable to do it here, once.
* cmdloop.el (read-quoted-char-radix): Use defcustom here, we
don't have any dump-order dependencies that would prevent that.
* custom.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling, rely on cl-extra.el in the
former case and the appropriate entry in bytecomp-load-hook in the
latter. Get rid of custom-declare-variable-list, we have no
dump-time dependencies that would require it.
* faces.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling.
* packages.el: Remove some inaccurate comments.
* post-gc.el (cleanup-simple-finalizers): Use #'delete-if-not
here, now the order of preloaded-file-list has been changed to
make it available.
* subr.el (custom-declare-variable-list): Remove. No need for it.
Also remove a stub define-abbrev-table from this file, given the
current order of preloaded-file-list there's no need for it.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-constp) Forms quoted with FUNCTION are
also constant.
(byte-compile-initial-macro-environment): In #'the, if FORM is
constant and does not match TYPE, warn at byte-compile time.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* backquote.el (bq-vector-contents, bq-list*): Remove; the former
is equivalent to (append VECTOR nil), the latter to (list* ...).
(bq-process-2): Use (append VECTOR nil) instead of using
#'bq-vector-contents to convert to a list.
(bq-process-1): Now we use list* instead of bq-list
* subr.el (list*): Moved from cl.el, since it is now required to
be available the first time a backquoted form is encountered.
* cl.el (list*): Move to subr.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* test-harness.el (Check-Message):
Add an omitted comma here, thank you the buildbot.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* hash-table.el (hash-table-key-list, hash-table-value-list)
(hash-table-key-value-alist, hash-table-key-value-plist):
Remove some useless #'nreverse calls in these files; our hash
tables have no order, it's not helpful to pretend they do.
* behavior.el (read-behavior):
Do the same in this file, in some code evidently copied from
hash-table.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* info.el (Info-insert-dir):
* format.el (format-deannotate-region):
* files.el (cd, save-buffers-kill-emacs):
Use #'some, #'every and related functions for applying boolean
operations to lists, instead of rolling our own ones that cons and
don't short-circuit.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-initial-macro-environment):
* cl-macs.el (the):
Rephrase the docstring, make its implementation when compiling
files a little nicer.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* descr-text.el (unidata-initialize-unicodedata-database)
(unidata-initialize-unihan-database, describe-char-unicode-data)
(describe-char-unicode-data):
Wrap calls to the database functions with (with-fboundp ...),
avoiding byte compile warnings on builds without support for the
database functions.
(describe-char): (reduce #'max ...), not (apply #'max ...), no
need to cons needlessly.
(describe-char): Remove a redundant lambda wrapping
#'extent-properties.
(describe-char-unicode-data): Call #'nsubst when replacing "" with
nil in the result of #'split-string, instead of consing inside
mapcar.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* x-faces.el (x-available-font-sizes):
* specifier.el (let-specifier):
* package-ui.el (pui-add-required-packages):
* msw-faces.el (mswindows-available-font-sizes):
* modeline.el (modeline-minor-mode-menu):
* minibuf.el (minibuf-directory-files):
Replace the O2N (delq nil (mapcar (lambda (W) (and X Y)) Z)) with
the ON (mapcan (lambda (W) (and X (list Y))) Z) in these files.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
When these functions are handed more than two arguments, and those
arguments have no side effects, transform to a series of two
argument calls, avoiding funcall in the byte-compiled code.
* mule/mule-cmds.el (finish-set-language-environment):
Take advantage of this change in a function called 256 times at
startup.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-function-form, byte-compile-quote)
(byte-compile-quote-form):
Warn at compile time, and error at runtime, if a (quote ...) or a
(function ...) form attempts to quote more than one object.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (byte-optimize-apply): Transform (apply 'nconc
(mapcar ...)) to (mapcan ...); warn about use of the first idiom.
* update-elc.el (do-autoload-commands):
* packages.el (packages-find-package-library-path):
* frame.el (frame-list):
* extents.el (extent-descendants):
* etags.el (buffer-tag-table-files):
* dumped-lisp.el (preloaded-file-list):
* device.el (device-list):
* bytecomp-runtime.el (proclaim-inline, proclaim-notinline)
Use #'mapcan, not (apply #'nconc (mapcar ...) in all these files.
* bytecomp-runtime.el (eval-when-compile, eval-and-compile):
In passing, mention that these macros also evaluate the body when
interpreted.
tests/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Test lexical scope for `block', `return-from'; add a
Known-Bug-Expect-Failure for a contorted example that fails when
byte-compiled.
author | Aidan Kehoe <kehoea@parhasard.net> |
---|---|
date | Mon, 07 Feb 2011 12:01:24 +0000 |
parents | 1537701f08a1 |
children | 3d1f8f0e690f |
rev | line source |
---|---|
428 | 1 @c -*-texinfo-*- |
2 @c This is part of the XEmacs Lisp Reference Manual. | |
444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
428 | 4 @c See the file lispref.texi for copying conditions. |
5 @setfilename ../../info/os.info | |
6 @node System Interface, X-Windows, Processes, Top | |
7 @chapter Operating System Interface | |
8 | |
9 This chapter is about starting and getting out of Emacs, access to | |
10 values in the operating system environment, and terminal input, output, | |
11 and flow control. | |
12 | |
13 @xref{Building XEmacs}, for related information. See also | |
14 @ref{Display}, for additional operating system status information | |
15 pertaining to the terminal and the screen. | |
16 | |
17 @menu | |
18 * Starting Up:: Customizing XEmacs start-up processing. | |
19 * Getting Out:: How exiting works (permanent or temporary). | |
20 * System Environment:: Distinguish the name and kind of system. | |
21 * User Identification:: Finding the name and user id of the user. | |
22 * Time of Day:: Getting the current time. | |
23 * Time Conversion:: Converting a time from numeric form to a string, or | |
24 to calendrical data (or vice versa). | |
25 * Timers:: Setting a timer to call a function at a certain time. | |
26 * Terminal Input:: Recording terminal input for debugging. | |
27 * Terminal Output:: Recording terminal output for debugging. | |
28 * Flow Control:: How to turn output flow control on or off. | |
29 * Batch Mode:: Running XEmacs without terminal interaction. | |
30 @end menu | |
31 @ignore | |
32 * Special Keysyms:: Defining system-specific key symbols for X windows. | |
33 @end ignore | |
34 | |
35 @node Starting Up | |
36 @section Starting Up XEmacs | |
37 | |
38 This section describes what XEmacs does when it is started, and how you | |
39 can customize these actions. | |
40 | |
41 @menu | |
42 * Start-up Summary:: Sequence of actions XEmacs performs at start-up. | |
43 * Init File:: Details on reading the init file (@file{.emacs}). | |
44 * Terminal-Specific:: How the terminal-specific Lisp file is read. | |
45 * Command Line Arguments:: How command line arguments are processed, | |
46 and how you can customize them. | |
47 @end menu | |
48 | |
49 @node Start-up Summary | |
50 @subsection Summary: Sequence of Actions at Start Up | |
51 @cindex initialization | |
52 @cindex start up of XEmacs | |
53 @cindex @file{startup.el} | |
54 | |
55 The order of operations performed (in @file{startup.el}) by XEmacs when | |
56 it is started up is as follows: | |
57 | |
58 @enumerate | |
59 @item | |
60 It loads the initialization library for the window system, if you are | |
61 using a window system. This library's name is | |
62 @file{term/@var{windowsystem}-win.el}. | |
63 | |
64 @item | |
65 It processes the initial options. (Some of them are handled | |
66 even earlier than this.) | |
67 | |
68 @item | |
69 It initializes the X window frame and faces, if appropriate. | |
70 | |
71 @item | |
72 It runs the normal hook @code{before-init-hook}. | |
73 | |
74 @item | |
75 It loads the library @file{site-start}, unless the option | |
76 @samp{-no-site-file} was specified. The library's file name is usually | |
77 @file{site-start.el}. | |
78 @cindex @file{site-start.el} | |
79 | |
444 | 80 @item |
428 | 81 It loads the file @file{~/.emacs} unless @samp{-q} was specified on |
82 the command line. (This is not done in @samp{-batch} mode.) The @samp{-u} | |
83 option can specify the user name whose home directory should be used | |
84 instead of @file{~}. | |
85 | |
444 | 86 @item |
428 | 87 It loads the library @file{default} unless @code{inhibit-default-init} |
88 is non-@code{nil}. (This is not done in @samp{-batch} mode or if | |
89 @samp{-q} was specified on the command line.) The library's file name | |
90 is usually @file{default.el}. | |
91 @cindex @file{default.el} | |
92 | |
93 @item | |
94 It runs the normal hook @code{after-init-hook}. | |
95 | |
96 @item | |
97 It sets the major mode according to @code{initial-major-mode}, provided | |
98 the buffer @samp{*scratch*} is still current and still in Fundamental | |
99 mode. | |
100 | |
444 | 101 @item |
428 | 102 It loads the terminal-specific Lisp file, if any, except when in batch |
103 mode or using a window system. | |
104 | |
105 @item | |
106 It displays the initial echo area message, unless you have suppressed | |
107 that with @code{inhibit-startup-echo-area-message}. | |
108 | |
444 | 109 @item |
428 | 110 It processes the action arguments from the command line. |
111 | |
444 | 112 @item |
428 | 113 It runs @code{term-setup-hook}. |
114 | |
115 @item | |
116 It calls @code{frame-notice-user-settings}, which modifies the | |
117 parameters of the selected frame according to whatever the init files | |
118 specify. | |
119 | |
444 | 120 @item |
428 | 121 It runs @code{window-setup-hook}. @xref{Terminal-Specific}. |
122 | |
444 | 123 @item |
428 | 124 It displays copyleft, nonwarranty, and basic use information, provided |
125 there were no remaining command line arguments (a few steps above) and | |
126 the value of @code{inhibit-startup-message} is @code{nil}. | |
127 @end enumerate | |
128 | |
129 @defopt inhibit-startup-message | |
130 This variable inhibits the initial startup messages (the nonwarranty, | |
131 etc.). If it is non-@code{nil}, then the messages are not printed. | |
132 | |
133 This variable exists so you can set it in your personal init file, once | |
134 you are familiar with the contents of the startup message. Do not set | |
135 this variable in the init file of a new user, or in a way that affects | |
136 more than one user, because that would prevent new users from receiving | |
137 the information they are supposed to see. | |
138 @end defopt | |
139 | |
140 @defopt inhibit-startup-echo-area-message | |
141 This variable controls the display of the startup echo area message. | |
142 You can suppress the startup echo area message by adding text with this | |
143 form to your @file{.emacs} file: | |
144 | |
145 @example | |
146 (setq inhibit-startup-echo-area-message | |
147 "@var{your-login-name}") | |
148 @end example | |
149 | |
150 Simply setting @code{inhibit-startup-echo-area-message} to your login | |
151 name is not sufficient to inhibit the message; Emacs explicitly checks | |
152 whether @file{.emacs} contains an expression as shown above. Your login | |
153 name must appear in the expression as a Lisp string constant. | |
154 | |
155 This way, you can easily inhibit the message for yourself if you wish, | |
156 but thoughtless copying of your @file{.emacs} file will not inhibit the | |
157 message for someone else. | |
158 @end defopt | |
159 | |
160 @node Init File | |
161 @subsection The Init File: @file{.emacs} | |
162 @cindex init file | |
163 @cindex @file{.emacs} | |
164 | |
165 When you start XEmacs, it normally attempts to load the file | |
166 @file{.emacs} from your home directory. This file, if it exists, must | |
167 contain Lisp code. It is called your @dfn{init file}. The command line | |
168 switches @samp{-q} and @samp{-u} affect the use of the init file; | |
169 @samp{-q} says not to load an init file, and @samp{-u} says to load a | |
170 specified user's init file instead of yours. @xref{Entering XEmacs,,, | |
171 xemacs, The XEmacs User's Manual}. | |
172 | |
173 @cindex default init file | |
174 A site may have a @dfn{default init file}, which is the library named | |
175 @file{default.el}. XEmacs finds the @file{default.el} file through the | |
176 standard search path for libraries (@pxref{How Programs Do Loading}). | |
177 The XEmacs distribution does not come with this file; sites may provide | |
178 one for local customizations. If the default init file exists, it is | |
179 loaded whenever you start Emacs, except in batch mode or if @samp{-q} is | |
180 specified. But your own personal init file, if any, is loaded first; if | |
181 it sets @code{inhibit-default-init} to a non-@code{nil} value, then | |
182 XEmacs does not subsequently load the @file{default.el} file. | |
183 | |
184 Another file for site-customization is @file{site-start.el}. Emacs | |
185 loads this @emph{before} the user's init file. You can inhibit the | |
186 loading of this file with the option @samp{-no-site-file}. | |
187 | |
188 @defvar site-run-file | |
189 This variable specifies the site-customization file to load | |
190 before the user's init file. Its normal value is @code{"site-start"}. | |
191 @end defvar | |
192 | |
193 If there is a great deal of code in your @file{.emacs} file, you | |
194 should move it into another file named @file{@var{something}.el}, | |
195 byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs} | |
196 file load the other file using @code{load} (@pxref{Loading}). | |
197 | |
198 @xref{Init File Examples,,, xemacs, The XEmacs User's Manual}, for | |
199 examples of how to make various commonly desired customizations in your | |
200 @file{.emacs} file. | |
201 | |
202 @defopt inhibit-default-init | |
203 This variable prevents XEmacs from loading the default initialization | |
204 library file for your session of XEmacs. If its value is non-@code{nil}, | |
205 then the default library is not loaded. The default value is | |
206 @code{nil}. | |
207 @end defopt | |
208 | |
209 @defvar before-init-hook | |
210 @defvarx after-init-hook | |
211 These two normal hooks are run just before, and just after, loading of | |
212 the user's init file, @file{default.el}, and/or @file{site-start.el}. | |
213 @end defvar | |
214 | |
215 @node Terminal-Specific | |
216 @subsection Terminal-Specific Initialization | |
217 @cindex terminal-specific initialization | |
218 | |
219 Each terminal type can have its own Lisp library that XEmacs loads when | |
220 run on that type of terminal. For a terminal type named @var{termtype}, | |
221 the library is called @file{term/@var{termtype}}. XEmacs finds the file | |
222 by searching the @code{load-path} directories as it does for other | |
223 files, and trying the @samp{.elc} and @samp{.el} suffixes. Normally, | |
224 terminal-specific Lisp library is located in @file{emacs/lisp/term}, a | |
225 subdirectory of the @file{emacs/lisp} directory in which most XEmacs Lisp | |
226 libraries are kept.@refill | |
227 | |
228 The library's name is constructed by concatenating the value of the | |
229 variable @code{term-file-prefix} and the terminal type. Normally, | |
230 @code{term-file-prefix} has the value @code{"term/"}; changing this | |
231 is not recommended. | |
232 | |
233 The usual function of a terminal-specific library is to enable special | |
234 keys to send sequences that XEmacs can recognize. It may also need to | |
235 set or add to @code{function-key-map} if the Termcap entry does not | |
236 specify all the terminal's function keys. @xref{Terminal Input}. | |
237 | |
238 @cindex Termcap | |
239 When the name of the terminal type contains a hyphen, only the part of | |
240 the name before the first hyphen is significant in choosing the library | |
241 name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use | |
242 the @file{term/aaa} library. If necessary, the library can evaluate | |
243 @code{(getenv "TERM")} to find the full name of the terminal | |
244 type.@refill | |
245 | |
246 Your @file{.emacs} file can prevent the loading of the | |
247 terminal-specific library by setting the variable | |
248 @code{term-file-prefix} to @code{nil}. This feature is useful when | |
249 experimenting with your own peculiar customizations. | |
250 | |
251 You can also arrange to override some of the actions of the | |
252 terminal-specific library by setting the variable | |
253 @code{term-setup-hook}. This is a normal hook which XEmacs runs using | |
254 @code{run-hooks} at the end of XEmacs initialization, after loading both | |
255 your @file{.emacs} file and any terminal-specific libraries. You can | |
256 use this variable to define initializations for terminals that do not | |
257 have their own libraries. @xref{Hooks}. | |
258 | |
259 @defvar term-file-prefix | |
260 @cindex @code{TERM} environment variable | |
261 If the @code{term-file-prefix} variable is non-@code{nil}, XEmacs loads | |
262 a terminal-specific initialization file as follows: | |
263 | |
264 @example | |
265 (load (concat term-file-prefix (getenv "TERM"))) | |
266 @end example | |
267 | |
268 @noindent | |
269 You may set the @code{term-file-prefix} variable to @code{nil} in your | |
270 @file{.emacs} file if you do not wish to load the | |
271 terminal-initialization file. To do this, put the following in | |
272 your @file{.emacs} file: @code{(setq term-file-prefix nil)}. | |
273 @end defvar | |
274 | |
444 | 275 @defvar term-setup-hook |
428 | 276 This variable is a normal hook that XEmacs runs after loading your |
277 @file{.emacs} file, the default initialization file (if any) and the | |
278 terminal-specific Lisp file. | |
279 | |
280 You can use @code{term-setup-hook} to override the definitions made by a | |
281 terminal-specific file. | |
282 @end defvar | |
283 | |
284 @defvar window-setup-hook | |
285 This variable is a normal hook which XEmacs runs after loading your | |
286 @file{.emacs} file and the default initialization file (if any), after | |
287 loading terminal-specific Lisp code, and after running the hook | |
288 @code{term-setup-hook}. | |
289 @end defvar | |
290 | |
291 @node Command Line Arguments | |
292 @subsection Command Line Arguments | |
293 @cindex command line arguments | |
294 | |
295 You can use command line arguments to request various actions when you | |
296 start XEmacs. Since you do not need to start XEmacs more than once per | |
297 day, and will often leave your XEmacs session running longer than that, | |
298 command line arguments are hardly ever used. As a practical matter, it | |
299 is best to avoid making the habit of using them, since this habit would | |
300 encourage you to kill and restart XEmacs unnecessarily often. These | |
301 options exist for two reasons: to be compatible with other editors (for | |
302 invocation by other programs) and to enable shell scripts to run | |
303 specific Lisp programs. | |
304 | |
305 This section describes how Emacs processes command line arguments, | |
306 and how you can customize them. | |
307 | |
308 @ignore | |
309 (Note that some other editors require you to start afresh each time | |
310 you want to edit a file. With this kind of editor, you will probably | |
311 specify the file as a command line argument. The recommended way to | |
312 use XEmacs is to start it only once, just after you log in, and do | |
313 all your editing in the same XEmacs process. Each time you want to edit | |
314 a different file, you visit it with the existing XEmacs, which eventually | |
315 comes to have many files in it ready for editing. Usually you do not | |
316 kill the XEmacs until you are about to log out.) | |
317 @end ignore | |
318 | |
319 @defun command-line | |
320 This function parses the command line that XEmacs was called with, | |
321 processes it, loads the user's @file{.emacs} file and displays the | |
322 startup messages. | |
323 @end defun | |
324 | |
325 @defvar command-line-processed | |
326 The value of this variable is @code{t} once the command line has been | |
327 processed. | |
328 | |
329 If you redump XEmacs by calling @code{dump-emacs}, you may wish to set | |
330 this variable to @code{nil} first in order to cause the new dumped XEmacs | |
331 to process its new command line arguments. | |
332 @end defvar | |
333 | |
334 @defvar command-switch-alist | |
335 @cindex switches on command line | |
336 @cindex options on command line | |
337 @cindex command line options | |
338 The value of this variable is an alist of user-defined command-line | |
339 options and associated handler functions. This variable exists so you | |
340 can add elements to it. | |
341 | |
342 A @dfn{command line option} is an argument on the command line of the | |
343 form: | |
344 | |
345 @example | |
346 -@var{option} | |
347 @end example | |
348 | |
444 | 349 The elements of the @code{command-switch-alist} look like this: |
428 | 350 |
351 @example | |
352 (@var{option} . @var{handler-function}) | |
353 @end example | |
354 | |
355 The @var{handler-function} is called to handle @var{option} and receives | |
356 the option name as its sole argument. | |
357 | |
358 In some cases, the option is followed in the command line by an | |
359 argument. In these cases, the @var{handler-function} can find all the | |
360 remaining command-line arguments in the variable | |
361 @code{command-line-args-left}. (The entire list of command-line | |
362 arguments is in @code{command-line-args}.) | |
363 | |
364 The command line arguments are parsed by the @code{command-line-1} | |
365 function in the @file{startup.el} file. See also @ref{Command | |
366 Switches, , Command Line Switches and Arguments, xemacs, The XEmacs | |
367 User's Manual}. | |
368 @end defvar | |
369 | |
370 @defvar command-line-args | |
371 The value of this variable is the list of command line arguments passed | |
372 to XEmacs. | |
373 @end defvar | |
374 | |
375 @defvar command-line-functions | |
376 This variable's value is a list of functions for handling an | |
377 unrecognized command-line argument. Each time the next argument to be | |
378 processed has no special meaning, the functions in this list are called, | |
379 in order of appearance, until one of them returns a non-@code{nil} | |
380 value. | |
381 | |
382 These functions are called with no arguments. They can access the | |
383 command-line argument under consideration through the variable | |
384 @code{argi}. The remaining arguments (not including the current one) | |
385 are in the variable @code{command-line-args-left}. | |
386 | |
387 When a function recognizes and processes the argument in @code{argi}, it | |
388 should return a non-@code{nil} value to say it has dealt with that | |
389 argument. If it has also dealt with some of the following arguments, it | |
390 can indicate that by deleting them from @code{command-line-args-left}. | |
391 | |
392 If all of these functions return @code{nil}, then the argument is used | |
393 as a file name to visit. | |
394 @end defvar | |
395 | |
396 @node Getting Out | |
397 @section Getting out of XEmacs | |
398 @cindex exiting XEmacs | |
399 | |
400 There are two ways to get out of XEmacs: you can kill the XEmacs job, | |
401 which exits permanently, or you can suspend it, which permits you to | |
402 reenter the XEmacs process later. As a practical matter, you seldom kill | |
403 XEmacs---only when you are about to log out. Suspending is much more | |
404 common. | |
405 | |
406 @menu | |
407 * Killing XEmacs:: Exiting XEmacs irreversibly. | |
408 * Suspending XEmacs:: Exiting XEmacs reversibly. | |
409 @end menu | |
410 | |
411 @node Killing XEmacs | |
412 @subsection Killing XEmacs | |
413 @cindex killing XEmacs | |
414 | |
415 Killing XEmacs means ending the execution of the XEmacs process. The | |
416 parent process normally resumes control. The low-level primitive for | |
417 killing XEmacs is @code{kill-emacs}. | |
418 | |
444 | 419 @deffn Command kill-emacs &optional exit-data |
428 | 420 This function exits the XEmacs process and kills it. |
421 | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
422 If @var{exit-data} is a fixnum, then it is used as the exit status |
428 | 423 of the XEmacs process. (This is useful primarily in batch operation; see |
424 @ref{Batch Mode}.) | |
425 | |
426 If @var{exit-data} is a string, its contents are stuffed into the | |
427 terminal input buffer so that the shell (or whatever program next reads | |
428 input) can read them. | |
444 | 429 @end deffn |
428 | 430 |
431 All the information in the XEmacs process, aside from files that have | |
432 been saved, is lost when the XEmacs is killed. Because killing XEmacs | |
433 inadvertently can lose a lot of work, XEmacs queries for confirmation | |
434 before actually terminating if you have buffers that need saving or | |
435 subprocesses that are running. This is done in the function | |
436 @code{save-buffers-kill-emacs}. | |
437 | |
438 @defvar kill-emacs-query-functions | |
439 After asking the standard questions, @code{save-buffers-kill-emacs} | |
440 calls the functions in the list @code{kill-buffer-query-functions}, in | |
441 order of appearance, with no arguments. These functions can ask for | |
442 additional confirmation from the user. If any of them returns | |
443 non-@code{nil}, XEmacs is not killed. | |
444 @end defvar | |
445 | |
446 @defvar kill-emacs-hook | |
447 This variable is a normal hook; once @code{save-buffers-kill-emacs} is | |
448 finished with all file saving and confirmation, it runs the functions in | |
449 this hook. | |
450 @end defvar | |
451 | |
452 @node Suspending XEmacs | |
453 @subsection Suspending XEmacs | |
454 @cindex suspending XEmacs | |
455 | |
456 @dfn{Suspending XEmacs} means stopping XEmacs temporarily and returning | |
457 control to its superior process, which is usually the shell. This | |
458 allows you to resume editing later in the same XEmacs process, with the | |
459 same buffers, the same kill ring, the same undo history, and so on. To | |
460 resume XEmacs, use the appropriate command in the parent shell---most | |
461 likely @code{fg}. | |
462 | |
463 Some operating systems do not support suspension of jobs; on these | |
464 systems, ``suspension'' actually creates a new shell temporarily as a | |
465 subprocess of XEmacs. Then you would exit the shell to return to XEmacs. | |
466 | |
467 Suspension is not useful with window systems such as X, because the | |
468 XEmacs job may not have a parent that can resume it again, and in any | |
469 case you can give input to some other job such as a shell merely by | |
470 moving to a different window. Therefore, suspending is not allowed | |
471 when XEmacs is an X client. | |
472 | |
444 | 473 @deffn Command suspend-emacs &optional stuffstring |
428 | 474 This function stops XEmacs and returns control to the superior process. |
475 If and when the superior process resumes XEmacs, @code{suspend-emacs} | |
476 returns @code{nil} to its caller in Lisp. | |
477 | |
444 | 478 If optional arg @var{stuffstring} is non-@code{nil}, its characters are |
479 sent to be read as terminal input by XEmacs's superior shell. The | |
480 characters in @var{stuffstring} are not echoed by the superior shell; | |
481 only the results appear. | |
428 | 482 |
483 Before suspending, @code{suspend-emacs} runs the normal hook | |
484 @code{suspend-hook}. In Emacs version 18, @code{suspend-hook} was not a | |
485 normal hook; its value was a single function, and if its value was | |
486 non-@code{nil}, then @code{suspend-emacs} returned immediately without | |
487 actually suspending anything. | |
488 | |
489 After the user resumes XEmacs, @code{suspend-emacs} runs the normal hook | |
490 @code{suspend-resume-hook}. @xref{Hooks}. | |
491 | |
492 The next redisplay after resumption will redraw the entire screen, | |
493 unless the variable @code{no-redraw-on-reenter} is non-@code{nil} | |
494 (@pxref{Refresh Screen}). | |
495 | |
496 In the following example, note that @samp{pwd} is not echoed after | |
497 XEmacs is suspended. But it is read and executed by the shell. | |
498 | |
499 @smallexample | |
500 @group | |
501 (suspend-emacs) | |
502 @result{} nil | |
503 @end group | |
504 | |
505 @group | |
506 (add-hook 'suspend-hook | |
507 (function (lambda () | |
508 (or (y-or-n-p | |
509 "Really suspend? ") | |
510 (error "Suspend cancelled"))))) | |
511 @result{} (lambda nil | |
512 (or (y-or-n-p "Really suspend? ") | |
513 (error "Suspend cancelled"))) | |
514 @end group | |
515 @group | |
516 (add-hook 'suspend-resume-hook | |
517 (function (lambda () (message "Resumed!")))) | |
518 @result{} (lambda nil (message "Resumed!")) | |
519 @end group | |
520 @group | |
521 (suspend-emacs "pwd") | |
522 @result{} nil | |
523 @end group | |
524 @group | |
525 ---------- Buffer: Minibuffer ---------- | |
526 Really suspend? @kbd{y} | |
527 ---------- Buffer: Minibuffer ---------- | |
528 @end group | |
529 | |
530 @group | |
531 ---------- Parent Shell ---------- | |
532 lewis@@slug[23] % /user/lewis/manual | |
533 lewis@@slug[24] % fg | |
534 @end group | |
535 | |
536 @group | |
537 ---------- Echo Area ---------- | |
538 Resumed! | |
539 @end group | |
540 @end smallexample | |
444 | 541 @end deffn |
428 | 542 |
543 @defvar suspend-hook | |
544 This variable is a normal hook run before suspending. | |
545 @end defvar | |
546 | |
547 @defvar suspend-resume-hook | |
548 This variable is a normal hook run after suspending. | |
549 @end defvar | |
550 | |
551 @node System Environment | |
552 @section Operating System Environment | |
553 @cindex operating system environment | |
554 | |
555 XEmacs provides access to variables in the operating system environment | |
556 through various functions. These variables include the name of the | |
557 system, the user's @sc{uid}, and so on. | |
558 | |
559 @defvar system-type | |
560 The value of this variable is a symbol indicating the type of operating | |
561 system XEmacs is operating on. Here is a table of the possible values: | |
562 | |
563 @table @code | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
564 @item aix |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
565 AIX 4.2 or later. |
428 | 566 |
567 @item berkeley-unix | |
568 Berkeley BSD. | |
569 | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
570 @item cygwin32 |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
571 Cygwin. |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
572 |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
573 @item darwin |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
574 Mac OS X. |
428 | 575 |
576 @item gnu | |
577 A GNU system using the GNU HURD and Mach. | |
578 | |
579 @item hpux | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
580 Hewlett-Packard HPUX operating system, version 11.0 or later. |
428 | 581 |
582 @item irix | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
583 Silicon Graphics Irix system, version 6.0 or later. |
428 | 584 |
585 @item linux | |
586 A GNU system using the Linux kernel. | |
587 | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
588 @item mach |
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
589 The Mach kernel with a BSD 4.3 layer. |
428 | 590 |
591 @item usg-unix-v | |
592 AT&T System V. | |
593 | |
594 @item windows-nt | |
4759
aa5ed11f473b
Remove support for obsolete systems. See xemacs-patches message with ID
Jerry James <james@xemacs.org>
parents:
3772
diff
changeset
|
595 Microsoft windows NT or one of its descendants. |
428 | 596 @end table |
597 | |
598 We do not wish to add new symbols to make finer distinctions unless it | |
599 is absolutely necessary! In fact, we hope to eliminate some of these | |
600 alternatives in the future. We recommend using | |
601 @code{system-configuration} to distinguish between different operating | |
602 systems. | |
603 @end defvar | |
604 | |
605 @defvar system-configuration | |
606 This variable holds the three-part configuration name for the | |
607 hardware/software configuration of your system, as a string. The | |
608 convenient way to test parts of this string is with @code{string-match}. | |
609 @end defvar | |
610 | |
611 @defun system-name | |
612 This function returns the name of the machine you are running on. | |
613 @example | |
614 (system-name) | |
615 @result{} "prep.ai.mit.edu" | |
616 @end example | |
617 @end defun | |
618 | |
619 @vindex system-name | |
620 The symbol @code{system-name} is a variable as well as a function. In | |
621 fact, the function returns whatever value the variable | |
622 @code{system-name} currently holds. Thus, you can set the variable | |
623 @code{system-name} in case Emacs is confused about the name of your | |
624 system. The variable is also useful for constructing frame titles | |
625 (@pxref{Frame Titles}). | |
626 | |
627 @defvar mail-host-address | |
628 If this variable is non-@code{nil}, it is used instead of | |
629 @code{system-name} for purposes of generating email addresses. For | |
630 example, it is used when constructing the default value of | |
631 @code{user-mail-address}. @xref{User Identification}. (Since this is | |
632 done when XEmacs starts up, the value actually used is the one saved when | |
633 XEmacs was dumped. @xref{Building XEmacs}.) | |
634 @end defvar | |
635 | |
444 | 636 @deffn Command getenv var &optional interactivep |
428 | 637 @cindex environment variable access |
638 This function returns the value of the environment variable @var{var}, | |
639 as a string. Within XEmacs, the environment variable values are kept in | |
640 the Lisp variable @code{process-environment}. | |
641 | |
444 | 642 When invoked interactively, @code{getenv} prints the value in the echo area. |
643 | |
428 | 644 @example |
645 @group | |
646 (getenv "USER") | |
647 @result{} "lewis" | |
648 @end group | |
649 | |
650 @group | |
651 lewis@@slug[10] % printenv | |
652 PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin | |
653 USER=lewis | |
654 @end group | |
655 @group | |
656 TERM=ibmapa16 | |
657 SHELL=/bin/csh | |
658 HOME=/user/lewis | |
659 @end group | |
660 @end example | |
444 | 661 @end deffn |
428 | 662 |
444 | 663 @deffn Command setenv variable &optional value unset |
428 | 664 This command sets the value of the environment variable named |
665 @var{variable} to @var{value}. Both arguments should be strings. This | |
666 function works by modifying @code{process-environment}; binding that | |
667 variable with @code{let} is also reasonable practice. | |
668 @end deffn | |
669 | |
670 @defvar process-environment | |
671 This variable is a list of strings, each describing one environment | |
444 | 672 variable. The functions @code{getenv} and @code{setenv} work by |
673 manipulating this variable. | |
428 | 674 |
675 @smallexample | |
676 @group | |
677 process-environment | |
678 @result{} ("l=/usr/stanford/lib/gnuemacs/lisp" | |
679 "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" | |
444 | 680 "USER=lewis" |
428 | 681 @end group |
682 @group | |
444 | 683 "TERM=ibmapa16" |
428 | 684 "SHELL=/bin/csh" |
685 "HOME=/user/lewis") | |
686 @end group | |
687 @end smallexample | |
688 @end defvar | |
689 | |
690 @defvar path-separator | |
691 This variable holds a string which says which character separates | |
692 directories in a search path (as found in an environment variable). Its | |
693 value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS | |
694 and Windows NT. | |
695 @end defvar | |
696 | |
697 @defvar invocation-name | |
698 This variable holds the program name under which Emacs was invoked. The | |
699 value is a string, and does not include a directory name. | |
700 @end defvar | |
701 | |
702 @defvar invocation-directory | |
703 This variable holds the directory from which the Emacs executable was | |
704 invoked, or perhaps @code{nil} if that directory cannot be determined. | |
705 @end defvar | |
706 | |
707 @defvar installation-directory | |
708 If non-@code{nil}, this is a directory within which to look for the | |
709 @file{lib-src} and @file{etc} subdirectories. This is non-@code{nil} | |
710 when Emacs can't find those directories in their standard installed | |
711 locations, but can find them in a directory related somehow to the one | |
712 containing the Emacs executable. | |
713 @end defvar | |
714 | |
715 @defun load-average &optional use-floats | |
716 This function returns a list of the current 1-minute, 5-minute and | |
717 15-minute load averages. The values are integers that are 100 times the | |
718 system load averages. (The load averages indicate the number of | |
719 processes trying to run.) | |
720 | |
444 | 721 When @var{use-floats} is non-@code{nil}, floats will be returned instead |
428 | 722 of integers. These floats are not multiplied by 100. |
723 | |
724 @example | |
725 @group | |
726 (load-average) | |
727 @result{} (169 158 164) | |
728 (load-average t) | |
729 @result{} (1.69921875 1.58984375 1.640625) | |
730 @end group | |
731 | |
732 @group | |
733 lewis@@rocky[5] % uptime | |
734 8:06pm up 16 day(s), 21:57, 40 users, | |
735 load average: 1.68, 1.59, 1.64 | |
736 @end group | |
737 @end example | |
738 | |
739 If the 5-minute or 15-minute load averages are not available, return a | |
740 shortened list, containing only those averages which are available. | |
741 | |
444 | 742 On some systems, this function may require special privileges to run, or |
428 | 743 it may be unimplemented for the particular system type. In that case, |
744 the function will signal an error. | |
745 @end defun | |
746 | |
747 @defun emacs-pid | |
748 This function returns the process @sc{id} of the Emacs process. | |
749 @end defun | |
750 | |
751 @node User Identification | |
752 @section User Identification | |
753 | |
754 @defvar user-mail-address | |
755 This holds the nominal email address of the user who is using Emacs. | |
756 When Emacs starts up, it computes a default value that is usually right, | |
757 but users often set this themselves when the default value is not right. | |
758 @end defvar | |
759 | |
760 @defun user-login-name &optional uid | |
761 If you don't specify @var{uid}, this function returns the name under | |
762 which the user is logged in. If the environment variable @code{LOGNAME} | |
763 is set, that value is used. Otherwise, if the environment variable | |
764 @code{USER} is set, that value is used. Otherwise, the value is based | |
765 on the effective @sc{uid}, not the real @sc{uid}. | |
766 | |
767 If you specify @var{uid}, the value is the user name that corresponds | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
768 to @var{uid} (which should be a fixnum). |
428 | 769 |
770 @example | |
771 @group | |
772 (user-login-name) | |
773 @result{} "lewis" | |
774 @end group | |
775 @end example | |
776 @end defun | |
777 | |
778 @defun user-real-login-name | |
779 This function returns the user name corresponding to Emacs's real | |
780 @sc{uid}. This ignores the effective @sc{uid} and ignores the | |
781 environment variables @code{LOGNAME} and @code{USER}. | |
782 @end defun | |
783 | |
784 @defvar user-full-name | |
785 This variable holds the name of the user running this Emacs. It is | |
786 initialized at startup time from the value of @code{NAME} environment | |
444 | 787 variable. You can change the value of this variable to alter the result |
428 | 788 of the @code{user-full-name} function. |
789 @end defvar | |
790 | |
791 @defun user-full-name &optional user | |
792 This function returns the full name of @var{user}. If @var{user} is | |
793 @code{nil}, it defaults to the user running this Emacs. In that case, | |
794 the value of @code{user-full-name} variable, if non-@code{nil}, will be | |
795 used. | |
796 | |
444 | 797 If @var{user} is specified explicitly, @code{user-full-name} variable is |
428 | 798 ignored. |
799 | |
800 @example | |
801 @group | |
802 (user-full-name) | |
803 @result{} "Hrvoje Niksic" | |
804 (setq user-full-name "Hrvoje \"Niksa\" Niksic") | |
805 (user-full-name) | |
806 @result{} "Hrvoje \"Niksa\" Niksic" | |
807 (user-full-name "hniksic") | |
808 @result{} "Hrvoje Niksic" | |
809 @end group | |
810 @end example | |
811 @end defun | |
812 | |
813 @vindex user-full-name | |
814 @vindex user-real-login-name | |
815 @vindex user-login-name | |
816 The symbols @code{user-login-name}, @code{user-real-login-name} and | |
817 @code{user-full-name} are variables as well as functions. The functions | |
818 return the same values that the variables hold. These variables allow | |
819 you to ``fake out'' Emacs by telling the functions what to return. The | |
820 variables are also useful for constructing frame titles (@pxref{Frame | |
821 Titles}). | |
822 | |
823 @defun user-real-uid | |
824 This function returns the real @sc{uid} of the user. | |
825 | |
826 @example | |
827 @group | |
828 (user-real-uid) | |
829 @result{} 19 | |
830 @end group | |
831 @end example | |
832 @end defun | |
833 | |
834 @defun user-uid | |
444 | 835 This function returns the effective @sc{uid} of the user. |
428 | 836 @end defun |
837 | |
838 @defun user-home-directory | |
839 This function returns the ``@code{HOME}'' directory of the user, and is | |
840 intended to replace occurrences of ``@code{(getenv "HOME")}''. Under | |
841 Unix systems, the following is done: | |
842 | |
843 @enumerate | |
844 @item | |
845 Return the value of ``@code{(getenv "HOME")}'', if set. | |
846 | |
847 @item | |
848 Return ``/'', as a fallback, but issue a warning. (Future versions of | |
849 XEmacs will also attempt to lookup the @code{HOME} directory via | |
850 @code{getpwent()}, but this has not yet been implemented.) | |
851 @end enumerate | |
852 | |
853 Under MS Windows, this is done: | |
854 | |
855 @enumerate | |
856 @item | |
857 Return the value of ``@code{(getenv "HOME")}'', if set. | |
858 | |
859 @item | |
3772 | 860 If the environment variables @code{HOMEDRIVE} and @code{HOMEPATH} are |
428 | 861 both set, return the concatenation (the following description uses MS |
862 Windows environment variable substitution syntax): | |
3772 | 863 @code{%HOMEDRIVE%%HOMEPATH%}. |
428 | 864 |
865 @item | |
866 Return ``C:\'', as a fallback, but issue a warning. | |
867 @end enumerate | |
868 @end defun | |
869 | |
870 @node Time of Day | |
871 @section Time of Day | |
872 | |
873 This section explains how to determine the current time and the time | |
874 zone. | |
875 | |
876 @defun current-time-string &optional time-value | |
877 This function returns the current time and date as a humanly-readable | |
878 string. The format of the string is unvarying; the number of characters | |
879 used for each part is always the same, so you can reliably use | |
880 @code{substring} to extract pieces of it. It is wise to count the | |
881 characters from the beginning of the string rather than from the end, as | |
882 additional information may be added at the end. | |
883 | |
884 @c Emacs 19 feature | |
885 The argument @var{time-value}, if given, specifies a time to format | |
886 instead of the current time. The argument should be a list whose first | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
887 two elements are fixnums. Thus, you can use times obtained from |
428 | 888 @code{current-time} (see below) and from @code{file-attributes} |
889 (@pxref{File Attributes}). | |
890 | |
891 @example | |
892 @group | |
893 (current-time-string) | |
894 @result{} "Wed Oct 14 22:21:05 1987" | |
895 @end group | |
896 @end example | |
897 @end defun | |
898 | |
899 @c Emacs 19 feature | |
900 @defun current-time | |
901 This function returns the system's time value as a list of three | |
902 integers: @code{(@var{high} @var{low} @var{microsec})}. The integers | |
903 @var{high} and @var{low} combine to give the number of seconds since | |
904 0:00 January 1, 1970, which is | |
905 @ifinfo | |
906 @var{high} * 2**16 + @var{low}. | |
907 @end ifinfo | |
908 @tex | |
909 $high*2^{16}+low$. | |
910 @end tex | |
911 | |
912 The third element, @var{microsec}, gives the microseconds since the | |
913 start of the current second (or 0 for systems that return time only on | |
914 the resolution of a second). | |
915 | |
916 The first two elements can be compared with file time values such as you | |
917 get with the function @code{file-attributes}. @xref{File Attributes}. | |
918 @end defun | |
919 | |
920 @c Emacs 19 feature | |
921 @defun current-time-zone &optional time-value | |
922 This function returns a list describing the time zone that the user is | |
923 in. | |
924 | |
925 The value has the form @code{(@var{offset} @var{name})}. Here | |
926 @var{offset} is an integer giving the number of seconds ahead of UTC | |
927 (east of Greenwich). A negative value means west of Greenwich. The | |
928 second element, @var{name} is a string giving the name of the time | |
929 zone. Both elements change when daylight savings time begins or ends; | |
930 if the user has specified a time zone that does not use a seasonal time | |
931 adjustment, then the value is constant through time. | |
932 | |
933 If the operating system doesn't supply all the information necessary to | |
934 compute the value, both elements of the list are @code{nil}. | |
935 | |
936 The argument @var{time-value}, if given, specifies a time to analyze | |
937 instead of the current time. The argument should be a cons cell | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
938 containing two fixnums, or a list whose first two elements are |
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
939 fixnums. Thus, you can use times obtained from @code{current-time} |
428 | 940 (see above) and from @code{file-attributes} (@pxref{File Attributes}). |
941 @end defun | |
942 | |
943 @node Time Conversion | |
944 @section Time Conversion | |
945 | |
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4759
diff
changeset
|
946 These functions convert time values (lists of two or three fixnums) |
428 | 947 to strings or to calendrical information. There is also a function to |
948 convert calendrical information to a time value. You can get time | |
949 values from the functions @code{current-time} (@pxref{Time of Day}) and | |
950 @code{file-attributes} (@pxref{File Attributes}). | |
951 | |
952 @defun format-time-string format-string &optional time | |
953 This function converts @var{time} to a string according to | |
954 @var{format-string}. If @var{time} is omitted, it defaults to the | |
955 current time. The argument @var{format-string} may contain | |
956 @samp{%}-sequences which say to substitute parts of the time. Here is a | |
957 table of what the @samp{%}-sequences mean: | |
958 | |
959 @table @samp | |
960 @item %a | |
961 This stands for the abbreviated name of the day of week. | |
962 @item %A | |
963 This stands for the full name of the day of week. | |
964 @item %b | |
965 This stands for the abbreviated name of the month. | |
966 @item %B | |
967 This stands for the full name of the month. | |
968 @item %c | |
969 This is a synonym for @samp{%x %X}. | |
970 @item %C | |
971 This has a locale-specific meaning. In the default locale (named C), it | |
972 is equivalent to @samp{%A, %B %e, %Y}. | |
973 @item %d | |
974 This stands for the day of month, zero-padded. | |
975 @item %D | |
976 This is a synonym for @samp{%m/%d/%y}. | |
977 @item %e | |
978 This stands for the day of month, blank-padded. | |
979 @item %h | |
980 This is a synonym for @samp{%b}. | |
981 @item %H | |
982 This stands for the hour (00-23). | |
983 @item %I | |
984 This stands for the hour (00-12). | |
985 @item %j | |
986 This stands for the day of the year (001-366). | |
987 @item %k | |
988 This stands for the hour (0-23), blank padded. | |
989 @item %l | |
990 This stands for the hour (1-12), blank padded. | |
991 @item %m | |
992 This stands for the month (01-12). | |
993 @item %M | |
994 This stands for the minute (00-59). | |
995 @item %n | |
996 This stands for a newline. | |
997 @item %p | |
998 This stands for @samp{AM} or @samp{PM}, as appropriate. | |
999 @item %r | |
1000 This is a synonym for @samp{%I:%M:%S %p}. | |
1001 @item %R | |
1002 This is a synonym for @samp{%H:%M}. | |
1003 @item %S | |
1004 This stands for the seconds (00-60). | |
1005 @item %t | |
1006 This stands for a tab character. | |
1007 @item %T | |
1008 This is a synonym for @samp{%H:%M:%S}. | |
1009 @item %U | |
1010 This stands for the week of the year (01-52), assuming that weeks | |
1011 start on Sunday. | |
1012 @item %w | |
1013 This stands for the numeric day of week (0-6). Sunday is day 0. | |
1014 @item %W | |
1015 This stands for the week of the year (01-52), assuming that weeks | |
1016 start on Monday. | |
1017 @item %x | |
1018 This has a locale-specific meaning. In the default locale (named C), it | |
1019 is equivalent to @samp{%D}. | |
1020 @item %X | |
1021 This has a locale-specific meaning. In the default locale (named C), it | |
1022 is equivalent to @samp{%T}. | |
1023 @item %y | |
1024 This stands for the year without century (00-99). | |
1025 @item %Y | |
1026 This stands for the year with century. | |
1027 @item %Z | |
1028 This stands for the time zone abbreviation. | |
5254
1537701f08a1
Support Roman month numbers, #'format-time-string
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1029 @item %\xe6 (the ISO-8859-1 lowercase ae character) |
1537701f08a1
Support Roman month numbers, #'format-time-string
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1030 This stands for the month as a lowercase Roman number (i-xii) |
1537701f08a1
Support Roman month numbers, #'format-time-string
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1031 @item %\xc6 (the ISO-8859-1 uppercase AE character) |
1537701f08a1
Support Roman month numbers, #'format-time-string
Aidan Kehoe <kehoea@parhasard.net>
parents:
4885
diff
changeset
|
1032 This stands for the month as an uppercase Roman number (I-XII) |
428 | 1033 @end table |
1034 @end defun | |
1035 | |
444 | 1036 @defun decode-time &optional specified-time |
428 | 1037 This function converts a time value into calendrical information. The |
444 | 1038 optional @var{specified-time} should be a list of |
1039 (@var{high} @var{low} . @var{ignored}) or (@var{high} . @var{low}), as from | |
1040 @code{current-time} and @code{file-attributes}, or @code{nil} to use the | |
1041 current time. | |
1042 | |
1043 The return value is a list of nine elements, as follows: | |
428 | 1044 |
1045 @example | |
1046 (@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) | |
1047 @end example | |
1048 | |
1049 Here is what the elements mean: | |
1050 | |
1051 @table @var | |
1052 @item sec | |
1053 The number of seconds past the minute, as an integer between 0 and 59. | |
1054 @item minute | |
1055 The number of minutes past the hour, as an integer between 0 and 59. | |
1056 @item hour | |
1057 The hour of the day, as an integer between 0 and 23. | |
1058 @item day | |
1059 The day of the month, as an integer between 1 and 31. | |
1060 @item month | |
1061 The month of the year, as an integer between 1 and 12. | |
1062 @item year | |
1063 The year, an integer typically greater than 1900. | |
1064 @item dow | |
1065 The day of week, as an integer between 0 and 6, where 0 stands for | |
1066 Sunday. | |
1067 @item dst | |
1068 @code{t} if daylight savings time is effect, otherwise @code{nil}. | |
1069 @item zone | |
1070 An integer indicating the time zone, as the number of seconds east of | |
1071 Greenwich. | |
1072 @end table | |
1073 | |
1074 Note that Common Lisp has different meanings for @var{dow} and | |
1075 @var{zone}. | |
1076 @end defun | |
1077 | |
1078 @defun encode-time seconds minutes hour day month year &optional zone | |
1079 This function is the inverse of @code{decode-time}. It converts seven | |
1080 items of calendrical data into a time value. For the meanings of the | |
1081 arguments, see the table above under @code{decode-time}. | |
1082 | |
1083 Year numbers less than 100 are treated just like other year numbers. If | |
1084 you want them to stand for years above 1900, you must alter them yourself | |
1085 before you call @code{encode-time}. | |
1086 | |
1087 The optional argument @var{zone} defaults to the current time zone and | |
1088 its daylight savings time rules. If specified, it can be either a list | |
1089 (as you would get from @code{current-time-zone}) or an integer (as you | |
1090 would get from @code{decode-time}). The specified zone is used without | |
1091 any further alteration for daylight savings time. | |
1092 @end defun | |
1093 | |
1094 @node Timers | |
1095 @section Timers for Delayed Execution | |
1096 | |
1097 You can set up a timer to call a function at a specified future time. | |
1098 | |
1099 @c All different in FSF 19 | |
1100 @defun add-timeout secs function object &optional resignal | |
1101 This function adds a timeout, to be signaled after the timeout period | |
1102 has elapsed. @var{secs} is a number of seconds, expressed as an integer | |
1103 or a float. @var{function} will be called after that many seconds have | |
1104 elapsed, with one argument, the given @var{object}. If the optional | |
1105 @var{resignal} argument is provided, then after this timeout expires, | |
444 | 1106 @code{add-timeout} will automatically be called again with |
1107 @var{resignal} as the first argument. | |
428 | 1108 |
1109 This function returns an object which is the @dfn{id} of this particular | |
1110 timeout. You can pass that object to @code{disable-timeout} to turn off | |
1111 the timeout before it has been signalled. | |
1112 | |
1113 The number of seconds may be expressed as a floating-point number, in which | |
1114 case some fractional part of a second will be used. Caveat: the usable | |
1115 timeout granularity will vary from system to system. | |
1116 | |
1117 Adding a timeout causes a timeout event to be returned by | |
1118 @code{next-event}, and the function will be invoked by | |
1119 @code{dispatch-event}, so if XEmacs is in a tight loop, the function will | |
1120 not be invoked until the next call to sit-for or until the return to | |
1121 top-level (the same is true of process filters). | |
1122 | |
1123 WARNING: if you are thinking of calling add-timeout from inside of a | |
1124 callback function as a way of resignalling a timeout, think again. There | |
1125 is a race condition. That's why the @var{resignal} argument exists. | |
1126 | |
1127 (NOTE: In FSF Emacs, this function is called @code{run-at-time} and | |
1128 has different semantics.) | |
1129 @end defun | |
1130 | |
1131 @defun disable-timeout id | |
1132 Cancel the requested action for @var{id}, which should be a value | |
1133 previously returned by @code{add-timeout}. This cancels the effect of | |
1134 that call to @code{add-timeout}; the arrival of the specified time will | |
1135 not cause anything special to happen. | |
1136 (NOTE: In FSF Emacs, this function is called @code{cancel-timer}.) | |
1137 @end defun | |
1138 | |
1139 @node Terminal Input | |
1140 @section Terminal Input | |
1141 @cindex terminal input | |
1142 | |
1143 This section describes functions and variables for recording or | |
1144 manipulating terminal input. See @ref{Display}, for related | |
1145 functions. | |
1146 | |
1147 @menu | |
1148 * Input Modes:: Options for how input is processed. | |
1149 * Translating Input:: Low level conversion of some characters or events | |
1150 into others. | |
1151 * Recording Input:: Saving histories of recent or all input events. | |
1152 @end menu | |
1153 | |
1154 @node Input Modes | |
1155 @subsection Input Modes | |
1156 @cindex input modes | |
1157 @cindex terminal input modes | |
1158 | |
444 | 1159 @defun set-input-mode interrupt flow meta &optional quit-char console |
428 | 1160 This function sets the mode for reading keyboard input. If |
1161 @var{interrupt} is non-null, then XEmacs uses input interrupts. If it is | |
1162 @code{nil}, then it uses @sc{cbreak} mode. When XEmacs communicates | |
1163 directly with X, it ignores this argument and uses interrupts if that is | |
1164 the way it knows how to communicate. | |
1165 | |
1166 If @var{flow} is non-@code{nil}, then XEmacs uses @sc{xon/xoff} (@kbd{C-q}, | |
1167 @kbd{C-s}) flow control for output to the terminal. This has no effect except | |
1168 in @sc{cbreak} mode. @xref{Flow Control}. | |
1169 | |
1170 The default setting is system dependent. Some systems always use | |
1171 @sc{cbreak} mode regardless of what is specified. | |
1172 | |
1173 @c Emacs 19 feature | |
1174 The argument @var{meta} controls support for input character codes | |
1175 above 127. If @var{meta} is @code{t}, XEmacs converts characters with | |
1176 the 8th bit set into Meta characters. If @var{meta} is @code{nil}, | |
1177 XEmacs disregards the 8th bit; this is necessary when the terminal uses | |
1178 it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, | |
1179 XEmacs uses all 8 bits of input unchanged. This is good for terminals | |
1180 using European 8-bit character sets. | |
1181 | |
1182 @c Emacs 19 feature | |
1183 If @var{quit-char} is non-@code{nil}, it specifies the character to | |
1184 use for quitting. Normally this character is @kbd{C-g}. | |
1185 @xref{Quitting}. | |
1186 @end defun | |
1187 | |
1188 The @code{current-input-mode} function returns the input mode settings | |
1189 XEmacs is currently using. | |
1190 | |
1191 @c Emacs 19 feature | |
444 | 1192 @defun current-input-mode &optional console |
428 | 1193 This function returns current mode for reading keyboard input. It |
1194 returns a list, corresponding to the arguments of @code{set-input-mode}, | |
1195 of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in | |
1196 which: | |
1197 @table @var | |
1198 @item interrupt | |
1199 is non-@code{nil} when XEmacs is using interrupt-driven input. If | |
1200 @code{nil}, Emacs is using @sc{cbreak} mode. | |
1201 @item flow | |
1202 is non-@code{nil} if XEmacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) | |
1203 flow control for output to the terminal. This value has no effect | |
1204 unless @var{interrupt} is non-@code{nil}. | |
1205 @item meta | |
1206 is @code{t} if XEmacs treats the eighth bit of input characters as | |
1207 the meta bit; @code{nil} means XEmacs clears the eighth bit of every | |
1208 input character; any other value means XEmacs uses all eight bits as the | |
1209 basic character code. | |
1210 @item quit | |
1211 is the character XEmacs currently uses for quitting, usually @kbd{C-g}. | |
1212 @end table | |
1213 @end defun | |
1214 | |
1215 @node Translating Input | |
1216 @subsection Translating Input Events | |
1217 @cindex translating input events | |
1218 | |
1219 This section describes features for translating input events into other | |
1220 input events before they become part of key sequences. | |
1221 | |
1222 @ignore Not in XEmacs yet. | |
1223 @c Emacs 19 feature | |
1224 @defvar extra-keyboard-modifiers | |
1225 This variable lets Lisp programs ``press'' the modifier keys on the | |
1226 keyboard. The value is a bit mask: | |
1227 | |
1228 @table @asis | |
1229 @item 1 | |
1230 The @key{SHIFT} key. | |
1231 @item 2 | |
1232 The @key{LOCK} key. | |
1233 @item 4 | |
1234 The @key{CTL} key. | |
1235 @item 8 | |
1236 The @key{META} key. | |
1237 @end table | |
1238 | |
1239 Each time the user types a keyboard key, it is altered as if the | |
1240 modifier keys specified in the bit mask were held down. | |
1241 | |
1242 When using X windows, the program can ``press'' any of the modifier | |
1243 keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can | |
1244 be virtually pressed. | |
1245 @end defvar | |
1246 | |
1247 @defvar keyboard-translate-table | |
1248 This variable is the translate table for keyboard characters. It lets | |
1249 you reshuffle the keys on the keyboard without changing any command | |
1250 bindings. Its value must be a string or @code{nil}. | |
1251 | |
1252 If @code{keyboard-translate-table} is a string, then each character read | |
1253 from the keyboard is looked up in this string and the character in the | |
1254 string is used instead. If the string is of length @var{n}, character codes | |
1255 @var{n} and up are untranslated. | |
1256 | |
1257 In the example below, we set @code{keyboard-translate-table} to a | |
1258 string of 128 characters. Then we fill it in to swap the characters | |
1259 @kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. | |
1260 Subsequently, typing @kbd{C-\} has all the usual effects of typing | |
1261 @kbd{C-s}, and vice versa. (@xref{Flow Control} for more information on | |
1262 this subject.) | |
1263 | |
1264 @cindex flow control example | |
1265 @example | |
1266 @group | |
1267 (defun evade-flow-control () | |
1268 "Replace C-s with C-\ and C-q with C-^." | |
1269 (interactive) | |
1270 @end group | |
1271 @group | |
1272 (let ((the-table (make-string 128 0))) | |
1273 (let ((i 0)) | |
1274 (while (< i 128) | |
1275 (aset the-table i i) | |
1276 (setq i (1+ i)))) | |
1277 @end group | |
1278 ;; @r{Swap @kbd{C-s} and @kbd{C-\}.} | |
1279 (aset the-table ?\034 ?\^s) | |
1280 (aset the-table ?\^s ?\034) | |
1281 @group | |
1282 ;; @r{Swap @kbd{C-q} and @kbd{C-^}.} | |
1283 (aset the-table ?\036 ?\^q) | |
1284 (aset the-table ?\^q ?\036) | |
1285 (setq keyboard-translate-table the-table))) | |
1286 @end group | |
1287 @end example | |
1288 | |
1289 Note that this translation is the first thing that happens to a | |
1290 character after it is read from the terminal. Record-keeping features | |
1291 such as @code{recent-keys} and dribble files record the characters after | |
1292 translation. | |
1293 @end defvar | |
1294 | |
444 | 1295 @defun keyboard-translate &rest pairs |
428 | 1296 This function modifies @code{keyboard-translate-table} to translate |
1297 character code @var{from} into character code @var{to}. It creates | |
444 | 1298 or enlarges the translate table if necessary. Multiple |
1299 @var{from}-@var{to} pairs may be specified. | |
428 | 1300 @end defun |
1301 @end ignore | |
1302 | |
1303 @defvar function-key-map | |
1304 This variable holds a keymap that describes the character sequences | |
1305 sent by function keys on an ordinary character terminal. This keymap | |
1306 uses the same data structure as other keymaps, but is used differently: it | |
1307 specifies translations to make while reading events. | |
1308 | |
1309 If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector | |
1310 @var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a | |
1311 key sequence, it is replaced with the events in @var{v}. | |
1312 | |
1313 For example, VT100 terminals send @kbd{@key{ESC} O P} when the | |
1314 keypad PF1 key is pressed. Therefore, we want XEmacs to translate | |
1315 that sequence of events into the single event @code{pf1}. We accomplish | |
1316 this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in | |
1317 @code{function-key-map}, when using a VT100. | |
1318 | |
1319 Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c | |
1320 @key{ESC} O P}; later the function @code{read-key-sequence} translates | |
1321 this back into @kbd{C-c @key{PF1}}, which it returns as the vector | |
1322 @code{[?\C-c pf1]}. | |
1323 | |
1324 Entries in @code{function-key-map} are ignored if they conflict with | |
1325 bindings made in the minor mode, local, or global keymaps. The intent | |
1326 is that the character sequences that function keys send should not have | |
1327 command bindings in their own right. | |
1328 | |
1329 The value of @code{function-key-map} is usually set up automatically | |
1330 according to the terminal's Terminfo or Termcap entry, but sometimes | |
1331 those need help from terminal-specific Lisp files. XEmacs comes with | |
1332 terminal-specific files for many common terminals; their main purpose is | |
1333 to make entries in @code{function-key-map} beyond those that can be | |
1334 deduced from Termcap and Terminfo. @xref{Terminal-Specific}. | |
1335 | |
1336 Emacs versions 18 and earlier used totally different means of detecting | |
1337 the character sequences that represent function keys. | |
1338 @end defvar | |
1339 | |
1340 @defvar key-translation-map | |
1341 This variable is another keymap used just like @code{function-key-map} | |
1342 to translate input events into other events. It differs from | |
1343 @code{function-key-map} in two ways: | |
1344 | |
1345 @itemize @bullet | |
1346 @item | |
1347 @code{key-translation-map} goes to work after @code{function-key-map} is | |
1348 finished; it receives the results of translation by | |
1349 @code{function-key-map}. | |
1350 | |
1351 @item | |
1352 @code{key-translation-map} overrides actual key bindings. | |
1353 @end itemize | |
1354 | |
1355 The intent of @code{key-translation-map} is for users to map one | |
1356 character set to another, including ordinary characters normally bound | |
1357 to @code{self-insert-command}. | |
1358 @end defvar | |
1359 | |
1360 @cindex key translation function | |
1361 You can use @code{function-key-map} or @code{key-translation-map} for | |
1362 more than simple aliases, by using a function, instead of a key | |
1363 sequence, as the ``translation'' of a key. Then this function is called | |
1364 to compute the translation of that key. | |
1365 | |
1366 The key translation function receives one argument, which is the prompt | |
1367 that was specified in @code{read-key-sequence}---or @code{nil} if the | |
1368 key sequence is being read by the editor command loop. In most cases | |
1369 you can ignore the prompt value. | |
1370 | |
1371 If the function reads input itself, it can have the effect of altering | |
1372 the event that follows. For example, here's how to define @kbd{C-c h} | |
1373 to turn the character that follows into a Hyper character: | |
1374 | |
1375 @example | |
1376 @group | |
1377 (defun hyperify (prompt) | |
1378 (let ((e (read-event))) | |
1379 (vector (if (numberp e) | |
1380 (logior (lsh 1 20) e) | |
1381 (if (memq 'hyper (event-modifiers e)) | |
1382 e | |
1383 (add-event-modifier "H-" e)))))) | |
1384 | |
1385 (defun add-event-modifier (string e) | |
1386 (let ((symbol (if (symbolp e) e (car e)))) | |
1387 (setq symbol (intern (concat string | |
1388 (symbol-name symbol)))) | |
1389 @end group | |
1390 @group | |
1391 (if (symbolp e) | |
1392 symbol | |
1393 (cons symbol (cdr e))))) | |
1394 | |
1395 (define-key function-key-map "\C-ch" 'hyperify) | |
1396 @end group | |
1397 @end example | |
1398 | |
1399 @pindex iso-transl | |
1400 @cindex Latin-1 character set (input) | |
1401 @cindex ISO Latin-1 characters (input) | |
1402 The @file{iso-transl} library uses this feature to provide a way of | |
1403 inputting non-ASCII Latin-1 characters. | |
1404 | |
1405 @node Recording Input | |
1406 @subsection Recording Input | |
1407 | |
1408 @defun recent-keys &optional number | |
1409 This function returns a vector containing recent input events from the | |
1410 keyboard or mouse. By default, 100 events are recorded, which is how | |
1411 many @code{recent-keys} returns. | |
1412 | |
1413 All input events are included, whether or not they were used as parts of | |
1414 key sequences. Thus, you always get the last 100 inputs, not counting | |
1415 keyboard macros. (Events from keyboard macros are excluded because they | |
1416 are less interesting for debugging; it should be enough to see the | |
1417 events that invoked the macros.) | |
1418 | |
1419 If @var{number} is specified, not more than @var{number} events will be | |
1420 returned. You may change the number of stored events using | |
1421 @code{set-recent-keys-ring-size}. | |
1422 @end defun | |
1423 | |
1424 @defun recent-keys-ring-size | |
1425 This function returns the number of recent events stored internally. | |
1426 This is also the maximum number of events @code{recent-keys} can | |
1427 return. By default, 100 events are stored. | |
1428 @end defun | |
1429 | |
1430 @defun set-recent-keys-ring-size size | |
444 | 1431 This function changes the number of events stored by XEmacs and returned |
428 | 1432 by @code{recent-keys}. |
1433 | |
1434 For example, @code{(set-recent-keys-ring-size 250)} will make XEmacs | |
1435 remember last 250 events and will make @code{recent-keys} return last | |
1436 250 events by default. | |
1437 @end defun | |
1438 | |
444 | 1439 @deffn Command open-dribble-file filename |
428 | 1440 @cindex dribble file |
1441 This function opens a @dfn{dribble file} named @var{filename}. When a | |
1442 dribble file is open, each input event from the keyboard or mouse (but | |
1443 not those from keyboard macros) is written in that file. A | |
1444 non-character event is expressed using its printed representation | |
1445 surrounded by @samp{<@dots{}>}. | |
1446 | |
1447 You close the dribble file by calling this function with an argument | |
1448 of @code{nil}. | |
1449 | |
1450 This function is normally used to record the input necessary to | |
1451 trigger an XEmacs bug, for the sake of a bug report. | |
1452 | |
1453 @example | |
1454 @group | |
1455 (open-dribble-file "~/dribble") | |
1456 @result{} nil | |
1457 @end group | |
1458 @end example | |
1459 @end deffn | |
1460 | |
1461 See also the @code{open-termscript} function (@pxref{Terminal Output}). | |
1462 | |
1463 @node Terminal Output | |
1464 @section Terminal Output | |
1465 @cindex terminal output | |
1466 | |
1467 The terminal output functions send output to the terminal or keep | |
1468 track of output sent to the terminal. The function | |
1469 @code{device-baud-rate} tells you what XEmacs thinks is the output speed | |
1470 of the terminal. | |
1471 | |
1472 @defun device-baud-rate &optional device | |
1473 This function's value is the output speed of the terminal associated | |
1474 with @var{device}, as far as XEmacs knows. @var{device} defaults to the | |
1475 selected device (usually the only device) if omitted. Changing this | |
1476 value does not change the speed of actual data transmission, but the | |
1477 value is used for calculations such as padding. This value has no | |
1478 effect for window-system devices. (This is different in FSF Emacs, where | |
1479 the baud rate also affects decisions about whether to scroll part of the | |
1480 screen or repaint, even when using a window system.) | |
1481 | |
1482 The value is measured in bits per second. | |
1483 @end defun | |
1484 | |
1485 XEmacs attempts to automatically initialize the baud rate by querying | |
1486 the terminal. If you are running across a network, however, and | |
1487 different parts of the network work are at different baud rates, the | |
1488 value returned by XEmacs may be different from the value used by your | |
1489 local terminal. Some network protocols communicate the local terminal | |
1490 speed to the remote machine, so that XEmacs and other programs can get | |
1491 the proper value, but others do not. If XEmacs has the wrong value, it | |
1492 makes decisions that are less than optimal. To fix the problem, use | |
1493 @code{set-device-baud-rate}. | |
1494 | |
444 | 1495 @defun set-device-baud-rate device baud-rate |
428 | 1496 This function sets the output speed of @var{device}. See |
1497 @code{device-baud-rate}. @var{device} defaults to the selected device | |
444 | 1498 (usually the only device) if @code{nil}. |
428 | 1499 @end defun |
1500 | |
1501 @defun send-string-to-terminal char-or-string &optional stdout-p device | |
1502 This function sends @var{char-or-string} to the terminal without | |
1503 alteration. Control characters in @var{char-or-string} have | |
1504 terminal-dependent effects. | |
1505 | |
1506 If @var{device} is @code{nil}, this function writes to XEmacs's | |
1507 stderr, or to stdout if @var{stdout-p} is non-@code{nil}. Otherwise, | |
1508 @var{device} should be a tty or stream device, and the function writes | |
1509 to the device's normal or error output, according to @var{stdout-p}. | |
1510 | |
1511 One use of this function is to define function keys on terminals that | |
1512 have downloadable function key definitions. For example, this is how on | |
1513 certain terminals to define function key 4 to move forward four | |
1514 characters (by transmitting the characters @kbd{C-u C-f} to the | |
1515 computer): | |
1516 | |
1517 @example | |
1518 @group | |
1519 (send-string-to-terminal "\eF4\^U\^F") | |
1520 @result{} nil | |
1521 @end group | |
1522 @end example | |
1523 @end defun | |
1524 | |
1525 @deffn Command open-termscript filename | |
1526 @cindex termscript file | |
1527 This function is used to open a @dfn{termscript file} that will record | |
1528 all the characters sent by XEmacs to the terminal. (If there are | |
1529 multiple tty or stream devices, all characters sent to all such devices | |
1530 are recorded.) The function returns @code{nil}. Termscript files are | |
1531 useful for investigating problems where XEmacs garbles the screen, | |
1532 problems that are due to incorrect Termcap entries or to undesirable | |
1533 settings of terminal options more often than to actual XEmacs bugs. | |
1534 Once you are certain which characters were actually output, you can | |
1535 determine reliably whether they correspond to the Termcap specifications | |
1536 in use. | |
1537 | |
1538 A @code{nil} value for @var{filename} stops recording terminal output. | |
1539 | |
1540 See also @code{open-dribble-file} in @ref{Terminal Input}. | |
1541 | |
1542 @example | |
1543 @group | |
1544 (open-termscript "../junk/termscript") | |
1545 @result{} nil | |
1546 @end group | |
1547 @end example | |
1548 @end deffn | |
1549 | |
1550 @ignore Not in XEmacs | |
1551 @node Special Keysyms | |
1552 @section System-Specific X11 Keysyms | |
1553 | |
1554 To define system-specific X11 keysyms, set the variable | |
1555 @code{system-key-alist}. | |
1556 | |
1557 @defvar system-key-alist | |
1558 This variable's value should be an alist with one element for each | |
1559 system-specific keysym. An element has this form: @code{(@var{code} | |
1560 . @var{symbol})}, where @var{code} is the numeric keysym code (not | |
1561 including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the | |
1562 name for the function key. | |
1563 | |
1564 For example @code{(168 . mute-acute)} defines a system-specific key used | |
1565 by HP X servers whose numeric code is (1 << 28) + 168. | |
1566 | |
1567 It is not a problem if the alist defines keysyms for other X servers, as | |
1568 long as they don't conflict with the ones used by the X server actually | |
1569 in use. | |
1570 | |
1571 The variable is always local to the current X terminal and cannot be | |
1572 buffer-local. @xref{Multiple Displays}. | |
1573 @end defvar | |
1574 @end ignore | |
1575 | |
1576 @node Flow Control | |
1577 @section Flow Control | |
1578 @cindex flow control characters | |
1579 | |
1580 This section attempts to answer the question ``Why does XEmacs choose | |
1581 to use flow-control characters in its command character set?'' For a | |
1582 second view on this issue, read the comments on flow control in the | |
1583 @file{emacs/INSTALL} file from the distribution; for help with Termcap | |
1584 entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}. | |
1585 | |
1586 @cindex @kbd{C-s} | |
1587 @cindex @kbd{C-q} | |
1588 At one time, most terminals did not need flow control, and none used | |
1589 @code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of | |
1590 @kbd{C-s} and @kbd{C-q} as command characters was uncontroversial. | |
1591 XEmacs, for economy of keystrokes and portability, used nearly all the | |
1592 @sc{ascii} control characters, with mnemonic meanings when possible; | |
1593 thus, @kbd{C-s} for search and @kbd{C-q} for quote. | |
1594 | |
1595 Later, some terminals were introduced which required these characters | |
1596 for flow control. They were not very good terminals for full-screen | |
1597 editing, so XEmacs maintainers did not pay attention. In later years, | |
1598 flow control with @kbd{C-s} and @kbd{C-q} became widespread among | |
1599 terminals, but by this time it was usually an option. And the majority | |
1600 of users, who can turn flow control off, were unwilling to switch to | |
1601 less mnemonic key bindings for the sake of flow control. | |
1602 | |
1603 So which usage is ``right'', XEmacs's or that of some terminal and | |
1604 concentrator manufacturers? This question has no simple answer. | |
1605 | |
1606 One reason why we are reluctant to cater to the problems caused by | |
1607 @kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other | |
1608 techniques (albeit less common in practice) for flow control that | |
1609 preserve transparency of the character stream. Note also that their use | |
1610 for flow control is not an official standard. Interestingly, on the | |
1611 model 33 teletype with a paper tape punch (which is very old), @kbd{C-s} | |
1612 and @kbd{C-q} were sent by the computer to turn the punch on and off! | |
1613 | |
1614 As X servers and other window systems replace character-only | |
1615 terminals, this problem is gradually being cured. For the mean time, | |
1616 XEmacs provides a convenient way of enabling flow control if you want it: | |
1617 call the function @code{enable-flow-control}. | |
1618 | |
444 | 1619 @deffn Command enable-flow-control &optional argument |
428 | 1620 This function enables use of @kbd{C-s} and @kbd{C-q} for output flow |
1621 control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases | |
1622 for them using @code{keyboard-translate-table} (@pxref{Translating Input}). | |
444 | 1623 |
1624 With optional argument @var{argument} (interactively the prefix | |
1625 argument), enable flow control mode if @var{argument} is positive; else | |
1626 disable it. | |
1627 @end deffn | |
428 | 1628 |
1629 You can use the function @code{enable-flow-control-on} in your | |
1630 @file{.emacs} file to enable flow control automatically on certain | |
1631 terminal types. | |
1632 | |
1633 @defun enable-flow-control-on &rest termtypes | |
1634 This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^}, | |
1635 if the terminal type is one of @var{termtypes}. For example: | |
1636 | |
1637 @smallexample | |
1638 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131") | |
1639 @end smallexample | |
1640 @end defun | |
1641 | |
1642 Here is how @code{enable-flow-control} does its job: | |
1643 | |
1644 @enumerate | |
1645 @item | |
1646 @cindex @sc{cbreak} | |
1647 It sets @sc{cbreak} mode for terminal input, and tells the operating | |
1648 system to handle flow control, with @code{(set-input-mode nil t)}. | |
1649 | |
1650 @item | |
1651 It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and | |
1652 @kbd{C-^} into @kbd{C-s} and @kbd{C-q}. Except at its very | |
1653 lowest level, XEmacs never knows that the characters typed were anything | |
1654 but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\} | |
1655 and @kbd{C-^} even when they are input for other commands. | |
1656 @xref{Translating Input}. | |
1657 @end enumerate | |
1658 | |
1659 If the terminal is the source of the flow control characters, then once | |
1660 you enable kernel flow control handling, you probably can make do with | |
1661 less padding than normal for that terminal. You can reduce the amount | |
1662 of padding by customizing the Termcap entry. You can also reduce it by | |
1663 setting @code{baud-rate} to a smaller value so that XEmacs uses a smaller | |
1664 speed when calculating the padding needed. @xref{Terminal Output}. | |
1665 | |
1666 @node Batch Mode | |
1667 @section Batch Mode | |
1668 @cindex batch mode | |
1669 @cindex noninteractive use | |
1670 | |
1671 The command line option @samp{-batch} causes XEmacs to run | |
1672 noninteractively. In this mode, XEmacs does not read commands from the | |
1673 terminal, it does not alter the terminal modes, and it does not expect | |
1674 to be outputting to an erasable screen. The idea is that you specify | |
1675 Lisp programs to run; when they are finished, XEmacs should exit. The | |
1676 way to specify the programs to run is with @samp{-l @var{file}}, which | |
1677 loads the library named @var{file}, and @samp{-f @var{function}}, which | |
1678 calls @var{function} with no arguments. | |
1679 | |
1680 Any Lisp program output that would normally go to the echo area, | |
1681 either using @code{message} or using @code{prin1}, etc., with @code{t} | |
1682 as the stream, goes instead to XEmacs's standard error descriptor when | |
1683 in batch mode. Thus, XEmacs behaves much like a noninteractive | |
1684 application program. (The echo area output that XEmacs itself normally | |
1685 generates, such as command echoing, is suppressed entirely.) | |
1686 | |
1687 @defun noninteractive | |
1688 This function returns non-@code{nil} when XEmacs is running in batch mode. | |
1689 @end defun | |
1690 | |
1691 @defvar noninteractive | |
1692 This variable is non-@code{nil} when XEmacs is running in batch mode. | |
1693 Setting this variable to @code{nil}, however, will not change whether | |
1694 XEmacs is running in batch mode, and will not change the return value | |
1695 of the @code{noninteractive} function. | |
1696 @end defvar |