SXEmacs Lisp Reference Manual

Next: Copying, Previous: (dir), Up: (dir)

Copying: Conditions for copying and changing SXEmacs.
Introduction: Introduction and conventions used.
Packaging: Lisp library administrative infrastructure.
Lisp Data Types: Data types of objects in SXEmacs Lisp.
Numbers: Numbers and arithmetic functions.
Strings and Characters: Strings, and functions that work on them.
Lists: Lists, cons cells, and related functions.
Sequences Arrays Vectors: Lists, strings and vectors are called sequences. Certain functions act on any kind of sequence. The description of vectors is here as well.
Symbols: Symbols represent names, uniquely.
Evaluation: How Lisp expressions are evaluated.
Control Structures: Conditionals, loops, nonlocal exits.
Variables: Using symbols in programs to stand for values.
Functions and Commands: A function is a Lisp program that can be invoked from other functions.
Macros: Macros are a way to extend the Lisp language.
Customization: Writing customization declarations.
Loading: Reading files of Lisp code into Lisp.
Byte Compilation: Compilation makes programs run faster.
Debugging: Tools and tips for debugging Lisp programs.
Read and Print: Converting Lisp objects to text and back.
Minibuffers: Using the minibuffer to read input.
Command Loop: How the editor command loop works, and how you can call its subroutines.
Keymaps: Defining the bindings from keys to commands.
Menus: Defining pull-down and pop-up menus.
Dialog Boxes: Creating dialog boxes.
Toolbar: Controlling the toolbar.
Gutter: Controlling the gutter.
Scrollbars: Controlling the scrollbars.
Drag and Drop: Generic API to inter-application communication via specific protocols.
Modes: Defining major and minor modes.
Documentation: Writing and using documentation strings.
Files: Accessing files.
Backups and Auto-Saving: Controlling how backups and auto-save files are made.
Buffers: Creating and using buffer objects.
Windows: Manipulating windows and displaying buffers.
Frames: Making multiple X windows.
Consoles and Devices: Opening frames on multiple TTY's or X displays.
Positions: Buffer positions and motion functions.
Markers: Markers represent positions and update automatically when the text is changed.
Text: Examining and changing text in buffers.
Searching and Matching: Searching buffers for strings or regexps.
Syntax Tables: The syntax table controls word and list parsing.
Abbrevs: How Abbrev mode works, and its data structures.
Extents: Extents are regions of text with particular display characteristics.
Specifiers: How faces and glyphs are specified.
Faces and Window-System Objects A face is a set of display characteristics specifying how text is to be displayed.
Glyphs: General interface to pixmaps displayed in a buffer or frame.
Annotations: Higher-level interface to glyphs in a buffer.
Display: Parameters controlling screen usage. The bell. Waiting for input.
Media: Handling media streams (audio and video).
Hash Tables: Fast data structures for mappings.
Range Tables: Keeping track of ranges of numbers.
Databases: An interface to standard DBM and DB databases.
Processes: Running and communicating with subprocesses.
System Interface: Getting the user id, system type, environment variables, and other such things.
X-Windows: Functions specific to the X Window System.
ToolTalk Support: Interfacing with the ToolTalk message service.
LDAP Support: Interfacing with the Lightweight Directory Access Protocol.
PostgreSQL Support: Interfacing to the PostgreSQL libpq library.
OpenSSL Support: Interfacing to the OpenSSL libcrypto/libssl libs
Enhanced Number Types: Using advanced numerical and mathematical features
Internationalization: How Emacs supports different languages and cultural conventions.
Foreign Functions: Accessing functions in external libraries from with SXEmacs lisp.
MULE: Specifics of the Asian-language support.

Appendices

Tips: Advice for writing Lisp programs.
Building SXEmacs and Object Allocation Behind-the-scenes information about SXEmacs.
Standard Errors: List of all error symbols.
Standard Buffer-Local Variables: List of variables local in all buffers.
Standard Keymaps: List of standard keymaps.
Standard Hooks: List of standard hook variables.
Index: Index including concepts, functions, variables, and other terms.

--- The Detailed Node Listing ---

Here are other nodes that are inferiors of those already listed, mentioned here so you can get to them in one step:

Introduction

Conventions

