1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Terminal Output, Next: Flow Control, Prev: Terminal Input, Up: System Interface
58 The terminal output functions send output to the terminal or keep
59 track of output sent to the terminal. The function `device-baud-rate'
60 tells you what XEmacs thinks is the output speed of the terminal.
62 - Function: device-baud-rate &optional device
63 This function's value is the output speed of the terminal
64 associated with DEVICE, as far as XEmacs knows. DEVICE defaults
65 to the selected device (usually the only device) if omitted.
66 Changing this value does not change the speed of actual data
67 transmission, but the value is used for calculations such as
68 padding. This value has no effect for window-system devices.
69 (This is different in FSF Emacs, where the baud rate also affects
70 decisions about whether to scroll part of the screen or repaint,
71 even when using a window system.)
73 The value is measured in bits per second.
75 XEmacs attempts to automatically initialize the baud rate by querying
76 the terminal. If you are running across a network, however, and
77 different parts of the network work are at different baud rates, the
78 value returned by XEmacs may be different from the value used by your
79 local terminal. Some network protocols communicate the local terminal
80 speed to the remote machine, so that XEmacs and other programs can get
81 the proper value, but others do not. If XEmacs has the wrong value, it
82 makes decisions that are less than optimal. To fix the problem, use
83 `set-device-baud-rate'.
85 - Function: set-device-baud-rate &optional device
86 This function sets the output speed of DEVICE. See
87 `device-baud-rate'. DEVICE defaults to the selected device
88 (usually the only device) if omitted.
90 - Function: send-string-to-terminal char-or-string &optional stdout-p
92 This function sends CHAR-OR-STRING to the terminal without
93 alteration. Control characters in CHAR-OR-STRING have
94 terminal-dependent effects.
96 If DEVICE is `nil', this function writes to XEmacs's stderr, or to
97 stdout if STDOUT-P is non-`nil'. Otherwise, DEVICE should be a
98 tty or stream device, and the function writes to the device's
99 normal or error output, according to STDOUT-P.
101 One use of this function is to define function keys on terminals
102 that have downloadable function key definitions. For example,
103 this is how on certain terminals to define function key 4 to move
104 forward four characters (by transmitting the characters `C-u C-f'
107 (send-string-to-terminal "\eF4\^U\^F")
110 - Command: open-termscript filename
111 This function is used to open a "termscript file" that will record
112 all the characters sent by XEmacs to the terminal. (If there are
113 multiple tty or stream devices, all characters sent to all such
114 devices are recorded.) The function returns `nil'. Termscript
115 files are useful for investigating problems where XEmacs garbles
116 the screen, problems that are due to incorrect Termcap entries or
117 to undesirable settings of terminal options more often than to
118 actual XEmacs bugs. Once you are certain which characters were
119 actually output, you can determine reliably whether they
120 correspond to the Termcap specifications in use.
122 A `nil' value for FILENAME stops recording terminal output.
124 See also `open-dribble-file' in *Note Terminal Input::.
126 (open-termscript "../junk/termscript")
130 File: lispref.info, Node: Flow Control, Next: Batch Mode, Prev: Terminal Output, Up: System Interface
135 This section attempts to answer the question "Why does XEmacs choose
136 to use flow-control characters in its command character set?" For a
137 second view on this issue, read the comments on flow control in the
138 `emacs/INSTALL' file from the distribution; for help with Termcap
139 entries and DEC terminal concentrators, see `emacs/etc/TERMS'.
141 At one time, most terminals did not need flow control, and none used
142 `C-s' and `C-q' for flow control. Therefore, the choice of `C-s' and
143 `C-q' as command characters was uncontroversial. XEmacs, for economy
144 of keystrokes and portability, used nearly all the ASCII control
145 characters, with mnemonic meanings when possible; thus, `C-s' for
146 search and `C-q' for quote.
148 Later, some terminals were introduced which required these characters
149 for flow control. They were not very good terminals for full-screen
150 editing, so XEmacs maintainers did not pay attention. In later years,
151 flow control with `C-s' and `C-q' became widespread among terminals,
152 but by this time it was usually an option. And the majority of users,
153 who can turn flow control off, were unwilling to switch to less
154 mnemonic key bindings for the sake of flow control.
156 So which usage is "right", XEmacs's or that of some terminal and
157 concentrator manufacturers? This question has no simple answer.
159 One reason why we are reluctant to cater to the problems caused by
160 `C-s' and `C-q' is that they are gratuitous. There are other
161 techniques (albeit less common in practice) for flow control that
162 preserve transparency of the character stream. Note also that their use
163 for flow control is not an official standard. Interestingly, on the
164 model 33 teletype with a paper tape punch (which is very old), `C-s'
165 and `C-q' were sent by the computer to turn the punch on and off!
167 As X servers and other window systems replace character-only
168 terminals, this problem is gradually being cured. For the mean time,
169 XEmacs provides a convenient way of enabling flow control if you want
170 it: call the function `enable-flow-control'.
172 - Function: enable-flow-control
173 This function enables use of `C-s' and `C-q' for output flow
174 control, and provides the characters `C-\' and `C-^' as aliases
175 for them using `keyboard-translate-table' (*note Translating
178 You can use the function `enable-flow-control-on' in your `.emacs'
179 file to enable flow control automatically on certain terminal types.
181 - Function: enable-flow-control-on &rest termtypes
182 This function enables flow control, and the aliases `C-\' and
183 `C-^', if the terminal type is one of TERMTYPES. For example:
185 (enable-flow-control-on "vt200" "vt300" "vt101" "vt131")
187 Here is how `enable-flow-control' does its job:
189 1. It sets CBREAK mode for terminal input, and tells the operating
190 system to handle flow control, with `(set-input-mode nil t)'.
192 2. It sets up `keyboard-translate-table' to translate `C-\' and `C-^'
193 into `C-s' and `C-q'. Except at its very lowest level, XEmacs
194 never knows that the characters typed were anything but `C-s' and
195 `C-q', so you can in effect type them as `C-\' and `C-^' even when
196 they are input for other commands. *Note Translating Input::.
198 If the terminal is the source of the flow control characters, then
199 once you enable kernel flow control handling, you probably can make do
200 with less padding than normal for that terminal. You can reduce the
201 amount of padding by customizing the Termcap entry. You can also
202 reduce it by setting `baud-rate' to a smaller value so that XEmacs uses
203 a smaller speed when calculating the padding needed. *Note Terminal
207 File: lispref.info, Node: Batch Mode, Prev: Flow Control, Up: System Interface
212 The command line option `-batch' causes XEmacs to run
213 noninteractively. In this mode, XEmacs does not read commands from the
214 terminal, it does not alter the terminal modes, and it does not expect
215 to be outputting to an erasable screen. The idea is that you specify
216 Lisp programs to run; when they are finished, XEmacs should exit. The
217 way to specify the programs to run is with `-l FILE', which loads the
218 library named FILE, and `-f FUNCTION', which calls FUNCTION with no
221 Any Lisp program output that would normally go to the echo area,
222 either using `message' or using `prin1', etc., with `t' as the stream,
223 goes instead to XEmacs's standard error descriptor when in batch mode.
224 Thus, XEmacs behaves much like a noninteractive application program.
225 (The echo area output that XEmacs itself normally generates, such as
226 command echoing, is suppressed entirely.)
228 - Function: noninteractive
229 This function returns non-`nil' when XEmacs is running in batch
232 - Variable: noninteractive
233 This variable is non-`nil' when XEmacs is running in batch mode.
234 Setting this variable to `nil', however, will not change whether
235 XEmacs is running in batch mode, and will not change the return
236 value of the `noninteractive' function.
239 File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top
241 Functions Specific to the X Window System
242 *****************************************
244 XEmacs provides the concept of "devices", which generalizes
245 connections to an X server, a TTY device, etc. Most information about
246 an X server that XEmacs is connected to can be determined through
247 general console and device functions. *Note Consoles and Devices::.
248 However, there are some features of the X Window System that do not
249 generalize well, and they are covered specially here.
253 * X Selections:: Transferring text to and from other X clients.
254 * X Server:: Information about the X server connected to
256 * X Miscellaneous:: Other X-specific functions and variables.
259 File: lispref.info, Node: X Selections, Next: X Server, Up: X-Windows
264 The X server records a set of "selections" which permit transfer of
265 data between application programs. The various selections are
266 distinguished by "selection types", represented in XEmacs by symbols.
267 X clients including XEmacs can read or set the selection for any given
270 - Function: x-own-selection data &optional type
271 This function sets a "selection" in the X server. It takes two
272 arguments: a value, DATA, and the selection type TYPE to assign it
273 to. DATA may be a string, a cons of two markers, or an extent.
274 In the latter cases, the selection is considered to be the text
275 between the markers, or between the extent's endpoints.
277 Each possible TYPE has its own selection value, which changes
278 independently. The usual values of TYPE are `PRIMARY' and
279 `SECONDARY'; these are symbols with upper-case names, in accord
280 with X Windows conventions. The default is `PRIMARY'.
282 (In FSF Emacs, this function is called `x-set-selection' and takes
283 different arguments.)
285 - Function: x-get-selection
286 This function accesses selections set up by XEmacs or by other X
287 clients. It returns the value of the current primary selection.
289 - Function: x-disown-selection &optional secondary-p
290 Assuming we own the selection, this function disowns it. If
291 SECONDARY-P is non-`nil', the secondary selection instead of the
292 primary selection is discarded.
294 The X server also has a set of numbered "cut buffers" which can
295 store text or other data being moved between applications. Cut buffers
296 are considered obsolete, but XEmacs supports them for the sake of X
297 clients that still use them.
299 - Function: x-get-cutbuffer &optional n
300 This function returns the contents of cut buffer number N. (This
301 function is called `x-get-cut-buffer' in FSF Emacs.)
303 - Function: x-store-cutbuffer string
304 This function stores STRING into the first cut buffer (cut buffer
305 0), moving the other values down through the series of cut buffers,
306 kill-ring-style. (This function is called `x-set-cut-buffer' in FSF
310 File: lispref.info, Node: X Server, Next: X Miscellaneous, Prev: X Selections, Up: X-Windows
315 This section describes how to access and change the overall status of
316 the X server XEmacs is using.
320 * Resources:: Getting resource values from the server.
321 * Server Data:: Getting info about the X server.
322 * Grabs:: Restricting access to the server by other apps.
325 File: lispref.info, Node: Resources, Next: Server Data, Up: X Server
330 - Function: default-x-device
331 This function return the default X device for resourcing. This is
332 the first-created X device that still exists.
334 - Function: x-get-resource name class type &optional locale device
336 This function retrieves a resource value from the X resource
339 * The first arg is the name of the resource to retrieve, such as
342 * The second arg is the class of the resource to retrieve, like
345 * The third arg should be one of the symbols `string',
346 `integer', `natnum', or `boolean', specifying the type of
347 object that the database is searched for.
349 * The fourth arg is the locale to search for the resources on,
350 and can currently be a a buffer, a frame, a device, or the
351 symbol `global'. If omitted, it defaults to `global'.
353 * The fifth arg is the device to search for the resources on.
354 (The resource database for a particular device is constructed
355 by combining non-device- specific resources such any
356 command-line resources specified and any app-defaults files
357 found [or the fallback resources supplied by XEmacs, if no
358 app-defaults file is found] with device-specific resources
359 such as those supplied using `xrdb'.) If omitted, it defaults
360 to the device of LOCALE, if a device can be derived (i.e. if
361 LOCALE is a frame or device), and otherwise defaults to the
362 value of `default-x-device'.
364 * The sixth arg NOERROR, if non-`nil', means do not signal an
365 error if a bogus resource specification was retrieved (e.g.
366 if a non-integer was given when an integer was requested).
367 In this case, a warning is issued instead.
369 The resource names passed to this function are looked up relative
372 If you want to search for a subresource, you just need to specify
373 the resource levels in NAME and CLASS. For example, NAME could be
374 `"modeline.attributeFont"', and CLASS `"Face.AttributeFont"'.
378 1. If LOCALE is a buffer, a call
380 `(x-get-resource "foreground" "Foreground" 'string SOME-BUFFER)'
382 is an interface to a C call something like
384 `XrmGetResource (db, "xemacs.buffer.BUFFER-NAME.foreground",
385 "Emacs.EmacsLocaleType.EmacsBuffer.Foreground",
388 2. If LOCALE is a frame, a call
390 `(x-get-resource "foreground" "Foreground" 'string SOME-FRAME)'
392 is an interface to a C call something like
394 `XrmGetResource (db, "xemacs.frame.FRAME-NAME.foreground",
395 "Emacs.EmacsLocaleType.EmacsFrame.Foreground",
398 3. If LOCALE is a device, a call
400 `(x-get-resource "foreground" "Foreground" 'string SOME-DEVICE)'
402 is an interface to a C call something like
404 `XrmGetResource (db, "xemacs.device.DEVICE-NAME.foreground",
405 "Emacs.EmacsLocaleType.EmacsDevice.Foreground",
408 4. If LOCALE is the symbol `global', a call
410 `(x-get-resource "foreground" "Foreground" 'string 'global)'
412 is an interface to a C call something like
414 `XrmGetResource (db, "xemacs.foreground",
418 Note that for `global', no prefix is added other than that of the
419 application itself; thus, you can use this locale to retrieve
420 arbitrary application resources, if you really want to.
422 The returned value of this function is `nil' if the queried
423 resource is not found. If TYPE is `string', a string is returned,
424 and if it is `integer', an integer is returned. If TYPE is
425 `boolean', then the returned value is the list `(t)' for true,
426 `(nil)' for false, and is `nil' to mean "unspecified".
428 - Function: x-put-resource resource-line &optional device
429 This function adds a resource to the resource database for DEVICE.
430 RESOURCE-LINE specifies the resource to add and should be a
431 standard resource specification.
433 - Variable: x-emacs-application-class
434 This variable holds The X application class of the XEmacs process.
435 This controls, among other things, the name of the "app-defaults"
436 file that XEmacs will use. For changes to this variable to take
437 effect, they must be made before the connection to the X server is
438 initialized, that is, this variable may only be changed before
439 XEmacs is dumped, or by setting it in the file
440 `lisp/term/x-win.el'.
442 By default, this variable is nil at startup. When the connection
443 to the X server is first initialized, the X resource database will
444 be consulted and the value will be set according to whether any
445 resources are found for the application class "XEmacs".
448 File: lispref.info, Node: Server Data, Next: Grabs, Prev: Resources, Up: X Server
450 Data about the X Server
451 -----------------------
453 This section describes functions and a variable that you can use to
454 get information about the capabilities and origin of the X server
455 corresponding to a particular device. The device argument is generally
456 optional and defaults to the selected device.
458 - Function: x-server-version &optional device
459 This function returns the list of version numbers of the X server
460 DEVICE is on. The returned value is a list of three integers: the
461 major and minor version numbers of the X protocol in use, and the
462 vendor-specific release number.
464 - Function: x-server-vendor &optional device
465 This function returns the vendor supporting the X server DEVICE is
468 - Function: x-display-visual-class &optional device
469 This function returns the visual class of the display DEVICE is
470 on. The value is one of the symbols `static-gray', `gray-scale',
471 `static-color', `pseudo-color', `true-color', and `direct-color'.
472 (Note that this is different from previous versions of XEmacs,
473 which returned `StaticGray', `GrayScale', etc.)
476 File: lispref.info, Node: Grabs, Prev: Server Data, Up: X Server
478 Restricting Access to the Server by Other Apps
479 ----------------------------------------------
481 - Function: x-grab-keyboard &optional device
482 This function grabs the keyboard on the given device (defaulting
483 to the selected one). So long as the keyboard is grabbed, all
484 keyboard events will be delivered to XEmacs - it is not possible
485 for other X clients to eavesdrop on them. Ungrab the keyboard
486 with `x-ungrab-keyboard' (use an `unwind-protect'). Returns `t'
487 if the grab was successful; `nil' otherwise.
489 - Function: x-ungrab-keyboard &optional device
490 This function releases a keyboard grab made with `x-grab-keyboard'.
492 - Function: x-grab-pointer &optional device cursor ignore-keyboard
493 This function grabs the pointer and restricts it to its current
494 window. If optional DEVICE argument is `nil', the selected device
495 will be used. If optional CURSOR argument is non-`nil', change
496 the pointer shape to that until `x-ungrab-pointer' is called (it
497 should be an object returned by the `make-cursor' function). If
498 the second optional argument IGNORE-KEYBOARD is non-`nil', ignore
499 all keyboard events during the grab. Returns `t' if the grab is
500 successful, `nil' otherwise.
502 - Function: x-ungrab-pointer &optional device
503 This function releases a pointer grab made with `x-grab-pointer'.
504 If optional first arg DEVICE is `nil' the selected device is used.
505 If it is `t' the pointer will be released on all X devices.
508 File: lispref.info, Node: X Miscellaneous, Prev: X Server, Up: X-Windows
510 Miscellaneous X Functions and Variables
511 =======================================
513 - Variable: x-bitmap-file-path
514 This variable holds a list of the directories in which X bitmap
515 files may be found. If `nil', this is initialized from the
516 `"*bitmapFilePath"' resource. This is used by the
517 `make-image-instance' function (however, note that if the
518 environment variable `XBMLANGPATH' is set, it is consulted first).
520 - Variable: x-library-search-path
521 This variable holds the search path used by `read-color' to find
524 - Function: x-valid-keysym-name-p keysym
525 This function returns true if KEYSYM names a keysym that the X
526 library knows about. Valid keysyms are listed in the files
527 `/usr/include/X11/keysymdef.h' and in `/usr/lib/X11/XKeysymDB', or
528 whatever the equivalents are on your system.
530 - Function: x-window-id &optional frame
531 This function returns the ID of the X11 window. This gives us a
532 chance to manipulate the Emacs window from within a different
533 program. Since the ID is an unsigned long, we return it as a
536 - Variable: x-allow-sendevents
537 If non-`nil', synthetic events are allowed. `nil' means they are
538 ignored. Beware: allowing XEmacs to process SendEvents opens a
541 - Function: x-debug-mode arg &optional device
542 With a true arg, make the connection to the X server synchronous.
543 With false, make it asynchronous. Synchronous connections are
544 much slower, but are useful for debugging. (If you get X errors,
545 make the connection synchronous, and use a debugger to set a
546 breakpoint on `x_error_handler'. Your backtrace of the C stack
547 will now be useful. In asynchronous mode, the stack above
548 `x_error_handler' isn't helpful because of buffering.) If DEVICE
549 is not specified, the selected device is assumed.
551 Calling this function is the same as calling the C function
552 `XSynchronize', or starting the program with the `-sync' command
555 - Variable: x-debug-events
556 If non-zero, debug information about events that XEmacs sees is
557 displayed. Information is displayed on stderr. Currently defined
560 * 1 == non-verbose output
562 * 2 == verbose output
565 File: lispref.info, Node: ToolTalk Support, Next: LDAP Support, Prev: X-Windows, Up: Top
572 * XEmacs ToolTalk API Summary::
574 * Receiving Messages::
577 File: lispref.info, Node: XEmacs ToolTalk API Summary, Next: Sending Messages, Up: ToolTalk Support
579 XEmacs ToolTalk API Summary
580 ===========================
582 The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
583 to the standard C ToolTalk API. Only the message and pattern parts of
584 the API are supported at present; more of the API could be added if
585 needed. The Lisp interface departs from the C API in a few ways:
587 * ToolTalk is initialized automatically at XEmacs startup-time.
588 Messages can only be sent other ToolTalk applications connected to
589 the same X11 server that XEmacs is running on.
591 * There are fewer entry points; polymorphic functions with keyword
592 arguments are used instead.
594 * The callback interface is simpler and marginally less functional.
595 A single callback may be associated with a message or a pattern;
596 the callback is specified with a Lisp symbol (the symbol should
597 have a function binding).
599 * The session attribute for messages and patterns is always
600 initialized to the default session.
602 * Anywhere a ToolTalk enum constant, e.g. `TT_SESSION', is valid, one
603 can substitute the corresponding symbol, e.g. `'TT_SESSION'. This
604 simplifies building lists that represent messages and patterns.
607 File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support
614 * Example of Sending Messages::
615 * Elisp Interface for Sending Messages::
618 File: lispref.info, Node: Example of Sending Messages, Next: Elisp Interface for Sending Messages, Up: Sending Messages
620 Example of Sending Messages
621 ---------------------------
623 Here's a simple example that sends a query to another application
624 and then displays its reply. Both the query and the reply are stored
625 in the first argument of the message.
627 (defun tooltalk-random-query-handler (msg)
628 (let ((state (get-tooltalk-message-attribute msg 'state)))
630 ((eq state 'TT_HANDLED)
631 (message (get-tooltalk-message-attribute msg arg_val 0)))
632 ((memq state '(TT_FAILED TT_REJECTED))
633 (message "Random query turns up nothing")))))
635 (defvar random-query-message
640 args '((TT_INOUT "?" "string"))
641 callback tooltalk-random-query-handler))
643 (let ((m (make-tooltalk-message random-query-message)))
644 (send-tooltalk-message m))
647 File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages
649 Elisp Interface for Sending Messages
650 ------------------------------------
652 - Function: make-tooltalk-message attributes
653 Create a ToolTalk message and initialize its attributes. The
654 value of ATTRIBUTES must be a list of alternating keyword/values,
655 where keywords are symbols that name valid message attributes.
658 (make-tooltalk-message
663 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
665 Values must always be strings, integers, or symbols that represent
666 ToolTalk constants. Attribute names are the same as those
667 supported by `set-tooltalk-message-attribute', plus `args'.
669 The value of `args' should be a list of message arguments where
670 each message argument has the following form:
672 `(mode [value [type]])' or just `value'
674 Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
675 a string. If TYPE isn't specified then `int' is used if VALUE is
676 a number; otherwise `string' is used. If TYPE is `string' then
677 VALUE is converted to a string (if it isn't a string already) with
678 `prin1-to-string'. If only a value is specified then MODE
679 defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
680 don't need to be specified. You can find out more about the
681 semantics and uses of ToolTalk message arguments in chapter 4 of
682 the `ToolTalk Programmer's Guide'.
685 - Function: send-tooltalk-message msg
686 Send the message on its way. Once the message has been sent it's
687 almost always a good idea to get rid of it with
688 `destroy-tooltalk-message'.
691 - Function: return-tooltalk-message msg &optional mode
692 Send a reply to this message. The second argument can be `reply',
693 `reject' or `fail'; the default is `reply'. Before sending a
694 reply, all message arguments whose mode is `TT_INOUT' or `TT_OUT'
695 should have been filled in - see `set-tooltalk-message-attribute'.
698 - Function: get-tooltalk-message-attribute msg attribute &optional argn
699 Returns the indicated ToolTalk message attribute. Attributes are
700 identified by symbols with the same name (underscores and all) as
701 the suffix of the ToolTalk `tt_message_<attribute>' function that
702 extracts the value. String attribute values are copied and
703 enumerated type values (except disposition) are converted to
704 symbols; e.g. `TT_HANDLER' is `'TT_HANDLER', `uid' and `gid' are
705 represented by fixnums (small integers), `opnum' is converted to a
706 string, and `disposition' is converted to a fixnum. We convert
707 `opnum' (a C int) to a string (e.g. `123' => `"123"') because
708 there's no guarantee that opnums will fit within the range of
709 XEmacs Lisp integers.
711 [TBD] Use the `plist' attribute instead of C API `user' attribute
712 for user-defined message data. To retrieve the value of a message
713 property, specify the indicator for ARGN. For example, to get the
714 value of a property called `rflag', use
716 (get-tooltalk-message-attribute msg 'plist 'rflag)
718 To get the value of a message argument use one of the `arg_val'
719 (strings), `arg_ival' (integers), or `arg_bval' (strings with
720 embedded nulls), attributes. For example, to get the integer
721 value of the third argument:
723 (get-tooltalk-message-attribute msg 'arg_ival 2)
725 As you can see, argument numbers are zero-based. The type of each
726 arguments can be retrieved with the `arg_type' attribute; however
727 ToolTalk doesn't define any semantics for the string value of
728 `arg_type'. Conventionally `string' is used for strings and `int'
729 for 32 bit integers. Note that XEmacs Lisp stores the lengths of
730 strings explicitly (unlike C) so treating the value returned by
731 `arg_bval' like a string is fine.
734 - Function: set-tooltalk-message-attribute value msg attribute
736 Initialize one ToolTalk message attribute.
738 Attribute names and values are the same as for
739 `get-tooltalk-message-attribute'. A property list is provided for
740 user data (instead of the `user' message attribute); see
741 `get-tooltalk-message-attribute'.
743 Callbacks are handled slightly differently than in the C ToolTalk
744 API. The value of CALLBACK should be the name of a function of one
745 argument. It will be called each time the state of the message
746 changes. This is usually used to notice when the message's state
747 has changed to `TT_HANDLED' (or `TT_FAILED'), so that reply
748 argument values can be used.
750 If one of the argument attributes is specified as `arg_val',
751 `arg_ival', or `arg_bval', then ARGN must be the number of an
752 already created argument. Arguments can be added to a message
753 with `add-tooltalk-message-arg'.
756 - Function: add-tooltalk-message-arg msg mode type &optional value
757 Append one new argument to the message. MODE must be one of
758 `TT_IN', `TT_INOUT', or `TT_OUT', TYPE must be a string, and VALUE
759 can be a string or an integer. ToolTalk doesn't define any
760 semantics for TYPE, so only the participants in the protocol
761 you're using need to agree what types mean (if anything).
762 Conventionally `string' is used for strings and `int' for 32 bit
763 integers. Arguments can initialized by providing a value or with
764 `set-tooltalk-message-attribute'; the latter is necessary if you
765 want to initialize the argument with a string that can contain
766 embedded nulls (use `arg_bval').
769 - Function: create-tooltalk-message
770 Create a new ToolTalk message. The message's session attribute is
771 initialized to the default session. Other attributes can be
772 initialized with `set-tooltalk-message-attribute'.
773 `make-tooltalk-message' is the preferred way to create and
774 initialize a message.
777 - Function: destroy-tooltalk-message msg
778 Apply `tt_message_destroy' to the message. It's not necessary to
779 destroy messages after they've been processed by a message or
780 pattern callback, the Lisp/ToolTalk callback machinery does this
784 File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support
791 * Example of Receiving Messages::
792 * Elisp Interface for Receiving Messages::
795 File: lispref.info, Node: Example of Receiving Messages, Next: Elisp Interface for Receiving Messages, Up: Receiving Messages
797 Example of Receiving Messages
798 -----------------------------
800 Here's a simple example of a handler for a message that tells XEmacs
801 to display a string in the mini-buffer area. The message operation is
802 called `emacs-display-string'. Its first (0th) argument is the string
805 (defun tooltalk-display-string-handler (msg)
806 (message (get-tooltalk-message-attribute msg 'arg_val 0)))
808 (defvar display-string-pattern
811 op "emacs-display-string"
812 callback tooltalk-display-string-handler))
814 (let ((p (make-tooltalk-pattern display-string-pattern)))
815 (register-tooltalk-pattern p))
818 File: lispref.info, Node: Elisp Interface for Receiving Messages, Prev: Example of Receiving Messages, Up: Receiving Messages
820 Elisp Interface for Receiving Messages
821 --------------------------------------
823 - Function: make-tooltalk-pattern attributes
824 Create a ToolTalk pattern and initialize its attributes. The
825 value of attributes must be a list of alternating keyword/values,
826 where keywords are symbols that name valid pattern attributes or
827 lists of valid attributes. For example:
829 (make-tooltalk-pattern
830 '(category TT_OBSERVE
832 op ("operation1" "operation2")
833 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
835 Attribute names are the same as those supported by
836 `add-tooltalk-pattern-attribute', plus `'args'.
838 Values must always be strings, integers, or symbols that represent
839 ToolTalk constants or lists of same. When a list of values is
840 provided all of the list elements are added to the attribute. In
841 the example above, messages whose `op' attribute is `"operation1"'
842 or `"operation2"' would match the pattern.
844 The value of ARGS should be a list of pattern arguments where each
845 pattern argument has the following form:
847 `(mode [value [type]])' or just `value'
849 Where MODE is one of `TT_IN', `TT_OUT', or `TT_INOUT' and TYPE is
850 a string. If TYPE isn't specified then `int' is used if VALUE is
851 a number; otherwise `string' is used. If TYPE is `string' then
852 VALUE is converted to a string (if it isn't a string already) with
853 `prin1-to-string'. If only a value is specified then MODE
854 defaults to `TT_IN'. If MODE is `TT_OUT' then VALUE and TYPE
855 don't need to be specified. You can find out more about the
856 semantics and uses of ToolTalk pattern arguments in chapter 3 of
857 the `ToolTalk Programmer's Guide'.
860 - Function: register-tooltalk-pattern pat
861 XEmacs will begin receiving messages that match this pattern.
863 - Function: unregister-tooltalk-pattern pat
864 XEmacs will stop receiving messages that match this pattern.
866 - Function: add-tooltalk-pattern-attribute value pat indicator
867 Add one value to the indicated pattern attribute. The names of
868 attributes are the same as the ToolTalk accessors used to set them
869 less the `tooltalk_pattern_' prefix and the `_add' suffix. For
870 example, the name of the attribute for the
871 `tt_pattern_disposition_add' attribute is `disposition'. The
872 `category' attribute is handled specially, since a pattern can only
873 be a member of one category (`TT_OBSERVE' or `TT_HANDLE').
875 Callbacks are handled slightly differently than in the C ToolTalk
876 API. The value of CALLBACK should be the name of a function of one
877 argument. It will be called each time the pattern matches an
880 - Function: add-tooltalk-pattern-arg pat mode type value
881 Add one fully-specified argument to a ToolTalk pattern. MODE must
882 be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE must be a
883 string. VALUE can be an integer, string or `nil'. If VALUE is an
884 integer then an integer argument (`tt_pattern_iarg_add') is added;
885 otherwise a string argument is added. At present there's no way
886 to add a binary data argument.
889 - Function: create-tooltalk-pattern
890 Create a new ToolTalk pattern and initialize its session attribute
891 to be the default session.
893 - Function: destroy-tooltalk-pattern pat
894 Apply `tt_pattern_destroy' to the pattern. This effectively
895 unregisters the pattern.
897 - Function: describe-tooltalk-message msg &optional stream
898 Print the message's attributes and arguments to STREAM. This is
899 often useful for debugging.
902 File: lispref.info, Node: LDAP Support, Next: Internationalization, Prev: ToolTalk Support, Up: Top
907 XEmacs can be linked with a LDAP client library to provide Elisp
908 primitives to access directory servers using the Lightweight Directory
913 * Building XEmacs with LDAP support:: How to add LDAP support to XEmacs
914 * XEmacs LDAP API:: Lisp access to LDAP functions
915 * Syntax of Search Filters:: A brief summary of RFC 1558
918 File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support
920 Building XEmacs with LDAP support
921 =================================
923 LDAP support must be added to XEmacs at build time since it requires
924 linking to an external LDAP client library. As of 21.2, XEmacs has been
925 successfully built and tested with
927 * OpenLDAP 1.0.3 (<http://www.openldap.org/>)
929 * University of Michigan's LDAP 3.3
930 (<http://www.umich.edu/~dirsvcs/ldap/>)
932 * LDAP SDK 1.0 from Netscape Corp. (<http://developer.netscape.com/>)
934 Other libraries conforming to RFC 1823 will probably work also but
935 may require some minor tweaking at C level.
937 The standard XEmacs configure script autodetects an installed LDAP
938 library provided the library itself and the corresponding header files
939 can be found in the library and include paths. A successful detection
940 will be signalled in the final output of the configure script.
943 File: lispref.info, Node: XEmacs LDAP API, Next: Syntax of Search Filters, Prev: Building XEmacs with LDAP support, Up: LDAP Support
948 XEmacs LDAP API consists of two layers: a low-level layer which
949 tries to stay as close as possible to the C API (where practical) and a
950 higher-level layer which provides more convenient primitives to
951 effectively use LDAP.
953 As of XEmacs 21.0, only interfaces to basic LDAP search functions are
954 provided, broader support is planned in future versions.
958 * LDAP Variables:: Lisp variables related to LDAP
959 * The High-Level LDAP API:: High-level LDAP lisp functions
960 * The Low-Level LDAP API:: Low-level LDAP lisp primitives
963 File: lispref.info, Node: LDAP Variables, Next: The High-Level LDAP API, Prev: XEmacs LDAP API, Up: XEmacs LDAP API
968 - Variable: ldap-default-host
969 The default LDAP server hostname. A TCP port number can be
970 appended to that name using a colon as a separator.
972 - Variable: ldap-default-port
973 Default TCP port for LDAP connections. Initialized from the LDAP
974 library. Default value is 389.
976 - Variable: ldap-default-base
977 Default base for LDAP searches. This is a string using the syntax
978 of RFC 1779. For instance, "o¬ME, cÿ" limits the search to the
979 Acme organization in the United States.
981 - Variable: ldap-host-parameters-alist
982 An alist of per host options for LDAP transactions. The list
983 elements look like `(HOST PROP1 VAL1 PROP2 VAL2 ...)' HOST is the
984 name of an LDAP server. A TCP port number can be appended to that
985 name using a colon as a separator. PROPN and VALN are
986 property/value pairs describing parameters for the server. Valid
989 The distinguished name of the user to bind as. This may look
990 like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
993 The password to use for authentication.
996 The authentication method to use, possible values depend on
997 the LDAP library XEmacs was compiled with, they may include
998 `simple', `krbv41' and `krbv42'.
1001 The base for the search. This may look like `cÿ, o¬me', see
1002 RFC 1779 for syntax details.
1005 One of the symbols `base', `onelevel' or `subtree' indicating
1006 the scope of the search limited to a base object, to a single
1007 level or to the whole subtree.
1010 The dereference policy is one of the symbols `never',
1011 `always', `search' or `find' and defines how aliases are
1014 Aliases are never dereferenced
1017 Aliases are always dereferenced
1020 Aliases are dereferenced when searching
1023 Aliases are dereferenced when locating the base object
1027 The timeout limit for the connection in seconds.
1030 The maximum number of matches to return for searches
1031 performed on this connection.
1034 File: lispref.info, Node: The High-Level LDAP API, Next: The Low-Level LDAP API, Prev: LDAP Variables, Up: XEmacs LDAP API
1036 The High-Level LDAP API
1037 -----------------------
1039 As of this writing the high-level Lisp LDAP API only provides for
1040 LDAP searches. Further support is planned in the future.
1042 The `ldap-search' function provides the most convenient interface to
1043 perform LDAP searches. It opens a connection to a host, performs the
1044 query and cleanly closes the connection thus insulating the user from
1045 all the details of the low-level interface such as LDAP Lisp objects
1046 *note The Low-Level LDAP API::
1048 - Function: ldap-search filter &optional host attributes attrsonly
1049 Perform an LDAP search. FILTER is the search filter *note Syntax
1050 of Search Filters:: HOST is the LDAP host on which to perform the
1051 search ATTRIBUTES is the specific attributes to retrieve, `nil'
1052 means retrieve all ATTRSONLY if non-`nil' retrieves the attributes
1053 only without their associated values. Additional search
1054 parameters can be specified through `ldap-host-parameters-alist'.
1057 File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API
1059 The Low-Level LDAP API
1060 ----------------------
1064 * The LDAP Lisp Object::
1065 * Opening and Closing a LDAP Connection::
1066 * Searching on a LDAP Server (Low-level)::
1069 File: lispref.info, Node: The LDAP Lisp Object, Next: Opening and Closing a LDAP Connection, Prev: The Low-Level LDAP API, Up: The Low-Level LDAP API
1071 The LDAP Lisp Object
1072 ....................
1074 An internal built-in `ldap' lisp object represents a LDAP connection.
1076 - Function: ldapp object
1077 This function returns non-`nil' if OBJECT is a `ldap' object.
1079 - Function: ldap-host ldap
1080 Return the server host of the connection represented by LDAP
1082 - Function: ldap-live-p ldap
1083 Return non-`nil' if LDAP is an active LDAP connection
1086 File: lispref.info, Node: Opening and Closing a LDAP Connection, Next: Searching on a LDAP Server (Low-level), Prev: The LDAP Lisp Object, Up: The Low-Level LDAP API
1088 Opening and Closing a LDAP Connection
1089 .....................................
1091 - Function: ldap-open host &optional plist
1092 Open a LDAP connection to HOST. PLIST is a property list
1093 containing additional parameters for the connection. Valid keys
1096 The TCP port to use for the connection if different from
1097 `ldap-default-port' or the library builtin value
1100 The authentication method to use, possible values depend on
1101 the LDAP library XEmacs was compiled with, they may include
1102 `simple', `krbv41' and `krbv42'.
1105 The distinguished name of the user to bind as. This may look
1106 like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details.
1109 The password to use for authentication.
1112 The dereference policy is one of the symbols `never',
1113 `always', `search' or `find' and defines how aliases are
1116 Aliases are never dereferenced
1119 Aliases are always dereferenced
1122 Aliases are dereferenced when searching
1125 Aliases are dereferenced when locating the base object
1126 for the search The default is `never'.
1129 The timeout limit for the connection in seconds.
1132 The maximum number of matches to return for searches
1133 performed on this connection.
1135 - Function: ldap-close ldap
1136 Close the connection represented by LDAP
1139 File: lispref.info, Node: Searching on a LDAP Server (Low-level), Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API
1141 Searching on a LDAP Server (Low-level)
1142 ......................................
1144 `ldap-search-internal' is the low-level primitive to perform a
1145 search on a LDAP server. It works directly on an open LDAP connection
1146 thus requiring a preliminary call to `ldap-open'. Multiple searches
1147 can be made on the same connection, then the session must be closed
1150 - Function: ldap-search-internal ldap filter base scope attrs attrsonly
1151 Perform a search on an open connection LDAP created with
1152 `ldap-open'. FILTER is a filter string for the search *note
1153 Syntax of Search Filters:: BASE is the distinguished name at which
1154 to start the search. SCOPE is one of the symbols `base',
1155 `onelevel' or `subtree' indicating the scope of the search limited
1156 to a base object, to a single level or to the whole subtree. The
1157 default is `subtree'. `attrs' is a list of strings indicating
1158 which attributes to retrieve for each matching entry. If `nil' all
1159 available attributes are returned. If `attrsonly' is non-`nil'
1160 then only the attributes are retrieved, not their associated values
1161 The function returns a list of matching entries. Each entry being
1162 itself an alist of attribute/values.
1165 File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support
1167 Syntax of Search Filters
1168 ========================
1170 LDAP search functions use RFC1558 syntax to describe the search
1171 filter. In that syntax simple filters have the form:
1173 (<attr> <filtertype> <value>)
1175 `<attr>' is an attribute name such as `cn' for Common Name, `o' for
1176 Organization, etc...
1178 `<value>' is the corresponding value. This is generally an exact
1179 string but may also contain `*' characters as wildcards
1181 `filtertype' is one `=' `~=', `<=', `>=' which respectively describe
1182 equality, approximate equality, inferiority and superiority.
1184 Thus `(cn=John Smith)' matches all records having a canonical name
1185 equal to John Smith.
1187 A special case is the presence filter `(<attr>=*' which matches
1188 records containing a particular attribute. For instance `(mail=*)'
1189 matches all records containing a `mail' attribute.
1191 Simple filters can be connected together with the logical operators
1192 `&', `|' and `!' which stand for the usual and, or and not operators.
1194 `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))'
1195 matches records of class `Person' containing a `mail' attribute and
1196 corresponding to people whose last name is `Smith' or whose first name
1200 File: lispref.info, Node: Internationalization, Next: MULE, Prev: LDAP Support, Up: Top
1202 Internationalization
1203 ********************
1207 * I18N Levels 1 and 2:: Support for different time, date, and currency formats.
1208 * I18N Level 3:: Support for localized messages.
1209 * I18N Level 4:: Support for Asian languages.
1212 File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization
1217 XEmacs is now compliant with I18N levels 1 and 2. Specifically,
1218 this means that it is 8-bit clean and correctly handles time and date
1219 functions. XEmacs will correctly display the entire ISO-Latin 1
1222 The compose key may now be used to create any character in the
1223 ISO-Latin 1 character set not directly available via the keyboard.. In
1224 order for the compose key to work it is necessary to load the file
1225 `x-compose.el'. At any time while composing a character, `C-h' will
1226 display all valid completions and the character which would be produced.
1229 File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization
1237 * Level 3 Primitives::
1238 * Dynamic Messaging::
1239 * Domain Specification::
1240 * Documentation String Extraction::
1243 File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3
1248 XEmacs now provides alpha-level functionality for I18N Level 3.
1249 This means that everything necessary for full messaging is available,
1250 but not every file has been converted.
1252 The two message files which have been created are `src/emacs.po' and
1253 `lisp/packages/mh-e.po'. Both files need to be converted using
1254 `msgfmt', and the resulting `.mo' files placed in some locale's
1255 `LC_MESSAGES' directory. The test "translations" in these files are
1256 the original messages prefixed by `TRNSLT_'.
1258 The domain for a variable is stored on the variable's property list
1259 under the property name VARIABLE-DOMAIN. The function
1260 `documentation-property' uses this information when translating a
1261 variable's documentation.