directory (this is the same as @kbd{cd $-}).
@item
-The command @kbd{cd =} shows the directory stack. Each line is
+The command @kbd{cd =} shows the directory ring. Each line is
numbered.
@item
-With @kbd{cd =foo}, Eshell searches the directory stack for a directory
+With @kbd{cd =foo}, Eshell searches the directory ring for a directory
matching the regular expression @samp{foo}, and changes to that
directory.
@end defmac
+@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.
+
@subsection Built-in variables
Eshell knows a few built-in variables:
@table @code
+@item $PWD
@item $+
+@vindex $PWD
@vindex $+
This variable always contains the current working directory.
+@item $OLDPWD
@item $-
+@vindex $OLDPWD
@vindex $-
This variable always contains the previous working directory (the
current working directory from before the last @code{cd} command).
+When using @code{$-}, you can also access older directories in the
+directory ring via subscripting, e.g. @samp{$-[1]} refers to the
+working directory @emph{before} the previous one.
@item $_
@vindex $_
-It refers to the last argument of the last command.
+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).
@item $$
@vindex $$
@item $?
@vindex $?
-This variable contains the exit code of the last command (0 or 1 for
-Lisp functions, based on successful completion).
+This variable contains the exit code of the last command. If the last
+command was a Lisp function, it is 0 for successful completion or 1
+otherwise.
+
+@item $COLUMNS
+@item $LINES
+@vindex $COLUMNS
+@vindex $LINES
+These variables tell the number of columns and lines, respectively,
+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.
+
+@item $INSIDE_EMACS
+This variable indicates to external commands that they are being
+invoked from within Emacs so they can adjust their behavior if
+necessary. Its value is @code{@var{emacs-version},eshell}.
@end table
@xref{Aliases}, for the built-in variables @samp{$*}, @samp{$1},
@samp{$2}, @dots{}, in alias definitions.
-@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.
-
@node Aliases
@section Aliases
(defvar eshell-last-dir-ring nil
"The last directory that Eshell was in.")
-(defconst eshell-inside-emacs (format "%s,eshell" emacs-version)
- "Value for the `INSIDE_EMACS' environment variable.")
-
;;; Functions:
(defun eshell-dirs-initialize () ;Called from `eshell-mode' via intern-soft!
(unless (ring-empty-p eshell-last-dir-ring)
(expand-file-name
(ring-ref eshell-last-dir-ring 0))))
- t)
- ("INSIDE_EMACS" eshell-inside-emacs
t))))
(when eshell-cd-on-directory
(require 'pcomplete)
(require 'ring)
+(defconst eshell-inside-emacs (format "%s,eshell" emacs-version)
+ "Value for the `INSIDE_EMACS' environment variable.")
+
(defgroup eshell-var nil
"Variable interpolation is introduced whenever the `$' character
appears unquoted in any argument (except when that argument is
`(;; for eshell.el
("COLUMNS" ,(lambda (_indices) (window-body-width nil 'remap)) t)
("LINES" ,(lambda (_indices) (window-body-height nil 'remap)) t)
+ ("INSIDE_EMACS" eshell-inside-emacs t)
;; for eshell-cmd.el
("_" ,(lambda (indices)
indices))))
("?" eshell-last-command-status)
("$" eshell-last-command-result)
+
+ ;; for em-alias.el and em-script.el
("0" eshell-command-name)
("1" ,(lambda (_indices) (nth 0 eshell-command-arguments)))
("2" ,(lambda (_indices) (nth 1 eshell-command-arguments)))
compute the string value that will be returned when the variable is
accessed via the syntax `$NAME'.
-If the value is a function, call that function with two arguments: the
-list of the indices that was used in the reference, and whether the
-user is requesting the length of the ultimate element. For example, a
-reference of `$NAME[10][20]' would result in the function for alias
-`NAME' being called (assuming it were aliased to a function), and the
-arguments passed to this function would be the list `(10 20)', and
-nil.
+If the value is a function, call that function with one argument: the
+list of the indices that was used in the reference. For example, if
+`NAME' were aliased to a function, a reference of `$NAME[10][20]'
+would result in that function being called with the argument
+`((\"10\") (\"20\"))'. (For more details, see `eshell-apply-indices').
If the value is a string, return the value for the variable with that
name in the current environment. If no variable with that name exists
--- /dev/null
+;;; em-alias-tests.el --- em-alias test suite -*- lexical-binding:t -*-
+
+;; Copyright (C) 2022 Free Software Foundation, Inc.
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Tests for Eshell's alias module.
+
+;;; Code:
+
+(require 'ert)
+(require 'esh-mode)
+(require 'eshell)
+(require 'em-alias)
+
+(require 'eshell-tests-helpers
+ (expand-file-name "eshell-tests-helpers"
+ (file-name-directory (or load-file-name
+ default-directory))))
+;;; Tests:
+
+(ert-deftest em-alias-test/simple-alias ()
+ "Test a simple alias with no arguments"
+ (with-temp-eshell
+ (eshell-insert-command "alias say-hi 'echo hi'")
+ (eshell-command-result-p "say-hi" "hi\n")
+ (eshell-command-result-p "say-hi bye" "hi\n")))
+
+(ert-deftest em-alias-test/alias-arg-vars ()
+ "Test alias with $0, $1, ... variables"
+ (with-temp-eshell
+ (eshell-insert-command "alias show-args 'printnl $0 \"$1 $2\"'")
+ (eshell-command-result-p "show-args one two" "show-args\none two\n")))
+
+(ert-deftest em-alias-test/alias-all-args-var ()
+ "Test alias with the $* variable"
+ (with-temp-eshell
+ (eshell-insert-command "alias show-all-args 'printnl $*'")
+ (eshell-command-result-p "show-all-args" "\\`\\'")
+ (eshell-command-result-p "show-all-args a" "a\n")
+ (eshell-command-result-p "show-all-args a b c" "a\nb\nc\n")))
+
+(ert-deftest em-alias-test/alias-all-args-var-indices ()
+ "Test alias with the $* variable using indices"
+ (with-temp-eshell
+ (eshell-insert-command "alias add-pair '+ $*[0] $*[1]'")
+ (eshell-command-result-p "add-pair 1 2" "3\n")))
+
+;; em-alias-tests.el ends here
--- /dev/null
+;;; em-dirs-tests.el --- em-dirs test suite -*- lexical-binding:t -*-
+
+;; Copyright (C) 2022 Free Software Foundation, Inc.
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Tests for Eshell's dirs module.
+
+;;; Code:
+
+(require 'ert)
+(require 'esh-mode)
+(require 'eshell)
+(require 'em-dirs)
+
+(require 'eshell-tests-helpers
+ (expand-file-name "eshell-tests-helpers"
+ (file-name-directory (or load-file-name
+ default-directory))))
+;;; Tests:
+
+(ert-deftest em-dirs-test/pwd-var ()
+ "Test using the $PWD variable."
+ (should (equal (eshell-test-command-result "echo $PWD")
+ (expand-file-name (eshell/pwd)))))
+
+(ert-deftest em-dirs-test/short-pwd-var ()
+ "Test using the $+ (current directory) variable."
+ (should (equal (eshell-test-command-result "echo $+")
+ (expand-file-name (eshell/pwd)))))
+
+(ert-deftest em-dirs-test/oldpwd-var ()
+ "Test using the $OLDPWD variable."
+ (let (eshell-last-dir-ring-file-name)
+ (with-temp-eshell
+ (eshell-command-result-p "echo $OLDPWD"
+ "\\`\\'")
+ (ring-insert eshell-last-dir-ring "/some/path")
+ (eshell-command-result-p "echo $OLDPWD"
+ "/some/path\n"))))
+
+(ert-deftest em-dirs-test/directory-ring-var ()
+ "Test using the $- (directory ring) variable."
+ (let (eshell-last-dir-ring-file-name)
+ (with-temp-eshell
+ (eshell-command-result-p "echo $-"
+ "\\`\\'")
+ (ring-insert eshell-last-dir-ring "/some/path")
+ (ring-insert eshell-last-dir-ring "/other/path")
+ (eshell-command-result-p "echo $-"
+ "/other/path\n")
+ (eshell-command-result-p "echo $-[0]"
+ "/other/path\n")
+ (eshell-command-result-p "echo $-[1]"
+ "/some/path\n"))))
+
+;; em-dirs-tests.el ends here
--- /dev/null
+;;; em-script-tests.el --- em-script test suite -*- lexical-binding:t -*-
+
+;; Copyright (C) 2022 Free Software Foundation, Inc.
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Tests for Eshell's script module.
+
+;;; Code:
+
+(require 'ert)
+(require 'esh-mode)
+(require 'eshell)
+(require 'em-script)
+
+(require 'eshell-tests-helpers
+ (expand-file-name "eshell-tests-helpers"
+ (file-name-directory (or load-file-name
+ default-directory))))
+;;; Tests:
+
+(ert-deftest em-script-test/source-script ()
+ "Test sourcing script with no argumentss"
+ (ert-with-temp-file temp-file :text "echo hi"
+ (with-temp-eshell
+ (eshell-command-result-p (format "source %s" temp-file)
+ "hi\n"))))
+
+(ert-deftest em-script-test/source-script-arg-vars ()
+ "Test sourcing script with $0, $1, ... variables"
+ (ert-with-temp-file temp-file :text "printnl $0 \"$1 $2\""
+ (with-temp-eshell
+ (eshell-command-result-p (format "source %s one two" temp-file)
+ (format "%s\none two\n" temp-file)))))
+
+(ert-deftest em-script-test/source-script-all-args-var ()
+ "Test sourcing script with the $* variable"
+ (ert-with-temp-file temp-file :text "printnl $*"
+ (with-temp-eshell
+ (eshell-command-result-p (format "source %s" temp-file)
+ "\\`\\'")
+ (eshell-command-result-p (format "source %s a" temp-file)
+ "a\n")
+ (eshell-command-result-p (format "source %s a b c" temp-file)
+ "a\nb\nc\n"))))
+
+;; em-script-tests.el ends here
(should (equal (eshell-test-command-result "echo $COLUMNS")
(window-body-width nil 'remap))))
+(ert-deftest esh-var-test/inside-emacs-var ()
+ "Test presence of \"INSIDE_EMACS\" in subprocesses"
+ (with-temp-eshell
+ (eshell-command-result-p "env"
+ (format "INSIDE_EMACS=%s,eshell"
+ emacs-version))))
+
(ert-deftest esh-var-test/last-result-var ()
"Test using the \"last result\" ($$) variable"
(with-temp-eshell
"Test using the \"last result\" ($$) variable twice"
(with-temp-eshell
(eshell-command-result-p "+ 1 2; + $$ $$"
- "3\n6\n")))
+ "3\n6\n")))
(ert-deftest esh-var-test/last-arg-var ()
"Test using the \"last arg\" ($_) variable"
(with-temp-eshell
(eshell-command-result-p "+ 1 2; + $_ 4"
- "3\n6\n")))
+ "3\n6\n")))
+
+(ert-deftest esh-var-test/last-arg-var-indices ()
+ "Test using the \"last arg\" ($_) variable with indices"
+ (with-temp-eshell
+ (eshell-command-result-p "+ 1 2; + $_[0] 4"
+ "3\n5\n")
+ (eshell-command-result-p "+ 1 2; + $_[1] 4"
+ "3\n6\n")))
+
+(ert-deftest esh-var-test/last-arg-var-split-indices ()
+ "Test using the \"last arg\" ($_) variable with split indices"
+ (with-temp-eshell
+ (eshell-command-result-p "concat 01:02 03:04; echo $_[0][: 1]"
+ "01:0203:04\n2\n")))
;; esh-var-tests.el ends here
(string-replace "\\" "\\\\" bufname))))
(should (equal (buffer-string) "hi")))))
-(ert-deftest eshell-test/inside-emacs-var ()
- "Test presence of \"INSIDE_EMACS\" in subprocesses"
- (with-temp-eshell
- (eshell-command-result-p "env"
- (format "INSIDE_EMACS=%s,eshell"
- emacs-version))))
-
(ert-deftest eshell-test/escape-nonspecial ()
"Test that \"\\c\" and \"c\" are equivalent when \"c\" is not a
special character."
projects / emacs.git / commitdiff