-This is ../info/lispref.info, produced by makeinfo version 4.0 from
+This is ../info/lispref.info, produced by makeinfo version 4.6 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Sequence Functions, Next: Arrays, Up: Sequences Arrays Vectors
-
-Sequences
-=========
-
- In XEmacs Lisp, a "sequence" is either a list, a vector, a bit
-vector, or a string. The common property that all sequences have is
-that each is an ordered collection of elements. This section describes
-functions that accept any kind of sequence.
-
- - Function: sequencep object
- Returns `t' if OBJECT is a list, vector, bit vector, or string,
- `nil' otherwise.
-
- - Function: copy-sequence sequence
- Returns a copy of SEQUENCE. The copy is the same type of object
- as the original sequence, and it has the same elements in the same
- order.
-
- Storing a new element into the copy does not affect the original
- SEQUENCE, and vice versa. However, the elements of the new
- sequence are not copies; they are identical (`eq') to the elements
- of the original. Therefore, changes made within these elements, as
- found via the copied sequence, are also visible in the original
- sequence.
-
- If the sequence is a string with extents or text properties, the
- extents and text properties in the copy are also copied, not
- shared with the original. (This means that modifying the extents
- or text properties of the original will not affect the copy.)
- However, the actual values of the properties are shared. *Note
- Extents::, *Note Text Properties::.
-
- See also `append' in *Note Building Lists::, `concat' in *Note
- Creating Strings::, `vconcat' in *Note Vectors::, and `bvconcat'
- in *Note Bit Vectors::, for other ways to copy sequences.
-
- (setq bar '(1 2))
- => (1 2)
- (setq x (vector 'foo bar))
- => [foo (1 2)]
- (setq y (copy-sequence x))
- => [foo (1 2)]
+File: lispref.info, Node: Font Instance Size, Next: Font Instance Characteristics, Prev: Font Instance Names, Up: Fonts
+
+Font Instance Size
+------------------
+
+ - Function: x-font-size font
+ This function returns the nominal size of the given font. This is
+ done by parsing its name, so it's likely to lose. X fonts can be
+ specified (by the user) in either pixels or 10ths of points, and
+ this returns the first one it finds, so you have to decide which
+ units the returned value is measured in yourself ...
+
+ - Function: x-find-larger-font font &optional device
+ This function loads a new, slightly larger version of the given
+ font (or font name). Returns the font if it succeeds, `nil'
+ otherwise. If scalable fonts are available, this returns a font
+ which is 1 point larger. Otherwise, it returns the next larger
+ version of this font that is defined.
+
+ - Function: x-find-smaller-font font &optional device
+ This function loads a new, slightly smaller version of the given
+ font (or font name). Returns the font if it succeeds, `nil'
+ otherwise. If scalable fonts are available, this returns a font
+ which is 1 point smaller. Otherwise, it returns the next smaller
+ version of this font that is defined.
+
+\1f
+File: lispref.info, Node: Font Instance Characteristics, Next: Font Convenience Functions, Prev: Font Instance Size, Up: Fonts
+
+Font Instance Characteristics
+-----------------------------
+
+ - Function: font-instance-properties font-instance
+ This function returns the properties (an alist or `nil') of
+ FONT-INSTANCE.
+
+ - Function: x-make-font-bold font &optional device
+ Given an X font specification, this attempts to make a "bold" font.
+ If it fails, it returns `nil'.
+
+ - Function: x-make-font-unbold font &optional device
+ Given an X font specification, this attempts to make a non-bold
+ font. If it fails, it returns `nil'.
+
+ - Function: x-make-font-italic font &optional device
+ Given an X font specification, this attempts to make an "italic"
+ font. If it fails, it returns `nil'.
+
+ - Function: x-make-font-unitalic font &optional device
+ Given an X font specification, this attempts to make a non-italic
+ font. If it fails, it returns `nil'.
+
+ - Function: x-make-font-bold-italic font &optional device
+ Given an X font specification, this attempts to make a
+ "bold-italic" font. If it fails, it returns `nil'.
+
+\1f
+File: lispref.info, Node: Font Convenience Functions, Prev: Font Instance Characteristics, Up: Fonts
+
+Font Convenience Functions
+--------------------------
+
+ - Function: font-name font &optional domain
+ This function returns the name of the FONT in the specified
+ DOMAIN, if any. FONT should be a font specifier object and DOMAIN
+ is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `font-instance-name' to the result.
+
+ - Function: font-truename font &optional domain
+ This function returns the truename of the FONT in the specified
+ DOMAIN, if any. FONT should be a font specifier object and DOMAIN
+ is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `font-instance-truename' to the result.
+
+ - Function: font-properties font &optional domain
+ This function returns the properties of the FONT in the specified
+ DOMAIN, if any. FONT should be a font specifier object and DOMAIN
+ is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `font-instance-properties' to the result.
+
+\1f
+File: lispref.info, Node: Colors, Prev: Fonts, Up: Faces and Window-System Objects
+
+Colors
+======
+
+* Menu:
+
+* Color Specifiers:: Specifying how a color will appear.
+* Color Instances:: What a color specifier gets instanced as.
+* Color Instance Properties:: Properties of color instances.
+* Color Convenience Functions:: Convenience functions that automatically
+ instance and retrieve the properties
+ of a color specifier.
+
+\1f
+File: lispref.info, Node: Color Specifiers, Next: Color Instances, Up: Colors
+
+Color Specifiers
+----------------
+
+ - Function: color-specifier-p object
+ This function returns non-`nil' if OBJECT is a color specifier.
+
+ - Function: make-color-specifier spec-list
+ Return a new `color' specifier object with the given specification
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ a detailed description of how specifiers work.
+
+ Valid instantiators for color specifiers are:
+
+ * A string naming a color (e.g. under X this might be
+ "lightseagreen2" or "#F534B2").
+
+ * A color instance (use that instance directly if the device
+ matches, or use the string that generated it).
+
+ * A vector of no elements (only on TTY's; this means to set no
+ color at all, thus using the "natural" color of the
+ terminal's text).
+
+ * A vector of one or two elements: a face to inherit from, and
+ optionally a symbol naming which property of that face to
+ inherit, either `foreground' or `background' (if omitted,
+ defaults to the same property that this color specifier is
+ used for; if this specifier is not part of a face, the
+ instantiator would not be valid).
+
+ - Function: make-face-boolean-specifier spec-list
+ Return a new `face-boolean' specifier object with the given spec
+ list. SPEC-LIST can be a list of specifications (each of which is
+ a cons of a locale and a list of instantiators), a single
+ instantiator, or a list of instantiators. *Note Specifiers::, for
+ a detailed description of how specifiers work.
+
+ Valid instantiators for face-boolean specifiers are
+
+ * t or nil.
+
+ * A vector of two or three elements: a face to inherit from,
+ optionally a symbol naming the property of that face to
+ inherit from (if omitted, defaults to the same property that
+ this face-boolean specifier is used for; if this specifier is
+ not part of a face, the instantiator would not be valid), and
+ optionally a value which, if non-`nil', means to invert the
+ sense of the inherited property.
+
+
+\1f
+File: lispref.info, Node: Color Instances, Next: Color Instance Properties, Prev: Color Specifiers, Up: Colors
+
+Color Instances
+---------------
+
+A "color-instance object" is an object describing the way a color
+specifier is instanced in a particular domain. Functions such as
+`face-background-instance' return a color-instance object. For example,
+
+ (face-background-instance 'default (next-window))
+ => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
+
+ The color-instance object returned describes the way the background
+color of the `default' face is displayed in the next window after the
+selected one.
+
+ - Function: color-instance-p object
+ This function returns non-`nil' if OBJECT is a color-instance.
+
+\1f
+File: lispref.info, Node: Color Instance Properties, Next: Color Convenience Functions, Prev: Color Instances, Up: Colors
+
+Color Instance Properties
+-------------------------
+
+ - Function: color-instance-name color-instance
+ This function returns the name used to allocate COLOR-INSTANCE.
+
+ - Function: color-instance-rgb-components color-instance
+ This function returns a three element list containing the red,
+ green, and blue color components of COLOR-INSTANCE.
+
+ (color-instance-rgb-components
+ (face-background-instance 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Color Convenience Functions, Prev: Color Instance Properties, Up: Colors
+
+Color Convenience Functions
+---------------------------
+
+ - Function: color-name color &optional domain
+ This function returns the name of the COLOR in the specified
+ DOMAIN, if any. COLOR should be a color specifier object and
+ DOMAIN is normally a window and defaults to the selected window if
+ omitted. This is equivalent to using `specifier-instance' and
+ applying `color-instance-name' to the result.
+
+ - Function: color-rgb-components color &optional domain
+ This function returns the RGB components of the COLOR in the
+ specified DOMAIN, if any. COLOR should be a color specifier
+ object and DOMAIN is normally a window and defaults to the
+ selected window if omitted. This is equivalent to using
+ `specifier-instance' and applying `color-instance-rgb-components'
+ to the result.
+
+ (color-rgb-components (face-background 'default (next-window)))
+ => (65535 58596 46517)
+
+\1f
+File: lispref.info, Node: Glyphs, Next: Annotations, Prev: Faces and Window-System Objects, Up: Top
+
+Glyphs
+******
+
+A "glyph" is an object that is used for pixmaps, widgets and images of
+all sorts, as well as for things that "act" like pixmaps, such as
+non-textual strings ("annotations") displayed in a buffer or in the
+margins. It is used in begin-glyphs and end-glyphs attached to
+extents, marginal and textual annotations, overlay arrows
+(`overlay-arrow-*' variables), toolbar buttons, mouse pointers, frame
+icons, truncation and continuation markers, and the like. (Basically,
+any place there is an image or something that acts like an image, there
+will be a glyph object representing it.)
+
+ The actual image that is displayed (as opposed to its position or
+clipping) is defined by an "image specifier" object contained within
+the glyph. The separation between an image specifier object and a
+glyph object is made because the glyph includes other properties than
+just the actual image: e.g. the face it is displayed in (for text
+images), the alignment of the image (when it is in a buffer), etc.
+
+ - Function: glyphp object
+ This function returns `t' if OBJECT is a glyph.
+
+* Menu:
+
+* Glyph Functions:: Functions for working with glyphs.
+* Images:: Graphical images displayed in a frame.
+* Glyph Types:: Each glyph has a particular type.
+* Mouse Pointer:: Controlling the mouse pointer.
+* Redisplay Glyphs:: Glyphs controlling various redisplay functions.
+* Subwindows:: Inserting an externally-controlled subwindow
+ into a buffer.
+* Glyph Examples:: Examples of how to work with glyphs.
+
+\1f
+File: lispref.info, Node: Glyph Functions, Next: Images, Up: Glyphs
+
+Glyph Functions
+===============
+
+* Menu:
+
+* Creating Glyphs:: Creating new glyphs.
+* Glyph Properties:: Accessing and modifying a glyph's properties.
+* Glyph Convenience Functions::
+ Convenience functions for accessing particular
+ properties of a glyph.
+* Glyph Dimensions:: Determining the height, width, etc. of a glyph.
+
+\1f
+File: lispref.info, Node: Creating Glyphs, Next: Glyph Properties, Up: Glyph Functions
+
+Creating Glyphs
+---------------
+
+ - Function: make-glyph &optional spec-list type
+ This function creates a new glyph object of type TYPE.
+
+ SPEC-LIST is used to initialize the glyph's image. It is
+ typically an image instantiator (a string or a vector; *Note Image
+ Specifiers::), but can also be a list of such instantiators (each
+ one in turn is tried until an image is successfully produced), a
+ cons of a locale (frame, buffer, etc.) and an instantiator, a list
+ of such conses, or any other form accepted by
+ `canonicalize-spec-list'. *Note Specifiers::, for more
+ information about specifiers.
+
+ TYPE specifies the type of the glyph, which specifies in which
+ contexts the glyph can be used, and controls the allowable image
+ types into which the glyph's image can be instantiated. TYPE
+ should be one of `buffer' (used for glyphs in an extent, the
+ modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
+ for the mouse-pointer), or `icon' (used for a frame's icon), and
+ defaults to `buffer'. *Note Glyph Types::.
+
+ A glyph in XEmacs does *NOT* refer to a single unit of textual
+ display (the XEmacs term for this is "rune"), but rather is an
+ object encapsulating a graphical element, such as an image or
+ widget (an element such as a button or text field; "widget" is the
+ term for this under X Windows, and it's called a "control" under
+ MS Windows). This graphical element could appear in a buffer, a
+ margin, a gutter, or a toolbar, or as a mouse pointer or an icon,
+ for example.
+
+ Creating a glyph using `make-glyph' does not specify _where_ the
+ glyph will be used, but it does specify _what_ the glyph will look
+ like. In particular, SPEC-LIST is used to specify this, and it's
+ used to initialize the glyph's `image' property, which is an image
+ specifier. (Note that "image" as used in the context of a glyph's
+ `image' property or in the terms "image specifier", "image
+ instantiator", or "image instance" does not refer to what people
+ normally think of as an image (which in XEmacs is called a
+ "pixmap"), but to any graphical element--a pixmap, a widget, or
+ even a block of text, when used in the places that call for a
+ glyph.) The format of the SPEC-LIST is typically an image
+ instantiator (a string or a vector; *Note Image Specifiers::), but
+ can also be a list of such instantiators (each one in turn is
+ tried until an image is successfully produced), a cons of a locale
+ (frame, buffer, etc.) and an instantiator, a list of such conses,
+ or any other form accepted by `canonicalize-spec-list'. *Note
+ Specifiers::, for more information about specifiers.
+
+ If you're not familiar with specifiers, you should be in order to
+ understand how glyphs work. The clearest introduction to
+ specifiers is in the Lispref manual, available under Info. (Choose
+ Help->Info->Info Contents on the menubar or type C-h i.) You can
+ also see `make-specifier' for a capsule summary. What's important
+ to keep in mind is that a specifier lets you set a different value
+ for any particular buffer, window, frame, device, or console.
+ This allows for a great deal of flexibility; in particular, only
+ one global glyph needs to exist for a particular purpose (e.g. the
+ icon used to represent an iconified frame, the mouse pointer used
+ over particular areas of a frame, etc.), and in these cases you do
+ not create your own glyph, but rather modify the existing one.
+
+ As well as using SPEC-LIST to initialize the glyph, you can set
+ specifications using `set-glyph-image'. Note that, due to a
+ possibly questionable historical design decision, a glyph itself
+ is not actually a specifier, but rather is an object containing an
+ image specifier (as well as other, seldom-used properties).
+ Therefore, you cannot set or access specifications for the glyph's
+ image by directly using `set-specifier', `specifier-instance' or
+ the like on the glyph; instead use them on `(glyph-image GLYPH)'
+ or use the convenience functions `set-glyph-image',
+ `glyph-image-instance', and `glyph-image'.
+
+ Once you have created a glyph, you specify where it will be used as
+ follows:
+
+ * To insert a glyph into a buffer, create an extent in the
+ buffer and then use `set-extent-begin-glyph' or
+ `set-extent-end-glyph' to set a glyph to be displayed at the
+ corresponding edge of the extent. (It is common to create
+ zero-width extents for this purpose.)
+
+ * To insert a glyph into the left or right margin of a buffer,
+ first make sure the margin is visible by setting a value for
+ the specifiers `left-margin-width' or `right-margin-width'.
+ (Not strictly necessary when using margin glyphs with layout
+ policy `whitespace'.) Then follow the same procedure above
+ for inserting a glyph in a buffer, and then set a non-default
+ layout policy for the glyph using
+ `set-extent-begin-glyph-layout' or
+ `set-extent-end-glyph-layout'. Alternatively, use the
+ high-level annotations API (see `make-annotation'). (In point
+ of fact, you can also use the annotations API for glyphs in a
+ buffer, by setting a layout policy of `text'.)
+
+ * To insert a glyph into the modeline, just put the glyph
+ directly as one of the modeline elements. (Unfortunately you
+ can't currently put a begin glyph or end glyph on one of the
+ modeline extents--they're ignored.)
+
+ * To insert a glyph into a toolbar, specify it as part of a
+ toolbar instantiator (typically set on the specifier
+ `default-toolbar'). See `default-toolbar' for more
+ information. (Note that it is standard practice to use a
+ symbol in place of the glyph list in the toolbar
+ instantiator; the symbol is evalled to get the glyph list.
+ This facilitates both creating the toolbar instantiator and
+ modifying individual glyphs in a toolbar later on. For
+ example, you can change the way that the Mail toolbar button
+ looks by modifying the value of the variable
+ `toolbar-mail-icon' (in general, `toolbar-*-icon') and then
+ calling `(set-specifier-dirty-flag default-toolbar)'. (####
+ Unfortunately this doesn't quite work the way it should; the
+ change will appear in new frames, but not existing ones.
+
+ * To insert a glyph into a gutter, create or modify a gutter
+ instantiator (typically set on the specifier
+ `default-gutter'). Gutter instantiators consist of strings
+ or lists of strings, so to insert a glyph, create an extent
+ over the string, and use `set-extent-begin-glyph' or
+ `set-extent-end-glyph' to set a glyph to be displayed at the
+ corresponding edge of the extent, just like for glyphs in a
+ buffer.
+
+ * To use a glyph as the icon for a frame, you do not actually
+ create a new glyph; rather, you change the specifications for
+ the existing glyph `frame-icon-glyph'. (Remember that,
+ because of the specifier nature of glyphs, you can set
+ different values for any particular buffer or frame.)
+
+ * To use a glyph as the mouse pointer, in general you do not
+ create a new glyph, but rather you change the specifications
+ of various existing glyphs, such as `text-pointer-glyph' for
+ the pointer used over text, `modeline-pointer-glyph' for the
+ pointer used over the modeline, etc. Do an apropos over
+ `*-pointer-glyph' to find all of them. (Note also that you
+ can temporarily set the mouse pointer to some specific shape
+ by using `set-frame-pointer', which takes an image instance,
+ as obtained from calling `glyph-image-instance' on a glyph of
+ type `pointer' - either one of the above-mentioned variables
+ or one you created yourself. (See below for what it means to
+ create a glyph of type `pointer'.) This pointer will last
+ only until the next mouse motion event is processed or
+ certain other things happen, such as creating or deleting a
+ window. (In fact, the above-mentioned pointer glyph variables
+ are implemented as part of the default handler for mouse
+ motion events. If you want to customize this behavior, take a
+ look at `mode-motion-hook', or `mouse-motion-handler' if you
+ really want to get low-level.)
+
+ * To use a glyph to control the shape of miscellaneous
+ redisplay effects such as the truncation and continuation
+ markers, set the appropriate existing glyph variables, as for
+ icons and pointers above. See `continuation-glyph',
+ `control-arrow-glyph', `hscroll-glyph',
+ `invisible-text-glyph', `octal-escape-glyph', and
+ `truncation-glyph'. See also `overlay-arrow-string', an odd
+ redisplay leftover which can be set to a glyph you created,
+ and will cause the glyph to be displayed on top of the text
+ position specified in the marker stored in
+ `overlay-arrow-position'.
+
+ * To use a glyph in a display table (i.e. to control the
+ appearance of any individual character), create the
+ appropriate character glyphs and then set a specification for
+ the specifier `current-display-table', which controls the
+ appearance of characters. You can also set an overriding
+ display table for use with text displayed in a particular
+ face; see `set-face-display-table' and `make-display-table'.
+ #### Note: Display tables do not currently support general
+ Mule characters. They will be overhauled at some point to
+ support this and to provide other features required under
+ Mule.
+
+ * To use a glyph as the background pixmap of a face: Note that
+ the background pixmap of a face is actually an image
+ specifier - probably the only place in XEmacs where an image
+ specifier occurs outside of a glyph. Similarly to how the
+ glyph's image specifier works, you don't create your own
+ image specifier, but rather add specifications to the
+ existing one (using `set-face-background-pixmap'). Note that
+ the image instance that is generated in order to actually
+ display the background pixmap is of type `mono-pixmap',
+ meaning that it's a two-color image and the foreground and
+ background of the image get filled in with the corresponding
+ colors from the face.
+
+ It is extremely rare that you will ever have to specify a value for
+ TYPE, which should be one of `buffer' (used for glyphs in an
+ extent, the modeline, the toolbar, or elsewhere in a buffer),
+ `pointer' (used for the mouse-pointer), or `icon' (used for a
+ frame's icon), and defaults to `buffer'. The only cases where it
+ needs to be specified is when creating icon or pointer glyphs, and
+ in both cases the necessary glyphs have already been created at
+ startup and are accessed through the appropriate variables, e.g.
+ `text-pointer-glyph' (or in general, `*-pointer-glyph') and
+ `frame-icon-glyph'. *Note Glyph Types::.
+
+ - Function: make-glyph-internal &optional type
+ This function creates a new, uninitialized glyph of type TYPE.
+
+ - Function: make-pointer-glyph &optional spec-list
+ Return a new `pointer-glyph' object with the specification list
+ SPEC-LIST. This function is equivalent to calling `make-glyph'
+ with a TYPE of `pointer'.
+
+ It is extremely unlikely that you will ever need to create a
+ pointer glyph. Instead, you probably want to be calling
+ `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
+
+ - Function: make-icon-glyph &optional spec-list
+ Return a new `pointer-glyph' object with the specification list
+ SPEC-LIST. This function is equivalent to calling `make-glyph'
+ with a TYPE of `icon'.
+
+ It is extremely unlikely that you will ever need to create a
+ pointer glyph. Instead, you probably want to be calling
+ `set-glyph-image' on an existing glyph, e.g. `text-pointer-glyph'.
+
+\1f
+File: lispref.info, Node: Glyph Properties, Next: Glyph Convenience Functions, Prev: Creating Glyphs, Up: Glyph Functions
+
+Glyph Properties
+----------------
+
+Each glyph has a list of properties, which control all of the aspects of
+the glyph's appearance. The following symbols have predefined meanings:
+
+`image'
+ The image used to display the glyph.
+
+`baseline'
+ Percent above baseline that glyph is to be displayed. Only for
+ glyphs displayed inside of a buffer.
+
+`contrib-p'
+ Whether the glyph contributes to the height of the line it's on.
+ Only for glyphs displayed inside of a buffer.
+
+`face'
+ Face of this glyph (_not_ a specifier).
+
+ - Function: set-glyph-property glyph property value &optional locale
+ tag-set how-to-add
+ This function changes a property of a GLYPH.
+
+ For built-in properties, the actual value of the property is a
+ specifier and you cannot change this; but you can change the
+ specifications within the specifier, and that is what this
+ function will do. For user-defined properties, you can use this
+ function to either change the actual value of the property or, if
+ this value is a specifier, change the specifications within it.
+
+ If PROPERTY is a built-in property, the specifications to be added
+ to this property can be supplied in many different ways:
+
+ * If VALUE is a simple instantiator (e.g. a string naming a
+ pixmap filename) or a list of instantiators, then the
+ instantiator(s) will be added as a specification of the
+ property for the given LOCALE (which defaults to `global' if
+ omitted).
+
+ * If VALUE is a list of specifications (each of which is a cons
+ of a locale and a list of instantiators), then LOCALE must be
+ `nil' (it does not make sense to explicitly specify a locale
+ in this case), and specifications will be added as given.
+
+ * If VALUE is a specifier (as would be returned by
+ `glyph-property' if no LOCALE argument is given), then some
+ or all of the specifications in the specifier will be added
+ to the property. In this case, the function is really
+ equivalent to `copy-specifier' and LOCALE has the same
+ semantics (if it is a particular locale, the specification
+ for the locale will be copied; if a locale type,
+ specifications for all locales of that type will be copied;
+ if `nil' or `all', then all specifications will be copied).
+
+ HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
+ `append', `remove-tag-set-prepend', `remove-tag-set-append',
+ `remove-locale', `remove-locale-type', or `remove-all'. See
+ `copy-specifier' and `add-spec-to-specifier' for a description of
+ what each of these means. Most of the time, you do not need to
+ worry about this argument; the default behavior usually is fine.
+
+ In general, it is OK to pass an instance object (e.g. as returned
+ by `glyph-property-instance') as an instantiator in place of an
+ actual instantiator. In such a case, the instantiator used to
+ create that instance object will be used (for example, if you set
+ a font-instance object as the value of the `font' property, then
+ the font name used to create that object will be used instead).
+ If some cases, however, doing this conversion does not make sense,
+ and this will be noted in the documentation for particular types
+ of instance objects.
+
+ If PROPERTY is not a built-in property, then this function will
+ simply set its value if LOCALE is `nil'. However, if LOCALE is
+ given, then this function will attempt to add VALUE as the
+ instantiator for the given LOCALE, using `add-spec-to-specifier'.
+ If the value of the property is not a specifier, it will
+ automatically be converted into a `generic' specifier.
+
+ - Function: glyph-property glyph property &optional locale
+ This function returns GLYPH's value of the given PROPERTY.
+
+ If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
+ be returned. For built-in properties, this will be a specifier
+ object of a type appropriate to the property (e.g. a font or color
+ specifier). For other properties, this could be anything.
+
+ If LOCALE is supplied, then instead of returning the actual value,
+ the specification(s) for the given locale or locale type will be
+ returned. This will only work if the actual value of PROPERTY is
+ a specifier (this will always be the case for built-in properties,
+ but may or may not apply to user-defined properties). If the
+ actual value of PROPERTY is not a specifier, this value will
+ simply be returned regardless of LOCALE.
+
+ The return value will be a list of instantiators (e.g. vectors
+ specifying pixmap data), or a list of specifications, each of
+ which is a cons of a locale and a list of instantiators.
+ Specifically, if LOCALE is a particular locale (a buffer, window,
+ frame, device, or `global'), a list of instantiators for that
+ locale will be returned. Otherwise, if LOCALE is a locale type
+ (one of the symbols `buffer', `window', `frame', or `device'), the
+ specifications for all locales of that type will be returned.
+ Finally, if LOCALE is `all', the specifications for all locales of
+ all types will be returned.
+
+ The specifications in a specifier determine what the value of
+ PROPERTY will be in a particular "domain" or set of circumstances,
+ which is typically a particular Emacs window along with the buffer
+ it contains and the frame and device it lies within. The value is
+ derived from the instantiator associated with the most specific
+ locale (in the order buffer, window, frame, device, and `global')
+ that matches the domain in question. In other words, given a
+ domain (i.e. an Emacs window, usually), the specifier for PROPERTY
+ will first be searched for a specification whose locale is the
+ buffer contained within that window; then for a specification
+ whose locale is the window itself; then for a specification whose
+ locale is the frame that the window is contained within; etc. The
+ first instantiator that is valid for the domain (usually this
+ means that the instantiator is recognized by the device [i.e. the
+ X server or TTY device] that the domain is on). The function
+ `glyph-property-instance' actually does all this, and is used to
+ determine how to display the glyph.
+
+ - Function: glyph-property-instance glyph property &optional domain
+ default no-fallback
+ This function returns the instance of GLYPH's PROPERTY in the
+ specified DOMAIN.
+
+ Under most circumstances, DOMAIN will be a particular window, and
+ the returned instance describes how the specified property
+ actually is displayed for that window and the particular buffer in
+ it. Note that this may not be the same as how the property
+ appears when the buffer is displayed in a different window or
+ frame, or how the property appears in the same window if you
+ switch to another buffer in that window; and in those cases, the
+ returned instance would be different.
+
+ The returned instance is an image-instance object, and you can
+ query it using the appropriate image instance functions. For
+ example, you could use `image-instance-depth' to find out the
+ depth (number of color planes) of a pixmap displayed in a
+ particular window. The results might be different from the
+ results you would get for another window (perhaps the user
+ specified a different image for the frame that window is on; or
+ perhaps the same image was specified but the window is on a
+ different X server, and that X server has different color
+ capabilities from this one).
+
+ DOMAIN defaults to the selected window if omitted.
+
+ DOMAIN can be a frame or device, instead of a window. The value
+ returned for such a domain is used in special circumstances when a
+ more specific domain does not apply; for example, a frame value
+ might be used for coloring a toolbar, which is conceptually
+ attached to a frame rather than a particular window. The value is
+ also useful in determining what the value would be for a
+ particular window within the frame or device, if it is not
+ overridden by a more specific specification.
+
+ If PROPERTY does not name a built-in property, its value will
+ simply be returned unless it is a specifier object, in which case
+ it will be instanced using `specifier-instance'.
+
+ Optional arguments DEFAULT and NO-FALLBACK are the same as in
+ `specifier-instance'. *Note Specifiers::.
+
+ - Function: remove-glyph-property glyph property &optional locale
+ tag-set exact-p
+ This function removes a property from a glyph. For built-in
+ properties, this is analogous to `remove-specifier'. *Note
+ remove-specifier-p: Specifiers, for the meaning of the LOCALE,
+ TAG-SET, and EXACT-P arguments.
+
+\1f
+File: lispref.info, Node: Glyph Convenience Functions, Next: Glyph Dimensions, Prev: Glyph Properties, Up: Glyph Functions
+
+Glyph Convenience Functions
+---------------------------
+
+The following functions are provided for working with specific
+properties of a glyph. Note that these are exactly like calling the
+general functions described above and passing in the appropriate value
+for PROPERTY.
+
+ Remember that if you want to determine the "value" of a specific
+glyph property, you probably want to use the `*-instance' functions.
+For example, to determine whether a glyph contributes to its line
+height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
+latter will return a boolean specifier or a list of specifications, and
+you probably aren't concerned with these.)
+
+ - Function: glyph-image glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `image'. The return value will be an image specifier
+ if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-image glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `image'.
+
+ - Function: glyph-image-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's image in the given
+ DOMAIN, and is equivalent to calling `glyph-property-instance'
+ with a property of `image'. The return value will be an image
+ instance.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing how the image appears
+ in that particular window and buffer will be returned.
+
+ - Function: glyph-contrib-p glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `contrib-p'. The return value will be a boolean
+ specifier if LOCALE is `nil' or omitted; otherwise, it will be a
+ specification or list of specifications.
+
+ - Function: set-glyph-contrib-p glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `contrib-p'.
+
+ - Function: glyph-contrib-p-instance glyph &optional domain default
+ no-fallback
+ This function returns whether the glyph contributes to its line
+ height in the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `contrib-p'. The
+ return value will be either `nil' or `t'. (Normally DOMAIN will be
+ a window or `nil', meaning the selected window.)
+
+ - Function: glyph-baseline glyph &optional locale
+ This function is equivalent to calling `glyph-property' with a
+ property of `baseline'. The return value will be a specifier if
+ LOCALE is `nil' or omitted; otherwise, it will be a specification
+ or list of specifications.
+
+ - Function: set-glyph-baseline glyph spec &optional locale tag-set
+ how-to-add
+ This function is equivalent to calling `set-glyph-property' with a
+ property of `baseline'.
+
+ - Function: glyph-baseline-instance glyph &optional domain default
+ no-fallback
+ This function returns the instance of GLYPH's baseline value in
+ the given DOMAIN, and is equivalent to calling
+ `glyph-property-instance' with a property of `baseline'. The
+ return value will be an integer or `nil'.
+
+ Normally DOMAIN will be a window or `nil' (meaning the selected
+ window), and an instance object describing the baseline value
+ appears in that particular window and buffer will be returned.
+
+ - Function: glyph-face glyph
+ This function returns the face of GLYPH. (Remember, this is not a
+ specifier, but a simple property.)
+
+ - Function: set-glyph-face glyph face
+ This function changes the face of GLYPH to FACE.
+
+\1f
+File: lispref.info, Node: Glyph Dimensions, Prev: Glyph Convenience Functions, Up: Glyph Functions
+
+Glyph Dimensions
+----------------
+
+ - Function: glyph-width glyph &optional window
+ This function returns the width of GLYPH on WINDOW. This may not
+ be exact as it does not take into account all of the context that
+ redisplay will.
+
+ - Function: glyph-ascent glyph &optional window
+ This function returns the ascent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
+
+ - Function: glyph-descent glyph &optional window
+ This function returns the descent value of GLYPH on WINDOW. This
+ may not be exact as it does not take into account all of the
+ context that redisplay will.
+
+ - Function: glyph-height glyph &optional window
+ This function returns the height of GLYPH on WINDOW. (This is
+ equivalent to the sum of the ascent and descent values.) This may
+ not be exact as it does not take into account all of the context
+ that redisplay will.
+
+\1f
+File: lispref.info, Node: Images, Next: Glyph Types, Prev: Glyph Functions, Up: Glyphs
+
+Images
+======
+
+* Menu:
+
+* Image Specifiers:: Specifying how an image will appear.
+* Image Instantiator Conversion::
+ Conversion is applied to image instantiators
+ at the time they are added to an
+ image specifier or at the time they
+ are passed to `make-image-instance'.
+* Image Instances:: What an image specifier gets instanced as.
+
+\1f
+File: lispref.info, Node: Image Specifiers, Next: Image Instantiator Conversion, Up: Images
+
+Image Specifiers
+----------------
+
+An image specifier is used to describe the actual image of a glyph. It
+works like other specifiers (*note Specifiers::), in that it contains a
+number of specifications describing how the image should appear in a
+variety of circumstances. These specifications are called "image
+instantiators". When XEmacs wants to display the image, it instantiates
+the image into an "image instance". Image instances are their own
+primitive object type (similar to font instances and color instances),
+describing how the image appears in a particular domain. (On the other
+hand, image instantiators, which are just descriptions of how the image
+should appear, are represented using strings or vectors.)
+
+ - Function: image-specifier-p object
+ This function returns non-`nil' if OBJECT is an image specifier.
+ Usually, an image specifier results from calling `glyph-image' on
+ a glyph.
+
+ - Function: make-image-specifier spec-list
+ This function creates a new image specifier object and initializes
+ it according to SPEC-LIST. *Note Specifiers::.
+
+ Note that, in practice, you rarely, if ever, need to actually
+ create an image specifier! (This function exists mainly for
+ completeness.) Pretty much the only use for image specifiers is to
+ control how glyphs are displayed, and the image specifier
+ associated with a glyph (the `image' property of a glyph) is
+ created automatically when a glyph is created and need not (and
+ cannot, for that matter) ever be changed (*note Glyphs::). In
+ fact, the design decision to create a separate image specifier
+ type, rather than make glyphs themselves be specifiers, is
+ debatable--the other properties of glyphs are rarely used and could
+ conceivably have been incorporated into the glyph's instantiator.
+ The rarely used glyph types (buffer, pointer, icon) could also
+ have been incorporated into the instantiator.
+
+ Image instantiators come in many formats: `xbm', `xpm', `gif',
+`jpeg', etc. This describes the format of the data describing the
+image. The resulting image instances also come in many
+types--`mono-pixmap', `color-pixmap', `text', `pointer', etc. This
+refers to the behavior of the image and the sorts of places it can
+appear. (For example, a color-pixmap image has fixed colors specified
+for it, while a mono-pixmap image comes in two unspecified shades
+"foreground" and "background" that are determined from the face of the
+glyph or surrounding text; a text image appears as a string of text and
+has an unspecified foreground, background, and font; a pointer image
+behaves like a mono-pixmap image but can only be used as a mouse
+pointer [mono-pixmap images cannot be used as mouse pointers]; etc.) It
+is important to keep the distinction between image instantiator format
+and image instance type in mind. Typically, a given image instantiator
+format can result in many different image instance types (for example,
+`xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
+whereas `cursor-font' can be instanced only as `pointer'), and a
+particular image instance type can be generated by many different image
+instantiator formats (e.g. `color-pixmap' can be generated by `xpm',
+`gif', `jpeg', etc.).
+
+ *Note Image Instances::, for a more detailed discussion of image
+instance types.
+
+ An image instantiator should be a string or a vector of the form
+
+ `[FORMAT :KEYWORD VALUE ...]'
+
+ i.e. a format symbol followed by zero or more alternating
+keyword-value pairs. The "format" field should be a symbol, one of
+
+`nothing'
+ Don't display anything; no keywords are valid for this. Can only
+ be instanced as `nothing'.
+
+`string'
+ Display this image as a text string. Can only be instanced as
+ `text', although support for instancing as `mono-pixmap' should be
+ added.
+
+`formatted-string'
+ Display this image as a text string with replaceable fields,
+ similar to a modeline format string; not currently implemented.
+
+`xbm'
+ An X bitmap; only if X support was compiled into this XEmacs. Can
+ be instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`xpm'
+ An XPM pixmap; only if XPM support was compiled into this XEmacs.
+ Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
+ XPM is an add-on library for X that was designed to rectify the
+ shortcomings of the XBM format. Most implementations of X include
+ the XPM library as a standard part. If your vendor does not, it
+ is highly recommended that you download it and install it. You
+ can get it from the standard XEmacs FTP site, among other places.
+
+`xface'
+ An X-Face bitmap, used to encode people's faces in e-mail messages;
+ only if X-Face support was compiled into this XEmacs. Can be
+ instanced as `mono-pixmap', `color-pixmap', or `pointer'.
+
+`gif'
+ A GIF87 or GIF89 image; only if GIF support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. Note that XEmacs
+ includes GIF decoding functions as a standard part of it, so if
+ you have X support, you will normally have GIF support, unless you
+ explicitly disable it at configure time.
+
+`jpeg'
+ A JPEG-format image; only if JPEG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'. If you have the JPEG
+ libraries present on your system when XEmacs is built, XEmacs will
+ automatically detect this and use them, unless you explicitly
+ disable it at configure time.
+
+`png'
+ A PNG/GIF24 image; only if PNG support was compiled into this
+ XEmacs. Can be instanced as `color-pixmap'.
+
+`tiff'
+ A TIFF-format image; only if TIFF support was compiled into this
+ XEmacs.
+
+`cursor-font'
+ One of the standard cursor-font names, such as `watch' or
+ `right_ptr' under X. Under X, this is, more specifically, any of
+ the standard cursor names from appendix B of the Xlib manual [also
+ known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix. On
+ other window systems, the valid names will be specific to the type
+ of window system. Can only be instanced as `pointer'.
+
+`font'
+ A glyph from a font; i.e. the name of a font, and glyph index into
+ it of the form `FONT fontname index [[mask-font] mask-index]'.
+ Only if X support was compiled into this XEmacs. Currently can
+ only be instanced as `pointer', although this should probably be
+ fixed.
+
+`mswindows-resource'
+ An MS Windows pointer resource. Specifies a resource to retrieve
+ directly from the system (an OEM resource) or from a file,
+ particularly an executable file. If the resource is to be
+ retrieved from a file, use :file and optionally :resource-id.
+ Otherwise use :resource-id. Always specify :resource-type to
+ specify the type (cursor, bitmap or icon) of the resource.
+ Possible values for :resource-id are listed below. Can be
+ instanced as `pointer' or `color-pixmap'.
+
+`subwindow'
+ An embedded windowing system window. Can only be instanced as
+ `subwindow'.
+
+`button'
+ A button widget; either a push button, radio button or toggle
+ button. Can only be instanced as `widget'.
+
+`combo-box'
+ A drop list of selectable items in a widget, for editing text.
+ Can only be instanced as `widget'.
+
+`edit-field'
+ A text editing widget. Can only be instanced as `widget'.
+
+`label'
+ A static, text-only, widget; for displaying text. Can only be
+ instanced as `widget'.
+
+`layout'
+ A widget for controlling the positioning of children underneath it.
+ Through the use of nested layouts, a widget hierarchy can be
+ created which can have the appearance of any standard dialog box
+ or similar arrangement; all of this is counted as one "glyph" and
+ could appear in many of the places that expect a single glyph.
+ Can only be instanced as `widget'.
+
+`native-layout'
+ The native version of a layout widget. Can only be instanced as
+ `widget'.
+
+`progress-gauge'
+ A sliding widget, for showing progress. Can only be instanced as
+ `widget'.
+
+`tab-control'
+ A tab widget; a series of user selectable tabs. Can only be
+ instanced as `widget'.
+
+`tree-view'
+ A folding widget. Can only be instanced as `widget'.
+
+`scrollbar'
+ A scrollbar widget. Can only be instanced as `widget'.
+
+`autodetect'
+ XEmacs tries to guess what format the data is in. If X support
+ exists, the data string will be checked to see if it names a
+ filename. If so, and this filename contains XBM or XPM data, the
+ appropriate sort of pixmap or pointer will be created. [This
+ includes picking up any specified hotspot or associated mask
+ file.] Otherwise, if `pointer' is one of the allowable
+ image-instance types and the string names a valid cursor-font
+ name, the image will be created as a pointer. Otherwise, the
+ image will be displayed as text. If no X support exists, the
+ image will always be displayed as text.
+
+`inherit'
+ Inherit from the background-pixmap property of a face. Can only be
+ instanced as `mono-pixmap'.
+
+ The valid keywords are:
+
+`:data'
+ Inline data. For most formats above, this should be a string. For
+ XBM images, this should be a list of three elements: width,
+ height, and a string of bit data. This keyword is not valid for
+ instantiator format `nothing'.
+
+`:file'
+ Data is contained in a file. The value is the name of this file.
+ If both `:data' and `:file' are specified, the image is created
+ from what is specified in `:data' and the string in `:file'
+ becomes the value of the `image-instance-file-name' function when
+ applied to the resulting image-instance. This keyword is not
+ valid for instantiator formats `nothing', `string',
+ `formatted-string', `cursor-font', `font', and `autodetect'.
+
+`:foreground'
+`:background'
+ For `xbm', `xface', `cursor-font', and `font'. These keywords
+ allow you to explicitly specify foreground and background colors.
+ The argument should be anything acceptable to
+ `make-color-instance'. This will cause what would be a
+ `mono-pixmap' to instead be colorized as a two-color color-pixmap,
+ and specifies the foreground and/or background colors for a pointer
+ instead of black and white.
+
+`:mask-data'
+ For `xbm' and `xface'. This specifies a mask to be used with the
+ bitmap. The format is a list of width, height, and bits, like for
+ `:data'.
+
+`:mask-file'
+ For `xbm' and `xface'. This specifies a file containing the mask
+ data. If neither a mask file nor inline mask data is given for an
+ XBM image, and the XBM image comes from a file, XEmacs will look
+ for a mask file with the same name as the image file but with
+ `Mask' or `msk' appended. For example, if you specify the XBM file
+ `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
+ associated mask file `left_ptrmsk' will automatically be picked up.
+
+`:hotspot-x'
+`:hotspot-y'
+ For `xbm' and `xface'. These keywords specify a hotspot if the
+ image is instantiated as a `pointer'. Note that if the XBM image
+ file specifies a hotspot, it will automatically be picked up if no
+ explicit hotspot is given.
+
+`:color-symbols'
+ Only for `xpm'. This specifies an alist that maps strings that
+ specify symbolic color names to the actual color to be used for
+ that symbolic color (in the form of a string or a color-specifier
+ object). If this is not specified, the contents of
+ `xpm-color-symbols' are used to generate the alist.
+
+`:resource-id'
+ Only for `mswindows-resource'. This must be either an integer
+ (which directly specifies a resource number) or a string. Valid
+ strings are
+
+ For bitmaps:
+
+ "close", "uparrow", "dnarrow", "rgarrow", "lfarrow", "reduce",
+ "zoom", "restore", "reduced", "zoomd", "restored", "uparrowd",
+ "dnarrowd", "rgarrowd", "lfarrowd", "mnarrow", "combo",
+ "uparrowi", "dnarrowi", "rgarrowi", "lfarrowi", "size", "btsize",
+ "check", "checkboxes", and "btncorners".
+
+ For cursors:
+
+ "normal", "ibeam", "wait", "cross", "up", "sizenwse", "sizenesw",
+ "sizewe", "sizens", "sizeall", and "no".
+
+ For icons:
+
+ "sample", "hand", "ques", "bang", "note", and "winlogo".
+
+`:resource-type'
+ Only for `mswindows-resource'. This must be a symbol, either
+ `cursor', `icon', or `bitmap', specifying the type of resource to
+ be retrieved.
+
+`:face'
+ Only for `inherit'. This specifies the face to inherit from. For
+ widgets this also specifies the face to use for display. It
+ defaults to gui-element-face.
+
+ Keywords accepted as menu item specs are also accepted by widgets.
+These are `:selected', `:active', `:suffix', `:keys', `:style',
+`:filter', `:config', `:included', `:key-sequence', `:accelerator',
+`:label' and `:callback'.
+
+ If instead of a vector, the instantiator is a string, it will be
+converted into a vector by looking it up according to the specs in the
+`console-type-image-conversion-list' for the console type of the domain
+(usually a window; sometimes a frame or device) over which the image is
+being instantiated.
+
+ If the instantiator specifies data from a file, the data will be
+read in at the time that the instantiator is added to the image
+specifier (which may be well before the image is actually displayed),
+and the instantiator will be converted into one of the inline-data
+forms, with the filename retained using a `:file' keyword. This
+implies that the file must exist when the instantiator is added to the
+image, but does not need to exist at any other time (e.g. it may safely
+be a temporary file).
+
+ - Function: valid-image-instantiator-format-p format &optional locale
+ This function returns non-`nil' if FORMAT is a valid image
+ instantiator format.
+
+ If LOCALE is non-`nil' then the format is checked in that locale.
+ If LOCALE is `nil' the current console is used.
+
+ Note that the return value for many formats listed above depends on
+ whether XEmacs was compiled with support for that format.
+
+ - Function: image-instantiator-format-list
+ This function return a list of valid image-instantiator formats.
+
+ - Variable: xpm-color-symbols
+ This variable holds definitions of logical color-names used when
+ reading XPM files. Elements of this list should be of the form
+ `(COLOR-NAME FORM-TO-EVALUATE)'. The COLOR-NAME should be a
+ string, which is the name of the color to define; the
+ FORM-TO-EVALUATE should evaluate to a color specifier object, or a
+ string to be passed to `make-color-instance' (*note Colors::). If
+ a loaded XPM file references a symbolic color called COLOR-NAME,
+ it will display as the computed color instead.
+
+ The default value of this variable defines the logical color names
+ `"foreground"' and `"background"' to be the colors of the
+ `default' face.
+
+ - Variable: x-bitmap-file-path
+ A list of the directories in which X bitmap files may be found.
+ If `nil', this is initialized from the `"*bitmapFilePath"'
+ resource. This is used by the `make-image-instance' function
+ (however, note that if the environment variable `XBMLANGPATH' is
+ set, it is consulted first).
+
+\1f
+File: lispref.info, Node: Image Instantiator Conversion, Next: Image Instances, Prev: Image Specifiers, Up: Images
+
+Image Instantiator Conversion
+-----------------------------
+
+ - Function: set-console-type-image-conversion-list console-type list
+ This function sets the image-conversion-list for consoles of the
+ given CONSOLE-TYPE. The image-conversion-list specifies how image
+ instantiators that are strings should be interpreted. Each
+ element of the list should be a list of two elements (a regular
+ expression string and a vector) or a list of three elements (the
+ preceding two plus an integer index into the vector). The string
+ is converted to the vector associated with the first matching
+ regular expression. If a vector index is specified, the string
+ itself is substituted into that position in the vector.
+
+ Note: The conversion above is applied when the image instantiator
+ is added to an image specifier, not when the specifier is actually
+ instantiated. Therefore, changing the image-conversion-list only
+ affects newly-added instantiators. Existing instantiators in
+ glyphs and image specifiers will not be affected.
+
+ - Function: console-type-image-conversion-list console-type
+ This function returns the image-conversion-list for consoles of
+ the given CONSOLE-TYPE.
+
+\1f
+File: lispref.info, Node: Image Instances, Prev: Image Instantiator Conversion, Up: Images
+
+Image Instances
+---------------
+
+Image-instance objects encapsulate the way a particular image (pixmap,
+etc.) is displayed on a particular device.
+
+ In most circumstances, you do not need to directly create image
+instances; use a glyph instead. However, it may occasionally be useful
+to explicitly create image instances, if you want more control over the
+instantiation process.
+
+ - Function: image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance.
+
+* Menu:
+
+* Image Instance Types:: Each image instances has a particular type.
+* Image Instance Functions:: Functions for working with image instances.
+
+\1f
+File: lispref.info, Node: Image Instance Types, Next: Image Instance Functions, Up: Image Instances
+
+Image Instance Types
+....................
+
+Image instances come in a number of different types. The type of an
+image instance specifies the nature of the image: Whether it is a text
+string, a mono pixmap, a color pixmap, etc.
+
+ The valid image instance types are
+
+`nothing'
+ Nothing is displayed.
+
+`text'
+ Displayed as text. The foreground and background colors and the
+ font of the text are specified independent of the pixmap.
+ Typically these attributes will come from the face of the
+ surrounding text, unless a face is specified for the glyph in
+ which the image appears.
+
+`mono-pixmap'
+ Displayed as a mono pixmap (a pixmap with only two colors where the
+ foreground and background can be specified independent of the
+ pixmap; typically the pixmap assumes the foreground and background
+ colors of the text around it, unless a face is specified for the
+ glyph in which the image appears).
+
+`color-pixmap'
+ Displayed as a color pixmap.
+
+`pointer'
+ Used as the mouse pointer for a window.
+
+`subwindow'
+ A child window that is treated as an image. This allows (e.g.)
+ another program to be responsible for drawing into the window.
+ Not currently implemented.
+
+ - Function: valid-image-instance-type-p type
+ This function returns non-`nil' if TYPE is a valid image instance
+ type.
+
+ - Function: image-instance-type-list
+ This function returns a list of the valid image instance types.
+
+ - Function: image-instance-type image-instance
+ This function returns the type of the given image instance. The
+ return value will be one of `nothing', `text', `mono-pixmap',
+ `color-pixmap', `pointer', or `subwindow'.
+
+ - Function: text-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `text'.
+
+ - Function: mono-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `mono-pixmap'.
+
+ - Function: color-pixmap-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `color-pixmap'.
+
+ - Function: pointer-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `pointer'.
+
+ - Function: subwindow-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `subwindow'.
+
+ - Function: nothing-image-instance-p object
+ This function returns non-`nil' if OBJECT is an image instance of
+ type `nothing'.
+
+ - Function: widget-image-instance-p object
+ Return `t' if OBJECT is an image instance of type `widget'.
+
+\1f
+File: lispref.info, Node: Image Instance Functions, Prev: Image Instance Types, Up: Image Instances
+
+Image Instance Functions
+........................
+
+ - Function: make-image-instance data &optional domain dest-types
+ noerror
+ This function creates a new image-instance object.
+
+ DATA is an image instantiator, which describes the image (*note
+ Image Specifiers::).
+
+ DEST-TYPES should be a list of allowed image instance types that
+ can be generated. The DEST-TYPES list is unordered. If multiple
+ destination types are possible for a given instantiator, the "most
+ natural" type for the instantiator's format is chosen. (For XBM,
+ the most natural types are `mono-pixmap', followed by
+ `color-pixmap', followed by `pointer'. For the other normal image
+ formats, the most natural types are `color-pixmap', followed by
+ `mono-pixmap', followed by `pointer'. For the string and
+ formatted-string formats, the most natural types are `text',
+ followed by `mono-pixmap' (not currently implemented), followed by
+ `color-pixmap' (not currently implemented). For MS Windows
+ resources, the most natural type for pointer resources is
+ `pointer', and for the others it's `color-pixmap'. The other
+ formats can only be instantiated as one type. (If you want to
+ control more specifically the order of the types into which an
+ image is instantiated, just call `make-image-instance' repeatedly
+ until it succeeds, passing less and less preferred destination
+ types each time.
+
+ If DEST-TYPES is omitted, all possible types are allowed.
+
+ DOMAIN specifies the domain to which the image instance will be
+ attached. This domain is termed the "governing domain". The type
+ of the governing domain depends on the image instantiator format.
+ (Although, more correctly, it should probably depend on the image
+ instance type.) For example, pixmap image instances are specific
+ to a device, but widget image instances are specific to a
+ particular XEmacs window because in order to display such a widget
+ when two windows onto the same buffer want to display the widget,
+ two separate underlying widgets must be created. (That's because a
+ widget is actually a child window-system window, and all
+ window-system windows have a unique existence on the screen.) This
+ means that the governing domain for a pixmap image instance will
+ be some device (most likely, the only existing device), whereas
+ the governing domain for a widget image instance will be some
+ XEmacs window.
+
+ If you specify an overly general DOMAIN (e.g. a frame when a
+ window was wanted), an error is signaled. If you specify an overly
+ specific DOMAIN (e.g. a window when a device was wanted), the
+ corresponding general domain is fetched and used instead. For
+ `make-image-instance', it makes no difference whether you specify
+ an overly specific domain or the properly general domain derived
+ from it. However, it does matter when creating an image instance
+ by instantiating a specifier or glyph (e.g. with
+ `glyph-image-instance'), because the more specific domain causes
+ spec lookup to start there and proceed to more general domains. (It
+ would also matter when creating an image instance with an
+ instantiator format of `inherit', but we currently disallow this.
+ #### We should fix this.) n If omitted, DOMAIN defaults to the
+ selected window.
+
+ NOERROR controls what happens when the image cannot be generated.
+ If `nil', an error message is generated. If `t', no messages are
+ generated and this function returns `nil'. If anything else, a
+ warning message is generated and this function returns `nil'.
+
+ - Function: colorize-image-instance image-instance foreground
+ background
+ This function makes the image instance be displayed in the given
+ colors. Image instances come in two varieties: bitmaps, which are
+ 1 bit deep which are rendered in the prevailing foreground and
+ background colors; and pixmaps, which are of arbitrary depth
+ (including 1) and which have the colors explicitly specified.
+ This function converts a bitmap to a pixmap. If the image
+ instance was a pixmap already, nothing is done (and `nil' is
+ returned). Otherwise `t' is returned.
+
+ - Function: image-instance-name image-instance
+ This function returns the name of the given image instance.
+
+ - Function: image-instance-domain image-instance
+ Return the governing domain of the given IMAGE-INSTANCE. The
+ governing domain of an image instance is the domain that the image
+ instance is specific to. It is _NOT_ necessarily the domain that
+ was given to the call to `specifier-instance' that resulted in the
+ creation of this image instance. See `make-image-instance' for
+ more information on governing domains.
+
+ - Function: image-instance-string image-instance
+ This function returns the string of the given image instance.
+ This will only be non-`nil' for text image instances.
+
+ - Function: image-instance-file-name image-instance
+ This function returns the file name from which IMAGE-INSTANCE was
+ read, if known.
+
+ - Function: image-instance-mask-file-name image-instance
+ This function returns the file name from which IMAGE-INSTANCE's
+ mask was read, if known.
+
+ - Function: image-instance-depth image-instance
+ This function returns the depth of the image instance. This is 0
+ for a mono pixmap, or a positive integer for a color pixmap.
+
+ - Function: image-instance-height image-instance
+ This function returns the height of the image instance, in pixels.
+
+ - Function: image-instance-width image-instance
+ This function returns the width of the image instance, in pixels.
+
+ - Function: image-instance-hotspot-x image-instance
+ This function returns the X coordinate of the image instance's
+ hotspot, if known. This is a point relative to the origin of the
+ pixmap. When an image is used as a mouse pointer, the hotspot is
+ the point on the image that sits over the location that the
+ pointer points to. This is, for example, the tip of the arrow or
+ the center of the crosshairs.
+
+ This will always be `nil' for a non-pointer image instance.
+
+ - Function: image-instance-hotspot-y image-instance
+ This function returns the Y coordinate of the image instance's
+ hotspot, if known.
+
+ - Function: image-instance-foreground image-instance
+ This function returns the foreground color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
+
+ - Function: image-instance-background image-instance
+ This function returns the background color of IMAGE-INSTANCE, if
+ applicable. This will be a color instance or `nil'. (It will only
+ be non-`nil' for colorized mono pixmaps and for pointers.)
+
+\1f
+File: lispref.info, Node: Glyph Types, Next: Mouse Pointer, Prev: Images, Up: Glyphs
+
+Glyph Types
+===========
+
+Each glyph has a particular type, which controls how the glyph's image
+is generated. Each glyph type has a corresponding list of allowable
+image instance types that can be generated. When you call
+`glyph-image-instance' to retrieve the image instance of a glyph,
+XEmacs does the equivalent of calling `make-image-instance' and passing
+in DEST-TYPES the list of allowable image instance types for the
+glyph's type.
+
+ * `buffer' glyphs can be used as the begin-glyph or end-glyph of an
+ extent, in the modeline, and in the toolbar. Their image can be
+ instantiated as `nothing', `mono-pixmap', `color-pixmap', `text',
+ and `subwindow'.
+
+ * `pointer' glyphs can be used to specify the mouse pointer. Their
+ image can be instantiated as `pointer'.
+
+ * `icon' glyphs can be used to specify the icon used when a frame is
+ iconified. Their image can be instantiated as `mono-pixmap' and
+ `color-pixmap'.
+
+ - Function: glyph-type glyph
+ This function returns the type of the given glyph. The return
+ value will be a symbol, one of `buffer', `pointer', or `icon'.
+
+ - Function: valid-glyph-type-p glyph-type
+ Given a GLYPH-TYPE, this function returns non-`nil' if it is valid.
+
+ - Function: glyph-type-list
+ This function returns a list of valid glyph types.
+
+ - Function: buffer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `buffer'.
+
+ - Function: icon-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `icon'.
+
+ - Function: pointer-glyph-p object
+ This function returns non-`nil' if OBJECT is a glyph of type
+ `pointer'.
+
+\1f
+File: lispref.info, Node: Mouse Pointer, Next: Redisplay Glyphs, Prev: Glyph Types, Up: Glyphs
+
+Mouse Pointer
+=============
+
+The shape of the mouse pointer when over a particular section of a frame
+is controlled using various glyph variables. Since the image of a glyph
+is a specifier, it can be controlled on a per-buffer, per-frame,
+per-window, or per-device basis.
+
+ You should use `set-glyph-image' to set the following variables,
+_not_ `setq'.
+
+ - Glyph: text-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ text.
+
+ - Glyph: nontext-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ buffer, but not over text. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: modeline-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the modeline. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ - Glyph: selection-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ selectable text region. If unspecified in a particular domain,
+ `text-pointer-glyph' is used.
+
+ - Glyph: gc-pointer-glyph
+ This variable specifies the shape of the mouse pointer when a
+ garbage collection is in progress. If the selected window is on a
+ window system and this glyph specifies a value (i.e. a pointer
+ image instance) in the domain of the selected window, the pointer
+ will be changed as specified during garbage collection.
+ Otherwise, a message will be printed in the echo area, as
+ controlled by `gc-message'.
+
+ - Glyph: busy-pointer-glyph
+ This variable specifies the shape of the mouse pointer when XEmacs
+ is busy. If unspecified in a particular domain, the pointer is
+ not changed when XEmacs is busy.
+
+ - Glyph: menubar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over
+ the menubar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: scrollbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ scrollbar. If unspecified in a particular domain, the
+ window-system-provided default pointer is used.
+
+ - Glyph: toolbar-pointer-glyph
+ This variable specifies the shape of the mouse pointer when over a
+ toolbar. If unspecified in a particular domain,
+ `nontext-pointer-glyph' is used.
+
+ Internally, these variables are implemented in
+`default-mouse-motion-handler', and thus only take effect when the
+mouse moves. That function calls `set-frame-pointer', which sets the
+current mouse pointer for a frame.
+
+ - Function: set-frame-pointer frame image-instance
+ This function sets the mouse pointer of FRAME to the given pointer
+ image instance. You should not call this function directly. (If
+ you do, the pointer will change again the next time the mouse
+ moves.)
+
+\1f
+File: lispref.info, Node: Redisplay Glyphs, Next: Subwindows, Prev: Mouse Pointer, Up: Glyphs
+
+Redisplay Glyphs
+================
+
+ - Glyph: truncation-glyph
+ This variable specifies what is displayed at the end of truncated
+ lines.
+
+ - Glyph: continuation-glyph
+ This variable specifies what is displayed at the end of wrapped
+ lines.
+
+ - Glyph: octal-escape-glyph
+ This variable specifies what to prefix character codes displayed
+ in octal with.
+
+ - Glyph: hscroll-glyph
+ This variable specifies what to display at the beginning of
+ horizontally scrolled lines.
+
+ - Glyph: invisible-text-glyph
+ This variable specifies what to use to indicate the presence of
+ invisible text. This is the glyph that is displayed when an
+ ellipsis is called for, according to `selective-display-ellipses'
+ or `buffer-invisibility-spec'). Normally this is three dots
+ ("...").
+
+ - Glyph: control-arrow-glyph
+ This variable specifies what to use as an arrow for control
+ characters.
+
+\1f
+File: lispref.info, Node: Subwindows, Next: Glyph Examples, Prev: Redisplay Glyphs, Up: Glyphs
+
+Subwindows
+==========
+
+Subwindows are not currently implemented.
+
+ - Function: subwindowp object
+ This function returns non-`nil' if OBJECT is a subwindow.
+
+\1f
+File: lispref.info, Node: Glyph Examples, Prev: Subwindows, Up: Glyphs
+
+Glyph Examples
+==============
+
+For many applications, displaying graphics is a simple process: you
+create a glyph, and then you insert it into a buffer.
+
+ The easiest way to create a glyph is to use a file that contains a
+graphical image, such as a JPEG, TIFF, or PNG file:
+
+ ;; Create a glyph from a JPEG file:
+ (setq foo (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+
+ ;; Create a glyph from a XPM file:
+ (setq foo (make-glyph [xpm :file "/tmp/file2.xpm"]))
+
+ ;; Create a glyph from a PNG file:
+ (setq foo (make-glyph [png :file "/tmp/file3.png"]))
+
+ ;; Create a glyph from a TIFF file:
+ (setq foo (make-glyph [tiff :file "/tmp/file4.tiff"]))
+
+ The parameters passed to `make-glyph' are called "Image Specifiers",
+and can handle more image types than those shown above. You can also
+put the raw image data into a string (e.g., if you put the contents of
+a JPEG file into a string), and use that to create a glyph. *Note
+Image Specifiers::, for more information.
+
+ *Caution*: In order for XEmacs to read a particular graphics file
+ format, support for that format must have been compiled into
+ XEmacs. It's possible, although somewhat unlikely, for XEmacs to
+ have been compiled without support for any of the various graphics
+ file formats. To see what graphics formats your particular
+ version of XEmacs supports, use `M-x describe-installation'.
+
+ To programmatically query whether or not a particular file format
+ is supported, you can use the `featurep' function, with one of:
+ `gif', `tiff', `jpeg', `xpm', `xbm', `png', or `xface'. For an
+ up-to-date list, *Note Image Specifiers::. Example:
+
+ ;; Returns `t' if TIFF is supported:
+ (featurep 'tiff)
+
+ Another example is:
+
+ ;; Returns a list of `t' or `nil', depending on whether or not the
+ ;; corresponding feature is supported:
+ (mapcar #'(lambda (format-symbol) (featurep format-symbol))
+ '(gif tiff jpeg xpm png))
+
+
+ Once you have a glyph, you can then insert it into a buffer.
+Example:
+
+ ;; Use this function to insert a glyph at the left edge of point in the
+ ;; current buffer. Any existing glyph at this location is replaced.
+ (defun insert-glyph (gl)
+ "Insert a glyph at the left edge of point."
+ (let ( (prop 'myimage) ;; myimage is an arbitrary name, chosen
+ ;; to (hopefully) not conflict with any
+ ;; other properties. Change it if
+ ;; necessary.
+ extent )
+ ;; First, check to see if one of our extents already exists at
+ ;; point. For ease-of-programming, we are creating and using our
+ ;; own extents (multiple extents are allowed to exist/overlap at the
+ ;; same point, and it's quite possible for other applications to
+ ;; embed extents in the current buffer without your knowledge).
+ ;; Basically, if an extent, with the property stored in "prop",
+ ;; exists at point, we assume that it is one of ours, and we re-use
+ ;; it (this is why it is important for the property stored in "prop"
+ ;; to be unique, and only used by us).
+ (if (not (setq extent (extent-at (point) (current-buffer) prop)))
+ (progn
+ ;; If an extent does not already exist, create a zero-length
+ ;; extent, and give it our special property.
+ (setq extent (make-extent (point) (point) (current-buffer)))
+ (set-extent-property extent prop t)
+ ))
+ ;; Display the glyph by storing it as the extent's "begin-glyph".
+ (set-extent-property extent 'begin-glyph gl)
+ ))
+
+ ;; You can then use this function like:
+ (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+ ;; This will insert the glyph at point.
+
+ ;; Here's an example of how to insert two glyphs side-by-side, at point
+ ;; (using the above code):
+ (progn
+ (insert-glyph (make-glyph [jpeg :file "/tmp/file1.jpg"]))
+ ;; Create a new extent at point. We can't simply call "insert-glyph",
+ ;; as "insert-glyph" will simply replace the first glyph with the
+ ;; second.
+ (setq extent (make-extent (point) (point) (current-buffer)))
+ ;; Here, we're only setting the 'myimage property in case we need
+ ;; to later identify/locate/reuse this particular extent.
+ (set-extent-property extent 'myimage t)
+ (set-extent-property extent 'begin-glyph
+ (make-glyph [jpeg :file "/tmp/file2.jpg"]))
+ )
+
+ Here are the gory details:
+
+ * Glyphs are displayed by attaching them to extents (see *Note
+ Extents::), either to the beginning or the end of extents.
+
+ Note that extents can be used for many things, and not just for
+ displaying images (although, in the above example, we are creating
+ our own extent for the sole purpose of displaying an image).
+ Also, note that multiple extents are allowed to exist at the same
+ position, and they can overlap.
+
+ * Glyphs are often displayed inside the text area (alongside text).
+ This is the default.
+
+ Although glyphs can also be displayed in the margins, how to do
+ this will not be described here. For more information on this, see
+ *Note Annotation Basics:: (look for information on "layout types")
+ and *Note Extent Properties:: (look for `begin-glyph-layout' and
+ `end-glyph-layout').
+
+ * The easiest way to insert a glyph into text is to create a
+ zero-length extent at the point where you want the glyph to appear.
+
+ Note that zero-length extents are attached to the character to the
+ right of the extent; deleting this character will also delete the
+ extent.
+
+ * It's often a good idea to assign a unique property to the
+ newly-created extent, in case you later want to locate it, and
+ replace any existing glyph with a different one (or just delete
+ the existing one). In the above example, we are using "myimage"
+ as our (hopefully) unique property name.
+
+ If you need to locate all of the extents, you'll have to use
+ functions like `extent-list' or `next-extent', or provide
+ additional parameters to the `extent-at' function. Assigning a
+ unique property to the extent makes it easy to locate your
+ extents; for example, `extent-list' can return only those extents
+ with a particular property. *Note Finding Extents::, and *Note
+ Mapping Over Extents::, for more information.
+
+ * Glyphs are displayed by assigning then to the `begin-glyph' or
+ `end-glyph' property of the extent. For zero-length extents, it
+ doesn't really matter if you assign the glyph to the `begin-glyph'
+ or `end-glyph' property, as they are both at the same location;
+ however, for non-zero-length extents (extents that cover one or
+ more characters of text), it does matter which one you use.
+
+ Assigning `nil' to the `begin-glyph' or `end-glyph' property will
+ delete any existing glyph. In this case, you may also want to
+ delete the extent, assuming that the extent is used for no other
+ purpose.
+
+ * If you happen to insert two glyphs, side-by-side, note that the
+ example `insert-glyph' function will have trouble, if it's again
+ used at the same point (it can only locate one of the two extents).
+ *Note Finding Extents::, and *Note Mapping Over Extents::, for more
+ information on locating extents in a buffer.
+
+ * Among other things, glyphs provide a way of displaying graphics
+ alongside text. Note, however, that glyphs only provide a way of
+ displaying graphics; glyphs are not actually part of the text, and
+ are only displayed alongside the text. If you save the text in
+ the buffer, the graphics are not saved. The low-level glyph code
+ does not provide a way of saving graphics with the text. If you
+ need to save graphics and text, you have to write your own code to
+ do this, and this topic is outside the scope of this discussion.
+
+
+\1f
+File: lispref.info, Node: Annotations, Next: Display, Prev: Glyphs, Up: Top
+
+Annotations
+***********
+
+An "annotation" is a pixmap or string that is not part of a buffer's
+text but is displayed next to a particular location in a buffer.
+Annotations can be displayed intermixed with text, in any whitespace at
+the beginning or end of a line, or in a special area at the left or
+right side of the frame called a "margin", whose size is controllable.
+Annotations are implemented using extents (*note Extents::); but you
+can work with annotations without knowing how extents work.
+
+* Menu:
+
+* Annotation Basics:: Introduction to annotations.
+* Annotation Primitives:: Creating and deleting annotations.
+* Annotation Properties:: Retrieving and changing the characteristics
+ of an annotation.
+* Margin Primitives:: Controlling the size of the margins.
+* Locating Annotations:: Looking for annotations in a buffer.
+* Annotation Hooks:: Hooks called at certain times during an
+ annotation's lifetime.
+
+\1f
+File: lispref.info, Node: Annotation Basics, Next: Annotation Primitives, Up: Annotations
+
+Annotation Basics
+=================
+
+Marginal annotations are notes associated with a particular location in
+a buffer. They may be displayed in a margin created on the left-hand or
+right-hand side of the frame, in any whitespace at the beginning or end
+of a line, or inside of the text itself. Every annotation may have an
+associated action to be performed when the annotation is selected. The
+term "annotation" is used to refer to an individual note. The term
+"margin" is generically used to refer to the whitespace before the
+first character on a line or after the last character on a line.
+
+ Each annotation has the following characteristics:
+GLYPH
+ This is a glyph object and is used as the displayed representation
+ of the annotation.
+
+DOWN-GLYPH
+ If given, this glyph is used as the displayed representation of
+ the annotation when the mouse is pressed down over the annotation.
+
+FACE
+ The face with which to display the glyph.
+
+SIDE
+ Which side of the text (left or right) the annotation is displayed
+ at.
+
+ACTION
+ If non-`nil', this field must contain a function capable of being
+ the first argument to `funcall'. This function is normally
+ evaluated with a single argument, the value of the DATA field,
+ each time the annotation is selected. However, if the WITH-EVENT
+ parameter to `make-annotation' is non-`nil', the function is
+ called with two arguments. The first argument is the same as
+ before, and the second argument is the event (a button-up event,
+ usually) that activated the annotation.
+
+DATA
+ Not used internally. This field can contain any E-Lisp object.
+ It is passed as the first argument to ACTION described above.
+
+MENU
+ A menu displayed when the right mouse button is pressed over the
+ annotation.
+
+ The margin is divided into "outside" and "inside". The outside
+margin is space on the left or right side of the frame which normal text
+cannot be displayed in. The inside margin is that space between the
+leftmost or rightmost point at which text can be displayed and where the
+first or last character actually is.
+
+ There are four different "layout types" which affect the exact
+location an annotation appears.
+
+`outside-margin'
+ The annotation is placed in the outside margin area. as close as
+ possible to the edge of the frame. If the outside margin is not
+ wide enough for an annotation to fit, it is not displayed.
+
+`inside-margin'
+ The annotation is placed in the inside margin area, as close as
+ possible to the edge of the frame. If the inside margin is not
+ wide enough for the annotation to fit, it will be displayed using
+ any available outside margin space if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`whitespace'
+ The annotation is placed in the inside margin area, as close as
+ possible to the first or last non-whitespace character on a line.
+ If the inside margin is not wide enough for the annotation to fit,
+ it will be displayed if and only if the specifier
+ `use-left-overflow' or `use-right-overflow' (depending on which
+ side the annotation appears in) is non-`nil'.
+
+`text'
+ The annotation is placed at the position it is inserted. It will
+ create enough space for itself inside of the text area. It does
+ not take up a place in the logical buffer, only in the display of
+ the buffer.
+
+ The current layout policy is that all `whitespace' annotations are
+displayed first. Next, all `inside-margin' annotations are displayed
+using any remaining space. Finally as many `outside-margin'
+annotations are displayed as possible. The `text' annotations will
+always display as they create their own space to display in.
+
+\1f
+File: lispref.info, Node: Annotation Primitives, Next: Annotation Properties, Prev: Annotation Basics, Up: Annotations
+
+Annotation Primitives
+=====================
+
+ - Function: make-annotation glyph &optional position layout buffer
+ with-event d-glyph rightp
+ This function creates a marginal annotation at position POSITION in
+ BUFFER. The annotation is displayed using GLYPH, which should be
+ a glyph object or a string, and is positioned using layout policy
+ LAYOUT. If POSITION is `nil', point is used. If LAYOUT is `nil',
+ `whitespace' is used. If BUFFER is `nil', the current buffer is
+ used.
+
+ If WITH-EVENT is non-`nil', then when an annotation is activated,
+ the triggering event is passed as the second arg to the annotation
+ function. If D-GLYPH is non-`nil' then it is used as the glyph
+ that will be displayed when button1 is down. If RIGHTP is
+ non-`nil' then the glyph will be displayed on the right side of
+ the buffer instead of the left.
+
+ The newly created annotation is returned.
+
+ - Function: delete-annotation annotation
+ This function removes ANNOTATION from its buffer. This does not
+ modify the buffer text.
+
+ - Function: annotationp annotation
+ This function returns `t' if ANNOTATION is an annotation, `nil'
+ otherwise.
+
+\1f
+File: lispref.info, Node: Annotation Properties, Next: Margin Primitives, Prev: Annotation Primitives, Up: Annotations
+
+Annotation Properties
+=====================
+
+ - Function: annotation-glyph annotation
+ This function returns the glyph object used to display ANNOTATION.
+
+ - Function: set-annotation-glyph annotation glyph &optional layout side
+ This function sets the glyph of ANNOTATION to GLYPH, which should
+ be a glyph object. If LAYOUT is non-`nil', set the layout policy
+ of ANNOTATION to LAYOUT. If SIDE is `left' or `right', change the
+ side of the buffer at which the annotation is displayed to the
+ given side. The new value of `annotation-glyph' is returned.
+
+ - Function: annotation-down-glyph annotation
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation.
+
+ - Function: set-annotation-down-glyph annotation glyph
+ This function returns the glyph used to display ANNOTATION when
+ the left mouse button is depressed on the annotation to GLYPH,
+ which should be a glyph object.
+
+ - Function: annotation-face annotation
+ This function returns the face associated with ANNOTATION.
+
+ - Function: set-annotation-face annotation face
+ This function sets the face associated with ANNOTATION to FACE.
+
+ - Function: annotation-layout annotation
+ This function returns the layout policy of ANNOTATION.
+
+ - Function: set-annotation-layout annotation layout
+ This function sets the layout policy of ANNOTATION to LAYOUT.
+
+ - Function: annotation-side annotation
+ This function returns the side of the buffer that ANNOTATION is
+ displayed on. Return value is a symbol, either `left' or `right'.
+
+ - Function: annotation-data annotation
+ This function returns the data associated with ANNOTATION.
+
+ - Function: set-annotation-data annotation data
+ This function sets the data field of ANNOTATION to DATA. DATA is
+ returned.
+
+ - Function: annotation-action annotation
+ This function returns the action associated with ANNOTATION.
+
+ - Function: set-annotation-action annotation action
+ This function sets the action field of ANNOTATION to ACTION.
+ ACTION is returned..
+
+ - Function: annotation-menu annotation
+ This function returns the menu associated with ANNOTATION.
+
+ - Function: set-annotation-menu annotation menu
+ This function sets the menu associated with ANNOTATION to MENU.
+ This menu will be displayed when the right mouse button is pressed
+ over the annotation.
+
+ - Function: annotation-visible annotation
+ This function returns `t' if there is enough available space to
+ display ANNOTATION, `nil' otherwise.
+
+ - Function: annotation-width annotation
+ This function returns the width of ANNOTATION in pixels.
+
+ - Function: hide-annotation annotation
+ This function removes ANNOTATION's glyph, making it invisible.
+
+ - Function: reveal-annotation annotation
+ This function restores ANNOTATION's glyph, making it visible.
+
+\1f
+File: lispref.info, Node: Locating Annotations, Next: Annotation Hooks, Prev: Margin Primitives, Up: Annotations
+
+Locating Annotations
+====================
+
+ - Function: annotations-in-region start end buffer
+ This function returns a list of all annotations in BUFFER which
+ are between START and END inclusively.
+
+ - Function: annotations-at &optional position buffer
+ This function returns a list of all annotations at POSITION in
+ BUFFER. If POSITION is `nil' point is used. If BUFFER is `nil'
+ the current buffer is used.
+
+ - Function: annotation-list &optional buffer
+ This function returns a list of all annotations in BUFFER. If
+ BUFFER is `nil', the current buffer is used.
+
+ - Function: all-annotations
+ This function returns a list of all annotations in all buffers in
+ existence.
+
+\1f
+File: lispref.info, Node: Margin Primitives, Next: Locating Annotations, Prev: Annotation Properties, Up: Annotations
+
+Margin Primitives
+=================
+
+The margin widths are controllable on a buffer-local, window-local,
+frame-local, device-local, or device-type-local basis through the use
+of specifiers. *Note Specifiers::.
+
+ - Specifier: left-margin-width
+ This is a specifier variable controlling the width of the left
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: right-margin-width
+ This is a specifier variable controlling the width of the right
+ outside margin, in characters. Use `set-specifier' to change its
+ value.
+
+ - Specifier: use-left-overflow
+ If non-`nil', use the left outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Specifier: use-right-overflow
+ If non-`nil', use the right outside margin as extra whitespace when
+ displaying `whitespace' and `inside-margin' annotations. Defaults
+ to `nil'. This is a specifier variable; use `set-specifier' to
+ change its value.
+
+ - Function: window-left-margin-pixel-width &optional window
+ This function returns the width in pixels of the left outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ - Function: window-right-margin-pixel-width &optional window
+ This function returns the width in pixels of the right outside
+ margin of WINDOW. If WINDOW is `nil', the selected window is
+ assumed.
+
+ The margin colors are controlled by the faces `left-margin' and
+`right-margin'. These can be set using the X resources
+`Emacs.left-margin.background' and `Emacs.left-margin.foreground';
+likewise for the right margin.
+
+\1f
+File: lispref.info, Node: Annotation Hooks, Prev: Locating Annotations, Up: Annotations
+
+Annotation Hooks
+================
+
+The following three hooks are provided for use with the marginal
+annotations:
+
+`before-delete-annotation-hook'
+ This hook is called immediately before an annotation is destroyed.
+ It is passed a single argument, the annotation being destroyed.
+
+`after-delete-annotation-hook'
+ This normal hook is called immediately after an annotation is
+ destroyed.
+
+`make-annotation-hook'
+ This hook is called immediately after an annotation is created.
+ It is passed a single argument, the newly created annotation.
+
+\1f
+File: lispref.info, Node: Display, Next: Hash Tables, Prev: Annotations, Up: Top
+
+Emacs Display
+*************
+
+This chapter describes a number of other features related to the display
+that XEmacs presents to the user.
+
+* Menu:
+
+* Refresh Screen:: Clearing the screen and redrawing everything on it.
+* Truncation:: Folding or wrapping long text lines.
+* The Echo Area:: Where messages are displayed.
+* Warnings:: Display of Warnings.
+* Invisible Text:: Hiding part of the buffer text.
+* Selective Display:: Hiding part of the buffer text (the old way).
+* Overlay Arrow:: Display of an arrow to indicate position.
+* Temporary Displays:: Displays that go away automatically.
+* Blinking:: How XEmacs 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.
+
+\1f
+File: lispref.info, Node: Refresh Screen, Next: Truncation, Up: Display
+
+Refreshing the Screen
+=====================
+
+The function `redraw-frame' redisplays the entire contents of a given
+frame. *Note Frames::.
+
+ - Function: redraw-frame &optional frame no-preempt
+ This function clears and redisplays frame FRAME.
+
+ FRAME defaults to the selected frame if omitted.
+
+ Normally, redisplay is preempted as normal if input arrives.
+ However, if optional second arg NO-PREEMPT is non-`nil', redisplay
+ will not stop for input and is guaranteed to proceed to completion.
+
+ Even more powerful is `redraw-display':
+
+ - Command: redraw-display &optional device
+ This function redraws all frames on DEVICE marked as having their
+ image garbled. DEVICE defaults to the selected device. If DEVICE
+ is `t', all devices will have their frames checked.
+
+ Processing user input takes absolute priority over redisplay. If you
+call these functions when input is available, they do nothing
+immediately, but a full redisplay does happen eventually--after all the
+input has been processed.
+
+ Normally, suspending and resuming XEmacs also refreshes the screen.
+Some terminal emulators record separate contents for display-oriented
+programs such as XEmacs and for ordinary sequential display. If you are
+using such a terminal, you might want to inhibit the redisplay on
+resumption. *Note Suspending XEmacs::.
+
+ - Variable: no-redraw-on-reenter
+ This variable controls whether XEmacs redraws the entire screen
+ after it has been suspended and resumed. Non-`nil' means yes,
+ `nil' means no.
+
+ The above functions do not actually cause the display to be updated;
+rather, they clear out the internal display records that XEmacs
+maintains, so that the next time the display is updated it will be
+redrawn from scratch. Normally this occurs the next time that
+`next-event' or `sit-for' is called; however, a display update will not
+occur if there is input pending. *Note Command Loop::.
+
+ - Function: force-cursor-redisplay &optional frame
+ This function causes an immediate update of the cursor on FRAME,
+ which defaults to the selected frame.
+
+\1f
+File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
+
+Truncation
+==========
+
+When a line of text extends beyond the right edge of a window, the line
+can either be truncated or continued on the next line. When a line is
+truncated, this is normally shown with a `\' in the rightmost column of
+the window on X displays, and with a `$' on TTY devices. When a line
+is continued or "wrapped" onto the next line, this is shown with a
+curved arrow in the rightmost column of the window (or with a `\' on
+TTY devices). The additional screen lines used to display a long text
+line are called "continuation" lines.
+
+ Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars. *Note Scrollbars::.
+
+ Note that continuation is different from filling; continuation
+happens on the screen only, not in the buffer contents, and it breaks a
+line precisely at the right margin, not at a word boundary. *Note
+Filling::.
+
+ - User Option: truncate-lines
+ This buffer-local variable controls how XEmacs displays lines that
+ extend beyond the right edge of the window. If it is non-`nil',
+ then XEmacs does not display continuation lines; rather each line
+ of text occupies exactly one screen line, and a backslash appears
+ at the edge of any line that extends to or beyond the edge of the
+ window. The default is `nil'.
+
+ If the variable `truncate-partial-width-windows' is non-`nil',
+ then truncation is always used for side-by-side windows (within one
+ frame) regardless of the value of `truncate-lines'.
+
+ - User Option: default-truncate-lines
+ This variable is the default value for `truncate-lines', for
+ buffers that do not have local values for it.
+
+ - User Option: truncate-partial-width-windows
+ This variable controls display of lines that extend beyond the
+ right edge of the window, in side-by-side windows (*note Splitting
+ Windows::). If it is non-`nil', these lines are truncated;
+ otherwise, `truncate-lines' says what to do with them.
+
+ The backslash and curved arrow used to indicate truncated or
+continued lines are only defaults, and can be changed. These images
+are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
+flexibility in how glyphs can be controlled. (This differs from FSF
+Emacs, which uses display tables to control these images.)
+
+ For details, *Note Redisplay Glyphs::.
+
+\1f
+File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
+
+The Echo Area
+=============
+
+The "echo area" is used for displaying messages made with the `message'
+primitive, and for echoing keystrokes. It is not the same as the
+minibuffer, despite the fact that the minibuffer appears (when active)
+in the same place on the screen as the echo area. The `XEmacs Lisp
+Reference Manual' specifies the rules for resolving conflicts between
+the echo area and the minibuffer for use of that screen space (*note
+The Minibuffer: (xemacs)Minibuffer.). Error messages appear in the
+echo area; see *Note Errors::.
+
+ You can write output in the echo area by using the Lisp printing
+functions with `t' as the stream (*note Output Functions::), or as
+follows:
+
+ - Function: message string &rest arguments
+ This function displays a one-line message in the echo area. The
+ argument STRING is similar to a C language `printf' control
+ string. See `format' in *Note String Conversion::, for the details
+ on the conversion specifications. `message' returns the
+ constructed string.
+
+ In batch mode, `message' prints the message text on the standard
+ error stream, followed by a newline.
+
+ If STRING is `nil', `message' clears the echo area. If the
+ minibuffer is active, this brings the minibuffer contents back onto
+ the screen immediately.
+
+ (message "Minibuffer depth is %d."
+ (minibuffer-depth))
+ -| Minibuffer depth is 0.
+ => "Minibuffer depth is 0."
+
+ ---------- Echo Area ----------
+ Minibuffer depth is 0.
+ ---------- Echo Area ----------
+
+ In addition to only displaying a message, XEmacs allows you to
+"label" your messages, giving you fine-grained control of their
+display. Message label is a symbol denoting the message type. Some
+standard labels are:
+
+ * `message'--default label used by the `message' function;
+
+ * `error'--default label used for reporting errors;
+
+ * `progress'--progress indicators like `Converting... 45%' (not
+ logged by default);
+
+ * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
+ default);
+
+ * `command'--helper command messages like `Mark set' (not logged by
+ default);
+
+ * `no-log'--messages that should never be logged
+
+ Several messages may be stacked in the echo area at once. Lisp
+programs may access these messages, or remove them as appropriate, via
+the message stack.
+
+ - Function: display-message label message &optional frame stdout-p
+ This function displays MESSAGE (a string) labeled as LABEL, as
+ described above.
+
+ The FRAME argument specifies the frame to whose minibuffer the
+ message should be printed. This is currently unimplemented. The
+ STDOUT-P argument is used internally.
+
+ (display-message 'command "Mark set")
+
+ - Function: lmessage label string &rest arguments
+ This function displays a message STRING with label LABEL. It is
+ similar to `message' in that it accepts a `printf'-like strings
+ and any number of arguments.
+
+ ;; Display a command message.
+ (lmessage 'command "Comment column set to %d" comment-column)
+
+ ;; Display a progress message.
+ (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
+
+ ;; Display a message that should not be logged.
+ (lmessage 'no-log "Done")
+
+ - Function: clear-message &optional label frame stdout-p no-restore
+ This function remove any message with the given LABEL from the
+ message-stack, erasing it from the echo area if it's currently
+ displayed there.
+
+ If a message remains at the head of the message-stack and
+ NO-RESTORE is `nil', it will be displayed. The string which
+ remains in the echo area will be returned, or `nil' if the
+ message-stack is now empty. If LABEL is `nil', the entire
+ message-stack is cleared.
+
+ ;; Show a message, wait for 2 seconds, and restore old minibuffer
+ ;; contents.
+ (message "A message")
+ -| A message
+ => "A Message"
+ (lmessage 'my-label "Newsflash! Newsflash!")
+ -| Newsflash! Newsflash!
+ => "Newsflash! Newsflash!"
+ (sit-for 2)
+ (clear-message 'my-label)
+ -| A message
+ => "A message"
+
+ Unless you need the return value or you need to specify a label,
+ you should just use `(message nil)'.
+
+ - Function: current-message &optional frame
+ This function returns the current message in the echo area, or
+ `nil'. The FRAME argument is currently unused.
+
+ Some of the messages displayed in the echo area are also recorded in
+the ` *Message-Log*' buffer. Exactly which messages will be recorded
+can be tuned using the following variables.
+
+ - User Option: log-message-max-size
+ This variable specifies the maximum size of the ` *Message-log*'
+ buffer.
+
+ - Variable: log-message-ignore-labels
+ This variable specifies the labels whose messages will not be
+ logged. It should be a list of symbols.
+
+ - Variable: log-message-ignore-regexps
+ This variable specifies the regular expressions matching messages
+ that will not be logged. It should be a list of regular
+ expressions.
+
+ Normally, packages that generate messages that might need to be
+ ignored should label them with `progress', `prompt', or `no-log',
+ so they can be filtered by `log-message-ignore-labels'.
+
+ - Variable: echo-keystrokes
+ This variable determines how much time should elapse before command
+ characters echo. Its value must be a number, which specifies the
+ number of seconds to wait before echoing. If the user types a
+ prefix key (such as `C-x') and then delays this many seconds
+ before continuing, the prefix key is echoed in the echo area. Any
+ subsequent characters in the same command will be echoed as well.
+
+ If the value is zero, then command input is not echoed.
+
+ - Variable: cursor-in-echo-area
+ This variable controls where the cursor appears when a message is
+ displayed in the echo area. If it is non-`nil', then the cursor
+ appears at the end of the message. Otherwise, the cursor appears
+ at point--not in the echo area at all.
+
+ The value is normally `nil'; Lisp programs bind it to `t' for
+ brief periods of time.
+
+\1f
+File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
+
+Warnings
+========
+
+XEmacs contains a facility for unified display of various warnings.
+Unlike errors, warnings are displayed in the situations when XEmacs
+encounters a problem that is recoverable, but which should be fixed for
+safe future operation.
+
+ For example, warnings are printed by the startup code when it
+encounters problems with X keysyms, when there is an error in `.emacs',
+and in other problematic situations. Unlike messages, warnings are
+displayed in a separate buffer, and include an explanatory message that
+may span across several lines. Here is an example of how a warning is
+displayed:
+
+ (1) (initialization/error) An error has occurred while loading ~/.emacs:
+
+ Symbol's value as variable is void: bogus-variable
+
+ To ensure normal operation, you should investigate the cause of the error
+ in your initialization file and remove it. Use the `-debug-init' option
+ to XEmacs to view a complete error backtrace.
+
+ Each warning has a "class" and a "priority level". The class is a
+symbol describing what sort of warning this is, such as
+`initialization', `resource' or `key-mapping'.
+
+ The warning priority level specifies how important the warning is.
+The recognized warning levels, in increased order of priority, are:
+`debug', `info', `notice', `warning', `error', `critical', `alert' and
+`emergency'.
+
+ - Function: display-warning class message &optional level
+ This function displays a warning message MESSAGE (a string).
+ CLASS should be a warning class symbol, as described above, or a
+ list of such symbols. LEVEL describes the warning priority level.
+ If unspecified, it default to `warning'.
+
+ (display-warning 'resource
+ "Bad resource specification encountered:
+ something like
+
+ Emacs*foo: bar
+
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.")
+
+ ---------- Warning buffer ----------
+ (1) (resource/warning) Bad resource specification encountered:
+ something like
+
+ Emacs*foo: bar
+
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.
+ ---------- Warning buffer ----------
+
+ - Function: lwarn class level message &rest args
+ This function displays a formatted labeled warning message. As
+ above, CLASS should be the warning class symbol, or a list of such
+ symbols, and LEVEL should specify the warning priority level
+ (`warning' by default).
+
+ Unlike in `display-warning', MESSAGE may be a formatted message,
+ which will be, together with the rest of the arguments, passed to
+ `format'.
+
+ (lwarn 'message-log 'warning
+ "Error caught in `remove-message-hook': %s"
+ (error-message-string e))
+
+ - Variable: log-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be generated. Warnings with level lower than defined by this
+ variable are completely ignored, as if they never happened.
+
+ - Variable: display-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be displayed. Unlike `log-warning-minimum-level', setting this
+ function does not suppress warnings entirely--they are still
+ generated in the `*Warnings*' buffer, only they are not displayed
+ by default.
+
+ - Variable: log-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will be completely ignored, as it they never happened.
+
+ - Variable: display-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will not be displayed. The warning will still logged in
+ the *Warnings* buffer (unless also contained in
+ `log-warning-suppressed-classes'), but the buffer will not be
+ automatically popped up.
+
+\1f
+File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
+
+Invisible Text
+==============
+
+You can make characters "invisible", so that they do not appear on the
+screen, with the `invisible' property. This can be either a text
+property or a property of an overlay.
+
+ In the simplest case, any non-`nil' `invisible' property makes a
+character invisible. This is the default case--if you don't alter the
+default value of `buffer-invisibility-spec', this is how the
+`invisibility' property works. This feature is much like selective
+display (*note Selective Display::), but more general and cleaner.
+
+ More generally, you can use the variable `buffer-invisibility-spec'
+to control which values of the `invisible' property make text
+invisible. This permits you to classify the text into different subsets
+in advance, by giving them different `invisible' values, and
+subsequently make various subsets visible or invisible by changing the
+value of `buffer-invisibility-spec'.
+
+ Controlling visibility with `buffer-invisibility-spec' is especially
+useful in a program to display the list of entries in a data base. It
+permits the implementation of convenient filtering commands to view
+just a part of the entries in the data base. Setting this variable is
+very fast, much faster than scanning all the text in the buffer looking
+for properties to change.
+
+ - Variable: buffer-invisibility-spec
+ This variable specifies which kinds of `invisible' properties
+ actually make a character invisible.
+
+ `t'
+ A character is invisible if its `invisible' property is
+ non-`nil'. This is the default.
+
+ a list
+ Each element of the list makes certain characters invisible.
+ Ultimately, a character is invisible if any of the elements
+ of this list applies to it. The list can have two kinds of
+ elements:
+
+ `ATOM'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+
+ `(ATOM . t)'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+ Moreover, if this character is at the end of a line and
+ is followed by a visible newline, it displays an
+ ellipsis.
+
+ Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible. However, the user-level line motion
+commands explicitly ignore invisible newlines. Since this causes a
+slow-down of these commands it is turned off by default, controlled by
+the variable `line-move-ignore-invisible'.
+
+\1f
+File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
+
+Selective Display
+=================
+
+"Selective display" is a pair of features that hide certain lines on
+the screen.
+
+ The first variant, explicit selective display, is designed for use in
+a Lisp program. The program controls which lines are hidden by altering
+the text. Outline mode has traditionally used this variant. It has
+been partially replaced by the invisible text feature (*note Invisible
+Text::); there is a new version of Outline mode which uses that instead.
+
+ In the second variant, the choice of lines to hide is made
+automatically based on indentation. This variant is designed to be a
+user-level feature.
+
+ The way you control explicit selective display is by replacing a
+newline (control-j) with a carriage return (control-m). The text that
+was formerly a line following that newline is now invisible. Strictly
+speaking, it is temporarily no longer a line at all, since only newlines
+can separate lines; it is now part of the previous line.
+
+ Selective display does not directly affect editing commands. For
+example, `C-f' (`forward-char') moves point unhesitatingly into
+invisible text. However, the replacement of newline characters with
+carriage return characters affects some editing commands. For example,
+`next-line' skips invisible lines, since it searches only for newlines.
+Modes that use selective display can also define commands that take
+account of the newlines, or that make parts of the text visible or
+invisible.
+
+ When you write a selectively displayed buffer into a file, all the
+control-m's are output as newlines. This means that when you next read
+in the file, it looks OK, with nothing invisible. The selective display
+effect is seen only within XEmacs.
+
+ - Variable: selective-display
+ This buffer-local variable enables selective display. This means
+ that lines, or portions of lines, may be made invisible.
+
+ * If the value of `selective-display' is `t', then any portion
+ of a line that follows a control-m is not displayed.
+
+ * If the value of `selective-display' is a positive integer,
+ then lines that start with more than that many columns of
+ indentation are not displayed.
+
+ When some portion of a buffer is invisible, the vertical movement
+ commands operate as if that portion did not exist, allowing a
+ single `next-line' command to skip any number of invisible lines.
+ However, character movement commands (such as `forward-char') do
+ not skip the invisible portion, and it is possible (if tricky) to
+ insert or delete text in an invisible portion.
+
+ In the examples below, we show the _display appearance_ of the
+ buffer `foo', which changes with the value of `selective-display'.
+ The _contents_ of the buffer do not change.
+
+ (setq selective-display nil)
+ => nil
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column
+ 3n this column
+ 3n this column
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ (setq selective-display 2)
+ => 2
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ - Variable: selective-display-ellipses
+ If this buffer-local variable is non-`nil', then XEmacs displays
+ `...' at the end of a line that is followed by invisible text.
+ This example is a continuation of the previous one.
+
+ (setq selective-display-ellipses t)
+ => t
+
+ ---------- Buffer: foo ----------
+ 1 on this column
+ 2on this column ...
+ 2on this column
+ 1 on this column
+ ---------- Buffer: foo ----------
+
+ You can use a display table to substitute other text for the
+ ellipsis (`...'). *Note Display Tables::.
+
+\1f
+File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
+
+The Overlay Arrow
+=================
+
+The "overlay arrow" is useful for directing the user's attention to a
+particular line in a buffer. For example, in the modes used for
+interface to debuggers, the overlay arrow indicates the line of code
+about to be executed.
+
+ - Variable: overlay-arrow-string
+ This variable holds the string to display to call attention to a
+ particular line, or `nil' if the arrow feature is not in use.
+ Despite its name, the value of this variable can be either a string
+ or a glyph (*note Glyphs::).
+
+ - Variable: overlay-arrow-position
+ This variable holds a marker that indicates where to display the
+ overlay arrow. It should point at the beginning of a line. The
+ arrow text appears at the beginning of that line, overlaying any
+ text that would otherwise appear. Since the arrow is usually
+ short, and the line usually begins with indentation, normally
+ nothing significant is overwritten.
+
+ The overlay string is displayed only in the buffer that this marker
+ points into. Thus, only one buffer can have an overlay arrow at
+ any given time.
+
+ You can do the same job by creating an extent with a `begin-glyph'
+property. *Note Extent Properties::.
+
+\1f
+File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
+
+Temporary Displays
+==================
+
+Temporary displays are used by commands to put output into a buffer and
+then present it to the user for perusal rather than for editing. Many
+of the help commands use this feature.
+
+ - Special Form: with-output-to-temp-buffer buffer-name forms...
+ This function executes FORMS while arranging to insert any output
+ they print into the buffer named BUFFER-NAME. The buffer is then
+ shown in some window for viewing, displayed but not selected.
+
+ The string BUFFER-NAME specifies the temporary buffer, which need
+ not already exist. The argument must be a string, not a buffer.
+ The buffer is erased initially (with no questions asked), and it is
+ marked as unmodified after `with-output-to-temp-buffer' exits.
+
+ `with-output-to-temp-buffer' binds `standard-output' to the
+ temporary buffer, then it evaluates the forms in FORMS. Output
+ using the Lisp output functions within FORMS goes by default to
+ that buffer (but screen display and messages in the echo area,
+ although they are "output" in the general sense of the word, are
+ not affected). *Note Output Functions::.
+
+ The value of the last form in FORMS is returned.
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ ---------- Buffer: foo ----------
+
+ (with-output-to-temp-buffer "foo"
+ (print 20)
+ (print standard-output))
+ => #<buffer foo>
+
+ ---------- Buffer: foo ----------
+ 20
+
+ #<buffer foo>
+
+ ---------- Buffer: foo ----------
+
+ - Variable: temp-buffer-show-function
+ If this variable is non-`nil', `with-output-to-temp-buffer' calls
+ it as a function to do the job of displaying a help buffer. The
+ function gets one argument, which is the buffer it should display.
+
+ In Emacs versions 18 and earlier, this variable was called
+ `temp-buffer-show-hook'.
+
+ - Function: momentary-string-display string position &optional char
+ message
+ This function momentarily displays STRING in the current buffer at
+ POSITION. It has no effect on the undo list or on the buffer's
+ modification status.
+
+ The momentary display remains until the next input event. If the
+ next input event is CHAR, `momentary-string-display' ignores it
+ and returns. Otherwise, that event remains buffered for
+ subsequent use as input. Thus, typing CHAR will simply remove the
+ string from the display, while typing (say) `C-f' will remove the
+ string from the display and later (presumably) move point forward.
+ The argument CHAR is a space by default.
+
+ The return value of `momentary-string-display' is not meaningful.
+
+ You can do the same job in a more general way by creating an extent
+ with a begin-glyph property. *Note Extent Properties::.
+
+ If MESSAGE is non-`nil', it is displayed in the echo area while
+ STRING is displayed in the buffer. If it is `nil', a default
+ message says to type CHAR to continue.
+
+ In this example, point is initially located at the beginning of the
+ second line:
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ -!-Second line.
+ ---------- Buffer: foo ----------
+
+ (momentary-string-display
+ "**** Important Message! ****"
+ (point) ?\r
+ "Type RET when done reading")
+ => t
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ **** Important Message! ****Second line.
+ ---------- Buffer: foo ----------
+
+ ---------- Echo Area ----------
+ Type RET when done reading
+ ---------- Echo Area ----------
+
+ This function works by actually changing the text in the buffer.
+ As a result, if you later undo in this buffer, you will see the
+ message come and go.
+
+\1f
+File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
+
+Blinking Parentheses
+====================
+
+This section describes the mechanism by which XEmacs shows a matching
+open parenthesis when the user inserts a close parenthesis.
+
+ - Variable: blink-paren-function
+ The value of this variable should be a function (of no arguments)
+ to be called whenever a character with close parenthesis syntax is
+ inserted. The value of `blink-paren-function' may be `nil', in
+ which case nothing is done.
+
+ *Please note:* This variable was named `blink-paren-hook' in
+ older Emacs versions, but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `blink-paren-function' in version 19.
+
+ - Variable: blink-matching-paren
+ If this variable is `nil', then `blink-matching-open' does nothing.
+
+ - Variable: blink-matching-paren-distance
+ This variable specifies the maximum distance to scan for a matching
+ parenthesis before giving up.
+
+ - Variable: blink-matching-paren-delay
+ This variable specifies the number of seconds for the cursor to
+ remain at the matching parenthesis. A fraction of a second often
+ gives good results, but the default is 1, which works on all
+ systems.
+
+ - Command: blink-matching-open
+ This function is the default value of `blink-paren-function'. It
+ assumes that point follows a character with close parenthesis
+ syntax and moves the cursor momentarily to the matching opening
+ character. If that character is not already on the screen, it
+ displays the character's context in the echo area. To avoid long
+ delays, this function does not search farther than
+ `blink-matching-paren-distance' characters.
+
+ Here is an example of calling this function explicitly.
+
+ (defun interactive-blink-matching-open ()
+ "Indicate momentarily the start of sexp before point."
+ (interactive)
+ (let ((blink-matching-paren-distance
+ (buffer-size))
+ (blink-matching-paren t))
+ (blink-matching-open)))
+
+\1f
+File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
+
+Usual Display Conventions
+=========================
+
+The usual display conventions define how to display each character
+code. You can override these conventions by setting up a display table
+(*note Display Tables::). Here are the usual display conventions:
+
+ * Character codes 32 through 126 map to glyph codes 32 through 126.
+ Normally this means they display as themselves.
+
+ * Character code 9 is a horizontal tab. It displays as whitespace
+ up to a position determined by `tab-width'.
+
+ * Character code 10 is a newline.
+
+ * All other codes in the range 0 through 31, and code 127, display
+ in one of two ways according to the value of `ctl-arrow'. If it is
+ non-`nil', these codes map to sequences of two glyphs, where the
+ first glyph is the ASCII code for `^'. (A display table can
+ specify a glyph to use instead of `^'.) Otherwise, these codes map
+ just like the codes in the range 128 to 255.
+
+ * Character codes 128 through 255 map to sequences of four glyphs,
+ where the first glyph is the ASCII code for `\', and the others are
+ digit characters representing the code in octal. (A display table
+ can specify a glyph to use instead of `\'.)
+
+ The usual display conventions apply even when there is a display
+table, for any character whose entry in the active display table is
+`nil'. Thus, when you set up a display table, you need only specify
+the characters for which you want unusual behavior.
+
+ These variables affect the way certain characters are displayed on
+the screen. Since they change the number of columns the characters
+occupy, they also affect the indentation functions.
+
+ - User Option: ctl-arrow
+ This buffer-local variable controls how control characters are
+ displayed. If it is non-`nil', they are displayed as a caret
+ followed by the character: `^A'. If it is `nil', they are
+ displayed as a backslash followed by three octal digits: `\001'.
+
+ - Variable: default-ctl-arrow
+ The value of this variable is the default value for `ctl-arrow' in
+ buffers that do not override it. *Note Default Value::.
+
+ - User Option: tab-width
+ The value of this variable is the spacing between tab stops used
+ for displaying tab characters in Emacs buffers. The default is 8.
+ Note that this feature is completely independent from the
+ user-settable tab stops used by the command `tab-to-tab-stop'.
+ *Note Indent Tabs::.
+
+\1f
+File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
+
+Display Tables
+==============
+
+You can use the "display table" feature to control how all 256 possible
+character codes display on the screen. This is useful for displaying
+European languages that have letters not in the ASCII character set.
+
+ The display table maps each character code into a sequence of
+"runes", each rune being an image that takes up one character position
+on the screen. You can also define how to display each rune on your
+terminal, using the "rune table".
+
+* Menu:
+
+* Display Table Format:: What a display table consists of.
+* Active Display Table:: How XEmacs selects a display table to use.
+* Character Descriptors:: Format of an individual element of a
+ display table.
+
+\1f
+File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
+
+Display Table Format
+--------------------
+
+A display table is an array of 256 elements. (In FSF Emacs, a display
+table is 262 elements. The six extra elements specify the truncation
+and continuation glyphs, etc. This method is very kludgey, and in
+XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
+used. *Note Truncation::.)
+
+ - Function: make-display-table
+ This creates and returns a display table. The table initially has
+ `nil' in all elements.
+
+ The 256 elements correspond to character codes; the Nth element says
+how to display the character code N. The value should be `nil', a
+string, a glyph, or a vector of strings and glyphs (*note Character
+Descriptors::). If an element is `nil', it says to display that
+character according to the usual display conventions (*note Usual
+Display::).
+
+ If you use the display table to change the display of newline
+characters, the whole buffer will be displayed as one long "line."
+
+ For example, here is how to construct a display table that mimics the
+effect of setting `ctl-arrow' to a non-`nil' value:
+
+ (setq disptab (make-display-table))
+ (let ((i 0))
+ (while (< i 32)
+ (or (= i ?\t) (= i ?\n)
+ (aset disptab i (concat "^" (char-to-string (+ i 64)))))
+ (setq i (1+ i)))
+ (aset disptab 127 "^?"))
+
+\1f
+File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
+
+Active Display Table
+--------------------
+
+The active display table is controlled by the variable
+`current-display-table'. This is a specifier, which means that you can
+specify separate values for it in individual buffers, windows, frames,
+and devices, as well as a global value. It also means that you cannot
+set this variable using `setq'; use `set-specifier' instead. *Note
+Specifiers::. (FSF Emacs uses `window-display-table',
+`buffer-display-table', `standard-display-table', etc. to control the
+display table. However, specifiers are a cleaner and more powerful way
+of doing the same thing. FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection to a
+"glyph table" and such. Note that "glyph" has a different meaning in
+XEmacs.)
+
+ - Variable: current-display-table
+ The display table currently in use. This is a specifier.
+
+ Display tables are used to control how characters are displayed.
+ Each time that redisplay processes a character, it is looked up in
+ all the display tables that apply (obtained by calling
+ `specifier-instance' on `current-display-table' and any overriding
+ display tables specified in currently active faces). The first
+ entry found that matches the character determines how the
+ character is displayed. If there is no matching entry, the
+ default display method is used. (Non-control characters are
+ displayed as themselves and control characters are displayed
+ according to the buffer-local variable `ctl-arrow'. Control
+ characters are further affected by `control-arrow-glyph' and
+ `octal-escape-glyph'.)
+
+ Each instantiator in this specifier and the display-table
+ specifiers in faces is a display table or a list of such tables.
+ If a list, each table will be searched in turn for an entry
+ matching a particular character. Each display table is one of
+
+ * A vector, specifying values for characters starting at 0.
+
+ * A char table, either of type `char' or `generic'.
+
+ * A range table.
+
+ Each entry in a display table should be one of
+
+ * nil (this entry is ignored and the search continues).
+
+ * A character (use this character; if it happens to be the same
+ as the original character, default processing happens,
+ otherwise redisplay attempts to display this character
+ directly; #### At some point recursive display-table lookup
+ will be implemented).
+
+ * A string (display each character in the string directly; ####
+ At some point recursive display-table lookup will be
+ implemented).
+
+ * A glyph (display the glyph; #### At some point recursive
+ display-table lookup will be implemented when a string glyph
+ is being processed).
+
+ * A cons of the form (format "STRING") where STRING is a
+ printf-like spec used to process the character. ####
+ Unfortunately no formatting directives other than %% are
+ implemented.
+
+ * A vector (each element of the vector is processed recursively;
+ in such a case, nil elements in the vector are simply
+ ignored).
+
+ #### At some point in the near future, display tables are
+ likely to be expanded to include other features, such as
+ referencing characters in particular fonts and allowing the
+ character search to continue all the way up the chain of
+ specifier instantiators. These features are necessary to
+ properly display Unicode characters.
+
+ Individual faces can also specify an overriding display table; this
+is set using `set-face-display-table'. *Note Faces::.
+
+ If no display table can be determined for a particular window, then
+XEmacs uses the usual display conventions. *Note Usual Display::.
+
+\1f
+File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
+
+Character Descriptors
+---------------------
+
+Each element of the display-table vector describes how to display a
+particular character and is called a "character descriptor". A
+character descriptor can be:
+
+a string
+ Display this particular string wherever the character is to be
+ displayed.
+
+a glyph
+ Display this particular glyph wherever the character is to be
+ displayed.
+
+a vector
+ The vector may contain strings and/or glyphs. Display the
+ elements of the vector one after another wherever the character is
+ to be displayed.
+
+`nil'
+ Display according to the standard interpretation (*note Usual
+ Display::).
+
+\1f
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
+
+Beeping
+=======
+
+You can make XEmacs ring a bell, play a sound, or blink the screen to
+attract the user's attention. Be conservative about how often you do
+this; frequent bells can become irritating. Also be careful not to use
+beeping alone when signaling an error is appropriate. (*Note Errors::.)
+
+ - Function: ding &optional dont-terminate sound device
+ This function beeps, or flashes the screen (see `visible-bell'
+ below). It also terminates any keyboard macro currently executing
+ unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
+ should be a symbol specifying which sound to make. This sound
+ will be played if `visible-bell' is `nil'. (This only works if
+ sound support was compiled into the executable and you are running
+ on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+ PC. Otherwise you just get a beep.) The optional third argument
+ specifies what device to make the sound on, and defaults to the
+ selected device.
+
+ - Function: beep &optional dont-terminate sound device
+ This is a synonym for `ding'.
+
+ - User Option: visible-bell
+ This variable determines whether XEmacs should flash the screen to
+ represent a bell. Non-`nil' means yes, `nil' means no. On TTY
+ devices, this is effective only if the Termcap entry for the
+ terminal type has the visible bell flag (`vb') set.
+
+ - Variable: sound-alist
+ This variable holds an alist associating names with sounds. When
+ `beep' or `ding' is called with one of the name symbols, the
+ associated sound will be generated instead of the standard beep.
+
+ Each element of `sound-alist' is a list describing a sound. The
+ first element of the list is the name of the sound being defined.
+ Subsequent elements of the list are alternating keyword/value
+ pairs:
+
+ `sound'
+ A string of raw sound data, or the name of another sound to
+ play. The symbol `t' here means use the default X beep.
+
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
+
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
+
+ `duration'
+ If using the default X beep, the duration (milliseconds).
+
+ For compatibility, elements of `sound-alist' may also be:
+
+ * `( sound-name . <sound> )'
+
+ * `( sound-name <volume> <sound> )'
+
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
+
+ Caveats:
+
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
+
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
+
+ The following beep-types are used by XEmacs itself:
+
+ `auto-save-error'
+ when an auto-save does not succeed
+
+ `command-error'
+ when the XEmacs command loop catches an error
+
+ `undefined-key'
+ when you type a key that is undefined
+
+ `undefined-click'
+ when you use an undefined mouse-click combination
+
+ `no-completion'
+ during completing-read
+
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
+
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
+
+ `default'
+ used when nothing else is appropriate.
+
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
+
+ - User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
+
+ - Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
+
+ - Command: load-sound-file filename sound-name &optional volume
+ This function reads in an audio file and adds it to `sound-alist'.
+ The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
+ should be a symbol, specifying the name of the sound. If VOLUME
+ is specified, the sound will be played at that volume; otherwise,
+ the value of `bell-volume' will be used.
+
+ - Function: play-sound sound &optional volume device
+ This function plays sound SOUND, which should be a symbol
+ mentioned in `sound-alist'. If VOLUME is specified, it overrides
+ the value (if any) specified in `sound-alist'. DEVICE specifies
+ the device to play the sound on, and defaults to the selected
+ device.
+
+ - Command: play-sound-file file &optional volume device
+ This function plays the named sound file at volume VOLUME, which
+ defaults to `bell-volume'. DEVICE specifies the device to play
+ the sound on, and defaults to the selected device.
+
+\1f
+File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
+
+Hash Tables
+***********
+
+ - Function: hash-table-p object
+ This function returns `t' if OBJECT is a hash table, else `nil'.
+
+* Menu:
+
+* Introduction to Hash Tables:: Hash tables are fast data structures for
+ implementing simple tables (i.e. finite
+ mappings from keys to values).
+* Working With Hash Tables:: Hash table functions.
+* Weak Hash Tables:: Hash tables with special garbage-collection
+ behavior.
+
+\1f
+File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
+
+Introduction to Hash Tables
+===========================
+
+A "hash table" is a data structure that provides mappings from
+arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
+called "values". A key/value pair is sometimes called an "entry" in
+the hash table. There are many ways other than hash tables of
+implementing the same sort of mapping, e.g. association lists (*note
+Association Lists::) and property lists (*note Property Lists::), but
+hash tables provide much faster lookup when there are many entries in
+the mapping. Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+ Internally, hash tables are hashed using the "linear probing" hash
+table implementation method. This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found. To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search. This method is used in preference to
+double hashing because of changes in recent hardware. The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+ When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+ Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table. But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower. Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection. If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+ Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table. For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0. For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+ Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+ #s(hash-table size 20 data (foo 1 bar 2))
+
+ The structure syntax accepts the same keywords as `make-hash-table'
+(without the `:' character), as well as the additional keyword `data',
+which specifies the initial hash table contents.
+
+ - Function: make-hash-table &key `test' `size' `rehash-size'
+ `rehash-threshold' `weakness'
+ This function returns a new empty hash table object.
+
+ Keyword `:test' can be `eq', `eql' (default) or `equal'.
+ Comparison between keys is done using this function. If speed is
+ important, consider using `eq'. When storing strings in the hash
+ table, you will likely need to use `equal'.
+
+ Keyword `:size' specifies the number of keys likely to be inserted.
+ This number of entries can be inserted without enlarging the hash
+ table.
+
+ Keyword `:rehash-size' must be a float greater than 1.0, and
+ specifies the factor by which to increase the size of the hash
+ table when enlarging.
+
+ Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+ and specifies the load factor of the hash table which triggers
+ enlarging.
+
+ Non-standard keyword `:weakness' can be `nil' (default), `t',
+ `key-and-value', `key', `value' or `key-or-value'. `t' is an
+ alias for `key-and-value'.
+
+ A key-and-value-weak hash table, also known as a fully-weak or
+ simply as a weak hash table, is one whose pointers do not count as
+ GC referents: for any key-value pair in the hash table, if the only
+ remaining pointer to either the key or the value is in a weak hash
+ table, then the pair will be removed from the hash table, and the
+ key and value collected. A non-weak hash table (or any other
+ pointer) would prevent the object from being collected.
+
+ A key-weak hash table is similar to a fully-weak hash table except
+ that a key-value pair will be removed only if the key remains
+ unmarked outside of weak hash tables. The pair will remain in the
+ hash table if the key is pointed to by something other than a weak
+ hash table, even if the value is not.
+
+ A value-weak hash table is similar to a fully-weak hash table
+ except that a key-value pair will be removed only if the value
+ remains unmarked outside of weak hash tables. The pair will
+ remain in the hash table if the value is pointed to by something
+ other than a weak hash table, even if the key is not.
+
+ A key-or-value-weak hash table is similar to a fully-weak hash
+ table except that a key-value pair will be removed only if the
+ value and the key remain unmarked outside of weak hash tables.
+ The pair will remain in the hash table if the value or key are
+ pointed to by something other than a weak hash table, even if the
+ other is not.
+
+ - Function: copy-hash-table hash-table
+ This function returns a new hash table which contains the same
+ keys and values as HASH-TABLE. The keys and values will not
+ themselves be copied.
+
+ - Function: hash-table-count hash-table
+ This function returns the number of entries in HASH-TABLE.
+
+ - Function: hash-table-test hash-table
+ This function returns the test function of HASH-TABLE. This can
+ be one of `eq', `eql' or `equal'.
+
+ - Function: hash-table-size hash-table
+ This function returns the current number of slots in HASH-TABLE,
+ whether occupied or not.
+
+ - Function: hash-table-rehash-size hash-table
+ This function returns the current rehash size of HASH-TABLE. This
+ is a float greater than 1.0; the factor by which HASH-TABLE is
+ enlarged when the rehash threshold is exceeded.
+
+ - Function: hash-table-rehash-threshold hash-table
+ This function returns the current rehash threshold of HASH-TABLE.
+ This is a float between 0.0 and 1.0; the maximum "load factor" of
+ HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
+
+ - Function: hash-table-weakness hash-table
+ This function returns the weakness of HASH-TABLE. This can be one
+ of `nil', `t', `key' or `value'.
+
+\1f
+File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
+
+Working With Hash Tables
+========================
+
+ - Function: puthash key value hash-table
+ This function hashes KEY to VALUE in HASH-TABLE.
+
+ - Function: gethash key hash-table &optional default
+ This function finds the hash value for KEY in HASH-TABLE. If
+ there is no entry for KEY in HASH-TABLE, DEFAULT is returned
+ (which in turn defaults to `nil').
+
+ - Function: remhash key hash-table
+ This function removes the entry for KEY from HASH-TABLE. Does
+ nothing if there is no entry for KEY in HASH-TABLE.
+
+ - Function: clrhash hash-table
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
+
+ - Function: maphash function hash-table
+ This function maps FUNCTION over entries in HASH-TABLE, calling it
+ with two args, each key and value in the hash table.
+
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
+
+\1f
+File: lispref.info, Node: Weak Hash Tables, Prev: Working With Hash Tables, Up: Hash Tables
+
+Weak Hash Tables
+================
+
+A "weak hash table" is a special variety of hash table whose elements
+do not count as GC referents. For any key-value pair in such a hash
+table, if either the key or value (or in some cases, if one particular
+one of the two) has no references to it outside of weak hash tables
+(and similar structures such as weak lists), the pair will be removed
+from the table, and the key and value collected. A non-weak hash table
+(or any other pointer) would prevent the objects from being collected.
+
+ Weak hash tables are useful for keeping track of information in a
+non-obtrusive way, for example to implement caching. If the cache
+contains objects such as buffers, markers, image instances, etc. that
+will eventually disappear and get garbage-collected, using a weak hash
+table ensures that these objects are collected normally rather than
+remaining around forever, long past their actual period of use.
+(Otherwise, you'd have to explicitly map over the hash table every so
+often and remove unnecessary elements.)
+
+ There are four types of weak hash tables:
+
+key-and-value-weak hash tables
+ In these hash tables, also known as fully weak or simply as weak
+ hash tables, a pair disappears if either the key or the value is
+ unreferenced outside of the table.
+
+key-weak hash tables
+ In these hash tables, a pair disappears if the key is unreferenced
+ outside of the table, regardless of how the value is referenced.
+
+value-weak hash tables
+ In these hash tables, a pair disappears if the value is
+ unreferenced outside of the table, regardless of how the key is
+ referenced.
+
+key-or-value-weak hash tables
+ In these hash tables, a pair disappears if both the key and the
+ value are unreferenced outside of the table.
+
+ Also see *Note Weak Lists::.
+
+ Weak hash tables are created by specifying the `:weakness' keyword to
+`make-hash-table'.
+
+\1f
+File: lispref.info, Node: Range Tables, Next: Databases, Prev: Hash Tables, Up: Top
+
+Range Tables
+************
+
+A range table is a table that efficiently associated values with ranges
+of integers.
+
+ Note that range tables have a read syntax, like this:
+
+ #s(range-table data ((-3 2) foo (5 20) bar))
+
+ This maps integers in the range (-3, 2) to `foo' and integers in the
+range (5, 20) to `bar'.
+
+ - Function: range-table-p object
+ Return non-`nil' if OBJECT is a range table.
+
+* Menu:
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+ integers to values.
+* Working With Range Tables:: Range table functions.
+
+\1f
+File: lispref.info, Node: Introduction to Range Tables, Next: Working With Range Tables, Up: Range Tables
+
+Introduction to Range Tables
+============================
+
+ - Function: make-range-table
+ Make a new, empty range table.
+
+ - Function: copy-range-table range-table
+ This function returns a new range table which contains the same
+ values for the same ranges as RANGE-TABLE. The values will not
+ themselves be copied.
+
+\1f
+File: lispref.info, Node: Working With Range Tables, Prev: Introduction to Range Tables, Up: Range Tables
+
+Working With Range Tables
+=========================
+
+ - Function: get-range-table pos range-table &optional default
+ This function finds value for position POS in RANGE-TABLE. If
+ there is no corresponding value, return DEFAULT (defaults to
+ `nil').
+
+ - Function: put-range-table start end value range-table
+ This function sets the value for range (START, END) to be VALUE in
+ RANGE-TABLE.
+
+ - Function: remove-range-table start end range-table
+ This function removes the value for range (START, END) in
+ RANGE-TABLE.
+
+ - Function: clear-range-table range-table
+ This function flushes RANGE-TABLE.
+
+ - Function: map-range-table function range-table
+ This function maps FUNCTION over entries in RANGE-TABLE, calling
+ it with three args, the beginning and end of the range and the
+ corresponding value.
+
+\1f
+File: lispref.info, Node: Databases, Next: Processes, Prev: Range Tables, Up: Top
+
+Databases
+*********
+
+ - Function: databasep object
+ This function returns non-`nil' if OBJECT is a database.
+
+* Menu:
+
+* Connecting to a Database::
+* Working With a Database::
+* Other Database Functions::
+
+\1f
+File: lispref.info, Node: Connecting to a Database, Next: Working With a Database, Up: Databases
+
+Connecting to a Database
+========================
+
+ - Function: open-database file &optional type subtype access mode
+ This function opens database FILE, using database method TYPE and
+ SUBTYPE, with access rights ACCESS and permissions MODE. ACCESS
+ can be any combination of `r' `w' and `+', for read, write, and
+ creation flags.
+
+ TYPE can have the value `'dbm' or `'berkeley-db' to select the
+ type of database file to use. (Note: XEmacs may not support both
+ of these types.)
+
+ For a TYPE of `'dbm', there are no subtypes, so SUBTYPE should be
+ `nil'.
+
+ For a TYPE of `'berkeley-db', the following subtypes are
+ available: `'hash', `'btree', and `'recno'. See the manpages for
+ the Berkeley DB functions for more information about these types.
+
+ - Function: close-database database
+ This function closes database DATABASE.
+
+ - Function: database-live-p object
+ This function returns `t' if OBJECT is an active database, else
+ `nil'.
+
+\1f
+File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
+
+Working With a Database
+=======================
+
+ - Function: get-database key database &optional default
+ This function finds the value for KEY in DATABASE. If there is no
+ corresponding value, DEFAULT is returned (`nil' if DEFAULT is
+ omitted).
+
+ - Function: map-database function database
+ This function maps FUNCTION over entries in DATABASE, calling it
+ with two args, each key and value in the database.
+
+ - Function: put-database key value database &optional replace
+ This function stores KEY and VALUE in DATABASE. If optional
+ fourth arg REPLACE is non-`nil', replace any existing entry in the
+ database.
+
+ - Function: remove-database key database
+ This function removes KEY from DATABASE.
+
+\1f
+File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
+
+Other Database Functions
+========================
+
+ - Function: database-file-name database
+ This function returns the filename associated with DATABASE.
+
+ - Function: database-last-error &optional database
+ This function returns the last error associated with DATABASE.
+
+ - Function: database-subtype database
+ This function returns the subtype of DATABASE, if any.
+
+ - Function: database-type database
+ This function returns the type of DATABASE.
+
+\1f
+File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
+
+Processes
+*********
+
+In the terminology of operating systems, a "process" is a space in
+which a program can execute. XEmacs runs in a process. XEmacs Lisp
+programs can invoke other programs in processes of their own. These are
+called "subprocesses" or "child processes" of the XEmacs process, which
+is their "parent process".
+
+ A subprocess of XEmacs may be "synchronous" or "asynchronous",
+depending on how it is created. When you create a synchronous
+subprocess, the Lisp program waits for the subprocess to terminate
+before continuing execution. When you create an asynchronous
+subprocess, it can run in parallel with the Lisp program. This kind of
+subprocess is represented within XEmacs by a Lisp object which is also
+called a "process". Lisp programs can use this object to communicate
+with the subprocess or to control it. For example, you can send
+signals, obtain status information, receive output from the process, or
+send input to it.
+
+ - Function: processp object
+ This function returns `t' if OBJECT is a process, `nil' otherwise.
+
+* Menu:
+
+* Subprocess Creation:: Functions that start subprocesses.
+* Synchronous Processes:: Details of using synchronous subprocesses.
+* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
+ for data sent to and from a subprocess.
+* 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.
+* Process Window Size:: Changing the logical window size of a process.
+* Transaction Queues:: Transaction-based communication with subprocesses.
+* Network:: Opening network connections.
+
+\1f
+File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
+
+Functions that Create Subprocesses
+==================================
+
+There are three functions that create a new subprocess in which to run
+a program. One of them, `start-process', creates an asynchronous
+process and returns a process object (*note Asynchronous Processes::).
+The other two, `call-process' and `call-process-region', create a
+synchronous process and do not return a process object (*note
+Synchronous Processes::).
+
+ Synchronous and asynchronous processes are explained in the following
+sections. Since the three functions are all called in a similar
+fashion, their common arguments are described here.
+
+ In all cases, the function's PROGRAM argument specifies the program
+to be run. An error is signaled if the file is not found or cannot be
+executed. If the file name is relative, the variable `exec-path'
+contains a list of directories to search. Emacs initializes
+`exec-path' when it starts up, based on the value of the environment
+variable `PATH'. The standard file name constructs, `~', `.', and
+`..', are interpreted as usual in `exec-path', but environment variable
+substitutions (`$HOME', etc.) are not recognized; use
+`substitute-in-file-name' to perform them (*note File Name Expansion::).
+
+ Each of the subprocess-creating functions has a BUFFER-OR-NAME
+argument which specifies where the standard output from the program will
+go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
+a filter function handles it. (*Note Filter Functions::, and *Note
+Read and Print::.) Normally, you should avoid having multiple
+processes send output to the same buffer because their output would be
+intermixed randomly.
+
+ All three of the subprocess-creating functions have a `&rest'
+argument, ARGS. The ARGS must all be strings, and they are supplied to
+PROGRAM as separate command line arguments. Wildcard characters and
+other shell constructs are not allowed in these strings, since they are
+passed directly to the specified program.
+
+ *Please note:* The argument PROGRAM contains only the name of the
+program; it may not contain any command-line arguments. You must use
+ARGS to provide those.
+
+ If you want to use features of the shell, then invoke the shell
+directly using, for example, PROGRAM of `"sh"', and ARGS of `"-c"' and
+"COMMAND LINE...".
+
+ The subprocess gets its current directory from the value of
+`default-directory' (*note File Name Expansion::).
+
+ The subprocess inherits its environment from XEmacs; but you can
+specify overrides for it with `process-environment'. *Note System
+Environment::.
+
+ - Variable: exec-directory
+ The value of this variable is the name of a directory (a string)
+ that contains programs that come with XEmacs, that are intended
+ for XEmacs to invoke. The program `wakeup' is an example of such
+ a program; the `display-time' command uses it to get a reminder
+ once per minute.
+
+ - User Option: exec-path
+ The value of this variable is a list of directories to search for
+ programs to run in subprocesses. Each element is either the name
+ of a directory (i.e., a string), or `nil', which stands for the
+ default directory (which is the value of `default-directory').
+
+ The value of `exec-path' is used by `call-process' and
+ `start-process' when the PROGRAM argument is not an absolute file
+ name.
+
+\1f
+File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
+
+Creating a Synchronous Process
+==============================
+
+After a "synchronous process" is created, XEmacs waits for the process
+to terminate before continuing. Starting Dired is an example of this:
+it runs `ls' in a synchronous process, then modifies the output
+slightly. Because the process is synchronous, the entire directory
+listing arrives in the buffer before XEmacs tries to do anything with
+it.
+
+ While Emacs waits for the synchronous subprocess to terminate, the
+user can quit by typing `C-g'. The first `C-g' tries to kill the
+subprocess with a `SIGINT' signal; but it waits until the subprocess
+actually terminates before quitting. If during that time the user
+types another `C-g', that kills the subprocess instantly with `SIGKILL'
+and quits immediately. *Note Quitting::.
+
+ The synchronous subprocess functions returned `nil' in version 18.
+In version 19, they return an indication of how the process terminated.
+
+ - Function: call-process program &optional infile destination display
+ &rest args
+ This function calls PROGRAM in a separate process and waits for it
+ to finish.
+
+ The standard input for the process comes from file INFILE if
+ INFILE is not `nil' and from `/dev/null' otherwise. The argument
+ DESTINATION says where to put the process output. Here are the
+ possibilities:
+
+ a buffer
+ Insert the output in that buffer, before point. This
+ includes both the standard output stream and the standard
+ error stream of the process.
+
+ a string
+ Find or create a buffer with that name, then insert the
+ output in that buffer, before point.
+
+ `t'
+ Insert the output in the current buffer, before point.
+
+ `nil'
+ Discard the output.
+
+ 0
+ Discard the output, and return immediately without waiting
+ for the subprocess to finish.
+
+ In this case, the process is not truly synchronous, since it
+ can run in parallel with Emacs; but you can think of it as
+ synchronous in that Emacs is essentially finished with the
+ subprocess as soon as this function returns.
+
+ (REAL-DESTINATION ERROR-DESTINATION)
+ Keep the standard output stream separate from the standard
+ error stream; deal with the ordinary output as specified by
+ REAL-DESTINATION, and dispose of the error output according
+ to ERROR-DESTINATION. The value `nil' means discard it, `t'
+ means mix it with the ordinary output, and a string specifies
+ a file name to redirect error output into.
+
+ You can't directly specify a buffer to put the error output
+ in; that is too difficult to implement. But you can achieve
+ this result by sending the error output to a temporary file
+ and then inserting the file into a buffer.
+
+ If DISPLAY is non-`nil', then `call-process' redisplays the buffer
+ as output is inserted. Otherwise the function does no redisplay,
+ and the results become visible on the screen only when XEmacs
+ redisplays that buffer in the normal course of events.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The value returned by `call-process' (unless you told it not to
+ wait) indicates the reason for process termination. A number
+ gives the exit status of the subprocess; 0 means success, and any
+ other value means failure. If the process terminated with a
+ signal, `call-process' returns a string describing the signal.
+
+ In the examples below, the buffer `foo' is current.
+
+ (call-process "pwd" nil t)
+ => nil
+
+ ---------- Buffer: foo ----------
+ /usr/user/lewis/manual
+ ---------- Buffer: foo ----------
+
+ (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
+ => nil
+
+ ---------- Buffer: bar ----------
+ lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+
+ ---------- Buffer: bar ----------
+
+ The `insert-directory' function contains a good example of the use
+ of `call-process':
+
+ (call-process insert-directory-program nil t nil switches
+ (if full-directory-p
+ (concat (file-name-as-directory file) ".")
+ file))
+
+ - Function: call-process-region start end program &optional deletep
+ destination displayp &rest args
+ This function sends the text between START to END as standard
+ input to a process running PROGRAM. It deletes the text sent if
+ DELETEP is non-`nil'; this is useful when BUFFER is `t', to insert
+ the output in the current buffer.
+
+ The arguments DESTINATION and DISPLAYP control what to do with the
+ output from the subprocess, and whether to update the display as
+ it comes in. For details, see the description of `call-process',
+ above. If DESTINATION is the integer 0, `call-process-region'
+ discards the output and returns `nil' immediately, without waiting
+ for the subprocess to finish.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ The return value of `call-process-region' is just like that of
+ `call-process': `nil' if you told it to return without waiting;
+ otherwise, a number or string which indicates how the subprocess
+ terminated.
+
+ In the following example, we use `call-process-region' to run the
+ `cat' utility, with standard input being the first five characters
+ in buffer `foo' (the word `input'). `cat' copies its standard
+ input into its standard output. Since the argument DESTINATION is
+ `t', this output is inserted in the current buffer.
+
+ ---------- Buffer: foo ----------
+ input-!-
+ ---------- Buffer: foo ----------
+
+ (call-process-region 1 6 "cat" nil t)
+ => nil
+
+ ---------- Buffer: foo ----------
+ inputinput-!-
+ ---------- Buffer: foo ----------
+
+ The `shell-command-on-region' command uses `call-process-region'
+ like this:
+
+ (call-process-region
+ start end
+ shell-file-name ; Name of program.
+ nil ; Do not delete region.
+ buffer ; Send output to `buffer'.
+ nil ; No redisplay during output.
+ "-c" command) ; Arguments for the shell.
+
+\1f
+File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
+
+MS-DOS Subprocesses
+===================
+
+On MS-DOS, you must indicate whether the data going to and from a
+synchronous subprocess are text or binary. Text data requires
+translation between the end-of-line convention used within Emacs (a
+single newline character) and the convention used outside Emacs (the
+two-character sequence, CRLF).
+
+ The variable `binary-process-input' applies to input sent to the
+subprocess, and `binary-process-output' applies to output received from
+it. A non-`nil' value means the data is non-text; `nil' means the data
+is text, and calls for conversion.
+
+ - Variable: binary-process-input
+ If this variable is `nil', convert newlines to CRLF sequences in
+ the input to a synchronous subprocess.
+
+ - Variable: binary-process-output
+ If this variable is `nil', convert CRLF sequences to newlines in
+ the output from a synchronous subprocess.
+
+ *Note Files and MS-DOS::, for related information.
+
+\1f
+File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
+
+Creating an Asynchronous Process
+================================
+
+After an "asynchronous process" is created, Emacs and the Lisp program
+both continue running immediately. The process may thereafter run in
+parallel with Emacs, and the two may communicate with each other using
+the functions described in following sections. Here we describe how to
+create an asynchronous process with `start-process'.
+
+ - Function: start-process name buffer-or-name program &rest args
+ This function creates a new asynchronous subprocess and starts the
+ program PROGRAM running in it. It returns a process object that
+ stands for the new subprocess in Lisp. The argument NAME
+ specifies the name for the process object; if a process with this
+ name already exists, then NAME is modified (by adding `<1>', etc.)
+ to be unique. The buffer BUFFER-OR-NAME is the buffer to
+ associate with the process.
+
+ The remaining arguments, ARGS, are strings that specify command
+ line arguments for the program.
+
+ In the example below, the first process is started and runs
+ (rather, sleeps) for 100 seconds. Meanwhile, the second process
+ is started, and given the name `my-process<1>' for the sake of
+ uniqueness. It inserts the directory listing at the end of the
+ buffer `foo', before the first process finishes. Then it
+ finishes, and a message to that effect is inserted in the buffer.
+ Much later, the first process finishes, and another message is
+ inserted in the buffer for it.
+
+ (start-process "my-process" "foo" "sleep" "100")
+ => #<process my-process>
+
+ (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
+ => #<process my-process<1>>
+
+ ---------- Buffer: foo ----------
+ total 2
+ lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
+ -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
+
+ Process my-process<1> finished
+
+ Process my-process finished
+ ---------- Buffer: foo ----------
+
+ - Function: start-process-shell-command name buffer-or-name command
+ &rest command-args
+ This function is like `start-process' except that it uses a shell
+ to execute the specified command. The argument COMMAND is a shell
+ command name, and COMMAND-ARGS are the arguments for the shell
+ command.
+
+ - Variable: process-connection-type
+ This variable controls the type of device used to communicate with
+ asynchronous subprocesses. If it is non-`nil', then PTYs are
+ used, when available. Otherwise, pipes are used.
+
+ PTYs are usually preferable for processes visible to the user, as
+ in Shell mode, because they allow job control (`C-c', `C-z', etc.)
+ to work between the process and its children whereas pipes do not.
+ For subprocesses used for internal purposes by programs, it is
+ often better to use a pipe, because they are more efficient. In
+ addition, the total number of PTYs is limited on many systems and
+ it is good not to waste them. A rule of thumb is to use ptys for
+ processes the user interacts with directly, and pipes for
+ processes that are hidden from the user.
+
+ The value `process-connection-type' is used when `start-process'
+ is called. So you can specify how to communicate with one
+ subprocess by binding the variable around the call to
+ `start-process'.
+
+ (let ((process-connection-type nil)) ; Use a pipe.
+ (start-process ...))
+
+ To determine whether a given subprocess actually got a pipe or a
+ PTY, use the function `process-tty-name' (*note Process
+ Information::).
+
+ Lisp functions that manipulate processes usually accept a PROCESS
+argument. Besides using an actual process object for this argument, you
+can use a process name, a buffer object, the name of a buffer, or
+`nil'. Specifying a buffer or buffer name for the PROCESS argument
+means use the process associated with the buffer (or the most recent
+one, if there is more than one). `nil' means use the process
+associated with the current buffer. *Note Process Information::.
+*Note Process Buffers::.
+
+\1f
+File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
+
+Deleting Processes
+==================
+
+"Deleting a process" disconnects XEmacs immediately from the
+subprocess, and removes it from the list of active processes. It sends
+a signal to the subprocess to make the subprocess terminate, but this is
+not guaranteed to happen immediately. The process object itself
+continues to exist as long as other Lisp objects point to it.
+
+ You can delete a process explicitly at any time. Processes are
+deleted automatically after they terminate, but not necessarily right
+away. If you delete a terminated process explicitly before it is
+deleted automatically, no harm results.
+
+ - Variable: delete-exited-processes
+ This variable controls automatic deletion of processes that have
+ terminated (due to calling `exit' or to a signal). If it is
+ `nil', then they continue to exist until the user runs
+ `list-processes'. Otherwise, they are deleted immediately after
+ they exit.
+
+ - Function: delete-process name
+ This function deletes the process associated with NAME, killing it
+ with a `SIGHUP' signal. The argument NAME may be a process, the
+ name of a process, a buffer, or the name of a buffer.
+
+ (delete-process "*shell*")
+ => nil
+
+ - Function: process-kill-without-query process &optional
+ require-query-p
+ This function declares that XEmacs need not query the user if
+ PROCESS is still running when XEmacs is exited. The process will
+ be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
+ _will_ query the user (this is the default). The return value is
+ `t' if a query was formerly required, and `nil' otherwise.
+
+ (process-kill-without-query (get-process "shell"))
+ => t
+
+\1f
+File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
+
+Process Information
+===================
+
+Several functions return information about processes. `list-processes'
+is provided for interactive use.
+
+ - Command: list-processes
+ This command displays a listing of all living processes. In
+ addition, it finally deletes any process whose status was `Exited'
+ or `Signaled'. It returns `nil'.
+
+ - Function: process-list
+ This function returns a list of all processes that have not been
+ deleted.
+
+ (process-list)
+ => (#<process display-time> #<process shell>)
+
+ - Function: get-process process-name
+ This function returns the process named PROCESS-NAME. If
+ PROCESS-NAME is a string and there is no process with that name,
+ the value is `nil'. If PROCESS-NAME is actually a process, it is
+ returned as given. (That is not very useful, so the argument is
+ usually a name.) For example:
+
+ (get-process "shell")
+ => #<process shell>
+
+ - Function: process-command process
+ This function returns the command that was executed to start
+ PROCESS. This is a list of strings, the first string being the
+ program executed and the rest of the strings being the arguments
+ that were given to the program.
+
+ (process-command (get-process "shell"))
+ => ("/bin/csh" "-i")
+
+ - Function: process-id process
+ This function returns the PID of PROCESS. This is an integer that
+ distinguishes the process PROCESS from all other processes running
+ on the same computer at the current time. The PID of a process is
+ chosen by the operating system kernel when the process is started
+ and remains constant as long as the process exists.
+
+ - Function: process-name process
+ This function returns the name of PROCESS.
+
+ - Function: process-status process
+ This function returns the status of PROCESS as a symbol. The
+ argument PROCESS must be a process, a buffer, a process name
+ (string) or a buffer name (string).
+
+ The possible values for an actual subprocess are:
+
+ `run'
+ for a process that is running.
+
+ `stop'
+ for a process that is stopped but continuable.
+
+ `exit'
+ for a process that has exited.
+
+ `signal'
+ for a process that has received a fatal signal.
+
+ `open'
+ for a network connection that is open.
+
+ `closed'
+ for a network connection that is closed. Once a connection
+ is closed, you cannot reopen it, though you might be able to
+ open a new connection to the same place.
+
+ `nil'
+ if PROCESS does not identify an existing process.
+
+ (process-status "shell")
+ => run
+ (process-status (get-buffer "*shell*"))
+ => run
+ x
+ => #<process xx<1>>
+ (process-status x)
+ => exit
+
+ For a network connection, `process-status' returns one of the
+ symbols `open' or `closed'. The latter means that the other side
+ closed the connection, or XEmacs did `delete-process'.
+
+ In earlier Emacs versions (prior to version 19), the status of a
+ network connection was `run' if open, and `exit' if closed.
+
+ - Function: process-kill-without-query-p process
+ This function returns whether PROCESS will be killed without
+ querying the user, if it is running when XEmacs is exited. The
+ default value is `nil'.
+
+ - Function: process-exit-status process
+ This function returns the exit status of PROCESS or the signal
+ number that killed it. (Use the result of `process-status' to
+ determine which of those it is.) If PROCESS has not yet
+ terminated, the value is 0.
+
+ - Function: process-tty-name process
+ This function returns the terminal name that PROCESS is using for
+ its communication with Emacs--or `nil' if it is using pipes
+ instead of a terminal (see `process-connection-type' in *Note
+ Asynchronous Processes::).
+
+\1f
+File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
+
+Sending Input to Processes
+==========================
+
+Asynchronous subprocesses receive input when it is sent to them by
+XEmacs, which is done with the functions in this section. You must
+specify the process to send input to, and the input data to send. The
+data appears on the "standard input" of the subprocess.
+
+ Some operating systems have limited space for buffered input in a
+PTY. On these systems, XEmacs sends long input in chunks, with EOF
+characters added amidst the other characters, to force the operating
+system to periodically drain the input buffer. For most programs,
+these EOFs do no harm.
+
+ - Function: process-send-string process string &optional start end
+ This function sends PROCESS the contents of STRING as standard
+ input.
+
+ The argument PROCESS may be a process or the name of a process, or
+ a buffer or the name of a buffer, in which case the buffer's
+ process is used. If it is `nil', the current buffer's process is
+ used.
+
+ Optional arguments START and END specify part of STRING; see
+ `substring'.
+
+ The function returns `nil'.
+
+ (process-send-string "shell<1>" "ls\n")
+ => nil
- (eq x y)
+
+ ---------- Buffer: *shell* ----------
+ ...
+ introduction.texi syntax-tables.texi~
+ introduction.texi~ text.texi
+ introduction.txt text.texi~
+ ...
+ ---------- Buffer: *shell* ----------
+
+ - Function: process-send-region process start end &optional buffer
+ This function sends the text in the region defined by START and
+ END as standard input to PROCESS.
+
+ The argument PROCESS may be a process or the name of a process, or
+ a buffer or the name of a buffer, in which case the buffer's
+ process is used. If it is `nil', the current buffer's process is
+ used.
+
+ An error is signaled unless both START and END are integers or
+ markers that indicate positions in the current buffer. (It is
+ unimportant which number is larger.)
+
+ - Function: process-send-eof &optional process
+ This function makes PROCESS see an end-of-file in its input. The
+ EOF comes after any text already sent to it.
+
+ PROCESS may be a process, a buffer, the name of a process or
+ buffer, or `nil', indicating the current buffer's process. An
+ error is signaled if PROCESS does not identify any process.
+
+ The function returns the process object identified by PROCESS.
+
+ (process-send-eof "shell")
+ => "shell"
+
+\1f
+File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
+
+Sending Signals to Processes
+============================
+
+"Sending a signal" to a subprocess is a way of interrupting its
+activities. There are several different signals, each with its own
+meaning. The set of signals and their names is defined by the operating
+system. For example, the signal `SIGINT' means that the user has typed
+`C-c', or that some analogous thing has happened.
+
+ Each signal has a standard effect on the subprocess. Most signals
+kill the subprocess, but some stop or resume execution instead. Most
+signals can optionally be handled by programs; if the program handles
+the signal, then we can say nothing in general about its effects.
+
+ The set of signals and their names is defined by the operating
+system; XEmacs has facilities for sending only a few of the signals
+that are defined. XEmacs can send signals only to its own subprocesses.
+
+ You can send signals explicitly by calling the functions in this
+section. XEmacs also sends signals automatically at certain times:
+killing a buffer sends a `SIGHUP' signal to all its associated
+processes; killing XEmacs sends a `SIGHUP' signal to all remaining
+processes. (`SIGHUP' is a signal that indicates that the connection
+between the user and the process is broken, for example if a connection
+via a telephone line is hung up.)
+
+ Each of the signal-sending functions takes two optional arguments:
+PROCESS and CURRENT-GROUP.
+
+ The argument PROCESS must be either a process or a buffer, the name
+of one, or `nil'. If it is `nil', the process defaults to the process
+associated with the current buffer. An error is signaled if PROCESS
+does not identify a process.
+
+ The argument CURRENT-GROUP is a flag that makes a difference when
+you are running a job-control shell as an XEmacs subprocess. If it is
+non-`nil', then the signal is sent to the current foreground process
+group of the terminal that XEmacs uses to communicate with the
+subprocess. If the process is a job-control shell, this means the
+shell's current subjob. If it is `nil', the signal is sent to the
+process group of the immediate subprocess of XEmacs. If the subprocess
+is a job-control shell, this is the shell itself.
+
+ The flag CURRENT-GROUP has no effect when a pipe is used to
+communicate with the subprocess, because the operating system does not
+support the distinction in the case of pipes. For the same reason,
+job-control shells won't work when a pipe is used. See
+`process-connection-type' in *Note Asynchronous Processes::.
+
+ Some of the functions below take a SIGNAL argument, which identifies
+a signal to be sent. It must be either an integer or a symbol which
+names the signal, like `SIGSEGV'.
+
+ - Function: process-send-signal signal &optional process current-group
+ This function sends the signal SIGNAL to the process PROCESS. The
+ following functions can be implemented in terms of
+ `process-send-signal'.
+
+ - Function: interrupt-process &optional process current-group
+ This function interrupts the process PROCESS by sending the signal
+ `SIGINT'. Outside of XEmacs, typing the "interrupt character"
+ (normally `C-c') sends this signal. When the argument
+ CURRENT-GROUP is non-`nil', you can think of this function as
+ "typing `C-c'" on the terminal by which XEmacs talks to the
+ subprocess.
+
+ - Function: kill-process &optional process current-group
+ This function kills the process PROCESS by sending the signal
+ `SIGKILL'. This signal kills the subprocess immediately, and
+ cannot be handled by the subprocess.
+
+ - Function: quit-process &optional process current-group
+ This function sends the signal `SIGQUIT' to the process PROCESS.
+ This signal is the one sent by the "quit character" (usually
+ `C-\') when you are not inside XEmacs.
+
+ - Function: stop-process &optional process current-group
+ This function stops the process PROCESS by sending the signal
+ `SIGTSTP'. Use `continue-process' to resume its execution.
+
+ On systems with job control, the "stop character" (usually `C-z')
+ sends this signal (outside of XEmacs). When CURRENT-GROUP is
+ non-`nil', you can think of this function as "typing `C-z'" on the
+ terminal XEmacs uses to communicate with the subprocess.
+
+ - Function: continue-process &optional process current-group
+ This function resumes execution of the process PROCESS by sending
+ it the signal `SIGCONT'. This presumes that PROCESS was stopped
+ previously.
+
+ - Command: signal-process pid signal
+ This function sends a signal to the process with process id PID,
+ which need not be a child of XEmacs. The argument SIGNAL
+ specifies which signal to send.
+
+\1f
+File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
+
+Receiving Output from Processes
+===============================
+
+There are two ways to receive the output that a subprocess writes to
+its standard output stream. The output can be inserted in a buffer,
+which is called the associated buffer of the process, or a function
+called the "filter function" can be called to act on the output. If
+the process has no buffer and no filter function, its output is
+discarded.
+
+* Menu:
+
+* Process Buffers:: If no filter, output is put in a buffer.
+* Filter Functions:: Filter functions accept output from the process.
+* Accepting Output:: Explicitly permitting subprocess output.
+ Waiting for subprocess output.
+
+\1f
+File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
+
+Process Buffers
+---------------
+
+A process can (and usually does) have an "associated buffer", which is
+an ordinary Emacs buffer that is used for two purposes: storing the
+output from the process, and deciding when to kill the process. You
+can also use the buffer to identify a process to operate on, since in
+normal practice only one process is associated with any given buffer.
+Many applications of processes also use the buffer for editing input to
+be sent to the process, but this is not built into XEmacs Lisp.
+
+ Unless the process has a filter function (*note Filter Functions::),
+its output is inserted in the associated buffer. The position to insert
+the output is determined by the `process-mark', which is then updated
+to point to the end of the text just inserted. Usually, but not
+always, the `process-mark' is at the end of the buffer.
+
+ - Function: process-buffer process
+ This function returns the associated buffer of the process PROCESS.
+
+ (process-buffer (get-process "shell"))
+ => #<buffer *shell*>
+
+ - Function: process-mark process
+ This function returns the process marker for PROCESS, which is the
+ marker that says where to insert output from the process.
+
+ If PROCESS does not have a buffer, `process-mark' returns a marker
+ that points nowhere.
+
+ Insertion of process output in a buffer uses this marker to decide
+ where to insert, and updates it to point after the inserted text.
+ That is why successive batches of output are inserted
+ consecutively.
+
+ Filter functions normally should use this marker in the same
+ fashion as is done by direct insertion of output in the buffer. A
+ good example of a filter function that uses `process-mark' is
+ found at the end of the following section.
+
+ When the user is expected to enter input in the process buffer for
+ transmission to the process, the process marker is useful for
+ distinguishing the new input from previous output.
+
+ - Function: set-process-buffer process buffer
+ This function sets the buffer associated with PROCESS to BUFFER.
+ If BUFFER is `nil', the process becomes associated with no buffer.
+
+ - Function: get-buffer-process buffer-or-name
+ This function returns the process associated with BUFFER-OR-NAME.
+ If there are several processes associated with BUFFER-OR-NAME,
+ then one is chosen. (Presently, the one chosen is the one most
+ recently created.) It is usually a bad idea to have more than one
+ process associated with the same buffer.
+
+ (get-buffer-process "*shell*")
+ => #<process shell>
+
+ Killing the process's buffer deletes the process, which kills the
+ subprocess with a `SIGHUP' signal (*note Signals to Processes::).
+
+\1f
+File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
+
+Process Filter Functions
+------------------------
+
+A process "filter function" is a function that receives the standard
+output from the associated process. If a process has a filter, then
+_all_ output from that process is passed to the filter. The process
+buffer is used directly for output from the process only when there is
+no filter.
+
+ A filter function must accept two arguments: the associated process
+and a string, which is the output. The function is then free to do
+whatever it chooses with the output.
+
+ A filter function runs only while XEmacs is waiting (e.g., for
+terminal input, or for time to elapse, or for process output). This
+avoids the timing errors that could result from running filters at
+random places in the middle of other Lisp programs. You may explicitly
+cause Emacs to wait, so that filter functions will run, by calling
+`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
+(*note Accepting Output::). Emacs is also waiting when the command loop
+is reading input.
+
+ Quitting is normally inhibited within a filter function--otherwise,
+the effect of typing `C-g' at command level or to quit a user command
+would be unpredictable. If you want to permit quitting inside a filter
+function, bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ If an error happens during execution of a filter function, it is
+caught automatically, so that it doesn't stop the execution of whatever
+program was running when the filter function was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the filter
+function. *Note Debugger::.
+
+ Many filter functions sometimes or always insert the text in the
+process's buffer, mimicking the actions of XEmacs when there is no
+filter. Such filter functions need to use `set-buffer' in order to be
+sure to insert in that buffer. To avoid setting the current buffer
+semipermanently, these filter functions must use `unwind-protect' to
+make sure to restore the previous current buffer. They should also
+update the process marker, and in some cases update the value of point.
+Here is how to do these things:
+
+ (defun ordinary-insertion-filter (process string)
+ (let ((old-buffer (current-buffer)))
+ (unwind-protect
+ (let (moving)
+ (set-buffer (process-buffer process))
+ (setq moving (= (point) (process-mark process)))
+ (save-excursion
+ ;; Insert the text, moving the process-marker.
+ (goto-char (process-mark process))
+ (insert string)
+ (set-marker (process-mark process) (point)))
+ (if moving (goto-char (process-mark process))))
+ (set-buffer old-buffer))))
+
+The reason to use an explicit `unwind-protect' rather than letting
+`save-excursion' restore the current buffer is so as to preserve the
+change in point made by `goto-char'.
+
+ To make the filter force the process buffer to be visible whenever
+new text arrives, insert the following line just before the
+`unwind-protect':
+
+ (display-buffer (process-buffer process))
+
+ To force point to move to the end of the new output no matter where
+it was previously, eliminate the variable `moving' and call `goto-char'
+unconditionally.
+
+ In earlier Emacs versions, every filter function that did regexp
+searching or matching had to explicitly save and restore the match data.
+Now Emacs does this automatically; filter functions never need to do it
+explicitly. *Note Match Data::.
+
+ A filter function that writes the output into the buffer of the
+process should check whether the buffer is still alive. If it tries to
+insert into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ The output to the function may come in chunks of any size. A program
+that produces the same output twice in a row may send it as one batch
+of 200 characters one time, and five batches of 40 characters the next.
+
+ - Function: set-process-filter process filter
+ This function gives PROCESS the filter function FILTER. If FILTER
+ is `nil', then the process will have no filter. If FILTER is `t',
+ then no output from the process will be accepted until the filter
+ is changed. (Output received during this time is not discarded,
+ but is queued, and will be processed as soon as the filter is
+ changed.)
+
+ - Function: process-filter process
+ This function returns the filter function of PROCESS, or `nil' if
+ it has none. `t' means that output processing has been stopped.
+
+ Here is an example of use of a filter function:
+
+ (defun keep-output (process output)
+ (setq kept (cons output kept)))
+ => keep-output
+ (setq kept nil)
+ => nil
+ (set-process-filter (get-process "shell") 'keep-output)
+ => keep-output
+ (process-send-string "shell" "ls ~/other\n")
+ => nil
+ kept
+ => ("lewis@slug[8] % "
+ "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
+ address.txt backup.psf kolstad.psf
+ backup.bib~ david.mss resume-Dec-86.mss~
+ backup.err david.psf resume-Dec.psf
+ backup.mss dland syllabus.mss
+ "
+ "#backups.mss# backup.mss~ kolstad.mss
+ ")
+
+\1f
+File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
+
+Accepting Output from Processes
+-------------------------------
+
+Output from asynchronous subprocesses normally arrives only while
+XEmacs is waiting for some sort of external event, such as elapsed time
+or terminal input. Occasionally it is useful in a Lisp program to
+explicitly permit output to arrive at a specific point, or even to wait
+until output arrives from a process.
+
+ - Function: accept-process-output &optional process seconds millisec
+ This function allows XEmacs to read pending output from processes.
+ The output is inserted in the associated buffers or given to
+ their filter functions. If PROCESS is non-`nil' then this
+ function does not return until some output has been received from
+ PROCESS.
+
+ The arguments SECONDS and MILLISEC let you specify timeout
+ periods. The former specifies a period measured in seconds and the
+ latter specifies one measured in milliseconds. The two time
+ periods thus specified are added together, and
+ `accept-process-output' returns after that much time whether or
+ not there has been any subprocess output. Note that SECONDS is
+ allowed to be a floating-point number; thus, there is no need to
+ ever use MILLISEC. (It is retained for compatibility purposes.)
+
+ The function `accept-process-output' returns non-`nil' if it did
+ get some output, or `nil' if the timeout expired before output
+ arrived.
+
+\1f
+File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
+
+Sentinels: Detecting Process Status Changes
+===========================================
+
+A "process sentinel" is a function that is called whenever the
+associated process changes status for any reason, including signals
+(whether sent by XEmacs or caused by the process's own actions) that
+terminate, stop, or continue the process. The process sentinel is also
+called if the process exits. The sentinel receives two arguments: the
+process for which the event occurred, and a string describing the type
+of event.
+
+ The string describing the event looks like one of the following:
+
+ * `"finished\n"'.
+
+ * `"exited abnormally with code EXITCODE\n"'.
+
+ * `"NAME-OF-SIGNAL\n"'.
+
+ * `"NAME-OF-SIGNAL (core dumped)\n"'.
+
+ A sentinel runs only while XEmacs is waiting (e.g., for terminal
+input, or for time to elapse, or for process output). This avoids the
+timing errors that could result from running them at random places in
+the middle of other Lisp programs. A program can wait, so that
+sentinels will run, by calling `sit-for' or `sleep-for' (*note
+Waiting::), or `accept-process-output' (*note Accepting Output::).
+Emacs is also waiting when the command loop is reading input.
+
+ Quitting is normally inhibited within a sentinel--otherwise, the
+effect of typing `C-g' at command level or to quit a user command would
+be unpredictable. If you want to permit quitting inside a sentinel,
+bind `inhibit-quit' to `nil'. *Note Quitting::.
+
+ A sentinel that writes the output into the buffer of the process
+should check whether the buffer is still alive. If it tries to insert
+into a dead buffer, it will get an error. If the buffer is dead,
+`(buffer-name (process-buffer PROCESS))' returns `nil'.
+
+ If an error happens during execution of a sentinel, it is caught
+automatically, so that it doesn't stop the execution of whatever
+programs was running when the sentinel was started. However, if
+`debug-on-error' is non-`nil', the error-catching is turned off. This
+makes it possible to use the Lisp debugger to debug the sentinel.
+*Note Debugger::.
+
+ In earlier Emacs versions, every sentinel that did regexp searching
+or matching had to explicitly save and restore the match data. Now
+Emacs does this automatically; sentinels never need to do it explicitly.
+*Note Match Data::.
+
+ - Function: set-process-sentinel process sentinel
+ This function associates SENTINEL with PROCESS. If SENTINEL is
+ `nil', then the process will have no sentinel. The default
+ behavior when there is no sentinel is to insert a message in the
+ process's buffer when the process status changes.
+
+ (defun msg-me (process event)
+ (princ
+ (format "Process: %s had the event `%s'" process event)))
+ (set-process-sentinel (get-process "shell") 'msg-me)
+ => msg-me
+ (kill-process (get-process "shell"))
+ -| Process: #<process shell> had the event `killed'
+ => #<process shell>
+
+ - Function: process-sentinel process
+ This function returns the sentinel of PROCESS, or `nil' if it has
+ none.
+
+ - Function: waiting-for-user-input-p
+ While a sentinel or filter function is running, this function
+ returns non-`nil' if XEmacs was waiting for keyboard input from
+ the user at the time the sentinel or filter function was called,
+ `nil' if it was not.
+
+\1f
+File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
+
+Process Window Size
+===================
+
+ - Function: set-process-window-size process height width
+ This function tells PROCESS that its logical window size is HEIGHT
+ by WIDTH characters. This is principally useful with pty's.
+
+\1f
+File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
+
+Transaction Queues
+==================
+
+You can use a "transaction queue" for more convenient communication
+with subprocesses using transactions. First use `tq-create' to create
+a transaction queue communicating with a specified process. Then you
+can call `tq-enqueue' to send a transaction.
+
+ - Function: tq-create process
+ This function creates and returns a transaction queue
+ communicating with PROCESS. The argument PROCESS should be a
+ subprocess capable of sending and receiving streams of bytes. It
+ may be a child process, or it may be a TCP connection to a server,
+ possibly on another machine.
+
+ - Function: tq-enqueue queue question regexp closure fn
+ This function sends a transaction to queue QUEUE. Specifying the
+ queue has the effect of specifying the subprocess to talk to.
+
+ The argument QUESTION is the outgoing message that starts the
+ transaction. The argument FN is the function to call when the
+ corresponding answer comes back; it is called with two arguments:
+ CLOSURE, and the answer received.
+
+ The argument REGEXP is a regular expression that should match the
+ entire answer, but nothing less; that's how `tq-enqueue' determines
+ where the answer ends.
+
+ The return value of `tq-enqueue' itself is not meaningful.
+
+ - Function: tq-close queue
+ Shut down transaction queue QUEUE, waiting for all pending
+ transactions to complete, and then terminate the connection or
+ child process.
+
+ Transaction queues are implemented by means of a filter function.
+*Note Filter Functions::.
+
+\1f
+File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
+
+Network Connections
+===================
+
+XEmacs Lisp programs can open TCP network connections to other
+processes on the same machine or other machines. A network connection
+is handled by Lisp much like a subprocess, and is represented by a
+process object. However, the process you are communicating with is not
+a child of the XEmacs process, so you can't kill it or send it signals.
+All you can do is send and receive data. `delete-process' closes the
+connection, but does not kill the process at the other end; that
+process must decide what to do about closure of the connection.
+
+ You can distinguish process objects representing network connections
+from those representing subprocesses with the `process-status'
+function. It always returns either `open' or `closed' for a network
+connection, and it never returns either of those values for a real
+subprocess. *Note Process Information::.
+
+ - Function: open-network-stream name buffer-or-name host service
+ &optional protocol
+ This function opens a TCP connection for a service to a host. It
+ returns a process object to represent the connection.
+
+ Input and output work as for other process objects.
+ `delete-process' closes the connection.
+
+ The NAME argument specifies the name for the process object. It
+ is modified as necessary to make it unique.
+
+ The BUFFER-OR-NAME argument is the buffer to associate with the
+ connection. It can be a buffer or the name of one. Output from
+ the connection is inserted in the buffer, unless you specify a
+ filter function to handle the output. If BUFFER-OR-NAME is `nil',
+ it means that the connection is not associated with any buffer.
+
+ The arguments HOST and SERVICE specify where to connect to; HOST
+ is the host name or IP address (a string), and SERVICE is the name
+ of a defined network service (a string) or a port number (an
+ integer).
+
+ Optional fifth arg PROTOCOL is the network protocol to use.
+ Currently only `tcp' (Transmission Control Protocol) and `udp'
+ (User Datagram Protocol) are supported. When omitted, `tcp' is
+ assumed.
+
+ Output via `process-send-string' and input via buffer or filter
+ (see `set-process-filter') are stream-oriented. That means UDP
+ datagrams are not guaranteed to be sent and received in discrete
+ packets. (But small datagrams around 500 bytes that are not
+ truncated by `process-send-string' are usually fine.) Note further
+ that the UDP protocol does not guard against lost packets.
+
+\1f
+File: lispref.info, Node: System Interface, Next: X-Windows, Prev: Processes, Up: Top
+
+Operating System Interface
+**************************
+
+This chapter is about starting and getting out of Emacs, access to
+values in the operating system environment, and terminal input, output,
+and flow control.
+
+ *Note Building XEmacs::, for related information. See also *Note
+Display::, for additional operating system status information
+pertaining to the terminal and the screen.
+
+* Menu:
+
+* Starting Up:: Customizing XEmacs start-up processing.
+* Getting Out:: How exiting works (permanent or temporary).
+* System Environment:: Distinguish the name and kind of system.
+* User Identification:: Finding the name and user id of the user.
+* Time of Day:: Getting the current time.
+* Time Conversion:: Converting a time from numeric form to a string, or
+ to calendrical data (or vice versa).
+* Timers:: Setting a timer to call a function at a certain time.
+* Terminal Input:: Recording terminal input for debugging.
+* Terminal Output:: Recording terminal output for debugging.
+* Flow Control:: How to turn output flow control on or off.
+* Batch Mode:: Running XEmacs without terminal interaction.
+
+\1f
+File: lispref.info, Node: Starting Up, Next: Getting Out, Up: System Interface
+
+Starting Up XEmacs
+==================
+
+This section describes what XEmacs does when it is started, and how you
+can customize these actions.
+
+* Menu:
+
+* Start-up Summary:: Sequence of actions XEmacs performs at start-up.
+* Init File:: Details on reading the init file (`.emacs').
+* Terminal-Specific:: How the terminal-specific Lisp file is read.
+* Command Line Arguments:: How command line arguments are processed,
+ and how you can customize them.
+
+\1f
+File: lispref.info, Node: Start-up Summary, Next: Init File, Up: Starting Up
+
+Summary: Sequence of Actions at Start Up
+----------------------------------------
+
+The order of operations performed (in `startup.el') by XEmacs when it
+is started up is as follows:
+
+ 1. It loads the initialization library for the window system, if you
+ are using a window system. This library's name is
+ `term/WINDOWSYSTEM-win.el'.
+
+ 2. It processes the initial options. (Some of them are handled even
+ earlier than this.)
+
+ 3. It initializes the X window frame and faces, if appropriate.
+
+ 4. It runs the normal hook `before-init-hook'.
+
+ 5. It loads the library `site-start', unless the option
+ `-no-site-file' was specified. The library's file name is usually
+ `site-start.el'.
+
+ 6. It loads the file `~/.emacs' unless `-q' was specified on the
+ command line. (This is not done in `-batch' mode.) The `-u'
+ option can specify the user name whose home directory should be
+ used instead of `~'.
+
+ 7. It loads the library `default' unless `inhibit-default-init' is
+ non-`nil'. (This is not done in `-batch' mode or if `-q' was
+ specified on the command line.) The library's file name is
+ usually `default.el'.
+
+ 8. It runs the normal hook `after-init-hook'.
+
+ 9. It sets the major mode according to `initial-major-mode', provided
+ the buffer `*scratch*' is still current and still in Fundamental
+ mode.
+
+ 10. It loads the terminal-specific Lisp file, if any, except when in
+ batch mode or using a window system.
+
+ 11. It displays the initial echo area message, unless you have
+ suppressed that with `inhibit-startup-echo-area-message'.
+
+ 12. It processes the action arguments from the command line.
+
+ 13. It runs `term-setup-hook'.
+
+ 14. It calls `frame-notice-user-settings', which modifies the
+ parameters of the selected frame according to whatever the init
+ files specify.
+
+ 15. It runs `window-setup-hook'. *Note Terminal-Specific::.
+
+ 16. It displays copyleft, nonwarranty, and basic use information,
+ provided there were no remaining command line arguments (a few
+ steps above) and the value of `inhibit-startup-message' is `nil'.
+
+ - User Option: inhibit-startup-message
+ This variable inhibits the initial startup messages (the
+ nonwarranty, etc.). If it is non-`nil', then the messages are not
+ printed.
+
+ This variable exists so you can set it in your personal init file,
+ once you are familiar with the contents of the startup message.
+ Do not set this variable in the init file of a new user, or in a
+ way that affects more than one user, because that would prevent
+ new users from receiving the information they are supposed to see.
+
+ - User Option: inhibit-startup-echo-area-message
+ This variable controls the display of the startup echo area
+ message. You can suppress the startup echo area message by adding
+ text with this form to your `.emacs' file:
+
+ (setq inhibit-startup-echo-area-message
+ "YOUR-LOGIN-NAME")
+
+ Simply setting `inhibit-startup-echo-area-message' to your login
+ name is not sufficient to inhibit the message; Emacs explicitly
+ checks whether `.emacs' contains an expression as shown above.
+ Your login name must appear in the expression as a Lisp string
+ constant.
+
+ This way, you can easily inhibit the message for yourself if you
+ wish, but thoughtless copying of your `.emacs' file will not
+ inhibit the message for someone else.
+
+\1f
+File: lispref.info, Node: Init File, Next: Terminal-Specific, Prev: Start-up Summary, Up: Starting Up
+
+The Init File: `.emacs'
+-----------------------
+
+When you start XEmacs, it normally attempts to load the file `.emacs'
+from your home directory. This file, if it exists, must contain Lisp
+code. It is called your "init file". The command line switches `-q'
+and `-u' affect the use of the init file; `-q' says not to load an init
+file, and `-u' says to load a specified user's init file instead of
+yours. *Note Entering XEmacs: (xemacs)Entering XEmacs.
+
+ A site may have a "default init file", which is the library named
+`default.el'. XEmacs finds the `default.el' file through the standard
+search path for libraries (*note How Programs Do Loading::). The
+XEmacs distribution does not come with this file; sites may provide one
+for local customizations. If the default init file exists, it is
+loaded whenever you start Emacs, except in batch mode or if `-q' is
+specified. But your own personal init file, if any, is loaded first; if
+it sets `inhibit-default-init' to a non-`nil' value, then XEmacs does
+not subsequently load the `default.el' file.
+
+ Another file for site-customization is `site-start.el'. Emacs loads
+this _before_ the user's init file. You can inhibit the loading of
+this file with the option `-no-site-file'.
+
+ - Variable: site-run-file
+ This variable specifies the site-customization file to load before
+ the user's init file. Its normal value is `"site-start"'.
+
+ If there is a great deal of code in your `.emacs' file, you should
+move it into another file named `SOMETHING.el', byte-compile it (*note
+Byte Compilation::), and make your `.emacs' file load the other file
+using `load' (*note Loading::).
+
+ *Note Init File Examples: (xemacs)Init File Examples, for examples
+of how to make various commonly desired customizations in your `.emacs'
+file.
+
+ - User Option: inhibit-default-init
+ This variable prevents XEmacs from loading the default
+ initialization library file for your session of XEmacs. If its
+ value is non-`nil', then the default library is not loaded. The
+ default value is `nil'.
+
+ - Variable: before-init-hook
+ - Variable: after-init-hook
+ These two normal hooks are run just before, and just after,
+ loading of the user's init file, `default.el', and/or
+ `site-start.el'.
+
+\1f
+File: lispref.info, Node: Terminal-Specific, Next: Command Line Arguments, Prev: Init File, Up: Starting Up
+
+Terminal-Specific Initialization
+--------------------------------
+
+Each terminal type can have its own Lisp library that XEmacs loads when
+run on that type of terminal. For a terminal type named TERMTYPE, the
+library is called `term/TERMTYPE'. XEmacs finds the file by searching
+the `load-path' directories as it does for other files, and trying the
+`.elc' and `.el' suffixes. Normally, terminal-specific Lisp library is
+located in `emacs/lisp/term', a subdirectory of the `emacs/lisp'
+directory in which most XEmacs Lisp libraries are kept.
+
+ The library's name is constructed by concatenating the value of the
+variable `term-file-prefix' and the terminal type. Normally,
+`term-file-prefix' has the value `"term/"'; changing this is not
+recommended.
+
+ The usual function of a terminal-specific library is to enable
+special keys to send sequences that XEmacs can recognize. It may also
+need to set or add to `function-key-map' if the Termcap entry does not
+specify all the terminal's function keys. *Note Terminal Input::.
+
+ When the name of the terminal type contains a hyphen, only the part
+of the name before the first hyphen is significant in choosing the
+library name. Thus, terminal types `aaa-48' and `aaa-30-rv' both use
+the `term/aaa' library. If necessary, the library can evaluate
+`(getenv "TERM")' to find the full name of the terminal type.
+
+ Your `.emacs' file can prevent the loading of the terminal-specific
+library by setting the variable `term-file-prefix' to `nil'. This
+feature is useful when experimenting with your own peculiar
+customizations.
+
+ You can also arrange to override some of the actions of the
+terminal-specific library by setting the variable `term-setup-hook'.
+This is a normal hook which XEmacs runs using `run-hooks' at the end of
+XEmacs initialization, after loading both your `.emacs' file and any
+terminal-specific libraries. You can use this variable to define
+initializations for terminals that do not have their own libraries.
+*Note Hooks::.
+
+ - Variable: term-file-prefix
+ If the `term-file-prefix' variable is non-`nil', XEmacs loads a
+ terminal-specific initialization file as follows:
+
+ (load (concat term-file-prefix (getenv "TERM")))
+
+ You may set the `term-file-prefix' variable to `nil' in your
+ `.emacs' file if you do not wish to load the
+ terminal-initialization file. To do this, put the following in
+ your `.emacs' file: `(setq term-file-prefix nil)'.
+
+ - Variable: term-setup-hook
+ This variable is a normal hook that XEmacs runs after loading your
+ `.emacs' file, the default initialization file (if any) and the
+ terminal-specific Lisp file.
+
+ You can use `term-setup-hook' to override the definitions made by a
+ terminal-specific file.
+
+ - Variable: window-setup-hook
+ This variable is a normal hook which XEmacs runs after loading your
+ `.emacs' file and the default initialization file (if any), after
+ loading terminal-specific Lisp code, and after running the hook
+ `term-setup-hook'.
+
+\1f
+File: lispref.info, Node: Command Line Arguments, Prev: Terminal-Specific, Up: Starting Up
+
+Command Line Arguments
+----------------------
+
+You can use command line arguments to request various actions when you
+start XEmacs. Since you do not need to start XEmacs more than once per
+day, and will often leave your XEmacs session running longer than that,
+command line arguments are hardly ever used. As a practical matter, it
+is best to avoid making the habit of using them, since this habit would
+encourage you to kill and restart XEmacs unnecessarily often. These
+options exist for two reasons: to be compatible with other editors (for
+invocation by other programs) and to enable shell scripts to run
+specific Lisp programs.
+
+ This section describes how Emacs processes command line arguments,
+and how you can customize them.
+
+ - Function: command-line
+ This function parses the command line that XEmacs was called with,
+ processes it, loads the user's `.emacs' file and displays the
+ startup messages.
+
+ - Variable: command-line-processed
+ The value of this variable is `t' once the command line has been
+ processed.
+
+ If you redump XEmacs by calling `dump-emacs', you may wish to set
+ this variable to `nil' first in order to cause the new dumped
+ XEmacs to process its new command line arguments.
+
+ - Variable: command-switch-alist
+ The value of this variable is an alist of user-defined command-line
+ options and associated handler functions. This variable exists so
+ you can add elements to it.
+
+ A "command line option" is an argument on the command line of the
+ form:
+
+ -OPTION
+
+ The elements of the `command-switch-alist' look like this:
+
+ (OPTION . HANDLER-FUNCTION)
+
+ The HANDLER-FUNCTION is called to handle OPTION and receives the
+ option name as its sole argument.
+
+ In some cases, the option is followed in the command line by an
+ argument. In these cases, the HANDLER-FUNCTION can find all the
+ remaining command-line arguments in the variable
+ `command-line-args-left'. (The entire list of command-line
+ arguments is in `command-line-args'.)
+
+ The command line arguments are parsed by the `command-line-1'
+ function in the `startup.el' file. See also *Note Command Line
+ Switches and Arguments: (xemacs)Command Switches.
+
+ - Variable: command-line-args
+ The value of this variable is the list of command line arguments
+ passed to XEmacs.
+
+ - Variable: command-line-functions
+ This variable's value is a list of functions for handling an
+ unrecognized command-line argument. Each time the next argument
+ to be processed has no special meaning, the functions in this list
+ are called, in order of appearance, until one of them returns a
+ non-`nil' value.
+
+ These functions are called with no arguments. They can access the
+ command-line argument under consideration through the variable
+ `argi'. The remaining arguments (not including the current one)
+ are in the variable `command-line-args-left'.
+
+ When a function recognizes and processes the argument in `argi', it
+ should return a non-`nil' value to say it has dealt with that
+ argument. If it has also dealt with some of the following
+ arguments, it can indicate that by deleting them from
+ `command-line-args-left'.
+
+ If all of these functions return `nil', then the argument is used
+ as a file name to visit.
+
+\1f
+File: lispref.info, Node: Getting Out, Next: System Environment, Prev: Starting Up, Up: System Interface
+
+Getting out of XEmacs
+=====================
+
+There are two ways to get out of XEmacs: you can kill the XEmacs job,
+which exits permanently, or you can suspend it, which permits you to
+reenter the XEmacs process later. As a practical matter, you seldom
+kill XEmacs--only when you are about to log out. Suspending is much
+more common.
+
+* Menu:
+
+* Killing XEmacs:: Exiting XEmacs irreversibly.
+* Suspending XEmacs:: Exiting XEmacs reversibly.
+
+\1f
+File: lispref.info, Node: Killing XEmacs, Next: Suspending XEmacs, Up: Getting Out
+
+Killing XEmacs
+--------------
+
+Killing XEmacs means ending the execution of the XEmacs process. The
+parent process normally resumes control. The low-level primitive for
+killing XEmacs is `kill-emacs'.
+
+ - Command: kill-emacs &optional exit-data
+ This function exits the XEmacs process and kills it.
+
+ If EXIT-DATA is an integer, then it is used as the exit status of
+ the XEmacs process. (This is useful primarily in batch operation;
+ see *Note Batch Mode::.)
+
+ If EXIT-DATA is a string, its contents are stuffed into the
+ terminal input buffer so that the shell (or whatever program next
+ reads input) can read them.
+
+ All the information in the XEmacs process, aside from files that have
+been saved, is lost when the XEmacs is killed. Because killing XEmacs
+inadvertently can lose a lot of work, XEmacs queries for confirmation
+before actually terminating if you have buffers that need saving or
+subprocesses that are running. This is done in the function
+`save-buffers-kill-emacs'.
+
+ - Variable: kill-emacs-query-functions
+ After asking the standard questions, `save-buffers-kill-emacs'
+ calls the functions in the list `kill-buffer-query-functions', in
+ order of appearance, with no arguments. These functions can ask
+ for additional confirmation from the user. If any of them returns
+ non-`nil', XEmacs is not killed.
+
+ - Variable: kill-emacs-hook
+ This variable is a normal hook; once `save-buffers-kill-emacs' is
+ finished with all file saving and confirmation, it runs the
+ functions in this hook.
+
+\1f
+File: lispref.info, Node: Suspending XEmacs, Prev: Killing XEmacs, Up: Getting Out
+
+Suspending XEmacs
+-----------------
+
+"Suspending XEmacs" means stopping XEmacs temporarily and returning
+control to its superior process, which is usually the shell. This
+allows you to resume editing later in the same XEmacs process, with the
+same buffers, the same kill ring, the same undo history, and so on. To
+resume XEmacs, use the appropriate command in the parent shell--most
+likely `fg'.
+
+ Some operating systems do not support suspension of jobs; on these
+systems, "suspension" actually creates a new shell temporarily as a
+subprocess of XEmacs. Then you would exit the shell to return to
+XEmacs.
+
+ Suspension is not useful with window systems such as X, because the
+XEmacs job may not have a parent that can resume it again, and in any
+case you can give input to some other job such as a shell merely by
+moving to a different window. Therefore, suspending is not allowed
+when XEmacs is an X client.
+
+ - Command: suspend-emacs &optional stuffstring
+ This function stops XEmacs and returns control to the superior
+ process. If and when the superior process resumes XEmacs,
+ `suspend-emacs' returns `nil' to its caller in Lisp.
+
+ If optional arg STUFFSTRING is non-`nil', its characters are sent
+ to be read as terminal input by XEmacs's superior shell. The
+ characters in STUFFSTRING are not echoed by the superior shell;
+ only the results appear.
+
+ Before suspending, `suspend-emacs' runs the normal hook
+ `suspend-hook'. In Emacs version 18, `suspend-hook' was not a
+ normal hook; its value was a single function, and if its value was
+ non-`nil', then `suspend-emacs' returned immediately without
+ actually suspending anything.
+
+ After the user resumes XEmacs, `suspend-emacs' runs the normal hook
+ `suspend-resume-hook'. *Note Hooks::.
+
+ The next redisplay after resumption will redraw the entire screen,
+ unless the variable `no-redraw-on-reenter' is non-`nil' (*note
+ Refresh Screen::).
+
+ In the following example, note that `pwd' is not echoed after
+ XEmacs is suspended. But it is read and executed by the shell.
+
+ (suspend-emacs)
=> nil
- (equal x y)
- => t
- (eq (elt x 1) (elt y 1))
- => t
- ;; Replacing an element of one sequence.
- (aset x 0 'quux)
- x => [quux (1 2)]
- y => [foo (1 2)]
+ (add-hook 'suspend-hook
+ (function (lambda ()
+ (or (y-or-n-p
+ "Really suspend? ")
+ (error "Suspend cancelled")))))
+ => (lambda nil
+ (or (y-or-n-p "Really suspend? ")
+ (error "Suspend cancelled")))
+ (add-hook 'suspend-resume-hook
+ (function (lambda () (message "Resumed!"))))
+ => (lambda nil (message "Resumed!"))
+ (suspend-emacs "pwd")
+ => nil
+ ---------- Buffer: Minibuffer ----------
+ Really suspend? y
+ ---------- Buffer: Minibuffer ----------
- ;; Modifying the inside of a shared element.
- (setcar (aref x 1) 69)
- x => [quux (69 2)]
- y => [foo (69 2)]
+ ---------- Parent Shell ----------
+ lewis@slug[23] % /user/lewis/manual
+ lewis@slug[24] % fg
- ;; Creating a bit vector.
- (bit-vector 1 0 1 1 0 1 0 0)
- => #*10110100
-
- - Function: length sequence
- Returns the number of elements in SEQUENCE. If SEQUENCE is a cons
- cell that is not a list (because the final CDR is not `nil'), a
- `wrong-type-argument' error is signaled.
-
- (length '(1 2 3))
- => 3
- (length ())
- => 0
- (length "foobar")
- => 6
- (length [1 2 3])
- => 3
- (length #*01101)
- => 5
-
- - Function: elt sequence index
- This function returns the element of SEQUENCE indexed by INDEX.
- Legitimate values of INDEX are integers ranging from 0 up to one
- less than the length of SEQUENCE. If SEQUENCE is a list, then
- out-of-range values of INDEX return `nil'; otherwise, they trigger
- an `args-out-of-range' error.
-
- (elt [1 2 3 4] 2)
- => 3
- (elt '(1 2 3 4) 2)
- => 3
- (char-to-string (elt "1234" 2))
- => "3"
- (elt #*00010000 3)
- => 1
- (elt [1 2 3 4] 4)
- error-->Args out of range: [1 2 3 4], 4
- (elt [1 2 3 4] -1)
- error-->Args out of range: [1 2 3 4], -1
-
- This function generalizes `aref' (*note Array Functions::) and
- `nth' (*note List Elements::).
-
-\1f
-File: lispref.info, Node: Arrays, Next: Array Functions, Prev: Sequence Functions, Up: Sequences Arrays Vectors
-
-Arrays
-======
+ ---------- Echo Area ----------
+ Resumed!
- An "array" object has slots that hold a number of other Lisp
-objects, called the elements of the array. Any element of an array may
-be accessed in constant time. In contrast, an element of a list
-requires access time that is proportional to the position of the element
-in the list.
+ - Variable: suspend-hook
+ This variable is a normal hook run before suspending.
- When you create an array, you must specify how many elements it has.
-The amount of space allocated depends on the number of elements.
-Therefore, it is impossible to change the size of an array once it is
-created; you cannot add or remove elements. However, you can replace an
-element with a different value.
+ - Variable: suspend-resume-hook
+ This variable is a normal hook run after suspending.
- XEmacs defines three types of array, all of which are
-one-dimensional: "strings", "vectors", and "bit vectors". A vector is a
-general array; its elements can be any Lisp objects. A string is a
-specialized array; its elements must be characters. A bit vector is
-another specialized array; its elements must be bits (an integer, either
-0 or 1). Each type of array has its own read syntax. *Note String
-Type::, *Note Vector Type::, and *Note Bit Vector Type::.
+\1f
+File: lispref.info, Node: System Environment, Next: User Identification, Prev: Getting Out, Up: System Interface
- All kinds of array share these characteristics:
+Operating System Environment
+============================
- * The first element of an array has index zero, the second element
- has index 1, and so on. This is called "zero-origin" indexing.
- For example, an array of four elements has indices 0, 1, 2, and 3.
+XEmacs provides access to variables in the operating system environment
+through various functions. These variables include the name of the
+system, the user's UID, and so on.
- * The elements of an array may be referenced or changed with the
- functions `aref' and `aset', respectively (*note Array
- Functions::).
+ - Variable: system-type
+ The value of this variable is a symbol indicating the type of
+ operating system XEmacs is operating on. Here is a table of the
+ possible values:
- In principle, if you wish to have an array of text characters, you
-could use either a string or a vector. In practice, we always choose
-strings for such applications, for four reasons:
+ `aix-v3'
+ AIX.
- * They usually occupy one-fourth the space of a vector of the same
- elements. (This is one-eighth the space for 64-bit machines such
- as the DEC Alpha, and may also be different when MULE support is
- compiled into XEmacs.)
+ `berkeley-unix'
+ Berkeley BSD.
- * Strings are printed in a way that shows the contents more clearly
- as characters.
+ `dgux'
+ Data General DGUX operating system.
- * Strings can hold extent and text properties. *Note Extents::,
- *Note Text Properties::.
+ `gnu'
+ A GNU system using the GNU HURD and Mach.
- * Many of the specialized editing and I/O facilities of XEmacs
- accept only strings. For example, you cannot insert a vector of
- characters into a buffer the way you can insert a string. *Note
- Strings and Characters::.
+ `hpux'
+ Hewlett-Packard HPUX operating system.
- By contrast, for an array of keyboard input characters (such as a key
-sequence), a vector may be necessary, because many keyboard input
-characters are non-printable and are represented with symbols rather
-than with characters. *Note Key Sequence Input::.
+ `irix'
+ Silicon Graphics Irix system.
- Similarly, when representing an array of bits, a bit vector has the
-following advantages over a regular vector:
+ `linux'
+ A GNU system using the Linux kernel.
- * They occupy 1/32nd the space of a vector of the same elements.
- (1/64th on 64-bit machines such as the DEC Alpha.)
+ `ms-dos'
+ Microsoft MS-DOS "operating system."
- * Bit vectors are printed in a way that shows the contents more
- clearly as bits.
+ `next-mach'
+ NeXT Mach-based system.
-\1f
-File: lispref.info, Node: Array Functions, Next: Vectors, Prev: Arrays, Up: Sequences Arrays Vectors
+ `rtu'
+ Masscomp RTU, UCB universe.
-Functions that Operate on Arrays
-================================
+ `unisoft-unix'
+ UniSoft UniPlus.
- In this section, we describe the functions that accept strings,
-vectors, and bit vectors.
+ `usg-unix-v'
+ AT&T System V.
- - Function: arrayp object
- This function returns `t' if OBJECT is an array (i.e., a string,
- vector, or bit vector).
+ `windows-nt'
+ Microsoft windows NT.
- (arrayp "asdf")
- => t
- (arrayp [a])
- => t
- (arrayp #*101)
- => t
+ `xenix'
+ SCO Xenix 386.
- - Function: aref array index
- This function returns the INDEXth element of ARRAY. The first
- element is at index zero.
+ We do not wish to add new symbols to make finer distinctions
+ unless it is absolutely necessary! In fact, we hope to eliminate
+ some of these alternatives in the future. We recommend using
+ `system-configuration' to distinguish between different operating
+ systems.
- (setq primes [2 3 5 7 11 13])
- => [2 3 5 7 11 13]
- (aref primes 4)
- => 11
- (elt primes 4)
- => 11
-
- (aref "abcdefg" 1)
- => ?b
-
- (aref #*1101 2)
- => 0
+ - Variable: system-configuration
+ This variable holds the three-part configuration name for the
+ hardware/software configuration of your system, as a string. The
+ convenient way to test parts of this string is with `string-match'.
- See also the function `elt', in *Note Sequence Functions::.
+ - Function: system-name
+ This function returns the name of the machine you are running on.
+ (system-name)
+ => "prep.ai.mit.edu"
- - Function: aset array index object
- This function sets the INDEXth element of ARRAY to be OBJECT. It
- returns OBJECT.
+ The symbol `system-name' is a variable as well as a function. In
+fact, the function returns whatever value the variable `system-name'
+currently holds. Thus, you can set the variable `system-name' in case
+Emacs is confused about the name of your system. The variable is also
+useful for constructing frame titles (*note Frame Titles::).
- (setq w [foo bar baz])
- => [foo bar baz]
- (aset w 0 'fu)
- => fu
- w
- => [fu bar baz]
-
- (setq x "asdfasfd")
- => "asdfasfd"
- (aset x 3 ?Z)
- => ?Z
- x
- => "asdZasfd"
-
- (setq bv #*1111)
- => #*1111
- (aset bv 2 0)
- => 0
- bv
- => #*1101
-
- If ARRAY is a string and OBJECT is not a character, a
- `wrong-type-argument' error results.
-
- - Function: fillarray array object
- This function fills the array ARRAY with OBJECT, so that each
- element of ARRAY is OBJECT. It returns ARRAY.
-
- (setq a [a b c d e f g])
- => [a b c d e f g]
- (fillarray a 0)
- => [0 0 0 0 0 0 0]
- a
- => [0 0 0 0 0 0 0]
+ - Variable: mail-host-address
+ If this variable is non-`nil', it is used instead of `system-name'
+ for purposes of generating email addresses. For example, it is
+ used when constructing the default value of `user-mail-address'.
+ *Note User Identification::. (Since this is done when XEmacs
+ starts up, the value actually used is the one saved when XEmacs
+ was dumped. *Note Building XEmacs::.)
+
+ - Command: getenv var &optional interactivep
+ This function returns the value of the environment variable VAR,
+ as a string. Within XEmacs, the environment variable values are
+ kept in the Lisp variable `process-environment'.
+
+ When invoked interactively, `getenv' prints the value in the echo
+ area.
+
+ (getenv "USER")
+ => "lewis"
- (setq s "When in the course")
- => "When in the course"
- (fillarray s ?-)
- => "------------------"
+ lewis@slug[10] % printenv
+ PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
+ USER=lewis
+ TERM=ibmapa16
+ SHELL=/bin/csh
+ HOME=/user/lewis
+
+ - Command: setenv variable &optional value unset
+ This command sets the value of the environment variable named
+ VARIABLE to VALUE. Both arguments should be strings. This
+ function works by modifying `process-environment'; binding that
+ variable with `let' is also reasonable practice.
+
+ - Variable: process-environment
+ This variable is a list of strings, each describing one environment
+ variable. The functions `getenv' and `setenv' work by
+ manipulating this variable.
+
+ process-environment
+ => ("l=/usr/stanford/lib/gnuemacs/lisp"
+ "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
+ "USER=lewis"
+ "TERM=ibmapa16"
+ "SHELL=/bin/csh"
+ "HOME=/user/lewis")
+
+ - Variable: path-separator
+ This variable holds a string which says which character separates
+ directories in a search path (as found in an environment
+ variable). Its value is `":"' for Unix and GNU systems, and `";"'
+ for MS-DOS and Windows NT.
+
+ - Variable: invocation-name
+ This variable holds the program name under which Emacs was
+ invoked. The value is a string, and does not include a directory
+ name.
+
+ - Variable: invocation-directory
+ This variable holds the directory from which the Emacs executable
+ was invoked, or perhaps `nil' if that directory cannot be
+ determined.
+
+ - Variable: installation-directory
+ If non-`nil', this is a directory within which to look for the
+ `lib-src' and `etc' subdirectories. This is non-`nil' when Emacs
+ can't find those directories in their standard installed
+ locations, but can find them in a directory related somehow to the
+ one containing the Emacs executable.
+
+ - Function: load-average &optional use-floats
+ This function returns a list of the current 1-minute, 5-minute and
+ 15-minute load averages. The values are integers that are 100
+ times the system load averages. (The load averages indicate the
+ number of processes trying to run.)
+
+ When USE-FLOATS is non-`nil', floats will be returned instead of
+ integers. These floats are not multiplied by 100.
+
+ (load-average)
+ => (169 158 164)
+ (load-average t)
+ => (1.69921875 1.58984375 1.640625)
- (setq bv #*1101)
- => #*1101
- (fillarray bv 0)
- => #*0000
+ lewis@rocky[5] % uptime
+ 8:06pm up 16 day(s), 21:57, 40 users,
+ load average: 1.68, 1.59, 1.64
+
+ If the 5-minute or 15-minute load averages are not available,
+ return a shortened list, containing only those averages which are
+ available.
- If ARRAY is a string and OBJECT is not a character, a
- `wrong-type-argument' error results.
+ On some systems, this function may require special privileges to
+ run, or it may be unimplemented for the particular system type.
+ In that case, the function will signal an error.
- The general sequence functions `copy-sequence' and `length' are
-often useful for objects known to be arrays. *Note Sequence
-Functions::.
+ - Function: emacs-pid
+ This function returns the process ID of the Emacs process.
\1f
-File: lispref.info, Node: Vectors, Next: Vector Functions, Prev: Array Functions, Up: Sequences Arrays Vectors
+File: lispref.info, Node: User Identification, Next: Time of Day, Prev: System Environment, Up: System Interface
-Vectors
-=======
+User Identification
+===================
- Arrays in Lisp, like arrays in most languages, are blocks of memory
-whose elements can be accessed in constant time. A "vector" is a
-general-purpose array; its elements can be any Lisp objects. (The other
-kind of array in XEmacs Lisp is the "string", whose elements must be
-characters.) Vectors in XEmacs serve as obarrays (vectors of symbols),
-although this is a shortcoming that should be fixed. They are also used
-internally as part of the representation of a byte-compiled function; if
-you print such a function, you will see a vector in it.
-
- In XEmacs Lisp, the indices of the elements of a vector start from
-zero and count up from there.
-
- Vectors are printed with square brackets surrounding the elements.
-Thus, a vector whose elements are the symbols `a', `b' and `a' is
-printed as `[a b a]'. You can write vectors in the same way in Lisp
-input.
-
- A vector, like a string or a number, is considered a constant for
-evaluation: the result of evaluating it is the same vector. This does
-not evaluate or even examine the elements of the vector. *Note
-Self-Evaluating Forms::.
-
- Here are examples of these principles:
-
- (setq avector [1 two '(three) "four" [five]])
- => [1 two (quote (three)) "four" [five]]
- (eval avector)
- => [1 two (quote (three)) "four" [five]]
- (eq avector (eval avector))
- => t
+ - Variable: user-mail-address
+ This holds the nominal email address of the user who is using
+ Emacs. When Emacs starts up, it computes a default value that is
+ usually right, but users often set this themselves when the
+ default value is not right.
-\1f
-File: lispref.info, Node: Vector Functions, Next: Bit Vectors, Prev: Vectors, Up: Sequences Arrays Vectors
+ - Function: user-login-name &optional uid
+ If you don't specify UID, this function returns the name under
+ which the user is logged in. If the environment variable `LOGNAME'
+ is set, that value is used. Otherwise, if the environment variable
+ `USER' is set, that value is used. Otherwise, the value is based
+ on the effective UID, not the real UID.
-Functions That Operate on Vectors
-=================================
+ If you specify UID, the value is the user name that corresponds to
+ UID (which should be an integer).
- Here are some functions that relate to vectors:
+ (user-login-name)
+ => "lewis"
- - Function: vectorp object
- This function returns `t' if OBJECT is a vector.
+ - Function: user-real-login-name
+ This function returns the user name corresponding to Emacs's real
+ UID. This ignores the effective UID and ignores the environment
+ variables `LOGNAME' and `USER'.
- (vectorp [a])
- => t
- (vectorp "asdf")
- => nil
+ - Variable: user-full-name
+ This variable holds the name of the user running this Emacs. It is
+ initialized at startup time from the value of `NAME' environment
+ variable. You can change the value of this variable to alter the
+ result of the `user-full-name' function.
- - Function: vector &rest objects
- This function creates and returns a vector whose elements are the
- arguments, OBJECTS.
+ - Function: user-full-name &optional user
+ This function returns the full name of USER. If USER is `nil', it
+ defaults to the user running this Emacs. In that case, the value
+ of `user-full-name' variable, if non-`nil', will be used.
- (vector 'foo 23 [bar baz] "rats")
- => [foo 23 [bar baz] "rats"]
- (vector)
- => []
+ If USER is specified explicitly, `user-full-name' variable is
+ ignored.
- - Function: make-vector length object
- This function returns a new vector consisting of LENGTH elements,
- each initialized to OBJECT.
+ (user-full-name)
+ => "Hrvoje Niksic"
+ (setq user-full-name "Hrvoje \"Niksa\" Niksic")
+ (user-full-name)
+ => "Hrvoje \"Niksa\" Niksic"
+ (user-full-name "hniksic")
+ => "Hrvoje Niksic"
- (setq sleepy (make-vector 9 'Z))
- => [Z Z Z Z Z Z Z Z Z]
+ The symbols `user-login-name', `user-real-login-name' and
+`user-full-name' are variables as well as functions. The functions
+return the same values that the variables hold. These variables allow
+you to "fake out" Emacs by telling the functions what to return. The
+variables are also useful for constructing frame titles (*note Frame
+Titles::).
- - Function: vconcat &rest sequences
- This function returns a new vector containing all the elements of
- the SEQUENCES. The arguments SEQUENCES may be lists, vectors, or
- strings. If no SEQUENCES are given, an empty vector is returned.
+ - Function: user-real-uid
+ This function returns the real UID of the user.
- The value is a newly constructed vector that is not `eq' to any
- existing vector.
+ (user-real-uid)
+ => 19
- (setq a (vconcat '(A B C) '(D E F)))
- => [A B C D E F]
- (eq a (vconcat a))
- => nil
- (vconcat)
- => []
- (vconcat [A B C] "aa" '(foo (6 7)))
- => [A B C 97 97 foo (6 7)]
+ - Function: user-uid
+ This function returns the effective UID of the user.
+
+ - Function: user-home-directory
+ This function returns the "`HOME'" directory of the user, and is
+ intended to replace occurrences of "`(getenv "HOME")'". Under
+ Unix systems, the following is done:
+
+ 1. Return the value of "`(getenv "HOME")'", if set.
+
+ 2. Return "/", as a fallback, but issue a warning. (Future
+ versions of XEmacs will also attempt to lookup the `HOME'
+ directory via `getpwent()', but this has not yet been
+ implemented.)
- The `vconcat' function also allows integers as arguments. It
- converts them to strings of digits, making up the decimal print
- representation of the integer, and then uses the strings instead
- of the original integers. *Don't use this feature; we plan to
- eliminate it. If you already use this feature, change your
- programs now!* The proper way to convert an integer to a decimal
- number in this way is with `format' (*note Formatting Strings::)
- or `number-to-string' (*note String Conversion::).
+ Under MS Windows, this is done:
- For other concatenation functions, see `mapconcat' in *Note
- Mapping Functions::, `concat' in *Note Creating Strings::, `append'
- in *Note Building Lists::, and `bvconcat' in *Note Bit Vector
- Functions::.
+ 1. Return the value of "`(getenv "HOME")'", if set.
- The `append' function provides a way to convert a vector into a list
-with the same elements (*note Building Lists::):
+ 2. If the environment variables `HOMEDRIVE' and `HOMEDIR' are
+ both set, return the concatenation (the following description
+ uses MS Windows environment variable substitution syntax):
+ `%HOMEDRIVE%%HOMEDIR%'.
- (setq avector [1 two (quote (three)) "four" [five]])
- => [1 two (quote (three)) "four" [five]]
- (append avector nil)
- => (1 two (quote (three)) "four" [five])
+ 3. Return "C:\", as a fallback, but issue a warning.
\1f
-File: lispref.info, Node: Bit Vectors, Next: Bit Vector Functions, Prev: Vector Functions, Up: Sequences Arrays Vectors
+File: lispref.info, Node: Time of Day, Next: Time Conversion, Prev: User Identification, Up: System Interface
-Bit Vectors
+Time of Day
===========
- Bit vectors are specialized vectors that can only represent arrays
-of 1's and 0's. Bit vectors have a very efficient representation and
-are useful for representing sets of boolean (true or false) values.
+This section explains how to determine the current time and the time
+zone.
+
+ - Function: current-time-string &optional time-value
+ This function returns the current time and date as a
+ humanly-readable string. The format of the string is unvarying;
+ the number of characters used for each part is always the same, so
+ you can reliably use `substring' to extract pieces of it. It is
+ wise to count the characters from the beginning of the string
+ rather than from the end, as additional information may be added
+ at the end.
+
+ The argument TIME-VALUE, if given, specifies a time to format
+ instead of the current time. The argument should be a list whose
+ first two elements are integers. Thus, you can use times obtained
+ from `current-time' (see below) and from `file-attributes' (*note
+ File Attributes::).
+
+ (current-time-string)
+ => "Wed Oct 14 22:21:05 1987"
+
+ - Function: current-time
+ This function returns the system's time value as a list of three
+ integers: `(HIGH LOW MICROSEC)'. The integers HIGH and LOW
+ combine to give the number of seconds since 0:00 January 1, 1970,
+ which is HIGH * 2**16 + LOW.
+
+ The third element, MICROSEC, gives the microseconds since the
+ start of the current second (or 0 for systems that return time
+ only on the resolution of a second).
+
+ The first two elements can be compared with file time values such
+ as you get with the function `file-attributes'. *Note File
+ Attributes::.
+
+ - Function: current-time-zone &optional time-value
+ This function returns a list describing the time zone that the
+ user is in.
+
+ The value has the form `(OFFSET NAME)'. Here OFFSET is an integer
+ giving the number of seconds ahead of UTC (east of Greenwich). A
+ negative value means west of Greenwich. The second element, NAME
+ is a string giving the name of the time zone. Both elements
+ change when daylight savings time begins or ends; if the user has
+ specified a time zone that does not use a seasonal time
+ adjustment, then the value is constant through time.
+
+ If the operating system doesn't supply all the information
+ necessary to compute the value, both elements of the list are
+ `nil'.
+
+ The argument TIME-VALUE, if given, specifies a time to analyze
+ instead of the current time. The argument should be a cons cell
+ containing two integers, or a list whose first two elements are
+ integers. Thus, you can use times obtained from `current-time'
+ (see above) and from `file-attributes' (*note File Attributes::).
- There is no limit on the size of a bit vector. You could, for
-example, create a bit vector with 100,000 elements if you really wanted
-to.
+\1f
+File: lispref.info, Node: Time Conversion, Next: Timers, Prev: Time of Day, Up: System Interface
- Bit vectors have a special printed representation consisting of `#*'
-followed by the bits of the vector. For example, a bit vector whose
-elements are 0, 1, 1, 0, and 1, respectively, is printed as
+Time Conversion
+===============
- #*01101
+These functions convert time values (lists of two or three integers) to
+strings or to calendrical information. There is also a function to
+convert calendrical information to a time value. You can get time
+values from the functions `current-time' (*note Time of Day::) and
+`file-attributes' (*note File Attributes::).
- Bit vectors are considered constants for evaluation, like vectors,
-strings, and numbers. *Note Self-Evaluating Forms::.
+ - Function: format-time-string format-string &optional time
+ This function converts TIME to a string according to
+ FORMAT-STRING. If TIME is omitted, it defaults to the current
+ time. The argument FORMAT-STRING may contain `%'-sequences which
+ say to substitute parts of the time. Here is a table of what the
+ `%'-sequences mean:
-\1f
-File: lispref.info, Node: Bit Vector Functions, Prev: Bit Vectors, Up: Sequences Arrays Vectors
+ `%a'
+ This stands for the abbreviated name of the day of week.
-Functions That Operate on Bit Vectors
-=====================================
+ `%A'
+ This stands for the full name of the day of week.
- Here are some functions that relate to bit vectors:
+ `%b'
+ This stands for the abbreviated name of the month.
- - Function: bit-vector-p object
- This function returns `t' if OBJECT is a bit vector.
+ `%B'
+ This stands for the full name of the month.
- (bit-vector-p #*01)
- => t
- (bit-vector-p [0 1])
- => nil
- (bit-vector-p "01")
- => nil
+ `%c'
+ This is a synonym for `%x %X'.
- - Function: bitp object
- This function returns `t' if OBJECT is either 0 or 1.
+ `%C'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%A, %B %e, %Y'.
- - Function: bit-vector &rest bits
- This function creates and returns a bit vector whose elements are
- the arguments BITS. Each argument must be a bit, i.e. one of the
- two integers 0 or 1.
+ `%d'
+ This stands for the day of month, zero-padded.
- (bit-vector 0 0 0 1 0 0 0 0 1 0)
- => #*0001000010
- (bit-vector)
- => #*
+ `%D'
+ This is a synonym for `%m/%d/%y'.
- - Function: make-bit-vector length bit
- This function creates and returns a bit vector consisting of
- LENGTH elements, each initialized to BIT, which must be one of the
- two integers 0 or 1.
+ `%e'
+ This stands for the day of month, blank-padded.
- (setq picket-fence (make-bit-vector 9 1))
- => #*111111111
+ `%h'
+ This is a synonym for `%b'.
- - Function: bvconcat &rest sequences
- This function returns a new bit vector containing all the elements
- of the SEQUENCES. The arguments SEQUENCES may be lists, vectors,
- or bit vectors, all of whose elements are the integers 0 or 1. If
- no SEQUENCES are given, an empty bit vector is returned.
+ `%H'
+ This stands for the hour (00-23).
- The value is a newly constructed bit vector that is not `eq' to any
- existing bit vector.
+ `%I'
+ This stands for the hour (00-12).
- (setq a (bvconcat '(1 1 0) '(0 0 1)))
- => #*110001
- (eq a (bvconcat a))
- => nil
- (bvconcat)
- => #*
- (bvconcat [1 0 0 0 0] #*111 '(0 0 0 0 1))
- => #*1000011100001
+ `%j'
+ This stands for the day of the year (001-366).
- For other concatenation functions, see `mapconcat' in *Note
- Mapping Functions::, `concat' in *Note Creating Strings::,
- `vconcat' in *Note Vector Functions::, and `append' in *Note
- Building Lists::.
+ `%k'
+ This stands for the hour (0-23), blank padded.
- The `append' function provides a way to convert a bit vector into a
-list with the same elements (*note Building Lists::):
+ `%l'
+ This stands for the hour (1-12), blank padded.
- (setq bv #*00001110)
- => #*00001110
- (append bv nil)
- => (0 0 0 0 1 1 1 0)
+ `%m'
+ This stands for the month (01-12).
-\1f
-File: lispref.info, Node: Symbols, Next: Evaluation, Prev: Sequences Arrays Vectors, Up: Top
+ `%M'
+ This stands for the minute (00-59).
+
+ `%n'
+ This stands for a newline.
+
+ `%p'
+ This stands for `AM' or `PM', as appropriate.
+
+ `%r'
+ This is a synonym for `%I:%M:%S %p'.
+
+ `%R'
+ This is a synonym for `%H:%M'.
+
+ `%S'
+ This stands for the seconds (00-60).
+
+ `%t'
+ This stands for a tab character.
+
+ `%T'
+ This is a synonym for `%H:%M:%S'.
+
+ `%U'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Sunday.
+
+ `%w'
+ This stands for the numeric day of week (0-6). Sunday is day
+ 0.
-Symbols
-*******
+ `%W'
+ This stands for the week of the year (01-52), assuming that
+ weeks start on Monday.
- A "symbol" is an object with a unique name. This chapter describes
-symbols, their components, their property lists, and how they are
-created and interned. Separate chapters describe the use of symbols as
-variables and as function names; see *Note Variables::, and *Note
-Functions::. For the precise read syntax for symbols, see *Note Symbol
-Type::.
+ `%x'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%D'.
- You can test whether an arbitrary Lisp object is a symbol with
-`symbolp':
+ `%X'
+ This has a locale-specific meaning. In the default locale
+ (named C), it is equivalent to `%T'.
- - Function: symbolp object
- This function returns `t' if OBJECT is a symbol, `nil' otherwise.
+ `%y'
+ This stands for the year without century (00-99).
+
+ `%Y'
+ This stands for the year with century.
+
+ `%Z'
+ This stands for the time zone abbreviation.
+
+ - Function: decode-time &optional specified-time
+ This function converts a time value into calendrical information.
+ The optional SPECIFIED-TIME should be a list of (HIGH LOW .
+ IGNORED) or (HIGH . LOW), as from `current-time' and
+ `file-attributes', or `nil' to use the current time.
+
+ The return value is a list of nine elements, as follows:
+
+ (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)
+
+ Here is what the elements mean:
+
+ SEC
+ The number of seconds past the minute, as an integer between
+ 0 and 59.
+
+ MINUTE
+ The number of minutes past the hour, as an integer between 0
+ and 59.
+
+ HOUR
+ The hour of the day, as an integer between 0 and 23.
+
+ DAY
+ The day of the month, as an integer between 1 and 31.
+
+ MONTH
+ The month of the year, as an integer between 1 and 12.
+
+ YEAR
+ The year, an integer typically greater than 1900.
+
+ DOW
+ The day of week, as an integer between 0 and 6, where 0
+ stands for Sunday.
+
+ DST
+ `t' if daylight savings time is effect, otherwise `nil'.
+
+ ZONE
+ An integer indicating the time zone, as the number of seconds
+ east of Greenwich.
+
+ Note that Common Lisp has different meanings for DOW and ZONE.
+
+ - Function: encode-time seconds minutes hour day month year &optional
+ zone
+ This function is the inverse of `decode-time'. It converts seven
+ items of calendrical data into a time value. For the meanings of
+ the arguments, see the table above under `decode-time'.
+
+ Year numbers less than 100 are treated just like other year
+ numbers. If you want them to stand for years above 1900, you must
+ alter them yourself before you call `encode-time'.
+
+ The optional argument ZONE defaults to the current time zone and
+ its daylight savings time rules. If specified, it can be either a
+ list (as you would get from `current-time-zone') or an integer (as
+ you would get from `decode-time'). The specified zone is used
+ without any further alteration for daylight savings time.
+
+\1f
+File: lispref.info, Node: Timers, Next: Terminal Input, Prev: Time Conversion, Up: System Interface
+
+Timers for Delayed Execution
+============================
+
+You can set up a timer to call a function at a specified future time.
+
+ - Function: add-timeout secs function object &optional resignal
+ This function adds a timeout, to be signaled after the timeout
+ period has elapsed. SECS is a number of seconds, expressed as an
+ integer or a float. FUNCTION will be called after that many
+ seconds have elapsed, with one argument, the given OBJECT. If the
+ optional RESIGNAL argument is provided, then after this timeout
+ expires, `add-timeout' will automatically be called again with
+ RESIGNAL as the first argument.
+
+ This function returns an object which is the "id" of this
+ particular timeout. You can pass that object to `disable-timeout'
+ to turn off the timeout before it has been signalled.
+
+ The number of seconds may be expressed as a floating-point number,
+ in which case some fractional part of a second will be used.
+ Caveat: the usable timeout granularity will vary from system to
+ system.
+
+ Adding a timeout causes a timeout event to be returned by
+ `next-event', and the function will be invoked by
+ `dispatch-event', so if XEmacs is in a tight loop, the function
+ will not be invoked until the next call to sit-for or until the
+ return to top-level (the same is true of process filters).
+
+ WARNING: if you are thinking of calling add-timeout from inside of
+ a callback function as a way of resignalling a timeout, think
+ again. There is a race condition. That's why the RESIGNAL
+ argument exists.
+
+ (NOTE: In FSF Emacs, this function is called `run-at-time' and has
+ different semantics.)
+
+ - Function: disable-timeout id
+ Cancel the requested action for ID, which should be a value
+ previously returned by `add-timeout'. This cancels the effect of
+ that call to `add-timeout'; the arrival of the specified time will
+ not cause anything special to happen. (NOTE: In FSF Emacs, this
+ function is called `cancel-timer'.)
+
+\1f
+File: lispref.info, Node: Terminal Input, Next: Terminal Output, Prev: Timers, Up: System Interface
+
+Terminal Input
+==============
+
+This section describes functions and variables for recording or
+manipulating terminal input. See *Note Display::, for related
+functions.
* Menu:
-* Symbol Components:: Symbols have names, values, function definitions
- and property lists.
-* Definitions:: A definition says how a symbol will be used.
-* Creating Symbols:: How symbols are kept unique.
-* Symbol Properties:: Each symbol has a property list
- for recording miscellaneous information.
+* Input Modes:: Options for how input is processed.
+* Translating Input:: Low level conversion of some characters or events
+ into others.
+* Recording Input:: Saving histories of recent or all input events.
\1f
-File: lispref.info, Node: Symbol Components, Next: Definitions, Up: Symbols
+File: lispref.info, Node: Input Modes, Next: Translating Input, Up: Terminal Input
+
+Input Modes
+-----------
+
+ - Function: set-input-mode interrupt flow meta &optional quit-char
+ console
+ This function sets the mode for reading keyboard input. If
+ INTERRUPT is non-null, then XEmacs uses input interrupts. If it is
+ `nil', then it uses CBREAK mode. When XEmacs communicates
+ directly with X, it ignores this argument and uses interrupts if
+ that is the way it knows how to communicate.
+
+ If FLOW is non-`nil', then XEmacs uses XON/XOFF (`C-q', `C-s')
+ flow control for output to the terminal. This has no effect except
+ in CBREAK mode. *Note Flow Control::.
+
+ The default setting is system dependent. Some systems always use
+ CBREAK mode regardless of what is specified.
+
+ The argument META controls support for input character codes above
+ 127. If META is `t', XEmacs converts characters with the 8th bit
+ set into Meta characters. If META is `nil', XEmacs disregards the
+ 8th bit; this is necessary when the terminal uses it as a parity
+ bit. If META is neither `t' nor `nil', XEmacs uses all 8 bits of
+ input unchanged. This is good for terminals using European 8-bit
+ character sets.
+
+ If QUIT-CHAR is non-`nil', it specifies the character to use for
+ quitting. Normally this character is `C-g'. *Note Quitting::.
+
+ The `current-input-mode' function returns the input mode settings
+XEmacs is currently using.
+
+ - Function: current-input-mode &optional console
+ This function returns current mode for reading keyboard input. It
+ returns a list, corresponding to the arguments of `set-input-mode',
+ of the form `(INTERRUPT FLOW META QUIT)' in which:
+ INTERRUPT
+ is non-`nil' when XEmacs is using interrupt-driven input. If
+ `nil', Emacs is using CBREAK mode.
+
+ FLOW
+ is non-`nil' if XEmacs uses XON/XOFF (`C-q', `C-s') flow
+ control for output to the terminal. This value has no effect
+ unless INTERRUPT is non-`nil'.
+
+ META
+ is `t' if XEmacs treats the eighth bit of input characters as
+ the meta bit; `nil' means XEmacs clears the eighth bit of
+ every input character; any other value means XEmacs uses all
+ eight bits as the basic character code.
+
+ QUIT
+ is the character XEmacs currently uses for quitting, usually
+ `C-g'.
-Symbol Components
-=================
+\1f
+File: lispref.info, Node: Translating Input, Next: Recording Input, Prev: Input Modes, Up: Terminal Input
+
+Translating Input Events
+------------------------
+
+This section describes features for translating input events into other
+input events before they become part of key sequences.
+
+ - Variable: function-key-map
+ This variable holds a keymap that describes the character sequences
+ sent by function keys on an ordinary character terminal. This
+ keymap uses the same data structure as other keymaps, but is used
+ differently: it specifies translations to make while reading
+ events.
+
+ If `function-key-map' "binds" a key sequence K to a vector V, then
+ when K appears as a subsequence _anywhere_ in a key sequence, it
+ is replaced with the events in V.
+
+ For example, VT100 terminals send `<ESC> O P' when the keypad PF1
+ key is pressed. Therefore, we want XEmacs to translate that
+ sequence of events into the single event `pf1'. We accomplish
+ this by "binding" `<ESC> O P' to `[pf1]' in `function-key-map',
+ when using a VT100.
+
+ Thus, typing `C-c <PF1>' sends the character sequence `C-c <ESC> O
+ P'; later the function `read-key-sequence' translates this back
+ into `C-c <PF1>', which it returns as the vector `[?\C-c pf1]'.
+
+ Entries in `function-key-map' are ignored if they conflict with
+ bindings made in the minor mode, local, or global keymaps. The
+ intent is that the character sequences that function keys send
+ should not have command bindings in their own right.
+
+ The value of `function-key-map' is usually set up automatically
+ according to the terminal's Terminfo or Termcap entry, but
+ sometimes those need help from terminal-specific Lisp files.
+ XEmacs comes with terminal-specific files for many common
+ terminals; their main purpose is to make entries in
+ `function-key-map' beyond those that can be deduced from Termcap
+ and Terminfo. *Note Terminal-Specific::.
+
+ Emacs versions 18 and earlier used totally different means of
+ detecting the character sequences that represent function keys.
+
+ - Variable: key-translation-map
+ This variable is another keymap used just like `function-key-map'
+ to translate input events into other events. It differs from
+ `function-key-map' in two ways:
+
+ * `key-translation-map' goes to work after `function-key-map' is
+ finished; it receives the results of translation by
+ `function-key-map'.
+
+ * `key-translation-map' overrides actual key bindings.
+
+ The intent of `key-translation-map' is for users to map one
+ character set to another, including ordinary characters normally
+ bound to `self-insert-command'.
+
+ You can use `function-key-map' or `key-translation-map' for more
+than simple aliases, by using a function, instead of a key sequence, as
+the "translation" of a key. Then this function is called to compute
+the translation of that key.
+
+ The key translation function receives one argument, which is the
+prompt that was specified in `read-key-sequence'--or `nil' if the key
+sequence is being read by the editor command loop. In most cases you
+can ignore the prompt value.
+
+ If the function reads input itself, it can have the effect of
+altering the event that follows. For example, here's how to define
+`C-c h' to turn the character that follows into a Hyper character:
+
+ (defun hyperify (prompt)
+ (let ((e (read-event)))
+ (vector (if (numberp e)
+ (logior (lsh 1 20) e)
+ (if (memq 'hyper (event-modifiers e))
+ e
+ (add-event-modifier "H-" e))))))
+
+ (defun add-event-modifier (string e)
+ (let ((symbol (if (symbolp e) e (car e))))
+ (setq symbol (intern (concat string
+ (symbol-name symbol))))
+ (if (symbolp e)
+ symbol
+ (cons symbol (cdr e)))))
+
+ (define-key function-key-map "\C-ch" 'hyperify)
+
+ The `iso-transl' library uses this feature to provide a way of
+inputting non-ASCII Latin-1 characters.
- Each symbol has four components (or "cells"), each of which
-references another object:
-
-Print name
- The "print name cell" holds a string that names the symbol for
- reading and printing. See `symbol-name' in *Note Creating
- Symbols::.
-
-Value
- The "value cell" holds the current value of the symbol as a
- variable. When a symbol is used as a form, the value of the form
- is the contents of the symbol's value cell. See `symbol-value' in
- *Note Accessing Variables::.
-
-Function
- The "function cell" holds the function definition of the symbol.
- When a symbol is used as a function, its function definition is
- used in its place. This cell is also used to make a symbol stand
- for a keymap or a keyboard macro, for editor command execution.
- Because each symbol has separate value and function cells,
- variables and function names do not conflict. See
- `symbol-function' in *Note Function Cells::.
-
-Property list
- The "property list cell" holds the property list of the symbol.
- See `symbol-plist' in *Note Symbol Properties::.
-
- The print name cell always holds a string, and cannot be changed.
-The other three cells can be set individually to any specified Lisp
-object.
-
- The print name cell holds the string that is the name of the symbol.
-Since symbols are represented textually by their names, it is important
-not to have two symbols with the same name. The Lisp reader ensures
-this: every time it reads a symbol, it looks for an existing symbol with
-the specified name before it creates a new one. (In XEmacs Lisp, this
-lookup uses a hashing algorithm and an obarray; see *Note Creating
-Symbols::.)
-
- In normal usage, the function cell usually contains a function or
-macro, as that is what the Lisp interpreter expects to see there (*note
-Evaluation::). Keyboard macros (*note Keyboard Macros::), keymaps
-(*note Keymaps::) and autoload objects (*note Autoloading::) are also
-sometimes stored in the function cell of symbols. We often refer to
-"the function `foo'" when we really mean the function stored in the
-function cell of the symbol `foo'. We make the distinction only when
-necessary.
-
- The property list cell normally should hold a correctly formatted
-property list (*note Property Lists::), as a number of functions expect
-to see a property list there.
-
- The function cell or the value cell may be "void", which means that
-the cell does not reference any object. (This is not the same thing as
-holding the symbol `void', nor the same as holding the symbol `nil'.)
-Examining a cell that is void results in an error, such as `Symbol's
-value as variable is void'.
-
- The four functions `symbol-name', `symbol-value', `symbol-plist',
-and `symbol-function' return the contents of the four cells of a
-symbol. Here as an example we show the contents of the four cells of
-the symbol `buffer-file-name':
-
- (symbol-name 'buffer-file-name)
- => "buffer-file-name"
- (symbol-value 'buffer-file-name)
- => "/gnu/elisp/symbols.texi"
- (symbol-plist 'buffer-file-name)
- => (variable-documentation 29529)
- (symbol-function 'buffer-file-name)
- => #<subr buffer-file-name>
-
-Because this symbol is the variable which holds the name of the file
-being visited in the current buffer, the value cell contents we see are
-the name of the source file of this chapter of the XEmacs Lisp Reference
-Manual. The property list cell contains the list
-`(variable-documentation 29529)' which tells the documentation
-functions where to find the documentation string for the variable
-`buffer-file-name' in the `DOC' file. (29529 is the offset from the
-beginning of the `DOC' file to where that documentation string begins.)
-The function cell contains the function for returning the name of the
-file. `buffer-file-name' names a primitive function, which has no read
-syntax and prints in hash notation (*note Primitive Function Type::). A
-symbol naming a function written in Lisp would have a lambda expression
-(or a byte-code object) in this cell.
-
-\1f
-File: lispref.info, Node: Definitions, Next: Creating Symbols, Prev: Symbol Components, Up: Symbols
-
-Defining Symbols
-================
+\1f
+File: lispref.info, Node: Recording Input, Prev: Translating Input, Up: Terminal Input
- A "definition" in Lisp is a special form that announces your
-intention to use a certain symbol in a particular way. In XEmacs Lisp,
-you can define a symbol as a variable, or define it as a function (or
-macro), or both independently.
-
- A definition construct typically specifies a value or meaning for the
-symbol for one kind of use, plus documentation for its meaning when used
-in this way. Thus, when you define a symbol as a variable, you can
-supply an initial value for the variable, plus documentation for the
-variable.
-
- `defvar' and `defconst' are special forms that define a symbol as a
-global variable. They are documented in detail in *Note Defining
-Variables::.
-
- `defun' defines a symbol as a function, creating a lambda expression
-and storing it in the function cell of the symbol. This lambda
-expression thus becomes the function definition of the symbol. (The
-term "function definition", meaning the contents of the function cell,
-is derived from the idea that `defun' gives the symbol its definition
-as a function.) `defsubst', `define-function' and `defalias' are other
-ways of defining a function. *Note Functions::.
-
- `defmacro' defines a symbol as a macro. It creates a macro object
-and stores it in the function cell of the symbol. Note that a given
-symbol can be a macro or a function, but not both at once, because both
-macro and function definitions are kept in the function cell, and that
-cell can hold only one Lisp object at any given time. *Note Macros::.
-
- In XEmacs Lisp, a definition is not required in order to use a symbol
-as a variable or function. Thus, you can make a symbol a global
-variable with `setq', whether you define it first or not. The real
-purpose of definitions is to guide programmers and programming tools.
-They inform programmers who read the code that certain symbols are
-_intended_ to be used as variables, or as functions. In addition,
-utilities such as `etags' and `make-docfile' recognize definitions, and
-add appropriate information to tag tables and the `DOC' file. *Note
-Accessing Documentation::.
-
-\1f
-File: lispref.info, Node: Creating Symbols, Next: Symbol Properties, Prev: Definitions, Up: Symbols
-
-Creating and Interning Symbols
-==============================
+Recording Input
+---------------
- To understand how symbols are created in XEmacs Lisp, you must know
-how Lisp reads them. Lisp must ensure that it finds the same symbol
-every time it reads the same set of characters. Failure to do so would
-cause complete confusion.
-
- When the Lisp reader encounters a symbol, it reads all the characters
-of the name. Then it "hashes" those characters to find an index in a
-table called an "obarray". Hashing is an efficient method of looking
-something up. For example, instead of searching a telephone book cover
-to cover when looking up Jan Jones, you start with the J's and go from
-there. That is a simple version of hashing. Each element of the
-obarray is a "bucket" which holds all the symbols with a given hash
-code; to look for a given name, it is sufficient to look through all
-the symbols in the bucket for that name's hash code.
-
- If a symbol with the desired name is found, the reader uses that
-symbol. If the obarray does not contain a symbol with that name, the
-reader makes a new symbol and adds it to the obarray. Finding or adding
-a symbol with a certain name is called "interning" it, and the symbol
-is then called an "interned symbol".
-
- Interning ensures that each obarray has just one symbol with any
-particular name. Other like-named symbols may exist, but not in the
-same obarray. Thus, the reader gets the same symbols for the same
-names, as long as you keep reading with the same obarray.
-
- No obarray contains all symbols; in fact, some symbols are not in any
-obarray. They are called "uninterned symbols". An uninterned symbol
-has the same four cells as other symbols; however, the only way to gain
-access to it is by finding it in some other object or as the value of a
-variable.
-
- In XEmacs Lisp, an obarray is actually a vector. Each element of the
-vector is a bucket; its value is either an interned symbol whose name
-hashes to that bucket, or 0 if the bucket is empty. Each interned
-symbol has an internal link (invisible to the user) to the next symbol
-in the bucket. Because these links are invisible, there is no way to
-find all the symbols in an obarray except using `mapatoms' (below).
-The order of symbols in a bucket is not significant.
-
- In an empty obarray, every element is 0, and you can create an
-obarray with `(make-vector LENGTH 0)'. *This is the only valid way to
-create an obarray.* Prime numbers as lengths tend to result in good
-hashing; lengths one less than a power of two are also good.
-
- *Do not try to put symbols in an obarray yourself.* This does not
-work--only `intern' can enter a symbol in an obarray properly. *Do not
-try to intern one symbol in two obarrays.* This would garble both
-obarrays, because a symbol has just one slot to hold the following
-symbol in the obarray bucket. The results would be unpredictable.
-
- It is possible for two different symbols to have the same name in
-different obarrays; these symbols are not `eq' or `equal'. However,
-this normally happens only as part of the abbrev mechanism (*note
-Abbrevs::).
-
- Common Lisp note: In Common Lisp, a single symbol may be interned
- in several obarrays.
-
- Most of the functions below take a name and sometimes an obarray as
-arguments. A `wrong-type-argument' error is signaled if the name is
-not a string, or if the obarray is not a vector.
-
- - Function: symbol-name symbol
- This function returns the string that is SYMBOL's name. For
- example:
-
- (symbol-name 'foo)
- => "foo"
-
- Changing the string by substituting characters, etc, does change
- the name of the symbol, but fails to update the obarray, so don't
- do it!
-
- - Function: make-symbol name
- This function returns a newly-allocated, uninterned symbol whose
- name is NAME (which must be a string). Its value and function
- definition are void, and its property list is `nil'. In the
- example below, the value of `sym' is not `eq' to `foo' because it
- is a distinct uninterned symbol whose name is also `foo'.
-
- (setq sym (make-symbol "foo"))
- => foo
- (eq sym 'foo)
- => nil
+ - Function: recent-keys &optional number
+ This function returns a vector containing recent input events from
+ the keyboard or mouse. By default, 100 events are recorded, which
+ is how many `recent-keys' returns.
- - Function: intern name &optional obarray
- This function returns the interned symbol whose name is NAME. If
- there is no such symbol in the obarray OBARRAY, `intern' creates a
- new one, adds it to the obarray, and returns it. If OBARRAY is
- omitted, the value of the global variable `obarray' is used.
+ All input events are included, whether or not they were used as
+ parts of key sequences. Thus, you always get the last 100 inputs,
+ not counting keyboard macros. (Events from keyboard macros are
+ excluded because they are less interesting for debugging; it
+ should be enough to see the events that invoked the macros.)
- (setq sym (intern "foo"))
- => foo
- (eq sym 'foo)
- => t
-
- (setq sym1 (intern "foo" other-obarray))
- => foo
- (eq sym 'foo)
- => nil
+ If NUMBER is specified, not more than NUMBER events will be
+ returned. You may change the number of stored events using
+ `set-recent-keys-ring-size'.
+
+ - Function: recent-keys-ring-size
+ This function returns the number of recent events stored
+ internally. This is also the maximum number of events
+ `recent-keys' can return. By default, 100 events are stored.
+
+ - Function: set-recent-keys-ring-size size
+ This function changes the number of events stored by XEmacs and
+ returned by `recent-keys'.
+
+ For example, `(set-recent-keys-ring-size 250)' will make XEmacs
+ remember last 250 events and will make `recent-keys' return last
+ 250 events by default.
+
+ - Command: open-dribble-file filename
+ This function opens a "dribble file" named FILENAME. When a
+ dribble file is open, each input event from the keyboard or mouse
+ (but not those from keyboard macros) is written in that file. A
+ non-character event is expressed using its printed representation
+ surrounded by `<...>'.
+
+ You close the dribble file by calling this function with an
+ argument of `nil'.
- - Function: intern-soft name &optional obarray
- This function returns the symbol in OBARRAY whose name is NAME, or
- `nil' if OBARRAY has no symbol with that name. Therefore, you can
- use `intern-soft' to test whether a symbol with a given name is
- already interned. If OBARRAY is omitted, the value of the global
- variable `obarray' is used.
+ This function is normally used to record the input necessary to
+ trigger an XEmacs bug, for the sake of a bug report.
- (intern-soft "frazzle") ; No such symbol exists.
+ (open-dribble-file "~/dribble")
=> nil
- (make-symbol "frazzle") ; Create an uninterned one.
- => frazzle
- (intern-soft "frazzle") ; That one cannot be found.
+
+ See also the `open-termscript' function (*note Terminal Output::).
+
+\1f
+File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
+
+Terminal Output
+===============
+
+The terminal output functions send output to the terminal or keep track
+of output sent to the terminal. The function `device-baud-rate' tells
+you what XEmacs thinks is the output speed of the terminal.
+
+ - Function: device-baud-rate &optional device
+ This function's value is the output speed of the terminal
+ associated with DEVICE, as far as XEmacs knows. DEVICE defaults
+ to the selected device (usually the only device) if omitted.
+ Changing this value does not change the speed of actual data
+ transmission, but the value is used for calculations such as
+ padding. This value has no effect for window-system devices.
+ (This is different in FSF Emacs, where the baud rate also affects
+ decisions about whether to scroll part of the screen or repaint,
+ even when using a window system.)
+
+ The value is measured in bits per second.
+
+ XEmacs attempts to automatically initialize the baud rate by querying
+the terminal. If you are running across a network, however, and
+different parts of the network work are at different baud rates, the
+value returned by XEmacs may be different from the value used by your
+local terminal. Some network protocols communicate the local terminal
+speed to the remote machine, so that XEmacs and other programs can get
+the proper value, but others do not. If XEmacs has the wrong value, it
+makes decisions that are less than optimal. To fix the problem, use
+`set-device-baud-rate'.
+
+ - Function: set-device-baud-rate device baud-rate
+ This function sets the output speed of DEVICE. See
+ `device-baud-rate'. DEVICE defaults to the selected device
+ (usually the only device) if `nil'.
+
+ - Function: send-string-to-terminal char-or-string &optional stdout-p
+ device
+ This function sends CHAR-OR-STRING to the terminal without
+ alteration. Control characters in CHAR-OR-STRING have
+ terminal-dependent effects.
+
+ If DEVICE is `nil', this function writes to XEmacs's stderr, or to
+ stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
+ tty or stream device, and the function writes to the device's
+ normal or error output, according to STDOUT-P.
+
+ One use of this function is to define function keys on terminals
+ that have downloadable function key definitions. For example,
+ this is how on certain terminals to define function key 4 to move
+ forward four characters (by transmitting the characters `C-u C-f'
+ to the computer):
+
+ (send-string-to-terminal "\eF4\^U\^F")
=> nil
- (setq sym (intern "frazzle")) ; Create an interned one.
- => frazzle
- (intern-soft "frazzle") ; That one can be found!
- => frazzle
- (eq sym 'frazzle) ; And it is the same one.
- => t
- - Variable: obarray
- This variable is the standard obarray for use by `intern' and
- `read'.
-
- - Function: mapatoms function &optional obarray
- This function calls FUNCTION for each symbol in the obarray
- OBARRAY. It returns `nil'. If OBARRAY is omitted, it defaults to
- the value of `obarray', the standard obarray for ordinary symbols.
-
- (setq count 0)
- => 0
- (defun count-syms (s)
- (setq count (1+ count)))
- => count-syms
- (mapatoms 'count-syms)
+ - Command: open-termscript filename
+ This function is used to open a "termscript file" that will record
+ all the characters sent by XEmacs to the terminal. (If there are
+ multiple tty or stream devices, all characters sent to all such
+ devices are recorded.) The function returns `nil'. Termscript
+ files are useful for investigating problems where XEmacs garbles
+ the screen, problems that are due to incorrect Termcap entries or
+ to undesirable settings of terminal options more often than to
+ actual XEmacs bugs. Once you are certain which characters were
+ actually output, you can determine reliably whether they
+ correspond to the Termcap specifications in use.
+
+ A `nil' value for FILENAME stops recording terminal output.
+
+ See also `open-dribble-file' in *Note Terminal Input::.
+
+ (open-termscript "../junk/termscript")
=> nil
- count
- => 1871
- See `documentation' in *Note Accessing Documentation::, for another
- example using `mapatoms'.
+\1f
+File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
+
+Flow Control
+============
+
+This section attempts to answer the question "Why does XEmacs choose to
+use flow-control characters in its command character set?" For a
+second view on this issue, read the comments on flow control in the
+`emacs/INSTALL' file from the distribution; for help with Termcap
+entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
+
+ At one time, most terminals did not need flow control, and none used
+`C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
+`C-q' as command characters was uncontroversial. XEmacs, for economy
+of keystrokes and portability, used nearly all the ASCII control
+characters, with mnemonic meanings when possible; thus, `C-s' for
+search and `C-q' for quote.
+
+ Later, some terminals were introduced which required these characters
+for flow control. They were not very good terminals for full-screen
+editing, so XEmacs maintainers did not pay attention. In later years,
+flow control with `C-s' and `C-q' became widespread among terminals,
+but by this time it was usually an option. And the majority of users,
+who can turn flow control off, were unwilling to switch to less
+mnemonic key bindings for the sake of flow control.
+
+ So which usage is "right", XEmacs's or that of some terminal and
+concentrator manufacturers? This question has no simple answer.
+
+ One reason why we are reluctant to cater to the problems caused by
+`C-s' and `C-q' is that they are gratuitous. There are other
+techniques (albeit less common in practice) for flow control that
+preserve transparency of the character stream. Note also that their use
+for flow control is not an official standard. Interestingly, on the
+model 33 teletype with a paper tape punch (which is very old), `C-s'
+and `C-q' were sent by the computer to turn the punch on and off!
+
+ As X servers and other window systems replace character-only
+terminals, this problem is gradually being cured. For the mean time,
+XEmacs provides a convenient way of enabling flow control if you want
+it: call the function `enable-flow-control'.
+
+ - Command: enable-flow-control &optional argument
+ This function enables use of `C-s' and `C-q' for output flow
+ control, and provides the characters `C-\' and `C-^' as aliases
+ for them using `keyboard-translate-table' (*note Translating
+ Input::).
+
+ With optional argument ARGUMENT (interactively the prefix
+ argument), enable flow control mode if ARGUMENT is positive; else
+ disable it.
+
+ You can use the function `enable-flow-control-on' in your `.emacs'
+file to enable flow control automatically on certain terminal types.
+
+ - Function: enable-flow-control-on &rest termtypes
+ This function enables flow control, and the aliases `C-\' and
+ `C-^', if the terminal type is one of TERMTYPES. For example:
+
+ (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
+
+ Here is how `enable-flow-control' does its job:
+
+ 1. It sets CBREAK mode for terminal input, and tells the operating
+ system to handle flow control, with `(set-input-mode nil t)'.
+
+ 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
+ into `C-s' and `C-q'. Except at its very lowest level, XEmacs
+ never knows that the characters typed were anything but `C-s' and
+ `C-q', so you can in effect type them as `C-\' and `C-^' even when
+ they are input for other commands. *Note Translating Input::.
+
+ If the terminal is the source of the flow control characters, then
+once you enable kernel flow control handling, you probably can make do
+with less padding than normal for that terminal. You can reduce the
+amount of padding by customizing the Termcap entry. You can also
+reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
+a smaller speed when calculating the padding needed. *Note Terminal
+Output::.
+
+\1f
+File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
+
+Batch Mode
+==========
+
+The command line option `-batch' causes XEmacs to run noninteractively.
+In this mode, XEmacs does not read commands from the terminal, it does
+not alter the terminal modes, and it does not expect to be outputting
+to an erasable screen. The idea is that you specify Lisp programs to
+run; when they are finished, XEmacs should exit. The way to specify
+the programs to run is with `-l FILE', which loads the library named
+FILE, and `-f FUNCTION', which calls FUNCTION with no arguments.
+
+ Any Lisp program output that would normally go to the echo area,
+either using `message' or using `prin1', etc., with `t' as the stream,
+goes instead to XEmacs's standard error descriptor when in batch mode.
+Thus, XEmacs behaves much like a noninteractive application program.
+(The echo area output that XEmacs itself normally generates, such as
+command echoing, is suppressed entirely.)
+
+ - Function: noninteractive
+ This function returns non-`nil' when XEmacs is running in batch
+ mode.
+
+ - Variable: noninteractive
+ This variable is non-`nil' when XEmacs is running in batch mode.
+ Setting this variable to `nil', however, will not change whether
+ XEmacs is running in batch mode, and will not change the return
+ value of the `noninteractive' function.
+
+\1f
+File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
+
+Functions Specific to the X Window System
+*****************************************
- - Function: unintern symbol &optional obarray
- This function deletes SYMBOL from the obarray OBARRAY. If
- `symbol' is not actually in the obarray, `unintern' does nothing.
- If OBARRAY is `nil', the current obarray is used.
+XEmacs provides the concept of "devices", which generalizes connections
+to an X server, a TTY device, etc. Most information about an X server
+that XEmacs is connected to can be determined through general console
+and device functions. *Note Consoles and Devices::. However, there
+are some features of the X Window System that do not generalize well,
+and they are covered specially here.
- If you provide a string instead of a symbol as SYMBOL, it stands
- for a symbol name. Then `unintern' deletes the symbol (if any) in
- the obarray which has that name. If there is no such symbol,
- `unintern' does nothing.
+* Menu:
- If `unintern' does delete a symbol, it returns `t'. Otherwise it
- returns `nil'.
+* X Selections:: Transferring text to and from other X clients.
+* X Server:: Information about the X server connected to
+ a particular device.
+* X Miscellaneous:: Other X-specific functions and variables.
\1f
-File: lispref.info, Node: Symbol Properties, Prev: Creating Symbols, Up: Symbols
+File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
+
+X Selections
+============
+
+The X server records a set of "selections" which permit transfer of
+data between application programs. The various selections are
+distinguished by "selection types", represented in XEmacs by symbols.
+X clients including XEmacs can read or set the selection for any given
+type.
+
+ - Function: x-own-selection data &optional type
+ This function sets a "selection" in the X server. It takes two
+ arguments: a value, DATA, and the selection type TYPE to assign it
+ to. DATA may be a string, a cons of two markers, or an extent.
+ In the latter cases, the selection is considered to be the text
+ between the markers, or between the extent's endpoints.
+
+ Each possible TYPE has its own selection value, which changes
+ independently. The usual values of TYPE are `PRIMARY' and
+ `SECONDARY'; these are symbols with upper-case names, in accord
+ with X Windows conventions. The default is `PRIMARY'.
+
+ (In FSF Emacs, this function is called `x-set-selection' and takes
+ different arguments.)
+
+ - Function: x-get-selection
+ This function accesses selections set up by XEmacs or by other X
+ clients. It returns the value of the current primary selection.
+
+ - Function: x-disown-selection &optional secondary-p
+ Assuming we own the selection, this function disowns it. If
+ SECONDARY-P is non-`nil', the secondary selection instead of the
+ primary selection is discarded.
+
+ The X server also has a set of numbered "cut buffers" which can
+store text or other data being moved between applications. Cut buffers
+are considered obsolete, but XEmacs supports them for the sake of X
+clients that still use them.
+
+ - Function: x-get-cutbuffer &optional n
+ This function returns the contents of cut buffer number N. (This
+ function is called `x-get-cut-buffer' in FSF Emacs.)
+
+ - Function: x-store-cutbuffer string &optional push
+ This function stores STRING into the first cut buffer (cut buffer
+ 0).
+
+ Normally, the contents of the first cut buffer are simply replaced
+ by STRING. However, if optional argument PUSH is non-`nil', the
+ cut buffers are rotated. This means that the previous value of
+ the first cut buffer moves to the second cut buffer, and the
+ second to the third, and so on, moving the other values down
+ through the series of cut buffers, kill-ring-style. There are 8
+ cut buffers altogether.
+
+ Cut buffers are considered obsolete; you should use selections
+ instead.
+
+ This function has no effect if support for cut buffers was not
+ compiled in.
+
+ This function is called `x-set-cut-buffer' in FSF Emacs.
-Symbol Properties
-=================
+\1f
+File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
+
+X Server
+========
+
+This section describes how to access and change the overall status of
+the X server XEmacs is using.
+
+* Menu:
+
+* Resources:: Getting resource values from the server.
+* Server Data:: Getting info about the X server.
+* Grabs:: Restricting access to the server by other apps.
+
+\1f
+File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
+
+Resources
+---------
+
+ - Function: default-x-device
+ This function return the default X device for resourcing. This is
+ the first-created X device that still exists.
+
+ - Function: x-get-resource name class type &optional locale device
+ noerror
+ This function retrieves a resource value from the X resource
+ manager.
+
+ * The first arg is the name of the resource to retrieve, such as
+ `"font"'.
+
+ * The second arg is the class of the resource to retrieve, like
+ `"Font"'.
+
+ * The third arg should be one of the symbols `string',
+ `integer', `natnum', or `boolean', specifying the type of
+ object that the database is searched for.
+
+ * The fourth arg is the locale to search for the resources on,
+ and can currently be a buffer, a frame, a device, or the
+ symbol `global'. If omitted, it defaults to `global'.
+
+ * The fifth arg is the device to search for the resources on.
+ (The resource database for a particular device is constructed
+ by combining non-device- specific resources such any
+ command-line resources specified and any app-defaults files
+ found [or the fallback resources supplied by XEmacs, if no
+ app-defaults file is found] with device-specific resources
+ such as those supplied using `xrdb'.) If omitted, it defaults
+ to the device of LOCALE, if a device can be derived (i.e. if
+ LOCALE is a frame or device), and otherwise defaults to the
+ value of `default-x-device'.
+
+ * The sixth arg NOERROR, if non-`nil', means do not signal an
+ error if a bogus resource specification was retrieved (e.g.
+ if a non-integer was given when an integer was requested).
+ In this case, a warning is issued instead.
+
+ The resource names passed to this function are looked up relative
+ to the locale.
+
+ If you want to search for a subresource, you just need to specify
+ the resource levels in NAME and CLASS. For example, NAME could be
+ `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
+
+ Specifically,
+
+ 1. If LOCALE is a buffer, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
+ "String");'
+
+ 2. If LOCALE is a frame, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
+ "String");'
+
+ 3. If LOCALE is a device, a call
+
+ `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
+ "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
+ "String");'
+
+ 4. If LOCALE is the symbol `global', a call
+
+ `(x-get-resource "foreground" "Foreground" 'string 'global)'
+
+ is an interface to a C call something like
+
+ `XrmGetResource (db, "xemacs.foreground",
+ "Emacs.Foreground",
+ "String");'
+
+ Note that for `global', no prefix is added other than that of the
+ application itself; thus, you can use this locale to retrieve
+ arbitrary application resources, if you really want to.
+
+ The returned value of this function is `nil' if the queried
+ resource is not found. If TYPE is `string', a string is returned,
+ and if it is `integer', an integer is returned. If TYPE is
+ `boolean', then the returned value is the list `(t)' for true,
+ `(nil)' for false, and is `nil' to mean "unspecified".
+
+ - Function: x-put-resource resource-line &optional device
+ This function adds a resource to the resource database for DEVICE.
+ RESOURCE-LINE specifies the resource to add and should be a
+ standard resource specification.
+
+ - Variable: x-emacs-application-class
+ This variable holds The X application class of the XEmacs process.
+ This controls, among other things, the name of the "app-defaults"
+ file that XEmacs will use. For changes to this variable to take
+ effect, they must be made before the connection to the X server is
+ initialized, that is, this variable may only be changed before
+ XEmacs is dumped, or by setting it in the file
+ `lisp/term/x-win.el'.
+
+ By default, this variable is `nil' at startup. When the connection
+ to the X server is first initialized, the X resource database will
+ be consulted and the value will be set according to whether any
+ resources are found for the application class "XEmacs".
- A "property list" ("plist" for short) is a list of paired elements,
-often stored in the property list cell of a symbol. Each of the pairs
-associates a property name (usually a symbol) with a property or value.
-Property lists are generally used to record information about a
-symbol, such as its documentation as a variable, the name of the file
-where it was defined, or perhaps even the grammatical class of the
-symbol (representing a word) in a language-understanding system.
+\1f
+File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
+
+Data about the X Server
+-----------------------
+
+This section describes functions and a variable that you can use to get
+information about the capabilities and origin of the X server
+corresponding to a particular device. The device argument is generally
+optional and defaults to the selected device.
+
+ - Function: x-server-version &optional device
+ This function returns the list of version numbers of the X server
+ DEVICE is on. The returned value is a list of three integers: the
+ major and minor version numbers of the X protocol in use, and the
+ vendor-specific release number.
+
+ - Function: x-server-vendor &optional device
+ This function returns the vendor supporting the X server DEVICE is
+ on.
+
+ - Function: x-display-visual-class &optional device
+ This function returns the visual class of the display DEVICE is
+ on. The value is one of the symbols `static-gray', `gray-scale',
+ `static-color', `pseudo-color', `true-color', and `direct-color'.
+ (Note that this is different from previous versions of XEmacs,
+ which returned `StaticGray', `GrayScale', etc.)
+
+\1f
+File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
+
+Restricting Access to the Server by Other Apps
+----------------------------------------------
+
+ - Function: x-grab-keyboard &optional device
+ This function grabs the keyboard on the given device (defaulting
+ to the selected one). So long as the keyboard is grabbed, all
+ keyboard events will be delivered to XEmacs--it is not possible
+ for other X clients to eavesdrop on them. Ungrab the keyboard
+ with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
+ if the grab was successful; `nil' otherwise.
+
+ - Function: x-ungrab-keyboard &optional device
+ This function releases a keyboard grab made with `x-grab-keyboard'.
+
+ - Function: x-grab-pointer &optional device cursor ignore-keyboard
+ This function grabs the pointer and restricts it to its current
+ window. If optional DEVICE argument is `nil', the selected device
+ will be used. If optional CURSOR argument is non-`nil', change
+ the pointer shape to that until `x-ungrab-pointer' is called (it
+ should be an object returned by the `make-cursor' function). If
+ the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
+ all keyboard events during the grab. Returns `t' if the grab is
+ successful, `nil' otherwise.
+
+ - Function: x-ungrab-pointer &optional device
+ This function releases a pointer grab made with `x-grab-pointer'.
+ If optional first arg DEVICE is `nil' the selected device is used.
+ If it is `t' the pointer will be released on all X devices.
+
+\1f
+File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
+
+Miscellaneous X Functions and Variables
+=======================================
+
+ - Variable: x-bitmap-file-path
+ This variable holds a list of the directories in which X bitmap
+ files may be found. If `nil', this is initialized from the
+ `"*bitmapFilePath"' resource. This is used by the
+ `make-image-instance' function (however, note that if the
+ environment variable `XBMLANGPATH' is set, it is consulted first).
+
+ - Variable: x-library-search-path
+ This variable holds the search path used by `read-color' to find
+ `rgb.txt'.
+
+ - Function: x-valid-keysym-name-p keysym
+ This function returns true if KEYSYM names a keysym that the X
+ library knows about. Valid keysyms are listed in the files
+ `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
+ whatever the equivalents are on your system.
+
+ - Function: x-window-id &optional frame
+ This function returns the ID of the X11 window. This gives us a
+ chance to manipulate the Emacs window from within a different
+ program. Since the ID is an unsigned long, we return it as a
+ string.
+
+ - Variable: x-allow-sendevents
+ If non-`nil', synthetic events are allowed. `nil' means they are
+ ignored. Beware: allowing XEmacs to process SendEvents opens a
+ big security hole.
+
+ - Function: x-debug-mode arg &optional device
+ With a true arg, make the connection to the X server synchronous.
+ With false, make it asynchronous. Synchronous connections are
+ much slower, but are useful for debugging. (If you get X errors,
+ make the connection synchronous, and use a debugger to set a
+ breakpoint on `x_error_handler'. Your backtrace of the C stack
+ will now be useful. In asynchronous mode, the stack above
+ `x_error_handler' isn't helpful because of buffering.) If DEVICE
+ is not specified, the selected device is assumed.
+
+ Calling this function is the same as calling the C function
+ `XSynchronize', or starting the program with the `-sync' command
+ line argument.
+
+ - Variable: x-debug-events
+ If non-zero, debug information about events that XEmacs sees is
+ displayed. Information is displayed on stderr. Currently defined
+ values are:
+
+ * 1 == non-verbose output
+
+ * 2 == verbose output
+
+\1f
+File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
+
+ToolTalk Support
+****************
+
+* Menu:
+
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::
- Some objects which are not symbols also have property lists
-associated with them, and XEmacs provides a full complement of
-functions for working with property lists. *Note Property Lists::.
+\1f
+File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
+
+XEmacs ToolTalk API Summary
+===========================
+
+The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
+to the standard C ToolTalk API. Only the message and pattern parts of
+the API are supported at present; more of the API could be added if
+needed. The Lisp interface departs from the C API in a few ways:
+
+ * ToolTalk is initialized automatically at XEmacs startup-time.
+ Messages can only be sent other ToolTalk applications connected to
+ the same X11 server that XEmacs is running on.
- The property names and values in a property list can be any Lisp
-objects, but the names are usually symbols. They are compared using
-`eq'. Here is an example of a property list, found on the symbol
-`progn' when the compiler is loaded:
+ * There are fewer entry points; polymorphic functions with keyword
+ arguments are used instead.
- (lisp-indent-function 0 byte-compile byte-compile-progn)
+ * The callback interface is simpler and marginally less functional.
+ A single callback may be associated with a message or a pattern;
+ the callback is specified with a Lisp symbol (the symbol should
+ have a function binding).
+
+ * The session attribute for messages and patterns is always
+ initialized to the default session.
+
+ * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
+ can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
+ simplifies building lists that represent messages and patterns.
+
+\1f
+File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
-Here `lisp-indent-function' and `byte-compile' are property names, and
-the other two elements are the corresponding values.
+Sending Messages
+================
* Menu:
-* Plists and Alists:: Comparison of the advantages of property
- lists and association lists.
-* Object Plists:: Functions to access objects' property lists.
-* Other Plists:: Accessing property lists stored elsewhere.
+* Example of Sending Messages::
+* Elisp Interface for Sending Messages::
+
+\1f
+File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
+
+Example of Sending Messages
+---------------------------
+
+Here's a simple example that sends a query to another application and
+then displays its reply. Both the query and the reply are stored in
+the first argument of the message.
+
+ (defun tooltalk-random-query-handler (msg)
+ (let ((state (get-tooltalk-message-attribute msg 'state)))
+ (cond
+ ((eq state 'TT_HANDLED)
+ (message (get-tooltalk-message-attribute msg arg_val 0)))
+ ((memq state '(TT_FAILED TT_REJECTED))
+ (message "Random query turns up nothing")))))
+
+ (defvar random-query-message
+ '( class TT_REQUEST
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "random-query"
+ args '((TT_INOUT "?" "string"))
+ callback tooltalk-random-query-handler))
+
+ (let ((m (make-tooltalk-message random-query-message)))
+ (send-tooltalk-message m))
\1f
-File: lispref.info, Node: Plists and Alists, Next: Object Plists, Up: Symbol Properties
+File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
-Property Lists and Association Lists
+Elisp Interface for Sending Messages
------------------------------------
- Association lists (*note Association Lists::) are very similar to
-property lists. In contrast to association lists, the order of the
-pairs in the property list is not significant since the property names
-must be distinct.
-
- Property lists are better than association lists for attaching
-information to various Lisp function names or variables. If all the
-associations are recorded in one association list, the program will need
-to search that entire list each time a function or variable is to be
-operated on. By contrast, if the information is recorded in the
-property lists of the function names or variables themselves, each
-search will scan only the length of one property list, which is usually
-short. This is why the documentation for a variable is recorded in a
-property named `variable-documentation'. The byte compiler likewise
-uses properties to record those functions needing special treatment.
-
- However, association lists have their own advantages. Depending on
-your application, it may be faster to add an association to the front of
-an association list than to update a property. All properties for a
-symbol are stored in the same property list, so there is a possibility
-of a conflict between different uses of a property name. (For this
-reason, it is a good idea to choose property names that are probably
-unique, such as by including the name of the library in the property
-name.) An association list may be used like a stack where associations
-are pushed on the front of the list and later discarded; this is not
-possible with a property list.
-
-\1f
-File: lispref.info, Node: Object Plists, Next: Other Plists, Prev: Plists and Alists, Up: Symbol Properties
-
-Property List Functions for Objects
------------------------------------
-
- Once upon a time, only symbols had property lists. Now, several
-other object types, including strings, extents, faces and glyphs also
-have property lists.
-
- - Function: symbol-plist symbol
- This function returns the property list of SYMBOL.
-
- - Function: object-plist object
- This function returns the property list of OBJECT. If OBJECT is a
- symbol, this is identical to `symbol-plist'.
-
- - Function: setplist symbol plist
- This function sets SYMBOL's property list to PLIST. Normally,
- PLIST should be a well-formed property list, but this is not
- enforced.
-
- (setplist 'foo '(a 1 b (2 3) c nil))
- => (a 1 b (2 3) c nil)
- (symbol-plist 'foo)
- => (a 1 b (2 3) c nil)
-
- For symbols in special obarrays, which are not used for ordinary
- purposes, it may make sense to use the property list cell in a
- nonstandard fashion; in fact, the abbrev mechanism does so (*note
- Abbrevs::). But generally, its use is discouraged. Use `put'
- instead. `setplist' can only be used with symbols, not other
- object types.
-
- - Function: get object property &optional default
- This function finds the value of the property named PROPERTY in
- OBJECT's property list. If there is no such property, `default'
- (which itself defaults to `nil') is returned.
-
- PROPERTY is compared with the existing properties using `eq', so
- any object is a legitimate property.
-
- See `put' for an example.
-
- - Function: put object property value
- This function puts VALUE onto OBJECT's property list under the
- property name PROPERTY, replacing any previous property value.
- The `put' function returns VALUE.
-
- (put 'fly 'verb 'transitive)
- =>'transitive
- (put 'fly 'noun '(a buzzing little bug))
- => (a buzzing little bug)
- (get 'fly 'verb)
- => transitive
- (object-plist 'fly)
- => (verb transitive noun (a buzzing little bug))
-
- - Function: remprop object property
- This function removes the entry for PROPERTY from the property
- list of OBJECT. It returns `t' if the property was indeed found
- and removed, or `nil' if there was no such property. (This
- function was probably omitted from Emacs originally because, since
- `get' did not allow a DEFAULT, it was very difficult to
- distinguish between a missing property and a property whose value
- was `nil'; thus, setting a property to `nil' was close enough to
- `remprop' for most purposes.)
-
-\1f
-File: lispref.info, Node: Other Plists, Prev: Object Plists, Up: Symbol Properties
-
-Property Lists Not Associated with Objects
-------------------------------------------
-
- These functions are useful for manipulating property lists that are
-stored in places other than symbols:
-
- - Function: getf plist property &optional default
- This returns the value of the PROPERTY property stored in the
- property list PLIST. For example,
-
- (getf '(foo 4) 'foo)
- => 4
-
- - Macro: putf plist property value
- This stores VALUE as the value of the PROPERTY property in the
- property list PLIST. It may modify PLIST destructively, or it may
- construct a new list structure without altering the old. The
- function returns the modified property list, so you can store that
- back in the place where you got PLIST. For example,
-
- (setq my-plist '(bar t foo 4))
- => (bar t foo 4)
- (setq my-plist (putf my-plist 'foo 69))
- => (bar t foo 69)
- (setq my-plist (putf my-plist 'quux '(a)))
- => (quux (a) bar t foo 5)
-
- - Function: plists-eq a b
- This function returns non-`nil' if property lists A and B are
- `eq'. This means that the property lists have the same values for
- all the same properties, where comparison between values is done
- using `eq'.
-
- - Function: plists-equal a b
- This function returns non-`nil' if property lists A and B are
- `equal'.
-
- Both of the above functions do order-insensitive comparisons.
-
- (plists-eq '(a 1 b 2 c nil) '(b 2 a 1))
- => t
- (plists-eq '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
- => nil
- (plists-equal '(foo "hello" bar "goodbye") '(bar "goodbye" foo "hello"))
- => t
+ - Function: make-tooltalk-message attributes
+ Create a ToolTalk message and initialize its attributes. The
+ value of ATTRIBUTES must be a list of alternating keyword/values,
+ where keywords are symbols that name valid message attributes.
+ For example:
+
+ (make-tooltalk-message
+ '(class TT_NOTICE
+ scope TT_SESSION
+ address TT_PROCEDURE
+ op "do-something"
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants. Attribute names are the same as those
+ supported by `set-tooltalk-message-attribute', plus `args'.
+
+ The value of `args' should be a list of message arguments where
+ each message argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk message arguments in chapter 4 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: send-tooltalk-message msg
+ Send the message on its way. Once the message has been sent it's
+ almost always a good idea to get rid of it with
+ `destroy-tooltalk-message'.
+
+
+ - Function: return-tooltalk-message msg &optional mode
+ Send a reply to this message. The second argument can be `reply',
+ `reject' or `fail'; the default is `reply'. Before sending a
+ reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
+ should have been filled in--see `set-tooltalk-message-attribute'.
+
+
+ - Function: get-tooltalk-message-attribute msg attribute &optional argn
+ Returns the indicated ToolTalk message attribute. Attributes are
+ identified by symbols with the same name (underscores and all) as
+ the suffix of the ToolTalk `tt_message_<attribute>' function that
+ extracts the value. String attribute values are copied and
+ enumerated type values (except disposition) are converted to
+ symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
+ represented by fixnums (small integers), `opnum' is converted to a
+ string, and `disposition' is converted to a fixnum. We convert
+ `opnum' (a C int) to a string (e.g. `123' => `"123"') because
+ there's no guarantee that opnums will fit within the range of
+ XEmacs Lisp integers.
+
+ [TBD] Use the `plist' attribute instead of C API `user' attribute
+ for user-defined message data. To retrieve the value of a message
+ property, specify the indicator for ARGN. For example, to get the
+ value of a property called `rflag', use
+
+ (get-tooltalk-message-attribute msg 'plist 'rflag)
+
+ To get the value of a message argument use one of the `arg_val'
+ (strings), `arg_ival' (integers), or `arg_bval' (strings with
+ embedded nulls), attributes. For example, to get the integer
+ value of the third argument:
+
+ (get-tooltalk-message-attribute msg 'arg_ival 2)
+
+ As you can see, argument numbers are zero-based. The type of each
+ arguments can be retrieved with the `arg_type' attribute; however
+ ToolTalk doesn't define any semantics for the string value of
+ `arg_type'. Conventionally `string' is used for strings and `int'
+ for 32 bit integers. Note that XEmacs Lisp stores the lengths of
+ strings explicitly (unlike C) so treating the value returned by
+ `arg_bval' like a string is fine.
+
+
+ - Function: set-tooltalk-message-attribute value msg attribute
+ &optional argn
+ Initialize one ToolTalk message attribute.
+
+ Attribute names and values are the same as for
+ `get-tooltalk-message-attribute'. A property list is provided for
+ user data (instead of the `user' message attribute); see
+ `get-tooltalk-message-attribute'.
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the state of the message
+ changes. This is usually used to notice when the message's state
+ has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
+ argument values can be used.
+
+ If one of the argument attributes is specified as `arg_val',
+ `arg_ival', or `arg_bval', then ARGN must be the number of an
+ already created argument. Arguments can be added to a message
+ with `add-tooltalk-message-arg'.
+
+
+ - Function: add-tooltalk-message-arg msg mode type &optional value
+ Append one new argument to the message. MODE must be one of
+ `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
+ can be a string or an integer. ToolTalk doesn't define any
+ semantics for TYPE, so only the participants in the protocol
+ you're using need to agree what types mean (if anything).
+ Conventionally `string' is used for strings and `int' for 32 bit
+ integers. Arguments can initialized by providing a value or with
+ `set-tooltalk-message-attribute'; the latter is necessary if you
+ want to initialize the argument with a string that can contain
+ embedded nulls (use `arg_bval').
+
+
+ - Function: create-tooltalk-message &optional no-callback
+ Create a new ToolTalk message. The message's session attribute is
+ initialized to the default session. Other attributes can be
+ initialized with `set-tooltalk-message-attribute'.
+ `make-tooltalk-message' is the preferred way to create and
+ initialize a message.
+
+ Optional arg NO-CALLBACK says don't add a C-level callback at all.
+ Normally don't do that; just don't specify the Lisp callback when
+ calling `make-tooltalk-message'.
+
+
+ - Function: destroy-tooltalk-message msg
+ Apply `tt_message_destroy' to the message. It's not necessary to
+ destroy messages after they've been processed by a message or
+ pattern callback, the Lisp/ToolTalk callback machinery does this
+ for you.
+
+\1f
+File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
+
+Receiving Messages
+==================
+
+* Menu:
+
+* Example of Receiving Messages::
+* Elisp Interface for Receiving Messages::
+
+\1f
+File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
+
+Example of Receiving Messages
+-----------------------------
+
+Here's a simple example of a handler for a message that tells XEmacs to
+display a string in the mini-buffer area. The message operation is
+called `emacs-display-string'. Its first (0th) argument is the string
+to display.
+
+ (defun tooltalk-display-string-handler (msg)
+ (message (get-tooltalk-message-attribute msg 'arg_val 0)))
+
+ (defvar display-string-pattern
+ '(category TT_HANDLE
+ scope TT_SESSION
+ op "emacs-display-string"
+ callback tooltalk-display-string-handler))
+
+ (let ((p (make-tooltalk-pattern display-string-pattern)))
+ (register-tooltalk-pattern p))
+
+\1f
+File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
+
+Elisp Interface for Receiving Messages
+--------------------------------------
+
+ - Function: make-tooltalk-pattern attributes
+ Create a ToolTalk pattern and initialize its attributes. The
+ value of attributes must be a list of alternating keyword/values,
+ where keywords are symbols that name valid pattern attributes or
+ lists of valid attributes. For example:
+
+ (make-tooltalk-pattern
+ '(category TT_OBSERVE
+ scope TT_SESSION
+ op ("operation1" "operation2")
+ args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
+
+ Attribute names are the same as those supported by
+ `add-tooltalk-pattern-attribute', plus `'args'.
+
+ Values must always be strings, integers, or symbols that represent
+ ToolTalk constants or lists of same. When a list of values is
+ provided all of the list elements are added to the attribute. In
+ the example above, messages whose `op' attribute is `"operation1"'
+ or `"operation2"' would match the pattern.
+
+ The value of ARGS should be a list of pattern arguments where each
+ pattern argument has the following form:
+
+ `(mode [value [type]])' or just `value'
+
+ Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
+ a string. If TYPE isn't specified then `int' is used if VALUE is
+ a number; otherwise `string' is used. If TYPE is `string' then
+ VALUE is converted to a string (if it isn't a string already) with
+ `prin1-to-string'. If only a value is specified then MODE
+ defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
+ don't need to be specified. You can find out more about the
+ semantics and uses of ToolTalk pattern arguments in chapter 3 of
+ the `ToolTalk Programmer's Guide'.
+
+
+ - Function: register-tooltalk-pattern pattern
+ XEmacs will begin receiving messages that match this pattern.
+
+ - Function: unregister-tooltalk-pattern pattern
+ XEmacs will stop receiving messages that match this pattern.
+
+ - Function: add-tooltalk-pattern-attribute value pattern indicator
+ Add one value to the indicated pattern attribute. The names of
+ attributes are the same as the ToolTalk accessors used to set them
+ less the `tooltalk_pattern_' prefix and the `_add' suffix. For
+ example, the name of the attribute for the
+ `tt_pattern_disposition_add' attribute is `disposition'. The
+ `category' attribute is handled specially, since a pattern can only
+ be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
+
+ Callbacks are handled slightly differently than in the C ToolTalk
+ API. The value of CALLBACK should be the name of a function of one
+ argument. It will be called each time the pattern matches an
+ incoming message.
+
+ - Function: add-tooltalk-pattern-arg pattern mode vtype &optional value
+ Add one fully-specified argument to a ToolTalk pattern. MODE must
+ be one of `TT_IN', `TT_INOUT', or `TT_OUT'. VTYPE must be a
+ string. VALUE can be an integer, string or `nil'. If VALUE is an
+ integer then an integer argument (`tt_pattern_iarg_add') is added;
+ otherwise a string argument is added. At present there's no way
+ to add a binary data argument.
+
+
+ - Function: create-tooltalk-pattern
+ Create a new ToolTalk pattern and initialize its session attribute
+ to be the default session.
+
+ - Function: destroy-tooltalk-pattern pattern
+ Apply `tt_pattern_destroy' to the pattern. This effectively
+ unregisters the pattern.
+
+ - Function: describe-tooltalk-message msg &optional stream
+ Print the message's attributes and arguments to STREAM. This is
+ often useful for debugging.
\1f
-File: lispref.info, Node: Evaluation, Next: Control Structures, Prev: Symbols, Up: Top
+File: lispref.info, Node: LDAP Support, Next: PostgreSQL Support, Prev: ToolTalk Support, Up: Top
-Evaluation
-**********
+LDAP Support
+************
- The "evaluation" of expressions in XEmacs Lisp is performed by the
-"Lisp interpreter"--a program that receives a Lisp object as input and
-computes its "value as an expression". How it does this depends on the
-data type of the object, according to rules described in this chapter.
-The interpreter runs automatically to evaluate portions of your
-program, but can also be called explicitly via the Lisp primitive
-function `eval'.
+XEmacs can be linked with a LDAP client library to provide Elisp
+primitives to access directory servers using the Lightweight Directory
+Access Protocol.
* Menu:
-* Intro Eval:: Evaluation in the scheme of things.
-* Eval:: How to invoke the Lisp interpreter explicitly.
-* Forms:: How various sorts of objects are evaluated.
-* Quoting:: Avoiding evaluation (to put constants in the program).
+* Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
+* XEmacs LDAP API:: Lisp access to LDAP functions
+* Syntax of Search Filters:: A brief summary of RFC 1558
\1f
-File: lispref.info, Node: Intro Eval, Next: Eval, Up: Evaluation
+File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
-Introduction to Evaluation
-==========================
+Building XEmacs with LDAP support
+=================================
- The Lisp interpreter, or evaluator, is the program that computes the
-value of an expression that is given to it. When a function written in
-Lisp is called, the evaluator computes the value of the function by
-evaluating the expressions in the function body. Thus, running any
-Lisp program really means running the Lisp interpreter.
-
- How the evaluator handles an object depends primarily on the data
-type of the object.
-
- A Lisp object that is intended for evaluation is called an
-"expression" or a "form". The fact that expressions are data objects
-and not merely text is one of the fundamental differences between
-Lisp-like languages and typical programming languages. Any object can
-be evaluated, but in practice only numbers, symbols, lists and strings
-are evaluated very often.
-
- It is very common to read a Lisp expression and then evaluate the
-expression, but reading and evaluation are separate activities, and
-either can be performed alone. Reading per se does not evaluate
-anything; it converts the printed representation of a Lisp object to the
-object itself. It is up to the caller of `read' whether this object is
-a form to be evaluated, or serves some entirely different purpose.
-*Note Input Functions::.
-
- Do not confuse evaluation with command key interpretation. The
-editor command loop translates keyboard input into a command (an
-interactively callable function) using the active keymaps, and then
-uses `call-interactively' to invoke the command. The execution of the
-command itself involves evaluation if the command is written in Lisp,
-but that is not a part of command key interpretation itself. *Note
-Command Loop::.
-
- Evaluation is a recursive process. That is, evaluation of a form may
-call `eval' to evaluate parts of the form. For example, evaluation of
-a function call first evaluates each argument of the function call, and
-then evaluates each form in the function body. Consider evaluation of
-the form `(car x)': the subform `x' must first be evaluated
-recursively, so that its value can be passed as an argument to the
-function `car'.
-
- Evaluation of a function call ultimately calls the function specified
-in it. *Note Functions::. The execution of the function may itself
-work by evaluating the function definition; or the function may be a
-Lisp primitive implemented in C, or it may be a byte-compiled function
-(*note Byte Compilation::).
-
- The evaluation of forms takes place in a context called the
-"environment", which consists of the current values and bindings of all
-Lisp variables.(1) Whenever the form refers to a variable without
-creating a new binding for it, the value of the binding in the current
-environment is used. *Note Variables::.
-
- Evaluation of a form may create new environments for recursive
-evaluation by binding variables (*note Local Variables::). These
-environments are temporary and vanish by the time evaluation of the form
-is complete. The form may also make changes that persist; these changes
-are called "side effects". An example of a form that produces side
-effects is `(setq foo 1)'.
-
- The details of what evaluation means for each kind of form are
-described below (*note Forms::).
-
- ---------- Footnotes ----------
-
- (1) This definition of "environment" is specifically not intended to
-include all the data that can affect the result of a program.
-
-\1f
-File: lispref.info, Node: Eval, Next: Forms, Prev: Intro Eval, Up: Evaluation
-
-Eval
-====
-
- Most often, forms are evaluated automatically, by virtue of their
-occurrence in a program being run. On rare occasions, you may need to
-write code that evaluates a form that is computed at run time, such as
-after reading a form from text being edited or getting one from a
-property list. On these occasions, use the `eval' function.
-
- *Please note:* it is generally cleaner and more flexible to call
-functions that are stored in data structures, rather than to evaluate
-expressions stored in data structures. Using functions provides the
-ability to pass information to them as arguments.
-
- The functions and variables described in this section evaluate forms,
-specify limits to the evaluation process, or record recently returned
-values. Loading a file also does evaluation (*note Loading::).
-
- - Function: eval form
- This is the basic function for performing evaluation. It evaluates
- FORM in the current environment and returns the result. How the
- evaluation proceeds depends on the type of the object (*note
- Forms::).
-
- Since `eval' is a function, the argument expression that appears
- in a call to `eval' is evaluated twice: once as preparation before
- `eval' is called, and again by the `eval' function itself. Here
- is an example:
-
- (setq foo 'bar)
- => bar
- (setq bar 'baz)
- => baz
- ;; `eval' receives argument `bar', which is the value of `foo'
- (eval foo)
- => baz
- (eval 'foo)
- => bar
-
- The number of currently active calls to `eval' is limited to
- `max-lisp-eval-depth' (see below).
-
- - Command: eval-region start end &optional stream
- This function evaluates the forms in the current buffer in the
- region defined by the positions START and END. It reads forms from
- the region and calls `eval' on them until the end of the region is
- reached, or until an error is signaled and not handled.
-
- If STREAM is supplied, `standard-output' is bound to it during the
- evaluation.
-
- You can use the variable `load-read-function' to specify a function
- for `eval-region' to use instead of `read' for reading
- expressions. *Note How Programs Do Loading::.
-
- `eval-region' always returns `nil'.
-
- - Command: eval-buffer buffer &optional stream
- This is like `eval-region' except that it operates on the whole
- contents of BUFFER.
-
- - Variable: max-lisp-eval-depth
- This variable defines the maximum depth allowed in calls to `eval',
- `apply', and `funcall' before an error is signaled (with error
- message `"Lisp nesting exceeds max-lisp-eval-depth"'). This counts
- internal uses of those functions, such as for calling the functions
- mentioned in Lisp expressions, and recursive evaluation of
- function call arguments and function body forms.
-
- This limit, with the associated error when it is exceeded, is one
- way that Lisp avoids infinite recursion on an ill-defined function.
-
- The default value of this variable is 1000. If you set it to a
- value less than 100, Lisp will reset it to 100 if the given value
- is reached.
-
- `max-specpdl-size' provides another limit on nesting. *Note Local
- Variables::.
-
- - Variable: values
- The value of this variable is a list of the values returned by all
- the expressions that were read from buffers (including the
- minibuffer), evaluated, and printed. The elements are ordered
- most recent first.
-
- (setq x 1)
- => 1
- (list 'A (1+ 2) auto-save-default)
- => (A 3 t)
- values
- => ((A 3 t) 1 ...)
-
- This variable is useful for referring back to values of forms
- recently evaluated. It is generally a bad idea to print the value
- of `values' itself, since this may be very long. Instead, examine
- particular elements, like this:
-
- ;; Refer to the most recent evaluation result.
- (nth 0 values)
- => (A 3 t)
- ;; That put a new element on,
- ;; so all elements move back one.
- (nth 1 values)
- => (A 3 t)
- ;; This gets the element that was next-to-most-recent
- ;; before this example.
- (nth 3 values)
- => 1
-
-\1f
-File: lispref.info, Node: Forms, Next: Quoting, Prev: Eval, Up: Evaluation
-
-Kinds of Forms
-==============
+LDAP support must be added to XEmacs at build time since it requires
+linking to an external LDAP client library. As of 21.2, XEmacs has been
+successfully built and tested with
+
+ * OpenLDAP 1.2 (<http://www.openldap.org/>)
+
+ * University of Michigan's LDAP 3.3
+ (<http://www.umich.edu/~dirsvcs/ldap/>)
+
+ * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
+
+ Other libraries conforming to RFC 1823 will probably work also but
+may require some minor tweaking at C level.
+
+ The standard XEmacs configure script auto-detects an installed LDAP
+library provided the library itself and the corresponding header files
+can be found in the library and include paths. A successful detection
+will be signalled in the final output of the configure script.
+
+\1f
+File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
+
+XEmacs LDAP API
+===============
+
+XEmacs LDAP API consists of two layers: a low-level layer which tries
+to stay as close as possible to the C API (where practical) and a
+higher-level layer which provides more convenient primitives to
+effectively use LDAP.
+
+ The low-level API should be used directly for very specific purposes
+(such as multiple operations on a connection) only. The higher-level
+functions provide a more convenient way to access LDAP directories
+hiding the subtleties of handling the connection, translating arguments
+and ensuring compliance with LDAP internationalization rules and formats
+(currently partly implemented only).
+
+* Menu:
+
+* LDAP Variables:: Lisp variables related to LDAP
+* The High-Level LDAP API:: High-level LDAP lisp functions
+* The Low-Level LDAP API:: Low-level LDAP lisp primitives
+* LDAP Internationalization:: I18n variables and functions
+
+\1f
+File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
+
+LDAP Variables
+--------------
+
+ - Variable: ldap-default-host
+ The default LDAP server hostname. A TCP port number can be
+ appended to that name using a colon as a separator.
+
+ - Variable: ldap-default-port
+ Default TCP port for LDAP connections. Initialized from the LDAP
+ library. Default value is 389.
+
+ - Variable: ldap-default-base
+ Default base for LDAP searches. This is a string using the syntax
+ of RFC 1779. For instance, "o=ACME, c=US" limits the search to the
+ Acme organization in the United States.
+
+ - Variable: ldap-host-parameters-alist
+ An alist of per host options for LDAP transactions. The list
+ elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
+ name of an LDAP server. A TCP port number can be appended to that
+ name using a colon as a separator. PROPN and VALN are
+ property/value pairs describing parameters for the server. Valid
+ properties:
+ `binddn'
+ The distinguished name of the user to bind as. This may look
+ like `cn=Babs Jensen,o=ACME,c=US', see RFC 1779 for details.
+
+ `passwd'
+ The password to use for authentication.
+
+ `auth'
+ The authentication method to use, possible values depend on
+ the LDAP library XEmacs was compiled with, they may include
+ `simple', `krbv41' and `krbv42'.
+
+ `base'
+ The base for the search. This may look like `cÿ, o¬me', see
+ RFC 1779 for syntax details.
+
+ `scope'
+ One of the symbols `base', `onelevel' or `subtree' indicating
+ the scope of the search limited to a base object, to a single
+ level or to the whole subtree.
+
+ `deref'
+ The dereference policy is one of the symbols `never',
+ `always', `search' or `find' and defines how aliases are
+ dereferenced.
+ `never'
+ Aliases are never dereferenced
+
+ `always'
+ Aliases are always dereferenced
+
+ `search'
+ Aliases are dereferenced when searching
+
+ `find'
+ Aliases are dereferenced when locating the base object
+ for the search
+
+ `timelimit'
+ The timeout limit for the connection in seconds.
+
+ `sizelimit'
+ The maximum number of matches to return for searches
+ performed on this connection.
+
+ - Variable: ldap-verbose
+ If non-`nil', LDAP operations will echo progress messages.
+ Defaults to `nil'.
+
+\1f
+File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
+
+The High-Level LDAP API
+-----------------------
+
+The following functions provide the most convenient interface to perform
+LDAP operations. All of them open a connection to a host, perform an
+operation (add/search/modify/delete) on one or several entries and
+cleanly close the connection thus insulating the user from all the
+details of the low-level interface such as LDAP Lisp objects *note The
+Low-Level LDAP API::.
+
+ Note that `ldap-search' which used to be the name of the high-level
+search function in XEmacs 21.1 is now obsolete. For consistency in the
+naming as well as backward compatibility, that function now acts as a
+wrapper that calls either `ldap-search-basic' (low-level search
+function) or `ldap-search-entries' (high-level search function)
+according to the actual parameters. A direct call to one of these two
+functions is preferred since it is faster and unambiguous.
+
+ - Command: ldap-search-entries filter &optional host attributes
+ attrsonly withdn
+ Perform an LDAP search. FILTER is the search filter *note Syntax
+ of Search Filters:: HOST is the LDAP host on which to perform the
+ search. ATTRIBUTES is the specific attributes to retrieve, `nil'
+ means retrieve all. ATTRSONLY if non-`nil' retrieves the
+ attributes only without their associated values. If WITHDN is
+ non-`nil' each entry in the result will be prepended with its
+ distinguished name DN. Additional search parameters can be
+ specified through `ldap-host-parameters-alist'. The function
+ returns a list of matching entries. Each entry is itself an alist
+ of attribute/value pairs optionally preceded by the DN of the
+ entry according to the value of WITHDN.
+
+ - Function: ldap-add-entries entries &optional host binddn passwd
+ Add entries to an LDAP directory. ENTRIES is a list of entry
+ specifications of the form `(DN (ATTR . VALUE) (ATTR . VALUE) ...)'
+ where DN the distinguished name of an entry to add, the following
+ are cons cells containing attribute/value string pairs. HOST is
+ the LDAP host, defaulting to `ldap-default-host'. BINDDN is the
+ DN to bind as to the server. PASSWD is the corresponding password.
+
+ - Function: ldap-modify-entries entry-mods &optional host binddn passwd
+ Modify entries of an LDAP directory. ENTRY_MODS is a list of
+ entry modifications of the form `(DN MOD-SPEC1 MOD-SPEC2 ...)'
+ where DN is the distinguished name of the entry to modify, the
+ following are modification specifications. A modification
+ specification is itself a list of the form `(MOD-OP ATTR VALUE1
+ VALUE2 ...)' MOD-OP and ATTR are mandatory, VALUES are optional
+ depending on MOD-OP. MOD-OP is the type of modification, one of
+ the symbols `add', `delete' or `replace'. ATTR is the LDAP
+ attribute type to modify. HOST is the LDAP host, defaulting to
+ `ldap-default-host'. BINDDN is the DN to bind as to the server.
+ PASSWD is the corresponding password.
+
+ - Function: ldap-delete-entries dn &optional host binddn passwd
+ Delete an entry from an LDAP directory. DN is the distinguished
+ name of an entry to delete or a list of those. HOST is the LDAP
+ host, defaulting to `ldap-default-host'. BINDDN is the DN to bind
+ as to the server. PASSWD is the corresponding password.
+
+\1f
+File: lispref.info, Node: The Low-Level LDAP API, Next: LDAP Internationalization, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
+
+The Low-Level LDAP API
+----------------------
+
+The low-level API should be used directly for very specific purposes
+(such as multiple operations on a connection) only. The higher-level
+functions provide a more convenient way to access LDAP directories
+hiding the subtleties of handling the connection, translating arguments
+and ensuring compliance with LDAP internationalization rules and formats
+(currently partly implemented only). See *note The High-Level LDAP API::
- A Lisp object that is intended to be evaluated is called a "form".
-How XEmacs evaluates a form depends on its data type. XEmacs has three
-different kinds of form that are evaluated differently: symbols, lists,
-and "all other types". This section describes all three kinds,
-starting with "all other types" which are self-evaluating forms.
+ Note that the former functions `ldap-*-internal' functions have been
+renamed in XEmacs 21.2
* Menu:
-* 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 Indirection:: When a symbol appears as the car of a list,
- we find the real function via the symbol.
-* 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.
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Low-level Operations on a LDAP Server::