Some Terms: Explanation of terms we use in this manual.
nil and t: How the symbols nil and t are used.
Evaluation Notation: The format we use for examples of evaluation.
Printing Notation: The format we use for examples that print output.
Error Messages: The format we use for examples of errors.
Buffer Text Notation: The format we use for buffer contents in examples.
Format of Descriptions: Notation for describing functions, variables, etc.

Format of Descriptions

Packaging

Package Overview

The Library Maintainer's View

Creating Packages

Lisp Data Types

Programming Types

Integer Type: Numbers without fractional parts.
Floating Point Type: Numbers with fractional parts and with a large range.
Character Type: The representation of letters, numbers and control characters.
Sequence Type: Both lists and arrays are classified as sequences.
Cons Cell Type: Cons cells, and lists (which are made from cons cells).
Array Type: Arrays include strings and vectors.
String Type: An (efficient) array of characters.
Vector Type: One-dimensional arrays.
Symbol Type: A multi-use object that refers to a function, variable, property list, or itself.
Function Type: A piece of executable code you can call from elsewhere.
Macro Type: A method of expanding an expression into another expression, more fundamental but less pretty.
Primitive Function Type: A function written in C, callable from Lisp.
Compiled-Function Type: A function written in Lisp, then compiled.
Autoload Type: A type used for automatically loading seldom-used functions.

Cons Cell Type

Editing Types

Numbers

Integer Basics: Representation and range of integers.
Float Basics: Representation and range of floating point.
Predicates on Numbers: Testing for numbers.
Comparison of Numbers: Equality and inequality predicates.
Arithmetic Operations: How to add, subtract, multiply and divide.
Bitwise Operations: Logical and, or, not, shifting.
Numeric Conversions: Converting float to integer and vice versa.
Math Functions: Trig, exponential and logarithmic functions.
Random Numbers: Obtaining random integers, predictable or not.

Strings and Characters

String Basics: Basic properties of strings and characters.
Predicates for Strings: Testing whether an object is a string or char.
Creating Strings: Functions to allocate new strings.
Predicates for Characters: Testing whether an object is a character.
Character Codes: Each character has an equivalent integer.
Text Comparison: Comparing characters or strings.
String Conversion: Converting characters or strings and vice versa.
Modifying Strings: Changing characters in a string.
String Properties: Additional information attached to strings.
Formatting Strings: format: SXEmacs's analog of printf.
Character Case: Case conversion functions.
Char Tables: Mapping from characters to Lisp objects.
Case Tables: Customizing case conversion.

Lists

Cons Cells: How lists are made out of cons cells.
Lists as Boxes: Graphical notation to explain lists.
List-related Predicates: Is this object a list? Comparing two lists.
List Elements: Extracting the pieces of a list.
Building Lists: Creating list structure.
Modifying Lists: Storing new pieces into an existing list.
Sets And Lists: A list can represent a finite mathematical set.
Association Lists: A list can represent a finite relation or mapping.
Property Lists: A different way to represent a finite mapping.
Weak Lists: A list with special garbage-collection behavior.
DL-Lists: A doubly-linked list implementation.
Bloom Filters: A special set type with anonymous membership.

Modifying Existing List Structure

Sequences, Arrays, and Vectors

Symbols

Evaluation

Kinds of Forms

Self-Evaluating Forms: Forms that evaluate to themselves.
Symbol Forms: Symbols evaluate as variables.
Classifying Lists: How to distinguish various sorts of list forms.
Function Forms: Forms that call functions.
Macro Forms: Forms that call macros.
Special Forms: ``Special forms'' are idiosyncratic primitives, most of them extremely important.
Autoloading: Functions set up to load files containing their real definitions.

Control Structures

Nonlocal Exits

Errors

Variables

Global Variables: Variable values that exist permanently, everywhere.
Constant Variables: Certain "variables" have values that never change.
Local Variables: Variable values that exist only temporarily.
Void Variables: Symbols that lack values.
Defining Variables: A definition says a symbol is used as a variable.
Accessing Variables: Examining values of variables whose names are known only at run time.
Setting Variables: Storing new values in variables.
Variable Scoping: How Lisp chooses among local and global values.
Buffer-Local Variables: Variable values in effect only in one buffer.

