X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/563a450c01499bf444e5c8fc5f314abb1b0325fa..8e554df009bc64b4e5e75028f36c397ba78596b4:/doc/misc/eshell.texi diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index e9772e7ea8..d52f3d9274 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -2,13 +2,15 @@ @c %**start of header @setfilename ../../info/eshell @settitle Eshell: The Emacs Shell +@defindex cm @synindex vr fn +@documentencoding UTF-8 @c %**end of header @copying This manual is for Eshell, the Emacs shell. -Copyright @copyright{} 1999--2012 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2014 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -32,9 +34,9 @@ modify this GNU manual.'' @sp 4 @c The title is printed in a large font. @center @titlefont{User's Guide} -@sp +@sp 1 @center @titlefont{to} -@sp +@sp 1 @center @titlefont{Eshell: The Emacs Shell} @ignore @sp 2 @@ -42,7 +44,7 @@ modify this GNU manual.'' @c -release- @end ignore @sp 3 -@center John Wiegley +@center John Wiegley & Aidan Gauland @c -date- @page @@ -60,35 +62,34 @@ modify this GNU manual.'' @node Top @top Eshell -Eshell is a shell-like command interpreter -implemented in Emacs Lisp. It invokes no external processes except for -those requested by the user. It is intended to be a functional -replacement for command shells such as @command{bash}, @command{zsh}, -@command{rc}, or @command{4dos}; since Emacs itself is capable of -handling the sort of tasks accomplished by those tools. +Eshell is a shell-like command interpreter implemented in Emacs Lisp. +It invokes no external processes except for those requested by the +user. It is intended to be an alternative to the IELM (@pxref{Lisp Interaction, Emacs Lisp Interaction, , emacs, The Emacs Editor}) +REPL for Emacs @emph{and} with an interface similar to command shells +such as @command{bash}, @command{zsh}, @command{rc}, or +@command{4dos}. @c This manual is updated to release 2.4 of Eshell. @insertcopying @end ifnottex @menu -* What is Eshell?:: A brief introduction to the Emacs Shell. -* Command basics:: The basics of command usage. +* Introduction:: A brief introduction to the Emacs Shell. * Commands:: -* Arguments:: +* Expansion:: * Input/Output:: -* Process control:: * Extension modules:: -* Extras and Goodies:: * Bugs and ideas:: Known problems, and future ideas. * GNU Free Documentation License:: The license for this documentation. * Concept Index:: * Function and Variable Index:: +* Command Index:: * Key Index:: @end menu -@node What is Eshell? -@chapter What is Eshell? +@node Introduction +@chapter Introduction +@section What is Eshell? @cindex what is Eshell? @cindex Eshell, what it is @@ -139,6 +140,24 @@ Any tool you use often deserves the time spent learning to master it. looks like: But don't let it fool you; once you know what's going on, it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.} +@section What Eshell is not +@cindex Eshell, what it is not +@cindex what Eshell is not +@cindex what isn't Eshell? + +Eshell is @emph{not} a replacement for system shells such as +@command{bash} or @command{zsh}. Use Eshell when you want to move +text between Emacs and external processes; if you only want to pipe +output from one external process to another (and then another, and so +on), use a system shell, because Emacs's IO system is buffer oriented, +not stream oriented, and is very inefficient at such tasks. If you +want to write shell scripts in Eshell, don't; either write an elisp +library or use a system shell. + +Some things Eshell just doesn't do well. It fills the niche between +IELM and your system shell, where the peculiar use-cases lie, and it +is less than ideal outside that niche. + @menu * Contributors to Eshell:: People who have helped out! @end menu @@ -158,167 +177,227 @@ The following persons have made contributions to Eshell. @item Eli Zaretskii made it possible for Eshell to run without requiring asynchronous subprocess support. This is important for MS-DOS, which -does not have such support.@refill +does not have such support. @item -Miles Bader contributed many fixes during the port to Emacs 21.@refill +Miles Bader contributed many fixes during the port to Emacs 21. @item Stefan Monnier fixed the things which bothered him, which of course made -things better for all.@refill +things better for all. @item Gerd Moellmann also helped to contribute bug fixes during the initial -integration with Emacs 21.@refill +integration with Emacs 21. @item Alex Schroeder contributed code for interactively querying the user -before overwriting files.@refill +before overwriting files. @item -Sudish Joseph helped with some XEmacs compatibility issues.@refill +Sudish Joseph helped with some XEmacs compatibility issues. @end itemize Apart from these, a lot of people have sent suggestions, ideas, requests, bug reports and encouragement. Thanks a lot! Without you there would be no new releases of Eshell. -@node Command basics -@chapter Basic overview +@node Commands +@chapter Commands -A command shell is a means of entering verbally-formed commands. This -is really all that it does, and every feature described in this manual -is a means to that end. Therefore, it's important to take firm hold on -exactly what a command is, and how it fits in the overall picture of -things. +In a command shell, everything is done by invoking commands. This +chapter covers command invocations in Eshell, including the command +history and invoking commands in a script file. @menu -* Commands verbs:: Commands always begin with a verb. -* Command arguments:: Some verbs require arguments. +* Invocation:: +* Arguments:: +* Built-ins:: +* Variables:: +* Aliases:: +* History:: +* Completion:: +* for loop:: +* Scripts:: @end menu -@node Commands verbs -@section Commands verbs - -Commands are expressed using @dfn{script}, a special shorthand language -computers can understand with no trouble. Script is an extremely simple -language; oddly enough, this is what makes it look so complicated! -Whereas normal languages use a variety of embellishments, the form of a -script command is always: - -@example -@var{verb} [@var{arguments}] -@end example +@node Invocation +@section Invocation +Unlike regular system shells, Eshell never invokes kernel functions +directly, such as @code{exec(3)}. Instead, it uses the Lisp functions +available in the Emacs Lisp library. It does this by transforming the +input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}} + +The command can be either an Elisp function or an external command. +Eshell looks first for an @ref{Aliases, alias} with the same name as the +command, then a @ref{Built-ins, built-in command} or a function with the +same name; if there is no match, it then tries to execute it as an +external command. + +The semicolon (@code{;}) can be used to separate multiple command +invocations on a single line. A command invocation followed by an +ampersand (@code{&}) will be run in the background. Eshell has no job +control, so you can not suspend or background the current process, or +bring a background process into the foreground. That said, background +processes invoked from Eshell can be controlled the same way as any +other background process in Emacs. -The verb expresses what you want your computer to do. There are a fixed -number of verbs, although this number is usually quite large. On the -author's computer, it reaches almost 1400 in number. But of course, -only a handful of these are really necessary. +@node Arguments +@section Arguments +Command arguments are passed to the functions as either strings or +numbers, depending on what the parser thinks they look like. If you +need to use a function that takes some other data type, you will need to +call it in an Elisp expression (which can also be used with +@ref{Expansion, expansions}). As with other shells, you can +escape special characters and spaces with the backslash (@code{\}) and +the single (@code{''}) and double (@code{""}) quotes. -Sometimes, the verb is all that's written. A verb is always a single -word, usually related to the task it performs. @command{reboot} is a -good example. Entering that on GNU/Linux will reboot the -computer---assuming you have sufficient privileges. +@node Built-ins -Other verbs require more information. These are usually very capable -verbs, and must be told specifically what to do. The extra information -is given in the form of @dfn{arguments}. For example, the -@command{echo} verb prints back whatever arguments you type. It -requires these arguments to know what to echo. A proper use of -@command{echo} looks like this: +@section Built-in commands +Several commands are built-in in Eshell. In order to call the +external variant of a built-in command @code{foo}, you could call +@code{*foo}. Usually, this should not be necessary. You can check +what will be applied by the @code{which} command: @example -echo This is an example of using echo! +~ $ which ls +eshell/ls is a compiled Lisp function in `em-ls.el' +~ $ which *ls +/bin/ls @end example -This script command causes the computer to echo back: ``This is an -example of using echo!'' - -Although command verbs are always simple words, like @command{reboot} or -@command{echo}, arguments may have a wide variety of forms. There are -textual arguments, numerical arguments---even Lisp arguments. -Distinguishing these different types of arguments requires special -typing, for the computer to know exactly what you mean. - -@node Command arguments -@section Command arguments - -Eshell recognizes several different kinds of command arguments: - -@enumerate -@item Strings (also called textual arguments) -@item Numbers (floating point or integer) -@item Lisp lists -@item Lisp symbols -@item Emacs buffers -@item Emacs process handles -@end enumerate - -Most users need to worry only about the first two. The third, Lisp lists, -occur very frequently, but almost always behind the scenes. - -Strings are the most common type of argument, and consist of nearly any -character. Special characters---those used by Eshell -specifically---must be preceded by a backslash (@samp{\}). When in doubt, it -is safe to add backslashes anywhere and everywhere. - -Here is a more complicated @command{echo} example: +If you want to discard a given built-in command, you could declare an +alias, @ref{Aliases}. Example: @example -echo A\ Multi-word\ Argument\ With\ A\ \$\ dollar +~ $ which sudo +eshell/sudo is a compiled Lisp function in `em-unix.el' +~ $ alias sudo '*sudo $*' +~ $ which sudo +sudo is an alias, defined as "*sudo $*" @end example -Beyond this, things get a bit more complicated. While not beyond the -reach of someone wishing to learn, it is definitely beyond the scope of -this manual to present it all in a simplistic manner. Get comfortable -with Eshell as a basic command invocation tool, and learn more about the -commands on your system; then come back when it all sits more familiarly -on your mind. Have fun! +@vindex eshell-prefer-lisp-functions +If you would prefer to use the built-in commands instead of the external +commands, set @code{eshell-prefer-lisp-functions} to @code{t}. -@node Commands -@chapter Commands +Some of the built-in commands have different behavior from their +external counterparts, and some have no external counterpart. Most of +these will print a usage message when given the @code{--help} option. -@menu -* Invocation:: -* Completion:: -* Aliases:: -* History:: -* Scripts:: -* Built-ins:: -@end menu +@table @code -Essentially, a command shell is all about invoking commands---and -everything that entails. So understanding how Eshell invokes commands -is the key to comprehending how it all works. +@item addpath +@cmindex addpath +Adds a given path or set of paths to the PATH environment variable, or, +with no arguments, prints the current paths in this variable. + +@item alias +@cmindex alias +Define an alias (@pxref{Aliases}). This does not add it to the aliases +file. + +@item date +@cmindex date +Similar to, but slightly different from, the GNU Coreutils +@command{date} command. + +@item define +@cmindex define +Define a varalias. +@xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}. + +@item diff +@cmindex diff +Use Emacs's internal @code{diff} (not to be confused with +@code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs Manual}. + +@item grep +@cmindex grep +@itemx agrep +@cmindex agrep +@itemx egrep +@cmindex egrep +@itemx fgrep +@cmindex fgrep +@itemx glimpse +@cmindex glimpse +The @command{grep} commands are compatible with GNU @command{grep}, but +use Emacs's internal @code{grep} instead. + +@item info +@cmindex info +Same as the external @command{info} command, but uses Emacs's internal +Info reader. + +@item jobs +@cmindex jobs +List subprocesses of the Emacs process, if any, using the function +@code{list-processes}. + +@item kill +@cmindex kill +Kill processes. Takes a PID or a process object and an optional +signal specifier. + +@item listify +@cmindex listify +Eshell version of @code{list}. Allows you to create a list using Eshell +syntax, rather than Elisp syntax. For example, @samp{listify foo bar} +and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}. + +@item locate +@cmindex locate +Alias to Emacs's @code{locate} function, which simply runs the external +@command{locate} command and parses the results. +@xref{Dired and Find, , , emacs, The GNU Emacs Manual}. + +@item make +@cmindex make +Run @command{make} through @code{compile}. +@xref{Compilation, , , emacs, The GNU Emacs Manual}. + +@item occur +@cmindex occur +Alias to Emacs's @code{occur}. +@xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}. + +@item printnl +@cmindex printnl +Print the arguments separated by newlines. -@node Invocation -@section Invocation +@item cd +@cmindex cd +This command changes the current working directory. Usually, it is +invoked as @samp{cd foo} where @file{foo} is the new working directory. +But @command{cd} knows about a few special arguments: -Unlike regular system shells, Eshell never invokes kernel functions -directly, such as @code{exec(3)}. Instead, it uses the Lisp functions -available in the Emacs Lisp library. It does this by transforming the -command you specify into a callable Lisp form.@footnote{To see the Lisp -form that will be invoked, type: @samp{eshell-parse-command "echo -hello"}} +When it receives no argument at all, it changes to the home directory. -This transformation, from the string of text typed at the command -prompt, to the ultimate invocation of either a Lisp function or external -command, follows these steps: +Giving the command @samp{cd -} changes back to the previous working +directory (this is the same as @samp{cd $-}). -@enumerate -@item Parse the command string into separate arguments. -@item -@end enumerate +The command @samp{cd =} shows the directory stack. Each line is +numbered. -@node Completion -@section Completion +With @samp{cd =foo}, Eshell searches the directory stack for a directory +matching the regular expression @samp{foo} and changes to that +directory. -@node Aliases -@section Aliases +With @samp{cd -42}, you can access the directory stack by number. -@node History -@section History +@item su +@cmindex su +@itemx sudo +@cmindex sudo +Uses TRAMP's @command{su} or @command{sudo} method @pxref{Inline methods, , , tramp} +to run a command via @command{su} or @command{sudo}. These commands +are in the eshell-tramp module, which is disabled by default. + +@end table +@subsection Built-in variables Eshell knows a few built-in variables: @table @code @@ -348,62 +427,28 @@ Lisp functions, based on successful completion). @end table -@node Scripts -@section Scripts - - -@node Built-ins -@section Built-in commands - -Several commands are built-in in Eshell. In order to call the -external variant of a built-in command @code{foo}, you could call -@code{*foo}. Usually, this should not be necessary. You can check -what will be applied by the @code{which} command: - -@example -~ $ which ls -eshell/ls is a compiled Lisp function in `em-ls.el' -~ $ which *ls -/bin/ls -@end example - -If you want to discard a given built-in command, you could declare an -alias, @ref{Aliases}. Eample: - -@example -~ $ which sudo -eshell/sudo is a compiled Lisp function in `em-unix.el' -~ $ alias sudo '*sudo $*' -~ $ which sudo -sudo is an alias, defined as "*sudo $*" -@end example - -Some of the built-in commands have a special behavior in Eshell: - -@table @code - -@item cd -@findex cd -This command changes the current working directory. Usually, it is -invoked as @samp{cd foo} where @file{foo} is the new working -directory. But @code{cd} knows about a few special arguments: - -When it receives no argument at all, it changes to the home directory. - -Giving the command @samp{cd -} changes back to the previous working -directory (this is the same as @samp{cd $-}). - -The command @samp{cd =} shows the directory stack. Each line is -numbered. +@node Variables +@section Variables +Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it +does not have its own scope, and simply stores variables the same you +would in an Elisp program. Eshell provides a command version of +@code{setq} for convenience. -With @samp{cd =foo}, Eshell searches the directory stack for a -directory matching the regular expression @samp{foo} and changes to -that directory. +@node Aliases +@section Aliases -With @samp{cd -42}, you can access the directory stack by number. +Aliases are commands that expand to a longer input line. For example, +@command{ll} is a common alias for @code{ls -l}, and would be defined +with the command invocation @samp{alias ll ls -l}; with this defined, +running @samp{ll foo} in Eshell will actually run @samp{ls -l foo}. +Aliases defined (or deleted) by the @command{alias} command are +automatically written to the file named by @code{eshell-aliases-file}, +which you can also edit directly (although you will have to manually +reload it). -@item history -@findex history +@node History +@section History +@cmindex history The @samp{history} command shows all commands kept in the history ring as numbered list. If the history ring contains @code{eshell-history-size} commands, those numbers change after every @@ -419,70 +464,249 @@ of the history ring. argument of the last command beginning with @code{foo} is accessible by @code{!foo:n}. -@item su -@findex su -@itemx sudo -@findex sudo -@code{su} and @code{sudo} work as expected: they apply the following -commands (@code{su}), or the command being an argument (@code{sudo}) -under the permissions of somebody else. - -This does not work only on -the local host, but even on a remote one, when -@code{default-directory} is a remote file name. The necessary -proxy configuration of Tramp is performed -@ifinfo -automatically, @ref{Multi-hops, , , tramp}. -@end ifinfo -@ifnotinfo -automatically. -@end ifnotinfo -Example: +The history ring is loaded from a file at the start of every session, +and written back to the file at the end of every session. The file path +is specified in @code{eshell-history-file-name}. Unlike other shells, +such as Bash, Eshell can not be configured to keep a history ring of a +different size than that of the history file. + +Since the default buffer navigation and searching key-bindings are +still present in the Eshell buffer, the commands for history +navigation and searching are bound to different keys: + +@table @kbd +@item M-r +@itemx M-s +History I-search. + +@item M-p +@itemx M-n +Previous and next history line. If there is anything on the input +line when you run these commands, they will instead jump to the +precious or next line that begins with that string. +@end table + +@node Completion +@section Completion +Eshell uses the pcomplete package for programmable completion, similar +to that of other command shells. Argument completion differs depending +on the preceding command: for example, possible completions for +@command{rmdir} are only directories, while @command{rm} completions can +be directories @emph{and} files. Eshell provides predefined completions +for the built-in functions and some common external commands, and you +can define your own for any command. + +Eshell completion also works for lisp forms and glob patterns. If the +point is on a lisp form, then @key{TAB} will behave similarly to completion +in @code{elisp-mode} and @code{lisp-interaction-mode}. For glob +patterns, If there are few enough possible completions of the patterns, +they will be cycled when @key{TAB} is pressed, otherwise it will be removed +from the input line and the possible completions will be listed. + +If you want to see the entire list of possible completions when it's +below the cycling threshold, press @kbd{M-?}. + +@subsection pcomplete +Pcomplete, short for programmable completion, is the completion +library originally written for Eshell, but usable for command +completion@footnote{Command completion as opposed to code completion, +which is a beyond the scope of pcomplete.} in other modes. + +Completions are defined as functions (with @code{defun}) named +@code{pcomplete/COMMAND}, where @code{COMMAND} is the name of the +command for which this function provides completions; you can also name +the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions +for a specific major mode. + +@node for loop +@section @code{for} loop +Because Eshell commands can not (easily) be combined with lisp forms, +Eshell provides a command-oriented @command{for}-loop for convenience. +The syntax is as follows: @example -~ $ cd /ssh:otherhost:/etc -/ssh:user@@otherhost:/etc $ sudo find-file shadow +@code{for VAR in TOKENS @{ command invocation(s) @}} @end example -@end table - +where @samp{TOKENS} is a space-separated sequence of values of +@var{VAR} for each iteration. This can even be the output of a +command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}. -@node Arguments -@chapter Arguments +@node Scripts +@section Scripts +@cmindex source +@fnindex eshell-source-file +You can run Eshell scripts much like scripts for other shells; the main +difference is that since Eshell is not a system command, you have to run +it from within Emacs. An Eshell script is simply a file containing a +sequence of commands, as with almost any other shell script. Scripts +are invoked from Eshell with @command{source}, or from anywhere in Emacs +with @code{eshell-source-file}. + +@cmindex . +If you wish to load a script into your @emph{current} environment, +rather than in a subshell, use the @code{.} command. + +@node Expansion +@chapter Expansion +Expansion in a command shell is somewhat like macro expansion in macro +parsers (such as @command{cpp} and @command{m4}), but in a command +shell, they are less often used for constants, and usually for using +variables and string manipulation.@footnote{Eshell has no +string-manipulation expansions because the Elisp library already +provides many functions for this.} For example, @code{$var} on a line +expands to the value of the variable @code{var} when the line is +executed. Expansions are usually passed as arguments, but may also be +used as commands.@footnote{E.g., entering just @samp{$var} at the prompt +is equivalent to entering the value of @code{var} at the prompt.} @menu -* The Parser:: -* Variables:: -* Substitution:: +* Dollars Expansion:: * Globbing:: -* Predicates:: @end menu -@node The Parser -@section The Parser +@node Dollars Expansion +@section Dollars Expansion +Eshell has different @code{$} expansion syntax from other shells. There +are some similarities, but don't let these lull you into a false sense +of familiarity. -@node Variables -@section Variables +@table @code -@node Substitution -@section Substitution +@item $var +Expands to the value bound to @code{var}. This is the main way to use +variables in command invocations. -@node Globbing -@section Globbing +@item $#var +Expands to the length of the value bound to @code{var}. Raises an error +if the value is not a sequence +(@pxref{Sequences Arrays Vectors, Sequences, , elisp, The Emacs Lisp Reference Manual}). -@node Predicates -@section Predicates +@item $(lisp) +Expands to the result of evaluating the S-expression @code{(lisp)}. On +its own, this is identical to just @code{(lisp)}, but with the @code{$}, +it can be used in a string, such as @samp{/some/path/$(lisp).txt}. +@item $@{command@} +Returns the output of @command{command}, which can be any valid Eshell +command invocation, and may even contain expansions. -@node Input/Output -@chapter Input/Output +@item $var[i] +Expands to the @code{i}th element of the value bound to @code{var}. If +the value is a string, it will be split at whitespace to make it a list. +Again, raises an error if the value is not a sequence. + +@item $var[: i] +As above, but now splitting occurs at the colon character. + +@item $var[: i j] +As above, but instead of returning just a string, it now returns a list +of two strings. If the result is being interpolated into a larger +string, this list will be flattened into one big string, with each +element separated by a space. + +@item $var["\\\\" i] +Separate on backslash characters. Actually, the first argument -- if it +doesn't have the form of a number, or a plain variable name -- can be +any regular expression. So to split on numbers, use @samp{$var["[0-9]+" 10 20]}. -@node Process control -@chapter Process control +@item $var[hello] +Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be +an alist (@pxref{Association List Type, Association Lists, , elisp, +The Emacs Lisp Reference Manual}). +@item $#var[hello] +Returns the length of the cdr of the element of @code{var} who car is equal +to @code{"hello"}. + +@end table + +@node Globbing +@section Globbing +Eshell's globbing syntax is very similar to that of Zsh. Users coming +from Bash can still use Bash-style globbing, as there are no +incompatibilities. Most globbing is pattern-based expansion, but there +is also predicate-based expansion. See +@ref{Filename Generation, , , zsh, The Z Shell Manual} +for full syntax. To customize the syntax and behavior of globbing in +Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, +The GNU Emacs Manual}.} +groups ``eshell-glob'' and ``eshell-pred''. + +@node Input/Output +@chapter Input/Output +Since Eshell does not communicate with a terminal like most command +shells, IO is a little different. + +@section 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 @code{eshell-visual-commands}; for commands that are +visual for only certain @emph{sub}-commands -- e.g. @samp{git log} but +not @samp{git status} -- use @code{eshell-visual-subcommands}; and for +commands that are visual only when passed certain options, use +@code{eshell-visual-options}. + +@section Redirection +Redirection is mostly the same in Eshell as it is in other command +shells. The output redirection operators @code{>} and @code{>>} 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 @code{>>>} redirection operator, and Elisp functions, using +virtual devices. + +The buffer redirection operator, @code{>>>}, expects a buffer object +on the right-hand side, into which it inserts the output of the +left-hand side. e.g., @samp{echo hello >>> #} +inserts the string @code{"hello"} into the @file{*scratch*} buffer. + +@code{eshell-virtual-targets} is a list of mappings of virtual device +names to functions. Eshell comes with two virtual devices: +@file{/dev/kill}, which sends the text to the kill ring, and +@file{/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 @samp{("/dev/name" @var{function} @var{mode})} to +@code{eshell-virtual-targets}. The first element is the device name; +@var{function} may be either a lambda or a function name. If +@var{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--@code{overwrite} for @code{>}, @code{append} for @code{>>}, or +@code{insert} for @code{>>>}--and the function is expected to return +the output function. + +The output function is called once on each line of output until +@code{nil} is passed, indicating end of output. @node Extension modules @chapter Extension modules +Eshell provides a facility for defining extension modules so that they +can be disabled and enabled without having to unload and reload them, +and to provide a common parent Customize group for the +modules.@footnote{ERC provides a similar module facility.} An Eshell +module is defined the same as any other library but one requirement: the +module must define a Customize@footnote{@xref{Customization, , , +elisp, The Emacs Lisp Reference Manual}.} +group using @code{eshell-defgroup} (in place of @code{defgroup}) with +@code{eshell-module} as the parent group.@footnote{If the module has +no user-customizable options, then there is no need to define it as an +Eshell module.} You also need to load the following as shown: + +@example +(eval-when-compile + (require 'cl-lib) + (require 'esh-mode) + (require 'eshell)) + +(require 'esh-util) +@end example @menu * Writing a module:: @@ -491,7 +715,6 @@ Example: * Key rebinding:: * Smart scrolling:: * Terminal emulation:: -* Built-in UNIX commands:: @end menu @node Writing a module @@ -512,13 +735,6 @@ Example: @node Terminal emulation @section Terminal emulation -@node Built-in UNIX commands -@section Built-in UNIX commands - - -@node Extras and Goodies -@chapter Extras and Goodies - @node Bugs and ideas @chapter Bugs and ideas @cindex reporting bugs and ideas @@ -527,26 +743,21 @@ Example: @cindex email to the author @cindex FAQ @cindex problems, list of common +@cindex known bugs +@cindex bugs, known -If you find a bug or misfeature, don't hesitate to let me know! Send -email to @email{johnw@@gnu.org}. Feature requests should also be sent -there. I prefer discussing one thing at a time. If you find several +If you find a bug or misfeature, don't hesitate to report it, by +using @kbd{M-x report-emacs-bug}. The same applies to feature requests. +It is best to discuss one thing at a time. If you find several unrelated bugs, please report them separately. +@ignore If you have ideas for improvements, or if you have written some extensions to this package, I would like to hear from you. I hope you find this package useful! +@end ignore -@menu -* Known problems:: -@end menu - -@node Known problems -@section Known problems -@cindex known bugs -@cindex bugs, known - -Below is complete list of known problems with Eshell version 2.4.2, +Below is a list of some known problems with Eshell version 2.4.2, which is the version included with Emacs 22. @table @asis @@ -554,7 +765,7 @@ which is the version included with Emacs 22. @item Differentiate between aliases and functions -Allow for a bash-compatible syntax, such as: +Allow for a Bash-compatible syntax, such as: @example alias arg=blah @@ -838,7 +1049,7 @@ them; @code{min} would display the smallest figure, etc. It would provide syntax, abbrev, highlighting and indenting support like @code{emacs-lisp-mode} and @code{shell-mode}. -@item In the history mechanism, finish the @command{bash}-style support +@item In the history mechanism, finish the Bash-style support This means @samp{!n}, @samp{!#}, @samp{!:%}, and @samp{!:1-} as separate from @samp{!:1*}. @@ -904,7 +1115,7 @@ it). @item Make the shell spawning commands be visual That is, make (@command{su}, @command{bash}, @command{telnet}, -@command{rlogin}, @command{rsh}, etc.) be part of +@command{rlogin}, @command{rsh}, etc.)@: be part of @code{eshell-visual-commands}. The only exception is if the shell is being used to invoke a single command. Then, the behavior should be based on what that command is. @@ -1008,6 +1219,11 @@ Since it keeps the cursor up where the command was invoked. @printindex fn +@node Command Index +@unnumbered Command Index + +@printindex cm + @node Key Index @unnumbered Key Index