small LAMMPS shell updates

- implement a "source" command (same as "include")
- synchronize documentation in manual and README
- updates to readline customizations

doc/src/Tools.rst

@@ -500,6 +500,7 @@ regular LAMMPS commands:
    help (or ?)    print a brief help message
    history        display the current command history list
    clear_history  wipe out the current command history list
+   source <file>  read commands from file (same as "include")
    pwd            print current working directory
    cd <directory> change current working directory (same as pwd if no directory)
    mem            print current and maximum memory usage
@@ -527,8 +528,8 @@ Limitations
 The LAMMPS shell was not designed for use with MPI parallelization
 via ``mpirun`` or ``mpiexec`` or ``srun``.
 
-Customization
-^^^^^^^^^^^^^
+Readline customization
+^^^^^^^^^^^^^^^^^^^^^^
 
 The behavior of the readline functionality can be customized in the
 ``${HOME}/.inputrc`` file.  This can be used to alter the default
@@ -540,7 +541,10 @@ global or specific for the LAMMPS shell by bracketing them between
 .. code-block:: bash
 
    $if lammps-shell
-   set expand-tilde on
+   # disable "beep" or "screen flash"
+   set bell-style none
+   # bind the "Insert" key to toggle overwrite mode
+   "\e[2~": overwrite-mode
    $endif
 
 More details about this are in the `readline documentation <https://tiswww.cwru.edu/php/chet/readline/rluserman.html#SEC9>`_.