Scoping Rules for Variable Bindings

Buffer-Local Variables

Functions

What Is a Function: Lisp functions vs primitives; terminology.
Lambda Expressions: How functions are expressed as Lisp objects.
Function Names: A symbol can serve as the name of a function.
Defining Functions: Lisp expressions for defining functions.
Calling Functions: How to use an existing function.
Mapping Functions: Applying a function to each element of a list, etc.
Anonymous Functions: Lambda-expressions are functions with no names.
Function Cells: Accessing or setting the function definition of a symbol.
Related Topics: Cross-references to specific Lisp primitives that have a special bearing on how functions work.

Lambda Expressions

Macros

Byte Compilation

Speed of Byte-Code: An example of speedup from byte compilation.
Compilation Functions: Byte compilation functions.
Docs and Compilation: Dynamic loading of documentation strings.
Dynamic Loading: Dynamic loading of individual functions.
Eval During Compile: Code to be evaluated when you compile.
Compiled-Function Objects: The data type used for byte-compiled functions.
Disassembly: Disassembling byte-code; how to read byte-code.
Different Behaviour: When compiled code gives different results.

Debugging Lisp Programs

The Lisp Debugger

Debugging Invalid Lisp Syntax

Reading and Printing Lisp Objects

Minibuffers

Completion

Basic Completion: Low-level functions for completing strings. (These are too low level to use the minibuffer.)
Minibuffer Completion: Invoking the minibuffer with completion.
Completion Commands: Minibuffer commands that do completion.
High-Level Completion: Convenient special cases of completion (reading buffer name, file name, etc.)
Reading File Names: Using completion to read file names.
Programmed Completion: Finding the completions for a given file name.

Command Loop

Command Overview: How the command loop reads commands.
Defining Commands: Specifying how a function should read arguments.
Interactive Call: Calling a command, so that it will read arguments.
Command Loop Info: Variables set by the command loop for you to examine.
Events: What input looks like when you read it.
Reading Input: How to read input events from the keyboard or mouse.
Waiting: Waiting for user input or elapsed time.
Quitting: How C-g works. How to catch or defer quitting.
Prefix Command Arguments: How the commands to set prefix args work.
Recursive Editing: Entering a recursive edit, and why you usually shouldn't.
Disabling Commands: How the command loop handles disabled commands.
Command History: How the command history is set up, and how accessed.
Keyboard Macros: How keyboard macros are implemented.

Defining Commands

Events

Event Types: Events come in different types.
Event Contents: What the contents of each event type are.
Event Predicates: Querying whether an event is of a particular type.
Accessing Mouse Event Positions Determining where a mouse event occurred, and over what.
Accessing Other Event Info: Accessing non-positional event info.
Working With Events: Creating, copying, and destroying events.
Converting Events: Converting between events, keys, and characters.

Accessing Mouse Event Positions

Reading Input

Keymaps

Keymap Terminology: Definitions of terms pertaining to keymaps.
Format of Keymaps: What a keymap looks like as a Lisp object.
Creating Keymaps: Functions to create and copy keymaps.
Inheritance and Keymaps: How one keymap can inherit the bindings of another keymap.
Key Sequences: How to specify key sequences.
Prefix Keys: Defining a key with a keymap as its definition.
Active Keymaps: Each buffer has a local keymap to override the standard (global) bindings. Each minor mode can also override them.
Key Lookup: How extracting elements from keymaps works.
Functions for Key Lookup: How to request key lookup.
Changing Key Bindings: Redefining a key in a keymap.
Key Binding Commands: Interactive interfaces for redefining keys.
Scanning Keymaps: Looking through all keymaps, for printing help.
Other Keymap Functions: Miscellaneous keymap functions.

Menus

Dialog Boxes

Toolbar

Gutter

Scrollbars

Major and Minor Modes

Major Modes

Minor Modes

Modeline Format

Documentation

Files

Visiting Files: Reading files into Emacs buffers for editing.
Saving Buffers: Writing changed buffers back into files.
Reading from Files: Reading files into other buffers.
Writing to Files: Writing new files from parts of buffers.
File Locks: Locking and unlocking files, to prevent simultaneous editing by two people.
Information about Files: Testing existence, accessibility, size of files.
Contents of Directories: Getting a list of the files in a directory.
Changing File Attributes: Renaming files, changing protection, etc.
File Names: Decomposing and expanding file names.

