pygsc is a Python script that lets you run shell scripts interactively. This is useful for doing live command line demos.

pygsc is a (another) rewrite of gsc. There is a long history with the creation of this tool for a computer class I teach. You can read it there.

• Run shell scripts "interactively".
  • Characters are sent to the shell, on at a time, each time you press a key.
  • When the end of a line has been reached, press enter to go to the next line.
• Script any command line application: vim, gnuplot, ssh, etc.
• Modal : switch between insert mode, command mode, and pass through mode (see below).
  • If you run into an error in your script (a typo, or some file that is missing), you can switch to pass-through mode to quickly fix the error without exiting the demo.
• Statusline in the upper right corner of the terminal lets you know where you are and what mode your in. This can be disabled.
• Reload scripts while running without starting over. If you reload a script, its contents are updated, but the position in the demo is maintained.

Install pygsc with pip:

$ pip install pygsc

To start a demo, run gsc with the script

$ gsc my_demo.sh

This will start shell (by default, $SHELL) in a forked process and connect to it with a psuedo terminal. Each line in the script is then loaded and sent to the shell, on character at a time, while the user types. Once the entire line has been sent, gsc waits for the user to press return, and the next line is loaded.

You can specify a different shell with the --shell option.

$ gsc my_demo.sh --shell zsh

Insert mode is the main mode, gsc starts up in insert mode. While in insert mode, gsc will read each line of the script and send characters to the shell each time the user presses a key. When an entire line has been sent to the shell, gsc will wait for the user to press enter before starting the next line in the script.

<any character>: send next character to shell.

return: if at the end of current script line send \r and load next script line. otherwise, send next character.

ctrl-d: switch to command mode.

ctrl-p: switch to pass-through mode.

ctrl-c: exit gsc

Line mode is special type of insert mode where entire lines are sent to the shell instead of single characters. This mode is useful for quickly testing a script.

<any character>: send next line to the shell.

return: send \r to shell and load next script line.

ctrl-d: switch to command mode.

ctrl-c: exit gsc

Command mode allows the user to make (simple) adjustments during the demo. The user can move the current character position, for example to skip a line or backup.

i: switch to insert mode.

I: switch to line mode.

p: switch to pass-through mode.

j: jump to the next line in the script.

k: jump to the previous line in the script.

h: jump to the previous character in the current script line.

k: jump to the next character in the current script line.

^: jump to the first character in the current script line.

$: jump to the end of the current script line (one past the last character).

s: toggle status line on/off.

R: reload scripts (useful for developing scripts, you can edit the script in a text file while running and reload).

Pass-through mode sends all user input to the shell. This can be used to fix the current line, fix the environment (remove files that are not supposed to be there), or just temporarily take over the demo.

ctrl-d: switch to command mode.

ctrl-p: switch to insert mode (ctrl-p acts as a toggle between insert and pass-through mode).

Temporary Pass-through mode is a special version of pass-through mode that exits as soon as the user pressed return. It is useful for allowing the user to insert a password.

return: send \r to shell and switch back to previous mode.

A script may embed commands in its comments. These are special keywords recognized by gsc that will cause some side effect or action to take place. Commands may provide arguments that will be processed by gsc when the command is recognized. The syntax for a command is

# name[:  [arg1 [arg2 [...]]]]

If a command takes arguments, a colon ':' must separate the command name from the arguments. Multiple arguments are separated by spaces. If an argument contains spaces, it must be quoted.

include: filename

Insert the script in filename into the script. Include command can be nested.

pause: N

Pause the session for N seconds. If N is less than zero, the session will be paused until the user presses a key.

display: 'message to display'

Display a message in a separate display window. This command requires a message display backend to be installed. Currently, the only backend supported is pygame. So, to use this command, pygame must be installed.

passthrough

Switch to pass-through mode. See above.

temporary passthrough

Switch to temporary pass-through mode. See above.

line

Switch to line mode. See above.

statusline: [on|off]

Enable/disable the status line.

Sometimes a script needs to include a special key sequence. For example, if the script opens an editor, it might need to use the arrow keys to navigate the file. These keys send non-printable characters that the terminal and applications interpret. Some editors (like vim/nvim) support inserting these characters into a text file. For vim/nvim you press ctrl-v and then the key. So to insert the character sent when the escape key is pressed you could insert �.

Thse are hard to read and not all special characters seem to get inserted correctly in all editor. So pygsc includes a set of mappings for the most common keys.

'<tab>' -> '\t'
'<bksp>' -> '\x7f'
'<esc>' -> '\x1b'
'<up>' -> '\x1bOA'
'<down>' -> '\x1bOB'
'<left>' -> '\x1bOD'
'<right>' -> '\x1bOC'
'<enter>' -> '\x1bOM'
'<entr>' -> '\x1bOM'
'<del>' -> '\x1b[3~'

So for example, a script could open vim, insert some text, go back to command mode and navigate

vim file.txt
iline one
line two<esc>
ggOnew first line<esc>
:wq
cat file.txt