Foundation instead of in the original English.
\1f
-File: lispref.info, Node: Working With a Database, Next: Other Database Functions, Prev: Connecting to a Database, Up: Databases
+File: lispref.info, Node: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
+
+Truncation
+==========
+
+ When a line of text extends beyond the right edge of a window, the
+line can either be truncated or continued on the next line. When a line
+is truncated, this is normally shown with a `\' in the rightmost column
+of the window on X displays, and with a `$' on TTY devices. When a
+line is continued or "wrapped" onto the next line, this is shown with a
+curved arrow in the rightmost column of the window (or with a `\' on
+TTY devices). The additional screen lines used to display a long text
+line are called "continuation" lines.
+
+ Normally, whenever line truncation is in effect for a particular
+window, a horizontal scrollbar is displayed in that window if the
+device supports scrollbars. *Note Scrollbars::.
+
+ Note that continuation is different from filling; continuation
+happens on the screen only, not in the buffer contents, and it breaks a
+line precisely at the right margin, not at a word boundary. *Note
+Filling::.
+
+ - User Option: truncate-lines
+ This buffer-local variable controls how XEmacs displays lines that
+ extend beyond the right edge of the window. If it is non-`nil',
+ then XEmacs does not display continuation lines; rather each line
+ of text occupies exactly one screen line, and a backslash appears
+ at the edge of any line that extends to or beyond the edge of the
+ window. The default is `nil'.
+
+ If the variable `truncate-partial-width-windows' is non-`nil',
+ then truncation is always used for side-by-side windows (within one
+ frame) regardless of the value of `truncate-lines'.
+
+ - User Option: default-truncate-lines
+ This variable is the default value for `truncate-lines', for
+ buffers that do not have local values for it.
+
+ - User Option: truncate-partial-width-windows
+ This variable controls display of lines that extend beyond the
+ right edge of the window, in side-by-side windows (*note Splitting
+ Windows::). If it is non-`nil', these lines are truncated;
+ otherwise, `truncate-lines' says what to do with them.
+
+ The backslash and curved arrow used to indicate truncated or
+continued lines are only defaults, and can be changed. These images
+are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
+flexibility in how glyphs can be controlled. (This differs from FSF
+Emacs, which uses display tables to control these images.)
+
+ For details, *Note Redisplay Glyphs::.
-Working With a Database
-=======================
+\1f
+File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
+
+The Echo Area
+=============
+
+ The "echo area" is used for displaying messages made with the
+`message' primitive, and for echoing keystrokes. It is not the same as
+the minibuffer, despite the fact that the minibuffer appears (when
+active) in the same place on the screen as the echo area. The `XEmacs
+Reference Manual' specifies the rules for resolving conflicts between
+the echo area and the minibuffer for use of that screen space (*note
+The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
+area; see *Note Errors::.
+
+ You can write output in the echo area by using the Lisp printing
+functions with `t' as the stream (*note Output Functions::), or as
+follows:
+
+ - Function: message string &rest arguments
+ This function displays a one-line message in the echo area. The
+ argument STRING is similar to a C language `printf' control
+ string. See `format' in *Note String Conversion::, for the details
+ on the conversion specifications. `message' returns the
+ constructed string.
+
+ In batch mode, `message' prints the message text on the standard
+ error stream, followed by a newline.
+
+ If STRING is `nil', `message' clears the echo area. If the
+ minibuffer is active, this brings the minibuffer contents back onto
+ the screen immediately.
+
+ (message "Minibuffer depth is %d."
+ (minibuffer-depth))
+ -| Minibuffer depth is 0.
+ => "Minibuffer depth is 0."
+
+ ---------- Echo Area ----------
+ Minibuffer depth is 0.
+ ---------- Echo Area ----------
- - Function: get-database key dbase &optional default
- This function finds the value for KEY in DATABASE. If there is no
- corresponding value, DEFAULT is returned (`nil' if DEFAULT is
- omitted).
+ In addition to only displaying a message, XEmacs allows you to
+"label" your messages, giving you fine-grained control of their
+display. Message label is a symbol denoting the message type. Some
+standard labels are:
- - Function: map-database function dbase
- This function maps FUNCTION over entries in DATABASE, calling it
- with two args, each key and value in the database.
+ * `message'--default label used by the `message' function;
- - Function: put-database key val dbase &optional replace
- This function stores KEY and VAL in DATABASE. If optional fourth
- arg REPLACE is non-`nil', replace any existing entry in the
- database.
+ * `error'--default label used for reporting errors;
- - Function: remove-database key dbase
- This function removes KEY from DATABASE.
+ * `progress'--progress indicators like `Converting... 45%' (not
+ logged by default);
-\1f
-File: lispref.info, Node: Other Database Functions, Prev: Working With a Database, Up: Databases
+ * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
+ default);
-Other Database Functions
-========================
+ * `command'--helper command messages like `Mark set' (not logged by
+ default);
- - Function: database-file-name obj
- This function returns the filename associated with the database
- OBJ.
+ * `no-log'--messages that should never be logged
- - Function: database-last-error &optional obj
- This function returns the last error associated with database OBJ.
+ Several messages may be stacked in the echo area at once. Lisp
+programs may access these messages, or remove them as appropriate, via
+the message stack.
- - Function: database-subtype obj
- This function returns the subtype of database OBJ, if any.
+ - Function: display-message label message &optional frame stdout-p
+ This function displays MESSAGE (a string) labeled as LABEL, as
+ described above.
- - Function: database-type obj
- This function returns the type of database OBJ.
+ The FRAME argument specifies the frame to whose minibuffer the
+ message should be printed. This is currently unimplemented. The
+ STDOUT-P argument is used internally.
-\1f
-File: lispref.info, Node: Processes, Next: System Interface, Prev: Databases, Up: Top
-
-Processes
-*********
-
- In the terminology of operating systems, a "process" is a space in
-which a program can execute. XEmacs runs in a process. XEmacs Lisp
-programs can invoke other programs in processes of their own. These are
-called "subprocesses" or "child processes" of the XEmacs process, which
-is their "parent process".
-
- A subprocess of XEmacs may be "synchronous" or "asynchronous",
-depending on how it is created. When you create a synchronous
-subprocess, the Lisp program waits for the subprocess to terminate
-before continuing execution. When you create an asynchronous
-subprocess, it can run in parallel with the Lisp program. This kind of
-subprocess is represented within XEmacs by a Lisp object which is also
-called a "process". Lisp programs can use this object to communicate
-with the subprocess or to control it. For example, you can send
-signals, obtain status information, receive output from the process, or
-send input to it.
-
- - Function: processp object
- This function returns `t' if OBJECT is a process, `nil' otherwise.
+ (display-message 'command "Mark set")
-* Menu:
+ - Function: lmessage label string &rest arguments
+ This function displays a message STRING with label LABEL. It is
+ similar to `message' in that it accepts a `printf'-like strings
+ and any number of arguments.
-* Subprocess Creation:: Functions that start subprocesses.
-* Synchronous Processes:: Details of using synchronous subprocesses.
-* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
- for data sent to and from a subprocess.
-* Asynchronous Processes:: Starting up an asynchronous subprocess.
-* Deleting Processes:: Eliminating an asynchronous subprocess.
-* Process Information:: Accessing run-status and other attributes.
-* Input to Processes:: Sending input to an asynchronous subprocess.
-* Signals to Processes:: Stopping, continuing or interrupting
- an asynchronous subprocess.
-* Output from Processes:: Collecting output from an asynchronous subprocess.
-* Sentinels:: Sentinels run when process run-status changes.
-* Process Window Size:: Changing the logical window size of a process.
-* Transaction Queues:: Transaction-based communication with subprocesses.
-* Network:: Opening network connections.
+ ;; Display a command message.
+ (lmessage 'command "Comment column set to %d" comment-column)
+
+ ;; Display a progress message.
+ (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
+
+ ;; Display a message that should not be logged.
+ (lmessage 'no-log "Done")
+
+ - Function: clear-message &optional label frame stdout-p no-restore
+ This function remove any message with the given LABEL from the
+ message-stack, erasing it from the echo area if it's currently
+ displayed there.
+
+ If a message remains at the head of the message-stack and
+ NO-RESTORE is `nil', it will be displayed. The string which
+ remains in the echo area will be returned, or `nil' if the
+ message-stack is now empty. If LABEL is nil, the entire
+ message-stack is cleared.
+
+ ;; Show a message, wait for 2 seconds, and restore old minibuffer
+ ;; contents.
+ (message "A message")
+ -| A message
+ => "A Message"
+ (lmessage 'my-label "Newsflash! Newsflash!")
+ -| Newsflash! Newsflash!
+ => "Newsflash! Newsflash!"
+ (sit-for 2)
+ (clear-message 'my-label)
+ -| A message
+ => "A message"
+
+ Unless you need the return value or you need to specify a label,
+ you should just use `(message nil)'.
+
+ - Function: current-message &optional frame
+ This function returns the current message in the echo area, or
+ `nil'. The FRAME argument is currently unused.
+
+ Some of the messages displayed in the echo area are also recorded in
+the ` *Message-Log*' buffer. Exactly which messages will be recorded
+can be tuned using the following variables.
+
+ - User Option: log-message-max-size
+ This variable specifies the maximum size of the ` *Message-log*'
+ buffer.
+
+ - Variable: log-message-ignore-labels
+ This variable specifies the labels whose messages will not be
+ logged. It should be a list of symbols.
+
+ - Variable: log-message-ignore-regexps
+ This variable specifies the regular expressions matching messages
+ that will not be logged. It should be a list of regular
+ expressions.
+
+ Normally, packages that generate messages that might need to be
+ ignored should label them with `progress', `prompt', or `no-log',
+ so they can be filtered by `log-message-ignore-labels'.
+
+ - Variable: echo-keystrokes
+ This variable determines how much time should elapse before command
+ characters echo. Its value must be a number, which specifies the
+ number of seconds to wait before echoing. If the user types a
+ prefix key (such as `C-x') and then delays this many seconds
+ before continuing, the prefix key is echoed in the echo area. Any
+ subsequent characters in the same command will be echoed as well.
+
+ If the value is zero, then command input is not echoed.
+
+ - Variable: cursor-in-echo-area
+ This variable controls where the cursor appears when a message is
+ displayed in the echo area. If it is non-`nil', then the cursor
+ appears at the end of the message. Otherwise, the cursor appears
+ at point--not in the echo area at all.
+
+ The value is normally `nil'; Lisp programs bind it to `t' for
+ brief periods of time.
\1f
-File: lispref.info, Node: Subprocess Creation, Next: Synchronous Processes, Up: Processes
-
-Functions that Create Subprocesses
-==================================
-
- There are three functions that create a new subprocess in which to
-run a program. One of them, `start-process', creates an asynchronous
-process and returns a process object (*note Asynchronous Processes::).
-The other two, `call-process' and `call-process-region', create a
-synchronous process and do not return a process object (*note
-Synchronous Processes::).
-
- Synchronous and asynchronous processes are explained in following
-sections. Since the three functions are all called in a similar
-fashion, their common arguments are described here.
-
- In all cases, the function's PROGRAM argument specifies the program
-to be run. An error is signaled if the file is not found or cannot be
-executed. If the file name is relative, the variable `exec-path'
-contains a list of directories to search. Emacs initializes
-`exec-path' when it starts up, based on the value of the environment
-variable `PATH'. The standard file name constructs, `~', `.', and
-`..', are interpreted as usual in `exec-path', but environment variable
-substitutions (`$HOME', etc.) are not recognized; use
-`substitute-in-file-name' to perform them (*note File Name Expansion::).
-
- Each of the subprocess-creating functions has a BUFFER-OR-NAME
-argument which specifies where the standard output from the program will
-go. If BUFFER-OR-NAME is `nil', that says to discard the output unless
-a filter function handles it. (*Note Filter Functions::, and *Note
-Read and Print::.) Normally, you should avoid having multiple
-processes send output to the same buffer because their output would be
-intermixed randomly.
-
- All three of the subprocess-creating functions have a `&rest'
-argument, ARGS. The ARGS must all be strings, and they are supplied to
-PROGRAM as separate command line arguments. Wildcard characters and
-other shell constructs are not allowed in these strings, since they are
-passed directly to the specified program.
-
- *Please note:* The argument PROGRAM contains only the name of the
-program; it may not contain any command-line arguments. You must use
-ARGS to provide those.
-
- The subprocess gets its current directory from the value of
-`default-directory' (*note File Name Expansion::).
-
- The subprocess inherits its environment from XEmacs; but you can
-specify overrides for it with `process-environment'. *Note System
-Environment::.
-
- - Variable: exec-directory
- The value of this variable is the name of a directory (a string)
- that contains programs that come with XEmacs, that are intended
- for XEmacs to invoke. The program `wakeup' is an example of such
- a program; the `display-time' command uses it to get a reminder
- once per minute.
-
- - User Option: exec-path
- The value of this variable is a list of directories to search for
- programs to run in subprocesses. Each element is either the name
- of a directory (i.e., a string), or `nil', which stands for the
- default directory (which is the value of `default-directory').
-
- The value of `exec-path' is used by `call-process' and
- `start-process' when the PROGRAM argument is not an absolute file
- name.
+File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
+
+Warnings
+========
+
+ XEmacs contains a facility for unified display of various warnings.
+Unlike errors, warnings are displayed in the situations when XEmacs
+encounters a problem that is recoverable, but which should be fixed for
+safe future operation.
+
+ For example, warnings are printed by the startup code when it
+encounters problems with X keysyms, when there is an error in `.emacs',
+and in other problematic situations. Unlike messages, warnings are
+displayed in a separate buffer, and include an explanatory message that
+may span across several lines. Here is an example of how a warning is
+displayed:
+
+ (1) (initialization/error) An error has occurred while loading ~/.emacs:
+
+ Symbol's value as variable is void: bogus-variable
+
+ To ensure normal operation, you should investigate the cause of the error
+ in your initialization file and remove it. Use the `-debug-init' option
+ to XEmacs to view a complete error backtrace.
+
+ Each warning has a "class" and a "priority level". The class is a
+symbol describing what sort of warning this is, such as
+`initialization', `resource' or `key-mapping'.
+
+ The warning priority level specifies how important the warning is.
+The recognized warning levels, in increased order of priority, are:
+`debug', `info', `notice', `warning', `error', `critical', `alert' and
+`emergency'.
+
+ - Function: display-warning class message &optional level
+ This function displays a warning message MESSAGE (a string).
+ CLASS should be a warning class symbol, as described above, or a
+ list of such symbols. LEVEL describes the warning priority level.
+ If unspecified, it default to `warning'.
+
+ (display-warning 'resource
+ "Bad resource specification encountered:
+ something like
+
+ Emacs*foo: bar
+
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.")
+
+ ---------- Warning buffer ----------
+ (1) (resource/warning) Bad resource specification encountered:
+ something like
+
+ Emacs*foo: bar
+
+ You should replace the * with a . in order to get proper behavior when
+ you use the specifier and/or `set-face-*' functions.
+ ---------- Warning buffer ----------
+
+ - Function: lwarn class level message &rest args
+ This function displays a formatted labeled warning message. As
+ above, CLASS should be the warning class symbol, or a list of such
+ symbols, and LEVEL should specify the warning priority level
+ (`warning' by default).
+
+ Unlike in `display-warning', MESSAGE may be a formatted message,
+ which will be, together with the rest of the arguments, passed to
+ `format'.
+
+ (lwarn 'message-log 'warning
+ "Error caught in `remove-message-hook': %s"
+ (error-message-string e))
+
+ - Variable: log-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be generated. Warnings with level lower than defined by this
+ variable are completely ignored, as if they never happened.
+
+ - Variable: display-warning-minimum-level
+ This variable specifies the minimum level of warnings that should
+ be displayed. Unlike `log-warning-minimum-level', setting this
+ function does not suppress warnings entirely--they are still
+ generated in the `*Warnings*' buffer, only they are not displayed
+ by default.
+
+ - Variable: log-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will be completely ignored, as it they never happened.
+
+ - Variable: display-warning-suppressed-classes
+ This variable specifies a list of classes that should not be
+ logged or displayed. If any of the class symbols associated with
+ a warning is the same as any of the symbols listed here, the
+ warning will not be displayed. The warning will still logged in
+ the *Warnings* buffer (unless also contained in
+ `log-warning-suppressed-classes'), but the buffer will not be
+ automatically popped up.
\1f
-File: lispref.info, Node: Synchronous Processes, Next: MS-DOS Subprocesses, Prev: Subprocess Creation, Up: Processes
-
-Creating a Synchronous Process
-==============================
-
- After a "synchronous process" is created, XEmacs waits for the
-process to terminate before continuing. Starting Dired is an example of
-this: it runs `ls' in a synchronous process, then modifies the output
-slightly. Because the process is synchronous, the entire directory
-listing arrives in the buffer before XEmacs tries to do anything with
-it.
-
- While Emacs waits for the synchronous subprocess to terminate, the
-user can quit by typing `C-g'. The first `C-g' tries to kill the
-subprocess with a `SIGINT' signal; but it waits until the subprocess
-actually terminates before quitting. If during that time the user
-types another `C-g', that kills the subprocess instantly with `SIGKILL'
-and quits immediately. *Note Quitting::.
-
- The synchronous subprocess functions returned `nil' in version 18.
-In version 19, they return an indication of how the process terminated.
-
- - Function: call-process program &optional infile destination display
- &rest args
- This function calls PROGRAM in a separate process and waits for it
- to finish.
-
- The standard input for the process comes from file INFILE if
- INFILE is not `nil' and from `/dev/null' otherwise. The argument
- DESTINATION says where to put the process output. Here are the
- possibilities:
-
- a buffer
- Insert the output in that buffer, before point. This
- includes both the standard output stream and the standard
- error stream of the process.
-
- a string
- Find or create a buffer with that name, then insert the
- output in that buffer, before point.
+File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
+
+Invisible Text
+==============
+
+ You can make characters "invisible", so that they do not appear on
+the screen, with the `invisible' property. This can be either a text
+property or a property of an overlay.
+
+ In the simplest case, any non-`nil' `invisible' property makes a
+character invisible. This is the default case--if you don't alter the
+default value of `buffer-invisibility-spec', this is how the
+`invisibility' property works. This feature is much like selective
+display (*note Selective Display::), but more general and cleaner.
+
+ More generally, you can use the variable `buffer-invisibility-spec'
+to control which values of the `invisible' property make text
+invisible. This permits you to classify the text into different subsets
+in advance, by giving them different `invisible' values, and
+subsequently make various subsets visible or invisible by changing the
+value of `buffer-invisibility-spec'.
+
+ Controlling visibility with `buffer-invisibility-spec' is especially
+useful in a program to display the list of entries in a data base. It
+permits the implementation of convenient filtering commands to view
+just a part of the entries in the data base. Setting this variable is
+very fast, much faster than scanning all the text in the buffer looking
+for properties to change.
+
+ - Variable: buffer-invisibility-spec
+ This variable specifies which kinds of `invisible' properties
+ actually make a character invisible.
`t'
- Insert the output in the current buffer, before point.
-
- `nil'
- Discard the output.
-
- 0
- Discard the output, and return immediately without waiting
- for the subprocess to finish.
-
- In this case, the process is not truly synchronous, since it
- can run in parallel with Emacs; but you can think of it as
- synchronous in that Emacs is essentially finished with the
- subprocess as soon as this function returns.
-
- (REAL-DESTINATION ERROR-DESTINATION)
- Keep the standard output stream separate from the standard
- error stream; deal with the ordinary output as specified by
- REAL-DESTINATION, and dispose of the error output according
- to ERROR-DESTINATION. The value `nil' means discard it, `t'
- means mix it with the ordinary output, and a string specifies
- a file name to redirect error output into.
-
- You can't directly specify a buffer to put the error output
- in; that is too difficult to implement. But you can achieve
- this result by sending the error output to a temporary file
- and then inserting the file into a buffer.
-
- If DISPLAY is non-`nil', then `call-process' redisplays the buffer
- as output is inserted. Otherwise the function does no redisplay,
- and the results become visible on the screen only when XEmacs
- redisplays that buffer in the normal course of events.
-
- The remaining arguments, ARGS, are strings that specify command
- line arguments for the program.
-
- The value returned by `call-process' (unless you told it not to
- wait) indicates the reason for process termination. A number
- gives the exit status of the subprocess; 0 means success, and any
- other value means failure. If the process terminated with a
- signal, `call-process' returns a string describing the signal.
-
- In the examples below, the buffer `foo' is current.
-
- (call-process "pwd" nil t)
+ A character is invisible if its `invisible' property is
+ non-`nil'. This is the default.
+
+ a list
+ Each element of the list makes certain characters invisible.
+ Ultimately, a character is invisible if any of the elements
+ of this list applies to it. The list can have two kinds of
+ elements:
+
+ `ATOM'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+
+ `(ATOM . t)'
+ A character is invisible if its `invisible' property
+ value is ATOM or if it is a list with ATOM as a member.
+ Moreover, if this character is at the end of a line and
+ is followed by a visible newline, it displays an
+ ellipsis.
+
+ Ordinarily, commands that operate on text or move point do not care
+whether the text is invisible. However, the user-level line motion
+commands explicitly ignore invisible newlines.
+
+\1f
+File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
+
+Selective Display
+=================
+
+ "Selective display" is a pair of features that hide certain lines on
+the screen.
+
+ The first variant, explicit selective display, is designed for use in
+a Lisp program. The program controls which lines are hidden by altering
+the text. Outline mode has traditionally used this variant. It has
+been partially replaced by the invisible text feature (*note Invisible
+Text::); there is a new version of Outline mode which uses that instead.
+
+ In the second variant, the choice of lines to hide is made
+automatically based on indentation. This variant is designed to be a
+user-level feature.
+
+ The way you control explicit selective display is by replacing a
+newline (control-j) with a carriage return (control-m). The text that
+was formerly a line following that newline is now invisible. Strictly
+speaking, it is temporarily no longer a line at all, since only newlines
+can separate lines; it is now part of the previous line.
+
+ Selective display does not directly affect editing commands. For
+example, `C-f' (`forward-char') moves point unhesitatingly into
+invisible text. However, the replacement of newline characters with
+carriage return characters affects some editing commands. For example,
+`next-line' skips invisible lines, since it searches only for newlines.
+Modes that use selective display can also define commands that take
+account of the newlines, or that make parts of the text visible or
+invisible.
+
+ When you write a selectively displayed buffer into a file, all the
+control-m's are output as newlines. This means that when you next read
+in the file, it looks OK, with nothing invisible. The selective display
+effect is seen only within XEmacs.
+
+ - Variable: selective-display
+ This buffer-local variable enables selective display. This means
+ that lines, or portions of lines, may be made invisible.
+
+ * If the value of `selective-display' is `t', then any portion
+ of a line that follows a control-m is not displayed.
+
+ * If the value of `selective-display' is a positive integer,
+ then lines that start with more than that many columns of
+ indentation are not displayed.
+
+ When some portion of a buffer is invisible, the vertical movement
+ commands operate as if that portion did not exist, allowing a
+ single `next-line' command to skip any number of invisible lines.
+ However, character movement commands (such as `forward-char') do
+ not skip the invisible portion, and it is possible (if tricky) to
+ insert or delete text in an invisible portion.
+
+ In the examples below, we show the _display appearance_ of the
+ buffer `foo', which changes with the value of `selective-display'.
+ The _contents_ of the buffer do not change.
+
+ (setq selective-display nil)
=> nil
---------- Buffer: foo ----------
- /usr/user/lewis/manual
+ 1 on this column
+ 2on this column
+ 3n this column
+ 3n this column
+ 2on this column
+ 1 on this column
---------- Buffer: foo ----------
- (call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
- => nil
-
- ---------- Buffer: bar ----------
- lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
+ (setq selective-display 2)
+ => 2
- ---------- Buffer: bar ----------
-
- The `insert-directory' function contains a good example of the use
- of `call-process':
-
- (call-process insert-directory-program nil t nil switches
- (if full-directory-p
- (concat (file-name-as-directory file) ".")
- file))
-
- - Function: call-process-region start end program &optional delete
- destination display &rest args
- This function sends the text between START to END as standard
- input to a process running PROGRAM. It deletes the text sent if
- DELETE is non-`nil'; this is useful when BUFFER is `t', to insert
- the output in the current buffer.
-
- The arguments DESTINATION and DISPLAY control what to do with the
- output from the subprocess, and whether to update the display as
- it comes in. For details, see the description of `call-process',
- above. If DESTINATION is the integer 0, `call-process-region'
- discards the output and returns `nil' immediately, without waiting
- for the subprocess to finish.
-
- The remaining arguments, ARGS, are strings that specify command
- line arguments for the program.
-
- The return value of `call-process-region' is just like that of
- `call-process': `nil' if you told it to return without waiting;
- otherwise, a number or string which indicates how the subprocess
- terminated.
-
- In the following example, we use `call-process-region' to run the
- `cat' utility, with standard input being the first five characters
- in buffer `foo' (the word `input'). `cat' copies its standard
- input into its standard output. Since the argument DESTINATION is
- `t', this output is inserted in the current buffer.
-
---------- Buffer: foo ----------
- input-!-
+ 1 on this column
+ 2on this column
+ 2on this column
+ 1 on this column
---------- Buffer: foo ----------
-
- (call-process-region 1 6 "cat" nil t)
- => nil
+
+ - Variable: selective-display-ellipses
+ If this buffer-local variable is non-`nil', then XEmacs displays
+ `...' at the end of a line that is followed by invisible text.
+ This example is a continuation of the previous one.
+
+ (setq selective-display-ellipses t)
+ => t
---------- Buffer: foo ----------
- inputinput-!-
+ 1 on this column
+ 2on this column ...
+ 2on this column
+ 1 on this column
---------- Buffer: foo ----------
- The `shell-command-on-region' command uses `call-process-region'
- like this:
-
- (call-process-region
- start end
- shell-file-name ; Name of program.
- nil ; Do not delete region.
- buffer ; Send output to `buffer'.
- nil ; No redisplay during output.
- "-c" command) ; Arguments for the shell.
+ You can use a display table to substitute other text for the
+ ellipsis (`...'). *Note Display Tables::.
\1f
-File: lispref.info, Node: MS-DOS Subprocesses, Next: Asynchronous Processes, Prev: Synchronous Processes, Up: Processes
+File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
-MS-DOS Subprocesses
-===================
+The Overlay Arrow
+=================
- On MS-DOS, you must indicate whether the data going to and from a
-synchronous subprocess are text or binary. Text data requires
-translation between the end-of-line convention used within Emacs (a
-single newline character) and the convention used outside Emacs (the
-two-character sequence, CRLF).
+ The "overlay arrow" is useful for directing the user's attention to
+a particular line in a buffer. For example, in the modes used for
+interface to debuggers, the overlay arrow indicates the line of code
+about to be executed.
- The variable `binary-process-input' applies to input sent to the
-subprocess, and `binary-process-output' applies to output received from
-it. A non-`nil' value means the data is non-text; `nil' means the data
-is text, and calls for conversion.
+ - Variable: overlay-arrow-string
+ This variable holds the string to display to call attention to a
+ particular line, or `nil' if the arrow feature is not in use.
+ Despite its name, the value of this variable can be either a string
+ or a glyph (*note Glyphs::).
- - Variable: binary-process-input
- If this variable is `nil', convert newlines to CRLF sequences in
- the input to a synchronous subprocess.
+ - Variable: overlay-arrow-position
+ This variable holds a marker that indicates where to display the
+ overlay arrow. It should point at the beginning of a line. The
+ arrow text appears at the beginning of that line, overlaying any
+ text that would otherwise appear. Since the arrow is usually
+ short, and the line usually begins with indentation, normally
+ nothing significant is overwritten.
- - Variable: binary-process-output
- If this variable is `nil', convert CRLF sequences to newlines in
- the output from a synchronous subprocess.
+ The overlay string is displayed only in the buffer that this marker
+ points into. Thus, only one buffer can have an overlay arrow at
+ any given time.
- *Note Files and MS-DOS::, for related information.
+ You can do the same job by creating an extent with a `begin-glyph'
+property. *Note Extent Properties::.
\1f
-File: lispref.info, Node: Asynchronous Processes, Next: Deleting Processes, Prev: MS-DOS Subprocesses, Up: Processes
-
-Creating an Asynchronous Process
-================================
-
- After an "asynchronous process" is created, Emacs and the Lisp
-program both continue running immediately. The process may thereafter
-run in parallel with Emacs, and the two may communicate with each other
-using the functions described in following sections. Here we describe
-how to create an asynchronous process with `start-process'.
-
- - Function: start-process name buffer-or-name program &rest args
- This function creates a new asynchronous subprocess and starts the
- program PROGRAM running in it. It returns a process object that
- stands for the new subprocess in Lisp. The argument NAME
- specifies the name for the process object; if a process with this
- name already exists, then NAME is modified (by adding `<1>', etc.)
- to be unique. The buffer BUFFER-OR-NAME is the buffer to
- associate with the process.
-
- The remaining arguments, ARGS, are strings that specify command
- line arguments for the program.
-
- In the example below, the first process is started and runs
- (rather, sleeps) for 100 seconds. Meanwhile, the second process
- is started, and given the name `my-process<1>' for the sake of
- uniqueness. It inserts the directory listing at the end of the
- buffer `foo', before the first process finishes. Then it
- finishes, and a message to that effect is inserted in the buffer.
- Much later, the first process finishes, and another message is
- inserted in the buffer for it.
-
- (start-process "my-process" "foo" "sleep" "100")
- => #<process my-process>
+File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
+
+Temporary Displays
+==================
+
+ Temporary displays are used by commands to put output into a buffer
+and then present it to the user for perusal rather than for editing.
+Many of the help commands use this feature.
+
+ - Special Form: with-output-to-temp-buffer buffer-name forms...
+ This function executes FORMS while arranging to insert any output
+ they print into the buffer named BUFFER-NAME. The buffer is then
+ shown in some window for viewing, displayed but not selected.
+
+ The string BUFFER-NAME specifies the temporary buffer, which need
+ not already exist. The argument must be a string, not a buffer.
+ The buffer is erased initially (with no questions asked), and it is
+ marked as unmodified after `with-output-to-temp-buffer' exits.
+
+ `with-output-to-temp-buffer' binds `standard-output' to the
+ temporary buffer, then it evaluates the forms in FORMS. Output
+ using the Lisp output functions within FORMS goes by default to
+ that buffer (but screen display and messages in the echo area,
+ although they are "output" in the general sense of the word, are
+ not affected). *Note Output Functions::.
+
+ The value of the last form in FORMS is returned.
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ ---------- Buffer: foo ----------
- (start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin")
- => #<process my-process<1>>
+ (with-output-to-temp-buffer "foo"
+ (print 20)
+ (print standard-output))
+ => #<buffer foo>
---------- Buffer: foo ----------
- total 2
- lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs
- -rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon
+ 20
- Process my-process<1> finished
+ #<buffer foo>
- Process my-process finished
---------- Buffer: foo ----------
- - Function: start-process-shell-command name buffer-or-name command
- &rest command-args
- This function is like `start-process' except that it uses a shell
- to execute the specified command. The argument COMMAND is a shell
- command name, and COMMAND-ARGS are the arguments for the shell
- command.
-
- - Variable: process-connection-type
- This variable controls the type of device used to communicate with
- asynchronous subprocesses. If it is non-`nil', then PTYs are
- used, when available. Otherwise, pipes are used.
-
- PTYs are usually preferable for processes visible to the user, as
- in Shell mode, because they allow job control (`C-c', `C-z', etc.)
- to work between the process and its children whereas pipes do not.
- For subprocesses used for internal purposes by programs, it is
- often better to use a pipe, because they are more efficient. In
- addition, the total number of PTYs is limited on many systems and
- it is good not to waste them.
-
- The value `process-connection-type' is used when `start-process'
- is called. So you can specify how to communicate with one
- subprocess by binding the variable around the call to
- `start-process'.
-
- (let ((process-connection-type nil)) ; Use a pipe.
- (start-process ...))
-
- To determine whether a given subprocess actually got a pipe or a
- PTY, use the function `process-tty-name' (*note Process
- Information::).
+ - Variable: temp-buffer-show-function
+ If this variable is non-`nil', `with-output-to-temp-buffer' calls
+ it as a function to do the job of displaying a help buffer. The
+ function gets one argument, which is the buffer it should display.
-\1f
-File: lispref.info, Node: Deleting Processes, Next: Process Information, Prev: Asynchronous Processes, Up: Processes
+ In Emacs versions 18 and earlier, this variable was called
+ `temp-buffer-show-hook'.
-Deleting Processes
-==================
+ - Function: momentary-string-display string position &optional char
+ message
+ This function momentarily displays STRING in the current buffer at
+ POSITION. It has no effect on the undo list or on the buffer's
+ modification status.
- "Deleting a process" disconnects XEmacs immediately from the
-subprocess, and removes it from the list of active processes. It sends
-a signal to the subprocess to make the subprocess terminate, but this is
-not guaranteed to happen immediately. The process object itself
-continues to exist as long as other Lisp objects point to it.
-
- You can delete a process explicitly at any time. Processes are
-deleted automatically after they terminate, but not necessarily right
-away. If you delete a terminated process explicitly before it is
-deleted automatically, no harm results.
-
- - Variable: delete-exited-processes
- This variable controls automatic deletion of processes that have
- terminated (due to calling `exit' or to a signal). If it is
- `nil', then they continue to exist until the user runs
- `list-processes'. Otherwise, they are deleted immediately after
- they exit.
-
- - Function: delete-process name
- This function deletes the process associated with NAME, killing it
- with a `SIGHUP' signal. The argument NAME may be a process, the
- name of a process, a buffer, or the name of a buffer.
-
- (delete-process "*shell*")
- => nil
+ The momentary display remains until the next input event. If the
+ next input event is CHAR, `momentary-string-display' ignores it
+ and returns. Otherwise, that event remains buffered for
+ subsequent use as input. Thus, typing CHAR will simply remove the
+ string from the display, while typing (say) `C-f' will remove the
+ string from the display and later (presumably) move point forward.
+ The argument CHAR is a space by default.
- - Function: process-kill-without-query process &optional
- require-query-p
- This function declares that XEmacs need not query the user if
- PROCESS is still running when XEmacs is exited. The process will
- be deleted silently. If REQUIRE-QUERY-P is non-`nil', then XEmacs
- _will_ query the user (this is the default). The return value is
- `t' if a query was formerly required, and `nil' otherwise.
+ The return value of `momentary-string-display' is not meaningful.
- (process-kill-without-query (get-process "shell"))
- => t
+ You can do the same job in a more general way by creating an extent
+ with a begin-glyph property. *Note Extent Properties::.
-\1f
-File: lispref.info, Node: Process Information, Next: Input to Processes, Prev: Deleting Processes, Up: Processes
+ If MESSAGE is non-`nil', it is displayed in the echo area while
+ STRING is displayed in the buffer. If it is `nil', a default
+ message says to type CHAR to continue.
-Process Information
-===================
+ In this example, point is initially located at the beginning of the
+ second line:
- Several functions return information about processes.
-`list-processes' is provided for interactive use.
-
- - Command: list-processes
- This command displays a listing of all living processes. In
- addition, it finally deletes any process whose status was `Exited'
- or `Signaled'. It returns `nil'.
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ -!-Second line.
+ ---------- Buffer: foo ----------
+
+ (momentary-string-display
+ "**** Important Message! ****"
+ (point) ?\r
+ "Type RET when done reading")
+ => t
+
+ ---------- Buffer: foo ----------
+ This is the contents of foo.
+ **** Important Message! ****Second line.
+ ---------- Buffer: foo ----------
+
+ ---------- Echo Area ----------
+ Type RET when done reading
+ ---------- Echo Area ----------
- - Function: process-list
- This function returns a list of all processes that have not been
- deleted.
+ This function works by actually changing the text in the buffer.
+ As a result, if you later undo in this buffer, you will see the
+ message come and go.
- (process-list)
- => (#<process display-time> #<process shell>)
+\1f
+File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
+
+Blinking Parentheses
+====================
+
+ This section describes the mechanism by which XEmacs shows a matching
+open parenthesis when the user inserts a close parenthesis.
+
+ - Variable: blink-paren-function
+ The value of this variable should be a function (of no arguments)
+ to be called whenever a character with close parenthesis syntax is
+ inserted. The value of `blink-paren-function' may be `nil', in
+ which case nothing is done.
+
+ *Please note:* This variable was named `blink-paren-hook' in
+ older Emacs versions, but since it is not called with the
+ standard convention for hooks, it was renamed to
+ `blink-paren-function' in version 19.
+
+ - Variable: blink-matching-paren
+ If this variable is `nil', then `blink-matching-open' does nothing.
+
+ - Variable: blink-matching-paren-distance
+ This variable specifies the maximum distance to scan for a matching
+ parenthesis before giving up.
+
+ - Variable: blink-matching-paren-delay
+ This variable specifies the number of seconds for the cursor to
+ remain at the matching parenthesis. A fraction of a second often
+ gives good results, but the default is 1, which works on all
+ systems.
+
+ - Function: blink-matching-open
+ This function is the default value of `blink-paren-function'. It
+ assumes that point follows a character with close parenthesis
+ syntax and moves the cursor momentarily to the matching opening
+ character. If that character is not already on the screen, it
+ displays the character's context in the echo area. To avoid long
+ delays, this function does not search farther than
+ `blink-matching-paren-distance' characters.
+
+ Here is an example of calling this function explicitly.
+
+ (defun interactive-blink-matching-open ()
+ "Indicate momentarily the start of sexp before point."
+ (interactive)
+ (let ((blink-matching-paren-distance
+ (buffer-size))
+ (blink-matching-paren t))
+ (blink-matching-open)))
- - Function: get-process name
- This function returns the process named NAME, or `nil' if there is
- none. An error is signaled if NAME is not a string.
+\1f
+File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
- (get-process "shell")
- => #<process shell>
+Usual Display Conventions
+=========================
- - Function: process-command process
- This function returns the command that was executed to start
- PROCESS. This is a list of strings, the first string being the
- program executed and the rest of the strings being the arguments
- that were given to the program.
+ The usual display conventions define how to display each character
+code. You can override these conventions by setting up a display table
+(*note Display Tables::). Here are the usual display conventions:
- (process-command (get-process "shell"))
- => ("/bin/csh" "-i")
+ * Character codes 32 through 126 map to glyph codes 32 through 126.
+ Normally this means they display as themselves.
- - Function: process-id process
- This function returns the PID of PROCESS. This is an integer that
- distinguishes the process PROCESS from all other processes running
- on the same computer at the current time. The PID of a process is
- chosen by the operating system kernel when the process is started
- and remains constant as long as the process exists.
+ * Character code 9 is a horizontal tab. It displays as whitespace
+ up to a position determined by `tab-width'.
- - Function: process-name process
- This function returns the name of PROCESS.
+ * Character code 10 is a newline.
- - Function: process-status process-name
- This function returns the status of PROCESS-NAME as a symbol. The
- argument PROCESS-NAME must be a process, a buffer, a process name
- (string) or a buffer name (string).
+ * All other codes in the range 0 through 31, and code 127, display
+ in one of two ways according to the value of `ctl-arrow'. If it is
+ non-`nil', these codes map to sequences of two glyphs, where the
+ first glyph is the ASCII code for `^'. (A display table can
+ specify a glyph to use instead of `^'.) Otherwise, these codes map
+ just like the codes in the range 128 to 255.
- The possible values for an actual subprocess are:
+ * Character codes 128 through 255 map to sequences of four glyphs,
+ where the first glyph is the ASCII code for `\', and the others are
+ digit characters representing the code in octal. (A display table
+ can specify a glyph to use instead of `\'.)
- `run'
- for a process that is running.
+ The usual display conventions apply even when there is a display
+table, for any character whose entry in the active display table is
+`nil'. Thus, when you set up a display table, you need only specify
+the characters for which you want unusual behavior.
- `stop'
- for a process that is stopped but continuable.
+ These variables affect the way certain characters are displayed on
+the screen. Since they change the number of columns the characters
+occupy, they also affect the indentation functions.
- `exit'
- for a process that has exited.
+ - User Option: ctl-arrow
+ This buffer-local variable controls how control characters are
+ displayed. If it is non-`nil', they are displayed as a caret
+ followed by the character: `^A'. If it is `nil', they are
+ displayed as a backslash followed by three octal digits: `\001'.
- `signal'
- for a process that has received a fatal signal.
+ - Variable: default-ctl-arrow
+ The value of this variable is the default value for `ctl-arrow' in
+ buffers that do not override it. *Note Default Value::.
- `open'
- for a network connection that is open.
+ - User Option: tab-width
+ The value of this variable is the spacing between tab stops used
+ for displaying tab characters in Emacs buffers. The default is 8.
+ Note that this feature is completely independent from the
+ user-settable tab stops used by the command `tab-to-tab-stop'.
+ *Note Indent Tabs::.
- `closed'
- for a network connection that is closed. Once a connection
- is closed, you cannot reopen it, though you might be able to
- open a new connection to the same place.
+\1f
+File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
- `nil'
- if PROCESS-NAME is not the name of an existing process.
+Display Tables
+==============
- (process-status "shell")
- => run
- (process-status (get-buffer "*shell*"))
- => run
- x
- => #<process xx<1>>
- (process-status x)
- => exit
+ You can use the "display table" feature to control how all 256
+possible character codes display on the screen. This is useful for
+displaying European languages that have letters not in the ASCII
+character set.
- For a network connection, `process-status' returns one of the
- symbols `open' or `closed'. The latter means that the other side
- closed the connection, or XEmacs did `delete-process'.
+ The display table maps each character code into a sequence of
+"runes", each rune being an image that takes up one character position
+on the screen. You can also define how to display each rune on your
+terminal, using the "rune table".
- In earlier Emacs versions (prior to version 19), the status of a
- network connection was `run' if open, and `exit' if closed.
+* Menu:
- - Function: process-kill-without-query-p process
- This function returns whether PROCESS will be killed without
- querying the user, if it is running when XEmacs is exited. The
- default value is `nil'.
+* Display Table Format:: What a display table consists of.
+* Active Display Table:: How XEmacs selects a display table to use.
+* Character Descriptors:: Format of an individual element of a
+ display table.
- - Function: process-exit-status process
- This function returns the exit status of PROCESS or the signal
- number that killed it. (Use the result of `process-status' to
- determine which of those it is.) If PROCESS has not yet
- terminated, the value is 0.
+\1f
+File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
+
+Display Table Format
+--------------------
+
+ A display table is an array of 256 elements. (In FSF Emacs, a display
+table is 262 elements. The six extra elements specify the truncation
+and continuation glyphs, etc. This method is very kludgey, and in
+XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
+used. *Note Truncation::.)
+
+ - Function: make-display-table
+ This creates and returns a display table. The table initially has
+ `nil' in all elements.
+
+ The 256 elements correspond to character codes; the Nth element says
+how to display the character code N. The value should be `nil', a
+string, a glyph, or a vector of strings and glyphs (*note Character
+Descriptors::). If an element is `nil', it says to display that
+character according to the usual display conventions (*note Usual
+Display::).
+
+ If you use the display table to change the display of newline
+characters, the whole buffer will be displayed as one long "line."
+
+ For example, here is how to construct a display table that mimics the
+effect of setting `ctl-arrow' to a non-`nil' value:
+
+ (setq disptab (make-display-table))
+ (let ((i 0))
+ (while (< i 32)
+ (or (= i ?\t) (= i ?\n)
+ (aset disptab i (concat "^" (char-to-string (+ i 64)))))
+ (setq i (1+ i)))
+ (aset disptab 127 "^?"))
- - Function: process-tty-name process
- This function returns the terminal name that PROCESS is using for
- its communication with Emacs--or `nil' if it is using pipes
- instead of a terminal (see `process-connection-type' in *Note
- Asynchronous Processes::).
+\1f
+File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
+
+Active Display Table
+--------------------
+
+ The active display table is controlled by the variable
+`current-display-table'. This is a specifier, which means that you can
+specify separate values for it in individual buffers, windows, frames,
+and devices, as well as a global value. It also means that you cannot
+set this variable using `setq'; use `set-specifier' instead. *Note
+Specifiers::. (FSF Emacs uses `window-display-table',
+`buffer-display-table', `standard-display-table', etc. to control the
+display table. However, specifiers are a cleaner and more powerful way
+of doing the same thing. FSF Emacs also uses a different format for
+the contents of a display table, using additional indirection to a
+"glyph table" and such. Note that "glyph" has a different meaning in
+XEmacs.)
+
+ - Variable: current-display-table
+ The display table currently in use. This is a specifier.
+
+ Display tables are used to control how characters are displayed.
+ Each time that redisplay processes a character, it is looked up in
+ all the display tables that apply (obtained by calling
+ `specifier-instance' on `current-display-table' and any overriding
+ display tables specified in currently active faces). The first
+ entry found that matches the character determines how the
+ character is displayed. If there is no matching entry, the
+ default display method is used. (Non-control characters are
+ displayed as themselves and control characters are displayed
+ according to the buffer-local variable `ctl-arrow'. Control
+ characters are further affected by `control-arrow-glyph' and
+ `octal-escape-glyph'.)
+
+ Each instantiator in this specifier and the display-table
+ specifiers in faces is a display table or a list of such tables.
+ If a list, each table will be searched in turn for an entry
+ matching a particular character. Each display table is one of
+
+ * A vector, specifying values for characters starting at 0.
+
+ * A char table, either of type `char' or `generic'.
+
+ * A range table.
+
+ Each entry in a display table should be one of
+
+ * nil (this entry is ignored and the search continues).
+
+ * A character (use this character; if it happens to be the same
+ as the original character, default processing happens,
+ otherwise redisplay attempts to display this character
+ directly; #### At some point recursive display-table lookup
+ will be implemented).
+
+ * A string (display each character in the string directly; ####
+ At some point recursive display-table lookup will be
+ implemented).
+
+ * A glyph (display the glyph; #### At some point recursive
+ display-table lookup will be implemented when a string glyph
+ is being processed).
+
+ * A cons of the form (format "STRING") where STRING is a
+ printf-like spec used to process the character. ####
+ Unfortunately no formatting directives other than %% are
+ implemented.
+
+ * A vector (each element of the vector is processed recursively;
+ in such a case, nil elements in the vector are simply
+ ignored).
+
+ #### At some point in the near future, display tables are
+ likely to be expanded to include other features, such as
+ referencing characters in particular fonts and allowing the
+ character search to continue all the way up the chain of
+ specifier instantiators. These features are necessary to
+ properly display Unicode characters.
+
+ Individual faces can also specify an overriding display table; this
+is set using `set-face-display-table'. *Note Faces::.
+
+ If no display table can be determined for a particular window, then
+XEmacs uses the usual display conventions. *Note Usual Display::.
\1f
-File: lispref.info, Node: Input to Processes, Next: Signals to Processes, Prev: Process Information, Up: Processes
+File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
-Sending Input to Processes
-==========================
+Character Descriptors
+---------------------
- Asynchronous subprocesses receive input when it is sent to them by
-XEmacs, which is done with the functions in this section. You must
-specify the process to send input to, and the input data to send. The
-data appears on the "standard input" of the subprocess.
+ Each element of the display-table vector describes how to display a
+particular character and is called a "character descriptor". A
+character descriptor can be:
- Some operating systems have limited space for buffered input in a
-PTY. On these systems, Emacs sends an EOF periodically amidst the
-other characters, to force them through. For most programs, these EOFs
-do no harm.
+a string
+ Display this particular string wherever the character is to be
+ displayed.
- - Function: process-send-string process-name string
- This function sends PROCESS-NAME the contents of STRING as
- standard input. The argument PROCESS-NAME must be a process or
- the name of a process. If it is `nil', the current buffer's
- process is used.
+a glyph
+ Display this particular glyph wherever the character is to be
+ displayed.
- The function returns `nil'.
+a vector
+ The vector may contain strings and/or glyphs. Display the
+ elements of the vector one after another wherever the character is
+ to be displayed.
- (process-send-string "shell<1>" "ls\n")
- => nil
-
-
- ---------- Buffer: *shell* ----------
- ...
- introduction.texi syntax-tables.texi~
- introduction.texi~ text.texi
- introduction.txt text.texi~
- ...
- ---------- Buffer: *shell* ----------
+`nil'
+ Display according to the standard interpretation (*note Usual
+ Display::).
- - Command: process-send-region process-name start end
- This function sends the text in the region defined by START and
- END as standard input to PROCESS-NAME, which is a process or a
- process name. (If it is `nil', the current buffer's process is
- used.)
+\1f
+File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
- An error is signaled unless both START and END are integers or
- markers that indicate positions in the current buffer. (It is
- unimportant which number is larger.)
+Beeping
+=======
- - Function: process-send-eof &optional process-name
- This function makes PROCESS-NAME see an end-of-file in its input.
- The EOF comes after any text already sent to it.
+ You can make XEmacs ring a bell, play a sound, or blink the screen to
+attract the user's attention. Be conservative about how often you do
+this; frequent bells can become irritating. Also be careful not to use
+beeping alone when signaling an error is appropriate. (*Note Errors::.)
- If PROCESS-NAME is not supplied, or if it is `nil', then this
- function sends the EOF to the current buffer's process. An error
- is signaled if the current buffer has no process.
+ - Function: ding &optional dont-terminate sound device
+ This function beeps, or flashes the screen (see `visible-bell'
+ below). It also terminates any keyboard macro currently executing
+ unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
+ should be a symbol specifying which sound to make. This sound
+ will be played if `visible-bell' is `nil'. (This only works if
+ sound support was compiled into the executable and you are running
+ on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
+ PC. Otherwise you just get a beep.) The optional third argument
+ specifies what device to make the sound on, and defaults to the
+ selected device.
- The function returns PROCESS-NAME.
+ - Function: beep &optional dont-terminate sound device
+ This is a synonym for `ding'.
- (process-send-eof "shell")
- => "shell"
+ - User Option: visible-bell
+ This variable determines whether XEmacs should flash the screen to
+ represent a bell. Non-`nil' means yes, `nil' means no. On TTY
+ devices, this is effective only if the Termcap entry for the
+ terminal type has the visible bell flag (`vb') set.
-\1f
-File: lispref.info, Node: Signals to Processes, Next: Output from Processes, Prev: Input to Processes, Up: Processes
-
-Sending Signals to Processes
-============================
-
- "Sending a signal" to a subprocess is a way of interrupting its
-activities. There are several different signals, each with its own
-meaning. The set of signals and their names is defined by the operating
-system. For example, the signal `SIGINT' means that the user has typed
-`C-c', or that some analogous thing has happened.
-
- Each signal has a standard effect on the subprocess. Most signals
-kill the subprocess, but some stop or resume execution instead. Most
-signals can optionally be handled by programs; if the program handles
-the signal, then we can say nothing in general about its effects.
-
- The set of signals and their names is defined by the operating
-system; XEmacs has facilities for sending only a few of the signals
-that are defined. XEmacs can send signals only to its own subprocesses.
-
- You can send signals explicitly by calling the functions in this
-section. XEmacs also sends signals automatically at certain times:
-killing a buffer sends a `SIGHUP' signal to all its associated
-processes; killing XEmacs sends a `SIGHUP' signal to all remaining
-processes. (`SIGHUP' is a signal that usually indicates that the user
-hung up the phone.)
-
- Each of the signal-sending functions takes two optional arguments:
-PROCESS-NAME and CURRENT-GROUP.
-
- The argument PROCESS-NAME must be either a process, the name of one,
-or `nil'. If it is `nil', the process defaults to the process
-associated with the current buffer. An error is signaled if
-PROCESS-NAME does not identify a process.
-
- The argument CURRENT-GROUP is a flag that makes a difference when
-you are running a job-control shell as an XEmacs subprocess. If it is
-non-`nil', then the signal is sent to the current process-group of the
-terminal that XEmacs uses to communicate with the subprocess. If the
-process is a job-control shell, this means the shell's current subjob.
-If it is `nil', the signal is sent to the process group of the
-immediate subprocess of XEmacs. If the subprocess is a job-control
-shell, this is the shell itself.
-
- The flag CURRENT-GROUP has no effect when a pipe is used to
-communicate with the subprocess, because the operating system does not
-support the distinction in the case of pipes. For the same reason,
-job-control shells won't work when a pipe is used. See
-`process-connection-type' in *Note Asynchronous Processes::.
-
- - Function: interrupt-process &optional process-name current-group
- This function interrupts the process PROCESS-NAME by sending the
- signal `SIGINT'. Outside of XEmacs, typing the "interrupt
- character" (normally `C-c' on some systems, and `DEL' on others)
- sends this signal. When the argument CURRENT-GROUP is non-`nil',
- you can think of this function as "typing `C-c'" on the terminal
- by which XEmacs talks to the subprocess.
-
- - Function: kill-process &optional process-name current-group
- This function kills the process PROCESS-NAME by sending the signal
- `SIGKILL'. This signal kills the subprocess immediately, and
- cannot be handled by the subprocess.
-
- - Function: quit-process &optional process-name current-group
- This function sends the signal `SIGQUIT' to the process
- PROCESS-NAME. This signal is the one sent by the "quit character"
- (usually `C-b' or `C-\') when you are not inside XEmacs.
-
- - Function: stop-process &optional process-name current-group
- This function stops the process PROCESS-NAME by sending the signal
- `SIGTSTP'. Use `continue-process' to resume its execution.
-
- On systems with job control, the "stop character" (usually `C-z')
- sends this signal (outside of XEmacs). When CURRENT-GROUP is
- non-`nil', you can think of this function as "typing `C-z'" on the
- terminal XEmacs uses to communicate with the subprocess.
-
- - Function: continue-process &optional process-name current-group
- This function resumes execution of the process PROCESS by sending
- it the signal `SIGCONT'. This presumes that PROCESS-NAME was
- stopped previously.
-
- - Function: signal-process pid signal
- This function sends a signal to process PID, which need not be a
- child of XEmacs. The argument SIGNAL specifies which signal to
- send; it should be an integer.
+ - Variable: sound-alist
+ This variable holds an alist associating names with sounds. When
+ `beep' or `ding' is called with one of the name symbols, the
+ associated sound will be generated instead of the standard beep.
-\1f
-File: lispref.info, Node: Output from Processes, Next: Sentinels, Prev: Signals to Processes, Up: Processes
+ Each element of `sound-alist' is a list describing a sound. The
+ first element of the list is the name of the sound being defined.
+ Subsequent elements of the list are alternating keyword/value
+ pairs:
-Receiving Output from Processes
-===============================
+ `sound'
+ A string of raw sound data, or the name of another sound to
+ play. The symbol `t' here means use the default X beep.
- There are two ways to receive the output that a subprocess writes to
-its standard output stream. The output can be inserted in a buffer,
-which is called the associated buffer of the process, or a function
-called the "filter function" can be called to act on the output. If
-the process has no buffer and no filter function, its output is
-discarded.
+ `volume'
+ An integer from 0-100, defaulting to `bell-volume'.
-* Menu:
+ `pitch'
+ If using the default X beep, the pitch (Hz) to generate.
-* Process Buffers:: If no filter, output is put in a buffer.
-* Filter Functions:: Filter functions accept output from the process.
-* Accepting Output:: Explicitly permitting subprocess output.
- Waiting for subprocess output.
+ `duration'
+ If using the default X beep, the duration (milliseconds).
-\1f
-File: lispref.info, Node: Process Buffers, Next: Filter Functions, Up: Output from Processes
+ For compatibility, elements of `sound-alist' may also be:
-Process Buffers
----------------
+ * `( sound-name . <sound> )'
- A process can (and usually does) have an "associated buffer", which
-is an ordinary Emacs buffer that is used for two purposes: storing the
-output from the process, and deciding when to kill the process. You
-can also use the buffer to identify a process to operate on, since in
-normal practice only one process is associated with any given buffer.
-Many applications of processes also use the buffer for editing input to
-be sent to the process, but this is not built into XEmacs Lisp.
+ * `( sound-name <volume> <sound> )'
- Unless the process has a filter function (*note Filter Functions::),
-its output is inserted in the associated buffer. The position to insert
-the output is determined by the `process-mark', which is then updated
-to point to the end of the text just inserted. Usually, but not
-always, the `process-mark' is at the end of the buffer.
+ You should probably add things to this list by calling the function
+ `load-sound-file'.
- - Function: process-buffer process
- This function returns the associated buffer of the process PROCESS.
+ Caveats:
- (process-buffer (get-process "shell"))
- => #<buffer *shell*>
+ - You can only play audio data if running on the console screen
+ of a Sun SparcStation, SGI, or HP9000s700.
- - Function: process-mark process
- This function returns the process marker for PROCESS, which is the
- marker that says where to insert output from the process.
+ - The pitch, duration, and volume options are available
+ everywhere, but many X servers ignore the `pitch' option.
- If PROCESS does not have a buffer, `process-mark' returns a marker
- that points nowhere.
+ The following beep-types are used by XEmacs itself:
- Insertion of process output in a buffer uses this marker to decide
- where to insert, and updates it to point after the inserted text.
- That is why successive batches of output are inserted
- consecutively.
+ `auto-save-error'
+ when an auto-save does not succeed
- Filter functions normally should use this marker in the same
- fashion as is done by direct insertion of output in the buffer. A
- good example of a filter function that uses `process-mark' is
- found at the end of the following section.
+ `command-error'
+ when the XEmacs command loop catches an error
- When the user is expected to enter input in the process buffer for
- transmission to the process, the process marker is useful for
- distinguishing the new input from previous output.
+ `undefined-key'
+ when you type a key that is undefined
- - Function: set-process-buffer process buffer
- This function sets the buffer associated with PROCESS to BUFFER.
- If BUFFER is `nil', the process becomes associated with no buffer.
+ `undefined-click'
+ when you use an undefined mouse-click combination
- - Function: get-buffer-process buffer-or-name
- This function returns the process associated with BUFFER-OR-NAME.
- If there are several processes associated with it, then one is
- chosen. (Presently, the one chosen is the one most recently
- created.) It is usually a bad idea to have more than one process
- associated with the same buffer.
+ `no-completion'
+ during completing-read
- (get-buffer-process "*shell*")
- => #<process shell>
+ `y-or-n-p'
+ when you type something other than 'y' or 'n'
- Killing the process's buffer deletes the process, which kills the
- subprocess with a `SIGHUP' signal (*note Signals to Processes::).
+ `yes-or-no-p'
+ when you type something other than 'yes' or 'no'
-\1f
-File: lispref.info, Node: Filter Functions, Next: Accepting Output, Prev: Process Buffers, Up: Output from Processes
-
-Process Filter Functions
-------------------------
-
- A process "filter function" is a function that receives the standard
-output from the associated process. If a process has a filter, then
-_all_ output from that process is passed to the filter. The process
-buffer is used directly for output from the process only when there is
-no filter.
-
- A filter function must accept two arguments: the associated process
-and a string, which is the output. The function is then free to do
-whatever it chooses with the output.
-
- A filter function runs only while XEmacs is waiting (e.g., for
-terminal input, or for time to elapse, or for process output). This
-avoids the timing errors that could result from running filters at
-random places in the middle of other Lisp programs. You may explicitly
-cause Emacs to wait, so that filter functions will run, by calling
-`sit-for' or `sleep-for' (*note Waiting::), or `accept-process-output'
-(*note Accepting Output::). Emacs is also waiting when the command loop
-is reading input.
-
- Quitting is normally inhibited within a filter function--otherwise,
-the effect of typing `C-g' at command level or to quit a user command
-would be unpredictable. If you want to permit quitting inside a filter
-function, bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- If an error happens during execution of a filter function, it is
-caught automatically, so that it doesn't stop the execution of whatever
-program was running when the filter function was started. However, if
-`debug-on-error' is non-`nil', the error-catching is turned off. This
-makes it possible to use the Lisp debugger to debug the filter
-function. *Note Debugger::.
-
- Many filter functions sometimes or always insert the text in the
-process's buffer, mimicking the actions of XEmacs when there is no
-filter. Such filter functions need to use `set-buffer' in order to be
-sure to insert in that buffer. To avoid setting the current buffer
-semipermanently, these filter functions must use `unwind-protect' to
-make sure to restore the previous current buffer. They should also
-update the process marker, and in some cases update the value of point.
-Here is how to do these things:
-
- (defun ordinary-insertion-filter (proc string)
- (let ((old-buffer (current-buffer)))
- (unwind-protect
- (let (moving)
- (set-buffer (process-buffer proc))
- (setq moving (= (point) (process-mark proc)))
- (save-excursion
- ;; Insert the text, moving the process-marker.
- (goto-char (process-mark proc))
- (insert string)
- (set-marker (process-mark proc) (point)))
- (if moving (goto-char (process-mark proc))))
- (set-buffer old-buffer))))
-
-The reason to use an explicit `unwind-protect' rather than letting
-`save-excursion' restore the current buffer is so as to preserve the
-change in point made by `goto-char'.
-
- To make the filter force the process buffer to be visible whenever
-new text arrives, insert the following line just before the
-`unwind-protect':
-
- (display-buffer (process-buffer proc))
-
- To force point to move to the end of the new output no matter where
-it was previously, eliminate the variable `moving' and call `goto-char'
-unconditionally.
-
- In earlier Emacs versions, every filter function that did regexp
-searching or matching had to explicitly save and restore the match data.
-Now Emacs does this automatically; filter functions never need to do it
-explicitly. *Note Match Data::.
-
- A filter function that writes the output into the buffer of the
-process should check whether the buffer is still alive. If it tries to
-insert into a dead buffer, it will get an error. If the buffer is dead,
-`(buffer-name (process-buffer PROCESS))' returns `nil'.
-
- The output to the function may come in chunks of any size. A program
-that produces the same output twice in a row may send it as one batch
-of 200 characters one time, and five batches of 40 characters the next.
-
- - Function: set-process-filter process filter
- This function gives PROCESS the filter function FILTER. If FILTER
- is `nil', then the process will have no filter. If FILTER is `t',
- then no output from the process will be accepted until the filter
- is changed. (Output received during this time is not discarded,
- but is queued, and will be processed as soon as the filter is
- changed.)
-
- - Function: process-filter process
- This function returns the filter function of PROCESS, or `nil' if
- it has none. `t' means that output processing has been stopped.
-
- Here is an example of use of a filter function:
-
- (defun keep-output (process output)
- (setq kept (cons output kept)))
- => keep-output
- (setq kept nil)
- => nil
- (set-process-filter (get-process "shell") 'keep-output)
- => keep-output
- (process-send-string "shell" "ls ~/other\n")
- => nil
- kept
- => ("lewis@slug[8] % "
- "FINAL-W87-SHORT.MSS backup.otl kolstad.mss~
- address.txt backup.psf kolstad.psf
- backup.bib~ david.mss resume-Dec-86.mss~
- backup.err david.psf resume-Dec.psf
- backup.mss dland syllabus.mss
- "
- "#backups.mss# backup.mss~ kolstad.mss
- ")
+ `default'
+ used when nothing else is appropriate.
-\1f
-File: lispref.info, Node: Accepting Output, Prev: Filter Functions, Up: Output from Processes
-
-Accepting Output from Processes
--------------------------------
-
- Output from asynchronous subprocesses normally arrives only while
-XEmacs is waiting for some sort of external event, such as elapsed time
-or terminal input. Occasionally it is useful in a Lisp program to
-explicitly permit output to arrive at a specific point, or even to wait
-until output arrives from a process.
-
- - Function: accept-process-output &optional process seconds millisec
- This function allows XEmacs to read pending output from processes.
- The output is inserted in the associated buffers or given to
- their filter functions. If PROCESS is non-`nil' then this
- function does not return until some output has been received from
- PROCESS.
-
- The arguments SECONDS and MILLISEC let you specify timeout
- periods. The former specifies a period measured in seconds and the
- latter specifies one measured in milliseconds. The two time
- periods thus specified are added together, and
- `accept-process-output' returns after that much time whether or
- not there has been any subprocess output. Note that SECONDS is
- allowed to be a floating-point number; thus, there is no need to
- ever use MILLISEC. (It is retained for compatibility purposes.)
-
- The function `accept-process-output' returns non-`nil' if it did
- get some output, or `nil' if the timeout expired before output
- arrived.
+ Other lisp packages may use other beep types, but these are the
+ ones that the C kernel of XEmacs uses.
-\1f
-File: lispref.info, Node: Sentinels, Next: Process Window Size, Prev: Output from Processes, Up: Processes
-
-Sentinels: Detecting Process Status Changes
-===========================================
-
- A "process sentinel" is a function that is called whenever the
-associated process changes status for any reason, including signals
-(whether sent by XEmacs or caused by the process's own actions) that
-terminate, stop, or continue the process. The process sentinel is also
-called if the process exits. The sentinel receives two arguments: the
-process for which the event occurred, and a string describing the type
-of event.
-
- The string describing the event looks like one of the following:
-
- * `"finished\n"'.
-
- * `"exited abnormally with code EXITCODE\n"'.
-
- * `"NAME-OF-SIGNAL\n"'.
-
- * `"NAME-OF-SIGNAL (core dumped)\n"'.
-
- A sentinel runs only while XEmacs is waiting (e.g., for terminal
-input, or for time to elapse, or for process output). This avoids the
-timing errors that could result from running them at random places in
-the middle of other Lisp programs. A program can wait, so that
-sentinels will run, by calling `sit-for' or `sleep-for' (*note
-Waiting::), or `accept-process-output' (*note Accepting Output::).
-Emacs is also waiting when the command loop is reading input.
-
- Quitting is normally inhibited within a sentinel--otherwise, the
-effect of typing `C-g' at command level or to quit a user command would
-be unpredictable. If you want to permit quitting inside a sentinel,
-bind `inhibit-quit' to `nil'. *Note Quitting::.
-
- A sentinel that writes the output into the buffer of the process
-should check whether the buffer is still alive. If it tries to insert
-into a dead buffer, it will get an error. If the buffer is dead,
-`(buffer-name (process-buffer PROCESS))' returns `nil'.
-
- If an error happens during execution of a sentinel, it is caught
-automatically, so that it doesn't stop the execution of whatever
-programs was running when the sentinel was started. However, if
-`debug-on-error' is non-`nil', the error-catching is turned off. This
-makes it possible to use the Lisp debugger to debug the sentinel.
-*Note Debugger::.
-
- In earlier Emacs versions, every sentinel that did regexp searching
-or matching had to explicitly save and restore the match data. Now
-Emacs does this automatically; sentinels never need to do it explicitly.
-*Note Match Data::.
-
- - Function: set-process-sentinel process sentinel
- This function associates SENTINEL with PROCESS. If SENTINEL is
- `nil', then the process will have no sentinel. The default
- behavior when there is no sentinel is to insert a message in the
- process's buffer when the process status changes.
-
- (defun msg-me (process event)
- (princ
- (format "Process: %s had the event `%s'" process event)))
- (set-process-sentinel (get-process "shell") 'msg-me)
- => msg-me
- (kill-process (get-process "shell"))
- -| Process: #<process shell> had the event `killed'
- => #<process shell>
-
- - Function: process-sentinel process
- This function returns the sentinel of PROCESS, or `nil' if it has
- none.
-
- - Function: waiting-for-user-input-p
- While a sentinel or filter function is running, this function
- returns non-`nil' if XEmacs was waiting for keyboard input from
- the user at the time the sentinel or filter function was called,
- `nil' if it was not.
+ - User Option: bell-volume
+ This variable specifies the default volume for sounds, from 0 to
+ 100.
-\1f
-File: lispref.info, Node: Process Window Size, Next: Transaction Queues, Prev: Sentinels, Up: Processes
+ - Command: load-default-sounds
+ This function loads and installs some sound files as beep-types.
+
+ - Command: load-sound-file filename sound-name &optional volume
+ This function reads in an audio file and adds it to `sound-alist'.
+ The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
+ should be a symbol, specifying the name of the sound. If VOLUME
+ is specified, the sound will be played at that volume; otherwise,
+ the value of BELL-VOLUME will be used.
-Process Window Size
-===================
+ - Function: play-sound sound &optional volume device
+ This function plays sound SOUND, which should be a symbol
+ mentioned in `sound-alist'. If VOLUME is specified, it overrides
+ the value (if any) specified in `sound-alist'. DEVICE specifies
+ the device to play the sound on, and defaults to the selected
+ device.
- - Function: set-process-window-size process height width
- This function tells PROCESS that its logical window size is HEIGHT
- by WIDTH characters. This is principally useful with pty's.
+ - Command: play-sound-file file &optional volume device
+ This function plays the named sound file at volume VOLUME, which
+ defaults to `bell-volume'. DEVICE specifies the device to play
+ the sound on, and defaults to the selected device.
\1f
-File: lispref.info, Node: Transaction Queues, Next: Network, Prev: Process Window Size, Up: Processes
+File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
-Transaction Queues
-==================
+Hash Tables
+***********
- You can use a "transaction queue" for more convenient communication
-with subprocesses using transactions. First use `tq-create' to create
-a transaction queue communicating with a specified process. Then you
-can call `tq-enqueue' to send a transaction.
+ - Function: hash-table-p object
+ This function returns `t' if OBJECT is a hash table, else `nil'.
- - Function: tq-create process
- This function creates and returns a transaction queue
- communicating with PROCESS. The argument PROCESS should be a
- subprocess capable of sending and receiving streams of bytes. It
- may be a child process, or it may be a TCP connection to a server,
- possibly on another machine.
+* Menu:
- - Function: tq-enqueue queue question regexp closure fn
- This function sends a transaction to queue QUEUE. Specifying the
- queue has the effect of specifying the subprocess to talk to.
+* Introduction to Hash Tables:: Hash tables are fast data structures for
+ implementing simple tables (i.e. finite
+ mappings from keys to values).
+* Working With Hash Tables:: Hash table functions.
+* Weak Hash Tables:: Hash tables with special garbage-collection
+ behavior.
- The argument QUESTION is the outgoing message that starts the
- transaction. The argument FN is the function to call when the
- corresponding answer comes back; it is called with two arguments:
- CLOSURE, and the answer received.
+\1f
+File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
+
+Introduction to Hash Tables
+===========================
+
+ A "hash table" is a data structure that provides mappings from
+arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
+called "values". A key/value pair is sometimes called an "entry" in
+the hash table. There are many ways other than hash tables of
+implementing the same sort of mapping, e.g. association lists (*note
+Association Lists::) and property lists (*note Property Lists::), but
+hash tables provide much faster lookup when there are many entries in
+the mapping. Hash tables are an implementation of the abstract data
+type "dictionary", also known as "associative array".
+
+ Internally, hash tables are hashed using the "linear probing" hash
+table implementation method. This method hashes each key to a
+particular spot in the hash table, and then scans forward sequentially
+until a blank entry is found. To look up a key, hash to the appropriate
+spot, then search forward for the key until either a key is found or a
+blank entry stops the search. This method is used in preference to
+double hashing because of changes in recent hardware. The penalty for
+non-sequential access to memory has been increasing, and this
+compensates for the problem of clustering that linear probing entails.
+
+ When hash tables are created, the user may (but is not required to)
+specify initial properties that influence performance.
+
+ Use the `:size' parameter to specify the number of entries that are
+likely to be stored in the hash table, to avoid the overhead of resizing
+the table. But if the pre-allocated space for the entries is never
+used, it is simply wasted and makes XEmacs slower. Excess unused hash
+table entries exact a small continuous performance penalty, since they
+must be scanned at every garbage collection. If the number of entries
+in the hash table is unknown, simply avoid using the `:size' keyword.
+
+ Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
+the algorithm for deciding when to rehash the hash table. For
+temporary hash tables that are going to be very heavily used, use a
+small rehash threshold, for example, 0.4 and a large rehash size, for
+example 2.0. For permanent hash tables that will be infrequently used,
+specify a large rehash threshold, for example 0.8.
+
+ Hash tables can also be created by the lisp reader using structure
+syntax, for example:
+ #s(hash-table size 20 data (foo 1 bar 2))
+
+ The structure syntax accepts the same keywords as `make-hash-table'
+(without the `:' character), as well as the additional keyword `data',
+which specifies the initial hash table contents.
+
+ - Function: make-hash-table &key `test' `size' `rehash-size'
+ `rehash-threshold' `weakness'
+ This function returns a new empty hash table object.
+
+ Keyword `:test' can be `eq', `eql' (default) or `equal'.
+ Comparison between keys is done using this function. If speed is
+ important, consider using `eq'. When storing strings in the hash
+ table, you will likely need to use `equal'.
+
+ Keyword `:size' specifies the number of keys likely to be inserted.
+ This number of entries can be inserted without enlarging the hash
+ table.
+
+ Keyword `:rehash-size' must be a float greater than 1.0, and
+ specifies the factor by which to increase the size of the hash
+ table when enlarging.
+
+ Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
+ and specifies the load factor of the hash table which triggers
+ enlarging.
+
+ Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
+
+ A weak hash table is one whose pointers do not count as GC
+ referents: for any key-value pair in the hash table, if the only
+ remaining pointer to either the key or the value is in a weak hash
+ table, then the pair will be removed from the hash table, and the
+ key and value collected. A non-weak hash table (or any other
+ pointer) would prevent the object from being collected.
+
+ A key-weak hash table is similar to a fully-weak hash table except
+ that a key-value pair will be removed only if the key remains
+ unmarked outside of weak hash tables. The pair will remain in the
+ hash table if the key is pointed to by something other than a weak
+ hash table, even if the value is not.
+
+ A value-weak hash table is similar to a fully-weak hash table
+ except that a key-value pair will be removed only if the value
+ remains unmarked outside of weak hash tables. The pair will
+ remain in the hash table if the value is pointed to by something
+ other than a weak hash table, even if the key is not.
+
+ - Function: copy-hash-table hash-table
+ This function returns a new hash table which contains the same
+ keys and values as HASH-TABLE. The keys and values will not
+ themselves be copied.
+
+ - Function: hash-table-count hash-table
+ This function returns the number of entries in HASH-TABLE.
+
+ - Function: hash-table-test hash-table
+ This function returns the test function of HASH-TABLE. This can
+ be one of `eq', `eql' or `equal'.
+
+ - Function: hash-table-size hash-table
+ This function returns the current number of slots in HASH-TABLE,
+ whether occupied or not.
+
+ - Function: hash-table-rehash-size hash-table
+ This function returns the current rehash size of HASH-TABLE. This
+ is a float greater than 1.0; the factor by which HASH-TABLE is
+ enlarged when the rehash threshold is exceeded.
+
+ - Function: hash-table-rehash-threshold hash-table
+ This function returns the current rehash threshold of HASH-TABLE.
+ This is a float between 0.0 and 1.0; the maximum "load factor" of
+ HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
+
+ - Function: hash-table-weakness hash-table
+ This function returns the weakness of HASH-TABLE. This can be one
+ of `nil', `t', `key' or `value'.
- The argument REGEXP is a regular expression that should match the
- entire answer, but nothing less; that's how `tq-enqueue' determines
- where the answer ends.
+\1f
+File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
- The return value of `tq-enqueue' itself is not meaningful.
+Working With Hash Tables
+========================
- - Function: tq-close queue
- Shut down transaction queue QUEUE, waiting for all pending
- transactions to complete, and then terminate the connection or
- child process.
+ - Function: puthash key value hash-table
+ This function hashes KEY to VALUE in HASH-TABLE.
- Transaction queues are implemented by means of a filter function.
-*Note Filter Functions::.
+ - Function: gethash key hash-table &optional default
+ This function finds the hash value for KEY in HASH-TABLE. If
+ there is no entry for KEY in HASH-TABLE, DEFAULT is returned
+ (which in turn defaults to `nil').
-\1f
-File: lispref.info, Node: Network, Prev: Transaction Queues, Up: Processes
-
-Network Connections
-===================
-
- XEmacs Lisp programs can open TCP network connections to other
-processes on the same machine or other machines. A network connection
-is handled by Lisp much like a subprocess, and is represented by a
-process object. However, the process you are communicating with is not
-a child of the XEmacs process, so you can't kill it or send it signals.
-All you can do is send and receive data. `delete-process' closes the
-connection, but does not kill the process at the other end; that
-process must decide what to do about closure of the connection.
-
- You can distinguish process objects representing network connections
-from those representing subprocesses with the `process-status'
-function. It always returns either `open' or `closed' for a network
-connection, and it never returns either of those values for a real
-subprocess. *Note Process Information::.
-
- - Function: open-network-stream name buffer-or-name host service
- This function opens a TCP connection for a service to a host. It
- returns a process object to represent the connection.
-
- The NAME argument specifies the name for the process object. It
- is modified as necessary to make it unique.
-
- The BUFFER-OR-NAME argument is the buffer to associate with the
- connection. Output from the connection is inserted in the buffer,
- unless you specify a filter function to handle the output. If
- BUFFER-OR-NAME is `nil', it means that the connection is not
- associated with any buffer.
-
- The arguments HOST and SERVICE specify where to connect to; HOST
- is the host name or IP address (a string), and SERVICE is the name
- of a defined network service (a string) or a port number (an
- integer).
+ - Function: remhash key hash-table
+ This function removes the entry for KEY from HASH-TABLE. Does
+ nothing if there is no entry for KEY in HASH-TABLE.
+
+ - Function: clrhash hash-table
+ This function removes all entries from HASH-TABLE, leaving it
+ empty.
+
+ - Function: maphash function hash-table
+ This function maps FUNCTION over entries in HASH-TABLE, calling it
+ with two args, each key and value in the hash table.
+
+ FUNCTION may not modify HASH-TABLE, with the one exception that
+ FUNCTION may remhash or puthash the entry currently being
+ processed by FUNCTION.
projects / chise / xemacs-chise.git / blobdiff