Visiting Files

Information about Files

File Names

File Name Components: The directory part of a file name, and the rest.
Directory Names: A directory's name as a directory is different from its name as a file.
Relative File Names: Some file names are relative to a current directory.
File Name Expansion: Converting relative file names to absolute ones.
Unique File Names: Generating names for temporary files.
File Name Completion: Finding the completions for a given file name.

Backups and Auto-Saving

Backup Files

Buffers

Buffer Basics: What is a buffer?
Buffer Names: Accessing and changing buffer names.
Buffer File Name: The buffer file name indicates which file is visited.
Buffer Modification: A buffer is modified if it needs to be saved.
Modification Time: Determining whether the visited file was changed ``behind SXEmacs's back''.
Read Only Buffers: Modifying text is not allowed in a read-only buffer.
The Buffer List: How to look at all the existing buffers.
Creating Buffers: Functions that create buffers.
Killing Buffers: Buffers exist until explicitly killed.
Current Buffer: Designating a buffer as current so primitives will access its contents.

Windows

Basic Windows: Basic information on using windows.
Splitting Windows: Splitting one window into two windows.
Deleting Windows: Deleting a window gives its space to other windows.
Selecting Windows: The selected window is the one that you edit in.
Cyclic Window Ordering: Moving around the existing windows.
Buffers and Windows: Each window displays the contents of a buffer.
Displaying Buffers: Higher-lever functions for displaying a buffer and choosing a window for it.
Window Point: Each window has its own location of point.
Window Start: The display-start position controls which text is on-screen in the window.
Vertical Scrolling: Moving text up and down in the window.
Horizontal Scrolling: Moving text sideways on the window.
Size of Window: Accessing the size of a window.
Resizing Windows: Changing the size of a window.
Window Configurations: Saving and restoring the state of the screen.

Frames

Creating Frames: Creating additional frames.
Frame Properties: Controlling frame size, position, font, etc.
Frame Titles: Automatic updating of frame titles.
Deleting Frames: Frames last until explicitly deleted.
Finding All Frames: How to examine all existing frames.
Frames and Windows: A frame contains windows; display of text always works through windows.
Minibuffers and Frames: How a frame finds the minibuffer to use.
Input Focus: Specifying the selected frame.
Visibility of Frames: Frames may be visible or invisible, or icons.
Raising and Lowering: Raising a frame makes it hide other X windows; lowering it makes the others hide them.
Frame Hooks: Hooks for customizing frame behavior.

Positions

Motion

Markers

Overview of Markers: The components of a marker, and how it relocates.
Predicates on Markers: Testing whether an object is a marker.
Creating Markers: Making empty markers or markers at certain places.
Information from Markers: Finding the marker's buffer or character position.
Changing Markers: Moving the marker to a new buffer or position.
The Mark: How ``the mark'' is implemented with a marker.
The Region: How to access ``the region''.

Text

Near Point: Examining text in the vicinity of point.
Buffer Contents: Examining text in a general fashion.
Comparing Text: Comparing substrings of buffers.
Insertion: Adding new text to a buffer.
Commands for Insertion: User-level commands to insert text.
Deletion: Removing text from a buffer.
User-Level Deletion: User-level commands to delete text.
The Kill Ring: Where removed text sometimes is saved for later use.
Undo: Undoing changes to the text of a buffer.
Maintaining Undo: How to enable and disable undo information. How to control how much information is kept.
Filling: Functions for explicit filling.
Margins: How to specify margins for filling commands.
Auto Filling: How auto-fill mode is implemented to break lines.
Sorting: Functions for sorting parts of the buffer.
Columns: Computing horizontal positions, and using them.
Indentation: Functions to insert or adjust indentation.
Case Changes: Case conversion of parts of the buffer.
Text Properties: Assigning Lisp property lists to text characters.
Substitution: Replacing a given character wherever it appears.
Registers: How registers are implemented. Accessing the text or position stored in a register.
Transposition: Swapping two portions of a buffer.
Change Hooks: Supplying functions to be run when text is changed.

