Lazily convert numeric strings to Lisp numbers in Eshell

This should reduce the number of issues with Eshell converting strings
to numbers too aggressively and losing information (e.g. "001" -> 1)
while still allowing almost all of the beneficial uses, like summing a
list of numeric strings with '+'.

* lisp/eshell/esh-util.el (eshell--do-mark-numeric-string): New
function.
(eshell-convert-to-number): Make obsolete in favor of...
(eshell-mark-numeric-string): ... this.  Update callers.

* lisp/eshell/esh-arg.el (eshell--numberlike-p): New function...
(eshell-concat-1): ... use it.

* test/lisp/eshell/esh-util-tests.el:  Reimplement type conversion tests
to use 'eshell-convertible-to-number-p' instead.

* test/lisp/eshell/esh-var-tests.el
(esh-var-test/interp-var-splice-concat, esh-var-test/interp-concat-cmd)
(esh-var-test/interp-convert-var-split-indices)
(esh-var-test/interp-convert-quoted-var-split-indices)
(esh-var-test/interp-convert-cmd-multiline)
(esh-var-test/interp-convert-cmd-split-indices): Adjust tests to check
the new behavior.

* doc/misc/eshell.texi (Type Conversion): New section.
(Expansion): Clarify concatenation behavior.

1 files changed, 46 insertions, 15 deletions

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 9a2714b14fb..ee4d0ca09c8 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -432,16 +432,6 @@ This command writes a list of all files matching the glob pattern
 
 @node Arguments
 @section Arguments
-Ordinarily, Eshell parses arguments in command form as either strings
-or numbers, depending on what the parser thinks they look like.  To
-specify an argument of some other data type, you can use a Lisp form
-(@pxref{Invocation}):
-
-@example
-~ $ echo (list 1 2 3)
-(1 2 3)
-@end example
-
 When calling external commands (and many built-in Eshell commands,
 too) Eshell will flatten the arguments the command receives, so
 passing a list as an argument will ``spread'' the elements into
@@ -454,13 +444,15 @@ multiple arguments:
 3
 @end example
 
-@subsection Quoting and escaping
+@subsection Quoting and Escaping
 As with other shells, you can escape special characters and spaces by
 prefixing the character with a backslash (@samp{\}), or by surrounding
 the string with apostrophes (@samp{''}) or double quotes (@samp{""}).
 This is needed especially for file names with special characters like
 pipe (@samp{|}) or square brackets (@samp{[} or @samp{]}), which could
-be part of remote file names.
+be part of remote file names.  In addition, quoting or escaping an
+argument will prevent it from being converted to a number when passed to
+a Lisp function.
 
 When you escape a character with @samp{\} outside of any quotes, the
 result is the literal character immediately following it.  For
@@ -495,7 +487,46 @@ When using expansions (@pxref{Expansion}) in an Eshell command, the
 result may potentially be of any data type.  To ensure that the result
 is always a string, the expansion can be surrounded by double quotes.
 
-@subsection Special argument types
+@subsection Type Conversion
+When invoking a Lisp function via command form, Eshell automatically
+converts string arguments that look like numbers to actual Lisp
+numbers in order to make it easier to work with numeric values.  You can
+prevent this conversion on a case-by-case basis by quoting or escaping
+the argument:
+
+@example
+~ $ type-of 1
+integer
+~ $ type-of "1"
+string
+@end example
+
+When invoking a subcommand in command form, Eshell will split the output
+line-by-line into a list.  Additionally, if every line looks like a
+number, then Eshell will mark them as numeric so that passing them to a
+Lisp function will convert them to Lisp numbers:
+
+@example
+~ $ cat numbers.txt
+01
+02
+03
+~ $ + $@@@{cat numbers.txt@}
+6
+@end example
+
+If you find this behavior inconvenient for certain functions, you can
+tell Eshell not to perform this conversion for that function:
+
+@example
+(put \\='find-file \\='eshell-no-numeric-conversions t)
+@end example
+
+@vindex eshell-convert-numeric-arguments
+You can also disable this conversion behavior entirely by setting
+@code{eshell-convert-numeric-arguments} to @code{nil}.
+
+@subsection Special Argument Types
 In addition to strings and numbers, Eshell supports a number of
 special argument types.  These let you refer to various other Emacs
 Lisp data types, such as lists or buffers.
@@ -1764,8 +1795,8 @@ behavior depends on the types of each value being concatenated:
 Concatenate both values together.
 
 @item one or both numbers
-Concatenate the string representation of each value, converting back to
-a number if possible.
+Concatenate the string representation of each value.  If either value is
+numeric, mark the concatenated value as numeric if possible.
 
 @item one or both (non-@code{nil}) lists
 Concatenate ``adjacent'' elements of each value (possibly converting