From afbe475271d3dd1074e7431a959bfd4add86fc0b Mon Sep 17 00:00:00 2001 From: Jim Porter Date: Sun, 3 Jul 2022 20:05:29 -0700 Subject: [PATCH 1/3] Improve tests/organization for built-in variables * lisp/eshell/em-dirs.el (eshell-inside-emacs) (eshell-dirs-initialize): Move 'INSIDE_EMACS' from here... * lisp/eshell/esh-var.el (eshell-inside-emacs) (eshell-variable-aliases-alist): ... to here, and improve doc string. * test/lisp/eshell/eshell-tests.el (eshell-test/inside-emacs-var): Move from here... * test/lisp/eshell/esh-var-tests.el (esh-var-test/inside-emacs-var): ... to here. (esh-var-test/last-arg-var-indices) (esh-var-test/last-arg-var-split-indices): New tests. * test/lisp/eshell/em-alias-tests.el: * test/lisp/eshell/em-dirs-tests.el: * test/lisp/eshell-em-script-tests.el: New files. * doc/misc/eshell.texi (Built-ins): Fix 'cd' documentation; it works with the directory ring, not the directory stack. Move built-in variables documentation from here... (Variables): ... to here, and add documentation for missing built-in variables. --- doc/misc/eshell.texi | 49 +++++++++++++++----- lisp/eshell/em-dirs.el | 5 -- lisp/eshell/esh-var.el | 18 +++++--- test/lisp/eshell/em-alias-tests.el | 64 +++++++++++++++++++++++++ test/lisp/eshell/em-dirs-tests.el | 72 +++++++++++++++++++++++++++++ test/lisp/eshell/em-script-tests.el | 62 +++++++++++++++++++++++++ test/lisp/eshell/esh-var-tests.el | 25 +++++++++- test/lisp/eshell/eshell-tests.el | 7 --- 8 files changed, 269 insertions(+), 33 deletions(-) create mode 100644 test/lisp/eshell/em-alias-tests.el create mode 100644 test/lisp/eshell/em-dirs-tests.el create mode 100644 test/lisp/eshell/em-script-tests.el diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 6a348f37dc..a72fc925c6 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -354,11 +354,11 @@ Built-ins 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. @@ -845,23 +845,40 @@ Built-ins @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 $$ @@ -870,21 +887,29 @@ Built-ins @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 diff --git a/lisp/eshell/em-dirs.el b/lisp/eshell/em-dirs.el index 5396044d8c..a3cf0b9131 100644 --- a/lisp/eshell/em-dirs.el +++ b/lisp/eshell/em-dirs.el @@ -168,9 +168,6 @@ eshell-dirstack (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! @@ -193,8 +190,6 @@ eshell-dirs-initialize (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 diff --git a/lisp/eshell/esh-var.el b/lisp/eshell/esh-var.el index 17add9b668..5092d2c6a5 100644 --- a/lisp/eshell/esh-var.el +++ b/lisp/eshell/esh-var.el @@ -113,6 +113,9 @@ (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 @@ -151,6 +154,7 @@ eshell-variable-aliases-list `(;; 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) @@ -160,6 +164,8 @@ eshell-variable-aliases-list 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))) @@ -180,13 +186,11 @@ eshell-variable-aliases-list 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 diff --git a/test/lisp/eshell/em-alias-tests.el b/test/lisp/eshell/em-alias-tests.el new file mode 100644 index 0000000000..762f125a78 --- /dev/null +++ b/test/lisp/eshell/em-alias-tests.el @@ -0,0 +1,64 @@ +;;; 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 . + +;;; 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 diff --git a/test/lisp/eshell/em-dirs-tests.el b/test/lisp/eshell/em-dirs-tests.el new file mode 100644 index 0000000000..eb27acd208 --- /dev/null +++ b/test/lisp/eshell/em-dirs-tests.el @@ -0,0 +1,72 @@ +;;; 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 . + +;;; 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 diff --git a/test/lisp/eshell/em-script-tests.el b/test/lisp/eshell/em-script-tests.el new file mode 100644 index 0000000000..a34f943402 --- /dev/null +++ b/test/lisp/eshell/em-script-tests.el @@ -0,0 +1,62 @@ +;;; 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 . + +;;; 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 diff --git a/test/lisp/eshell/esh-var-tests.el b/test/lisp/eshell/esh-var-tests.el index 3180fe7a5f..955190aee0 100644 --- a/test/lisp/eshell/esh-var-tests.el +++ b/test/lisp/eshell/esh-var-tests.el @@ -487,6 +487,13 @@ esh-var-test/columns-var (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 @@ -497,12 +504,26 @@ esh-var-test/last-result-var2 "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 diff --git a/test/lisp/eshell/eshell-tests.el b/test/lisp/eshell/eshell-tests.el index ab5d73d479..5dc1877548 100644 --- a/test/lisp/eshell/eshell-tests.el +++ b/test/lisp/eshell/eshell-tests.el @@ -178,13 +178,6 @@ eshell-test/redirect-buffer-escaped (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." -- 2.25.1