diff options
Diffstat (limited to 'doc/misc/eshell.texi')
| -rw-r--r-- | doc/misc/eshell.texi | 144 |
1 files changed, 101 insertions, 43 deletions
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 1789cded9d3..4e2bddf42af 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -418,9 +418,9 @@ alias (@pxref{Aliases}). Example: @example ~ $ which sudo eshell/sudo is a compiled Lisp function in `em-tramp.el'. -~ $ alias sudo '*sudo $*' +~ $ alias sudo '*sudo $@@*' ~ $ which sudo -sudo is an alias, defined as "*sudo $*" +sudo is an alias, defined as "*sudo $@@*" @end example Some of the built-in commands have different behavior from their @@ -540,7 +540,7 @@ Manual}. If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this command does not use Emacs's internal @code{diff}. This is the same -as using @samp{alias diff '*diff $*'}. +as using @samp{alias diff '*diff $@@*'}. @item dirname @cmindex dirname @@ -602,6 +602,8 @@ disabled by default. @cmindex egrep @itemx fgrep @cmindex fgrep +@itemx rgrep +@cmindex rgrep @itemx glimpse @cmindex glimpse The @command{grep} commands are compatible with GNU @command{grep}, @@ -610,9 +612,9 @@ but use Emacs's internal @code{grep} instead. If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these commands do not use Emacs's internal @code{grep}. This is the same as -using @samp{alias grep '*grep $*'}, though this setting applies to all -of the built-in commands for which you would need to create a separate -alias. +using @samp{alias grep '*grep $@@*'}, though this setting applies to +all of the built-in commands for which you would need to create a +separate alias. @item history @cmindex history @@ -668,7 +670,7 @@ Alias to Emacs's @code{locate} function, which simply runs the external If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's internal @code{locate} is not used. This is the same as using -@samp{alias locate '*locate $*'}. +@samp{alias locate '*locate $@@*'}. @item ls @cmindex ls @@ -1047,12 +1049,21 @@ whenever you change the current directory to a different host the value will automatically update to reflect the search path on that host. +@vindex $UID +@item $UID +This returns the effective @acronym{UID} for the current user. This +variable is connection-aware, so when the current directory is remote, +its value will be @acronym{UID} for the user associated with that +remote connection. + @vindex $_ @item $_ This refers to the last argument of the last command. With a subscript, you can access any argument of the last command. For example, @samp{$_[1]} refers to the second argument of the last -command (excluding the command name itself). +command (excluding the command name itself). To get all arguments of +the last command, you can use an index range like @samp{$_[..]} +(@pxref{Dollars Expansion}). @vindex $$ @item $$ @@ -1078,6 +1089,7 @@ that are currently visible in the Eshell window. They are both copied to the environment, so external commands invoked from Eshell can consult them to do the right thing. +@vindex $INSIDE_EMACS @item $INSIDE_EMACS This variable indicates to external commands that they are being invoked from within Emacs so they can adjust their behavior if @@ -1091,24 +1103,47 @@ necessary. Its value is @code{@var{emacs-version},eshell}. @node Aliases @section Aliases -@vindex $* +@findex eshell-read-aliases-list 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 @kbd{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). - -@vindex $1, $2, @dots{} +@command{ll} is a common alias for @code{ls -l}. To define this alias +in Eshell, you can use the command invocation @kbd{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. After +doing so, use @w{@kbd{M-x eshell-read-aliases-list}} to load the +edited aliases. + Note that unlike aliases in Bash, arguments must be handled -explicitly. Typically the alias definition would end in @samp{$*} to -pass all arguments along. More selective use of arguments via -@samp{$1}, @samp{$2}, etc., is also possible. For example, +explicitly. Within aliases, you can use the special variables +@samp{$*}, @samp{$0}, @samp{$1}, @samp{$2}, etc. to refer to the +arguments passed to the alias. + +@table @code + +@vindex $* +@item $* +This expands to the list of arguments passed to the alias. For +example, if you run @code{my-alias 1 2 3}, then @samp{$*} would be the +list @code{(1 2 3)}. Note that since this variable is a list, using +@samp{$*} in an alias will pass this list as a single argument to the +aliased command. Therefore, when defining an alias, you should +usually use @samp{$@@*} to pass all arguments along, splicing them +into your argument list (@pxref{Dollars Expansion}). + +@vindex $0 +@item $0 +This expands to the name of the alias currently being executed. + +@vindex $1, $2, @dots{}, $9 +@item $1, $2, @dots{}, $9 +These variables expand to the nth argument (starting at 1) passed to +the alias. This lets you selectively use an alias's arguments, so @kbd{alias mcd 'mkdir $1 && cd $1'} would cause @kbd{mcd foo} to create and switch to a directory called @samp{foo}. +@end table + @node History @section History @cmindex history @@ -1339,11 +1374,24 @@ index. The exact behavior depends on the type of @var{expr}'s value: @item a sequence Expands to the element at the (zero-based) index @var{i} of the sequence (@pxref{Sequences Arrays Vectors, Sequences, , elisp, The -Emacs Lisp Reference Manual}). +Emacs Lisp Reference Manual}). If @var{i} is negative, @var{i} counts +from the end, so -1 refers to the last element of the sequence. + +If @var{i} is a range like @code{@var{start}..@var{end}}, this expands +to a subsequence from the indices @var{start} to @var{end}, where +@var{end} is excluded@footnote{This behavior is different from ranges +in Bash (where both the start and end are included in the range), but +matches the behavior of similar Emacs Lisp functions, like +@code{substring} (@pxref{Creating Strings, , , elisp, The Emacs Lisp +Reference Manual}).}. @var{start} and/or @var{end} can also be +omitted, which is equivalent to the start and/or end of the entire +list. For example, @samp{$@var{expr}[-2..]} expands to the last two +values of @var{expr}. @item a string Split the string at whitespace, and then expand to the @var{i}th -element of the resulting sequence. +element of the resulting sequence. As above, @var{i} can be a range +like @code{@var{start}..@var{end}}. @item an alist If @var{i} is a non-numeric value, expand to the value associated with @@ -1370,12 +1418,36 @@ to split the string. @var{regexp} can be any form other than a number. For example, @samp{$@var{var}[: 0]} will return the first element of a colon-delimited string. +@cindex length operator, in variable expansion @item $#@var{expr} -Expands to the length of the result of @var{expr}, an expression in -one of the above forms. For example, @samp{$#@var{var}} returns the -length of the variable @var{var} and @samp{$#@var{var}[0]} returns the -length of the first element of @var{var}. Again, signals an error if -the result of @var{expr} is not a string or a sequence. +This is the @dfn{length operator}. It expands to the length of the +result of @var{expr}, an expression in one of the above forms. For +example, @samp{$#@var{var}} returns the length of the variable +@var{var} and @samp{$#@var{var}[0]} returns the length of the first +element of @var{var}. Again, signals an error if the result of +@var{expr} is not a string or a sequence. + +@cindex splice operator, in variable expansion +@item $@@@var{expr} +This is the @dfn{splice operator}. It ``splices'' the elements of +@var{expr} (an expression of one of the above forms) into the +resulting list of arguments, much like the @samp{,@@} marker in Emacs +Lisp (@pxref{Backquote, , , elisp, The Emacs Lisp Reference Manual}). +The elements of @var{expr} become arguments at the same level as the +other arguments around it. For example, if @var{numbers} is the list +@code{(1 2 3)}, then: + +@example +@group +~ $ echo 0 $numbers +(0 + (1 2 3)) +@end group +@group +~ $ echo 0 $@@numbers +(0 1 2 3) +@end group +@end example @end table @@ -2094,7 +2166,7 @@ Allow for a Bash-compatible syntax, such as: @example alias arg=blah -function arg () @{ blah $* @} +function arg () @{ blah $@@* @} @end example @item Pcomplete sometimes gets stuck @@ -2119,8 +2191,6 @@ Hitting space during a process invocation, such as @command{make}, will cause it to track the bottom of the output; but backspace no longer scrolls back. -@item It's not possible to fully @code{unload-feature} Eshell - @item Menu support was removed, but never put back @item If an interactive process is currently running, @kbd{M-!} doesn't work @@ -2179,11 +2249,6 @@ So that @kbd{M-@key{DEL}} acts in a predictable manner, etc. @item Allow all Eshell buffers to share the same history and list-dir -@item There is a problem with script commands that output to @file{/dev/null} - -If a script file, somewhere in the middle, uses @samp{> /dev/null}, -output from all subsequent commands is swallowed. - @item Split up parsing of text after @samp{$} in @file{esh-var.el} Make it similar to the way that @file{esh-arg.el} is structured. @@ -2392,13 +2457,6 @@ current being used. This way, the user could change it to use rc syntax: @samp{>[2=1]}. -@item Allow @samp{$_[-1]}, which would indicate the last element of the array - -@item Make @samp{$x[*]} equal to listing out the full contents of @samp{x} - -Return them as a list, so that @samp{$_[*]} is all the arguments of the -last command. - @item Copy ANSI code handling from @file{term.el} into @file{em-term.el} Make it possible for the user to send char-by-char to the underlying |