X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=info%2Flispref.info-45;h=e4484ee95602a26aa68d92a89495353e3ebb7f79;hb=8b51f3a0091d0adb12b1b9effc131c8cfc1c1451;hp=f6e43556fe17bb5c65e5d7f9efc2a04a2562d282;hpb=a92fd34d4e19af388237a0913a5c30ddbcfdde7a;p=chise%2Fxemacs-chise.git diff --git a/info/lispref.info-45 b/info/lispref.info-45 index f6e4355..e4484ee 100644 --- a/info/lispref.info-45 +++ b/info/lispref.info-45 @@ -50,1267 +50,1032 @@ may be included in a translation approved by the Free Software Foundation instead of in the original English.  -File: lispref.info, Node: Pure Storage, Next: Garbage Collection, Prev: Building XEmacs, Up: Building XEmacs and Object Allocation - -Pure Storage -============ - - XEmacs Lisp uses two kinds of storage for user-created Lisp objects: -"normal storage" and "pure storage". Normal storage is where all the -new data created during an XEmacs session is kept; see the following -section for information on normal storage. Pure storage is used for -certain data in the preloaded standard Lisp files--data that should -never change during actual use of XEmacs. - - Pure storage is allocated only while `temacs' is loading the -standard preloaded Lisp libraries. In the file `xemacs', it is marked -as read-only (on operating systems that permit this), so that the -memory space can be shared by all the XEmacs jobs running on the machine -at once. Pure storage is not expandable; a fixed amount is allocated -when XEmacs is compiled, and if that is not sufficient for the preloaded -libraries, `temacs' aborts with an error message. If that happens, you -must increase the compilation parameter `PURESIZE' using the -`--puresize' option to `configure'. This normally won't happen unless -you try to preload additional libraries or add features to the standard -ones. - - - Function: purecopy object - This function makes a copy of OBJECT in pure storage and returns - it. It copies strings by simply making a new string with the same - characters in pure storage. It recursively copies the contents of - vectors and cons cells. It does not make copies of other objects - such as symbols, but just returns them unchanged. It signals an - error if asked to copy markers. - - This function is a no-op except while XEmacs is being built and - dumped; it is usually called only in the file - `xemacs/lisp/prim/loaddefs.el', but a few packages call it just in - case you decide to preload them. - - - Variable: pure-bytes-used - The value of this variable is the number of bytes of pure storage - allocated so far. Typically, in a dumped XEmacs, this number is - very close to the total amount of pure storage available--if it - were not, we would preallocate less. - - - Variable: purify-flag - This variable determines whether `defun' should make a copy of the - function definition in pure storage. If it is non-`nil', then the - function definition is copied into pure storage. - - This flag is `t' while loading all of the basic functions for - building XEmacs initially (allowing those functions to be sharable - and non-collectible). Dumping XEmacs as an executable always - writes `nil' in this variable, regardless of the value it actually - has before and after dumping. - - You should not change this flag in a running XEmacs. +File: lispref.info, Node: Coding System Properties, Next: Basic Coding System Functions, Prev: EOL Conversion, Up: Coding Systems + +Coding System Properties +------------------------ + +`mnemonic' + String to be displayed in the modeline when this coding system is + active. + +`eol-type' + End-of-line conversion to be used. It should be one of the types + listed in *Note EOL Conversion::. + +`eol-lf' + The coding system which is the same as this one, except that it + uses the Unix line-breaking convention. + +`eol-crlf' + The coding system which is the same as this one, except that it + uses the DOS line-breaking convention. + +`eol-cr' + The coding system which is the same as this one, except that it + uses the Macintosh line-breaking convention. + +`post-read-conversion' + Function called after a file has been read in, to perform the + decoding. Called with two arguments, START and END, denoting a + region of the current buffer to be decoded. + +`pre-write-conversion' + Function called before a file is written out, to perform the + encoding. Called with two arguments, START and END, denoting a + region of the current buffer to be encoded. + + The following additional properties are recognized if TYPE is +`iso2022': + +`charset-g0' +`charset-g1' +`charset-g2' +`charset-g3' + The character set initially designated to the G0 - G3 registers. + The value should be one of + + * A charset object (designate that character set) + + * `nil' (do not ever use this register) + + * `t' (no character set is initially designated to the + register, but may be later on; this automatically sets the + corresponding `force-g*-on-output' property) + +`force-g0-on-output' +`force-g1-on-output' +`force-g2-on-output' +`force-g3-on-output' + If non-`nil', send an explicit designation sequence on output + before using the specified register. + +`short' + If non-`nil', use the short forms `ESC $ @', `ESC $ A', and `ESC $ + B' on output in place of the full designation sequences `ESC $ ( + @', `ESC $ ( A', and `ESC $ ( B'. + +`no-ascii-eol' + If non-`nil', don't designate ASCII to G0 at each end of line on + output. Setting this to non-`nil' also suppresses other + state-resetting that normally happens at the end of a line. + +`no-ascii-cntl' + If non-`nil', don't designate ASCII to G0 before control chars on + output. + +`seven' + If non-`nil', use 7-bit environment on output. Otherwise, use + 8-bit environment. + +`lock-shift' + If non-`nil', use locking-shift (SO/SI) instead of single-shift or + designation by escape sequence. + +`no-iso6429' + If non-`nil', don't use ISO6429's direction specification. + +`escape-quoted' + If non-`nil', literal control characters that are the same as the + beginning of a recognized ISO 2022 or ISO 6429 escape sequence (in + particular, ESC (0x1B), SO (0x0E), SI (0x0F), SS2 (0x8E), SS3 + (0x8F), and CSI (0x9B)) are "quoted" with an escape character so + that they can be properly distinguished from an escape sequence. + (Note that doing this results in a non-portable encoding.) This + encoding flag is used for byte-compiled files. Note that ESC is a + good choice for a quoting character because there are no escape + sequences whose second byte is a character from the Control-0 or + Control-1 character sets; this is explicitly disallowed by the ISO + 2022 standard. + +`input-charset-conversion' + A list of conversion specifications, specifying conversion of + characters in one charset to another when decoding is performed. + Each specification is a list of two elements: the source charset, + and the destination charset. + +`output-charset-conversion' + A list of conversion specifications, specifying conversion of + characters in one charset to another when encoding is performed. + The form of each specification is the same as for + `input-charset-conversion'. + + The following additional properties are recognized (and required) if +TYPE is `ccl': + +`decode' + CCL program used for decoding (converting to internal format). + +`encode' + CCL program used for encoding (converting to external format). + + The following properties are used internally: EOL-CR, EOL-CRLF, +EOL-LF, and BASE.  -File: lispref.info, Node: Garbage Collection, Prev: Pure Storage, Up: Building XEmacs and Object Allocation - -Garbage Collection -================== - - When a program creates a list or the user defines a new function -(such as by loading a library), that data is placed in normal storage. -If normal storage runs low, then XEmacs asks the operating system to -allocate more memory in blocks of 2k bytes. Each block is used for one -type of Lisp object, so symbols, cons cells, markers, etc., are -segregated in distinct blocks in memory. (Vectors, long strings, -buffers and certain other editing types, which are fairly large, are -allocated in individual blocks, one per object, while small strings are -packed into blocks of 8k bytes. [More correctly, a string is allocated -in two sections: a fixed size chunk containing the length, list of -extents, etc.; and a chunk containing the actual characters in the -string. It is this latter chunk that is either allocated individually -or packed into 8k blocks. The fixed size chunk is packed into 2k -blocks, as for conses, markers, etc.]) - - It is quite common to use some storage for a while, then release it -by (for example) killing a buffer or deleting the last pointer to an -object. XEmacs provides a "garbage collector" to reclaim this -abandoned storage. (This name is traditional, but "garbage recycler" -might be a more intuitive metaphor for this facility.) - - The garbage collector operates by finding and marking all Lisp -objects that are still accessible to Lisp programs. To begin with, it -assumes all the symbols, their values and associated function -definitions, and any data presently on the stack, are accessible. Any -objects that can be reached indirectly through other accessible objects -are also accessible. - - When marking is finished, all objects still unmarked are garbage. No -matter what the Lisp program or the user does, it is impossible to refer -to them, since there is no longer a way to reach them. Their space -might as well be reused, since no one will miss them. The second -("sweep") phase of the garbage collector arranges to reuse them. - - The sweep phase puts unused cons cells onto a "free list" for future -allocation; likewise for symbols, markers, extents, events, floats, -compiled-function objects, and the fixed-size portion of strings. It -compacts the accessible small string-chars chunks so they occupy fewer -8k blocks; then it frees the other 8k blocks. Vectors, buffers, -windows, and other large objects are individually allocated and freed -using `malloc' and `free'. - - Common Lisp note: unlike other Lisps, XEmacs Lisp does not call - the garbage collector when the free list is empty. Instead, it - simply requests the operating system to allocate more storage, and - processing continues until `gc-cons-threshold' bytes have been - used. - - This means that you can make sure that the garbage collector will - not run during a certain portion of a Lisp program by calling the - garbage collector explicitly just before it (provided that portion - of the program does not use so much space as to force a second - garbage collection). - - - Command: garbage-collect - This command runs a garbage collection, and returns information on - the amount of space in use. (Garbage collection can also occur - spontaneously if you use more than `gc-cons-threshold' bytes of - Lisp data since the previous garbage collection.) - - `garbage-collect' returns a list containing the following - information: - - ((USED-CONSES . FREE-CONSES) - (USED-SYMS . FREE-SYMS) - (USED-MARKERS . FREE-MARKERS) - USED-STRING-CHARS - USED-VECTOR-SLOTS - (PLIST)) - - => ((73362 . 8325) (13718 . 164) - (5089 . 5098) 949121 118677 - (conses-used 73362 conses-free 8329 cons-storage 658168 - symbols-used 13718 symbols-free 164 symbol-storage 335216 - bit-vectors-used 0 bit-vectors-total-length 0 - bit-vector-storage 0 vectors-used 7882 - vectors-total-length 118677 vector-storage 537764 - compiled-functions-used 1336 compiled-functions-free 37 - compiled-function-storage 44440 short-strings-used 28829 - long-strings-used 2 strings-free 7722 - short-strings-total-length 916657 short-string-storage 1179648 - long-strings-total-length 32464 string-header-storage 441504 - floats-used 3 floats-free 43 float-storage 2044 markers-used 5089 - markers-free 5098 marker-storage 245280 events-used 103 - events-free 835 event-storage 110656 extents-used 10519 - extents-free 2718 extent-storage 372736 - extent-auxiliarys-used 111 extent-auxiliarys-freed 3 - extent-auxiliary-storage 4440 window-configurations-used 39 - window-configurations-on-free-list 5 - window-configurations-freed 10 window-configuration-storage 9492 - popup-datas-used 3 popup-data-storage 72 toolbar-buttons-used 62 - toolbar-button-storage 4960 toolbar-datas-used 12 - toolbar-data-storage 240 symbol-value-buffer-locals-used 182 - symbol-value-buffer-local-storage 5824 - symbol-value-lisp-magics-used 22 - symbol-value-lisp-magic-storage 1496 - symbol-value-varaliases-used 43 - symbol-value-varalias-storage 1032 opaque-lists-used 2 - opaque-list-storage 48 color-instances-used 12 - color-instance-storage 288 font-instances-used 5 - font-instance-storage 180 opaques-used 11 opaque-storage 312 - range-tables-used 1 range-table-storage 16 faces-used 34 - face-storage 2584 glyphs-used 124 glyph-storage 4464 - specifiers-used 775 specifier-storage 43869 weak-lists-used 786 - weak-list-storage 18864 char-tables-used 40 - char-table-storage 41920 buffers-used 25 buffer-storage 7000 - extent-infos-used 457 extent-infos-freed 73 - extent-info-storage 9140 keymaps-used 275 keymap-storage 12100 - consoles-used 4 console-storage 384 command-builders-used 2 - command-builder-storage 120 devices-used 2 device-storage 344 - frames-used 3 frame-storage 624 image-instances-used 47 - image-instance-storage 3008 windows-used 27 windows-freed 2 - window-storage 9180 lcrecord-lists-used 15 - lcrecord-list-storage 360 hash-tables-used 631 - hash-table-storage 25240 streams-used 1 streams-on-free-list 3 - streams-freed 12 stream-storage 91)) - - Here is a table explaining each element: - - USED-CONSES - The number of cons cells in use. - - FREE-CONSES - The number of cons cells for which space has been obtained - from the operating system, but that are not currently being - used. - - USED-SYMS - The number of symbols in use. - - FREE-SYMS - The number of symbols for which space has been obtained from - the operating system, but that are not currently being used. - - USED-MARKERS - The number of markers in use. - - FREE-MARKERS - The number of markers for which space has been obtained from - the operating system, but that are not currently being used. - - USED-STRING-CHARS - The total size of all strings, in characters. - - USED-VECTOR-SLOTS - The total number of elements of existing vectors. - - PLIST - A list of alternating keyword/value pairs providing more - detailed information. (As you can see above, quite a lot of - information is provided.) - - - User Option: gc-cons-threshold - The value of this variable is the number of bytes of storage that - must be allocated for Lisp objects after one garbage collection in - order to trigger another garbage collection. A cons cell counts - as eight bytes, a string as one byte per character plus a few - bytes of overhead, and so on; space allocated to the contents of - buffers does not count. Note that the subsequent garbage - collection does not happen immediately when the threshold is - exhausted, but only the next time the Lisp evaluator is called. - - The initial threshold value is 500,000. If you specify a larger - value, garbage collection will happen less often. This reduces the - amount of time spent garbage collecting, but increases total - memory use. You may want to do this when running a program that - creates lots of Lisp data. - - You can make collections more frequent by specifying a smaller - value, down to 10,000. A value less than 10,000 will remain in - effect only until the subsequent garbage collection, at which time - `garbage-collect' will set the threshold back to 10,000. (This does - not apply if XEmacs was configured with `--debug'. Therefore, be - careful when setting `gc-cons-threshold' in that case!) - - - Function: memory-limit - This function returns the address of the last byte XEmacs has - allocated, divided by 1024. We divide the value by 1024 to make - sure it fits in a Lisp integer. - - You can use this to get a general idea of how your actions affect - the memory usage. - - - Variable: pre-gc-hook - This is a normal hook to be run just before each garbage - collection. Interrupts, garbage collection, and errors are - inhibited while this hook runs, so be extremely careful in what - you add here. In particular, avoid consing, and do not interact - with the user. - - - Variable: post-gc-hook - This is a normal hook to be run just after each garbage collection. - Interrupts, garbage collection, and errors are inhibited while - this hook runs, so be extremely careful in what you add here. In - particular, avoid consing, and do not interact with the user. - - - Variable: gc-message - This is a string to print to indicate that a garbage collection is - in progress. This is printed in the echo area. If the selected - frame is on a window system and `gc-pointer-glyph' specifies a - value (i.e. a pointer image instance) in the domain of the - selected frame, the mouse cursor will change instead of this - message being printed. - - - Glyph: gc-pointer-glyph - This holds the pointer glyph used to indicate that a garbage - collection is in progress. If the selected window is on a window - system and this glyph specifies a value (i.e. a pointer image - instance) in the domain of the selected window, the cursor will be - changed as specified during garbage collection. Otherwise, a - message will be printed in the echo area, as controlled by - `gc-message'. *Note Glyphs::. - - If XEmacs was configured with `--debug', you can set the following -two variables to get direct information about all the allocation that -is happening in a segment of Lisp code. - - - Variable: debug-allocation - If non-zero, print out information to stderr about all objects - allocated. - - - Variable: debug-allocation-backtrace - Length (in stack frames) of short backtrace printed out by - `debug-allocation'. +File: lispref.info, Node: Basic Coding System Functions, Next: Coding System Property Functions, Prev: Coding System Properties, Up: Coding Systems - -File: lispref.info, Node: Standard Errors, Next: Standard Buffer-Local Variables, Prev: Building XEmacs and Object Allocation, Up: Top - -Standard Errors -*************** - - Here is the complete list of the error symbols in standard Emacs, -grouped by concept. The list includes each symbol's message (on the -`error-message' property of the symbol) and a cross reference to a -description of how the error can occur. - - Each error symbol has an `error-conditions' property that is a list -of symbols. Normally this list includes the error symbol itself and -the symbol `error'. Occasionally it includes additional symbols, which -are intermediate classifications, narrower than `error' but broader -than a single error symbol. For example, all the errors in accessing -files have the condition `file-error'. - - As a special exception, the error symbol `quit' does not have the -condition `error', because quitting is not considered an error. - - *Note Errors::, for an explanation of how errors are generated and -handled. - -`SYMBOL' - STRING; REFERENCE. - -`error' - `"error"' - *Note Errors::. - -`quit' - `"Quit"' - *Note Quitting::. - -`args-out-of-range' - `"Args out of range"' - *Note Sequences Arrays Vectors::. - -`arith-error' - `"Arithmetic error"' - See `/' and `%' in *Note Numbers::. - -`beginning-of-buffer' - `"Beginning of buffer"' - *Note Motion::. - -`buffer-read-only' - `"Buffer is read-only"' - *Note Read Only Buffers::. - -`cyclic-function-indirection' - `"Symbol's chain of function indirections contains a loop"' - *Note Function Indirection::. - -`domain-error' - `"Arithmetic domain error"' -`end-of-buffer' - `"End of buffer"' - *Note Motion::. - -`end-of-file' - `"End of file during parsing"' - This is not a `file-error'. - *Note Input Functions::. - -`file-error' - This error and its subcategories do not have error-strings, - because the error message is constructed from the data items alone - when the error condition `file-error' is present. - *Note Files::. - -`file-locked' - This is a `file-error'. - *Note File Locks::. - -`file-already-exists' - This is a `file-error'. - *Note Writing to Files::. - -`file-supersession' - This is a `file-error'. - *Note Modification Time::. - -`invalid-byte-code' - `"Invalid byte code"' - *Note Byte Compilation::. - -`invalid-function' - `"Invalid function"' - *Note Classifying Lists::. - -`invalid-read-syntax' - `"Invalid read syntax"' - *Note Input Functions::. - -`invalid-regexp' - `"Invalid regexp"' - *Note Regular Expressions::. - -`mark-inactive' - `"The mark is not active now"' -`no-catch' - `"No catch for tag"' - *Note Catch and Throw::. - -`overflow-error' - `"Arithmetic overflow error"' -`protected-field' - `"Attempt to modify a protected field"' -`range-error' - `"Arithmetic range error"' -`search-failed' - `"Search failed"' - *Note Searching and Matching::. - -`setting-constant' - `"Attempt to set a constant symbol"' - *Note Variables that Never Change: Constant Variables. - -`singularity-error' - `"Arithmetic singularity error"' -`tooltalk-error' - `"ToolTalk error"' - *Note ToolTalk Support::. - -`undefined-keystroke-sequence' - `"Undefined keystroke sequence"' -`void-function' - `"Symbol's function definition is void"' - *Note Function Cells::. - -`void-variable' - `"Symbol's value as variable is void"' - *Note Accessing Variables::. - -`wrong-number-of-arguments' - `"Wrong number of arguments"' - *Note Classifying Lists::. - -`wrong-type-argument' - `"Wrong type argument"' - *Note Type Predicates::. - - These error types, which are all classified as special cases of -`arith-error', can occur on certain systems for invalid use of -mathematical functions. - -`domain-error' - `"Arithmetic domain error"' - *Note Math Functions::. - -`overflow-error' - `"Arithmetic overflow error"' - *Note Math Functions::. - -`range-error' - `"Arithmetic range error"' - *Note Math Functions::. - -`singularity-error' - `"Arithmetic singularity error"' - *Note Math Functions::. - -`underflow-error' - `"Arithmetic underflow error"' - *Note Math Functions::. - - -File: lispref.info, Node: Standard Buffer-Local Variables, Next: Standard Keymaps, Prev: Standard Errors, Up: Top - -Buffer-Local Variables -********************** - - The table below lists the general-purpose Emacs variables that are -automatically local (when set) in each buffer. Many Lisp packages -define such variables for their internal use; we don't list them here. - -`abbrev-mode' - *note Abbrevs:: - -`auto-fill-function' - *note Auto Filling:: - -`buffer-auto-save-file-name' - *note Auto-Saving:: - -`buffer-backed-up' - *note Backup Files:: - -`buffer-display-table' - *note Display Tables:: - -`buffer-file-format' - *note Format Conversion:: - -`buffer-file-name' - *note Buffer File Name:: - -`buffer-file-number' - *note Buffer File Name:: - -`buffer-file-truename' - *note Buffer File Name:: - -`buffer-file-type' - *note Files and MS-DOS:: - -`buffer-invisibility-spec' - *note Invisible Text:: - -`buffer-offer-save' - *note Saving Buffers:: - -`buffer-read-only' - *note Read Only Buffers:: - -`buffer-saved-size' - *note Point:: - -`buffer-undo-list' - *note Undo:: - -`cache-long-line-scans' - *note Text Lines:: - -`case-fold-search' - *note Searching and Case:: - -`ctl-arrow' - *note Usual Display:: - -`comment-column' - *note Comments: (emacs)Comments. - -`default-directory' - *note System Environment:: - -`defun-prompt-regexp' - *note List Motion:: - -`fill-column' - *note Auto Filling:: - -`goal-column' - *note Moving Point: (emacs)Moving Point. - -`left-margin' - *note Indentation:: - -`local-abbrev-table' - *note Abbrevs:: - -`local-write-file-hooks' - *note Saving Buffers:: - -`major-mode' - *note Mode Help:: - -`mark-active' - *note The Mark:: - -`mark-ring' - *note The Mark:: - -`minor-modes' - *note Minor Modes:: - -`modeline-format' - *note Modeline Data:: - -`modeline-buffer-identification' - *note Modeline Variables:: - -`modeline-format' - *note Modeline Data:: +Basic Coding System Functions +----------------------------- -`modeline-modified' - *note Modeline Variables:: + - Function: find-coding-system coding-system-or-name + This function retrieves the coding system of the given name. -`modeline-process' - *note Modeline Variables:: + If CODING-SYSTEM-OR-NAME is a coding-system object, it is simply + returned. Otherwise, CODING-SYSTEM-OR-NAME should be a symbol. + If there is no such coding system, `nil' is returned. Otherwise + the associated coding system object is returned. -`mode-name' - *note Modeline Variables:: + - Function: get-coding-system name + This function retrieves the coding system of the given name. Same + as `find-coding-system' except an error is signalled if there is no + such coding system instead of returning `nil'. -`overwrite-mode' - *note Insertion:: + - Function: coding-system-list + This function returns a list of the names of all defined coding + systems. -`paragraph-separate' - *note Standard Regexps:: + - Function: coding-system-name coding-system + This function returns the name of the given coding system. -`paragraph-start' - *note Standard Regexps:: + - Function: coding-system-base coding-system + Returns the base coding system (undecided EOL convention) coding + system. -`point-before-scroll' - Used for communication between mouse commands and scroll-bar - commands. + - Function: make-coding-system name type &optional doc-string props + This function registers symbol NAME as a coding system. -`require-final-newline' - *note Insertion:: + TYPE describes the conversion method used and should be one of the + types listed in *Note Coding System Types::. -`selective-display' - *note Selective Display:: + DOC-STRING is a string describing the coding system. -`selective-display-ellipses' - *note Selective Display:: + PROPS is a property list, describing the specific nature of the + character set. Recognized properties are as in *Note Coding + System Properties::. -`tab-width' - *note Usual Display:: + - Function: copy-coding-system old-coding-system new-name + This function copies OLD-CODING-SYSTEM to NEW-NAME. If NEW-NAME + does not name an existing coding system, a new one will be created. -`truncate-lines' - *note Truncation:: - -`vc-mode' - *note Modeline Variables:: + - Function: subsidiary-coding-system coding-system eol-type + This function returns the subsidiary coding system of + CODING-SYSTEM with eol type EOL-TYPE.  -File: lispref.info, Node: Standard Keymaps, Next: Standard Hooks, Prev: Standard Buffer-Local Variables, Up: Top - -Standard Keymaps -**************** - - The following symbols are used as the names for various keymaps. -Some of these exist when XEmacs is first started, others are loaded -only when their respective mode is used. This is not an exhaustive -list. - - Almost all of these maps are used as local maps. Indeed, of the -modes that presently exist, only Vip mode and Terminal mode ever change -the global keymap. - -`bookmark-map' - A keymap containing bindings to bookmark functions. - -`Buffer-menu-mode-map' - A keymap used by Buffer Menu mode. - -`c++-mode-map' - A keymap used by C++ mode. - -`c-mode-map' - A keymap used by C mode. A sparse keymap used by C mode. - -`command-history-map' - A keymap used by Command History mode. - -`ctl-x-4-map' - A keymap for subcommands of the prefix `C-x 4'. - -`ctl-x-5-map' - A keymap for subcommands of the prefix `C-x 5'. - -`ctl-x-map' - A keymap for `C-x' commands. - -`debugger-mode-map' - A keymap used by Debugger mode. - -`dired-mode-map' - A keymap for `dired-mode' buffers. - -`edit-abbrevs-map' - A keymap used in `edit-abbrevs'. - -`edit-tab-stops-map' - A keymap used in `edit-tab-stops'. - -`electric-buffer-menu-mode-map' - A keymap used by Electric Buffer Menu mode. - -`electric-history-map' - A keymap used by Electric Command History mode. - -`emacs-lisp-mode-map' - A keymap used by Emacs Lisp mode. - -`help-map' - A keymap for characters following the Help key. - -`Helper-help-map' - A keymap used by the help utility package. - It has the same keymap in its value cell and in its function cell. - -`Info-edit-map' - A keymap used by the `e' command of Info. - -`Info-mode-map' - A keymap containing Info commands. - -`isearch-mode-map' - A keymap that defines the characters you can type within - incremental search. - -`itimer-edit-map' - A keymap used when in Itimer Edit mode. - -`lisp-interaction-mode-map' - A keymap used by Lisp mode. - -`lisp-mode-map' - A keymap used by Lisp mode. - - A keymap for minibuffer input with completion. - -`minibuffer-local-isearch-map' - A keymap for editing isearch strings in the minibuffer. - -`minibuffer-local-map' - Default keymap to use when reading from the minibuffer. - -`minibuffer-local-must-match-map' - A keymap for minibuffer input with completion, for exact match. - -`mode-specific-map' - The keymap for characters following `C-c'. Note, this is in the - global map. This map is not actually mode specific: its name was - chosen to be informative for the user in `C-h b' - (`display-bindings'), where it describes the main use of the `C-c' - prefix key. - -`modeline-map' - The keymap consulted for mouse-clicks on the modeline of a window. - -`objc-mode-map' - A keymap used in Objective C mode as a local map. - -`occur-mode-map' - A local keymap used by Occur mode. - -`overriding-local-map' - A keymap that overrides all other local keymaps. - -`query-replace-map' - A local keymap used for responses in `query-replace' and related - commands; also for `y-or-n-p' and `map-y-or-n-p'. The functions - that use this map do not support prefix keys; they look up one - event at a time. +File: lispref.info, Node: Coding System Property Functions, Next: Encoding and Decoding Text, Prev: Basic Coding System Functions, Up: Coding Systems -`read-expression-map' - The minibuffer keymap used for reading Lisp expressions. +Coding System Property Functions +-------------------------------- -`read-shell-command-map' - The minibuffer keymap used by shell-command and related commands. + - Function: coding-system-doc-string coding-system + This function returns the doc string for CODING-SYSTEM. -`shared-lisp-mode-map' - A keymap for commands shared by all sorts of Lisp modes. + - Function: coding-system-type coding-system + This function returns the type of CODING-SYSTEM. -`text-mode-map' - A keymap used by Text mode. - -`toolbar-map' - The keymap consulted for mouse-clicks over a toolbar. - -`view-mode-map' - A keymap used by View mode. + - Function: coding-system-property coding-system prop + This function returns the PROP property of CODING-SYSTEM.  -File: lispref.info, Node: Standard Hooks, Next: Index, Prev: Standard Keymaps, Up: Top - -Standard Hooks -************** - - The following is a list of hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - - Most of these variables have names ending with `-hook'. They are -"normal hooks", run by means of `run-hooks'. The value of such a hook -is a list of functions. The recommended way to put a new function on -such a hook is to call `add-hook'. *Note Hooks::, for more information -about using hooks. - - The variables whose names end in `-function' have single functions -as their values. Usually there is a specific reason why the variable is -not a normal hook, such as the need to pass arguments to the function. -(In older Emacs versions, some of these variables had names ending in -`-hook' even though they were not normal hooks.) - - The variables whose names end in `-hooks' or `-functions' have lists -of functions as their values, but these functions are called in a -special way (they are passed arguments, or else their values are used). - -`activate-menubar-hook' - -`activate-popup-menu-hook' - -`ad-definition-hooks' - -`adaptive-fill-function' - -`add-log-current-defun-function' - -`after-change-functions' - -`after-delete-annotation-hook' - -`after-init-hook' - -`after-insert-file-functions' - -`after-revert-hook' - -`after-save-hook' - -`after-set-visited-file-name-hooks' - -`after-write-file-hooks' - -`auto-fill-function' - -`auto-save-hook' - -`before-change-functions' - -`before-delete-annotation-hook' - -`before-init-hook' - -`before-revert-hook' - -`blink-paren-function' - -`buffers-menu-switch-to-buffer-function' - -`c++-mode-hook' - -`c-delete-function' - -`c-mode-common-hook' - -`c-mode-hook' - -`c-special-indent-hook' - -`calendar-load-hook' - -`change-major-mode-hook' - -`command-history-hook' - -`comment-indent-function' - -`compilation-buffer-name-function' - -`compilation-exit-message-function' - -`compilation-finish-function' - -`compilation-parse-errors-function' - -`compilation-mode-hook' - -`create-console-hook' - -`create-device-hook' - -`create-frame-hook' - -`dabbrev-friend-buffer-function' - -`dabbrev-select-buffers-function' - -`delete-console-hook' - -`delete-device-hook' - -`delete-frame-hook' - -`deselect-frame-hook' - -`diary-display-hook' - -`diary-hook' - -`dired-after-readin-hook' - -`dired-before-readin-hook' - -`dired-load-hook' - -`dired-mode-hook' - -`disabled-command-hook' - -`display-buffer-function' - -`ediff-after-setup-control-frame-hook' - -`ediff-after-setup-windows-hook' - -`ediff-before-setup-control-frame-hook' - -`ediff-before-setup-windows-hook' - -`ediff-brief-help-message-function' - -`ediff-cleanup-hook' - -`ediff-control-frame-position-function' - -`ediff-display-help-hook' - -`ediff-focus-on-regexp-matches-function' - -`ediff-forward-word-function' - -`ediff-hide-regexp-matches-function' - -`ediff-keymap-setup-hook' - -`ediff-load-hook' - -`ediff-long-help-message-function' - -`ediff-make-wide-display-function' +File: lispref.info, Node: Encoding and Decoding Text, Next: Detection of Textual Encoding, Prev: Coding System Property Functions, Up: Coding Systems + +Encoding and Decoding Text +-------------------------- + + - Function: decode-coding-region start end coding-system &optional + buffer + This function decodes the text between START and END which is + encoded in CODING-SYSTEM. This is useful if you've read in + encoded text from a file without decoding it (e.g. you read in a + JIS-formatted file but used the `binary' or `no-conversion' coding + system, so that it shows up as `^[$B!> | <8 | >8 | // + | < | > | == | <= | >= | != | de-sjis | en-sjis +ASSIGNMENT_OPERATOR := + += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>= +ARRAY := '[' integer ... ']' -`vm-rename-current-buffer-function' + +File: lispref.info, Node: CCL Statements, Next: CCL Expressions, Prev: CCL Syntax, Up: CCL + +CCL Statements +-------------- + + The Emacs Code Conversion Language provides the following statement +types: "set", "if", "branch", "loop", "repeat", "break", "read", +"write", "call", and "end". + +Set statement: +============== + + The "set" statement has three variants with the syntaxes `(REG = +EXPRESSION)', `(REG ASSIGNMENT_OPERATOR EXPRESSION)', and `INTEGER'. +The assignment operator variation of the "set" statement works the same +way as the corresponding C expression statement does. The assignment +operators are `+=', `-=', `*=', `/=', `%=', `&=', `|=', `^=', `<<=', +and `>>=', and they have the same meanings as in C. A "naked integer" +INTEGER is equivalent to a SET statement of the form `(r0 = INTEGER)'. + +I/O statements: +=============== + + The "read" statement takes one or more registers as arguments. It +reads one byte (a C char) from the input into each register in turn. + + The "write" takes several forms. In the form `(write REG ...)' it +takes one or more registers as arguments and writes each in turn to the +output. The integer in a register (interpreted as an Emchar) is +encoded to multibyte form (ie, Bufbytes) and written to the current +output buffer. If it is less than 256, it is written as is. The forms +`(write EXPRESSION)' and `(write INTEGER)' are treated analogously. +The form `(write STRING)' writes the constant string to the output. A +"naked string" `STRING' is equivalent to the statement `(write +STRING)'. The form `(write REG ARRAY)' writes the REGth element of the +ARRAY to the output. + +Conditional statements: +======================= + + The "if" statement takes an EXPRESSION, a CCL BLOCK, and an optional +SECOND CCL BLOCK as arguments. If the EXPRESSION evaluates to +non-zero, the first CCL BLOCK is executed. Otherwise, if there is a +SECOND CCL BLOCK, it is executed. + + The "read-if" variant of the "if" statement takes an EXPRESSION, a +CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. The +EXPRESSION must have the form `(REG OPERATOR OPERAND)' (where OPERAND is +a register or an integer). The `read-if' statement first reads from +the input into the first register operand in the EXPRESSION, then +conditionally executes a CCL block just as the `if' statement does. + + The "branch" statement takes an EXPRESSION and one or more CCL +blocks as arguments. The CCL blocks are treated as a zero-indexed +array, and the `branch' statement uses the EXPRESSION as the index of +the CCL block to execute. Null CCL blocks may be used as no-ops, +continuing execution with the statement following the `branch' +statement in the containing CCL block. Out-of-range values for the +EXPRESSION are also treated as no-ops. + + The "read-branch" variant of the "branch" statement takes an +REGISTER, a CCL BLOCK, and an optional SECOND CCL BLOCK as arguments. +The `read-branch' statement first reads from the input into the +REGISTER, then conditionally executes a CCL block just as the `branch' +statement does. + +Loop control statements: +======================== + + The "loop" statement creates a block with an implied jump from the +end of the block back to its head. The loop is exited on a `break' +statement, and continued without executing the tail by a `repeat' +statement. + + The "break" statement, written `(break)', terminates the current +loop and continues with the next statement in the current block. + + The "repeat" statement has three variants, `repeat', `write-repeat', +and `write-read-repeat'. Each continues the current loop from its +head, possibly after performing I/O. `repeat' takes no arguments and +does no I/O before jumping. `write-repeat' takes a single argument (a +register, an integer, or a string), writes it to the output, then jumps. +`write-read-repeat' takes one or two arguments. The first must be a +register. The second may be an integer or an array; if absent, it is +implicitly set to the first (register) argument. `write-read-repeat' +writes its second argument to the output, then reads from the input +into the register, and finally jumps. See the `write' and `read' +statements for the semantics of the I/O operations for each type of +argument. + +Other control statements: +========================= + + The "call" statement, written `(call CCL-PROGRAM-NAME)', executes a +CCL program as a subroutine. It does not return a value to the caller, +but can modify the register status. + + The "end" statement, written `(end)', terminates the CCL program +successfully, and returns to caller (which may be a CCL program). It +does not alter the status of the registers. -`vm-reply-hook' + +File: lispref.info, Node: CCL Expressions, Next: Calling CCL, Prev: CCL Statements, Up: CCL + +CCL Expressions +--------------- + + CCL, unlike Lisp, uses infix expressions. The simplest CCL +expressions consist of a single OPERAND, either a register (one of `r0', +..., `r0') or an integer. Complex expressions are lists of the form `( +EXPRESSION OPERATOR OPERAND )'. Unlike C, assignments are not +expressions. + + In the following table, X is the target resister for a "set". In +subexpressions, this is implicitly `r7'. This means that `>8', `//', +`de-sjis', and `en-sjis' cannot be used freely in subexpressions, since +they return parts of their values in `r7'. Y may be an expression, +register, or integer, while Z must be a register or an integer. + +Name Operator Code C-like Description +CCL_PLUS `+' 0x00 X = Y + Z +CCL_MINUS `-' 0x01 X = Y - Z +CCL_MUL `*' 0x02 X = Y * Z +CCL_DIV `/' 0x03 X = Y / Z +CCL_MOD `%' 0x04 X = Y % Z +CCL_AND `&' 0x05 X = Y & Z +CCL_OR `|' 0x06 X = Y | Z +CCL_XOR `^' 0x07 X = Y ^ Z +CCL_LSH `<<' 0x08 X = Y << Z +CCL_RSH `>>' 0x09 X = Y >> Z +CCL_LSH8 `<8' 0x0A X = (Y << 8) | Z +CCL_RSH8 `>8' 0x0B X = Y >> 8, r[7] = Y & 0xFF +CCL_DIVMOD `//' 0x0C X = Y / Z, r[7] = Y % Z +CCL_LS `<' 0x10 X = (X < Y) +CCL_GT `>' 0x11 X = (X > Y) +CCL_EQ `==' 0x12 X = (X == Y) +CCL_LE `<=' 0x13 X = (X <= Y) +CCL_GE `>=' 0x14 X = (X >= Y) +CCL_NE `!=' 0x15 X = (X != Y) +CCL_ENCODE_SJIS `en-sjis' 0x16 X = HIGHER_BYTE (SJIS (Y, Z)) + r[7] = LOWER_BYTE (SJIS (Y, Z) +CCL_DECODE_SJIS `de-sjis' 0x17 X = HIGHER_BYTE (DE-SJIS (Y, Z)) + r[7] = LOWER_BYTE (DE-SJIS (Y, Z)) + + The CCL operators are as in C, with the addition of CCL_LSH8, +CCL_RSH8, CCL_DIVMOD, CCL_ENCODE_SJIS, and CCL_DECODE_SJIS. The +CCL_ENCODE_SJIS and CCL_DECODE_SJIS treat their first and second bytes +as the high and low bytes of a two-byte character code. (SJIS stands +for Shift JIS, an encoding of Japanese characters used by Microsoft. +CCL_ENCODE_SJIS is a complicated transformation of the Japanese +standard JIS encoding to Shift JIS. CCL_DECODE_SJIS is its inverse.) +It is somewhat odd to represent the SJIS operations in infix form. -`vm-resend-bounced-message-hook' + +File: lispref.info, Node: Calling CCL, Next: CCL Examples, Prev: CCL Expressions, Up: CCL + +Calling CCL +----------- + + CCL programs are called automatically during Emacs buffer I/O when +the external representation has a coding system type of `shift-jis', +`big5', or `ccl'. The program is specified by the coding system (*note +Coding Systems::). You can also call CCL programs from other CCL +programs, and from Lisp using these functions: + + - Function: ccl-execute ccl-program status + Execute CCL-PROGRAM with registers initialized by STATUS. + CCL-PROGRAM is a vector of compiled CCL code created by + `ccl-compile'. It is an error for the program to try to execute a + CCL I/O command. STATUS must be a vector of nine values, + specifying the initial value for the R0, R1 .. R7 registers and + for the instruction counter IC. A `nil' value for a register + initializer causes the register to be set to 0. A `nil' value for + the IC initializer causes execution to start at the beginning of + the program. When the program is done, STATUS is modified (by + side-effect) to contain the ending values for the corresponding + registers and IC. + + - Function: ccl-execute-on-string ccl-program status string &optional + continue + Execute CCL-PROGRAM with initial STATUS on STRING. CCL-PROGRAM is + a vector of compiled CCL code created by `ccl-compile'. STATUS + must be a vector of nine values, specifying the initial value for + the R0, R1 .. R7 registers and for the instruction counter IC. A + `nil' value for a register initializer causes the register to be + set to 0. A `nil' value for the IC initializer causes execution + to start at the beginning of the program. An optional fourth + argument CONTINUE, if non-`nil', causes the IC to remain on the + unsatisfied read operation if the program terminates due to + exhaustion of the input buffer. Otherwise the IC is set to the end + of the program. When the program is done, STATUS is modified (by + side-effect) to contain the ending values for the corresponding + registers and IC. Returns the resulting string. + + To call a CCL program from another CCL program, it must first be +registered: + + - Function: register-ccl-program name ccl-program + Register NAME for CCL program CCL-PROGRAM in `ccl-program-table'. + CCL-PROGRAM should be the compiled form of a CCL program, or + `nil'. Return index number of the registered CCL program. + + Information about the processor time used by the CCL interpreter can +be obtained using these functions: + + - Function: ccl-elapsed-time + Returns the elapsed processor time of the CCL interpreter as cons + of user and system time, as floating point numbers measured in + seconds. If only one overall value can be determined, the return + value will be a cons of that value and 0. + + - Function: ccl-reset-elapsed-time + Resets the CCL interpreter's internal elapsed time registers. -`vm-resend-message-hook' + +File: lispref.info, Node: CCL Examples, Prev: Calling CCL, Up: CCL -`vm-retrieved-spooled-mail-hook' +CCL Examples +------------ -`vm-select-message-hook' + This section is not yet written. -`vm-select-new-message-hook' + +File: lispref.info, Node: Category Tables, Prev: CCL, Up: MULE -`vm-select-unread-message-hook' +Category Tables +=============== -`vm-send-digest-hook' + A category table is a type of char table used for keeping track of +categories. Categories are used for classifying characters for use in +regexps--you can refer to a category rather than having to use a +complicated [] expression (and category lookups are significantly +faster). -`vm-summary-mode-hook' + There are 95 different categories available, one for each printable +character (including space) in the ASCII charset. Each category is +designated by one such character, called a "category designator". They +are specified in a regexp using the syntax `\cX', where X is a category +designator. (This is not yet implemented.) -`vm-summary-pointer-update-hook' + A category table specifies, for each character, the categories that +the character is in. Note that a character can be in more than one +category. More specifically, a category table maps from a character to +either the value `nil' (meaning the character is in no categories) or a +95-element bit vector, specifying for each of the 95 categories whether +the character is in that category. -`vm-summary-redo-hook' + Special Lisp functions are provided that abstract this, so you do not +have to directly manipulate bit vectors. -`vm-summary-update-hook' + - Function: category-table-p object + This function returns `t' if OBJECT is a category table. -`vm-undisplay-buffer-hook' + - Function: category-table &optional buffer + This function returns the current category table. This is the one + specified by the current buffer, or by BUFFER if it is non-`nil'. -`vm-visit-folder-hook' + - Function: standard-category-table + This function returns the standard category table. This is the + one used for new buffers. -`window-setup-hook' + - Function: copy-category-table &optional category-table + This function returns a new category table which is a copy of + CATEGORY-TABLE, which defaults to the standard category table. -`write-contents-hooks' + - Function: set-category-table category-table &optional buffer + This function selects CATEGORY-TABLE as the new category table for + BUFFER. BUFFER defaults to the current buffer if omitted. -`write-file-data-hooks' + - Function: category-designator-p object + This function returns `t' if OBJECT is a category designator (a + char in the range `' '' to `'~''). -`write-file-hooks' + - Function: category-table-value-p object + This function returns `t' if OBJECT is a category table value. + Valid values are `nil' or a bit vector of size 95. -`write-region-annotate-functions' + +File: lispref.info, Node: Tips, Next: Building XEmacs and Object Allocation, Prev: MULE, Up: Top -`x-lost-selection-hooks' +Tips and Standards +****************** -`x-sent-selection-hooks' + This chapter describes no additional features of XEmacs Lisp. +Instead it gives advice on making effective use of the features +described in the previous chapters. -`zmacs-activate-region-hook' +* Menu: -`zmacs-deactivate-region-hook' +* Style Tips:: Writing clean and robust programs. +* Compilation Tips:: Making compiled code run fast. +* Documentation Tips:: Writing readable documentation strings. +* Comment Tips:: Conventions for writing comments. +* Library Headers:: Standard headers for library packages. -`zmacs-update-region-hook'