Lispect

• A text-terminal automation tool similar to expect(1) of UNIX and Linux
• It runs on Windows 10 and later, and Linux
• The script is written in the subset of ISLisp (gmnlisp)

example.lsp

$ lispect example.lsp {SSH-OPTIONS} USERNAME@DOMAIN PASSWORD
→ login USERNAME@DOMAIN with ssh and input PASSWORD automatically

Note

Some variable names have been updated for compatibility with recent versions of gmnlisp, but the old names remain available for now.

lispect ./example.lsp -p 2222 [email protected] yourpassword

(if (< (length *argv*) 2)
  (progn
    (format (error-output) "Usage: ~A ~A {SSH-OPTIONS} USERNAME@DOMAIN PASSWORD~%" *executable-name* *program-name*)
    (quit 1)))

(let* ((ssh-param (subseq *argv* 0 (- (length *argv*) 1)))
       (password (elt *argv* (- (length *argv*) 1)))
       (sshpid nil))

  (with-handler
    (lambda (c)
      (format (error-output) "ssh is not found~%")
      (quit 2))
    (setq sshpid (apply #'spawn "ssh" ssh-param)))

  (expect*
    ("[fingerprint])?"
     (sendln "yes")
     (expect "password:")
     (sendln password))

    ("password:"
     (sendln password))

    (("Connection refused"
      "Could not resolve hostname")
     (quit 3))

    (30
     (format (error-output) "TIME OUT~%")
     (quit 4)))

  (expect*
    ("Permission denied"
     (expect "password:")
     (send #\U3)
     (wait sshpid)
     (quit 5))

    ("$ ")
    )
  (sendln "echo YOU CAN CALL SOME COMMAND HERE")
  (expect "$ ")
  (sendln "exit")
  (wait sshpid)
  )

Install

Download the binary package from Releases and extract the executable.

go install

go install github.com/hymkor/lispect/cmd/lispect@latest

scoop-installer

scoop install https://raw.githubusercontent.com/hymkor/lispect/master/lispect.json

or

scoop bucket add hymkor https://github.com/hymkor/scoop-bucket
scoop install lispect

Functions and variables

Parameters enclosed in curly braces {...} are optional and can be omitted.

• (send {'interval MS} "STRING")
  • Send STRING to the terminal
  • Specify the 'interval MS option to make the program wait MS milliseconds before outputting each character
• (sendln {'interval MS} "STRING")
  • send STRING and Enter-key to the terminal
• (expect {'timeout SEC} "STRING-0" "STRING-1" ...)
  • Wait until STRINGs are found on the terminal
  • When STRING-n is found on the terminal, it will return n
  • If a timeout occurs after SEC seconds have elapsed, it returns -1
• (expect* ("STRING-0" COMMANDS-0...) ("STRING-1"...)... (SEC COMMANDS-FOR-TIMEOUT...))
  • When STRING-n is found on the terminal, COMMANDS-n will be executed
  • After SEC seconds have elapsed, COMMANDS-FOR-TIMEOUT will be executed
• (spawn "COMMANDNAME" "ARG-1" ...)
  • Start the executable file and it returns Process-ID
• (wait PID)
  • Wait the process specified with PID
• (getenv "NAME")
  • Get the value of the environment variable NAME
• (setenv "NAME" "VALUE")
  • Set the value of the environment variable NAME as VALUE
• (quit {N})
  • Terminates the Lispect process with exit code N when running Lispect as a command-line executable.
  • N must be an integer between 0 and 255. If omitted, the exit code defaults to 0.
  • When Lispect is used as a library (for example, calling lispect.RunFile or lispect.RunString), the process is not terminated. Instead, these functions return an error of type exit.ExitError corresponding to the requested exit code.
• *argv* (formerly ARGV, now deprecated)¹
  The list of command-line arguments.
• *program-name* (formerly PROGRAM-NAME, now deprecated)¹
  The path to the script.
• *executable-name* (formerly EXECUTABLE-NAME, now deprecated)¹
  The path to the Lispect executable.
• *match* (formerly MATCH, now deprecated)¹
  The matched string in an (expect*) block.
• (apply FUNCTION ARG-LIST)
  • Calls FUNCTION with arguments supplied as a list ARG-LIST.
    Useful when the number of arguments is dynamic or collected in a list.
    Example:

    (setq args (list "-p" "2222" "user@host"))
    (apply #'spawn "ssh" args)  ; equivalent to (spawn "ssh" "-p" "2222" "user@host")

• (with-handler HANDLER FORM...)
  • When an error occurs in FORMS..., call HANDLER. See also ISLISP Draft - Operations relating to condition handling

Other functions are defined on ISLisp

Comparison with Expect-lua and expect(1)

	Expect-lua	Lispect	expect(1)
Started	2017	2024	1990?
Script	Lua (GophaLua)	ISLisp (gmnlisp)	tcl
Windows 7/8	Supported	Not Supported	Not Supported
Windows 10/11	Supported	Supported	Not Supported
Linux	Not Supported	Supported	Supported
Mechanisms	ReadConsoleOutputW	PseudoConsole	PseudoConsole
Read Misses	Possible1	Unlikely	Never
Stdout Redirection	Unavailable	Available	Available
Status	Stable	Work in Progress	Stable

Technologies used

• Creating a Pseudoconsole session - Windows Console | Microsoft Learn
• aymanbagabas/go-pty: Cross platform Go Pty interface
• hymkor/gmnlisp: gmnlisp - the subset of ISLisp

Acknowledgements

Thanks to the following contributors:

• @rwinkhart - #1 : modularization support

Author

This project is developed and maintained by @hymkor

Footnotes

1. These variable names were changed to accommodate gmnlisp v0.7.10 and later, in which symbol names are case-insensitive. The new format avoids potential name conflicts. ↩ ↩² ↩³ ↩⁴ ↩⁵