eshell: Input/Output
4 Input/Output
**************
Since Eshell does not communicate with a terminal like most command
shells, IO is a little different.
4.1 Visual Commands
===================
If you try to run programs from within Eshell that are not
line-oriented, such as programs that use ncurses, you will just get
garbage output, since the Eshell buffer is not a terminal emulator.
Eshell solves this problem by running such programs in Emacs’s terminal
emulator.
Programs that need a terminal to display output properly are referred
to in this manual as “visual commands,” because they are not simply
line-oriented. You must tell Eshell which commands are visual, by
adding them to ‘eshell-visual-commands’; for commands that are visual
for only certain _sub_-commands – e.g., ‘git log’ but not ‘git status’ –
use ‘eshell-visual-subcommands’; and for commands that are visual only
when passed certain options, use ‘eshell-visual-options’.
Caution: Some tools such as Git use the pager ‘less’ by default to
paginate their output but call it with its ‘-F’ option. This option
causes ‘less’ to echo the output instead of paginating it if the output
is less than one page long. This causes undesirable behavior if, e.g.,
‘git diff’, is defined as a visual subcommand. It’ll work if the output
is big enough and fail if it is less than one page long. If that occurs
to you, search for configuration options for calling ‘less’ without the
‘-F’ option. For Git, you can do that using ‘git config --global
core.pager 'less -+F'’.
If you want the buffers created by visual programs killed when the
program exits, customize the variable
‘eshell-destroy-buffer-when-process-dies’ to a non-‘nil’ value; the
default is ‘nil’.
4.2 Redirection
===============
Redirection is mostly the same in Eshell as it is in other command
shells. The output redirection operators ‘>’ and ‘>>’ as well as pipes
are supported, but there is not yet any support for input redirection.
Output can also be redirected to buffers, using the ‘>>>’ redirection
operator, and Elisp functions, using virtual devices.
The buffer redirection operator, ‘>>>’, expects a buffer object on
the right-hand side, into which it inserts the output of the left-hand
side. e.g., ‘echo hello >>> #<buffer *scratch*>’ inserts the string
‘"hello"’ into the ‘*scratch*’ buffer. The convenience shorthand
variant ‘#<BUFFER-NAME>’, as in ‘#<*scratch*>’, is also accepted.
‘eshell-virtual-targets’ is a list of mappings of virtual device
names to functions. Eshell comes with two virtual devices: ‘/dev/kill’,
which sends the text to the kill ring, and ‘/dev/clip’, which sends text
to the clipboard.
You can, of course, define your own virtual targets. They are
defined by adding a list of the form ‘("/dev/name" FUNCTION MODE)’ to
‘eshell-virtual-targets’. The first element is the device name;
FUNCTION may be either a lambda or a function name. If MODE is ‘nil’,
then the function is the output function; if it is non-‘nil’, then the
function is passed the redirection mode as a symbol–‘overwrite’ for ‘>’,
‘append’ for ‘>>’, or ‘insert’ for ‘>>>’–and the function is expected to
return the output function.
The output function is called once on each line of output until ‘nil’
is passed, indicating end of output.