The Kill Ring

Indentation

Searching and Matching

String Search: Search for an exact match.
Regular Expressions: Describing classes of strings.
Regexp Search: Searching for a match for a regexp.
Match Data: Finding out which part of the text matched various parts of a regexp, after regexp search.
Saving Match Data: Saving and restoring this information.
Standard Regexps: Useful regexps for finding sentences, pages,...
Searching and Case: Case-independent or case-significant searching.

Regular Expressions

Syntax Tables

Syntax Descriptors

Abbrevs And Abbrev Expansion

Extents

Intro to Extents: Extents are regions over a buffer or string.
Creating and Modifying Extents Basic extent functions.
Extent Endpoints: Accessing and setting the bounds of an extent.
Finding Extents: Determining which extents are in an object.
Mapping Over Extents: More sophisticated functions for extent scanning.
Extent Properties: Extents have built-in and user-definable properties.
Detached Extents: Extents that are not in a buffer.
Extent Parents: Inheriting properties from another extent.
Duplicable Extents: Extents can be marked to be copied into strings.
Extents and Events: Extents can interact with the keyboard and mouse.
Atomic Extents: Treating a block of text as a single entity.

Specifiers

Introduction to Specifiers: Specifiers provide a clean way for display and other properties to vary (under user control) in a wide variety of contexts.
Specifiers In-Depth: Gory details about specifier innards.
Specifier Instancing: Instancing means obtaining the ``value'' of a specifier in a particular context.
Specifier Types: Specifiers come in different flavors.
Adding Specifications: Specifications control a specifier's ``value'' by giving conditions under which a particular value is valid.
Retrieving Specifications: Querying a specifier's specifications.
Specifier Instancing Functions Functions to instance a specifier.
Specifier Examples: Making all this stuff clearer.
Creating Specifiers: Creating specifiers for your own use.
Specifier Validation Functions Validating the components of a specifier.
Other Specification Functions Other ways of working with specifications.

Faces and Window-System Objects

Faces

Fonts

Colors

Glyphs

Images

Image Instances

Using Glyphs

Image Instances

Using Glyphs

Native GUI Widgets

Manipulating Glyphs

Annotations

SXEmacs Display

Refresh Screen: Clearing the screen and redrawing everything on it.
Truncation: Folding or wrapping long text lines.
The Echo Area: Where messages are displayed.
Selective Display: Hiding part of the buffer text.
Overlay Arrow: Display of an arrow to indicate position.
Temporary Displays: Displays that go away automatically.
Blinking: How SXEmacs shows the matching open parenthesis.
Usual Display: The usual conventions for displaying nonprinting chars.
Display Tables: How to specify other conventions.
Beeping: Audible signal to the user.

Media

Hash Tables

Range Tables

Processes

Subprocess Creation: Functions that start subprocesses.
Synchronous Processes: Details of using synchronous subprocesses.
Asynchronous Processes: Starting up an asynchronous subprocess.
Deleting Processes: Eliminating an asynchronous subprocess.
Process Information: Accessing run-status and other attributes.
Input to Processes: Sending input to an asynchronous subprocess.
Signals to Processes: Stopping, continuing or interrupting an asynchronous subprocess.
Output from Processes: Collecting output from an asynchronous subprocess.
Sentinels: Sentinels run when process run-status changes.
Network: Opening network connections.

Receiving Output from Processes

Operating System Interface

Starting Up SXEmacs

Getting out of SXEmacs

X-Windows

ToolTalk Support

LDAP Support

SXEmacs LDAP API

The Low-Level LDAP API

LDAP Internationalization

PostgreSQL Support

SXEmacs PostgreSQL libpq API

OpenSSL Support

SXEmacs OpenSSL API

Enhanced Number Types

Internationalization

MULE

Internationalization Terminology Definition of various internationalization terms.
Charsets: Sets of related characters.
MULE Characters: Working with characters in SXEmacs/MULE.
Composite Characters: Making new characters by overstriking other ones.
ISO 2022: An international standard for charsets and encodings.
Coding Systems: Ways of representing a string of chars using integers.
CCL: A special language for writing fast converters.
Category Tables: Subdividing charsets into groups.

Tips

Building SXEmacs and Object Allocation