1 This is ../info/lispref.info, produced by makeinfo version 4.8 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
55 This Info file contains the third edition of the XEmacs Lisp
56 Reference Manual, corresponding to XEmacs version 21.0.
60 * Copying:: Conditions for copying and changing XEmacs.
61 * Introduction:: Introduction and conventions used.
63 * Packaging:: Lisp library administrative infrastructure.
65 * Lisp Data Types:: Data types of objects in XEmacs Lisp.
66 * Numbers:: Numbers and arithmetic functions.
67 * Strings and Characters:: Strings, and functions that work on them.
68 * Lists:: Lists, cons cells, and related functions.
69 * Sequences Arrays Vectors:: Lists, strings and vectors are called sequences.
70 Certain functions act on any kind of sequence.
71 The description of vectors is here as well.
72 * Symbols:: Symbols represent names, uniquely.
74 * Evaluation:: How Lisp expressions are evaluated.
75 * Control Structures:: Conditionals, loops, nonlocal exits.
76 * Variables:: Using symbols in programs to stand for values.
78 * Functions and Commands:: A function is a Lisp program that can be
79 invoked from other functions.
81 * Macros:: Macros are a way to extend the Lisp language.
82 * Customization:: Writing customization declarations.
84 * Loading:: Reading files of Lisp code into Lisp.
85 * Byte Compilation:: Compilation makes programs run faster.
86 * Debugging:: Tools and tips for debugging Lisp programs.
88 * Read and Print:: Converting Lisp objects to text and back.
89 * Minibuffers:: Using the minibuffer to read input.
90 * Command Loop:: How the editor command loop works,
91 and how you can call its subroutines.
92 * Keymaps:: Defining the bindings from keys to commands.
93 * Menus:: Defining pull-down and pop-up menus.
94 * Dialog Boxes:: Creating dialog boxes.
95 * Toolbar:: Controlling the toolbar.
96 * Gutter:: Controlling the gutter.
97 * Scrollbars:: Controlling the scrollbars.
98 * Drag and Drop:: Generic API to inter-application communication
99 via specific protocols.
100 * Modes:: Defining major and minor modes.
101 * Documentation:: Writing and using documentation strings.
103 * Files:: Accessing files.
104 * Backups and Auto-Saving:: Controlling how backups and auto-save
106 * Buffers:: Creating and using buffer objects.
107 * Windows:: Manipulating windows and displaying buffers.
108 * Frames:: Making multiple X windows.
109 * Consoles and Devices:: Opening frames on multiple TTY's or X displays.
110 * Positions:: Buffer positions and motion functions.
111 * Markers:: Markers represent positions and update
112 automatically when the text is changed.
114 * Text:: Examining and changing text in buffers.
115 * Searching and Matching:: Searching buffers for strings or regexps.
116 * Syntax Tables:: The syntax table controls word and list parsing.
117 * Abbrevs:: How Abbrev mode works, and its data structures.
119 * Extents:: Extents are regions of text with particular
120 display characteristics.
121 * Specifiers:: How faces and glyphs are specified.
122 * Faces and Window-System Objects::
123 A face is a set of display characteristics
124 specifying how text is to be displayed.
125 * Glyphs:: General interface to pixmaps displayed in a
127 * Annotations:: Higher-level interface to glyphs in a buffer.
128 * Display:: Parameters controlling screen usage.
129 The bell. Waiting for input.
131 * Hash Tables:: Fast data structures for mappings.
132 * Range Tables:: Keeping track of ranges of numbers.
133 * Databases:: An interface to standard DBM and DB databases.
135 * Processes:: Running and communicating with subprocesses.
136 * System Interface:: Getting the user id, system type, environment
137 variables, and other such things.
138 * X-Windows:: Functions specific to the X Window System.
139 * ToolTalk Support:: Interfacing with the ToolTalk message service.
140 * LDAP Support:: Interfacing with the Lightweight Directory
142 * PostgreSQL Support:: Interfacing to the PostgreSQL libpq library.
143 * Internationalization:: How Emacs supports different languages and
144 cultural conventions.
145 * MULE:: Specifics of the Asian-language support.
149 * Tips:: Advice for writing Lisp programs.
150 * Building XEmacs and Object Allocation::
151 Behind-the-scenes information about XEmacs.
152 * Standard Errors:: List of all error symbols.
153 * Standard Buffer-Local Variables:: List of variables local in all buffers.
154 * Standard Keymaps:: List of standard keymaps.
155 * Standard Hooks:: List of standard hook variables.
157 * Index:: Index including concepts, functions, variables,
160 --- The Detailed Node Listing ---
162 Here are other nodes that are inferiors of those already listed,
163 mentioned here so you can get to them in one step:
167 * Caveats:: Flaws and a request for help.
168 * Lisp History:: XEmacs Lisp is descended from Maclisp.
169 * Conventions:: How the manual is formatted.
170 * Acknowledgements:: The authors, editors, and sponsors of this manual.
174 * Some Terms:: Explanation of terms we use in this manual.
175 * nil and t:: How the symbols `nil' and `t' are used.
176 * Evaluation Notation:: The format we use for examples of evaluation.
177 * Printing Notation:: The format we use for examples that print output.
178 * Error Messages:: The format we use for examples of errors.
179 * Buffer Text Notation:: The format we use for buffer contents in examples.
180 * Format of Descriptions:: Notation for describing functions, variables, etc.
182 Format of Descriptions
184 * A Sample Function Description::
185 * A Sample Variable Description::
189 * Package Overview:: Lisp Libraries and Packages.
190 * Package Terminology:: Basic stuff.
191 * Building Packages:: Turn packaged source into a tarball.
192 * Local.rules File:: Tell the XEmacs Packaging System about your host.
193 * Creating Packages:: Tell the XEmacs Packaging System about your package.
199 * The Library Maintainer View::
200 * The Package Release Engineer View::
202 The Library Maintainer's View
204 * Infrastructure:: Global Makefiles and common rules.
205 * Control Files:: Package-specific Makefiles and administrative files.
206 * Obtaining:: Obtaining the XEmacs Packaging System and utilities.
210 * package-info.in:: package-info.in
211 * Makefile:: `Makefile'
216 * Printed Representation:: How Lisp objects are represented as text.
217 * Comments:: Comments and their formatting conventions.
218 * Programming Types:: Types found in all Lisp systems.
219 * Editing Types:: Types specific to XEmacs.
220 * Type Predicates:: Tests related to types.
221 * Equality Predicates:: Tests of equality between any two objects.
225 * Integer Type:: Numbers without fractional parts.
226 * Floating Point Type:: Numbers with fractional parts and with a large range.
227 * Character Type:: The representation of letters, numbers and
229 * Sequence Type:: Both lists and arrays are classified as sequences.
230 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
231 * Array Type:: Arrays include strings and vectors.
232 * String Type:: An (efficient) array of characters.
233 * Vector Type:: One-dimensional arrays.
234 * Symbol Type:: A multi-use object that refers to a function,
235 variable, property list, or itself.
236 * Function Type:: A piece of executable code you can call from elsewhere.
237 * Macro Type:: A method of expanding an expression into another
238 expression, more fundamental but less pretty.
239 * Primitive Function Type:: A function written in C, callable from Lisp.
240 * Compiled-Function Type:: A function written in Lisp, then compiled.
241 * Autoload Type:: A type used for automatically loading seldom-used
246 * Dotted Pair Notation:: An alternative syntax for lists.
247 * Association List Type:: A specially constructed list.
251 * Buffer Type:: The basic object of editing.
252 * Window Type:: What makes buffers visible.
253 * Window Configuration Type:: Save what the screen looks like.
254 * Marker Type:: A position in a buffer.
255 * Process Type:: A process running on the underlying OS.
256 * Stream Type:: Receive or send characters.
257 * Keymap Type:: What function a keystroke invokes.
258 * Syntax Table Type:: What a character means.
262 * Integer Basics:: Representation and range of integers.
263 * Float Basics:: Representation and range of floating point.
264 * Predicates on Numbers:: Testing for numbers.
265 * Comparison of Numbers:: Equality and inequality predicates.
266 * Arithmetic Operations:: How to add, subtract, multiply and divide.
267 * Bitwise Operations:: Logical and, or, not, shifting.
268 * Numeric Conversions:: Converting float to integer and vice versa.
269 * Math Functions:: Trig, exponential and logarithmic functions.
270 * Random Numbers:: Obtaining random integers, predictable or not.
272 Strings and Characters
274 * String Basics:: Basic properties of strings and characters.
275 * Predicates for Strings:: Testing whether an object is a string or char.
276 * Creating Strings:: Functions to allocate new strings.
277 * Predicates for Characters:: Testing whether an object is a character.
278 * Character Codes:: Each character has an equivalent integer.
279 * Text Comparison:: Comparing characters or strings.
280 * String Conversion:: Converting characters or strings and vice versa.
281 * Modifying Strings:: Changing characters in a string.
282 * String Properties:: Additional information attached to strings.
283 * Formatting Strings:: `format': XEmacs's analog of `printf'.
284 * Character Case:: Case conversion functions.
285 * Char Tables:: Mapping from characters to Lisp objects.
286 * Case Tables:: Customizing case conversion.
290 * Cons Cells:: How lists are made out of cons cells.
291 * Lists as Boxes:: Graphical notation to explain lists.
292 * List-related Predicates:: Is this object a list? Comparing two lists.
293 * List Elements:: Extracting the pieces of a list.
294 * Building Lists:: Creating list structure.
295 * Modifying Lists:: Storing new pieces into an existing list.
296 * Sets And Lists:: A list can represent a finite mathematical set.
297 * Association Lists:: A list can represent a finite relation or mapping.
298 * Property Lists:: A different way to represent a finite mapping.
299 * Weak Lists:: A list with special garbage-collection behavior.
301 Modifying Existing List Structure
303 * Setcar:: Replacing an element in a list.
304 * Setcdr:: Replacing part of the list backbone.
305 This can be used to remove or add elements.
306 * Rearrangement:: Reordering the elements in a list; combining lists.
308 Sequences, Arrays, and Vectors
310 * Sequence Functions:: Functions that accept any kind of sequence.
311 * Arrays:: Characteristics of arrays in XEmacs Lisp.
312 * Array Functions:: Functions specifically for arrays.
313 * Vectors:: Functions specifically for vectors.
317 * Symbol Components:: Symbols have names, values, function definitions
319 * Definitions:: A definition says how a symbol will be used.
320 * Creating Symbols:: How symbols are kept unique.
321 * Symbol Properties:: Each symbol has a property list
322 for recording miscellaneous information.
326 * Intro Eval:: Evaluation in the scheme of things.
327 * Eval:: How to invoke the Lisp interpreter explicitly.
328 * Forms:: How various sorts of objects are evaluated.
329 * Quoting:: Avoiding evaluation (to put constants in
334 * Self-Evaluating Forms:: Forms that evaluate to themselves.
335 * Symbol Forms:: Symbols evaluate as variables.
336 * Classifying Lists:: How to distinguish various sorts of list forms.
337 * Function Forms:: Forms that call functions.
338 * Macro Forms:: Forms that call macros.
339 * Special Forms:: ``Special forms'' are idiosyncratic primitives,
340 most of them extremely important.
341 * Autoloading:: Functions set up to load files
342 containing their real definitions.
346 * Sequencing:: Evaluation in textual order.
347 * Conditionals:: `if', `cond'.
348 * Combining Conditions:: `and', `or', `not'.
349 * Iteration:: `while' loops.
350 * Nonlocal Exits:: Jumping out of a sequence.
354 * Catch and Throw:: Nonlocal exits for the program's own purposes.
355 * Examples of Catch:: Showing how such nonlocal exits can be written.
356 * Errors:: How errors are signaled and handled.
357 * Cleanups:: Arranging to run a cleanup form if an
362 * Signaling Errors:: How to report an error.
363 * Processing of Errors:: What XEmacs does when you report an error.
364 * Handling Errors:: How you can trap errors and continue execution.
365 * Error Symbols:: How errors are classified for trapping them.
369 * Global Variables:: Variable values that exist permanently, everywhere.
370 * Constant Variables:: Certain "variables" have values that never change.
371 * Local Variables:: Variable values that exist only temporarily.
372 * Void Variables:: Symbols that lack values.
373 * Defining Variables:: A definition says a symbol is used as a variable.
374 * Accessing Variables:: Examining values of variables whose names
375 are known only at run time.
376 * Setting Variables:: Storing new values in variables.
377 * Variable Scoping:: How Lisp chooses among local and global values.
378 * Buffer-Local Variables:: Variable values in effect only in one buffer.
380 Scoping Rules for Variable Bindings
382 * Scope:: Scope means where in the program a value
383 is visible. Comparison with other languages.
384 * Extent:: Extent means how long in time a value exists.
385 * Impl of Scope:: Two ways to implement dynamic scoping.
386 * Using Scoping:: How to use dynamic scoping carefully and
389 Buffer-Local Variables
391 * Intro to Buffer-Local:: Introduction and concepts.
392 * Creating Buffer-Local:: Creating and destroying buffer-local bindings.
393 * Default Value:: The default value is seen in buffers
394 that don't have their own local values.
398 * What Is a Function:: Lisp functions vs primitives; terminology.
399 * Lambda Expressions:: How functions are expressed as Lisp objects.
400 * Function Names:: A symbol can serve as the name of a function.
401 * Defining Functions:: Lisp expressions for defining functions.
402 * Calling Functions:: How to use an existing function.
403 * Mapping Functions:: Applying a function to each element of a list, etc.
404 * Anonymous Functions:: Lambda-expressions are functions with no names.
405 * Function Cells:: Accessing or setting the function definition
407 * Related Topics:: Cross-references to specific Lisp primitives
408 that have a special bearing on how
413 * Lambda Components:: The parts of a lambda expression.
414 * Simple Lambda:: A simple example.
415 * Argument List:: Details and special features of argument lists.
416 * Function Documentation:: How to put documentation in a function.
420 * Simple Macro:: A basic example.
421 * Expansion:: How, when and why macros are expanded.
422 * Compiling Macros:: How macros are expanded by the compiler.
423 * Defining Macros:: How to write a macro definition.
424 * Backquote:: Easier construction of list structure.
425 * Problems with Macros:: Don't evaluate the macro arguments too many times.
426 Don't hide the user's variables.
430 * How Programs Do Loading:: The `load' function and others.
431 * Autoload:: Setting up a function to autoload.
432 * Named Features:: Loading a library if it isn't already loaded.
433 * Repeated Loading:: Precautions about loading a file twice.
437 * Speed of Byte-Code:: An example of speedup from byte compilation.
438 * Compilation Functions:: Byte compilation functions.
439 * Docs and Compilation:: Dynamic loading of documentation strings.
440 * Dynamic Loading:: Dynamic loading of individual functions.
441 * Eval During Compile:: Code to be evaluated when you compile.
442 * Compiled-Function Objects:: The data type used for byte-compiled functions.
443 * Disassembly:: Disassembling byte-code; how to read byte-code.
444 * Different Behavior:: When compiled code gives different results.
446 Debugging Lisp Programs
448 * Debugger:: How the XEmacs Lisp debugger is implemented.
449 * Syntax Errors:: How to find syntax errors.
450 * Compilation Errors:: How to find errors that show up in
452 * Edebug:: A source-level XEmacs Lisp debugger.
456 * Error Debugging:: Entering the debugger when an error happens.
457 * Function Debugging:: Entering it when a certain function is called.
458 * Explicit Debug:: Entering it at a certain point in the program.
459 * Using Debugger:: What the debugger does; what you see while in it.
460 * Debugger Commands:: Commands used while in the debugger.
461 * Invoking the Debugger:: How to call the function `debug'.
462 * Internals of Debugger:: Subroutines of the debugger, and global variables.
464 Debugging Invalid Lisp Syntax
466 * Excess Open:: How to find a spurious open paren or missing close.
467 * Excess Close:: How to find a spurious close paren or missing open.
469 Reading and Printing Lisp Objects
471 * Streams Intro:: Overview of streams, reading and printing.
472 * Input Streams:: Various data types that can be used as
474 * Input Functions:: Functions to read Lisp objects from text.
475 * Output Streams:: Various data types that can be used as
477 * Output Functions:: Functions to print Lisp objects as text.
481 * Intro to Minibuffers:: Basic information about minibuffers.
482 * Text from Minibuffer:: How to read a straight text string.
483 * Object from Minibuffer:: How to read a Lisp object or expression.
484 * Completion:: How to invoke and customize completion.
485 * Yes-or-No Queries:: Asking a question with a simple answer.
486 * Minibuffer Misc:: Various customization hooks and variables.
490 * Basic Completion:: Low-level functions for completing strings.
491 (These are too low level to use the minibuffer.)
492 * Minibuffer Completion:: Invoking the minibuffer with completion.
493 * Completion Commands:: Minibuffer commands that do completion.
494 * High-Level Completion:: Convenient special cases of completion
495 (reading buffer name, file name, etc.)
496 * Reading File Names:: Using completion to read file names.
497 * Programmed Completion:: Finding the completions for a given file name.
501 * Command Overview:: How the command loop reads commands.
502 * Defining Commands:: Specifying how a function should read arguments.
503 * Interactive Call:: Calling a command, so that it will read arguments.
504 * Command Loop Info:: Variables set by the command loop for you to examine.
505 * Events:: What input looks like when you read it.
506 * Reading Input:: How to read input events from the keyboard or mouse.
507 * Waiting:: Waiting for user input or elapsed time.
508 * Quitting:: How C-g works. How to catch or defer quitting.
509 * Prefix Command Arguments:: How the commands to set prefix args work.
510 * Recursive Editing:: Entering a recursive edit,
511 and why you usually shouldn't.
512 * Disabling Commands:: How the command loop handles disabled commands.
513 * Command History:: How the command history is set up, and how accessed.
514 * Keyboard Macros:: How keyboard macros are implemented.
518 * Using Interactive:: General rules for `interactive'.
519 * Interactive Codes:: The standard letter-codes for reading arguments
521 * Interactive Examples:: Examples of how to read interactive arguments.
525 * Event Types:: Events come in different types.
526 * Event Contents:: What the contents of each event type are.
527 * Event Predicates:: Querying whether an event is of a
529 * Accessing Mouse Event Positions::
530 Determining where a mouse event occurred,
532 * Accessing Other Event Info:: Accessing non-positional event info.
533 * Working With Events:: Creating, copying, and destroying events.
534 * Converting Events:: Converting between events, keys, and
537 Accessing Mouse Event Positions
539 * Frame-Level Event Position Info::
540 * Window-Level Event Position Info::
541 * Event Text Position Info::
542 * Event Glyph Position Info::
543 * Event Toolbar Position Info::
544 * Other Event Position Info::
548 * Key Sequence Input:: How to read one key sequence.
549 * Reading One Event:: How to read just one event.
550 * Dispatching an Event:: What to do with an event once it has been read.
551 * Quoted Character Input:: Asking the user to specify a character.
552 * Peeking and Discarding:: How to reread or throw away input events.
556 * Keymap Terminology:: Definitions of terms pertaining to keymaps.
557 * Format of Keymaps:: What a keymap looks like as a Lisp object.
558 * Creating Keymaps:: Functions to create and copy keymaps.
559 * Inheritance and Keymaps:: How one keymap can inherit the bindings
561 * Key Sequences:: How to specify key sequences.
562 * Prefix Keys:: Defining a key with a keymap as its definition.
563 * Active Keymaps:: Each buffer has a local keymap
564 to override the standard (global) bindings.
565 Each minor mode can also override them.
566 * Key Lookup:: How extracting elements from keymaps works.
567 * Functions for Key Lookup:: How to request key lookup.
568 * Changing Key Bindings:: Redefining a key in a keymap.
569 * Key Binding Commands:: Interactive interfaces for redefining keys.
570 * Scanning Keymaps:: Looking through all keymaps, for printing help.
571 * Other Keymap Functions:: Miscellaneous keymap functions.
575 * Menu Format:: Format of a menu description.
576 * Menubar Format:: How to specify a menubar.
577 * Menubar:: Functions for controlling the menubar.
578 * Modifying Menus:: Modifying a menu description.
579 * Pop-Up Menus:: Functions for specifying pop-up menus.
580 * Menu Filters:: Filter functions for the default menubar.
581 * Buffers Menu:: The menu that displays the list of buffers.
585 * Dialog Box Format::
586 * Dialog Box Functions::
590 * Toolbar Intro:: An introduction.
591 * Toolbar Descriptor Format:: How to create a toolbar.
592 * Specifying the Toolbar:: Setting a toolbar.
593 * Other Toolbar Variables:: Controlling the size of toolbars.
599 Major and Minor Modes
601 * Major Modes:: Defining major modes.
602 * Minor Modes:: Defining minor modes.
603 * Modeline Format:: Customizing the text that appears in the modeline.
604 * Hooks:: How to use hooks; how to write code that
609 * Major Mode Conventions:: Coding conventions for keymaps, etc.
610 * Example Major Modes:: Text mode and Lisp modes.
611 * Auto Major Mode:: How XEmacs chooses the major mode automatically.
612 * Mode Help:: Finding out how to use a mode.
616 * Minor Mode Conventions:: Tips for writing a minor mode.
617 * Keymaps and Minor Modes:: How a minor mode can have its own keymap.
621 * Modeline Data:: The data structure that controls the modeline.
622 * Modeline Variables:: Variables used in that data structure.
623 * %-Constructs:: Putting information into a modeline.
627 * Documentation Basics:: Good style for doc strings.
628 Where to put them. How XEmacs stores them.
629 * Accessing Documentation:: How Lisp programs can access doc strings.
630 * Keys in Documentation:: Substituting current key bindings.
631 * Describing Characters:: Making printable descriptions of
632 non-printing characters and key sequences.
633 * Help Functions:: Subroutines used by XEmacs help facilities.
637 * Visiting Files:: Reading files into Emacs buffers for editing.
638 * Saving Buffers:: Writing changed buffers back into files.
639 * Reading from Files:: Reading files into other buffers.
640 * Writing to Files:: Writing new files from parts of buffers.
641 * File Locks:: Locking and unlocking files, to prevent
642 simultaneous editing by two people.
643 * Information about Files:: Testing existence, accessibility, size of files.
644 * Contents of Directories:: Getting a list of the files in a directory.
645 * Changing File Attributes:: Renaming files, changing protection, etc.
646 * File Names:: Decomposing and expanding file names.
650 * Visiting Functions:: The usual interface functions for visiting.
651 * Subroutines of Visiting:: Lower-level subroutines that they use.
653 Information about Files
655 * Testing Accessibility:: Is a given file readable? Writable?
656 * Kinds of Files:: Is it a directory? A link?
657 * File Attributes:: How large is it? Any other names? Etc.
661 * File Name Components:: The directory part of a file name, and the rest.
662 * Directory Names:: A directory's name as a directory
663 is different from its name as a file.
664 * Relative File Names:: Some file names are relative to a
666 * File Name Expansion:: Converting relative file names to absolute ones.
667 * Unique File Names:: Generating names for temporary files.
668 * File Name Completion:: Finding the completions for a given file name.
670 Backups and Auto-Saving
672 * Backup Files:: How backup files are made; how their names
674 * Auto-Saving:: How auto-save files are made; how their
676 * Reverting:: `revert-buffer', and how to customize
681 * Making Backups:: How XEmacs makes backup files, and when.
682 * Rename or Copy:: Two alternatives: renaming the old file
684 * Numbered Backups:: Keeping multiple backups for each source file.
685 * Backup Names:: How backup file names are computed; customization.
689 * Buffer Basics:: What is a buffer?
690 * Buffer Names:: Accessing and changing buffer names.
691 * Buffer File Name:: The buffer file name indicates which file
693 * Buffer Modification:: A buffer is "modified" if it needs to be saved.
694 * Modification Time:: Determining whether the visited file was changed
695 ``behind XEmacs's back''.
696 * Read Only Buffers:: Modifying text is not allowed in a
698 * The Buffer List:: How to look at all the existing buffers.
699 * Creating Buffers:: Functions that create buffers.
700 * Killing Buffers:: Buffers exist until explicitly killed.
701 * Current Buffer:: Designating a buffer as current
702 so primitives will access its contents.
706 * Basic Windows:: Basic information on using windows.
707 * Splitting Windows:: Splitting one window into two windows.
708 * Deleting Windows:: Deleting a window gives its space to other windows.
709 * Selecting Windows:: The selected window is the one that you edit in.
710 * Cyclic Window Ordering:: Moving around the existing windows.
711 * Buffers and Windows:: Each window displays the contents of a buffer.
712 * Displaying Buffers:: Higher-lever functions for displaying a buffer
713 and choosing a window for it.
714 * Window Point:: Each window has its own location of point.
715 * Window Start:: The display-start position controls which text
716 is on-screen in the window.
717 * Vertical Scrolling:: Moving text up and down in the window.
718 * Horizontal Scrolling:: Moving text sideways on the window.
719 * Size of Window:: Accessing the size of a window.
720 * Resizing Windows:: Changing the size of a window.
721 * Window Configurations:: Saving and restoring the state of the screen.
725 * Creating Frames:: Creating additional frames.
726 * Frame Properties:: Controlling frame size, position, font, etc.
727 * Frame Titles:: Automatic updating of frame titles.
728 * Deleting Frames:: Frames last until explicitly deleted.
729 * Finding All Frames:: How to examine all existing frames.
730 * Frames and Windows:: A frame contains windows;
731 display of text always works through windows.
732 * Minibuffers and Frames:: How a frame finds the minibuffer to use.
733 * Input Focus:: Specifying the selected frame.
734 * Visibility of Frames:: Frames may be visible or invisible, or icons.
735 * Raising and Lowering:: Raising a frame makes it hide other X windows;
736 lowering it makes the others hide them.
737 * Frame Hooks:: Hooks for customizing frame behavior.
741 * Point:: The special position where editing takes place.
742 * Motion:: Changing point.
743 * Excursions:: Temporary motion and buffer changes.
744 * Narrowing:: Restricting editing to a portion of the buffer.
748 * Character Motion:: Moving in terms of characters.
749 * Word Motion:: Moving in terms of words.
750 * Buffer End Motion:: Moving to the beginning or end of the buffer.
751 * Text Lines:: Moving in terms of lines of text.
752 * Screen Lines:: Moving in terms of lines as displayed.
753 * List Motion:: Moving by parsing lists and sexps.
754 * Skipping Characters:: Skipping characters belonging to a certain set.
758 * Overview of Markers:: The components of a marker, and how it relocates.
759 * Predicates on Markers:: Testing whether an object is a marker.
760 * Creating Markers:: Making empty markers or markers at certain places.
761 * Information from Markers:: Finding the marker's buffer or character
763 * Changing Markers:: Moving the marker to a new buffer or position.
764 * The Mark:: How ``the mark'' is implemented with a marker.
765 * The Region:: How to access ``the region''.
769 * Near Point:: Examining text in the vicinity of point.
770 * Buffer Contents:: Examining text in a general fashion.
771 * Comparing Text:: Comparing substrings of buffers.
772 * Insertion:: Adding new text to a buffer.
773 * Commands for Insertion:: User-level commands to insert text.
774 * Deletion:: Removing text from a buffer.
775 * User-Level Deletion:: User-level commands to delete text.
776 * The Kill Ring:: Where removed text sometimes is saved for later use.
777 * Undo:: Undoing changes to the text of a buffer.
778 * Maintaining Undo:: How to enable and disable undo information.
779 How to control how much information is kept.
780 * Filling:: Functions for explicit filling.
781 * Margins:: How to specify margins for filling commands.
782 * Auto Filling:: How auto-fill mode is implemented to break lines.
783 * Sorting:: Functions for sorting parts of the buffer.
784 * Columns:: Computing horizontal positions, and using them.
785 * Indentation:: Functions to insert or adjust indentation.
786 * Case Changes:: Case conversion of parts of the buffer.
787 * Text Properties:: Assigning Lisp property lists to text characters.
788 * Substitution:: Replacing a given character wherever it appears.
789 * Registers:: How registers are implemented. Accessing the text or
790 position stored in a register.
791 * Transposition:: Swapping two portions of a buffer.
792 * Change Hooks:: Supplying functions to be run when text is changed.
796 * Kill Ring Concepts:: What text looks like in the kill ring.
797 * Kill Functions:: Functions that kill text.
798 * Yank Commands:: Commands that access the kill ring.
799 * Low-Level Kill Ring:: Functions and variables for kill ring access.
800 * Internals of Kill Ring:: Variables that hold kill-ring data.
804 * Primitive Indent:: Functions used to count and insert indentation.
805 * Mode-Specific Indent:: Customize indentation for different modes.
806 * Region Indent:: Indent all the lines in a region.
807 * Relative Indent:: Indent the current line based on previous lines.
808 * Indent Tabs:: Adjustable, typewriter-like tab stops.
809 * Motion by Indent:: Move to first non-blank character.
811 Searching and Matching
813 * String Search:: Search for an exact match.
814 * Regular Expressions:: Describing classes of strings.
815 * Regexp Search:: Searching for a match for a regexp.
816 * Match Data:: Finding out which part of the text matched
817 various parts of a regexp, after regexp search.
818 * Saving Match Data:: Saving and restoring this information.
819 * Standard Regexps:: Useful regexps for finding sentences, pages,...
820 * Searching and Case:: Case-independent or case-significant searching.
824 * Syntax of Regexps:: Rules for writing regular expressions.
825 * Regexp Example:: Illustrates regular expression syntax.
829 * Syntax Descriptors:: How characters are classified.
830 * Syntax Table Functions:: How to create, examine and alter syntax tables.
831 * Parsing Expressions:: Parsing balanced expressions
832 using the syntax table.
833 * Standard Syntax Tables:: Syntax tables used by various major modes.
834 * Syntax Table Internals:: How syntax table information is stored.
838 * Syntax Class Table:: Table of syntax classes.
839 * Syntax Flags:: Additional flags each character can have.
841 Abbrevs And Abbrev Expansion
843 * Abbrev Mode:: Setting up XEmacs for abbreviation.
844 * Tables: Abbrev Tables. Creating and working with abbrev tables.
845 * Defining Abbrevs:: Specifying abbreviations and their expansions.
846 * Files: Abbrev Files. Saving abbrevs in files.
847 * Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
848 * Standard Abbrev Tables:: Abbrev tables used by various major modes.
852 * Intro to Extents:: Extents are regions over a buffer or string.
853 * Creating and Modifying Extents::
854 Basic extent functions.
855 * Extent Endpoints:: Accessing and setting the bounds of an extent.
856 * Finding Extents:: Determining which extents are in an object.
857 * Mapping Over Extents:: More sophisticated functions for extent scanning.
858 * Extent Properties:: Extents have built-in and user-definable properties.
859 * Detached Extents:: Extents that are not in a buffer.
860 * Extent Parents:: Inheriting properties from another extent.
861 * Duplicable Extents:: Extents can be marked to be copied into strings.
862 * Extents and Events:: Extents can interact with the keyboard and mouse.
863 * Atomic Extents:: Treating a block of text as a single entity.
867 * Introduction to Specifiers:: Specifiers provide a clean way for
868 display and other properties to vary
869 (under user control) in a wide variety
871 * Specifiers In-Depth:: Gory details about specifier innards.
872 * Specifier Instancing:: Instancing means obtaining the ``value'' of
873 a specifier in a particular context.
874 * Specifier Types:: Specifiers come in different flavors.
875 * Adding Specifications:: Specifications control a specifier's ``value''
876 by giving conditions under which a
877 particular value is valid.
878 * Retrieving Specifications:: Querying a specifier's specifications.
879 * Specifier Instancing Functions::
880 Functions to instance a specifier.
881 * Specifier Examples:: Making all this stuff clearer.
882 * Creating Specifiers:: Creating specifiers for your own use.
883 * Specifier Validation Functions::
884 Validating the components of a specifier.
885 * Other Specification Functions::
886 Other ways of working with specifications.
888 Faces and Window-System Objects
890 * Faces:: Controlling the way text looks.
891 * Fonts:: Controlling the typeface of text.
892 * Colors:: Controlling the color of text and pixmaps.
896 * Merging Faces:: How XEmacs decides which face to use
898 * Basic Face Functions:: How to define and examine faces.
899 * Face Properties:: How to access and modify a face's properties.
900 * Face Convenience Functions:: Convenience functions for accessing
901 particular properties of a face.
902 * Other Face Display Functions:: Other functions pertaining to how a
907 * Font Specifiers:: Specifying how a font will appear.
908 * Font Instances:: What a font specifier gets instanced as.
909 * Font Instance Names:: The name of a font instance.
910 * Font Instance Size:: The size of a font instance.
911 * Font Instance Characteristics:: Display characteristics of font instances.
912 * Font Convenience Functions:: Convenience functions that automatically
913 instance and retrieve the properties
918 * Color Specifiers:: Specifying how a color will appear.
919 * Color Instances:: What a color specifier gets instanced as.
920 * Color Instance Properties:: Properties of color instances.
921 * Color Convenience Functions:: Convenience functions that automatically
922 instance and retrieve the properties
923 of a color specifier.
927 * Glyph Intro:: Glyphs are abstract image specifications.
928 * Images:: Specifying the appearance of glyphs.
929 * Using Glyphs:: Creating and displaying glyphs.
930 * Manipulating Glyphs:: Getting and setting glyph properties.
931 * Glyph Examples:: Examples of how to work with glyphs.
935 * Image Specifiers:: Specifying an image's appearance.
936 * Image Instantiator Conversion:: Lazy realization of graphics.
937 * Image Instantiator Formats:: A catalog of image descriptors.
938 * Image Instances:: Classes of graphical objects.
942 * Image Instance Types:: Each image instances has a particular type.
943 * Image Instance Functions:: Functions for working with image instances.
950 * Image Instance Types:: Each image instances has a particular type.
951 * Image Instance Functions:: Functions for working with image instances.
955 * Creating Glyphs:: Creating new glyphs.
956 * Buffer Glyphs:: Annotations are glyphs that appear in a buffer.
957 * Redisplay Glyphs:: Glyphs controlling various redisplay functions.
958 * Frame Glyphs:: Displaying glyphs in GUI components of the frame.
959 * External Glyphs:: Icons and mouse pointers for the window system.
960 * Native GUI Widgets:: Complex active elements treated as a single glyph.
961 * Subwindows:: Externally-controlled subwindows in buffers.
965 * Introduction to Widgets:: Native widgets provide tight integration of
966 GUI features with the platform GUI.
967 * Lisp API to Native Widgets:: Native widgets are glyphs.
968 * Layouts:: Specifying composite widgets from Lisp.
969 * Primitive Widgets:: Catalogue of available native widgets.
973 * Glyph Properties:: Accessing and modifying a glyph's properties.
974 * Glyph Convenience Functions:: Accessing particular properties of a glyph.
975 * Glyph Dimensions:: Determining the height, width, etc. of a glyph.
976 * Glyph Types:: Each glyph has a particular type.
980 * Annotation Basics:: Introduction to annotations.
981 * Annotation Primitives:: Creating and deleting annotations.
982 * Annotation Properties:: Retrieving and changing the characteristics
984 * Margin Primitives:: Controlling the size of the margins.
985 * Locating Annotations:: Looking for annotations in a buffer.
986 * Annotation Hooks:: Hooks called at certain times during an
987 annotation's lifetime.
991 * Introduction to Hash Tables:: Hash tables are fast data structures for
992 implementing simple tables (i.e. finite
993 mappings from keys to values).
994 * Working With Hash Tables:: Hash table functions.
995 * Weak Hash Tables:: Hash tables with special garbage-collection
1000 * Introduction to Range Tables:: Range tables efficiently map ranges of
1002 * Working With Range Tables:: Range table functions.
1007 * Refresh Screen:: Clearing the screen and redrawing everything on it.
1008 * Truncation:: Folding or wrapping long text lines.
1009 * The Echo Area:: Where messages are displayed.
1010 * Selective Display:: Hiding part of the buffer text.
1011 * Overlay Arrow:: Display of an arrow to indicate position.
1012 * Temporary Displays:: Displays that go away automatically.
1013 * Blinking:: How XEmacs shows the matching open parenthesis.
1014 * Usual Display:: The usual conventions for displaying nonprinting chars.
1015 * Display Tables:: How to specify other conventions.
1016 * Beeping:: Audible signal to the user.
1020 * Subprocess Creation:: Functions that start subprocesses.
1021 * Synchronous Processes:: Details of using synchronous subprocesses.
1022 * Asynchronous Processes:: Starting up an asynchronous subprocess.
1023 * Deleting Processes:: Eliminating an asynchronous subprocess.
1024 * Process Information:: Accessing run-status and other attributes.
1025 * Input to Processes:: Sending input to an asynchronous subprocess.
1026 * Signals to Processes:: Stopping, continuing or interrupting
1027 an asynchronous subprocess.
1028 * Output from Processes:: Collecting output from an asynchronous subprocess.
1029 * Sentinels:: Sentinels run when process run-status changes.
1030 * Network:: Opening network connections.
1032 Receiving Output from Processes
1034 * Process Buffers:: If no filter, output is put in a buffer.
1035 * Filter Functions:: Filter functions accept output from the process.
1036 * Accepting Output:: How to wait until process output arrives.
1038 Operating System Interface
1040 * Starting Up:: Customizing XEmacs start-up processing.
1041 * Getting Out:: How exiting works (permanent or temporary).
1042 * System Environment:: Distinguish the name and kind of system.
1043 * Terminal Input:: Recording terminal input for debugging.
1044 * Terminal Output:: Recording terminal output for debugging.
1045 * Flow Control:: How to turn output flow control on or off.
1046 * Batch Mode:: Running XEmacs without terminal interaction.
1050 * Start-up Summary:: Sequence of actions XEmacs performs at start-up.
1051 * Init File:: Details on reading the init file (`.emacs').
1052 * Terminal-Specific:: How the terminal-specific Lisp file is read.
1053 * Command Line Arguments:: How command line arguments are processed,
1054 and how you can customize them.
1056 Getting out of XEmacs
1058 * Killing XEmacs:: Exiting XEmacs irreversibly.
1059 * Suspending XEmacs:: Exiting XEmacs reversibly.
1063 * X Selections:: Transferring text to and from other X clients.
1064 * X Server:: Information about the X server connected to
1065 a particular device.
1066 * Resources:: Getting resource values from the server.
1067 * Server Data:: Getting info about the X server.
1068 * Grabs:: Restricting access to the server by other apps.
1069 * X Miscellaneous:: Other X-specific functions and variables.
1073 * XEmacs ToolTalk API Summary::
1074 * Sending Messages::
1075 * Receiving Messages::
1079 * Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
1080 * XEmacs LDAP API:: Lisp access to LDAP functions
1081 * Syntax of Search Filters:: A brief summary of RFC 1558
1085 * LDAP Variables:: Lisp variables related to LDAP
1086 * The High-Level LDAP API:: High-level LDAP lisp functions
1087 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
1088 * LDAP Internationalization:: I18n variables and functions
1090 The Low-Level LDAP API
1092 * The LDAP Lisp Object::
1093 * Opening and Closing a LDAP Connection::
1094 * Low-level Operations on a LDAP Server::
1096 LDAP Internationalization
1098 * LDAP Internationalization Variables::
1099 * Encoder/Decoder Functions::
1101 Internationalization
1103 * I18N Levels 1 and 2:: Support for different time, date, and currency formats.
1104 * I18N Level 3:: Support for localized messages.
1105 * I18N Level 4:: Support for Asian languages.
1109 * Internationalization Terminology::
1110 Definition of various internationalization terms.
1111 * Charsets:: Sets of related characters.
1112 * MULE Characters:: Working with characters in XEmacs/MULE.
1113 * Composite Characters:: Making new characters by overstriking other ones.
1114 * ISO 2022:: An international standard for charsets and encodings.
1115 * Coding Systems:: Ways of representing a string of chars using integers.
1116 * CCL:: A special language for writing fast converters.
1117 * Category Tables:: Subdividing charsets into groups.
1121 * Style Tips:: Writing clean and robust programs.
1122 * Compilation Tips:: Making compiled code run fast.
1123 * Documentation Tips:: Writing readable documentation strings.
1124 * Comment Tips:: Conventions for writing comments.
1125 * Library Headers:: Standard headers for library packages.
1127 Building XEmacs and Object Allocation
1129 * Building XEmacs:: How to preload Lisp libraries into XEmacs.
1130 * Pure Storage:: A kludge to make preloaded Lisp functions sharable.
1131 * Garbage Collection:: Reclaiming space for Lisp objects no longer used.
1134 File: lispref.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top
1136 GNU GENERAL PUBLIC LICENSE
1137 **************************
1139 Version 2, June 1991
1141 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
1142 675 Mass Ave, Cambridge, MA 02139, USA
1144 Everyone is permitted to copy and distribute verbatim copies
1145 of this license document, but changing it is not allowed.
1150 The licenses for most software are designed to take away your freedom
1151 to share and change it. By contrast, the GNU General Public License is
1152 intended to guarantee your freedom to share and change free
1153 software--to make sure the software is free for all its users. This
1154 General Public License applies to most of the Free Software
1155 Foundation's software and to any other program whose authors commit to
1156 using it. (Some other Free Software Foundation software is covered by
1157 the GNU Library General Public License instead.) You can apply it to
1160 When we speak of free software, we are referring to freedom, not
1161 price. Our General Public Licenses are designed to make sure that you
1162 have the freedom to distribute copies of free software (and charge for
1163 this service if you wish), that you receive source code or can get it
1164 if you want it, that you can change the software or use pieces of it in
1165 new free programs; and that you know you can do these things.
1167 To protect your rights, we need to make restrictions that forbid
1168 anyone to deny you these rights or to ask you to surrender the rights.
1169 These restrictions translate to certain responsibilities for you if you
1170 distribute copies of the software, or if you modify it.
1172 For example, if you distribute copies of such a program, whether
1173 gratis or for a fee, you must give the recipients all the rights that
1174 you have. You must make sure that they, too, receive or can get the
1175 source code. And you must show them these terms so they know their
1178 We protect your rights with two steps: (1) copyright the software,
1179 and (2) offer you this license which gives you legal permission to copy,
1180 distribute and/or modify the software.
1182 Also, for each author's protection and ours, we want to make certain
1183 that everyone understands that there is no warranty for this free
1184 software. If the software is modified by someone else and passed on, we
1185 want its recipients to know that what they have is not the original, so
1186 that any problems introduced by others will not reflect on the original
1187 authors' reputations.
1189 Finally, any free program is threatened constantly by software
1190 patents. We wish to avoid the danger that redistributors of a free
1191 program will individually obtain patent licenses, in effect making the
1192 program proprietary. To prevent this, we have made it clear that any
1193 patent must be licensed for everyone's free use or not licensed at all.
1195 The precise terms and conditions for copying, distribution and
1196 modification follow.
1198 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1199 0. This License applies to any program or other work which contains a
1200 notice placed by the copyright holder saying it may be distributed
1201 under the terms of this General Public License. The "Program",
1202 below, refers to any such program or work, and a "work based on
1203 the Program" means either the Program or any derivative work under
1204 copyright law: that is to say, a work containing the Program or a
1205 portion of it, either verbatim or with modifications and/or
1206 translated into another language. (Hereinafter, translation is
1207 included without limitation in the term "modification".) Each
1208 licensee is addressed as "you".
1210 Activities other than copying, distribution and modification are
1211 not covered by this License; they are outside its scope. The act
1212 of running the Program is not restricted, and the output from the
1213 Program is covered only if its contents constitute a work based on
1214 the Program (independent of having been made by running the
1215 Program). Whether that is true depends on what the Program does.
1217 1. You may copy and distribute verbatim copies of the Program's
1218 source code as you receive it, in any medium, provided that you
1219 conspicuously and appropriately publish on each copy an appropriate
1220 copyright notice and disclaimer of warranty; keep intact all the
1221 notices that refer to this License and to the absence of any
1222 warranty; and give any other recipients of the Program a copy of
1223 this License along with the Program.
1225 You may charge a fee for the physical act of transferring a copy,
1226 and you may at your option offer warranty protection in exchange
1229 2. You may modify your copy or copies of the Program or any portion
1230 of it, thus forming a work based on the Program, and copy and
1231 distribute such modifications or work under the terms of Section 1
1232 above, provided that you also meet all of these conditions:
1234 a. You must cause the modified files to carry prominent notices
1235 stating that you changed the files and the date of any change.
1237 b. You must cause any work that you distribute or publish, that
1238 in whole or in part contains or is derived from the Program
1239 or any part thereof, to be licensed as a whole at no charge
1240 to all third parties under the terms of this License.
1242 c. If the modified program normally reads commands interactively
1243 when run, you must cause it, when started running for such
1244 interactive use in the most ordinary way, to print or display
1245 an announcement including an appropriate copyright notice and
1246 a notice that there is no warranty (or else, saying that you
1247 provide a warranty) and that users may redistribute the
1248 program under these conditions, and telling the user how to
1249 view a copy of this License. (Exception: if the Program
1250 itself is interactive but does not normally print such an
1251 announcement, your work based on the Program is not required
1252 to print an announcement.)
1254 These requirements apply to the modified work as a whole. If
1255 identifiable sections of that work are not derived from the
1256 Program, and can be reasonably considered independent and separate
1257 works in themselves, then this License, and its terms, do not
1258 apply to those sections when you distribute them as separate
1259 works. But when you distribute the same sections as part of a
1260 whole which is a work based on the Program, the distribution of
1261 the whole must be on the terms of this License, whose permissions
1262 for other licensees extend to the entire whole, and thus to each
1263 and every part regardless of who wrote it.
1265 Thus, it is not the intent of this section to claim rights or
1266 contest your rights to work written entirely by you; rather, the
1267 intent is to exercise the right to control the distribution of
1268 derivative or collective works based on the Program.
1270 In addition, mere aggregation of another work not based on the
1271 Program with the Program (or with a work based on the Program) on
1272 a volume of a storage or distribution medium does not bring the
1273 other work under the scope of this License.
1275 3. You may copy and distribute the Program (or a work based on it,
1276 under Section 2) in object code or executable form under the terms
1277 of Sections 1 and 2 above provided that you also do one of the
1280 a. Accompany it with the complete corresponding machine-readable
1281 source code, which must be distributed under the terms of
1282 Sections 1 and 2 above on a medium customarily used for
1283 software interchange; or,
1285 b. Accompany it with a written offer, valid for at least three
1286 years, to give any third party, for a charge no more than your
1287 cost of physically performing source distribution, a complete
1288 machine-readable copy of the corresponding source code, to be
1289 distributed under the terms of Sections 1 and 2 above on a
1290 medium customarily used for software interchange; or,
1292 c. Accompany it with the information you received as to the offer
1293 to distribute corresponding source code. (This alternative is
1294 allowed only for noncommercial distribution and only if you
1295 received the program in object code or executable form with
1296 such an offer, in accord with Subsection b above.)
1298 The source code for a work means the preferred form of the work for
1299 making modifications to it. For an executable work, complete
1300 source code means all the source code for all modules it contains,
1301 plus any associated interface definition files, plus the scripts
1302 used to control compilation and installation of the executable.
1303 However, as a special exception, the source code distributed need
1304 not include anything that is normally distributed (in either
1305 source or binary form) with the major components (compiler,
1306 kernel, and so on) of the operating system on which the executable
1307 runs, unless that component itself accompanies the executable.
1309 If distribution of executable or object code is made by offering
1310 access to copy from a designated place, then offering equivalent
1311 access to copy the source code from the same place counts as
1312 distribution of the source code, even though third parties are not
1313 compelled to copy the source along with the object code.
1315 4. You may not copy, modify, sublicense, or distribute the Program
1316 except as expressly provided under this License. Any attempt
1317 otherwise to copy, modify, sublicense or distribute the Program is
1318 void, and will automatically terminate your rights under this
1319 License. However, parties who have received copies, or rights,
1320 from you under this License will not have their licenses
1321 terminated so long as such parties remain in full compliance.
1323 5. You are not required to accept this License, since you have not
1324 signed it. However, nothing else grants you permission to modify
1325 or distribute the Program or its derivative works. These actions
1326 are prohibited by law if you do not accept this License.
1327 Therefore, by modifying or distributing the Program (or any work
1328 based on the Program), you indicate your acceptance of this
1329 License to do so, and all its terms and conditions for copying,
1330 distributing or modifying the Program or works based on it.
1332 6. Each time you redistribute the Program (or any work based on the
1333 Program), the recipient automatically receives a license from the
1334 original licensor to copy, distribute or modify the Program
1335 subject to these terms and conditions. You may not impose any
1336 further restrictions on the recipients' exercise of the rights
1337 granted herein. You are not responsible for enforcing compliance
1338 by third parties to this License.
1340 7. If, as a consequence of a court judgment or allegation of patent
1341 infringement or for any other reason (not limited to patent
1342 issues), conditions are imposed on you (whether by court order,
1343 agreement or otherwise) that contradict the conditions of this
1344 License, they do not excuse you from the conditions of this
1345 License. If you cannot distribute so as to satisfy simultaneously
1346 your obligations under this License and any other pertinent
1347 obligations, then as a consequence you may not distribute the
1348 Program at all. For example, if a patent license would not permit
1349 royalty-free redistribution of the Program by all those who
1350 receive copies directly or indirectly through you, then the only
1351 way you could satisfy both it and this License would be to refrain
1352 entirely from distribution of the Program.
1354 If any portion of this section is held invalid or unenforceable
1355 under any particular circumstance, the balance of the section is
1356 intended to apply and the section as a whole is intended to apply
1357 in other circumstances.
1359 It is not the purpose of this section to induce you to infringe any
1360 patents or other property right claims or to contest validity of
1361 any such claims; this section has the sole purpose of protecting
1362 the integrity of the free software distribution system, which is
1363 implemented by public license practices. Many people have made
1364 generous contributions to the wide range of software distributed
1365 through that system in reliance on consistent application of that
1366 system; it is up to the author/donor to decide if he or she is
1367 willing to distribute software through any other system and a
1368 licensee cannot impose that choice.
1370 This section is intended to make thoroughly clear what is believed
1371 to be a consequence of the rest of this License.
1373 8. If the distribution and/or use of the Program is restricted in
1374 certain countries either by patents or by copyrighted interfaces,
1375 the original copyright holder who places the Program under this
1376 License may add an explicit geographical distribution limitation
1377 excluding those countries, so that distribution is permitted only
1378 in or among countries not thus excluded. In such case, this
1379 License incorporates the limitation as if written in the body of
1382 9. The Free Software Foundation may publish revised and/or new
1383 versions of the General Public License from time to time. Such
1384 new versions will be similar in spirit to the present version, but
1385 may differ in detail to address new problems or concerns.
1387 Each version is given a distinguishing version number. If the
1388 Program specifies a version number of this License which applies
1389 to it and "any later version", you have the option of following
1390 the terms and conditions either of that version or of any later
1391 version published by the Free Software Foundation. If the Program
1392 does not specify a version number of this License, you may choose
1393 any version ever published by the Free Software Foundation.
1395 10. If you wish to incorporate parts of the Program into other free
1396 programs whose distribution conditions are different, write to the
1397 author to ask for permission. For software which is copyrighted
1398 by the Free Software Foundation, write to the Free Software
1399 Foundation; we sometimes make exceptions for this. Our decision
1400 will be guided by the two goals of preserving the free status of
1401 all derivatives of our free software and of promoting the sharing
1402 and reuse of software generally.
1405 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
1406 WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
1407 LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
1408 HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
1409 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
1410 NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
1411 FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
1412 QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
1413 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
1414 SERVICING, REPAIR OR CORRECTION.
1416 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
1417 WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
1418 MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
1419 LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
1420 INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
1421 INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
1422 DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
1423 OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
1424 OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
1425 ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
1427 END OF TERMS AND CONDITIONS
1428 How to Apply These Terms to Your New Programs
1429 =============================================
1431 If you develop a new program, and you want it to be of the greatest
1432 possible use to the public, the best way to achieve this is to make it
1433 free software which everyone can redistribute and change under these
1436 To do so, attach the following notices to the program. It is safest
1437 to attach them to the start of each source file to most effectively
1438 convey the exclusion of warranty; and each file should have at least
1439 the "copyright" line and a pointer to where the full notice is found.
1441 ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
1442 Copyright (C) 19YY NAME OF AUTHOR
1444 This program is free software; you can redistribute it and/or
1445 modify it under the terms of the GNU General Public License
1446 as published by the Free Software Foundation; either version 2
1447 of the License, or (at your option) any later version.
1449 This program is distributed in the hope that it will be useful,
1450 but WITHOUT ANY WARRANTY; without even the implied warranty of
1451 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1452 GNU General Public License for more details.
1454 You should have received a copy of the GNU General Public License
1455 along with this program; if not, write to the Free Software
1456 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1458 Also add information on how to contact you by electronic and paper
1461 If the program is interactive, make it output a short notice like
1462 this when it starts in an interactive mode:
1464 Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
1465 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
1466 type `show w'. This is free software, and you are welcome
1467 to redistribute it under certain conditions; type `show c'
1470 The hypothetical commands `show w' and `show c' should show the
1471 appropriate parts of the General Public License. Of course, the
1472 commands you use may be called something other than `show w' and `show
1473 c'; they could even be mouse-clicks or menu items--whatever suits your
1476 You should also get your employer (if you work as a programmer) or
1477 your school, if any, to sign a "copyright disclaimer" for the program,
1478 if necessary. Here is a sample; alter the names:
1480 Yoyodyne, Inc., hereby disclaims all copyright
1481 interest in the program `Gnomovision'
1482 (which makes passes at compilers) written
1485 SIGNATURE OF TY COON, 1 April 1989
1486 Ty Coon, President of Vice
1488 This General Public License does not permit incorporating your
1489 program into proprietary programs. If your program is a subroutine
1490 library, you may consider it more useful to permit linking proprietary
1491 applications with the library. If this is what you want to do, use the
1492 GNU Library General Public License instead of this License.
1495 File: lispref.info, Node: Introduction, Next: Packaging, Prev: Copying, Up: Top
1500 Most of the XEmacs text editor is written in the programming language
1501 called XEmacs Lisp. You can write new code in XEmacs Lisp and install
1502 it as an extension to the editor. However, XEmacs Lisp is more than a
1503 mere "extension language"; it is a full computer programming language
1504 in its own right. You can use it as you would any other programming
1507 Because XEmacs Lisp is designed for use in an editor, it has special
1508 features for scanning and parsing text as well as features for handling
1509 files, buffers, displays, subprocesses, and so on. XEmacs Lisp is
1510 closely integrated with the editing facilities; thus, editing commands
1511 are functions that can also conveniently be called from Lisp programs,
1512 and parameters for customization are ordinary Lisp variables.
1514 This manual describes XEmacs Lisp, presuming considerable familiarity
1515 with the use of XEmacs for editing. (See `The XEmacs Reference
1516 Manual', for this basic information.) Generally speaking, the earlier
1517 chapters describe features of XEmacs Lisp that have counterparts in many
1518 programming languages, and later chapters describe features that are
1519 peculiar to XEmacs Lisp or relate specifically to editing.
1521 This is edition 3.3.
1525 * Caveats:: Flaws and a request for help.
1526 * Lisp History:: XEmacs Lisp is descended from Maclisp.
1527 * Conventions:: How the manual is formatted.
1528 * Acknowledgements:: The authors, editors, and sponsors of this manual.
1531 File: lispref.info, Node: Caveats, Next: Lisp History, Up: Introduction
1536 This manual has gone through numerous drafts. It is nearly complete
1537 but not flawless. There are a few topics that are not covered, either
1538 because we consider them secondary (such as most of the individual
1539 modes) or because they are yet to be written. Because we are not able
1540 to deal with them completely, we have left out several parts
1543 The manual should be fully correct in what it does cover, and it is
1544 therefore open to criticism on anything it says--from specific examples
1545 and descriptive text, to the ordering of chapters and sections. If
1546 something is confusing, or you find that you have to look at the sources
1547 or experiment to learn something not covered in the manual, then perhaps
1548 the manual should be fixed. Please let us know.
1550 As you use this manual, we ask that you send corrections as soon as
1551 you find them. If you think of a simple, real life example for a
1552 function or group of functions, please make an effort to write it up
1553 and send it in. Please reference any comments to the node name and
1554 function or variable name, as appropriate. Also state the number of
1555 the edition which you are criticizing.
1557 This manual was originally written for FSF Emacs 19 and was updated
1558 by Ben Wing (ben@xemacs.org) for Lucid Emacs 19.10 and later for XEmacs
1559 19.12, 19.13, 19.14, and 20.0. It was further updated by the XEmacs
1560 Development Team for 19.15 and 20.1. Please send comments and
1561 corrections relating to XEmacs-specific portions of this manual to
1564 or post to the newsgroup
1571 File: lispref.info, Node: Lisp History, Next: Conventions, Prev: Caveats, Up: Introduction
1576 Lisp (LISt Processing language) was first developed in the late 1950's
1577 at the Massachusetts Institute of Technology for research in artificial
1578 intelligence. The great power of the Lisp language makes it superior
1579 for other purposes as well, such as writing editing commands.
1581 Dozens of Lisp implementations have been built over the years, each
1582 with its own idiosyncrasies. Many of them were inspired by Maclisp,
1583 which was written in the 1960's at MIT's Project MAC. Eventually the
1584 implementors of the descendants of Maclisp came together and developed a
1585 standard for Lisp systems, called Common Lisp.
1587 XEmacs Lisp is largely inspired by Maclisp, and a little by Common
1588 Lisp. If you know Common Lisp, you will notice many similarities.
1589 However, many of the features of Common Lisp have been omitted or
1590 simplified in order to reduce the memory requirements of XEmacs.
1591 Sometimes the simplifications are so drastic that a Common Lisp user
1592 might be very confused. We will occasionally point out how XEmacs Lisp
1593 differs from Common Lisp. If you don't know Common Lisp, don't worry
1594 about it; this manual is self-contained.
1597 File: lispref.info, Node: Conventions, Next: Acknowledgements, Prev: Lisp History, Up: Introduction
1602 This section explains the notational conventions that are used in this
1603 manual. You may want to skip this section and refer back to it later.
1607 * Some Terms:: Explanation of terms we use in this manual.
1608 * nil and t:: How the symbols `nil' and `t' are used.
1609 * Evaluation Notation:: The format we use for examples of evaluation.
1610 * Printing Notation:: The format we use for examples that print output.
1611 * Error Messages:: The format we use for examples of errors.
1612 * Buffer Text Notation:: The format we use for buffer contents in examples.
1613 * Format of Descriptions:: Notation for describing functions, variables, etc.
1616 File: lispref.info, Node: Some Terms, Next: nil and t, Up: Conventions
1621 Throughout this manual, the phrases "the Lisp reader" and "the Lisp
1622 printer" are used to refer to those routines in Lisp that convert
1623 textual representations of Lisp objects into actual Lisp objects, and
1624 vice versa. *Note Printed Representation::, for more details. You, the
1625 person reading this manual, are thought of as "the programmer" and are
1626 addressed as "you". "The user" is the person who uses Lisp programs,
1627 including those you write.
1629 Examples of Lisp code appear in this font or form: `(list 1 2 3)'.
1630 Names that represent arguments or metasyntactic variables appear in
1631 this font or form: FIRST-NUMBER.
1634 File: lispref.info, Node: nil and t, Next: Evaluation Notation, Prev: Some Terms, Up: Conventions
1639 In Lisp, the symbol `nil' has three separate meanings: it is a symbol
1640 with the name `nil'; it is the logical truth value FALSE; and it is the
1641 empty list--the list of zero elements. When used as a variable, `nil'
1642 always has the value `nil'.
1644 As far as the Lisp reader is concerned, `()' and `nil' are
1645 identical: they stand for the same object, the symbol `nil'. The
1646 different ways of writing the symbol are intended entirely for human
1647 readers. After the Lisp reader has read either `()' or `nil', there is
1648 no way to determine which representation was actually written by the
1651 In this manual, we use `()' when we wish to emphasize that it means
1652 the empty list, and we use `nil' when we wish to emphasize that it
1653 means the truth value FALSE. That is a good convention to use in Lisp
1656 (cons 'foo ()) ; Emphasize the empty list
1657 (not nil) ; Emphasize the truth value FALSE
1659 In contexts where a truth value is expected, any non-`nil' value is
1660 considered to be TRUE. However, `t' is the preferred way to represent
1661 the truth value TRUE. When you need to choose a value which represents
1662 TRUE, and there is no other basis for choosing, use `t'. The symbol
1663 `t' always has value `t'.
1665 In XEmacs Lisp, `nil' and `t' are special symbols that always
1666 evaluate to themselves. This is so that you do not need to quote them
1667 to use them as constants in a program. An attempt to change their
1668 values results in a `setting-constant' error. *Note Accessing
1672 File: lispref.info, Node: Evaluation Notation, Next: Printing Notation, Prev: nil and t, Up: Conventions
1674 1.3.3 Evaluation Notation
1675 -------------------------
1677 A Lisp expression that you can evaluate is called a "form". Evaluating
1678 a form always produces a result, which is a Lisp object. In the
1679 examples in this manual, this is indicated with `=>':
1684 You can read this as "`(car '(1 2))' evaluates to 1".
1686 When a form is a macro call, it expands into a new form for Lisp to
1687 evaluate. We show the result of the expansion with `==>'. We may or
1688 may not show the actual result of the evaluation of the expanded form.
1690 (news-cadr '(a b c))
1691 ==> (car (cdr '(a b c)))
1694 Sometimes to help describe one form we show another form that
1695 produces identical results. The exact equivalence of two forms is
1696 indicated with `=='.
1698 (cons 'a nil) == (list 'a)
1701 File: lispref.info, Node: Printing Notation, Next: Error Messages, Prev: Evaluation Notation, Up: Conventions
1703 1.3.4 Printing Notation
1704 -----------------------
1706 Many of the examples in this manual print text when they are evaluated.
1707 If you execute example code in a Lisp Interaction buffer (such as the
1708 buffer `*scratch*'), the printed text is inserted into the buffer. If
1709 you execute the example by other means (such as by evaluating the
1710 function `eval-region'), the printed text is displayed in the echo
1711 area. You should be aware that text displayed in the echo area is
1712 truncated to a single line.
1714 Examples in this manual indicate printed text with `-|',
1715 irrespective of where that text goes. The value returned by evaluating
1716 the form (here `bar') follows on a separate line.
1718 (progn (print 'foo) (print 'bar))
1724 File: lispref.info, Node: Error Messages, Next: Buffer Text Notation, Prev: Printing Notation, Up: Conventions
1726 1.3.5 Error Messages
1727 --------------------
1729 Some examples signal errors. This normally displays an error message
1730 in the echo area. We show the error message on a line starting with
1731 `error-->'. Note that `error-->' itself does not appear in the echo
1735 error--> Wrong type argument: integer-or-marker-p, x
1738 File: lispref.info, Node: Buffer Text Notation, Next: Format of Descriptions, Prev: Error Messages, Up: Conventions
1740 1.3.6 Buffer Text Notation
1741 --------------------------
1743 Some examples show modifications to text in a buffer, with "before" and
1744 "after" versions of the text. These examples show the contents of the
1745 buffer in question between two lines of dashes containing the buffer
1746 name. In addition, `-!-' indicates the location of point. (The symbol
1747 for point, of course, is not part of the text in the buffer; it
1748 indicates the place _between_ two characters where point is located.)
1750 ---------- Buffer: foo ----------
1751 This is the -!-contents of foo.
1752 ---------- Buffer: foo ----------
1756 ---------- Buffer: foo ----------
1757 This is the changed -!-contents of foo.
1758 ---------- Buffer: foo ----------
1761 File: lispref.info, Node: Format of Descriptions, Prev: Buffer Text Notation, Up: Conventions
1763 1.3.7 Format of Descriptions
1764 ----------------------------
1766 Functions, variables, macros, commands, user options, and special forms
1767 are described in this manual in a uniform format. The first line of a
1768 description contains the name of the item followed by its arguments, if
1769 any. The category--function, variable, or whatever--appears at the
1770 beginning of the line. The description follows on succeeding lines,
1771 sometimes with examples.
1775 * A Sample Function Description:: A description of an imaginary
1777 * A Sample Variable Description:: A description of an imaginary
1779 `electric-future-map'.
1782 File: lispref.info, Node: A Sample Function Description, Next: A Sample Variable Description, Up: Format of Descriptions
1784 1.3.7.1 A Sample Function Description
1785 .....................................
1787 In a function description, the name of the function being described
1788 appears first. It is followed on the same line by a list of parameters.
1789 The names used for the parameters are also used in the body of the
1792 The appearance of the keyword `&optional' in the parameter list
1793 indicates that the arguments for subsequent parameters may be omitted
1794 (omitted parameters default to `nil'). Do not write `&optional' when
1795 you call the function.
1797 The keyword `&rest' (which will always be followed by a single
1798 parameter) indicates that any number of arguments can follow. The value
1799 of the single following parameter will be a list of all these arguments.
1800 Do not write `&rest' when you call the function.
1802 Here is a description of an imaginary function `foo':
1804 -- Function: foo integer1 &optional integer2 &rest integers
1805 The function `foo' subtracts INTEGER1 from INTEGER2, then adds all
1806 the rest of the arguments to the result. If INTEGER2 is not
1807 supplied, then the number 19 is used by default.
1820 Any parameter whose name contains the name of a type (e.g., INTEGER,
1821 INTEGER1 or BUFFER) is expected to be of that type. A plural of a type
1822 (such as BUFFERS) often means a list of objects of that type.
1823 Parameters named OBJECT may be of any type. (*Note Lisp Data Types::,
1824 for a list of XEmacs object types.) Parameters with other sorts of
1825 names (e.g., NEW-FILE) are discussed specifically in the description of
1826 the function. In some sections, features common to parameters of
1827 several functions are described at the beginning.
1829 *Note Lambda Expressions::, for a more complete description of
1830 optional and rest arguments.
1832 Command, macro, and special form descriptions have the same format,
1833 but the word `Function' is replaced by `Command', `Macro', or `Special
1834 Form', respectively. Commands are simply functions that may be called
1835 interactively; macros process their arguments differently from functions
1836 (the arguments are not evaluated), but are presented the same way.
1838 Special form descriptions use a more complex notation to specify
1839 optional and repeated parameters because they can break the argument
1840 list down into separate arguments in more complicated ways.
1841 ``[OPTIONAL-ARG]'' means that OPTIONAL-ARG is optional and
1842 `REPEATED-ARGS...' stands for zero or more arguments. Parentheses are
1843 used when several arguments are grouped into additional levels of list
1844 structure. Here is an example:
1846 -- Special Form: count-loop (VAR [FROM TO [INC]]) BODY...
1847 This imaginary special form implements a loop that executes the
1848 BODY forms and then increments the variable VAR on each iteration.
1849 On the first iteration, the variable has the value FROM; on
1850 subsequent iterations, it is incremented by 1 (or by INC if that
1851 is given). The loop exits before executing BODY if VAR equals TO.
1854 (count-loop (i 0 10)
1855 (prin1 i) (princ " ")
1856 (prin1 (aref vector i)) (terpri))
1858 If FROM and TO are omitted, then VAR is bound to `nil' before the
1859 loop begins, and the loop exits if VAR is non-`nil' at the
1860 beginning of an iteration. Here is an example:
1867 In this special form, the arguments FROM and TO are optional, but
1868 must both be present or both absent. If they are present, INC may
1869 optionally be specified as well. These arguments are grouped with
1870 the argument VAR into a list, to distinguish them from BODY, which
1871 includes all remaining elements of the form.
1874 File: lispref.info, Node: A Sample Variable Description, Prev: A Sample Function Description, Up: Format of Descriptions
1876 1.3.7.2 A Sample Variable Description
1877 .....................................
1879 A "variable" is a name that can hold a value. Although any variable
1880 can be set by the user, certain variables that exist specifically so
1881 that users can change them are called "user options". Ordinary
1882 variables and user options are described using a format like that for
1883 functions except that there are no arguments.
1885 Here is a description of the imaginary `electric-future-map'
1888 -- Variable: electric-future-map
1889 The value of this variable is a full keymap used by Electric
1890 Command Future mode. The functions in this map allow you to edit
1891 commands you have not yet thought about executing.
1893 User option descriptions have the same format, but `Variable' is
1894 replaced by `User Option'.
1897 File: lispref.info, Node: Acknowledgements, Prev: Conventions, Up: Introduction
1899 1.4 Acknowledgements
1900 ====================
1902 This manual was based on the GNU Emacs Lisp Reference Manual, version
1903 2.4, written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M.
1904 Stallman and Chris Welty, the volunteers of the GNU manual group, in an
1905 effort extending over several years. Robert J. Chassell helped to
1906 review and edit the manual, with the support of the Defense Advanced
1907 Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt,
1908 Jr. of Computational Logic, Inc.
1910 Ben Wing adapted this manual for XEmacs 19.14 and 20.0, and earlier
1911 for Lucid Emacs 19.10, XEmacs 19.12, and XEmacs 19.13. He is the sole
1912 author of many of the manual sections, in particular the XEmacs-specific
1913 sections: events, faces, extents, glyphs, specifiers, toolbar, menubars,
1914 scrollbars, dialog boxes, devices, consoles, hash tables, range tables,
1915 char tables, databases, and others. The section on annotations was
1916 originally written by Chuck Thompson. Corrections to v3.1 and later
1917 were done by Martin Buchholz, Steve Baur, and Hrvoje Niksic.
1919 Corrections to the original GNU Emacs Lisp Reference Manual were
1920 supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David
1921 Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch,
1922 David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf
1923 Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow,
1924 George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman,
1925 Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard
1926 Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner
1927 Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim,
1928 Arnold D. Robbins, Raul Rockwell, Per Starback, Shinichirou Sugou, Kimmo
1929 Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew
1930 Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
1933 File: lispref.info, Node: Packaging, Next: Lisp Data Types, Prev: Introduction, Up: Top
1935 2 The XEmacs Packaging System
1936 *****************************
1938 The XEmacs distribution, starting with version 21, comes only with a
1939 very basic set of built-in modes and libraries. Most of the libraries
1940 that were part of the distribution of earlier versions of XEmacs are now
1941 available separately. The user as well as the system administrator can
1942 choose which packages to install; the actual installation process is
1943 easy. This gives an installer the ability to tailor an XEmacs
1944 installation for local needs with safe removal of unnecessary code.
1946 This chapter describes how to package Lisp libraries for use with the
1947 XEmacs Packaging System.
1949 _Please note carefully_ that the term "package" as used in XEmacs
1950 refers to an aggregation of Lisp code and/or data distributed as a
1951 unit. It does not, as it does in many Lisps, refer to a way of
1952 creating separate name spaces. XEmacs has no facility for providing
1953 separate name spaces. (If we ever do get separate name spaces, we'll
1954 probably regret overloading the nomenclature in this way, but it's
1955 become established.)
1960 * Package Overview:: Lisp Libraries and Packages.
1962 Packaging Lisp Libraries:
1963 * Package Terminology:: Basic stuff.
1964 * Building Packages:: Turn packaged source into a tarball.
1965 * Makefile Targets:: Package `Makefile' targets
1966 * Local.rules File:: Tell the XEmacs Packaging System about your host.
1967 * Creating Packages:: Tell the XEmacs Packaging System about your package.
1968 * Documenting Packages:: Explain your package to users and hackers.
1970 Internals and Package Release Engineering:
1974 File: lispref.info, Node: Package Overview, Next: Package Terminology, Up: Packaging
1976 3 An overview of the XEmacs Packaging System
1977 ********************************************
1979 The XEmacs Packaging System is a system for administering the
1980 installation, upgrade, and removal of Lisp libraries. For the end
1981 user, it provides facilities for determining availability of packages
1982 and which versions at remote sites. It will download and automatically
1983 install a package, ensuring that any old files from previous versions
1984 of the package are removed first. By providing a standard set of
1985 hierarchies for installation, it makes configuration of XEmacs simpler.
1986 Furthermore, packages normally provide ancillary auto-autoloads and
1987 custom-loads libraries, which are automatically detected and loaded by
1988 XEmacs upon startup. This means that once installed, all facilities of
1989 package, including autoloading the library upon invocation of a command
1990 provided by the library and convenient configuration and customization,
1991 are automatically available to the user. There is no need to add
1992 autoloads or keybindings to in the init file, and structured
1993 configuration of the package is available through the Customize system
1994 even before the libraries are loaded.
1996 All of this convenience comes at a cost. The cost of administration
1997 at the package level is negligible compared to the benefits, of course.
1998 However, the requirement that XEmacs find and load auto-autoloads and
1999 custom-loads libraries comes at a fairly large cost in startup time. In
2000 order to reduce this cost, XEmacs imposes fairly strict conditions on
2001 the structure of an installed package.
2003 Meeting these requirements, as well as simply providing the
2004 auto-autoloads and the information about availability and so on does
2005 impose some costs on the library maintainer. The XEmacs Packaging
2006 System also provides structure and utilities to the library maintainer
2007 to make these tasks easier. This manual documents the requirements and
2008 the tools that the XEmacs Packaging System provides to ensure that a
2009 package satisfies them.
2014 * The Library Maintainer View::
2015 * The Package Release Engineer View::
2018 File: lispref.info, Node: The User View, Next: The Library Maintainer View, Up: Package Overview
2023 *N.B.* Much of the discussion in this section undoubtedly belongs
2024 elsewhere, *Note Packages: (xemacs)Packages.
2026 From the user's point of view, an XEmacs binary package is simply a
2027 standard tarball (usually gzipped) containing Lisp sources, compiled
2028 Lisp, documentation, and possibly data files or supporting executables.
2029 The tarball is unpacked using standard tools such as GNU tar and gzip.
2030 The package system does impose certain requirements for automatic
2031 configuration to work.
2033 Here the main consideration is that the tarball "expects" to be
2034 unpacked from the top of a package hierarchy. A "package hierarchy" is
2035 basically an image of a classic Emacs "run-in-place" tree, with `lisp',
2036 `etc', `info', `man', `lib-src', and `pkginfo' subdirectories of the
2037 top. The `pkginfo' subdirectory is for use by the XEmacs Packaging
2038 System administration tools, and currently contains a
2039 `MANIFEST.PACKAGE-NAME' file for each package to ensure that no cruft
2040 remains when a package is removed or updated. The `lisp', `etc', and
2041 `lib-src' subdirectories are further subdivided, with a subdirectory
2042 for each package. The `info' directory obeys the usual conventions.
2043 _I.e._, the `info' directory is flat with a(n) (optional) `dir' file
2044 and one (set of) info file(s) per package. The `man' subdirectory
2045 typically contains documentation sources, separated by package. (It
2046 does not contain `man(1)' pages, as Emacs provides very few of them.)
2048 There are several standard package hierarchies, and administrators
2049 can configure others at build time, while users can configure others at
2050 run time. The standard system hierarchies are all subdirectories of an
2051 XEmacs installation root, typically `/usr/local/lib/xemacs/'. These
2052 are the `xemacs-packages', `mule-packages', `infodock-packages', and
2053 `site-packages' hierarchies. Each has the structure described above,
2054 but the purposes differ. The `xemacs-packages' is the normal place for
2055 installing "official" packages and many third-party libraries.
2056 Unfortunately, it is not yet quite possible to read libraries
2057 containing international characters with a non-Mule XEmacs, so such
2058 libraries are sequestered in the `mule-packages' hierarchy. Some
2059 packages are compatible only with the Infodock development environment,
2060 and they will be installed in the `infodock-packages' hierarchy. The
2061 `site-packages' hierarchy is for packages not distributed by
2062 XEmacs.org, typically locally developed.
2064 Packages are in principle supposed to be XEmacs version-independent,
2065 but if such dependencies are unavoidable, additional standard package
2066 hierarchies may be installed under version directories, _e.g._
2067 `/usr/local/lib/xemacs-21.4.6/'.
2069 Users who do not have sufficient privilege to install packages in the
2070 system hierarchies may install package hierarchies under `~/.xemacs'.
2071 At present only the `xemacs-packages', `mule-packages', and
2072 `site-packages' hierarchies are supported, but it might make sense to
2073 extend this to support `infodock-packages' hierarchies in the future.
2075 The package hierarchies are not searched directly for libraries to be
2076 loaded; this would be very costly. Instead, the hierarchies are ordered
2077 according to certain rules, and searched for package lisp directories at
2078 invocation. These directories are added to the general `load-path'.
2079 As usual, it is `load-path' that is searched at run-time. This
2080 approach is somewhat costly at initialization, but results in a very
2081 "clean" `load-path'.
2083 The order of search can be changed at build time by specifying the
2084 `--package-path' option to `configure', or at run-time by specifying
2085 the `EMACSPACKAGEPATH' environment variable. *Note Packages:
2088 The default order of search is hierarchically determined. First, the
2089 roots are ordered. The "early" roots are the user-specific roots,
2090 typically `~/.xemacs'. The "late" roots are the system roots,
2091 typically `/usr/local/lib/xemacs-21.4.6' and `/usr/local/lib/xemacs',
2092 in that order. All hierarchies for a given root are searched for
2093 package Lisp directories, which are appended to `load-path' in the
2094 order found. Then the search proceeds to the next root, whose results
2095 will be appended to the `load-path' generated by previous roots.
2097 Second, the hierarchies below each root are searched in the order
2098 `site-packages', `infodock-packages', `mule-packages', then
2101 In each hierarchy there should be a `lisp' subdirectory, containing
2102 directories named for the packages. Each package's Lisp libraries thus
2103 are contained in a directory of the form ROOT/HIERARCHY/lisp/PACKAGE/.
2105 With such a complex search algorithm, the possibility of libraries
2106 being shadowed by another library with the same name is quite real.
2107 There are two considerations here. First, every XEmacs package
2108 contains certain libraries with constant names. These are
2111 Lisp code to inform the package administration system about the
2115 Lisp code to set up autoloaded functions and variables that may be
2119 definitions of configuration variables for use with the Customize
2122 They are special-cased, because the way they are used prevents
2123 shadowing from being an issue.
2125 Second, it is possible that multiple copies of some library, or
2126 different libraries with the same name, are installed in various places
2127 in the hierarchies. To detect such shadows, use
2128 `list-load-path-shadows'.
2130 Finally, note that most basic Emacs functionality, including most of
2131 the Lisp API, is implemented in Lisp libraries. Because they use
2132 internal reserved APIs that are subject to change according the needs
2133 of the developers, these libraries are distributed with the XEmacs
2134 binary, and are called "core Lisp libraries". Most core Lisp libraries
2135 are "preloaded" into the Emacs binary and in normal usage are never
2136 explicitly loaded. However, they can be explicitly loaded, and if so
2137 they are searched on `load-path'. Furthermore, functions such as
2138 `locate-library' will also search on the `load-path'. The searching
2139 takes place under somewhat different rules from those used for packaged
2140 Lisp. It is probably easiest to think of the package hierarchy
2141 searching algorithm as receiving a `load-path' initialized to the core
2145 File: lispref.info, Node: The Library Maintainer View, Next: The Package Release Engineer View, Prev: The User View, Up: Package Overview
2147 3.2 The Library Maintainer View
2148 ===============================
2150 From the library maintainer's viewpoint, the advantages to the XEmacs
2151 Packaging System stem from the convenience to the user of installation
2152 and upgrade. Since an installed package automatically registers its
2153 entry points via autoload and its configuration variables with the
2154 Customize system, configuration FAQs are reduced. When it's easy to
2155 upgrade, users learn to try `Tools | Packages | Update Installed
2156 Packages' before posting a FAQ whose answer is "long since fixed,
2159 This comes at some cost, as the library maintainer needs to arrange
2160 that the package be installed in a directory structure that satisfies
2161 the requirements of the XEmacs Packaging System. Autoload cookies and
2162 defcustoms must also be added to existing libraries. The XEmacs
2163 Packaging System provides infrastructure to assure that all of these
2164 annoyances need only be dealt with once. The autoload cookies and
2165 defcustoms are beyond the scope of this chapter, but most maintainers
2166 of modern packages are already familiar with these mechanisms.
2168 The XEmacs Packaging System may be divided into the "infrastructure"
2169 common to all packages, and the package-specific "control files". The
2170 infrastructure supports global builds, installation, and generation of
2171 the "sumo" bundles of packages, as well as generation of individual
2172 packages. The package control files describe the structure of the
2173 package's source tree and provide administrative information.
2177 * Infrastructure:: Global Makefiles and common rules.
2178 * Control Files:: Package-specific Makefiles and administrative files.
2179 * Obtaining:: Obtaining the XEmacs Packaging System and required utilities.
2182 File: lispref.info, Node: Infrastructure, Next: Control Files, Up: The Library Maintainer View
2184 3.2.1 Infrastructure
2185 --------------------
2187 In order to get the greatest benefit from the XEmacs Packaging System,
2188 a library maintainer should place the package sources in an appropriate
2189 place in the XEmacs source package hierarchy, and arrange to have the
2190 source package imported into the XEmacs CVS repository. (We realize
2191 that the latter requirement can be quite burdensome. We are working on
2192 ways to remove this requirement, but for the present it remains
2193 necessary.) The library maintainer must also keep sources for any
2194 packages his/her package requires. This requirement is somewhat
2195 burdensome, but unlikely to be relaxed because of the implementation of
2196 compilation of macros in Emacs Lisp. Macros cannot be called by
2197 compiled Lisp (the macro expansion, which is always known at compile
2198 time, is inlined), so the source of the macro must be loaded before
2199 compiling the called function.
2201 The source package hierarchy may be rooted anywhere. The CVS module
2202 is called "packages," so we will refer to the top directory of the
2203 source package hierarchy as "the `packages' directory." The `packages'
2204 directory contains two source subdirectories, `xemacs-packages' and
2205 `mule-packages' (for convenience in segregating the packages which
2206 depend on Mule, as they will cause load-time errors in a non-Mule
2207 XEmacs). Each subdirectory contains many package source directories,
2208 whose internal structure is not specified. That structure is left up
2209 to the convenience of the library maintainers. The requirements on the
2210 top directory of an individual package source tree are given below,
2211 *Note Control Files::.
2213 The `packages' directory contains some auxiliary Lisp libraries used
2214 in the compilation and packaging process. The content of these
2215 libraries is of interest primarily to the packaging engineers, *Note
2216 The Package Release Engineer View::.
2218 Finally, the `packages', `packages/xemacs-packages', and
2219 `packages/mule-packages' directories contain `Makefile's and include
2220 files to control the package creation process. The `Makefile's in
2221 `packages/xemacs-packages' and `packages/mule-packages' simply define
2222 the default sets of known packages and include `../iterate.rules',
2223 which implements recursive building of all target packages.
2225 The `make' infrastructure in `packages' includes
2228 controls building of individual packages, local installation, and
2229 bundling of "sumo" tarballs
2232 controls recursive builds of multiple packages
2234 `meta-iterate.rules'
2235 This is used by higher-level subdirectories that do not directly
2236 contain packages. Subdirectories directly containing packages
2237 should use iterate.rules instead.
2240 provides the rules for building and packaging. Included by all
2241 package `Makefile's.
2244 provides local configuration, such as installation targets and
2245 staging directories, as well as a number of kludges (many now
2246 obsolete) required for building packages on the Windows platform.
2248 `Local.rules.template'
2249 a template for Local.rules, liberally commented
2252 consistency checking for `Local.rules', included by both the
2253 top-level `Makefile' and by `XEmacs.rules'.
2256 a file to `include' in package `Makefile's to be able to get at
2257 variables in `Local.rules' _before_ including `XEmacs.rules'.
2259 `package-compile.el'
2260 compile environment (_e.g._, load-path) setup.
2262 Of these, only `Local.rules' and `package-compile.el' need to be
2263 modified by the library maintainer. The changes to Local.rules affect
2264 only your environment. This should need to be done only once when
2265 first preparing the source environment. The necessary modifications to
2266 `package-compile.el' need to be done for each package and are discussed
2267 in the next section, *Note Control Files::.
2270 File: lispref.info, Node: Control Files, Next: Obtaining, Prev: Infrastructure, Up: The Library Maintainer View
2275 Each package source must contain a number of control files in the
2276 top-level directory. These files in general can be created and then
2277 ignored, except for a few variables that need to be updated when new
2278 versions are released. In most cases even adding, renaming, and
2279 removing library source files can be handled by generic rules.
2281 The package control files include
2284 Must set a few `make' variables used by the administrative
2285 utilities, and defines a couple of package-building targets to
2286 depend on appropriate targets defined generically in
2287 `XEmacs.rules'. It may also provide various variables and rules
2288 to transform the source tree structure into that expected by the
2292 Provides a template for package information to be provided to the
2293 administrative utilities. Static variables that are rarely changed
2294 (such as the package's name) are entered as literals. Some
2295 variables are generated by the build process (build dates and MD5
2296 checksums) and are automatically filled in. Finally, some
2297 variables that change irregularly (dependences and even version
2298 numbers) are set as `make' variables in the `Makefile'.
2301 Not strictly required, but normally a ChangeLog will be added by
2302 the XEmacs package maintainer if different from the upstream
2306 Generated. Simply does a `package-provide' for the package.
2309 Generated. Read when XEmacs is initialized, and provides
2310 autoloads for defuns and other forms in the sources that are
2311 marked with an "autoload cookie" (`;;;###autoload'.
2314 Generated. Read when XEmacs is initialized, and informs the
2315 Customize subsystem how to find the defcustom forms needed to
2316 create Customization forms for the usre configuration variables of
2320 File: lispref.info, Node: Obtaining, Prev: Control Files, Up: The Library Maintainer View
2322 3.2.3 Obtaining the XEmacs Packaging System and Required Utilities
2323 ------------------------------------------------------------------
2325 Currently both the infrastructure for creating XEmacs packages and the
2326 package sources themselves are available only by CVS. See
2327 `http://www.xemacs.org/Develop/cvsaccess.html' for more intformation.
2329 The XEmacs Packaging System currently requires GNU `make', and
2330 XEmacs, to build packages.
2333 File: lispref.info, Node: The Package Release Engineer View, Prev: The Library Maintainer View, Up: Package Overview
2335 3.2.4 The Package Release Engineer View
2336 ---------------------------------------
2338 The XEmacs Package Release Engineer is responsible for keeping the
2339 system coherent. The changes to `packages/package-compile.el' and
2340 `packages/xemacs-packages/Makefile' required to make the package
2341 available to others, and for building SUMO tarballs, _etc_, are done by
2342 the Package Release Engineer, not individual library maintainers.
2344 The Package Release Engineer also maintains assorted infrastructure
2345 for actually making releases. These are generally available for
2346 inspection in the `xemacs-builds' module in the CVS repository.
2349 File: lispref.info, Node: Package Terminology, Next: Building Packages, Prev: Package Overview, Up: Packaging
2351 Package Terminology:
2352 ====================
2354 3.2.5 Libraries and Packages
2355 ----------------------------
2357 A Lisp "library" is a single loadable file containing Lisp code. It
2358 may be in source or byte-compiled form. A Lisp "package" is a set of
2359 one or more libraries, usually related to each other in some way,
2360 bundled with administrative information for convenient distribution.
2362 3.2.6 Package Flavors
2363 ---------------------
2365 There are two main flavors of packages.
2368 A regular package is a set of Lisp libraries design to cooperate
2369 with one another. A very complex example is Gnus. One may not in
2370 general safely remove any of the component libraries.
2372 *Single-File Packages*
2373 A single-file package is a collection of thematically related but
2374 otherwise independent Lisp libraries. These libraries are bundled
2375 together for convenience of the maintainers. Usually individual
2376 libraries may be deleted at will without any loss of functionality
2377 of other libraries in the package. However, we would recommend
2378 that you follow this rule of thumb: "When in doubt, don't delete".
2379 If it's really that big a deal, request that the maintainers
2380 split the package into smaller aggregations.
2382 3.2.7 Package Distributions
2383 ---------------------------
2385 XEmacs Lisp packages are distributed in two ways. "Binary packages"
2386 are used by system administrators and end users. They are packaged in a
2387 form convenient for direct installation into an XEmacs package
2388 hierarchy. "Source packages" are for developers and include all files
2389 necessary for rebuilding byte-compiled lisp and creating tarballs for
2390 distribution or installation. This is all of the package author's
2391 source code plus all of the files necessary to build distribution
2392 tarballs (Unix Tar format files, gzipped for space savings).
2393 (Occasionally sources that are not relevant to XEmacs are usually
2394 renamed to `file.upstream'.)
2396 Currently, source packages are only available via CVS. See
2397 `http://www.xemacs.org/Develop/cvsaccess.html' for details.
2399 The package distributions are also split according to major features
2400 required in XEmacs to support them. At present there are "generic"
2401 packages, which can be loaded by _any_ XEmacs, and "Mule" packages,
2402 which _require_ Mule support or they will cause errors when loaded.
2403 Note that there is no guarantee that a generic package will have any
2404 useful functionality in a minimally configured XEmacs. As long as any
2405 XEmacs can successfully load the package's libraries (perhaps given
2406 other required Lisp libraries), it will be classified as generic. At
2407 the present time only Mule packages need be treated specially, and even
2408 those only if they contain multibyte characters.
2411 File: lispref.info, Node: Building Packages, Next: Makefile Targets, Prev: Package Terminology, Up: Packaging
2416 Currently, source packages are only available via anonymous CVS. See
2417 `http://www.xemacs.org/Develop/cvsaccess.html' for details of checking
2418 out the `packages' module.
2420 3.2.8 Prerequisites for Building Source Packages
2421 ------------------------------------------------
2426 (or a BSD compatible install program).
2429 (3.79 or later preferred).
2432 (4.2 from texinfo-4.2)
2440 `A properly configured `Local.rules' file.'
2441 *Note Local.rules File::.
2443 And of course, XEmacs, 21.0 or higher.
2445 3.3 What You Can Do With Source Packages
2446 ========================================
2448 The packages CVS sources are most useful for creating XEmacs package
2449 tarballs for installation into your own XEmacs installations or for
2450 distributing to others.
2452 It should be noted that most of the package `Makefile's do _not_
2453 need to contain _any_ target rules. Everything is handled from the
2454 `XEmacs.rules' file, located in the toplevel directory of the packages
2458 File: lispref.info, Node: Makefile Targets, Next: Local.rules File, Prev: Building Packages, Up: Packaging
2460 4 `Makefile' targets
2461 ********************
2463 The following targets can be used when running `make' to build the
2467 Removes any documentation files that have been processed by TeX.
2470 Does a `mostlyclean', plus removes generated postscript and dvi
2471 files. Also removes any generated .elc files, along with the
2472 normal .elc files in the package and HTML and .info files.
2475 Use this when preparing a distribution. It kills anything that
2479 Does a `distclean' and also removes any backup files (`*~') and
2483 Creates the `package-info' file from the `package-info.in' and
2484 writes an entry in the `package-index' file.
2487 Builds the package, including any Texinfo documentation (info
2488 format), writes an entry into the `package-index' file and builds
2489 a tarball of the package. Also writes an entry into
2490 `setup-packages.ini' which is later used in the creation of
2491 netinstaller's `setup.ini'.
2494 Builds and installs a package
2497 Doesn't build anything, just installs it.
2500 Generate the package's `auto-autoloads.el' file.
2503 Creates the directories needed for installation and copies the
2504 files there. Basically this is an alias for `install-only'.
2507 Builds the HTML versions of the documentation.
2510 Does most of the work. Builds the elcs, infos at a minimum.
2512 4.0.1 The targets that most people would be interested in would be:
2513 -------------------------------------------------------------------
2530 File: lispref.info, Node: Local.rules File, Next: Creating Packages, Prev: Makefile Targets, Up: Packaging
2532 The Local.rules File:
2533 =====================
2535 This file in `packages' provides the XEmacs Packaging System with
2536 information about the local configuration and environment. To create
2537 `Local.rules', simply copy `Local.rules.template' from that directory to
2538 `Local.rules' and edit it to suit your needs.
2540 These are the variables in `Local.rules' that you may need to
2544 The name (and path if needed) of the XEmacs binary to use for
2545 building the packages. The default is `xemacs'.
2548 This will enable some, as yet, unimplemented features in XEmacs
2549 21.5 and above. For now leave this blank (the default) regardless
2550 of the XEmacs version you are using.
2552 `BUILD_WITHOUT_MULE'
2553 Set this to `t' if you are using a non-Mule XEmacs. The default is
2554 that this variable is not set (blank) which means to build _with_
2558 Set this to `t' if you are using a native Microsoft Windows build
2559 of XEmacs (not a Cygwin build) to build the packages. *N.B.* To
2560 Windows users, you still need the Cygwin environment to actually
2563 `XEMACS_INSTALLED_PACKAGES_ROOT'
2564 Set this to the root of where you want the packages to be
2565 installed. Under this directory will hang `xemacs-packages' and
2566 `mule-packages'. See NONMULE_INSTALLED_PACKAGES_ROOT and
2567 MULE_INSTALLED_PACKAGES_ROOT. The default for this is
2568 `/usr/local/lib/xemacs'. Which may not be what you want if you are
2569 developing XEmacs. To quote the comments in
2570 `Local.rules.template':
2572 If you are developing XEmacs, you probably don't want to
2573 install the packages under /usr/local, which is where the
2574 stable, released version of XEmacs goes. Instead, we suggest
2575 a layout as described in the base README file of recent
2576 versions of XEmacs. In a nutshell, we suggest you put your
2577 source under /src/xemacs, and under this put the package
2578 sources in package-src/, and the installed packages in
2579 xemacs-packages/ and mule-packages/. If you do everything
2580 this way, you might want to set things as follows:
2582 XEMACS_INSTALLED_PACKAGES_ROOT = ${XEMACS_PACKAGES_BASE}/..
2584 which puts the xemacs-packages/ and mule-packages/
2585 directories as sisters of the package-src/ directory, and you
2586 have to tell configure the location of the installed packages
2587 using `-package-path', something like
2590 -package-path=/src/xemacs/xemacs-packages;/src/xemacs/mule-packages
2593 The default is unset (blank). If you set this to `t' then `make
2594 install' will create a "symlink farm" of the installed packages
2595 under XEMACS_INSTALLED_PACKAGES_ROOT. Obviously, for this to
2596 work, your system has to support symbolic links. This is as close
2597 as you can get to "running in place" for the packages.
2599 `NONMULE_INSTALLED_PACKAGES_ROOT'
2600 This is where the non-Mule packages get installed to. The default
2601 is `${XEMACS_INSTALLED_PACKAGES_ROOT}/xemacs-packages'.
2603 `MULE_INSTALLED_PACKAGES_ROOT'
2604 This is where the Mule packages get installed to. The default is
2605 `${XEMACS_INSTALLED_PACKAGES_ROOT}/mule-packages'.
2608 A whitespace separated list of non-Mule packages to build/install.
2610 NONMULE_PACKAGES = bbdb gnus xemacs-base prog-modes
2612 The value for this variable can also be the symbol
2613 `xemacs-packages', which means to build/install _all_ of the
2614 non-Mule packages. The default is `xemacs-packages'.
2617 A whitespace separated list of Mule packages to build/install.
2619 MULE_PACKAGES = mule-base leim locale
2621 The value for this variable can also be the symbol
2622 `mule-packages', which means to build/install _all_ of the Mule
2623 packages. The default is `mule-packages'.
2626 The name of the package-index file. The default is `package-index'
2627 and you probably don't need to worry about changing it.
2630 The path to a BSD compatible install program. The default is
2634 The path to GNU/tar. The default is `tar'.
2637 The path to the bzip2 compression program. The default is unset
2638 (blank). If this is set `.tar.bz2' archives will be built _in
2639 addition to_ the `.tar.gz' archives.
2642 For things that you _don't_ want to go into the package tarballs.
2643 It takes the same format as GNU/tar's `--exclude' option. The
2651 --exclude '*.orig' \
2656 Set to the XEmacs command line option that forces running in
2657 "vanilla" mode. The default is `-vanilla'. You wouldn't ever
2661 How to put XEmacs into "batch" mode. It also sets a couple of
2662 other things and in the normal course of events you wouldn't need
2663 to alter this from the default which is:
2665 BATCH = $(VANILLA) -batch -eval \
2666 '(setq stack-trace-on-error t \
2667 load-always-display-messages t \
2668 load-ignore-out-of-date-elc-files t \
2669 load-show-full-path-in-messages t)'
2672 The path to `makeinfo'. The default is `makeinfo'
2675 Set this to `t' if you want to install HTML versions of the Texinfo
2676 documentation. The default is unset (blank).
2679 The path to the program that can convert Texinfo source to HTML.
2680 The default is `texi2html'.
2683 The path to the program that can convert Texinfo source to DVI.
2684 The default is `texi2dvi'
2687 The path to the program that can convert DVI to Postscript. The
2691 The path to the program that can convert Texinfo source to PDF
2692 format. The default is `texi2pdf'.
2695 The path to TeX. The default is `tex'
2698 The path to msgfmt. The default is `msgfmt'
2701 The path to your copy command (GNU cp). The default is dependent
2702 on whether or not SYMLINK is set (`t').
2704 If SYMLINK is unset (blank), RCOPY's default is `cp -af'. If
2705 SYMLINK is set (`t'), RCOPY's default is `cp --force --recursive
2708 It should be noted that in most cases the defaults should be fine.
2709 Most people will probably only need to alter:
2711 * XEMACS_INSTALLED_PACKAGES_ROOT
2713 * NONMULE_INSTALLED_PACKAGES_ROOT
2715 * MULE_INSTALLED_PACKAGES_ROOT
2722 File: lispref.info, Node: Creating Packages, Next: Documenting Packages, Prev: Local.rules File, Up: Packaging
2724 5 Creating Packages:
2725 ********************
2727 Creating a package from an existing Lisp library is not very difficult.
2729 In addition to the Lisp libraries themselves, you need a *Note
2730 package-info.in:: file and a simple *Note Makefile::. The rest is done
2731 by `XEmacs.rules', part of the packaging system infrastructure.
2735 * package-info.in:: package-info.in
2736 * Makefile:: `Makefile'
2739 File: lispref.info, Node: package-info.in, Next: Makefile, Up: Creating Packages
2744 `package-info.in' contains information that gets injected into the
2745 `package-index' file when `make bindist' is run. Here is a real world
2746 example from the xemacs-base package (a description of each field
2747 follows the example):
2750 (standards-version 1.1
2752 author-version AUTHOR_VERSION
2754 build-date BUILD_DATE
2755 maintainer MAINTAINER
2760 description "Fundamental XEmacs support, you almost certainly need this."
2764 provides (add-log advice-preload advice annotations assoc case-table chistory comint-xemacs comint compile debug ebuff-menu echistory edmacro ehelp electric enriched env facemenu ffap helper imenu iso-syntax macros novice outline passwd pp regexp-opt regi ring shell skeleton sort thing time-stamp timezone tq xbm-button xpm-button)
2769 Description of the Fields in `package-info.in':
2770 -----------------------------------------------
2773 The name of the package. In the case of the example it is
2777 Part of the internal package infrastructure, its value should
2778 always be `1.1'. Do not change this.
2781 This is the XEmacs package version number of the package. It is
2782 set from the `Makefile' variable VERSION. This is something that
2783 the XEmacs Package Release Engineer deals with so there is no need
2784 for a package maintainer to touch it. In `package-info.in' just
2785 put the place-marker, `VERSION' here.
2788 This is the package's internal, or `upstream' version number if it
2789 has one. It is set from the `Makefile' variable AUTHOR_VERSION.
2792 This is the date of the last change made to the package. It is
2793 auto-generated at build time, taken from the package's toplevel
2797 The date the package was built. It is auto-generated.
2800 This is the name and email address of the package's maintainer.
2801 It is taken from the `Makefile' variable MAINTAINER.
2804 An unused field, leave as `xemacs'
2807 An unused field, can be any of `high', `medium', or `low'.
2810 The `category' of the package. It is taken from the `Makefile'
2811 variable CATEGORY and can be either `standard' for non-Mule
2812 packages, or `mule' for Mule packages. The is also provision for
2813 `unsupported' in this field which would be for packages that
2814 XEmacs.org do not distribute.
2816 *N.B.* As yet, the XEmacs Packaging System does _not_ support this
2817 type of package. It will in the future.
2820 Unused. Always `nil'
2823 A free form short description of the package.
2826 The file name of the package's binary tarball. It is generated at
2827 build time by `make bindist'.
2830 The MD5 message digest of the package's binary tarball. Generated
2831 at build time by `make bindist'.
2834 The size in bytes of the package's binary tarball. Generated at
2838 A whitespace separated list of _all_ the features the package
2839 provides. Surround the list with parens.
2842 Taken from the `Makefile' variable REQUIRES. It is a list of all
2843 the package's dependencies, including any macros and defstructs
2844 that need to be inlined.
2846 `REQUIRES' cannot be correctly computed from the calls to
2847 `require' in the package's library sources. `REQUIRES' is used to
2848 ensure that all macro and defstruct definitions used by the
2849 package are available at build time. This is not merely a matter
2850 of efficiency, to get the expansions inlined. In fact, it is
2851 _impossible_ to call a macro by name in byte-compiled Emacs Lisp
2852 code. Thus, if the macro expansion is not inlined, the call will
2853 result in an error at run-time! Thus, packages providing
2854 libraries that would be loaded because of autoload definitions
2855 must also be included.
2858 Can either be `regular' for a regular package, or `single-file'
2859 for a single file package.
2861 *N.B.* This doesn't refer to the number of lisp files in a
2862 package. A single-file package can have multiple lisp files in it.
2863 *Note Package Terminology::.
2865 The fields in `package-info.in' that need to be changed directly are:
2875 Everything else is either set from the appropriate `Makefile'
2876 variable, is auto-generated at build time, or is static.
2879 File: lispref.info, Node: Makefile, Prev: package-info.in, Up: Creating Packages
2884 The `Makefile' is quite stylized. The idea is similar to an
2885 `Imakefile' or an `automake' file: the complexity is hidden in generic
2886 rules files, in this case the `XEmacs.rules' include file in the top
2887 directory of the packages hierarchy.
2889 It is important to note that the XEmacs used to compile packages is
2890 the bare minimum: it is called with the `-no-autoloads'. This means
2891 that anything not dumped into XEmacs by default needs to be specified
2892 in the `REQUIRES' variable (for packaged Lisp) or in some cases the
2893 `PRELOADS' (autoloads used in libraries mentioned in `PRELOADS').
2895 There isn't much to an XEmacs Packaging System `Makefile', basically
2896 it just contains a few `Makefile' variables and that's it. See the
2899 Here is a real world example, from the `build' package:
2901 # Makefile for build lisp code
2903 # This file is part of XEmacs.
2905 # XEmacs is free software; you can redistribute it and/or modify it
2906 # under the terms of the GNU General Public License as published by the
2907 # Free Software Foundation; either version 2, or (at your option) any
2910 # XEmacs is distributed in the hope that it will be useful, but WITHOUT
2911 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
2912 # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
2915 # You should have received a copy of the GNU General Public License
2916 # along with XEmacs; see the file COPYING. If not, write to
2917 # the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
2918 # Boston, MA 02111-1307, USA.
2920 # For the time being, remove MULE_ELCS from the all dependencies if
2921 # building without Mule.
2924 AUTHOR_VERSION = 2.02
2925 MAINTAINER = Adrian Aichner <adrian@xemacs.org>
2928 REQUIRES = xemacs-base pcl-cvs dired w3 prog-modes
2931 ELCS = build.elc build-report.elc
2935 include ../../XEmacs.rules
2937 Most packages don't need any more than what you see above. It is
2938 usually _not_ necessary to specify any special `Makefile' rules.
2939 Everything is handled from the `*.rules' files in the toplevel of the
2940 package source hierarchy.
2942 Of course, with that said, there are always exceptions to the rule.
2943 If you think that your package will need some special `Makefile'
2944 hackery contact the XEmacs developers <xemacs-beta@xemacs.org>. We
2945 distribute over 100 packages so the chances are good that you won't be
2946 the first to need such hackery and it is probably already catered for.
2948 `Makefile' Variables Explained:
2949 -------------------------------
2951 A number of `make' variables are defined by the XEmacs Packaging
2952 System. Some are required, others are optional. Of course your
2953 `Makefile' may define other variables for private use, but you should
2954 be careful not to choose names that conflict with variables defined and
2955 used by the XEmacs Packaging System.
2957 The required variables are described in the table below. The
2958 corresponding field names for `package-info.in', where relevant, are
2959 given in parentheses.
2962 (version) The version of the XEmacs package, a numeric literal (a
2963 decimal fixed-point number with two-places of precision). The
2964 only person who ever needs to touch this is the XEmacs Packages
2968 (author-version) The upstream author's version, an uninterpreted
2972 (maintainer) A literal containing the XEmacs package's maintainer
2973 and his/her email address.
2976 The name of the package, a literal
2979 The type of package, a literal containing either `regular' for
2980 regular packages, or `single-file' for single-file packages. This
2981 should feed the `type' field in `package-info.in', but currently
2984 *N.B.* `single-file' here does _not_ refer to the number of lisp
2985 files in a package. *Note Package Terminology::.
2988 (category) A literal, either `standard' or `mule'. The non-Mule
2989 packages are `standard' and the Mule packages are, you guessed it,
2990 `mule'. This field is used at package installation time as part of
2991 the process of determining where a package should be installed to.
2994 (requires) A list of packages required to correctly build this
2997 Note that the usual form in `package-info.in' already has the
2998 parentheses, so the `make' variable should be set to a
2999 space-separated list of package names _not_ enclosed in
3002 The list is of _packages_, not _libraries_, as would ordinarily be
3003 provided to the Lisp `require' function.
3005 `REQUIRES' cannot be correctly computed from the calls to
3006 `require' in the package's library sources. `REQUIRES' is used to
3007 ensure that all macro and defstruct definitions used by the
3008 package are available at build time. This is not merely a matter
3009 of efficiency, to get the expansions inlined. In fact, it is
3010 _impossible_ to call a macro by name in byte-compiled Emacs Lisp
3011 code. Thus, if the macro expansion is not inlined, the call will
3012 result in an error at run-time! Thus, packages providing
3013 libraries that would be loaded because of autoload definitions
3014 must also be included.
3017 The list of the byte-compiled Lisp files used by the package.
3018 These files and their `.el' versions will be included in the binary
3019 package. This variable determines which libraries will be
3020 byte-compiled. These libraries are also deleted by `make clean'.
3022 Note there is no sanity-checking done on this variable. If you put
3023 `.el' files in here, they will not be compiled and they _will_ be
3024 deleted by `make clean'. You would surely be very distressed if
3025 that happened, so be very careful. If this variable is left
3026 empty, none of your Lisp code will be compiled or packaged. This
3027 would be a less than amusing surprise, too.
3029 We don't consider this a feature, of course. Please do submit
3030 code to do sanity checking to <xemacs-patches@xemacs.org>.
3032 Optional, but commonly used variables are explained below.
3035 A list of extra byte-compiled Lisp files used by the package to be
3036 installed in a subdirectory of the package's lisp directory. The
3037 same care should be taken with this as with ELCS in regard to
3041 The name of the subdirectory for the ELCS_1 files to be installed
3042 to. Be sure to include `$(PACKAGE)/' as part of the name.
3044 ELCS_1_DEST = $(PACKAGE)/extra
3046 Would put the ELCS_1 files for the package, `foo' into
3047 `xemacs-packages/lisp/foo/extra/'.
3049 `EARLY_GENERATED_LISP'
3050 For additional `.el' files that will be generated before any
3051 byte-compiling happens. Use this for `autoload-type' files. You
3052 must write `Makefile' rules to build these files.
3055 For additional `.el' files that will be generated at
3056 byte-compilation time. You must write `Makefile' rules to build
3060 This is used if you need to pass extra command line arguments to
3061 XEmacs to build the package. For instance, a specification for
3062 loading libraries containing macros before compiling the Lisp in
3063 the package. This is spliced directly into the invocation of
3064 XEmacs for byte-compilation, so it must contain the `-l' flag for
3067 PRELOADS=-l ./apackage-macros.el -l ../bpackage/lisp/bpackage-macros.el
3069 Preloads are loaded before `package-compile.el', so the LOAD-PATH
3070 is minimal. Therefore `PRELOADS' must specify a full path to
3071 packaged Lisp. The base LOAD-PATH does include the core Lisp
3072 directory, so core libraries are found.
3075 The subdirectory in the package's source tree where the `.el' files
3076 reside. This is where the `auto-autoloads.el' file will be placed.
3078 *N.B.* There is no need to use this variable if the `.el' files
3079 are in the package's toplevel directory. AUTOLOAD_PATH defaults
3083 Place calls to `package-suppress' here to indicate Lisp libraries
3084 that should only be available to particular versions of XEmacs.
3087 PACKAGE_SUPPRESS = \
3088 (package-suppress 'xemacs-base \"regexp-opt\" '(emacs-version>= 21 5 11)) \
3089 (package-suppress 'xemacs-base \"easy-mmode\" '(emacs-version>= 21 5 11))
3091 *N.B.* This feature has not yet been implemented in XEmacs yet.
3092 It will appear in an upcoming version of XEmacs 21.5.
3095 Set this to `t' if your package's Texinfo source file is located in
3096 the package's toplevel directory _and_ is named `$(PACKAGE).texi'.
3099 Use this to explicitly list Texinfo sources that _aren't_ in the
3100 package's toplevel directory. For example:
3102 EXPLICIT_DOCS = texi/$(PACKAGE).texi
3104 See DOCS_TXI_EXTENSION and DOCS_TEXINFO_EXTENSION if you don't use
3105 the `.texi' file extension on your Texinfo sources.
3108 List here extra Texinfo source files needed to build your
3109 documentation. Whatever is listed here is passed on to `makeinfo'
3113 Use this to specify extra `.html' files to output.
3115 `DOCS_TEXINFO_EXTENSION'
3116 Set this to `t' if your Texinfo source files have a `.texinfo'
3119 `DOCS_TXI_EXTENSION'
3120 Set this to `t' if your Texinfo source files have a `.txi'
3124 Files listed here will be installed to `.../man/$(PACKAGE)/'. For
3125 example, you might want to list TeX files or `.eps' files here.
3128 Other files (such as extra Lisp sources or an upstream `Makefile')
3129 that are normally placed in the installed Lisp directory, but not
3130 byte-compiled. These files are _preserved_ by the `clean' targets.
3133 For files that need to be installed to `lib-src/$(PACKAGE)/'. If
3134 the files listed here need to be built you will have to write
3135 `Makefile' rules to do so.
3138 Any data files, such as pixmaps, READMEs, and ChangeLogs. These
3139 must be paths relative to the root of the package's source tree.
3140 These files will be copied to `$(DATA_DEST)' for installation.
3141 Any directory component of the path for a file will be stripped,
3142 so that the file ends up in `$(DATA_DEST)', not in a subdiredtory.
3145 The directory where the files in DATA_FILES are installed to. It
3146 is a subdirectory of the installed `etc/' directory. Be sure to
3147 prefix this value with `$(PACKAGE)', for example:
3149 DATA_DEST = $(PACKAGE)/foo
3151 Would put files into `.../etc/$(PACKAGE)/foo/'.
3153 `DATA_1_FILES ... DATA_35_FILES'
3154 For data files that need to go into a different directory from
3157 `DATA_1_DEST ... DATA_35_DEST'
3158 The name of the subdirectory for files specified in DATA_N_FILES.
3159 And like DATA_DEST, be sure to prefix `$(PACKAGE)' to the value of
3162 `EXTRA_DEPENDENCIES'
3163 For additional files to build that aren't appropriate to place in
3164 any other `Makefile' variable. You will need to write `Makefile'
3165 rules to build these files.
3167 7.1 `package-compile.el'
3168 ========================
3170 The XEmacs Packaging System does not automatically become aware of your
3171 package simply because there is a new subtree. If any package,
3172 including your own, requires any of your files, it must be explicitly
3173 added to the compile environment or loads/requires that search
3174 load-path will fail. The changes that need to be made are
3176 *an entry in `package-directory-map'*
3177 This tells the XEmacs Packaging System which distribution
3178 (currently `xemacs-packages' or `mule-packages') your package is
3179 found in. It then looks in the distribution subdirectory whose
3180 name is the same as the package's.
3182 *an entry in the `cond' in `package-name-to-directory'*
3183 This is optional; it is necessary only if you keep your Lisp code
3184 somewhere other than the top-level directory of the package's
3185 source tree, eg, in `packages/xemacs-packages/PACKAGE/lisp'.
3187 This only needs to be done once, when the package is first added to
3188 the XEmacs Packaging System. (Well, when you randomly change the
3189 subdirectory layout, too.) Your changes to `package-compile.el' must
3190 be cleared and checked in by the XEmacs Package Release Engineer before
3191 your package will build correctly from a fresh checkout.
3193 This is unfortunate; it works pretty well once set up, but can cause
3194 confusion when first building a package in the XEmacs Packaging System
3195 context. In particular, if the `package-directory-map' entry for a
3196 required package, including the package itself, is not found, the
3197 necessary requires will not be executed by `package-compile.el'. If
3198 required functions are executed (under `eval-when-compile'), they won't
3199 be found and the compile will fail. If required function is actually a
3200 macro, the byte compiler will not recognize that, compile a function
3201 call to the macro. This will cause a run-time error because the
3202 byte-code interpreter does not know how to execute macros. (Macros can
3203 always be expanded at compile-time, and this is more efficient.)
3205 If your package keeps some or all Lisp code somewhere other than the
3206 top directory, then an entry in `package-name-to-directory' is also
3207 necessary, or requires will fail, leading to the problems just
3211 File: lispref.info, Node: Documenting Packages, Next: Issues, Prev: Creating Packages, Up: Packaging
3213 Documenting Packages:
3214 =====================
3216 Some random notes on documenting your package.
3218 Do write a Texinfo file. It's not that hard to do basically, and
3219 even using the more advanced features of Texinfo soon become natural.
3220 For a start, just grab the template `Samples/package.texi' from the
3221 XEmacs Packaging System source tree, and drop your current README into
3222 the Top node. At least this way your documentation will be accessible
3223 from the standard Info readers. Next, try to add lots of
3224 cross-referencing and logical markup, and then node structure.
3226 Address both end users and developer issues. You may not be the
3229 If you are maintaining a package that is part of the GNU Emacs
3230 distribution, you'll likely find that you occasionally synchronize your
3231 package with the GNU Emacs sources. When you synch a file,
3232 conventionally you should place a comment just above the standard `;;;
3233 Code' comment that looks like this:
3236 ;; GNU Emacs 21.1, 2002-02-08, Stephen Turnbull <stephen@xemacs.org>
3238 This comment is a status flag; the ChangeLog doesn't really give the
3241 Do maintain a detailed ChangeLog.
3244 File: lispref.info, Node: Issues, Prev: Documenting Packages, Up: Packaging
3252 File: lispref.info, Node: Lisp Data Types, Next: Numbers, Prev: Packaging, Up: Top
3257 A Lisp "object" is a piece of data used and manipulated by Lisp
3258 programs. For our purposes, a "type" or "data type" is a set of
3261 Every object belongs to at least one type. Objects of the same type
3262 have similar structures and may usually be used in the same contexts.
3263 Types can overlap, and objects can belong to two or more types.
3264 Consequently, we can ask whether an object belongs to a particular type,
3265 but not for "the" type of an object.
3267 A few fundamental object types are built into XEmacs. These, from
3268 which all other types are constructed, are called "primitive types".
3269 Each object belongs to one and only one primitive type. These types
3270 include "integer", "character" (starting with XEmacs 20.0), "float",
3271 "cons", "symbol", "string", "vector", "bit-vector", "subr",
3272 "compiled-function", "hash-table", "range-table", "char-table",
3273 "weak-list", and several special types, such as "buffer", that are
3274 related to editing. (*Note Editing Types::.)
3276 Each primitive type has a corresponding Lisp function that checks
3277 whether an object is a member of that type.
3279 Note that Lisp is unlike many other languages in that Lisp objects
3280 are "self-typing": the primitive type of the object is implicit in the
3281 object itself. For example, if an object is a vector, nothing can treat
3282 it as a number; Lisp knows it is a vector, not a number.
3284 In most languages, the programmer must declare the data type of each
3285 variable, and the type is known by the compiler but not represented in
3286 the data. Such type declarations do not exist in XEmacs Lisp. A Lisp
3287 variable can have any type of value, and it remembers whatever value
3288 you store in it, type and all.
3290 This chapter describes the purpose, printed representation, and read
3291 syntax of each of the standard types in Emacs Lisp. Details on how to
3292 use these types can be found in later chapters.
3296 * Printed Representation:: How Lisp objects are represented as text.
3297 * Comments:: Comments and their formatting conventions.
3298 * Primitive Types:: List of all primitive types in XEmacs.
3299 * Programming Types:: Types found in all Lisp systems.
3300 * Editing Types:: Types specific to XEmacs.
3301 * Window-System Types:: Types specific to windowing systems.
3302 * Type Predicates:: Tests related to types.
3303 * Equality Predicates:: Tests of equality between any two objects.
3306 File: lispref.info, Node: Printed Representation, Next: Comments, Up: Lisp Data Types
3308 8.1 Printed Representation and Read Syntax
3309 ==========================================
3311 The "printed representation" of an object is the format of the output
3312 generated by the Lisp printer (the function `prin1') for that object.
3313 The "read syntax" of an object is the format of the input accepted by
3314 the Lisp reader (the function `read') for that object. Most objects
3315 have more than one possible read syntax. Some types of object have no
3316 read syntax; except for these cases, the printed representation of an
3317 object is also a read syntax for it.
3319 In other languages, an expression is text; it has no other form. In
3320 Lisp, an expression is primarily a Lisp object and only secondarily the
3321 text that is the object's read syntax. Often there is no need to
3322 emphasize this distinction, but you must keep it in the back of your
3323 mind, or you will occasionally be very confused.
3325 Every type has a printed representation. Some types have no read
3326 syntax, since it may not make sense to enter objects of these types
3327 directly in a Lisp program. For example, the buffer type does not have
3328 a read syntax. Objects of these types are printed in "hash notation":
3329 the characters `#<' followed by a descriptive string (typically the
3330 type name followed by the name of the object), and closed with a
3331 matching `>'. Hash notation cannot be read at all, so the Lisp reader
3332 signals the error `invalid-read-syntax' whenever it encounters `#<'.
3335 => #<buffer "objects.texi">
3337 When you evaluate an expression interactively, the Lisp interpreter
3338 first reads the textual representation of it, producing a Lisp object,
3339 and then evaluates that object (*note Evaluation::). However,
3340 evaluation and reading are separate activities. Reading returns the
3341 Lisp object represented by the text that is read; the object may or may
3342 not be evaluated later. *Note Input Functions::, for a description of
3343 `read', the basic function for reading objects.
3346 File: lispref.info, Node: Comments, Next: Primitive Types, Prev: Printed Representation, Up: Lisp Data Types
3351 A "comment" is text that is written in a program only for the sake of
3352 humans that read the program, and that has no effect on the meaning of
3353 the program. In Lisp, a semicolon (`;') starts a comment if it is not
3354 within a string or character constant. The comment continues to the
3355 end of line. The Lisp reader discards comments; they do not become
3356 part of the Lisp objects which represent the program within the Lisp
3359 The `#@COUNT' construct, which skips the next COUNT characters, is
3360 useful for program-generated comments containing binary data. The
3361 XEmacs Lisp byte compiler uses this in its output files (*note Byte
3362 Compilation::). It isn't meant for source files, however.
3364 *Note Comment Tips::, for conventions for formatting comments.
3367 File: lispref.info, Node: Primitive Types, Next: Programming Types, Prev: Comments, Up: Lisp Data Types
3372 For reference, here is a list of all the primitive types that may exist
3373 in XEmacs. Note that some of these types may not exist in some XEmacs
3374 executables; that depends on the options that XEmacs was configured
3451 * window-configuration
3455 In addition, the following special types are created internally but
3456 will never be seen by Lisp code. You may encounter them, however, if
3457 you are debugging XEmacs. The printed representation of these objects
3458 begins `#<INTERNAL EMACS BUG', which indicates to the Lisp programmer
3459 that he has found an internal bug in XEmacs if he ever encounters any
3480 * symbol-value-buffer-local
3482 * symbol-value-forward
3484 * symbol-value-lisp-magic
3486 * symbol-value-varalias
3491 File: lispref.info, Node: Programming Types, Next: Editing Types, Prev: Primitive Types, Up: Lisp Data Types
3493 8.4 Programming Types
3494 =====================
3496 There are two general categories of types in XEmacs Lisp: those having
3497 to do with Lisp programming, and those having to do with editing. The
3498 former exist in many Lisp implementations, in one form or another. The
3499 latter are unique to XEmacs Lisp.
3503 * Integer Type:: Numbers without fractional parts.
3504 * Floating Point Type:: Numbers with fractional parts and with a large range.
3505 * Character Type:: The representation of letters, numbers and
3507 * Symbol Type:: A multi-use object that refers to a function,
3508 variable, or property list, and has a unique identity.
3509 * Sequence Type:: Both lists and arrays are classified as sequences.
3510 * Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
3511 * Array Type:: Arrays include strings and vectors.
3512 * String Type:: An (efficient) array of characters.
3513 * Vector Type:: One-dimensional arrays.
3514 * Bit Vector Type:: An (efficient) array of bits.
3515 * Function Type:: A piece of executable code you can call from elsewhere.
3516 * Macro Type:: A method of expanding an expression into another
3517 expression, more fundamental but less pretty.
3518 * Primitive Function Type:: A function written in C, callable from Lisp.
3519 * Compiled-Function Type:: A function written in Lisp, then compiled.
3520 * Autoload Type:: A type used for automatically loading seldom-used
3522 * Char Table Type:: A mapping from characters to Lisp objects.
3523 * Hash Table Type:: A fast mapping between Lisp objects.
3524 * Range Table Type:: A mapping from ranges of integers to Lisp objects.
3525 * Weak List Type:: A list with special garbage-collection properties.
3528 File: lispref.info, Node: Integer Type, Next: Floating Point Type, Up: Programming Types
3533 The range of values for integers in XEmacs Lisp is -134217728 to
3534 134217727 (28 bits; i.e., -2**27 to 2**27 - 1) on most machines. (Some
3535 machines, in particular 64-bit machines such as the DEC Alpha, may
3536 provide a wider range.) It is important to note that the XEmacs Lisp
3537 arithmetic functions do not check for overflow. Thus `(1+ 134217727)'
3538 is -134217728 on most machines. (However, you _will_ get an error if
3539 you attempt to read an out-of-range number using the Lisp reader.)
3541 The read syntax for integers is a sequence of (base ten) digits with
3542 an optional sign at the beginning. (The printed representation produced
3543 by the Lisp interpreter never has a leading `+'.)
3545 -1 ; The integer -1.
3547 +1 ; Also the integer 1.
3548 268435457 ; Causes an error on a 28-bit implementation.
3550 *Note Numbers::, for more information.
3553 File: lispref.info, Node: Floating Point Type, Next: Character Type, Prev: Integer Type, Up: Programming Types
3555 8.4.2 Floating Point Type
3556 -------------------------
3558 XEmacs supports floating point numbers. The precise range of floating
3559 point numbers is machine-specific.
3561 The printed representation for floating point numbers requires either
3562 a decimal point (with at least one digit following), an exponent, or
3563 both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
3564 are five ways of writing a floating point number whose value is 1500.
3565 They are all equivalent.
3567 *Note Numbers::, for more information.
3570 File: lispref.info, Node: Character Type, Next: Symbol Type, Prev: Floating Point Type, Up: Programming Types
3572 8.4.3 Character Type
3573 --------------------
3575 In XEmacs version 19, and in all versions of FSF GNU Emacs, a
3576 "character" in XEmacs Lisp is nothing more than an integer. This is
3577 yet another holdover from XEmacs Lisp's derivation from vintage-1980
3578 Lisps; modern versions of Lisp consider this equivalence a bad idea,
3579 and have separate character types. In XEmacs version 20, the modern
3580 convention is followed, and characters are their own primitive types.
3581 (This change was necessary in order for MULE, i.e. Asian-language,
3582 support to be correctly implemented.)
3584 Even in XEmacs version 20, remnants of the equivalence between
3585 characters and integers still exist; this is termed the "char-int
3586 confoundance disease". In particular, many functions such as `eq',
3587 `equal', and `memq' have equivalent functions (`old-eq', `old-equal',
3588 `old-memq', etc.) that pretend like characters are integers are the
3589 same. Byte code compiled under any version 19 Emacs will have all such
3590 functions mapped to their `old-' equivalents when the byte code is read
3591 into XEmacs 20. This is to preserve compatibility--Emacs 19 converts
3592 all constant characters to the equivalent integer during
3593 byte-compilation, and thus there is no other way to preserve byte-code
3594 compatibility even if the code has specifically been written with the
3595 distinction between characters and integers in mind.
3597 Every character has an equivalent integer, called the "character
3598 code". For example, the character `A' is represented as the
3599 integer 65, following the standard ASCII representation of characters.
3600 If XEmacs was not compiled with MULE support, the range of this integer
3601 will always be 0 to 255--eight bits, or one byte. (Integers outside
3602 this range are accepted but silently truncated; however, you should
3603 most decidedly _not_ rely on this, because it will not work under
3604 XEmacs with MULE support.) When MULE support is present, the range of
3605 character codes is much larger. (Currently, 19 bits are used.)
3607 FSF GNU Emacs uses kludgy character codes above 255 to represent
3608 keyboard input of ASCII characters in combination with certain
3609 modifiers. XEmacs does not use this (a more general mechanism is used
3610 that does not distinguish between ASCII keys and other keys), so you
3611 will never find character codes above 255 in a non-MULE XEmacs.
3613 Individual characters are not often used in programs. It is far more
3614 common to work with _strings_, which are sequences composed of
3615 characters. *Note String Type::.
3617 The read syntax for characters begins with a question mark, followed
3618 by the character (if it's printable) or some symbolic representation of
3619 it. In XEmacs 20, where characters are their own type, this is also the
3620 print representation. In XEmacs 19, however, where characters are
3621 really integers, the printed representation of a character is a decimal
3622 number. This is also a possible read syntax for a character, but
3623 writing characters that way in Lisp programs is a very bad idea. You
3624 should _always_ use the special read syntax formats that XEmacs Lisp
3625 provides for characters.
3627 The usual read syntax for alphanumeric characters is a question mark
3628 followed by the character; thus, `?A' for the character `A', `?B' for
3629 the character `B', and `?a' for the character `a'.
3639 You can use the same syntax for punctuation characters, but it is
3640 often a good idea to add a `\' so that the Emacs commands for editing
3641 Lisp code don't get confused. For example, `?\ ' is the way to write
3642 the space character. If the character is `\', you _must_ use a second
3643 `\' to quote it: `?\\'. XEmacs 20 always prints punctuation characters
3644 with a `\' in front of them, to avoid confusion.
3646 You can express the characters Control-g, backspace, tab, newline,
3647 vertical tab, formfeed, return, and escape as `?\a', `?\b', `?\t',
3648 `?\n', `?\v', `?\f', `?\r', `?\e', respectively. Their character codes
3649 are 7, 8, 9, 10, 11, 12, 13, and 27 in decimal. Thus,
3654 ?\b => ?\^H ; backspace, <BS>, `C-h'
3656 ?\t => ?\t ; tab, <TAB>, `C-i'
3658 ?\n => ?\n ; newline, <LFD>, `C-j'
3659 ?\v => ?\^K ; vertical tab, `C-k'
3660 ?\f => ?\^L ; formfeed character, `C-l'
3661 ?\r => ?\r ; carriage return, <RET>, `C-m'
3662 ?\e => ?\^[ ; escape character, <ESC>, `C-['
3663 ?\\ => ?\\ ; backslash character, `\'
3666 ?\b => 8 ; backspace, <BS>, `C-h'
3667 ?\t => 9 ; tab, <TAB>, `C-i'
3668 ?\n => 10 ; newline, <LFD>, `C-j'
3669 ?\v => 11 ; vertical tab, `C-k'
3670 ?\f => 12 ; formfeed character, `C-l'
3671 ?\r => 13 ; carriage return, <RET>, `C-m'
3672 ?\e => 27 ; escape character, <ESC>, `C-['
3673 ?\\ => 92 ; backslash character, `\'
3675 These sequences which start with backslash are also known as "escape
3676 sequences", because backslash plays the role of an escape character;
3677 this usage has nothing to do with the character <ESC>.
3679 Control characters may be represented using yet another read syntax.
3680 This consists of a question mark followed by a backslash, caret, and the
3681 corresponding non-control character, in either upper or lower case. For
3682 example, both `?\^I' and `?\^i' are valid read syntax for the character
3683 `C-i', the character whose value is 9.
3685 Instead of the `^', you can use `C-'; thus, `?\C-i' is equivalent to
3686 `?\^I' and to `?\^i':
3689 ?\^I => ?\t ?\C-I => ?\t
3690 (char-int ?\^I) => 9
3692 ?\^I => 9 ?\C-I => 9
3694 There is also a character read syntax beginning with `\M-'. This
3695 sets the high bit of the character code (same as adding 128 to the
3696 character code). For example, `?\M-A' stands for the character with
3697 character code 193, or 128 plus 65. You should _not_ use this syntax
3698 in your programs. It is a holdover of yet another confoundance disease
3699 from earlier Emacsen. (This was used to represent keyboard input with
3700 the <META> key set, thus the `M'; however, it conflicts with the
3701 legitimate ISO-8859-1 interpretation of the character code. For
3702 example, character code 193 is a lowercase `a' with an acute accent, in
3705 Finally, the most general read syntax consists of a question mark
3706 followed by a backslash and the character code in octal (up to three
3707 octal digits); thus, `?\101' for the character `A', `?\001' for the
3708 character `C-a', and `?\002' for the character `C-b'. Although this
3709 syntax can represent any ASCII character, it is preferred only when the
3710 precise octal value is more important than the ASCII representation.
3713 ?\012 => ?\n ?\n => ?\n ?\C-j => ?\n
3714 ?\101 => ?A ?A => ?A
3716 ?\012 => 10 ?\n => 10 ?\C-j => 10
3717 ?\101 => 65 ?A => 65
3719 A backslash is allowed, and harmless, preceding any character without
3720 a special escape meaning; thus, `?\+' is equivalent to `?+'. There is
3721 no reason to add a backslash before most characters. However, you
3722 should add a backslash before any of the characters `()\|;'`"#.,' to
3723 avoid confusing the Emacs commands for editing Lisp code. Also add a
3724 backslash before whitespace characters such as space, tab, newline and
3725 formfeed. However, it is cleaner to use one of the easily readable
3726 escape sequences, such as `\t', instead of an actual whitespace
3727 character such as a tab.
3730 File: lispref.info, Node: Symbol Type, Next: Sequence Type, Prev: Character Type, Up: Programming Types
3735 A "symbol" in XEmacs Lisp is an object with a name. The symbol name
3736 serves as the printed representation of the symbol. In ordinary use,
3737 the name is unique--no two symbols have the same name.
3739 A symbol can serve as a variable, as a function name, or to hold a
3740 property list. Or it may serve only to be distinct from all other Lisp
3741 objects, so that its presence in a data structure may be recognized
3742 reliably. In a given context, usually only one of these uses is
3743 intended. But you can use one symbol in all of these ways,
3746 A symbol name can contain any characters whatever. Most symbol names
3747 are written with letters, digits, and the punctuation characters
3748 `-+=*/'. Such names require no special punctuation; the characters of
3749 the name suffice as long as the name does not look like a number. (If
3750 it does, write a `\' at the beginning of the name to force
3751 interpretation as a symbol.) The characters `_~!@$%^&:<>{}' are less
3752 often used but also require no special punctuation. Any other
3753 characters may be included in a symbol's name by escaping them with a
3754 backslash. In contrast to its use in strings, however, a backslash in
3755 the name of a symbol simply quotes the single character that follows the
3756 backslash. For example, in a string, `\t' represents a tab character;
3757 in the name of a symbol, however, `\t' merely quotes the letter `t'.
3758 To have a symbol with a tab character in its name, you must actually
3759 use a tab (preceded with a backslash). But it's rare to do such a
3762 Common Lisp note: In Common Lisp, lower case letters are always
3763 "folded" to upper case, unless they are explicitly escaped. In
3764 Emacs Lisp, upper case and lower case letters are distinct.
3766 Here are several examples of symbol names. Note that the `+' in the
3767 fifth example is escaped to prevent it from being read as a number.
3768 This is not necessary in the sixth example because the rest of the name
3769 makes it invalid as a number.
3771 foo ; A symbol named `foo'.
3772 FOO ; A symbol named `FOO', different from `foo'.
3773 char-to-string ; A symbol named `char-to-string'.
3774 1+ ; A symbol named `1+'
3775 ; (not `+1', which is an integer).
3776 \+1 ; A symbol named `+1'
3777 ; (not a very readable name).
3778 \(*\ 1\ 2\) ; A symbol named `(* 1 2)' (a worse name).
3779 +-*/_~!@$%^&=:<>{} ; A symbol named `+-*/_~!@$%^&=:<>{}'.
3780 ; These characters need not be escaped.
3783 File: lispref.info, Node: Sequence Type, Next: Cons Cell Type, Prev: Symbol Type, Up: Programming Types
3785 8.4.5 Sequence Types
3786 --------------------
3788 A "sequence" is a Lisp object that represents an ordered set of
3789 elements. There are two kinds of sequence in XEmacs Lisp, lists and
3790 arrays. Thus, an object of type list or of type array is also
3791 considered a sequence.
3793 Arrays are further subdivided into strings, vectors, and bit vectors.
3794 Vectors can hold elements of any type, but string elements must be
3795 characters, and bit vector elements must be either 0 or 1. However, the
3796 characters in a string can have extents (*note Extents::) and text
3797 properties (*note Text Properties::) like characters in a buffer;
3798 vectors do not support extents or text properties even when their
3799 elements happen to be characters.
3801 Lists, strings, vectors, and bit vectors are different, but they have
3802 important similarities. For example, all have a length L, and all have
3803 elements which can be indexed from zero to L minus one. Also, several
3804 functions, called sequence functions, accept any kind of sequence. For
3805 example, the function `elt' can be used to extract an element of a
3806 sequence, given its index. *Note Sequences Arrays Vectors::.
3808 It is impossible to read the same sequence twice, since sequences are
3809 always created anew upon reading. If you read the read syntax for a
3810 sequence twice, you get two sequences with equal contents. There is one
3811 exception: the empty list `()' always stands for the same object, `nil'.
3814 File: lispref.info, Node: Cons Cell Type, Next: Array Type, Prev: Sequence Type, Up: Programming Types
3816 8.4.6 Cons Cell and List Types
3817 ------------------------------
3819 A "cons cell" is an object comprising two pointers named the CAR and
3820 the CDR. Each of them can point to any Lisp object.
3822 A "list" is a series of cons cells, linked together so that the CDR
3823 of each cons cell points either to another cons cell or to the empty
3824 list. *Note Lists::, for functions that work on lists. Because most
3825 cons cells are used as part of lists, the phrase "list structure" has
3826 come to refer to any structure made out of cons cells.
3828 The names CAR and CDR have only historical meaning now. The
3829 original Lisp implementation ran on an IBM 704 computer which divided
3830 words into two parts, called the "address" part and the "decrement";
3831 CAR was an instruction to extract the contents of the address part of a
3832 register, and CDR an instruction to extract the contents of the
3833 decrement. By contrast, "cons cells" are named for the function `cons'
3834 that creates them, which in turn is named for its purpose, the
3835 construction of cells.
3837 Because cons cells are so central to Lisp, we also have a word for
3838 "an object which is not a cons cell". These objects are called "atoms".
3840 The read syntax and printed representation for lists are identical,
3841 and consist of a left parenthesis, an arbitrary number of elements, and
3842 a right parenthesis.
3844 Upon reading, each object inside the parentheses becomes an element
3845 of the list. That is, a cons cell is made for each element. The CAR
3846 of the cons cell points to the element, and its CDR points to the next
3847 cons cell of the list, which holds the next element in the list. The
3848 CDR of the last cons cell is set to point to `nil'.
3850 A list can be illustrated by a diagram in which the cons cells are
3851 shown as pairs of boxes. (The Lisp reader cannot read such an
3852 illustration; unlike the textual notation, which can be understood by
3853 both humans and computers, the box illustrations can be understood only
3854 by humans.) The following represents the three-element list `(rose
3857 ___ ___ ___ ___ ___ ___
3858 |___|___|--> |___|___|--> |___|___|--> nil
3861 --> rose --> violet --> buttercup
3863 In this diagram, each box represents a slot that can refer to any
3864 Lisp object. Each pair of boxes represents a cons cell. Each arrow is
3865 a reference to a Lisp object, either an atom or another cons cell.
3867 In this example, the first box, the CAR of the first cons cell,
3868 refers to or "contains" `rose' (a symbol). The second box, the CDR of
3869 the first cons cell, refers to the next pair of boxes, the second cons
3870 cell. The CAR of the second cons cell refers to `violet' and the CDR
3871 refers to the third cons cell. The CDR of the third (and last) cons
3872 cell refers to `nil'.
3874 Here is another diagram of the same list, `(rose violet buttercup)',
3875 sketched in a different manner:
3877 --------------- ---------------- -------------------
3878 | car | cdr | | car | cdr | | car | cdr |
3879 | rose | o-------->| violet | o-------->| buttercup | nil |
3881 --------------- ---------------- -------------------
3883 A list with no elements in it is the "empty list"; it is identical
3884 to the symbol `nil'. In other words, `nil' is both a symbol and a list.
3886 Here are examples of lists written in Lisp syntax:
3888 (A 2 "A") ; A list of three elements.
3889 () ; A list of no elements (the empty list).
3890 nil ; A list of no elements (the empty list).
3891 ("A ()") ; A list of one element: the string `"A ()"'.
3892 (A ()) ; A list of two elements: `A' and the empty list.
3893 (A nil) ; Equivalent to the previous.
3894 ((A B C)) ; A list of one element
3895 ; (which is a list of three elements).
3897 Here is the list `(A ())', or equivalently `(A nil)', depicted with
3901 |___|___|--> |___|___|--> nil
3908 * Dotted Pair Notation:: An alternative syntax for lists.
3909 * Association List Type:: A specially constructed list.
3912 File: lispref.info, Node: Dotted Pair Notation, Next: Association List Type, Up: Cons Cell Type
3914 8.4.6.1 Dotted Pair Notation
3915 ............................
3917 "Dotted pair notation" is an alternative syntax for cons cells that
3918 represents the CAR and CDR explicitly. In this syntax, `(A . B)'
3919 stands for a cons cell whose CAR is the object A, and whose CDR is the
3920 object B. Dotted pair notation is therefore more general than list
3921 syntax. In the dotted pair notation, the list `(1 2 3)' is written as
3922 `(1 . (2 . (3 . nil)))'. For `nil'-terminated lists, the two
3923 notations produce the same result, but list notation is usually clearer
3924 and more convenient when it is applicable. When printing a list, the
3925 dotted pair notation is only used if the CDR of a cell is not a list.
3927 Here's how box notation can illustrate dotted pairs. This example
3928 shows the pair `(rose . violet)':
3936 Dotted pair notation can be combined with list notation to represent
3937 a chain of cons cells with a non-`nil' final CDR. For example, `(rose
3938 violet . buttercup)' is equivalent to `(rose . (violet . buttercup))'.
3939 The object looks like this:
3942 |___|___|--> |___|___|--> buttercup
3947 These diagrams make it evident why `(rose . violet . buttercup)' is
3948 invalid syntax; it would require a cons cell that has three parts
3951 The list `(rose violet)' is equivalent to `(rose . (violet))' and
3955 |___|___|--> |___|___|--> nil
3960 Similarly, the three-element list `(rose violet buttercup)' is
3961 equivalent to `(rose . (violet . (buttercup)))'. It looks like this:
3963 ___ ___ ___ ___ ___ ___
3964 |___|___|--> |___|___|--> |___|___|--> nil
3967 --> rose --> violet --> buttercup
3970 File: lispref.info, Node: Association List Type, Prev: Dotted Pair Notation, Up: Cons Cell Type
3972 8.4.6.2 Association List Type
3973 .............................
3975 An "association list" or "alist" is a specially-constructed list whose
3976 elements are cons cells. In each element, the CAR is considered a
3977 "key", and the CDR is considered an "associated value". (In some
3978 cases, the associated value is stored in the CAR of the CDR.)
3979 Association lists are often used as stacks, since it is easy to add or
3980 remove associations at the front of the list.
3984 (setq alist-of-colors
3985 '((rose . red) (lily . white) (buttercup . yellow)))
3987 sets the variable `alist-of-colors' to an alist of three elements. In
3988 the first element, `rose' is the key and `red' is the value.
3990 *Note Association Lists::, for a further explanation of alists and
3991 for functions that work on alists.
3994 File: lispref.info, Node: Array Type, Next: String Type, Prev: Cons Cell Type, Up: Programming Types
3999 An "array" is composed of an arbitrary number of slots for referring to
4000 other Lisp objects, arranged in a contiguous block of memory.
4001 Accessing any element of an array takes the same amount of time. In
4002 contrast, accessing an element of a list requires time proportional to
4003 the position of the element in the list. (Elements at the end of a
4004 list take longer to access than elements at the beginning of a list.)
4006 XEmacs defines three types of array, strings, vectors, and bit
4007 vectors. A string is an array of characters, a vector is an array of
4008 arbitrary objects, and a bit vector is an array of 1's and 0's. All are
4009 one-dimensional. (Most other programming languages support
4010 multidimensional arrays, but they are not essential; you can get the
4011 same effect with an array of arrays.) Each type of array has its own
4012 read syntax; see *Note String Type::, *Note Vector Type::, and *Note
4015 An array may have any length up to the largest integer; but once
4016 created, it has a fixed size. The first element of an array has index
4017 zero, the second element has index 1, and so on. This is called
4018 "zero-origin" indexing. For example, an array of four elements has
4019 indices 0, 1, 2, and 3.
4021 The array type is contained in the sequence type and contains the
4022 string type, the vector type, and the bit vector type.
4025 File: lispref.info, Node: String Type, Next: Vector Type, Prev: Array Type, Up: Programming Types
4030 A "string" is an array of characters. Strings are used for many
4031 purposes in XEmacs, as can be expected in a text editor; for example, as
4032 the names of Lisp symbols, as messages for the user, and to represent
4033 text extracted from buffers. Strings in Lisp are constants: evaluation
4034 of a string returns the same string.
4036 The read syntax for strings is a double-quote, an arbitrary number of
4037 characters, and another double-quote, `"like this"'. The Lisp reader
4038 accepts the same formats for reading the characters of a string as it
4039 does for reading single characters (without the question mark that
4040 begins a character literal). You can enter a nonprinting character such
4041 as tab or `C-a' using the convenient escape sequences, like this: `"\t,
4042 \C-a"'. You can include a double-quote in a string by preceding it
4043 with a backslash; thus, `"\""' is a string containing just a single
4044 double-quote character. (*Note Character Type::, for a description of
4045 the read syntax for characters.)
4047 The printed representation of a string consists of a double-quote,
4048 the characters it contains, and another double-quote. However, you must
4049 escape any backslash or double-quote characters in the string with a
4050 backslash, like this: `"this \" is an embedded quote"'.
4052 The newline character is not special in the read syntax for strings;
4053 if you write a new line between the double-quotes, it becomes a
4054 character in the string. But an escaped newline--one that is preceded
4055 by `\'--does not become part of the string; i.e., the Lisp reader
4056 ignores an escaped newline while reading a string.
4058 "It is useful to include newlines
4059 in documentation strings,
4060 but the newline is \
4061 ignored if escaped."
4062 => "It is useful to include newlines
4063 in documentation strings,
4064 but the newline is ignored if escaped."
4066 A string can hold extents and properties of the text it contains, in
4067 addition to the characters themselves. This enables programs that copy
4068 text between strings and buffers to preserve the extents and properties
4069 with no special effort. *Note Extents::, *Note Text Properties::.
4071 Note that FSF GNU Emacs has a special read and print syntax for
4072 strings with text properties, but XEmacs does not currently implement
4073 this. It was judged better not to include this in XEmacs because it
4074 entails that `equal' return `nil' when passed a string with text
4075 properties and the equivalent string without text properties, which is
4076 often counter-intuitive.
4078 *Note Strings and Characters::, for functions that work on strings.
4081 File: lispref.info, Node: Vector Type, Next: Bit Vector Type, Prev: String Type, Up: Programming Types
4086 A "vector" is a one-dimensional array of elements of any type. It
4087 takes a constant amount of time to access any element of a vector. (In
4088 a list, the access time of an element is proportional to the distance of
4089 the element from the beginning of the list.)
4091 The printed representation of a vector consists of a left square
4092 bracket, the elements, and a right square bracket. This is also the
4093 read syntax. Like numbers and strings, vectors are considered constants
4096 [1 "two" (three)] ; A vector of three elements.
4097 => [1 "two" (three)]
4099 *Note Vectors::, for functions that work with vectors.
4102 File: lispref.info, Node: Bit Vector Type, Next: Function Type, Prev: Vector Type, Up: Programming Types
4104 8.4.10 Bit Vector Type
4105 ----------------------
4107 A "bit vector" is a one-dimensional array of 1's and 0's. It takes a
4108 constant amount of time to access any element of a bit vector, as for
4109 vectors. Bit vectors have an extremely compact internal representation
4110 (one machine bit per element), which makes them ideal for keeping track
4111 of unordered sets, large collections of boolean values, etc.
4113 The printed representation of a bit vector consists of `#*' followed
4114 by the bits in the vector. This is also the read syntax. Like
4115 numbers, strings, and vectors, bit vectors are considered constants for
4118 #*00101000 ; A bit vector of eight elements.
4121 *Note Bit Vectors::, for functions that work with bit vectors.
4124 File: lispref.info, Node: Function Type, Next: Macro Type, Prev: Bit Vector Type, Up: Programming Types
4126 8.4.11 Function Type
4127 --------------------
4129 Just as functions in other programming languages are executable, "Lisp
4130 function" objects are pieces of executable code. However, functions in
4131 Lisp are primarily Lisp objects, and only secondarily the text which
4132 represents them. These Lisp objects are lambda expressions: lists
4133 whose first element is the symbol `lambda' (*note Lambda Expressions::).
4135 In most programming languages, it is impossible to have a function
4136 without a name. In Lisp, a function has no intrinsic name. A lambda
4137 expression is also called an "anonymous function" (*note Anonymous
4138 Functions::). A named function in Lisp is actually a symbol with a
4139 valid function in its function cell (*note Defining Functions::).
4141 Most of the time, functions are called when their names are written
4142 in Lisp expressions in Lisp programs. However, you can construct or
4143 obtain a function object at run time and then call it with the primitive
4144 functions `funcall' and `apply'. *Note Calling Functions::.
4147 File: lispref.info, Node: Macro Type, Next: Primitive Function Type, Prev: Function Type, Up: Programming Types
4152 A "Lisp macro" is a user-defined construct that extends the Lisp
4153 language. It is represented as an object much like a function, but with
4154 different parameter-passing semantics. A Lisp macro has the form of a
4155 list whose first element is the symbol `macro' and whose CDR is a Lisp
4156 function object, including the `lambda' symbol.
4158 Lisp macro objects are usually defined with the built-in `defmacro'
4159 function, but any list that begins with `macro' is a macro as far as
4160 XEmacs is concerned. *Note Macros::, for an explanation of how to
4164 File: lispref.info, Node: Primitive Function Type, Next: Compiled-Function Type, Prev: Macro Type, Up: Programming Types
4166 8.4.13 Primitive Function Type
4167 ------------------------------
4169 A "primitive function" is a function callable from Lisp but written in
4170 the C programming language. Primitive functions are also called
4171 "subrs" or "built-in functions". (The word "subr" is derived from
4172 "subroutine".) Most primitive functions evaluate all their arguments
4173 when they are called. A primitive function that does not evaluate all
4174 its arguments is called a "special form" (*note Special Forms::).
4176 It does not matter to the caller of a function whether the function
4177 is primitive. However, this does matter if you try to substitute a
4178 function written in Lisp for a primitive of the same name. The reason
4179 is that the primitive function may be called directly from C code.
4180 Calls to the redefined function from Lisp will use the new definition,
4181 but calls from C code may still use the built-in definition.
4183 The term "function" refers to all Emacs functions, whether written
4184 in Lisp or C. *Note Function Type::, for information about the
4185 functions written in Lisp.
4187 Primitive functions have no read syntax and print in hash notation
4188 with the name of the subroutine.
4190 (symbol-function 'car) ; Access the function cell
4193 (subrp (symbol-function 'car)) ; Is this a primitive function?
4197 File: lispref.info, Node: Compiled-Function Type, Next: Autoload Type, Prev: Primitive Function Type, Up: Programming Types
4199 8.4.14 Compiled-Function Type
4200 -----------------------------
4202 The byte compiler produces "compiled-function objects". The evaluator
4203 handles this data type specially when it appears as a function to be
4204 called. *Note Byte Compilation::, for information about the byte
4207 The printed representation for a compiled-function object is normally
4208 `#<compiled-function...>'. If `print-readably' is true, however, it is
4212 File: lispref.info, Node: Autoload Type, Next: Char Table Type, Prev: Compiled-Function Type, Up: Programming Types
4214 8.4.15 Autoload Type
4215 --------------------
4217 An "autoload object" is a list whose first element is the symbol
4218 `autoload'. It is stored as the function definition of a symbol as a
4219 placeholder for the real definition; it says that the real definition
4220 is found in a file of Lisp code that should be loaded when necessary.
4221 The autoload object contains the name of the file, plus some other
4222 information about the real definition.
4224 After the file has been loaded, the symbol should have a new function
4225 definition that is not an autoload object. The new definition is then
4226 called as if it had been there to begin with. From the user's point of
4227 view, the function call works as expected, using the function definition
4230 An autoload object is usually created with the function `autoload',
4231 which stores the object in the function cell of a symbol. *Note
4232 Autoload::, for more details.
4235 File: lispref.info, Node: Char Table Type, Next: Hash Table Type, Prev: Autoload Type, Up: Programming Types
4237 8.4.16 Char Table Type
4238 ----------------------
4240 (not yet documented)
4243 File: lispref.info, Node: Hash Table Type, Next: Range Table Type, Prev: Char Table Type, Up: Programming Types
4245 8.4.17 Hash Table Type
4246 ----------------------
4248 A "hash table" is a table providing an arbitrary mapping from one Lisp
4249 object to another, using an internal indexing method called "hashing".
4250 Hash tables are very fast (much more efficient that using an
4251 association list, when there are a large number of elements in the
4254 Hash tables have a special read syntax beginning with
4255 `#s(hash-table' (this is an example of "structure" read syntax. This
4256 notation is also used for printing when `print-readably' is `t'.
4258 Otherwise they print in hash notation (The "hash" in "hash notation"
4259 has nothing to do with the "hash" in "hash table"), giving the number
4260 of elements, total space allocated for elements, and a unique number
4261 assigned at the time the hash table was created. (Hash tables
4262 automatically resize as necessary so there is no danger of running out
4263 of space for elements.)
4265 (make-hash-table :size 50)
4266 => #<hash-table 0/107 0x313a>
4268 *Note Hash Tables::, for information on how to create and work with
4272 File: lispref.info, Node: Range Table Type, Next: Weak List Type, Prev: Hash Table Type, Up: Programming Types
4274 8.4.18 Range Table Type
4275 -----------------------
4277 A "range table" is a table that maps from ranges of integers to
4278 arbitrary Lisp objects. Range tables automatically combine overlapping
4279 ranges that map to the same Lisp object, and operations are provided
4280 for mapping over all of the ranges in a range table.
4282 Range tables have a special read syntax beginning with
4283 `#s(range-table' (this is an example of "structure" read syntax, which
4284 is also used for char tables and faces).
4286 (setq x (make-range-table))
4287 (put-range-table 20 50 'foo x)
4288 (put-range-table 100 200 "bar" x)
4290 => #s(range-table data ((20 50) foo (100 200) "bar"))
4292 *Note Range Tables::, for information on how to create and work with
4296 File: lispref.info, Node: Weak List Type, Prev: Range Table Type, Up: Programming Types
4298 8.4.19 Weak List Type
4299 ---------------------
4301 (not yet documented)
4304 File: lispref.info, Node: Editing Types, Next: Window-System Types, Prev: Programming Types, Up: Lisp Data Types
4309 The types in the previous section are common to many Lisp dialects.
4310 XEmacs Lisp provides several additional data types for purposes
4311 connected with editing.
4315 * Buffer Type:: The basic object of editing.
4316 * Marker Type:: A position in a buffer.
4317 * Extent Type:: A range in a buffer or string, maybe with properties.
4318 * Window Type:: Buffers are displayed in windows.
4319 * Frame Type:: Windows subdivide frames.
4320 * Device Type:: Devices group all frames on a display.
4321 * Console Type:: Consoles group all devices with the same keyboard.
4322 * Window Configuration Type:: Recording the way a frame is subdivided.
4323 * Event Type:: An interesting occurrence in the system.
4324 * Process Type:: A process running on the underlying OS.
4325 * Stream Type:: Receive or send characters.
4326 * Keymap Type:: What function a keystroke invokes.
4327 * Syntax Table Type:: What a character means.
4328 * Display Table Type:: How display tables are represented.
4329 * Database Type:: A connection to an external DBM or DB database.
4330 * Charset Type:: A character set (e.g. all Kanji characters),
4332 * Coding System Type:: An object encapsulating a way of converting between
4333 different textual encodings, under XEmacs/MULE.
4334 * ToolTalk Message Type:: A message, in the ToolTalk IPC protocol.
4335 * ToolTalk Pattern Type:: A pattern, in the ToolTalk IPC protocol.
4338 File: lispref.info, Node: Buffer Type, Next: Marker Type, Up: Editing Types
4343 A "buffer" is an object that holds text that can be edited (*note
4344 Buffers::). Most buffers hold the contents of a disk file (*note
4345 Files::) so they can be edited, but some are used for other purposes.
4346 Most buffers are also meant to be seen by the user, and therefore
4347 displayed, at some time, in a window (*note Windows::). But a buffer
4348 need not be displayed in any window.
4350 The contents of a buffer are much like a string, but buffers are not
4351 used like strings in XEmacs Lisp, and the available operations are
4352 different. For example, insertion of text into a buffer is very
4353 efficient, whereas "inserting" text into a string requires
4354 concatenating substrings, and the result is an entirely new string
4357 Each buffer has a designated position called "point" (*note
4358 Positions::). At any time, one buffer is the "current buffer". Most
4359 editing commands act on the contents of the current buffer in the
4360 neighborhood of point. Many of the standard Emacs functions manipulate
4361 or test the characters in the current buffer; a whole chapter in this
4362 manual is devoted to describing these functions (*note Text::).
4364 Several other data structures are associated with each buffer:
4366 * a local syntax table (*note Syntax Tables::);
4368 * a local keymap (*note Keymaps::);
4370 * a local variable binding list (*note Buffer-Local Variables::);
4372 * a list of extents (*note Extents::);
4374 * and various other related properties.
4376 The local keymap and variable list contain entries that individually
4377 override global bindings or values. These are used to customize the
4378 behavior of programs in different buffers, without actually changing the
4381 A buffer may be "indirect", which means it shares the text of
4382 another buffer. *Note Indirect Buffers::.
4384 Buffers have no read syntax. They print in hash notation, showing
4388 => #<buffer "objects.texi">
4391 File: lispref.info, Node: Marker Type, Next: Extent Type, Prev: Buffer Type, Up: Editing Types
4396 A "marker" denotes a position in a specific buffer. Markers therefore
4397 have two components: one for the buffer, and one for the position.
4398 Changes in the buffer's text automatically relocate the position value
4399 as necessary to ensure that the marker always points between the same
4400 two characters in the buffer.
4402 Markers have no read syntax. They print in hash notation, giving the
4403 current character position and the name of the buffer.
4406 => #<marker at 50661 in objects.texi>
4408 *Note Markers::, for information on how to test, create, copy, and
4412 File: lispref.info, Node: Extent Type, Next: Window Type, Prev: Marker Type, Up: Editing Types
4417 An "extent" specifies temporary alteration of the display appearance of
4418 a part of a buffer (or string). It contains markers delimiting a range
4419 of the buffer, plus a property list (a list whose elements are
4420 alternating property names and values). Extents are used to present
4421 parts of the buffer temporarily in a different display style. They
4422 have no read syntax, and print in hash notation, giving the buffer name
4423 and range of positions.
4425 Extents can exist over strings as well as buffers; the primary use
4426 of this is to preserve extent and text property information as text is
4427 copied from one buffer to another or between different parts of a
4430 Extents have no read syntax. They print in hash notation, giving the
4431 range of text they cover, the name of the buffer or string they are in,
4432 the address in core, and a summary of some of the properties attached to
4436 => #<extent [51742, 51748) font-lock text-prop 0x90121e0 in buffer objects.texi>
4438 *Note Extents::, for how to create and use extents.
4440 Extents are used to implement text properties. *Note Text
4444 File: lispref.info, Node: Window Type, Next: Frame Type, Prev: Extent Type, Up: Editing Types
4449 A "window" describes the portion of the frame that XEmacs uses to
4450 display a buffer. (In standard window-system usage, a "window" is what
4451 XEmacs calls a "frame"; XEmacs confusingly uses the term "window" to
4452 refer to what is called a "pane" in standard window-system usage.)
4453 Every window has one associated buffer, whose contents appear in the
4454 window. By contrast, a given buffer may appear in one window, no
4455 window, or several windows.
4457 Though many windows may exist simultaneously, at any time one window
4458 is designated the "selected window". This is the window where the
4459 cursor is (usually) displayed when XEmacs is ready for a command. The
4460 selected window usually displays the current buffer, but this is not
4461 necessarily the case.
4463 Windows are grouped on the screen into frames; each window belongs to
4464 one and only one frame. *Note Frame Type::.
4466 Windows have no read syntax. They print in hash notation, giving the
4467 name of the buffer being displayed and a unique number assigned at the
4468 time the window was created. (This number can be useful because the
4469 buffer displayed in any given window can change frequently.)
4472 => #<window on "objects.texi" 0x266c>
4474 *Note Windows::, for a description of the functions that work on
4478 File: lispref.info, Node: Frame Type, Next: Device Type, Prev: Window Type, Up: Editing Types
4483 A FRAME is a rectangle on the screen (a "window" in standard
4484 window-system terminology) that contains one or more non-overlapping
4485 Emacs windows ("panes" in standard window-system terminology). A frame
4486 initially contains a single main window (plus perhaps a minibuffer
4487 window) which you can subdivide vertically or horizontally into smaller
4490 Frames have no read syntax. They print in hash notation, giving the
4491 frame's type, name as used for resourcing, and a unique number assigned
4492 at the time the frame was created.
4495 => #<x-frame "emacs" 0x9db>
4497 *Note Frames::, for a description of the functions that work on
4501 File: lispref.info, Node: Device Type, Next: Console Type, Prev: Frame Type, Up: Editing Types
4506 A "device" represents a single display on which frames exist.
4507 Normally, there is only one device object, but there may be more than
4508 one if XEmacs is being run on a multi-headed display (e.g. an X server
4509 with attached color and mono screens) or if XEmacs is simultaneously
4510 driving frames attached to different consoles, e.g. an X display and a
4513 Devices do not have a read syntax. They print in hash notation,
4514 giving the device's type, connection name, and a unique number assigned
4515 at the time the device was created.
4518 => #<x-device on ":0.0" 0x5b9>
4520 *Note Consoles and Devices::, for a description of several functions
4524 File: lispref.info, Node: Console Type, Next: Window Configuration Type, Prev: Device Type, Up: Editing Types
4529 A "console" represents a single keyboard to which devices (i.e.
4530 displays on which frames exist) are connected. Normally, there is only
4531 one console object, but there may be more than one if XEmacs is
4532 simultaneously driving frames attached to different X servers and/or
4533 TTY connections. (XEmacs is capable of driving multiple X and TTY
4534 connections at the same time, and provides a robust mechanism for
4535 handling the differing display capabilities of such heterogeneous
4536 environments. A buffer with embedded glyphs and multiple fonts and
4537 colors, for example, will display reasonably if it simultaneously
4538 appears on a frame on a color X display, a frame on a mono X display,
4539 and a frame on a TTY connection.)
4541 Consoles do not have a read syntax. They print in hash notation,
4542 giving the console's type, connection name, and a unique number assigned
4543 at the time the console was created.
4546 => #<x-console on "localhost:0" 0x5b7>
4548 *Note Consoles and Devices::, for a description of several functions
4549 related to consoles.
4552 File: lispref.info, Node: Window Configuration Type, Next: Event Type, Prev: Console Type, Up: Editing Types
4554 8.5.8 Window Configuration Type
4555 -------------------------------
4557 A "window configuration" stores information about the positions, sizes,
4558 and contents of the windows in a frame, so you can recreate the same
4559 arrangement of windows later.
4561 Window configurations do not have a read syntax. They print in hash
4562 notation, giving a unique number assigned at the time the window
4563 configuration was created.
4565 (current-window-configuration)
4566 => #<window-configuration 0x2db4>
4568 *Note Window Configurations::, for a description of several functions
4569 related to window configurations.
4572 File: lispref.info, Node: Event Type, Next: Process Type, Prev: Window Configuration Type, Up: Editing Types
4577 (not yet documented)
4580 File: lispref.info, Node: Process Type, Next: Stream Type, Prev: Event Type, Up: Editing Types
4585 The word "process" usually means a running program. XEmacs itself runs
4586 in a process of this sort. However, in XEmacs Lisp, a process is a
4587 Lisp object that designates a subprocess created by the XEmacs process.
4588 Programs such as shells, GDB, ftp, and compilers, running in
4589 subprocesses of XEmacs, extend the capabilities of XEmacs.
4591 An Emacs subprocess takes textual input from Emacs and returns
4592 textual output to Emacs for further manipulation. Emacs can also send
4593 signals to the subprocess.
4595 Process objects have no read syntax. They print in hash notation,
4596 giving the name of the process, its associated process ID, and the
4597 current state of the process:
4600 => (#<process "shell" pid 2909 state:run>)
4602 *Note Processes::, for information about functions that create,
4603 delete, return information about, send input or signals to, and receive
4604 output from processes.
4607 File: lispref.info, Node: Stream Type, Next: Keymap Type, Prev: Process Type, Up: Editing Types
4612 A "stream" is an object that can be used as a source or sink for
4613 characters--either to supply characters for input or to accept them as
4614 output. Many different types can be used this way: markers, buffers,
4615 strings, and functions. Most often, input streams (character sources)
4616 obtain characters from the keyboard, a buffer, or a file, and output
4617 streams (character sinks) send characters to a buffer, such as a
4618 `*Help*' buffer, or to the echo area.
4620 The object `nil', in addition to its other meanings, may be used as
4621 a stream. It stands for the value of the variable `standard-input' or
4622 `standard-output'. Also, the object `t' as a stream specifies input
4623 using the minibuffer (*note Minibuffers::) or output in the echo area
4624 (*note The Echo Area::).
4626 Streams have no special printed representation or read syntax, and
4627 print as whatever primitive type they are.
4629 *Note Read and Print::, for a description of functions related to
4630 streams, including parsing and printing functions.
4633 File: lispref.info, Node: Keymap Type, Next: Syntax Table Type, Prev: Stream Type, Up: Editing Types
4638 A "keymap" maps keys typed by the user to commands. This mapping
4639 controls how the user's command input is executed.
4641 NOTE: In XEmacs, a keymap is a separate primitive type. In FSF GNU
4642 Emacs, a keymap is actually a list whose CAR is the symbol `keymap'.
4644 *Note Keymaps::, for information about creating keymaps, handling
4645 prefix keys, local as well as global keymaps, and changing key bindings.
4648 File: lispref.info, Node: Syntax Table Type, Next: Display Table Type, Prev: Keymap Type, Up: Editing Types
4650 8.5.13 Syntax Table Type
4651 ------------------------
4653 Under XEmacs 20, a "syntax table" is a particular type of char table.
4654 Under XEmacs 19, a syntax table a vector of 256 integers. In both
4655 cases, each element defines how one character is interpreted when it
4656 appears in a buffer. For example, in C mode (*note Major Modes::), the
4657 `+' character is punctuation, but in Lisp mode it is a valid character
4658 in a symbol. These modes specify different interpretations by changing
4659 the syntax table entry for `+'.
4661 Syntax tables are used only for scanning text in buffers, not for
4662 reading Lisp expressions. The table the Lisp interpreter uses to read
4663 expressions is built into the XEmacs source code and cannot be changed;
4664 thus, to change the list delimiters to be `{' and `}' instead of `('
4665 and `)' would be impossible.
4667 *Note Syntax Tables::, for details about syntax classes and how to
4668 make and modify syntax tables.
4671 File: lispref.info, Node: Display Table Type, Next: Database Type, Prev: Syntax Table Type, Up: Editing Types
4673 8.5.14 Display Table Type
4674 -------------------------
4676 A "display table" specifies how to display each character code. Each
4677 buffer and each window can have its own display table. A display table
4678 is actually a vector of length 256, although in XEmacs 20 this may
4679 change to be a particular type of char table. *Note Display Tables::.
4682 File: lispref.info, Node: Database Type, Next: Charset Type, Prev: Display Table Type, Up: Editing Types
4684 8.5.15 Database Type
4685 --------------------
4687 (not yet documented)
4690 File: lispref.info, Node: Charset Type, Next: Coding System Type, Prev: Database Type, Up: Editing Types
4695 (not yet documented)
4698 File: lispref.info, Node: Coding System Type, Next: ToolTalk Message Type, Prev: Charset Type, Up: Editing Types
4700 8.5.17 Coding System Type
4701 -------------------------
4703 (not yet documented)
4706 File: lispref.info, Node: ToolTalk Message Type, Next: ToolTalk Pattern Type, Prev: Coding System Type, Up: Editing Types
4708 8.5.18 ToolTalk Message Type
4709 ----------------------------
4711 (not yet documented)
4714 File: lispref.info, Node: ToolTalk Pattern Type, Prev: ToolTalk Message Type, Up: Editing Types
4716 8.5.19 ToolTalk Pattern Type
4717 ----------------------------
4719 (not yet documented)
4722 File: lispref.info, Node: Window-System Types, Next: Type Predicates, Prev: Editing Types, Up: Lisp Data Types
4724 8.6 Window-System Types
4725 =======================
4727 XEmacs also has some types that represent objects such as faces
4728 (collections of display characters), fonts, and pixmaps that are
4729 commonly found in windowing systems.
4733 * Face Type:: A collection of display characteristics.
4734 * Glyph Type:: An image appearing in a buffer or elsewhere.
4735 * Specifier Type:: A way of controlling display characteristics on
4736 a per-buffer, -frame, -window, or -device level.
4737 * Font Instance Type:: The way a font appears on a particular device.
4738 * Color Instance Type:: The way a color appears on a particular device.
4739 * Image Instance Type:: The way an image appears on a particular device.
4740 * Toolbar Button Type:: An object representing a button in a toolbar.
4741 * Subwindow Type:: An externally-controlled window-system window
4742 appearing in a buffer.
4743 * X Resource Type:: A miscellaneous X resource, if Epoch support was
4744 compiled into XEmacs.
4747 File: lispref.info, Node: Face Type, Next: Glyph Type, Up: Window-System Types
4752 (not yet documented)
4755 File: lispref.info, Node: Glyph Type, Next: Specifier Type, Prev: Face Type, Up: Window-System Types
4760 (not yet documented)
4763 File: lispref.info, Node: Specifier Type, Next: Font Instance Type, Prev: Glyph Type, Up: Window-System Types
4765 8.6.3 Specifier Type
4766 --------------------
4768 (not yet documented)
4771 File: lispref.info, Node: Font Instance Type, Next: Color Instance Type, Prev: Specifier Type, Up: Window-System Types
4773 8.6.4 Font Instance Type
4774 ------------------------
4776 (not yet documented)
4779 File: lispref.info, Node: Color Instance Type, Next: Image Instance Type, Prev: Font Instance Type, Up: Window-System Types
4781 8.6.5 Color Instance Type
4782 -------------------------
4784 (not yet documented)
4787 File: lispref.info, Node: Image Instance Type, Next: Toolbar Button Type, Prev: Color Instance Type, Up: Window-System Types
4789 8.6.6 Image Instance Type
4790 -------------------------
4792 (not yet documented)
4795 File: lispref.info, Node: Toolbar Button Type, Next: Subwindow Type, Prev: Image Instance Type, Up: Window-System Types
4797 8.6.7 Toolbar Button Type
4798 -------------------------
4800 (not yet documented)
4803 File: lispref.info, Node: Subwindow Type, Next: X Resource Type, Prev: Toolbar Button Type, Up: Window-System Types
4805 8.6.8 Subwindow Type
4806 --------------------
4808 (not yet documented)
4811 File: lispref.info, Node: X Resource Type, Prev: Subwindow Type, Up: Window-System Types
4813 8.6.9 X Resource Type
4814 ---------------------
4816 (not yet documented)
4819 File: lispref.info, Node: Type Predicates, Next: Equality Predicates, Prev: Window-System Types, Up: Lisp Data Types
4824 The XEmacs Lisp interpreter itself does not perform type checking on
4825 the actual arguments passed to functions when they are called. It could
4826 not do so, since function arguments in Lisp do not have declared data
4827 types, as they do in other programming languages. It is therefore up to
4828 the individual function to test whether each actual argument belongs to
4829 a type that the function can use.
4831 All built-in functions do check the types of their actual arguments
4832 when appropriate, and signal a `wrong-type-argument' error if an
4833 argument is of the wrong type. For example, here is what happens if you
4834 pass an argument to `+' that it cannot handle:
4837 error--> Wrong type argument: integer-or-marker-p, a
4839 If you want your program to handle different types differently, you
4840 must do explicit type checking. The most common way to check the type
4841 of an object is to call a "type predicate" function. Emacs has a type
4842 predicate for each type, as well as some predicates for combinations of
4845 A type predicate function takes one argument; it returns `t' if the
4846 argument belongs to the appropriate type, and `nil' otherwise.
4847 Following a general Lisp convention for predicate functions, most type
4848 predicates' names end with `p'.
4850 Here is an example which uses the predicates `listp' to check for a
4851 list and `symbolp' to check for a symbol.
4855 ;; If X is a symbol, put it on LIST.
4856 (setq list (cons x list)))
4858 ;; If X is a list, add its elements to LIST.
4859 (setq list (append x list)))
4861 ;; We only handle symbols and lists.
4862 (error "Invalid argument %s in add-on" x))))
4864 Here is a table of predefined type predicates, in alphabetical order,
4865 with references to further information.
4868 *Note annotationp: Annotation Primitives.
4871 *Note arrayp: Array Functions.
4874 *Note atom: List-related Predicates.
4877 *Note bit-vector-p: Bit Vector Functions.
4880 *Note bitp: Bit Vector Functions.
4882 `boolean-specifier-p'
4883 *Note boolean-specifier-p: Specifier Types.
4886 *Note buffer-glyph-p: Glyph Types.
4889 *Note buffer-live-p: Killing Buffers.
4892 *Note bufferp: Buffer Basics.
4895 *Note button-event-p: Event Predicates.
4897 `button-press-event-p'
4898 *Note button-press-event-p: Event Predicates.
4900 `button-release-event-p'
4901 *Note button-release-event-p: Event Predicates.
4904 *Note case-table-p: Case Tables.
4907 *Note char-int-p: Character Codes.
4909 `char-or-char-int-p'
4910 *Note char-or-char-int-p: Character Codes.
4913 *Note char-or-string-p: Predicates for Strings.
4916 *Note char-table-p: Char Tables.
4919 *Note characterp: Predicates for Characters.
4922 *Note color-instance-p: Colors.
4924 `color-pixmap-image-instance-p'
4925 *Note color-pixmap-image-instance-p: Image Instance Types.
4928 *Note color-specifier-p: Specifier Types.
4931 *Note commandp: Interactive Call.
4933 `compiled-function-p'
4934 *Note compiled-function-p: Compiled-Function Type.
4937 *Note console-live-p: Connecting to a Console or Device.
4940 *Note consolep: Consoles and Devices.
4943 *Note consp: List-related Predicates.
4946 *Note database-live-p: Connecting to a Database.
4949 *Note databasep: Databases.
4952 *Note device-live-p: Connecting to a Console or Device.
4955 *Note device-or-frame-p: Basic Device Functions.
4958 *Note devicep: Consoles and Devices.
4961 *Note eval-event-p: Event Predicates.
4964 *Note event-live-p: Event Predicates.
4967 *Note eventp: Events.
4970 *Note extent-live-p: Creating and Modifying Extents.
4973 *Note extentp: Extents.
4975 `face-boolean-specifier-p'
4976 *Note face-boolean-specifier-p: Specifier Types.
4979 *Note facep: Basic Face Functions.
4982 *Note floatp: Predicates on Numbers.
4985 *Note font-instance-p: Fonts.
4988 *Note font-specifier-p: Specifier Types.
4991 *Note frame-live-p: Deleting Frames.
4994 *Note framep: Frames.
4997 (not yet documented)
4999 `generic-specifier-p'
5000 *Note generic-specifier-p: Specifier Types.
5003 *Note glyphp: Glyphs.
5006 *Note hash-table-p: Hash Tables.
5009 *Note icon-glyph-p: Glyph Types.
5012 *Note image-instance-p: Images.
5015 *Note image-specifier-p: Specifier Types.
5017 `integer-char-or-marker-p'
5018 *Note integer-char-or-marker-p: Predicates on Markers.
5021 *Note integer-or-char-p: Predicates for Characters.
5023 `integer-or-marker-p'
5024 *Note integer-or-marker-p: Predicates on Markers.
5026 `integer-specifier-p'
5027 *Note integer-specifier-p: Specifier Types.
5030 *Note integerp: Predicates on Numbers.
5033 (not yet documented)
5036 *Note key-press-event-p: Event Predicates.
5039 *Note keymapp: Creating Keymaps.
5042 (not yet documented)
5045 *Note listp: List-related Predicates.
5048 *Note markerp: Predicates on Markers.
5051 *Note misc-user-event-p: Event Predicates.
5053 `mono-pixmap-image-instance-p'
5054 *Note mono-pixmap-image-instance-p: Image Instance Types.
5057 *Note motion-event-p: Event Predicates.
5060 *Note mouse-event-p: Event Predicates.
5062 `natnum-specifier-p'
5063 *Note natnum-specifier-p: Specifier Types.
5066 *Note natnump: Predicates on Numbers.
5069 *Note nlistp: List-related Predicates.
5071 `nothing-image-instance-p'
5072 *Note nothing-image-instance-p: Image Instance Types.
5074 `number-char-or-marker-p'
5075 *Note number-char-or-marker-p: Predicates on Markers.
5077 `number-or-marker-p'
5078 *Note number-or-marker-p: Predicates on Markers.
5081 *Note numberp: Predicates on Numbers.
5084 *Note pointer-glyph-p: Glyph Types.
5086 `pointer-image-instance-p'
5087 *Note pointer-image-instance-p: Image Instance Types.
5090 *Note process-event-p: Event Predicates.
5093 *Note processp: Processes.
5096 *Note range-table-p: Range Tables.
5099 (not yet documented)
5102 *Note sequencep: Sequence Functions.
5105 *Note specifierp: Specifiers.
5108 *Note stringp: Predicates for Strings.
5111 *Note subrp: Function Cells.
5113 `subwindow-image-instance-p'
5114 *Note subwindow-image-instance-p: Image Instance Types.
5117 *Note subwindowp: Subwindows.
5120 *Note symbolp: Symbols.
5123 *Note syntax-table-p: Syntax Tables.
5125 `text-image-instance-p'
5126 *Note text-image-instance-p: Image Instance Types.
5129 *Note timeout-event-p: Event Predicates.
5132 *Note toolbar-button-p: Toolbar.
5134 `toolbar-specifier-p'
5135 *Note toolbar-specifier-p: Toolbar.
5138 *Note user-variable-p: Defining Variables.
5141 *Note vectorp: Vectors.
5144 *Note weak-list-p: Weak Lists.
5146 `window-configuration-p'
5147 *Note window-configuration-p: Window Configurations.
5150 *Note window-live-p: Deleting Windows.
5153 *Note windowp: Basic Windows.
5155 The most general way to check the type of an object is to call the
5156 function `type-of'. Recall that each object belongs to one and only
5157 one primitive type; `type-of' tells you which one (*note Lisp Data
5158 Types::). But `type-of' knows nothing about non-primitive types. In
5159 most cases, it is more convenient to use type predicates than `type-of'.
5161 -- Function: type-of object
5162 This function returns a symbol naming the primitive type of
5163 OBJECT. The value is one of `bit-vector', `buffer', `char-table',
5164 `character', `charset', `coding-system', `cons', `color-instance',
5165 `compiled-function', `console', `database', `device', `event',
5166 `extent', `face', `float', `font-instance', `frame', `glyph',
5167 `hash-table', `image-instance', `integer', `keymap', `marker',
5168 `process', `range-table', `specifier', `string', `subr',
5169 `subwindow', `symbol', `toolbar-button', `tooltalk-message',
5170 `tooltalk-pattern', `vector', `weak-list', `window',
5171 `window-configuration', or `x-resource'.
5177 (type-of '()) ; `()' is `nil'.
5183 File: lispref.info, Node: Equality Predicates, Prev: Type Predicates, Up: Lisp Data Types
5185 8.8 Equality Predicates
5186 =======================
5188 Here we describe two functions that test for equality between any two
5189 objects. Other functions test equality between objects of specific
5190 types, e.g., strings. For these predicates, see the appropriate chapter
5191 describing the data type.
5193 -- Function: eq object1 object2
5194 This function returns `t' if OBJECT1 and OBJECT2 are the same
5195 object, `nil' otherwise. The "same object" means that a change in
5196 one will be reflected by the same change in the other.
5198 `eq' returns `t' if OBJECT1 and OBJECT2 are integers with the same
5199 value. Also, since symbol names are normally unique, if the
5200 arguments are symbols with the same name, they are `eq'. For
5201 other types (e.g., lists, vectors, strings), two arguments with
5202 the same contents or elements are not necessarily `eq' to each
5203 other: they are `eq' only if they are the same object.
5205 (The `make-symbol' function returns an uninterned symbol that is
5206 not interned in the standard `obarray'. When uninterned symbols
5207 are in use, symbol names are no longer unique. Distinct symbols
5208 with the same name are not `eq'. *Note Creating Symbols::.)
5210 NOTE: Under XEmacs 19, characters are really just integers, and
5211 thus characters and integers are `eq'. Under XEmacs 20, it was
5212 necessary to preserve remnants of this in function such as `old-eq'
5213 in order to maintain byte-code compatibility. Byte code compiled
5214 under any Emacs 19 will automatically have calls to `eq' mapped to
5215 `old-eq' when executed under XEmacs 20.
5226 (eq '(1 (2 (3))) '(1 (2 (3))))
5229 (setq foo '(1 (2 (3))))
5233 (eq foo '(1 (2 (3))))
5236 (eq [(1 2) 3] [(1 2) 3])
5239 (eq (point-marker) (point-marker))
5243 -- Function: old-eq object1 object2
5244 This function exists under XEmacs 20 and is exactly like `eq'
5245 except that it suffers from the char-int confoundance disease. In
5246 other words, it returns `t' if given a character and the
5247 equivalent integer, even though the objects are of different types!
5248 You should _not_ ever call this function explicitly in your code.
5249 However, be aware that all calls to `eq' in byte code compiled
5250 under version 19 map to `old-eq' in XEmacs 20. (Likewise for
5251 `old-equal', `old-memq', `old-member', `old-assq' and
5254 ;; Remember, this does not apply under XEmacs 19.
5260 => t ; Eek, we've been infected.
5262 => nil ; We are still healthy.
5264 -- Function: equal object1 object2
5265 This function returns `t' if OBJECT1 and OBJECT2 have equal
5266 components, `nil' otherwise. Whereas `eq' tests if its arguments
5267 are the same object, `equal' looks inside nonidentical arguments
5268 to see if their elements are the same. So, if two objects are
5269 `eq', they are `equal', but the converse is not always true.
5277 (equal "asdf" "asdf")
5282 (equal '(1 (2 (3))) '(1 (2 (3))))
5284 (eq '(1 (2 (3))) '(1 (2 (3))))
5287 (equal [(1 2) 3] [(1 2) 3])
5289 (eq [(1 2) 3] [(1 2) 3])
5292 (equal (point-marker) (point-marker))
5295 (eq (point-marker) (point-marker))
5298 Comparison of strings is case-sensitive.
5300 Note that in FSF GNU Emacs, comparison of strings takes into
5301 account their text properties, and you have to use `string-equal'
5302 if you want only the strings themselves compared. This difference
5303 does not exist in XEmacs; `equal' and `string-equal' always return
5304 the same value on the same strings.
5306 (equal "asdf" "ASDF")
5309 Two distinct buffers are never `equal', even if their contents are
5312 The test for equality is implemented recursively, and circular lists
5313 may therefore cause infinite recursion (leading to an error).
5316 File: lispref.info, Node: Numbers, Next: Strings and Characters, Prev: Lisp Data Types, Up: Top
5321 XEmacs supports two numeric data types: "integers" and "floating point
5322 numbers". Integers are whole numbers such as -3, 0, #b0111, #xFEED,
5323 #o744. Their values are exact. The number prefixes `#b', `#o', and
5324 `#x' are supported to represent numbers in binary, octal, and
5325 hexadecimal notation (or radix). Floating point numbers are numbers
5326 with fractional parts, such as -4.5, 0.0, or 2.71828. They can also be
5327 expressed in exponential notation: 1.5e2 equals 150; in this example,
5328 `e2' stands for ten to the second power, and is multiplied by 1.5.
5329 Floating point values are not exact; they have a fixed, limited amount
5334 * Integer Basics:: Representation and range of integers.
5335 * Float Basics:: Representation and range of floating point.
5336 * Predicates on Numbers:: Testing for numbers.
5337 * Comparison of Numbers:: Equality and inequality predicates.
5338 * Numeric Conversions:: Converting float to integer and vice versa.
5339 * Arithmetic Operations:: How to add, subtract, multiply and divide.
5340 * Rounding Operations:: Explicitly rounding floating point numbers.
5341 * Bitwise Operations:: Logical and, or, not, shifting.
5342 * Math Functions:: Trig, exponential and logarithmic functions.
5343 * Random Numbers:: Obtaining random integers, predictable or not.
5346 File: lispref.info, Node: Integer Basics, Next: Float Basics, Up: Numbers
5351 The range of values for an integer depends on the machine. The minimum
5352 range is -134217728 to 134217727 (28 bits; i.e., -2**27 to 2**27 - 1),
5353 but some machines may provide a wider range. Many examples in this
5354 chapter assume an integer has 28 bits.
5356 The Lisp reader reads an integer as a sequence of digits with
5357 optional initial sign and optional final period.
5361 +1 ; Also the integer 1.
5362 -1 ; The integer -1.
5363 268435457 ; Also the integer 1, due to overflow.
5367 To understand how various functions work on integers, especially the
5368 bitwise operators (*note Bitwise Operations::), it is often helpful to
5369 view the numbers in their binary form.
5371 In 28-bit binary, the decimal integer 5 looks like this:
5373 0000 0000 0000 0000 0000 0000 0101
5375 (We have inserted spaces between groups of 4 bits, and two spaces
5376 between groups of 8 bits, to make the binary integer easier to read.)
5378 The integer -1 looks like this:
5380 1111 1111 1111 1111 1111 1111 1111
5382 -1 is represented as 28 ones. (This is called "two's complement"
5385 The negative integer, -5, is creating by subtracting 4 from -1. In
5386 binary, the decimal integer 4 is 100. Consequently, -5 looks like this:
5388 1111 1111 1111 1111 1111 1111 1011
5390 In this implementation, the largest 28-bit binary integer is the
5391 decimal integer 134,217,727. In binary, it looks like this:
5393 0111 1111 1111 1111 1111 1111 1111
5395 Since the arithmetic functions do not check whether integers go
5396 outside their range, when you add 1 to 134,217,727, the value is the
5397 negative integer -134,217,728:
5401 => 1000 0000 0000 0000 0000 0000 0000
5403 Many of the following functions accept markers for arguments as well
5404 as integers. (*Note Markers::.) More precisely, the actual arguments
5405 to such functions may be either integers or markers, which is why we
5406 often give these arguments the name INT-OR-MARKER. When the argument
5407 value is a marker, its position value is used and its buffer is ignored.
5410 File: lispref.info, Node: Float Basics, Next: Predicates on Numbers, Prev: Integer Basics, Up: Numbers
5412 9.2 Floating Point Basics
5413 =========================
5415 XEmacs supports floating point numbers. The precise range of floating
5416 point numbers is machine-specific; it is the same as the range of the C
5417 data type `double' on the machine in question.
5419 The printed representation for floating point numbers requires either
5420 a decimal point (with at least one digit following), an exponent, or
5421 both. For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
5422 are five ways of writing a floating point number whose value is 1500.
5423 They are all equivalent. You can also use a minus sign to write
5424 negative floating point numbers, as in `-1.0'.
5426 Most modern computers support the IEEE floating point standard, which
5427 provides for positive infinity and negative infinity as floating point
5428 values. It also provides for a class of values called NaN or
5429 "not-a-number"; numerical functions return such values in cases where
5430 there is no correct answer. For example, `(sqrt -1.0)' returns a NaN.
5431 For practical purposes, there's no significant difference between
5432 different NaN values in XEmacs Lisp, and there's no rule for precisely
5433 which NaN value should be used in a particular case, so this manual
5434 doesn't try to distinguish them. XEmacs Lisp has no read syntax for
5435 NaNs or infinities; perhaps we should create a syntax in the future.
5437 You can use `logb' to extract the binary exponent of a floating
5438 point number (or estimate the logarithm of an integer):
5440 -- Function: logb number
5441 This function returns the binary exponent of NUMBER. More
5442 precisely, the value is the logarithm of NUMBER base 2, rounded
5446 File: lispref.info, Node: Predicates on Numbers, Next: Comparison of Numbers, Prev: Float Basics, Up: Numbers
5448 9.3 Type Predicates for Numbers
5449 ===============================
5451 The functions in this section test whether the argument is a number or
5452 whether it is a certain sort of number. The functions `integerp' and
5453 `floatp' can take any type of Lisp object as argument (the predicates
5454 would not be of much use otherwise); but the `zerop' predicate requires
5455 a number as its argument. See also `integer-or-marker-p',
5456 `integer-char-or-marker-p', `number-or-marker-p' and
5457 `number-char-or-marker-p', in *Note Predicates on Markers::.
5459 -- Function: floatp object
5460 This predicate tests whether its argument is a floating point
5461 number and returns `t' if so, `nil' otherwise.
5463 `floatp' does not exist in Emacs versions 18 and earlier.
5465 -- Function: integerp object
5466 This predicate tests whether its argument is an integer, and
5467 returns `t' if so, `nil' otherwise.
5469 -- Function: numberp object
5470 This predicate tests whether its argument is a number (either
5471 integer or floating point), and returns `t' if so, `nil' otherwise.
5473 -- Function: natnump object
5474 The `natnump' predicate (whose name comes from the phrase
5475 "natural-number-p") tests to see whether its argument is a
5476 nonnegative integer, and returns `t' if so, `nil' otherwise. 0 is
5477 considered non-negative.
5479 -- Function: zerop number
5480 This predicate tests whether its argument is zero, and returns `t'
5481 if so, `nil' otherwise. The argument must be a number.
5483 These two forms are equivalent: `(zerop x)' == `(= x 0)'.
5486 File: lispref.info, Node: Comparison of Numbers, Next: Numeric Conversions, Prev: Predicates on Numbers, Up: Numbers
5488 9.4 Comparison of Numbers
5489 =========================
5491 To test numbers for numerical equality, you should normally use `=',
5492 not `eq'. There can be many distinct floating point number objects
5493 with the same numeric value. If you use `eq' to compare them, then you
5494 test whether two values are the same _object_. By contrast, `='
5495 compares only the numeric values of the objects.
5497 At present, each integer value has a unique Lisp object in XEmacs
5498 Lisp. Therefore, `eq' is equivalent to `=' where integers are
5499 concerned. It is sometimes convenient to use `eq' for comparing an
5500 unknown value with an integer, because `eq' does not report an error if
5501 the unknown value is not a number--it accepts arguments of any type.
5502 By contrast, `=' signals an error if the arguments are not numbers or
5503 markers. However, it is a good idea to use `=' if you can, even for
5504 comparing integers, just in case we change the representation of
5505 integers in a future XEmacs version.
5507 There is another wrinkle: because floating point arithmetic is not
5508 exact, it is often a bad idea to check for equality of two floating
5509 point values. Usually it is better to test for approximate equality.
5510 Here's a function to do this:
5512 (defconst fuzz-factor 1.0e-6)
5513 (defun approx-equal (x y)
5514 (or (and (= x 0) (= y 0))
5516 (max (abs x) (abs y)))
5519 Common Lisp note: Comparing numbers in Common Lisp always requires
5520 `=' because Common Lisp implements multi-word integers, and two
5521 distinct integer objects can have the same numeric value. XEmacs
5522 Lisp can have just one integer object for any given value because
5523 it has a limited range of integer values.
5525 In addition to numbers, all of the following functions also accept
5526 characters and markers as arguments, and treat them as their number
5529 -- Function: = number &rest more-numbers
5530 This function returns `t' if all of its arguments are numerically
5531 equal, `nil' otherwise.
5542 -- Function: /= number &rest more-numbers
5543 This function returns `t' if no two arguments are numerically
5544 equal, `nil' otherwise.
5553 -- Function: < number &rest more-numbers
5554 This function returns `t' if the sequence of its arguments is
5555 monotonically increasing, `nil' otherwise.
5564 -- Function: <= number &rest more-numbers
5565 This function returns `t' if the sequence of its arguments is
5566 monotonically nondecreasing, `nil' otherwise.
5575 -- Function: > number &rest more-numbers
5576 This function returns `t' if the sequence of its arguments is
5577 monotonically decreasing, `nil' otherwise.
5579 -- Function: >= number &rest more-numbers
5580 This function returns `t' if the sequence of its arguments is
5581 monotonically nonincreasing, `nil' otherwise.
5583 -- Function: max number &rest more-numbers
5584 This function returns the largest of its arguments.
5593 -- Function: min number &rest more-numbers
5594 This function returns the smallest of its arguments.
5600 File: lispref.info, Node: Numeric Conversions, Next: Arithmetic Operations, Prev: Comparison of Numbers, Up: Numbers
5602 9.5 Numeric Conversions
5603 =======================
5605 To convert an integer to floating point, use the function `float'.
5607 -- Function: float number
5608 This returns NUMBER converted to floating point. If NUMBER is
5609 already a floating point number, `float' returns it unchanged.
5611 There are four functions to convert floating point numbers to
5612 integers; they differ in how they round. These functions accept
5613 integer arguments also, and return such arguments unchanged.
5615 -- Function: truncate number
5616 This returns NUMBER, converted to an integer by rounding towards
5619 -- Function: floor number &optional divisor
5620 This returns NUMBER, converted to an integer by rounding downward
5621 (towards negative infinity).
5623 If DIVISOR is specified, NUMBER is divided by DIVISOR before the
5624 floor is taken; this is the division operation that corresponds to
5625 `mod'. An `arith-error' results if DIVISOR is 0.
5627 -- Function: ceiling number
5628 This returns NUMBER, converted to an integer by rounding upward
5629 (towards positive infinity).
5631 -- Function: round number
5632 This returns NUMBER, converted to an integer by rounding towards
5633 the nearest integer. Rounding a value equidistant between two
5634 integers may choose the integer closer to zero, or it may prefer
5635 an even integer, depending on your machine.
5638 File: lispref.info, Node: Arithmetic Operations, Next: Rounding Operations, Prev: Numeric Conversions, Up: Numbers
5640 9.6 Arithmetic Operations
5641 =========================
5643 XEmacs Lisp provides the traditional four arithmetic operations:
5644 addition, subtraction, multiplication, and division. Remainder and
5645 modulus functions supplement the division functions. The functions to
5646 add or subtract 1 are provided because they are traditional in Lisp and
5649 All of these functions except `%' return a floating point value if
5650 any argument is floating.
5652 It is important to note that in XEmacs Lisp, arithmetic functions do
5653 not check for overflow. Thus `(1+ 134217727)' may evaluate to
5654 -134217728, depending on your hardware.
5656 -- Function: 1+ number
5657 This function returns NUMBER plus one. NUMBER may be a number,
5658 character or marker. Markers and characters are converted to
5668 This function is not analogous to the C operator `++'--it does not
5669 increment a variable. It just computes a sum. Thus, if we
5675 If you want to increment the variable, you must use `setq', like
5681 Now that the `cl' package is always available from lisp code, a
5682 more convenient and natural way to increment a variable is
5685 -- Function: 1- number
5686 This function returns NUMBER minus one. NUMBER may be a number,
5687 character or marker. Markers and characters are converted to
5690 -- Function: abs number
5691 This returns the absolute value of NUMBER.
5693 -- Function: + &rest numbers
5694 This function adds its arguments together. When given no
5695 arguments, `+' returns 0.
5697 If any of the arguments are characters or markers, they are first
5698 converted to integers.
5707 -- Function: - &optional number &rest other-numbers
5708 The `-' function serves two purposes: negation and subtraction.
5709 When `-' has a single argument, the value is the negative of the
5710 argument. When there are multiple arguments, `-' subtracts each of
5711 the OTHER-NUMBERS from NUMBER, cumulatively. If there are no
5712 arguments, an error is signaled.
5714 If any of the arguments are characters or markers, they are first
5715 converted to integers.
5724 -- Function: * &rest numbers
5725 This function multiplies its arguments together, and returns the
5726 product. When given no arguments, `*' returns 1.
5728 If any of the arguments are characters or markers, they are first
5729 converted to integers.
5738 -- Function: / dividend &rest divisors
5739 The `/' function serves two purposes: inversion and division. When
5740 `/' has a single argument, the value is the inverse of the
5741 argument. When there are multiple arguments, `/' divides DIVIDEND
5742 by each of the DIVISORS, cumulatively, returning the quotient. If
5743 there are no arguments, an error is signaled.
5745 If none of the arguments are floats, then the result is an integer.
5746 This means the result has to be rounded. On most machines, the
5747 result is rounded towards zero after each division, but some
5748 machines may round differently with negative arguments. This is
5749 because the Lisp function `/' is implemented using the C division
5750 operator, which also permits machine-dependent rounding. As a
5751 practical matter, all known machines round in the standard fashion.
5753 If any of the arguments are characters or markers, they are first
5754 converted to integers.
5756 If you divide by 0, an `arith-error' error is signaled. (*Note
5766 => 0.3333333333333333
5770 The result of `(/ -17 6)' could in principle be -3 on some
5773 -- Function: % dividend divisor
5774 This function returns the integer remainder after division of
5775 DIVIDEND by DIVISOR. The arguments must be integers or markers.
5777 For negative arguments, the remainder is in principle
5778 machine-dependent since the quotient is; but in practice, all
5779 known machines behave alike.
5781 An `arith-error' results if DIVISOR is 0.
5792 For any two integers DIVIDEND and DIVISOR,
5794 (+ (% DIVIDEND DIVISOR)
5795 (* (/ DIVIDEND DIVISOR) DIVISOR))
5797 always equals DIVIDEND.
5799 -- Function: mod dividend divisor
5800 This function returns the value of DIVIDEND modulo DIVISOR; in
5801 other words, the remainder after division of DIVIDEND by DIVISOR,
5802 but with the same sign as DIVISOR. The arguments must be numbers
5805 Unlike `%', `mod' returns a well-defined result for negative
5806 arguments. It also permits floating point arguments; it rounds the
5807 quotient downward (towards minus infinity) to an integer, and uses
5808 that quotient to compute the remainder.
5810 An `arith-error' results if DIVISOR is 0.
5823 For any two numbers DIVIDEND and DIVISOR,
5825 (+ (mod DIVIDEND DIVISOR)
5826 (* (floor DIVIDEND DIVISOR) DIVISOR))
5828 always equals DIVIDEND, subject to rounding error if either
5829 argument is floating point. For `floor', see *Note Numeric
5833 File: lispref.info, Node: Rounding Operations, Next: Bitwise Operations, Prev: Arithmetic Operations, Up: Numbers
5835 9.7 Rounding Operations
5836 =======================
5838 The functions `ffloor', `fceiling', `fround' and `ftruncate' take a
5839 floating point argument and return a floating point result whose value
5840 is a nearby integer. `ffloor' returns the nearest integer below;
5841 `fceiling', the nearest integer above; `ftruncate', the nearest integer
5842 in the direction towards zero; `fround', the nearest integer.
5844 -- Function: ffloor number
5845 This function rounds NUMBER to the next lower integral value, and
5846 returns that value as a floating point number.
5848 -- Function: fceiling number
5849 This function rounds NUMBER to the next higher integral value, and
5850 returns that value as a floating point number.
5852 -- Function: ftruncate number
5853 This function rounds NUMBER towards zero to an integral value, and
5854 returns that value as a floating point number.
5856 -- Function: fround number
5857 This function rounds NUMBER to the nearest integral value, and
5858 returns that value as a floating point number.
5861 File: lispref.info, Node: Bitwise Operations, Next: Math Functions, Prev: Rounding Operations, Up: Numbers
5863 9.8 Bitwise Operations on Integers
5864 ==================================
5866 In a computer, an integer is represented as a binary number, a sequence
5867 of "bits" (digits which are either zero or one). A bitwise operation
5868 acts on the individual bits of such a sequence. For example,
5869 "shifting" moves the whole sequence left or right one or more places,
5870 reproducing the same pattern "moved over".
5872 The bitwise operations in XEmacs Lisp apply only to integers.
5874 -- Function: lsh integer1 count
5875 `lsh', which is an abbreviation for "logical shift", shifts the
5876 bits in INTEGER1 to the left COUNT places, or to the right if
5877 COUNT is negative, bringing zeros into the vacated bits. If COUNT
5878 is negative, `lsh' shifts zeros into the leftmost
5879 (most-significant) bit, producing a positive result even if
5880 INTEGER1 is negative. Contrast this with `ash', below.
5882 Here are two examples of `lsh', shifting a pattern of bits one
5883 place to the left. We show only the low-order eight bits of the
5884 binary pattern; the rest are all zero.
5888 ;; Decimal 5 becomes decimal 10.
5889 00000101 => 00001010
5893 ;; Decimal 7 becomes decimal 14.
5894 00000111 => 00001110
5896 As the examples illustrate, shifting the pattern of bits one place
5897 to the left produces a number that is twice the value of the
5900 Shifting a pattern of bits two places to the left produces results
5901 like this (with 8-bit binary numbers):
5905 ;; Decimal 3 becomes decimal 12.
5906 00000011 => 00001100
5908 On the other hand, shifting one place to the right looks like this:
5912 ;; Decimal 6 becomes decimal 3.
5913 00000110 => 00000011
5917 ;; Decimal 5 becomes decimal 2.
5918 00000101 => 00000010
5920 As the example illustrates, shifting one place to the right
5921 divides the value of a positive integer by two, rounding downward.
5923 The function `lsh', like all XEmacs Lisp arithmetic functions, does
5924 not check for overflow, so shifting left can discard significant
5925 bits and change the sign of the number. For example, left shifting
5926 134,217,727 produces -2 on a 28-bit machine:
5928 (lsh 134217727 1) ; left shift
5931 In binary, in the 28-bit implementation, the argument looks like
5934 ;; Decimal 134,217,727
5935 0111 1111 1111 1111 1111 1111 1111
5937 which becomes the following when left shifted:
5940 1111 1111 1111 1111 1111 1111 1110
5942 -- Function: ash integer1 count
5943 `ash' ("arithmetic shift") shifts the bits in INTEGER1 to the left
5944 COUNT places, or to the right if COUNT is negative.
5946 `ash' gives the same results as `lsh' except when INTEGER1 and
5947 COUNT are both negative. In that case, `ash' puts ones in the
5948 empty bit positions on the left, while `lsh' puts zeros in those
5951 Thus, with `ash', shifting the pattern of bits one place to the
5952 right looks like this:
5955 ;; Decimal -6 becomes decimal -3.
5956 1111 1111 1111 1111 1111 1111 1010
5958 1111 1111 1111 1111 1111 1111 1101
5960 In contrast, shifting the pattern of bits one place to the right
5961 with `lsh' looks like this:
5963 (lsh -6 -1) => 134217725
5964 ;; Decimal -6 becomes decimal 134,217,725.
5965 1111 1111 1111 1111 1111 1111 1010
5967 0111 1111 1111 1111 1111 1111 1101
5969 Here are other examples:
5971 ; 28-bit binary values
5973 (lsh 5 2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
5974 => 20 ; = 0000 0000 0000 0000 0000 0001 0100
5977 (lsh -5 2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
5978 => -20 ; = 1111 1111 1111 1111 1111 1110 1100
5981 (lsh 5 -2) ; 5 = 0000 0000 0000 0000 0000 0000 0101
5982 => 1 ; = 0000 0000 0000 0000 0000 0000 0001
5985 (lsh -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
5986 => 4194302 ; = 0011 1111 1111 1111 1111 1111 1110
5987 (ash -5 -2) ; -5 = 1111 1111 1111 1111 1111 1111 1011
5988 => -2 ; = 1111 1111 1111 1111 1111 1111 1110
5990 -- Function: logand &rest ints-or-markers
5991 This function returns the "logical and" of the arguments: the Nth
5992 bit is set in the result if, and only if, the Nth bit is set in
5993 all the arguments. ("Set" means that the value of the bit is 1
5996 For example, using 4-bit binary numbers, the "logical and" of 13
5997 and 12 is 12: 1101 combined with 1100 produces 1100. In both the
5998 binary numbers, the leftmost two bits are set (i.e., they are
5999 1's), so the leftmost two bits of the returned value are set.
6000 However, for the rightmost two bits, each is zero in at least one
6001 of the arguments, so the rightmost two bits of the returned value
6009 If `logand' is not passed any argument, it returns a value of -1.
6010 This number is an identity element for `logand' because its binary
6011 representation consists entirely of ones. If `logand' is passed
6012 just one argument, it returns that argument.
6014 ; 28-bit binary values
6016 (logand 14 13) ; 14 = 0000 0000 0000 0000 0000 0000 1110
6017 ; 13 = 0000 0000 0000 0000 0000 0000 1101
6018 => 12 ; 12 = 0000 0000 0000 0000 0000 0000 1100
6020 (logand 14 13 4) ; 14 = 0000 0000 0000 0000 0000 0000 1110
6021 ; 13 = 0000 0000 0000 0000 0000 0000 1101
6022 ; 4 = 0000 0000 0000 0000 0000 0000 0100
6023 => 4 ; 4 = 0000 0000 0000 0000 0000 0000 0100
6026 => -1 ; -1 = 1111 1111 1111 1111 1111 1111 1111
6028 -- Function: logior &rest ints-or-markers
6029 This function returns the "inclusive or" of its arguments: the Nth
6030 bit is set in the result if, and only if, the Nth bit is set in at
6031 least one of the arguments. If there are no arguments, the result
6032 is zero, which is an identity element for this operation. If
6033 `logior' is passed just one argument, it returns that argument.
6035 ; 28-bit binary values
6037 (logior 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
6038 ; 5 = 0000 0000 0000 0000 0000 0000 0101
6039 => 13 ; 13 = 0000 0000 0000 0000 0000 0000 1101
6041 (logior 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
6042 ; 5 = 0000 0000 0000 0000 0000 0000 0101
6043 ; 7 = 0000 0000 0000 0000 0000 0000 0111
6044 => 15 ; 15 = 0000 0000 0000 0000 0000 0000 1111
6046 -- Function: logxor &rest ints-or-markers
6047 This function returns the "exclusive or" of its arguments: the Nth
6048 bit is set in the result if, and only if, the Nth bit is set in an
6049 odd number of the arguments. If there are no arguments, the
6050 result is 0, which is an identity element for this operation. If
6051 `logxor' is passed just one argument, it returns that argument.
6053 ; 28-bit binary values
6055 (logxor 12 5) ; 12 = 0000 0000 0000 0000 0000 0000 1100
6056 ; 5 = 0000 0000 0000 0000 0000 0000 0101
6057 => 9 ; 9 = 0000 0000 0000 0000 0000 0000 1001
6059 (logxor 12 5 7) ; 12 = 0000 0000 0000 0000 0000 0000 1100
6060 ; 5 = 0000 0000 0000 0000 0000 0000 0101
6061 ; 7 = 0000 0000 0000 0000 0000 0000 0111
6062 => 14 ; 14 = 0000 0000 0000 0000 0000 0000 1110
6064 -- Function: lognot integer
6065 This function returns the logical complement of its argument: the
6066 Nth bit is one in the result if, and only if, the Nth bit is zero
6067 in INTEGER, and vice-versa.
6071 ;; 5 = 0000 0000 0000 0000 0000 0000 0101
6073 ;; -6 = 1111 1111 1111 1111 1111 1111 1010
6076 File: lispref.info, Node: Math Functions, Next: Random Numbers, Prev: Bitwise Operations, Up: Numbers
6078 9.9 Standard Mathematical Functions
6079 ===================================
6081 These mathematical functions are available if floating point is
6082 supported (which is the normal state of affairs). They allow integers
6083 as well as floating point numbers as arguments.
6085 -- Function: sin number
6086 -- Function: cos number
6087 -- Function: tan number
6088 These are the ordinary trigonometric functions, with argument
6089 measured in radians.
6091 -- Function: asin number
6092 The value of `(asin NUMBER)' is a number between -pi/2 and pi/2
6093 (inclusive) whose sine is NUMBER; if, however, NUMBER is out of
6094 range (outside [-1, 1]), then the result is a NaN.
6096 -- Function: acos number
6097 The value of `(acos NUMBER)' is a number between 0 and pi
6098 (inclusive) whose cosine is NUMBER; if, however, NUMBER is out of
6099 range (outside [-1, 1]), then the result is a NaN.
6101 -- Function: atan number &optional number2
6102 The value of `(atan NUMBER)' is a number between -pi/2 and pi/2
6103 (exclusive) whose tangent is NUMBER.
6105 If optional argument NUMBER2 is supplied, the function returns
6106 `atan2(NUMBER,NUMBER2)'.
6108 -- Function: sinh number
6109 -- Function: cosh number
6110 -- Function: tanh number
6111 These are the ordinary hyperbolic trigonometric functions.
6113 -- Function: asinh number
6114 -- Function: acosh number
6115 -- Function: atanh number
6116 These are the inverse hyperbolic trigonometric functions.
6118 -- Function: exp number
6119 This is the exponential function; it returns e to the power
6120 NUMBER. e is a fundamental mathematical constant also called the
6121 base of natural logarithms.
6123 -- Function: log number &optional base
6124 This function returns the logarithm of NUMBER, with base BASE. If
6125 you don't specify BASE, the base `e' is used. If NUMBER is
6126 negative, the result is a NaN.
6128 -- Function: log10 number
6129 This function returns the logarithm of NUMBER, with base 10. If
6130 NUMBER is negative, the result is a NaN. `(log10 X)' == `(log X
6131 10)', at least approximately.
6133 -- Function: expt x y
6134 This function returns X raised to power Y. If both arguments are
6135 integers and Y is positive, the result is an integer; in this
6136 case, it is truncated to fit the range of possible integer values.
6138 -- Function: sqrt number
6139 This returns the square root of NUMBER. If NUMBER is negative,
6142 -- Function: cube-root number
6143 This returns the cube root of NUMBER.
6146 File: lispref.info, Node: Random Numbers, Prev: Math Functions, Up: Numbers
6151 A deterministic computer program cannot generate true random numbers.
6152 For most purposes, "pseudo-random numbers" suffice. A series of
6153 pseudo-random numbers is generated in a deterministic fashion. The
6154 numbers are not truly random, but they have certain properties that
6155 mimic a random series. For example, all possible values occur equally
6156 often in a pseudo-random series.
6158 In XEmacs, pseudo-random numbers are generated from a "seed" number.
6159 Starting from any given seed, the `random' function always generates
6160 the same sequence of numbers. XEmacs always starts with the same seed
6161 value, so the sequence of values of `random' is actually the same in
6162 each XEmacs run! For example, in one operating system, the first call
6163 to `(random)' after you start XEmacs always returns -1457731, and the
6164 second one always returns -7692030. This repeatability is helpful for
6167 If you want truly unpredictable random numbers, execute `(random
6168 t)'. This chooses a new seed based on the current time of day and on
6169 XEmacs's process ID number.
6171 -- Function: random &optional limit
6172 This function returns a pseudo-random integer. Repeated calls
6173 return a series of pseudo-random integers.
6175 If LIMIT is a positive integer, the value is chosen to be
6176 nonnegative and less than LIMIT.
6178 If LIMIT is `t', it means to choose a new seed based on the
6179 current time of day and on XEmacs's process ID number.
6181 On some machines, any integer representable in Lisp may be the
6182 result of `random'. On other machines, the result can never be
6183 larger than a certain maximum or less than a certain (negative)
6187 File: lispref.info, Node: Strings and Characters, Next: Lists, Prev: Numbers, Up: Top
6189 10 Strings and Characters
6190 *************************
6192 A string in XEmacs Lisp is an array that contains an ordered sequence
6193 of characters. Strings are used as names of symbols, buffers, and
6194 files, to send messages to users, to hold text being copied between
6195 buffers, and for many other purposes. Because strings are so important,
6196 XEmacs Lisp has many functions expressly for manipulating them. XEmacs
6197 Lisp programs use strings more often than individual characters.
6201 * String Basics:: Basic properties of strings and characters.
6202 * Predicates for Strings:: Testing whether an object is a string or char.
6203 * Creating Strings:: Functions to allocate new strings.
6204 * Predicates for Characters:: Testing whether an object is a character.
6205 * Character Codes:: Each character has an equivalent integer.
6206 * Text Comparison:: Comparing characters or strings.
6207 * String Conversion:: Converting characters or strings and vice versa.
6208 * Modifying Strings:: Changing characters in a string.
6209 * String Properties:: Additional information attached to strings.
6210 * Formatting Strings:: `format': XEmacs's analog of `printf'.
6211 * Character Case:: Case conversion functions.
6212 * Case Tables:: Customizing case conversion.
6213 * Char Tables:: Mapping from characters to Lisp objects.
6216 File: lispref.info, Node: String Basics, Next: Predicates for Strings, Up: Strings and Characters
6218 10.1 String and Character Basics
6219 ================================
6221 Strings in XEmacs Lisp are arrays that contain an ordered sequence of
6222 characters. Characters are their own primitive object type in XEmacs
6223 20. However, in XEmacs 19, characters are represented in XEmacs Lisp as
6224 integers; whether an integer was intended as a character or not is
6225 determined only by how it is used. *Note Character Type::.
6227 The length of a string (like any array) is fixed and independent of
6228 the string contents, and cannot be altered. Strings in Lisp are _not_
6229 terminated by a distinguished character code. (By contrast, strings in
6230 C are terminated by a character with ASCII code 0.) This means that
6231 any character, including the null character (ASCII code 0), is a valid
6232 element of a string.
6234 Since strings are considered arrays, you can operate on them with the
6235 general array functions. (*Note Sequences Arrays Vectors::.) For
6236 example, you can access or change individual characters in a string
6237 using the functions `aref' and `aset' (*note Array Functions::).
6239 Strings use an efficient representation for storing the characters
6240 in them, and thus take up much less memory than a vector of the same
6243 Sometimes you will see strings used to hold key sequences. This
6244 exists for backward compatibility with Emacs 18, but should _not_ be
6245 used in new code, since many key chords can't be represented at all and
6246 others (in particular meta key chords) are confused with accented
6249 Strings are useful for holding regular expressions. You can also
6250 match regular expressions against strings (*note Regexp Search::). The
6251 functions `match-string' (*note Simple Match Data::) and
6252 `replace-match' (*note Replacing Match::) are useful for decomposing
6253 and modifying strings based on regular expression matching.
6255 Like a buffer, a string can contain extents in it. These extents are
6256 created when a function such as `buffer-substring' is called on a
6257 region with duplicable extents in it. When the string is inserted into
6258 a buffer, the extents are inserted along with it. *Note Duplicable
6261 *Note Text::, for information about functions that display strings or
6262 copy them into buffers. *Note Character Type::, and *Note String
6263 Type::, for information about the syntax of characters and strings.
6266 File: lispref.info, Node: Predicates for Strings, Next: Creating Strings, Prev: String Basics, Up: Strings and Characters
6268 10.2 The Predicates for Strings
6269 ===============================
6271 For more information about general sequence and array predicates, see
6272 *Note Sequences Arrays Vectors::, and *Note Arrays::.
6274 -- Function: stringp object
6275 This function returns `t' if OBJECT is a string, `nil' otherwise.
6277 -- Function: char-or-string-p object
6278 This function returns `t' if OBJECT is a string or a character,
6281 In XEmacs addition, this function also returns `t' if OBJECT is an
6282 integer that can be represented as a character. This is because
6283 of compatibility with previous XEmacs and should not be depended
6287 File: lispref.info, Node: Creating Strings, Next: Predicates for Characters, Prev: Predicates for Strings, Up: Strings and Characters
6289 10.3 Creating Strings
6290 =====================
6292 The following functions create strings, either from scratch, or by
6293 putting strings together, or by taking them apart.
6295 -- Function: string &rest characters
6296 This function returns a new string made up of CHARACTERS.
6298 (string ?X ?E ?m ?a ?c ?s)
6303 Analogous functions operating on other data types include `list',
6304 `cons' (*note Building Lists::), `vector' (*note Vectors::) and
6305 `bit-vector' (*note Bit Vectors::). This function has not been
6306 available in XEmacs prior to 21.0 and FSF Emacs prior to 20.3.
6308 -- Function: make-string length character
6309 This function returns a new string consisting entirely of LENGTH
6310 successive copies of CHARACTER. LENGTH must be a non-negative
6318 Other functions to compare with this one include `char-to-string'
6319 (*note String Conversion::), `make-vector' (*note Vectors::), and
6320 `make-list' (*note Building Lists::).
6322 -- Function: substring string start &optional end
6323 This function returns a new string which consists of those
6324 characters from STRING in the range from (and including) the
6325 character at the index START up to (but excluding) the character
6326 at the index END. The first character is at index zero.
6328 (substring "abcdefg" 0 3)
6331 Here the index for `a' is 0, the index for `b' is 1, and the index
6332 for `c' is 2. Thus, three letters, `abc', are copied from the
6333 string `"abcdefg"'. The index 3 marks the character position up
6334 to which the substring is copied. The character whose index is 3
6335 is actually the fourth character in the string.
6337 A negative number counts from the end of the string, so that -1
6338 signifies the index of the last character of the string. For
6341 (substring "abcdefg" -3 -1)
6344 In this example, the index for `e' is -3, the index for `f' is -2,
6345 and the index for `g' is -1. Therefore, `e' and `f' are included,
6346 and `g' is excluded.
6348 When `nil' is used as an index, it stands for the length of the
6351 (substring "abcdefg" -3 nil)
6354 Omitting the argument END is equivalent to specifying `nil'. It
6355 follows that `(substring STRING 0)' returns a copy of all of
6358 (substring "abcdefg" 0)
6361 But we recommend `copy-sequence' for this purpose (*note Sequence
6364 If the characters copied from STRING have duplicable extents or
6365 text properties, those are copied into the new string also. *Note
6366 Duplicable Extents::.
6368 A `wrong-type-argument' error is signaled if either START or END
6369 is not an integer or `nil'. An `args-out-of-range' error is
6370 signaled if START indicates a character following END, or if
6371 either integer is out of range for STRING.
6373 Contrast this function with `buffer-substring' (*note Buffer
6374 Contents::), which returns a string containing a portion of the
6375 text in the current buffer. The beginning of a string is at index
6376 0, but the beginning of a buffer is at index 1.
6378 -- Function: concat &rest sequences
6379 This function returns a new string consisting of the characters in
6380 the arguments passed to it (along with their text properties, if
6381 any). The arguments may be strings, lists of numbers, or vectors
6382 of numbers; they are not themselves changed. If `concat' receives
6383 no arguments, it returns an empty string.
6385 (concat "abc" "-def")
6387 (concat "abc" (list 120 (+ 256 121)) [122])
6389 ;; `nil' is an empty sequence.
6390 (concat "abc" nil "-def")
6392 (concat "The " "quick brown " "fox.")
6393 => "The quick brown fox."
6397 The second example above shows how characters stored in strings are
6398 taken modulo 256. In other words, each character in the string is
6401 The `concat' function always constructs a new string that is not
6402 `eq' to any existing string.
6404 When an argument is an integer (not a sequence of integers), it is
6405 converted to a string of digits making up the decimal printed
6406 representation of the integer. *Don't use this feature; we plan
6407 to eliminate it. If you already use this feature, change your
6408 programs now!* The proper way to convert an integer to a decimal
6409 number in this way is with `format' (*note Formatting Strings::) or
6410 `number-to-string' (*note String Conversion::).
6417 For information about other concatenation functions, see the
6418 description of `mapconcat' in *Note Mapping Functions::, `vconcat'
6419 in *Note Vectors::, `bvconcat' in *Note Bit Vectors::, and `append'
6420 in *Note Building Lists::.
6423 File: lispref.info, Node: Predicates for Characters, Next: Character Codes, Prev: Creating Strings, Up: Strings and Characters
6425 10.4 The Predicates for Characters
6426 ==================================
6428 -- Function: characterp object
6429 This function returns `t' if OBJECT is a character.
6431 Some functions that work on integers (e.g. the comparison functions
6432 <, <=, =, /=, etc. and the arithmetic functions +, -, *, etc.)
6433 accept characters and implicitly convert them into integers. In
6434 general, functions that work on characters also accept char-ints
6435 and implicitly convert them into characters. WARNING: Neither of
6436 these behaviors is very desirable, and they are maintained for
6437 backward compatibility with old E-Lisp programs that confounded
6438 characters and integers willy-nilly. These behaviors may change
6439 in the future; therefore, do not rely on them. Instead, convert
6440 the characters explicitly using `char-int'.
6442 -- Function: integer-or-char-p object
6443 This function returns `t' if OBJECT is an integer or character.
6446 File: lispref.info, Node: Character Codes, Next: Text Comparison, Prev: Predicates for Characters, Up: Strings and Characters
6448 10.5 Character Codes
6449 ====================
6451 -- Function: char-int character
6452 This function converts a character into an equivalent integer.
6453 The resulting integer will always be non-negative. The integers in
6454 the range 0 - 255 map to characters as follows:
6466 Right half of ISO-8859-1
6468 If support for MULE does not exist, these are the only valid
6469 character values. When MULE support exists, the values assigned to
6470 other characters may vary depending on the particular version of
6471 XEmacs, the order in which character sets were loaded, etc., and
6472 you should not depend on them.
6474 -- Function: int-char integer
6475 This function converts an integer into the equivalent character.
6476 Not all integers correspond to valid characters; use `char-int-p'
6477 to determine whether this is the case. If the integer cannot be
6478 converted, `nil' is returned.
6480 -- Function: char-int-p object
6481 This function returns `t' if OBJECT is an integer that can be
6482 converted into a character.
6484 -- Function: char-or-char-int-p object
6485 This function returns `t' if OBJECT is a character or an integer
6486 that can be converted into one.
6489 File: lispref.info, Node: Text Comparison, Next: String Conversion, Prev: Character Codes, Up: Strings and Characters
6491 10.6 Comparison of Characters and Strings
6492 =========================================
6494 -- Function: char-equal character1 character2 &optional buffer
6495 This function returns `t' if the arguments represent the same
6496 character, `nil' otherwise. This function ignores differences in
6497 case if the value of `case-fold-search' is non-`nil' in BUFFER,
6498 which defaults to the current buffer.
6502 (let ((case-fold-search t))
6505 (let ((case-fold-search nil))
6509 -- Function: char= character1 character2
6510 This function returns `t' if the arguments represent the same
6511 character, `nil' otherwise. Case is significant.
6517 (let ((case-fold-search t))
6520 (let ((case-fold-search nil))
6524 -- Function: string= string1 string2
6525 This function returns `t' if the characters of the two strings
6526 match exactly; case is significant.
6528 (string= "abc" "abc")
6530 (string= "abc" "ABC")
6532 (string= "ab" "ABC")
6536 -- Function: string-equal string1 string2
6537 `string-equal' is another name for `string='.
6539 -- Function: string< string1 string2
6540 This function compares two strings a character at a time. First it
6541 scans both the strings at once to find the first pair of
6542 corresponding characters that do not match. If the lesser
6543 character of those two is the character from STRING1, then STRING1
6544 is less, and this function returns `t'. If the lesser character
6545 is the one from STRING2, then STRING1 is greater, and this
6546 function returns `nil'. If the two strings match entirely, the
6549 Pairs of characters are compared by their ASCII codes. Keep in
6550 mind that lower case letters have higher numeric values in the
6551 ASCII character set than their upper case counterparts; numbers and
6552 many punctuation characters have a lower numeric value than upper
6555 (string< "abc" "abd")
6557 (string< "abd" "abc")
6559 (string< "123" "abc")
6562 When the strings have different lengths, and they match up to the
6563 length of STRING1, then the result is `t'. If they match up to
6564 the length of STRING2, the result is `nil'. A string of no
6565 characters is less than any other string.
6569 (string< "ab" "abc")
6573 (string< "abc" "ab")
6578 -- Function: string-lessp string1 string2
6579 `string-lessp' is another name for `string<'.
6581 See also `compare-buffer-substrings' in *Note Comparing Text::, for
6582 a way to compare text in buffers. The function `string-match', which
6583 matches a regular expression against a string, can be used for a kind
6584 of string comparison; see *Note Regexp Search::.
6587 File: lispref.info, Node: String Conversion, Next: Modifying Strings, Prev: Text Comparison, Up: Strings and Characters
6589 10.7 Conversion of Characters and Strings
6590 =========================================
6592 This section describes functions for conversions between characters,
6593 strings and integers. `format' and `prin1-to-string' (*note Output
6594 Functions::) can also convert Lisp objects into strings.
6595 `read-from-string' (*note Input Functions::) can "convert" a string
6596 representation of a Lisp object into an object.
6598 *Note Documentation::, for functions that produce textual
6599 descriptions of text characters and general input events
6600 (`single-key-description' and `text-char-description'). These
6601 functions are used primarily for making help messages.
6603 -- Function: char-to-string character
6604 This function returns a new string with a length of one character.
6605 The value of CHARACTER, modulo 256, is used to initialize the
6606 element of the string.
6608 This function is similar to `make-string' with an integer argument
6609 of 1. (*Note Creating Strings::.) This conversion can also be
6610 done with `format' using the `%c' format specification. (*Note
6611 Formatting Strings::.)
6615 (char-to-string (+ 256 ?x))
6620 -- Function: string-to-char string
6621 This function returns the first character in STRING. If the
6622 string is empty, the function returns 0. (Under XEmacs 19, the
6623 value is also 0 when the first character of STRING is the null
6624 character, ASCII code 0.)
6626 (string-to-char "ABC")
6627 => ?A ;; Under XEmacs 20.
6628 => 65 ;; Under XEmacs 19.
6629 (string-to-char "xyz")
6630 => ?x ;; Under XEmacs 20.
6631 => 120 ;; Under XEmacs 19.
6634 (string-to-char "\000")
6635 => ?\^ ;; Under XEmacs 20.
6636 => 0 ;; Under XEmacs 20.
6638 This function may be eliminated in the future if it does not seem
6639 useful enough to retain.
6641 -- Function: number-to-string number
6642 This function returns a string consisting of the printed
6643 representation of NUMBER, which may be an integer or a floating
6644 point number. The value starts with a sign if the argument is
6647 (number-to-string 256)
6649 (number-to-string -23)
6651 (number-to-string -23.5)
6654 `int-to-string' is a semi-obsolete alias for this function.
6656 See also the function `format' in *Note Formatting Strings::.
6658 -- Function: string-to-number string &optional base
6659 This function returns the numeric value represented by STRING,
6660 read in BASE. It skips spaces and tabs at the beginning of
6661 STRING, then reads as much of STRING as it can interpret as a
6662 number. (On some systems it ignores other whitespace at the
6663 beginning, not just spaces and tabs.) If the first character
6664 after the ignored whitespace is not a digit or a minus sign, this
6667 If BASE is not specified, it defaults to ten. With BASE other
6668 than ten, only integers can be read.
6670 (string-to-number "256")
6672 (string-to-number "25 is a perfect square.")
6674 (string-to-number "X256")
6676 (string-to-number "-4.5")
6678 (string-to-number "ffff" 16)
6681 `string-to-int' is an obsolete alias for this function.
6684 File: lispref.info, Node: Modifying Strings, Next: String Properties, Prev: String Conversion, Up: Strings and Characters
6686 10.8 Modifying Strings
6687 ======================
6689 You can modify a string using the general array-modifying primitives.
6690 *Note Arrays::. The function `aset' modifies a single character; the
6691 function `fillarray' sets all characters in the string to a specified
6694 Each string has a tick counter that starts out at zero (when the
6695 string is created) and is incremented each time a change is made to that
6698 -- Function: string-modified-tick string
6699 This function returns the tick counter for `string'.
6702 File: lispref.info, Node: String Properties, Next: Formatting Strings, Prev: Modifying Strings, Up: Strings and Characters
6704 10.9 String Properties
6705 ======================
6707 Just as with symbols, extents, faces, and glyphs, you can attach
6708 additional information to strings in the form of "string properties".
6709 These differ from text properties, which are logically attached to
6710 particular characters in the string.
6712 To attach a property to a string, use `put'. To retrieve a property
6713 from a string, use `get'. You can also use `remprop' to remove a
6714 property from a string and `object-plist' to retrieve a list of all the
6715 properties in a string.
6718 File: lispref.info, Node: Formatting Strings, Next: Character Case, Prev: String Properties, Up: Strings and Characters
6720 10.10 Formatting Strings
6721 ========================
6723 "Formatting" means constructing a string by substitution of computed
6724 values at various places in a constant string. This string controls
6725 how the other values are printed as well as where they appear; it is
6726 called a "format string".
6728 Formatting is often useful for computing messages to be displayed.
6729 In fact, the functions `message' and `error' provide the same
6730 formatting feature described here; they differ from `format' only in
6731 how they use the result of formatting.
6733 -- Function: format string &rest objects
6734 This function returns a new string that is made by copying STRING
6735 and then replacing any format specification in the copy with
6736 encodings of the corresponding OBJECTS. The arguments OBJECTS are
6737 the computed values to be formatted.
6739 A format specification is a sequence of characters beginning with a
6740 `%'. Thus, if there is a `%d' in STRING, the `format' function
6741 replaces it with the printed representation of one of the values to be
6742 formatted (one of the arguments OBJECTS). For example:
6744 (format "The value of fill-column is %d." fill-column)
6745 => "The value of fill-column is 72."
6747 If STRING contains more than one format specification, the format
6748 specifications correspond with successive values from OBJECTS. Thus,
6749 the first format specification in STRING uses the first such value, the
6750 second format specification uses the second such value, and so on. Any
6751 extra format specifications (those for which there are no corresponding
6752 values) cause unpredictable behavior. Any extra values to be formatted
6755 Certain format specifications require values of particular types.
6756 However, no error is signaled if the value actually supplied fails to
6757 have the expected type. Instead, the output is likely to be
6760 Here is a table of valid format specifications:
6763 Replace the specification with the printed representation of the
6764 object, made without quoting. Thus, strings are represented by
6765 their contents alone, with no `"' characters, and symbols appear
6766 without `\' characters. This is equivalent to printing the object
6769 If there is no corresponding object, the empty string is used.
6772 Replace the specification with the printed representation of the
6773 object, made with quoting. Thus, strings are enclosed in `"'
6774 characters, and `\' characters appear where necessary before
6775 special characters. This is equivalent to printing the object
6778 If there is no corresponding object, the empty string is used.
6781 Replace the specification with the base-eight representation of an
6786 Replace the specification with the base-ten representation of an
6790 Replace the specification with the base-sixteen representation of
6791 an integer, using lowercase letters.
6794 Replace the specification with the base-sixteen representation of
6795 an integer, using uppercase letters.
6798 Replace the specification with the character which is the value
6802 Replace the specification with the exponential notation for a
6803 floating point number (e.g. `7.85200e+03').
6806 Replace the specification with the decimal-point notation for a
6807 floating point number.
6810 Replace the specification with notation for a floating point
6811 number, using a "pretty format". Either exponential notation or
6812 decimal-point notation will be used (usually whichever is
6813 shorter), and trailing zeroes are removed from the fractional part.
6816 A single `%' is placed in the string. This format specification is
6817 unusual in that it does not use a value. For example, `(format "%%
6818 %d" 30)' returns `"% 30"'.
6820 Any other format character results in an `Invalid format operation'
6823 Here are several examples:
6825 (format "The name of this buffer is %s." (buffer-name))
6826 => "The name of this buffer is strings.texi."
6828 (format "The buffer object prints as %s." (current-buffer))
6829 => "The buffer object prints as #<buffer strings.texi>."
6831 (format "The octal value of %d is %o,
6832 and the hex value is %x." 18 18 18)
6833 => "The octal value of 18 is 22,
6834 and the hex value is 12."
6836 There are many additional flags and specifications that can occur
6837 between the `%' and the format character, in the following order:
6839 1. An optional repositioning specification, which is a positive
6840 integer followed by a `$'.
6842 2. Zero or more of the optional flag characters `-', `+', ` ', `0',
6845 3. An asterisk (`*', meaning that the field width is now assumed to
6846 have been specified as an argument.
6848 4. An optional minimum field width.
6850 5. An optional precision, preceded by a `.' character.
6852 A "repositioning" specification changes which argument to `format'
6853 is used by the current and all following format specifications.
6854 Normally the first specification uses the first argument, the second
6855 specification uses the second argument, etc. Using a repositioning
6856 specification, you can change this. By placing a number N followed by
6857 a `$' between the `%' and the format character, you cause the
6858 specification to use the Nth argument. The next specification will use
6859 the N+1'th argument, etc.
6863 (format "Can't find file `%s' in directory `%s'."
6864 "ignatius.c" "loyola/")
6865 => "Can't find file `ignatius.c' in directory `loyola/'."
6867 (format "In directory `%2$s', the file `%1$s' was not found."
6868 "ignatius.c" "loyola/")
6869 => "In directory `loyola/', the file `ignatius.c' was not found."
6872 "The numbers %d and %d are %1$x and %x in hex and %1$o and %o in octal."
6874 => "The numbers 37 and 12 are 25 and c in hex and 45 and 14 in octal."
6876 As you can see, this lets you reprocess arguments more than once or
6877 reword a format specification (thereby moving the arguments around)
6878 without having to actually reorder the arguments. This is especially
6879 useful in translating messages from one language to another: Different
6880 languages use different word orders, and this sometimes entails changing
6881 the order of the arguments. By using repositioning specifications,
6882 this can be accomplished without having to embed knowledge of particular
6883 languages into the location in the program's code where the message is
6886 All the specification characters allow an optional numeric prefix
6887 between the `%' and the character, and following any repositioning
6888 specification or flag. The optional numeric prefix defines the minimum
6889 width for the object. If the printed representation of the object
6890 contains fewer characters than this, then it is padded. The padding is
6891 normally on the left, but will be on the right if the `-' flag
6892 character is given. The padding character is normally a space, but if
6893 the `0' flag character is given, zeros are used for padding.
6895 (format "%06d is padded on the left with zeros" 123)
6896 => "000123 is padded on the left with zeros"
6898 (format "%-6d is padded on the right" 123)
6899 => "123 is padded on the right"
6901 `format' never truncates an object's printed representation, no
6902 matter what width you specify. Thus, you can use a numeric prefix to
6903 specify a minimum spacing between columns with no risk of losing
6906 In the following three examples, `%7s' specifies a minimum width of
6907 7. In the first case, the string inserted in place of `%7s' has only 3
6908 letters, so 4 blank spaces are inserted for padding. In the second
6909 case, the string `"specification"' is 13 letters wide but is not
6910 truncated. In the third case, the padding is on the right.
6912 (format "The word `%7s' actually has %d letters in it."
6913 "foo" (length "foo"))
6914 => "The word ` foo' actually has 3 letters in it."
6916 (format "The word `%7s' actually has %d letters in it."
6917 "specification" (length "specification"))
6918 => "The word `specification' actually has 13 letters in it."
6920 (format "The word `%-7s' actually has %d letters in it."
6921 "foo" (length "foo"))
6922 => "The word `foo ' actually has 3 letters in it."
6924 After any minimum field width, a precision may be specified by
6925 preceding it with a `.' character. The precision specifies the minimum
6926 number of digits to appear in `%d', `%i', `%o', `%x', and `%X'
6927 conversions (the number is padded on the left with zeroes as
6928 necessary); the number of digits printed after the decimal point for
6929 `%f', `%e', and `%E' conversions; the number of significant digits
6930 printed in `%g' and `%G' conversions; and the maximum number of
6931 non-padding characters printed in `%s' and `%S' conversions. The
6932 default precision for floating-point conversions is six.
6934 The other flag characters have the following meanings:
6936 * The ` ' flag means prefix non-negative numbers with a space.
6938 * The `+' flag means prefix non-negative numbers with a plus sign.
6940 * The `#' flag means print numbers in an alternate, more verbose
6941 format: octal numbers begin with zero; hex numbers begin with a
6942 `0x' or `0X'; a decimal point is printed in `%f', `%e', and `%E'
6943 conversions even if no numbers are printed after it; and trailing
6944 zeroes are not omitted in `%g' and `%G' conversions.
6947 File: lispref.info, Node: Character Case, Next: Case Tables, Prev: Formatting Strings, Up: Strings and Characters
6949 10.11 Character Case
6950 ====================
6952 The character case functions change the case of single characters or of
6953 the contents of strings. The functions convert only alphabetic
6954 characters (the letters `A' through `Z' and `a' through `z'); other
6955 characters are not altered. The functions do not modify the strings
6956 that are passed to them as arguments.
6958 The examples below use the characters `X' and `x' which have ASCII
6959 codes 88 and 120 respectively.
6961 -- Function: downcase string-or-char &optional buffer
6962 This function converts a character or a string to lower case.
6964 When the argument to `downcase' is a string, the function creates
6965 and returns a new string in which each letter in the argument that
6966 is upper case is converted to lower case. When the argument to
6967 `downcase' is a character, `downcase' returns the corresponding
6968 lower case character. (This value is actually an integer under
6969 XEmacs 19.) If the original character is lower case, or is not a
6970 letter, then the value equals the original character.
6972 Optional second arg BUFFER specifies which buffer's case tables to
6973 use, and defaults to the current buffer.
6975 (downcase "The cat in the hat")
6976 => "the cat in the hat"
6979 => ?x ;; Under XEmacs 20.
6980 => 120 ;; Under XEmacs 19.
6982 -- Function: upcase string-or-char &optional buffer
6983 This function converts a character or a string to upper case.
6985 When the argument to `upcase' is a string, the function creates
6986 and returns a new string in which each letter in the argument that
6987 is lower case is converted to upper case.
6989 When the argument to `upcase' is a character, `upcase' returns the
6990 corresponding upper case character. (This value is actually an
6991 integer under XEmacs 19.) If the original character is upper
6992 case, or is not a letter, then the value equals the original
6995 Optional second arg BUFFER specifies which buffer's case tables to
6996 use, and defaults to the current buffer.
6998 (upcase "The cat in the hat")
6999 => "THE CAT IN THE HAT"
7002 => ?X ;; Under XEmacs 20.
7003 => 88 ;; Under XEmacs 19.
7005 -- Function: capitalize string-or-char &optional buffer
7006 This function capitalizes strings or characters. If
7007 STRING-OR-CHAR is a string, the function creates and returns a new
7008 string, whose contents are a copy of STRING-OR-CHAR in which each
7009 word has been capitalized. This means that the first character of
7010 each word is converted to upper case, and the rest are converted
7013 The definition of a word is any sequence of consecutive characters
7014 that are assigned to the word constituent syntax class in the
7015 current syntax table (*note Syntax Class Table::).
7017 When the argument to `capitalize' is a character, `capitalize' has
7018 the same result as `upcase'.
7020 Optional second arg BUFFER specifies which buffer's case tables to
7021 use, and defaults to the current buffer.
7023 (capitalize "The cat in the hat")
7024 => "The Cat In The Hat"
7026 (capitalize "THE 77TH-HATTED CAT")
7027 => "The 77th-Hatted Cat"
7030 => ?X ;; Under XEmacs 20.
7031 => 88 ;; Under XEmacs 19.
7034 File: lispref.info, Node: Case Tables, Next: Char Tables, Prev: Character Case, Up: Strings and Characters
7036 10.12 The Case Table
7037 ====================
7039 You can customize case conversion by installing a special "case table".
7040 A case table specifies the mapping between upper case and lower case
7041 letters. It affects both the string and character case conversion
7042 functions (see the previous section) and those that apply to text in the
7043 buffer (*note Case Changes::). You need a case table if you are using a
7044 language which has letters other than the standard ASCII letters.
7046 A case table is a list of this form:
7048 (DOWNCASE UPCASE CANONICALIZE EQUIVALENCES)
7050 where each element is either `nil' or a string of length 256. The
7051 element DOWNCASE says how to map each character to its lower-case
7052 equivalent. The element UPCASE maps each character to its upper-case
7053 equivalent. If lower and upper case characters are in one-to-one
7054 correspondence, use `nil' for UPCASE; then XEmacs deduces the upcase
7055 table from DOWNCASE.
7057 For some languages, upper and lower case letters are not in
7058 one-to-one correspondence. There may be two different lower case
7059 letters with the same upper case equivalent. In these cases, you need
7060 to specify the maps for both directions.
7062 The element CANONICALIZE maps each character to a canonical
7063 equivalent; any two characters that are related by case-conversion have
7064 the same canonical equivalent character.
7066 The element EQUIVALENCES is a map that cyclicly permutes each
7067 equivalence class (of characters with the same canonical equivalent).
7068 (For ordinary ASCII, this would map `a' into `A' and `A' into `a', and
7069 likewise for each set of equivalent characters.)
7071 When you construct a case table, you can provide `nil' for
7072 CANONICALIZE; then Emacs fills in this string from UPCASE and DOWNCASE.
7073 You can also provide `nil' for EQUIVALENCES; then Emacs fills in this
7074 string from CANONICALIZE. In a case table that is actually in use,
7075 those components are non-`nil'. Do not try to specify EQUIVALENCES
7076 without also specifying CANONICALIZE.
7078 Each buffer has a case table. XEmacs also has a "standard case
7079 table" which is copied into each buffer when you create the buffer.
7080 Changing the standard case table doesn't affect any existing buffers.
7082 Here are the functions for working with case tables:
7084 -- Function: case-table-p object
7085 This predicate returns non-`nil' if OBJECT is a valid case table.
7087 -- Function: set-standard-case-table case-table
7088 This function makes CASE-TABLE the standard case table, so that it
7089 will apply to any buffers created subsequently.
7091 -- Function: standard-case-table
7092 This returns the standard case table.
7094 -- Function: current-case-table &optional buffer
7095 This function returns the case table of BUFFER, which defaults to
7098 -- Function: set-case-table case-table
7099 This sets the current buffer's case table to CASE-TABLE.
7101 The following three functions are convenient subroutines for packages
7102 that define non-ASCII character sets. They modify a string
7103 DOWNCASE-TABLE provided as an argument; this should be a string to be
7104 used as the DOWNCASE part of a case table. They also modify the
7105 standard syntax table. *Note Syntax Tables::.
7107 -- Function: set-case-syntax-pair uc lc downcase-table
7108 This function specifies a pair of corresponding letters, one upper
7109 case and one lower case.
7111 -- Function: set-case-syntax-delims l r downcase-table
7112 This function makes characters L and R a matching pair of
7113 case-invariant delimiters.
7115 -- Function: set-case-syntax char syntax downcase-table
7116 This function makes CHAR case-invariant, with syntax SYNTAX.
7118 -- Command: describe-buffer-case-table
7119 This command displays a description of the contents of the current
7120 buffer's case table.
7122 You can load the library `iso-syntax' to set up the standard syntax
7123 table and define a case table for the 8-bit ISO Latin 1 character set.
7126 File: lispref.info, Node: Char Tables, Prev: Case Tables, Up: Strings and Characters
7128 10.13 The Char Table
7129 ====================
7131 A char table is a table that maps characters (or ranges of characters)
7132 to values. Char tables are specialized for characters, only allowing
7133 particular sorts of ranges to be assigned values. Although this loses
7134 in generality, it makes for extremely fast (constant-time) lookups, and
7135 thus is feasible for applications that do an extremely large number of
7136 lookups (e.g. scanning a buffer for a character in a particular syntax,
7137 where a lookup in the syntax table must occur once per character).
7139 Note that char tables as a primitive type, and all of the functions
7140 in this section, exist only in XEmacs 20. In XEmacs 19, char tables are
7141 generally implemented using a vector of 256 elements.
7143 When MULE support exists, the types of ranges that can be assigned
7150 * a single row in a two-octet charset
7152 * a single character
7154 When MULE support is not present, the types of ranges that can be
7159 * a single character
7161 -- Function: char-table-p object
7162 This function returns non-`nil' if OBJECT is a char table.
7166 * Char Table Types:: Char tables have different uses.
7167 * Working With Char Tables:: Creating and working with char tables.
7170 File: lispref.info, Node: Char Table Types, Next: Working With Char Tables, Up: Char Tables
7172 10.13.1 Char Table Types
7173 ------------------------
7175 Each char table type is used for a different purpose and allows
7176 different sorts of values. The different char table types are
7179 Used for category tables, which specify the regexp categories that
7180 a character is in. The valid values are `nil' or a bit vector of
7181 95 elements. Higher-level Lisp functions are provided for working
7182 with category tables. Currently categories and category tables
7183 only exist when MULE support is present.
7186 A generalized char table, for mapping from one character to
7187 another. Used for case tables, syntax matching tables,
7188 `keyboard-translate-table', etc. The valid values are characters.
7191 An even more generalized char table, for mapping from a character
7195 Used for display tables, which specify how a particular character
7196 is to appear when displayed. #### Not yet implemented.
7199 Used for syntax tables, which specify the syntax of a particular
7200 character. Higher-level Lisp functions are provided for working
7201 with syntax tables. The valid values are integers.
7203 -- Function: char-table-type char-table
7204 This function returns the type of char table CHAR-TABLE.
7206 -- Function: char-table-type-list
7207 This function returns a list of the recognized char table types.
7209 -- Function: valid-char-table-type-p type
7210 This function returns `t' if TYPE if a recognized char table type.
7213 File: lispref.info, Node: Working With Char Tables, Prev: Char Table Types, Up: Char Tables
7215 10.13.2 Working With Char Tables
7216 --------------------------------
7218 -- Function: make-char-table type
7219 This function makes a new, empty char table of type TYPE. TYPE
7220 should be a symbol, one of `char', `category', `display',
7221 `generic', or `syntax'.
7223 -- Function: put-char-table range value char-table
7224 This function sets the value for chars in RANGE to be VALUE in
7227 RANGE specifies one or more characters to be affected and should be
7228 one of the following:
7230 * `t' (all characters are affected)
7232 * A charset (only allowed when MULE support is present)
7234 * A vector of two elements: a two-octet charset and a row number
7235 (only allowed when MULE support is present)
7237 * A single character
7239 VALUE must be a value appropriate for the type of CHAR-TABLE.
7241 -- Function: get-char-table character char-table
7242 This function finds the value for CHARACTER in CHAR-TABLE.
7244 -- Function: get-range-char-table range char-table &optional multi
7245 This function finds the value for a range in CHAR-TABLE. If there
7246 is more than one value, MULTI is returned (defaults to `nil').
7248 -- Function: reset-char-table char-table
7249 This function resets CHAR-TABLE to its default state.
7251 -- Function: map-char-table function char-table &optional range
7252 This function maps FUNCTION over entries in CHAR-TABLE, calling it
7253 with two args, each key and value in the table.
7255 RANGE specifies a subrange to map over and is in the same format
7256 as the RANGE argument to `put-range-table'. If omitted or `t', it
7257 defaults to the entire table.
7259 -- Function: valid-char-table-value-p value char-table-type
7260 This function returns non-`nil' if VALUE is a valid value for
7263 -- Function: check-valid-char-table-value value char-table-type
7264 This function signals an error if VALUE is not a valid value for
7268 File: lispref.info, Node: Lists, Next: Sequences Arrays Vectors, Prev: Strings and Characters, Up: Top
7273 A "list" represents a sequence of zero or more elements (which may be
7274 any Lisp objects). The important difference between lists and vectors
7275 is that two or more lists can share part of their structure; in
7276 addition, you can insert or delete elements in a list without copying
7281 * Cons Cells:: How lists are made out of cons cells.
7282 * Lists as Boxes:: Graphical notation to explain lists.
7283 * List-related Predicates:: Is this object a list? Comparing two lists.
7284 * List Elements:: Extracting the pieces of a list.
7285 * Building Lists:: Creating list structure.
7286 * Modifying Lists:: Storing new pieces into an existing list.
7287 * Sets And Lists:: A list can represent a finite mathematical set.
7288 * Association Lists:: A list can represent a finite relation or mapping.
7289 * Property Lists:: A different way to represent a finite mapping.
7290 * Weak Lists:: A list with special garbage-collection behavior.
7293 File: lispref.info, Node: Cons Cells, Next: Lists as Boxes, Up: Lists
7295 11.1 Lists and Cons Cells
7296 =========================
7298 Lists in Lisp are not a primitive data type; they are built up from
7299 "cons cells". A cons cell is a data object that represents an ordered
7300 pair. It records two Lisp objects, one labeled as the CAR, and the
7301 other labeled as the CDR. These names are traditional; see *Note Cons
7302 Cell Type::. CDR is pronounced "could-er."
7304 A list is a series of cons cells chained together, one cons cell per
7305 element of the list. By convention, the CARs of the cons cells are the
7306 elements of the list, and the CDRs are used to chain the list: the CDR
7307 of each cons cell is the following cons cell. The CDR of the last cons
7308 cell is `nil'. This asymmetry between the CAR and the CDR is entirely
7309 a matter of convention; at the level of cons cells, the CAR and CDR
7310 slots have the same characteristics.
7312 Because most cons cells are used as part of lists, the phrase "list
7313 structure" has come to mean any structure made out of cons cells.
7315 The symbol `nil' is considered a list as well as a symbol; it is the
7316 list with no elements. For convenience, the symbol `nil' is considered
7317 to have `nil' as its CDR (and also as its CAR).
7319 The CDR of any nonempty list L is a list containing all the elements
7320 of L except the first.
7323 File: lispref.info, Node: Lists as Boxes, Next: List-related Predicates, Prev: Cons Cells, Up: Lists
7325 11.2 Lists as Linked Pairs of Boxes
7326 ===================================
7328 A cons cell can be illustrated as a pair of boxes. The first box
7329 represents the CAR and the second box represents the CDR. Here is an
7330 illustration of the two-element list, `(tulip lily)', made from two
7333 --------------- ---------------
7334 | car | cdr | | car | cdr |
7335 | tulip | o---------->| lily | nil |
7337 --------------- ---------------
7339 Each pair of boxes represents a cons cell. Each box "refers to",
7340 "points to" or "contains" a Lisp object. (These terms are synonymous.)
7341 The first box, which is the CAR of the first cons cell, contains the
7342 symbol `tulip'. The arrow from the CDR of the first cons cell to the
7343 second cons cell indicates that the CDR of the first cons cell points
7344 to the second cons cell.
7346 The same list can be illustrated in a different sort of box notation
7350 |___|___|--> |___|___|--> nil
7355 Here is a more complex illustration, showing the three-element list,
7356 `((pine needles) oak maple)', the first element of which is a
7359 ___ ___ ___ ___ ___ ___
7360 |___|___|--> |___|___|--> |___|___|--> nil
7366 --> |___|___|--> |___|___|--> nil
7369 --> pine --> needles
7371 The same list represented in the first box notation looks like this:
7373 -------------- -------------- --------------
7374 | car | cdr | | car | cdr | | car | cdr |
7375 | o | o------->| oak | o------->| maple | nil |
7377 -- | --------- -------------- --------------
7380 | -------------- ----------------
7381 | | car | cdr | | car | cdr |
7382 ------>| pine | o------->| needles | nil |
7384 -------------- ----------------
7386 *Note Cons Cell Type::, for the read and print syntax of cons cells
7387 and lists, and for more "box and arrow" illustrations of lists.
7390 File: lispref.info, Node: List-related Predicates, Next: List Elements, Prev: Lists as Boxes, Up: Lists
7392 11.3 Predicates on Lists
7393 ========================
7395 The following predicates test whether a Lisp object is an atom, is a
7396 cons cell or is a list, or whether it is the distinguished object
7397 `nil'. (Many of these predicates can be defined in terms of the
7398 others, but they are used so often that it is worth having all of them.)
7400 -- Function: consp object
7401 This function returns `t' if OBJECT is a cons cell, `nil'
7402 otherwise. `nil' is not a cons cell, although it _is_ a list.
7404 -- Function: atom object
7405 This function returns `t' if OBJECT is an atom, `nil' otherwise.
7406 All objects except cons cells are atoms. The symbol `nil' is an
7407 atom and is also a list; it is the only Lisp object that is both.
7409 (atom OBJECT) == (not (consp OBJECT))
7411 -- Function: listp object
7412 This function returns `t' if OBJECT is a cons cell or `nil'.
7413 Otherwise, it returns `nil'.
7420 -- Function: nlistp object
7421 This function is the opposite of `listp': it returns `t' if OBJECT
7422 is not a list. Otherwise, it returns `nil'.
7424 (listp OBJECT) == (not (nlistp OBJECT))
7426 -- Function: null object
7427 This function returns `t' if OBJECT is `nil', and returns `nil'
7428 otherwise. This function is identical to `not', but as a matter
7429 of clarity we use `null' when OBJECT is considered a list and
7430 `not' when it is considered a truth value (see `not' in *Note
7431 Combining Conditions::).
projects / chise / xemacs-chise.git / blob