lispect

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)[^1]
  The list of command-line arguments.
• *program-name* (formerly PROGRAM-NAME, now deprecated)[^1]
  The path to the script.
• *executable-name* (formerly EXECUTABLE-NAME, now deprecated)[^1]
  The path to the Lispect executable.
• *match* (formerly MATCH, now deprecated)[^1]
  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

[^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.

Other functions are defined on ISLisp

Comparison with Expect-lua and expect(1)

[^1]: When the output is too excessive, there might be some dropped data

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