File: term.el.html

This file defines a general command-interpreter-in-a-buffer package
(term mode). The idea is that you can build specific process-in-a-buffer
modes on top of term mode -- e.g., Lisp, shell, Scheme, T, soar, .... This way, all these specific packages share a common base functionality, and a common set of bindings, which makes them easier to use (and saves code, implementation time, etc., etc.).

If, instead of term, you call ansi-term, you get multiple term buffers, after every new call ansi-term opens a new
"*ansi-term*<xx>" window, where <xx> is, as usual, a number...

For hints on converting existing process modes (e.g., tex-mode, background, dbx, gdb, kermit, prolog, telnet) to use term-mode instead of shell-mode, see the notes at the end of this file.

Speed considerations and a few caveats
--------------------------------------

While the message passing and the colorization surely introduce some overhead this has became so small that IMHO it is surely outweighed by the benefits you get but, as usual, YMMV.

Important caveat, when deciding the cursor/'gray keys' keycodes I had to make a choice: on my Linux box this choice allows me to run all the ncurses applications without problems but make these keys incomprehensible to all the cursesX programs. Your mileage may vary so you may consider changing the default 'emulation'. Just search for this piece of code and modify it as you like:

;; Which would be better: "\\e[A" or "\\eOA"? readline accepts either.
;; For my configuration it's definitely better \eOA but YMMV. -mm
;; For example: vi works with \eOA while elm wants \e[A ...
(defun term-send-up () (interactive) (term-send-raw-string "\\eOA"))
(defun term-send-down () (interactive) (term-send-raw-string "\\eOB"))
(defun term-send-right () (interactive) (term-send-raw-string "\\eOC"))
(defun term-send-left () (interactive) (term-send-raw-string "\\eOD"))

IMPORTANT: additions & changes
------------------------------

 With this enhanced ansi-term.el you will get a reliable mechanism of
directory/username/host tracking: the only drawback is that you will have to modify your shell start-up script. It's worth it, believe me :).

When you ssh/sudo/su and the account you access has a modified startup script, you will be able to access the remote files as usual with C-x C-f, if it's needed you will have to enter a password, otherwise the file should get loaded straight away.

This is useful even if you work only on one host: it often happens that, for maintenance reasons, you have to edit files 'as root': before patching term.el, I su-ed in a term.el buffer and used vi :), now I simply do a C-x C-f and, via ange-ftp, the file is automatically loaded
'as-root'. (If you don't want to enter the root password every time you
can put it in your .netrc: note that this is -not- advisable if you're connected to the internet or if somebody else works on your workstation!)

If you use wu-ftpd you can use some of its features to avoid root ftp access to the rest of the world: just put in /etc/ftphosts something like

# Local access
allow root 127.0.0.1

# By default nobody can't do anything
deny root *

            ----------------------------------------

 With the variable term-buffer-maximum-size you can decide how many
scrollback lines to keep: its default is 8192.

            ----------------------------------------

 ANSI colorization should work well. Blink, is not supported.
 Currently it's mapped as bold.

            ----------------------------------------

 TODO:

 - Add hooks to allow raw-mode keys to be configurable
 - Which keys are better ? \eOA or \e[A ?

 ----------------------------------------------------------------
 You should/could have something like this in your .emacs to take
 full advantage of this package

 (add-hook 'term-mode-hook
           (lambda ()
             (setq term-prompt-regexp "^[^#$%>\\n]*[#$%>] *")
             (setq-local mouse-yank-at-point t)
             (setq-local transient-mark-mode nil)
             (auto-fill-mode -1)
             (setq tab-width 8)))

            ----------------------------------------

 If you want to use color ls the best setup is to have a different file
when you use eterm ( see above, mine is named .emacs_dircolors ). This is necessary because some terminals, rxvt for example, need non-ansi hacks to work ( for example on my rxvt white is wired to fg, and to obtain normal white I have to do bold-white :)

            ----------------------------------------

 # Configuration file for the color ls utility
 # This file goes in the /etc directory, and must be world readable.
 # You can copy this file to .dir_colors in your $HOME directory to
 # override the system defaults.

 # COLOR needs one of these arguments: 'tty' colorizes output to ttys, but
 # not pipes. 'all' adds color characters to all output. 'none' shuts
 # colorization off.
 COLOR tty
 OPTIONS -F

 # Below, there should be one TERM entry for each termtype that is
 # colorizable
 TERM eterm

 # EIGHTBIT, followed by '1' for on, '0' for off. (8-bit output)
 EIGHTBIT 1

 # Below are the color init strings for the basic file types. A color init
 # string consists of one or more of the following numeric codes:
 # Attribute codes:
 # 00=none 01=bold 04=underscore 05=blink 07=reverse 08=concealed
 # Text color codes:
 # 30=black 31=red 32=green 33=yellow 34=blue 35=magenta 36=cyan 37=white
 # Background color codes:
 # 40=black 41=red 42=green 43=yellow 44=blue 45=magenta 46=cyan 47=white
 NORMAL 00 # global default, although everything should be something.
 FILE 00 # normal file
 DIR 00;37 # directory
 LINK 00;36 # symbolic link
 FIFO 00;37 # pipe
 SOCK 40;35 # socket
 BLK 33;01 # block device driver
 CHR 33;01 # character device driver

 # This is for files with execute permission:
 EXEC 00;32

 # List any file extensions like '.gz' or '.tar' that you would like ls
 # to colorize below. Put the extension, a space, and the color init
 # string. (and any comments you want to add after a '#')
 .tar 01;33 # archives or compressed
 .tgz 01;33
 .arj 01;33
 .taz 01;33
 .lzh 01;33
 .zip 01;33
 .z 01;33
 .Z 01;33
 .gz 01;33
 .jpg 01;35 # image formats
 .gif 01;35
 .bmp 01;35
 .xbm 01;35
 .xpm 01;35

            ----------------------------------------

There are actually two methods for directory tracking, one implemented in term-command-hook(var)/term-command-hook(fun) which sets the directory according to an escape sequence of the form "\\032/<directory>\\n". Some shells like bash will already send this escape sequence when they detect they are running in Emacs. This can be configured or disabled on the Emacs side by setting term-command-hook(var)/term-command-hook(fun) to a different function.

The second method is in term-handle-ansi-terminal-messages which sets user, host, and directory according to escape sequences of the form "\\033AnSiTc <directory>\\n" (replace the "c" with "u" and "h" for user and host, respectively). If the user and host don't match, it will set directory to a remote one, so it is important to set user and host correctly first. See the example bash configuration below.

            ----------------------------------------

# Set HOSTNAME if not already set.
: ${HOSTNAME=$(uname -n)}

# su does not change this but I'd like it to
USER=$(whoami)

# ...

case $TERM in
    eterm*)

printf '%s\n' \
-------------------------------------------------------------- \
"Hello $USER" \
"Today is $(date)" \
"We are on $HOSTNAME running $(uname) under Emacs term mode" \
--------------------------------------------------------------

# The \033 stands for ESC.
# There is a space between "AnSiT?" and $whatever.
printf '\033AnSiTh %s\n' "$HOSTNAME"
printf '\033AnSiTu %s\n' "$USER"
printf '\033AnSiTc %s\n' "$PWD"

cd() { command cd "$@" && printf '\033AnSiTc %s\n' "$PWD"; }
pushd() { command pushd "$@" && printf '\033AnSiTc %s\n' "$PWD"; }
popd() { command popd "$@" && printf '\033AnSiTc %s\n' "$PWD"; }

# Use custom dircolors in term buffers.
# eval $(dircolors $HOME/.emacs_dircolors)
esac

# ...

For troubleshooting in Bash, you can check the definition of the custom functions with the "type" command. e.g. "type cd". If you do not see the expected definition from the config below, then the directory tracking will not work.


Brief Command Documentation:
============================================================================
Term Mode Commands: (common to all derived modes, like cmushell & cmulisp mode)

M-p term-previous-input Cycle backwards in input history
M-n term-next-input Cycle forwards
M-r term-previous-matching-input Previous input matching a regexp
M-s term-next-matching-input Next input that matches
return term-send-input
C-c C-a term-bol Beginning of line; skip prompt.
C-d term-delchar-or-maybe-eof Delete char unless at end of buff.
C-c C-u term-kill-input ^u
C-c C-w backward-kill-word ^w
C-c C-c term-interrupt-subjob ^c
C-c C-z term-stop-subjob ^z
C-c C-\ term-quit-subjob ^\
C-c C-o term-kill-output Delete last batch of process output
C-c C-r term-show-output Show last batch of process output
C-c C-h term-dynamic-list-input-ring List input history

Not bound by default in term-mode
term-send-invisible Read a line without echo, and send to proc
(These are bound in shell-mode)
term-dynamic-complete Complete filename at point.
term-dynamic-list-completions List completions in help buffer.
term-replace-by-expanded-filename Expand and complete filename at point;
replace with expanded/completed name.
term-kill-subjob No mercy.
term-show-maximum-output Show as much output as possible.
term-continue-subjob Send CONT signal to buffer's process
group. Useful if you accidentally
suspend your process (with C-c C-z).

term-mode-hook is the term mode hook. Basically for your keybindings. term-load-hook is run after loading in this package.

Defined variables (68)

Defined functions (143)

Defined faces (23)