readme

;; Author: Himanshu Gupta (g DOT himanshu AT gmail DOT com)

;; This is client side implementation of telnet for scsh
;; (http://www.scsh.net/). Its pretty much the port of
;; telnetlib(http://www.cliki.net/telnetlib) from lisp
;; to scheme.

;; HOW TO USE:
,open defrec-package
(load "path/to/utils.scm")
(load "path/to/logger.scm")
(load "path/to/telnet.scm")

;; EXTERNAL INTERFACE:
;; macro to return first value of the multiple-values-stmt passed.
;; where multiple-values-stmt is a form that on evaluation results
;; in (values val1 val2 ...)
;; (define-syntax first-value multiple-value-stmt..)

;; Open a telnet session with given host and port. Default port
;; is 23.
;; Returns: a telnet record
;; (define (open-telnet-session host . port)....)

;; Closes the telnet session of given telnet record.
;; (define (close-telnet-session tn)....)

;; Peeks some data and returns as strings.
;; block-read is false by default
;; (define (peek-available-data tn . block-read)....)

;; Reads aome data and returns as string
;; block-read is false by default
;; (define (read-available-data tn . block-read)....)

;; Read until a given string is encountered.
;; When no match is found, return nil with a +eof+ or +timeout+ .
;; By default the timeout is 600 secs
;; Returns (values string-read/nil +ok+/+eof+/+timeout+)
;; Note: timeout is in seconds.
;; (define (read-until tn str case-sensitive . timeout)....)

;; Read until one from a list of given strings is encountered.
;; When no match is found, return nil with a +eof+ or +timeout+ .
;; By default the timeout is 600 secs
;; Returns (values string-read/nil +ok+/+eof+/+timeout+ -1/index-of-match-in-strings)
;; Note: timeout is in seconds.
;; (define (read-until-2 tn str case-sensitive . timeout)....)

;; Read until a given regex match is encountered.
;; When no match is found, return nil with a +eof+ or +timeout+ .
;; By default the timeout is 600 secs
;; Returns (values string-read/nil +ok+/+eof+/+timeout+)
;; Note: timeout is in seconds.
;; (define (expect tn regex case-sensitive . timeout)....)

;; Write a line to telnet connection socket.
;; (define (write-ln tn str)....)

;; Write a line to telnet connection socket ending with CR,LF
;; (define (write-ln-crlr tn str)....)

;; Known Issues
;; **
;; When I load telnet.scm, it gives following warning message
;; Warning: undefined variables
   #{Package 167 user}
;; process-sock-stream%
;; But it doesn't seem to be creating any trouble.
;;


;; EXAMPLES:
(define (exp-1)
  (let ((tn (open-telnet-session "127.0.0.1")))
    (display (first-value (read-until tn "ogin:" #f)))
    (write-ln tn "himanshu")
    (display (first-value (read-until tn "assword: " #f)))
    (write-ln tn "himanshu")
    (display (first-value (read-until tn "~]$" #f)))
    (write-ln tn "ls")
    (display (first-value (read-until tn "~]$" #f)))
    (write-ln tn "exit")
    (close-telnet-session tn)))

(define (exp-2)
  (let ((tn (open-telnet-session "127.0.0.1")))
    (display (first-value (read-until-2 tn '("xxx" "ogin:") #f)))
    (write-ln tn "himanshu")
    (display (first-value (read-until-2 tn '("assword: " "xxx") #f)))
    (write-ln tn "himanshu")
    (display (first-value (read-until tn "~]$" #f)))
    (write-ln tn "ls")
    (display (first-value (read-until tn "~]$" #f)))
    (write-ln tn "exit")
    (close-telnet-session tn)))

(define (exp-3)
  (let ((tn (open-telnet-session "127.0.0.1")))
    (display (first-value (expect tn (rx (: "ogin:")) #f)))
    (write-ln tn "himanshu")
    (display (first-value (expect tn (rx (: "assword: ")) #f)))
    (write-ln tn "himanshu")
    (display (first-value (expect tn (rx (: "~]$")) #f)))
    (write-ln tn "ls")
    (display (first-value (expect tn (rx (: "~]$")) #f)))
    (write-ln tn "exit")
    (close-telnet-session tn)))

(define (exp-4)
  (let ((tn (open-telnet-session "www.scsh.net" 80)))
    (write-ln tn "GET /index.html HTTP/1.1")
    (write-ln tn "Host: www.scsh.net")
    (write-ln tn "")
    (display (peek-available-data tn #t))
    (display "peeked some data.")
    (display (read-available-data tn))
    (display "finished reading same data that was peeked.")
    (close-telnet-session tn)))