@@ -549,21 +553,21 @@ More details about this are in the `readline documentation <https://tiswww.cwru.
 LAMMPS Shell tips and tricks
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Tilde expansion
-"""""""""""""""
+Enable tilde expansion
+""""""""""""""""""""""
 
-Adding ``set expand-tilde on`` is recommended as this will change the
-filename expansion behavior to replace any text starting with "~" by the
-full path to the corresponding user's home directory.  While the
-expansion of filenames **will** happen on all arguments where the
-context is not known (e.g. ``~/compile/lamm<TAB>`` will expand to
-``~/compile/lammps/``), it will not replace the tilde by default.  But
-since LAMMPS does not do tilde expansion itself (unlike a shell), this
-will result in errors.  Instead the tilde-expression should be expanded
-into a valid path, where the plain
-"~/" stands for the current user's home directory and "~someuser/"
-stands for "/home/someuser" or whatever the full path to that user's
-home directory is.
+Adding ``set expand-tilde on`` to ``${HOME}/.inputrc`` is recommended as
+this will change the filename expansion behavior to replace any text
+starting with "~" by the full path to the corresponding user's home
+directory.  While the expansion of filenames **will** happen on all
+arguments where the context is not known (e.g. ``~/compile/lamm<TAB>``
+will expand to ``~/compile/lammps/``), it will not replace the tilde by
+default.  But since LAMMPS does not do tilde expansion itself (unlike a
+shell), this will result in errors.  Instead the tilde-expression should
+be expanded into a valid path, where the plain "~/" stands for the
+current user's home directory and "~someuser/" stands for
+"/home/someuser" or whatever the full path to that user's home directory
+is.
 
 File extension association
 """"""""""""""""""""""""""

doc/utils/sphinx-config/false_positives.txt

@@ -2596,6 +2596,7 @@ rdf
 RDideal
 rdx
 reacter
+Readline
 realTypeMap
 real_t
 README
@@ -2889,6 +2890,7 @@ Sodani
 Soderlind
 solvated
 solvation
+someuser
 Sorensen
 soundspeed
 sourceforge

tools/lammps-shell/README

@@ -1,7 +1,7 @@
 The LAMMPS Shell. An enhanced LAMMPS executable for interactive sessions.
 
 Overview
-========
+^^^^^^^^
 
 This is a program that functions very similar to the regular LAMMPS
 executable but has several modifications and additions that make it
@@ -27,7 +27,7 @@ These enhancements makes the LAMMPS shell an attractive choice for
 interactive LAMMPS sessions in graphical user interfaces.
 
 TAB-expansion
-=============
+^^^^^^^^^^^^^
 
 When writing commands interactively at the shell prompt, you can hit
 the TAB key at any time to try and complete the text.  This completion
@@ -48,10 +48,11 @@ available in that executable.
   to known compute/fix IDs and variable names. Variable name expansion
   is also available for the ${name} variable syntax.
 
-- In all other cases, expansion will be performed on filenames.
+- In all other cases TAB expansion will complete to names of files
+  and directories.
 
 Command line editing and history
-================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When typing commands, command line editing similar to what BASH
 provides is available.  Thus it is possible to move around the
@@ -79,7 +80,7 @@ readline, please see the available documentation at:
 http://www.gnu.org/s/readline/#Documentation
 
 Additional commands
-===================
+^^^^^^^^^^^^^^^^^^^
 
 The followind commands are added to the LAMMPS shell on top of the
 regular LAMMPS commands:
@@ -87,14 +88,20 @@ regular LAMMPS commands:
 - help (or ?)    print a brief help message
 - history        display the current command history list
 - clear_history  wipe out the current command history list
+- source <file>  read commands from file (same as "include")
 - pwd            print current working directory
 - cd <directory> change current working directory (same as pwd if no directory)
 - mem            print current and maximum memory usage
 - |<command>     execute <command> as a shell command and return to the command prompt
 - exit           exit the LAMMPS shell cleanly (unlike the "quit" command)
 
+Please note that some known shell operations are implemented in the
+LAMMPS "shell" command in a platform neutral fashion, while using
+the '\|' character will always pass the following text to the
+operating system's shell command.
+
 Compilation
-===========
+^^^^^^^^^^^
 
 Compilation of the LAMMPS shell can be enabled by setting the CMake
 variable BUILD_LAMMPS_SHELL to "on" or using the makefile in the
@@ -104,7 +111,61 @@ customization depending on the features and settings used for
 compiling LAMMPS.
 
 Limitations
-===========
+^^^^^^^^^^^
 
 The LAMMPS shell was not designed for use with MPI parallelization
 via "mpirun" or "mpiexec" or "srun".
+
+Readline customization
+^^^^^^^^^^^^^^^^^^^^^^
+
+The behavior of the readline functionality can be customized in the
+"${HOME}/.inputrc" file.  This can be used to alter the default
+settings or change the key-bindings.  The LAMMPS Shell sets the
+application name "lammps-shell", so customizations can be either
+global or specific for the LAMMPS shell by bracketing them between
+"$if lammps-shell" and "$endif" like in the following example:
+
+   $if lammps-shell
+   # disable "beep" or "screen flash"
+   set bell-style none
+   # bind the "Insert" key to toggle overwrite mode
+   "\e[2~": overwrite-mode
+   $endif
+
+More details about this are in the readline documentation https://tiswww.cwru.edu/php/chet/readline/rluserman.html#SEC9
+
+
+LAMMPS Shell tips and tricks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Enable tilde expansion
+""""""""""""""""""""""
+
+Adding "set expand-tilde on" to "${HOME}/.inputrc" is recommended as
+this will change the filename expansion behavior to replace any text
+starting with "~" by the full path to the corresponding user's home
+directory.  While the expansion of filenames **will** happen on all
+arguments where the context is not known (e.g. "~/compile/lamm<TAB>"
+will expand to "~/compile/lammps/"), it will not replace the tilde by
+default.  But since LAMMPS does not do tilde expansion itself (unlike a
+shell), this will result in errors.  Instead the tilde-expression should
+be expanded into a valid path, where the plain "~/" stands for the
+current user's home directory and "~someuser/" stands for
+"/home/someuser" or whatever the full path to that user's home directory
+is.
+
+File extension association
+""""""""""""""""""""""""""
+
+Since the LAMMPS shell (unlike the regular LAMMPS executable) does not
+exit when an input file is passed on the command line with the "-in" or
+"-i" flag (the behavior is like for "python -i <filename>"), it makes
+the LAMMPS shell suitable for associating it with input files based on
+their filename extension (e.g. ".lmp").  Since "lammps-shell" is a
+console application, you have to run it inside a terminal program with a
+command line like this:
+
+   xterm -title "LAMMPS Shell" -e /path/to/lammps-shell -i in.file.lmp
+
+

tools/lammps-shell/lammps-shell.cpp

@@ -464,8 +464,10 @@ static void init_commands()
     commands.push_back("pwd");
     commands.push_back("cd");
     commands.push_back("mem");
+    commands.push_back("source");
     commands.push_back("history");
     commands.push_back("clear_history");
+    commands.push_back("save_history");
 
     // set name so there can be specific entries in ~/.inputrc
     rl_readline_name               = "lammps-shell";
@@ -553,6 +555,10 @@ static int shell_cmd(const std::string &cmd)
     } else if (words[0] == "exit") {
         free(text);
         return shell_end();
+    } else if (words[0] == "source") {
+        lammps_file(lmp, words[1].c_str());
+        free(text);
+        return 0;
     } else if ((words[0] == "pwd") || ((words[0] == "cd") && (words.size() == 1))) {
         if (getcwd(buf, buflen)) std::cout << buf << "\n";
         free(text);