X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=info%2Flispref.info-40;fp=info%2Flispref.info-40;h=0000000000000000000000000000000000000000;hb=a5812bf2ff9a9cf40f4ff78dcb83f5b4c295bd18;hp=b79fe212714572ce04277e7c1bda21af9149df17;hpb=ccce6217f84987dff10ed3d2b60b9f0f65d8f25a;p=chise%2Fxemacs-chise.git.1 diff --git a/info/lispref.info-40 b/info/lispref.info-40 deleted file mode 100644 index b79fe21..0000000 --- a/info/lispref.info-40 +++ /dev/null @@ -1,1263 +0,0 @@ -This is Info file ../../info/lispref.info, produced by Makeinfo version -1.68 from the input file lispref.texi. - -INFO-DIR-SECTION XEmacs Editor -START-INFO-DIR-ENTRY -* Lispref: (lispref). XEmacs Lisp Reference Manual. -END-INFO-DIR-ENTRY - - Edition History: - - GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU -Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid -Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994 -XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995 -GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp -Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp -Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp -Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May, -November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998 - - Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software -Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc. -Copyright (C) 1995, 1996 Ben Wing. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the section entitled "GNU General Public License" is included -exactly as in the original, and provided that the entire resulting -derived work is distributed under the terms of a permission notice -identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that the section entitled "GNU General Public License" -may be included in a translation approved by the Free Software -Foundation instead of in the original English. - - -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 &optional DEVICE - This function sets the output speed of DEVICE. See - `device-baud-rate'. DEVICE defaults to the selected device - (usually the only device) if omitted. - - - 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 - - - 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 - - -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'. - - - Function: enable-flow-control - 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::.). - - 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::. - - -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. - - -File: lispref.info, Node: X-Windows, Next: ToolTalk Support, Prev: System Interface, Up: Top - -Functions Specific to the X Window System -***************************************** - - 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. - -* Menu: - -* 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. - - -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 - This function stores STRING into the first cut buffer (cut buffer - 0), moving the other values down through the series of cut buffers, - kill-ring-style. (This function is called `x-set-cut-buffer' in FSF - Emacs.) - - -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. - - -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 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". - - -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.) - - -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. - - -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 - - -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:: - - -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. - - * There are fewer entry points; polymorphic functions with keyword - arguments are used instead. - - * 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. - - -File: lispref.info, Node: Sending Messages, Next: Receiving Messages, Prev: XEmacs ToolTalk API Summary, Up: ToolTalk Support - -Sending Messages -================ - -* Menu: - -* Example of Sending Messages:: -* Elisp Interface for Sending Messages:: - - -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)) - - -File: lispref.info, Node: Elisp Interface for Sending Messages, Prev: Example of Sending Messages, Up: Sending Messages - -Elisp Interface for Sending Messages ------------------------------------- - - - 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_' 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 - 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. - - - - 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. - - -File: lispref.info, Node: Receiving Messages, Prev: Sending Messages, Up: ToolTalk Support - -Receiving Messages -================== - -* Menu: - -* Example of Receiving Messages:: -* Elisp Interface for Receiving Messages:: - - -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)) - - -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 PAT - XEmacs will begin receiving messages that match this pattern. - - - Function: unregister-tooltalk-pattern PAT - XEmacs will stop receiving messages that match this pattern. - - - Function: add-tooltalk-pattern-attribute VALUE PAT 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 PAT MODE TYPE VALUE - Add one fully-specified argument to a ToolTalk pattern. MODE must - be one of `TT_IN', `TT_INOUT', or `TT_OUT'. TYPE 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 PAT - 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. - - -File: lispref.info, Node: LDAP Support, Next: Internationalization, Prev: ToolTalk Support, Up: Top - -LDAP Support -************ - - XEmacs can be linked with a LDAP client library to provide Elisp -primitives to access directory servers using the Lightweight Directory -Access Protocol. - -* Menu: - -* 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 - - -File: lispref.info, Node: Building XEmacs with LDAP support, Next: XEmacs LDAP API, Prev: LDAP Support, Up: LDAP Support - -Building XEmacs with LDAP support -================================= - - 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.0.3 (`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 autodetects 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. - - -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. - - As of XEmacs 21.0, only interfaces to basic LDAP search functions are -provided, broader support is planned in future versions. - -* 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 - - -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¬ME, cÿ" 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 `cÿ, o¬me, cnÿnny Bugs', 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. - - -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 ------------------------ - - As of this writing the high-level Lisp LDAP API only provides for -LDAP searches. Further support is planned in the future. - - The `ldap-search' function provides the most convenient interface to -perform LDAP searches. It opens a connection to a host, performs the -query and cleanly closes 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::. - - - Function: ldap-search FILTER &optional HOST ATTRIBUTES ATTRSONLY - 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. Additional - search parameters can be specified through - `ldap-host-parameters-alist'. - - -File: lispref.info, Node: The Low-Level LDAP API, Prev: The High-Level LDAP API, Up: XEmacs LDAP API - -The Low-Level LDAP API ----------------------- - -* Menu: - -* The LDAP Lisp Object:: -* Opening and Closing a LDAP Connection:: -* Searching on a LDAP Server (Low-level):: - - -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 - -The LDAP Lisp Object -.................... - - An internal built-in `ldap' lisp object represents a LDAP connection. - - - Function: ldapp OBJECT - This function returns non-`nil' if OBJECT is a `ldap' object. - - - Function: ldap-host LDAP - Return the server host of the connection represented by LDAP - - - Function: ldap-live-p LDAP - Return non-`nil' if LDAP is an active LDAP connection - - -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 - -Opening and Closing a LDAP Connection -..................................... - - - Function: ldap-open HOST &optional PLIST - Open a LDAP connection to HOST. PLIST is a property list - containing additional parameters for the connection. Valid keys - in that list are: - `port' - The TCP port to use for the connection if different from - `ldap-default-port' or the library builtin value - - `auth' - The authentication method to use, possible values depend on - the LDAP library XEmacs was compiled with, they may include - `simple', `krbv41' and `krbv42'. - - `binddn' - The distinguished name of the user to bind as. This may look - like `cÿ, o¬me, cnÿnny Bugs', see RFC 1779 for details. - - `passwd' - The password to use for authentication. - - `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 The default is `never'. - - `timelimit' - The timeout limit for the connection in seconds. - - `sizelimit' - The maximum number of matches to return for searches - performed on this connection. - - - Function: ldap-close LDAP - Close the connection represented by LDAP - - -File: lispref.info, Node: Searching on a LDAP Server (Low-level), Prev: Opening and Closing a LDAP Connection, Up: The Low-Level LDAP API - -Searching on a LDAP Server (Low-level) -...................................... - - `ldap-search-internal' is the low-level primitive to perform a -search on a LDAP server. It works directly on an open LDAP connection -thus requiring a preliminary call to `ldap-open'. Multiple searches -can be made on the same connection, then the session must be closed -with `ldap-close'. - - - Function: ldap-search-internal LDAP FILTER BASE SCOPE ATTRS ATTRSONLY - Perform a search on an open connection LDAP created with - `ldap-open'. FILTER is a filter string for the search *note - Syntax of Search Filters::. BASE is the distinguished name at - which to start the search. SCOPE is 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. The - default is `subtree'. `attrs' is a list of strings indicating - which attributes to retrieve for each matching entry. If `nil' all - available attributes are returned. If `attrsonly' is non-`nil' - then only the attributes are retrieved, not their associated values - The function returns a list of matching entries. Each entry being - itself an alist of attribute/values. - - -File: lispref.info, Node: Syntax of Search Filters, Prev: XEmacs LDAP API, Up: LDAP Support - -Syntax of Search Filters -======================== - - LDAP search functions use RFC1558 syntax to describe the search -filter. In that syntax simple filters have the form: - - ( ) - - `' is an attribute name such as `cn' for Common Name, `o' for -Organization, etc... - - `' is the corresponding value. This is generally an exact -string but may also contain `*' characters as wildcards - - `filtertype' is one `=' `~=', `<=', `>=' which respectively describe -equality, approximate equality, inferiority and superiority. - - Thus `(cn=John Smith)' matches all records having a canonical name -equal to John Smith. - - A special case is the presence filter `(=*' which matches -records containing a particular attribute. For instance `(mail=*)' -matches all records containing a `mail' attribute. - - Simple filters can be connected together with the logical operators -`&', `|' and `!' which stand for the usual and, or and not operators. - - `(&(objectClass=Person)(mail=*)(|(sn=Smith)(givenname=John)))' -matches records of class `Person' containing a `mail' attribute and -corresponding to people whose last name is `Smith' or whose first name -is `John'. - - -File: lispref.info, Node: Internationalization, Next: MULE, Prev: LDAP Support, Up: Top - -Internationalization -******************** - -* Menu: - -* I18N Levels 1 and 2:: Support for different time, date, and currency formats. -* I18N Level 3:: Support for localized messages. -* I18N Level 4:: Support for Asian languages. - - -File: lispref.info, Node: I18N Levels 1 and 2, Next: I18N Level 3, Up: Internationalization - -I18N Levels 1 and 2 -=================== - - XEmacs is now compliant with I18N levels 1 and 2. Specifically, -this means that it is 8-bit clean and correctly handles time and date -functions. XEmacs will correctly display the entire ISO-Latin 1 -character set. - - The compose key may now be used to create any character in the -ISO-Latin 1 character set not directly available via the keyboard.. In -order for the compose key to work it is necessary to load the file -`x-compose.el'. At any time while composing a character, `C-h' will -display all valid completions and the character which would be produced. - - -File: lispref.info, Node: I18N Level 3, Next: I18N Level 4, Prev: I18N Levels 1 and 2, Up: Internationalization - -I18N Level 3 -============ - -* Menu: - -* Level 3 Basics:: -* Level 3 Primitives:: -* Dynamic Messaging:: -* Domain Specification:: -* Documentation String Extraction:: - - -File: lispref.info, Node: Level 3 Basics, Next: Level 3 Primitives, Up: I18N Level 3 - -Level 3 Basics --------------- - - XEmacs now provides alpha-level functionality for I18N Level 3. -This means that everything necessary for full messaging is available, -but not every file has been converted. - - The two message files which have been created are `src/emacs.po' and -`lisp/packages/mh-e.po'. Both files need to be converted using -`msgfmt', and the resulting `.mo' files placed in some locale's -`LC_MESSAGES' directory. The test "translations" in these files are -the original messages prefixed by `TRNSLT_'. - - The domain for a variable is stored on the variable's property list -under the property name VARIABLE-DOMAIN. The function -`documentation-property' uses this information when translating a -variable's documentation. -