diff --git a/doc/src/Tools.rst b/doc/src/Tools.rst index 2d9d89404a..6ecb29d2e5 100644 --- a/doc/src/Tools.rst +++ b/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 read commands from file (same as "include") pwd print current working directory cd 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 `_. @@ -549,21 +553,21 @@ More details about this are in the `readline documentation `` 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`` +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 """""""""""""""""""""""""" diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index 8d88417291..78e6efe14a 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/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 diff --git a/tools/lammps-shell/README b/tools/lammps-shell/README index bacb28ae56..1f5895b725 100644 --- a/tools/lammps-shell/README +++ b/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 read commands from file (same as "include") - pwd print current working directory - cd change current working directory (same as pwd if no directory) - mem print current and maximum memory usage - | execute 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" +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 "), 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 + + diff --git a/tools/lammps-shell/lammps-shell.cpp b/tools/lammps-shell/lammps-shell.cpp index 48ac8fe2a1..21b8ef8c7a 100644 --- a/tools/lammps-shell/lammps-shell.cpp +++ b/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);