ruby-core

Index: lib/net/telnet.rb
===================================================================
RCS file: /src/ruby/lib/net/telnet.rb,v
retrieving revision 1.20
diff -u -u -r1.20 telnet.rb
--- lib/net/telnet.rb	3 Jun 2003 09:40:21 -0000	1.20
+++ lib/net/telnet.rb	31 Jul 2003 15:17:00 -0000
@@ -11,34 +11,67 @@
 
   host = Net::Telnet::new({
            "Binmode"    => false,        # default: false
+                           # Set "Binmode" to true to stop incoming EOL
+                           # being converted to "\n". (See the
+                           # "SEND STRING" example below for details of EOL.)
+
            "Host"       => "localhost",  # default: "localhost"
+                           # The "Host" option can be either a name or a
+                           # numeric IP address.
+
            "Output_log" => "output_log", # default: nil (no output)
            "Dump_log"   => "dump_log",   # default: nil (no output)
+
            "Port"       => 23,           # default: 23
+                           # The "Port" option can either be a port number
+                           # or a service name as given in /etc/services.
+
            "Prompt"     => /[$%#>] \z/n, # default: /[$%#>] \z/n
+
            "Telnetmode" => true,         # default: true
+                           # Set "Telnetmode" to false to prevent
+                           # interpretation of telnet commands.
+                           # This can be useful if you're not actually
+                           # talking to a telnet server (though you may
+                           # find it easier to use net::FTP, net::HTTP
+                           # or one of the other protocol implementations
+                           # rather than using Net::Telnet yourself).
+
            "Timeout"    => 10,           # default: 10
-             # if ignore timeout then set "Timeout" to false.
+                           # Network timeout in seconds.
+                           # Set "Timeout" to false (not 0) for no timeout.
+
            "Waittime"   => 0,            # default: 0
+                           # Number of seconds to wait after "Prompt" has
+                           # appeared, checking that there's no more output
+                           # on its way, before deciding that we've actually
+                           # seen the prompt.
+                           #
+                           # Data that matches "Prompt" could occur amongst
+                           # other output, but a prompt should mean that
+                           # the remote host is no longer producing output,
+                           # and is waiting for us to respond.
+                           # A heavily loaded host or a slow network might
+                           # mean that you have to increase this value.
+                           #
+                           # If you want to give up waiting for a prompt
+                           # after a given number of seconds, you should use
+                           # the "Timeout" option instead.
+
            "Proxy"      => proxy         # default: nil
-                           # proxy is Net::Telnet or IO object
+                           # Proxy must be either a Net::Telnet or IO object.
          })
 
-Telnet object has socket class methods.
-
-if set "Telnetmode" option to false. not telnet command interpretation.
-"Waittime" is time to confirm "Prompt". There is a possibility that
-the same character as "Prompt" is included in the data, and, when
-the network or the host is very heavy, the value is enlarged.
+Telnet objects delegate to Socket to make its methods available.
 
 
 === STATUS OUTPUT
 
   host = Net::Telnet::new({"Host" => "localhost"}){|c| print c }
 
-connection status output.
+Outputs the connection status.
 
-example:
+For example:
 
   Trying localhost...
   Connected to localhost.
@@ -47,40 +80,53 @@
 === WAIT FOR MATCH
 
   line = host.waitfor(/match/)
-  line = host.waitfor({"Match"   => /match/,
-                       "String"  => "string",
+  line = host.waitfor({"Match"   => /regex/,
                        "Timeout" => secs})
-                         # if ignore timeout then set "Timeout" to false.
+                         # Set "Timeout" to false (not 0) for no timeout.
+  line = host.waitfor({"String"  => "literal text to match",
+                       "Timeout" => secs})
+
+The "String" option is used to match a literal string, and may be more
+convenient than using a regex containing escapes. Using the "String" option
+is equivalent to setting "Match" to the value of Regexp.new(quote("string")).
 
-if set "String" option, then Match == Regexp.new(quote("string"))
+Note that the "String" option will be ignored if a "Match" option is given.
 
 
 ==== REALTIME OUTPUT
 
+An optional block can be used to process all the data received while waiting.
+
   host.waitfor(/match/){|c| print c }
   host.waitfor({"Match"   => /match/,
-                "String"  => "string",
                 "Timeout" => secs}){|c| print c}
 
-of cource, set sync=true or flush is necessary.
+Of course, set sync=true or flush is necessary.
 
 
-=== SEND STRING AND WAIT PROMPT
+=== SEND STRING AND WAIT FOR PROMPT
 
   line = host.cmd("string")
-  line = host.cmd({"String" => "string",
+  line = host.cmd({"String" => "command",
                    "Match" => /[$%#>] \z/n,
                    "Timeout" => 10})
 
+Note that the "String" parameter to the cmd method is unrelated to the
+"String" parameter to the waitfor method. Here, "String" is the text of
+the command to be sent to the server. "Match" is, as with waitfor, a
+regex matching the prompt.
+
 
 ==== REALTIME OUTPUT
 
+An optional block can be used to process all the data received while waiting.
+
   host.cmd("string"){|c| print c }
-  host.cmd({"String" => "string",
+  host.cmd({"String" => "command",
             "Match" => /[$%#>] \z/n,
             "Timeout" => 10}){|c| print c }
 
-of cource, set sync=true or flush is necessary.
+Of course, set sync=true or flush is necessary.
 
 
 === SEND STRING
@@ -88,29 +134,34 @@
   host.print("string")
   host.puts("string")
 
-Telnet#puts() adds "\n" to the last of "string".
+Telnet#puts() appends "\n" to the given string.
 
-CAUTION: Telnet#print() NOT adds "\n" to the last of "string".
+CAUTION: Telnet#print() no longer appends "\n" as it once did.
 
-If "Telnetmode" option is true, then escape IAC code ("\xFF"). If
-"Binmode" option is false, then convert "\n" to EOL(end of line) code.
+If the "Telnetmode" option is true then any IAC ("\xFF") characters
+in "string" will be escaped (telnet uses IAC -- Interpret As Command --
+to insert its own communication into your data stream).
 
-If "WILL SGA" and "DO BIN", then EOL is CR. If "WILL SGA", then EOL is
-CR + NULL. If the other cases, EOL is CR + LF.
+If the "Binmode" option is false then "\n" will be converted to EOL,
+the appropriate end of line string.
+
+Normally, EOL is CR + LF. If "WILL SGA" and "DO BIN" have been
+negotiated, EOL will be CR. If "WILL SGA" was negotiated, EOL will
+be CR + NULL.
 
 
 === TOGGLE TELNET COMMAND INTERPRETATION
 
   host.telnetmode          # return the current status (true or false)
   host.telnetmode = true   # do telnet command interpretation (default)
-  host.telnetmode = false  # don't telnet command interpretation
+  host.telnetmode = false  # don't do telnet command interpretation
 
 
 === TOGGLE NEWLINE TRANSLATION
 
   host.binmode          # return the current status (true or false)
-  host.binmode = true   # no translate newline
-  host.binmode = false  # translate newline (default)
+  host.binmode = false  # do translate newline (default)
+  host.binmode = true   # don't translate newlines
 
 
 === LOGIN
@@ -119,7 +170,7 @@
   host.login({"Name" => "username",
               "Password" => "password"})
 
-if no password prompt:
+If you don't need to respond to a password prompt, use this instead:
 
   host.login("username")
   host.login({"Name" => "username"})
@@ -127,12 +178,14 @@
 
 ==== REALTIME OUTPUT
 
+An optional block can be used to process all the data received while
+logging in.
+
   host.login("username", "password"){|c| print c }
   host.login({"Name" => "username",
               "Password" => "password"}){|c| print c }
 
-of cource, set sync=true or flush is necessary.
-
+Of course, set sync=true or flush is necessary.
 
 
 == EXAMPLE
@@ -149,6 +202,7 @@
 
 === CHECKS A POP SERVER TO SEE IF YOU HAVE MAIL
 
+  # See also Net::POP3.
   pop = Net::Telnet::new({"Host" => "your_destination_host_here",
                           "Port" => 110,
                           "Telnetmode" => false,
@@ -250,7 +304,7 @@
         @options["Binmode"]    = false         
       else
         unless (true == @options["Binmode"] or false == @options["Binmode"])
-          raise ArgumentError, "Binmode option required true or false"
+          raise ArgumentError, "Binmode option must be true or false"
         end
       end
 
@@ -258,7 +312,7 @@
         @options["Telnetmode"] = true          
       else
         unless (true == @options["Telnetmode"] or false == @options["Telnetmode"])
-          raise ArgumentError, "Telnetmode option required true or false"
+          raise ArgumentError, "Telnetmode option must be true or false"
         end
       end
 
@@ -303,7 +357,7 @@
         elsif @options["Proxy"].kind_of?(IO)
           @sock = @options["Proxy"]
         else
-          raise "Error; Proxy is Net::Telnet or IO object."
+          raise "Error: Proxy must be a Net::Telnet or IO object."
         end
       else
         message = "Trying " + @options["Host"] + "...\n"
@@ -320,7 +374,7 @@
             end
           end
         rescue TimeoutError
-          raise TimeoutError, "timed-out; opening of the host"
+          raise TimeoutError, "timed out while opening a connection to the host"
         rescue
           @log.write($ERROR_INFO.to_s + "\n") if @options.has_key?("Output_log")
           @dumplog.log_dump('#', $ERROR_INFO.to_s + "\n") if @options.has_key?("Dump_log")
@@ -347,7 +401,7 @@
       when true, false
         @options["Telnetmode"] = mode
       else
-        raise ArgumentError, "required true or false"
+        raise ArgumentError, "argument must be true or false"
       end
     end
 
@@ -355,7 +409,7 @@
       if (true == mode or false == mode)
         @options["Telnetmode"] = mode
       else
-        raise ArgumentError, "required true or false"
+        raise ArgumentError, "argument must be true or false"
       end
     end
 
@@ -366,7 +420,7 @@
       when true, false
         @options["Binmode"] = mode
       else
-        raise ArgumentError, "required true or false"
+        raise ArgumentError, "argument must be true or false"
       end
     end
 
@@ -374,7 +428,7 @@
       if (true == mode or false == mode)
         @options["Binmode"] = mode
       else
-        raise ArgumentError, "required true or false"
+        raise ArgumentError, "argument must be true or false"
       end
     end
 
@@ -462,7 +516,7 @@
       rest = ''
       until(prompt === line and not IO::select([@sock], nil, nil, waittime))
         unless IO::select([@sock], nil, nil, time_out)
-          raise TimeoutError, "timed-out; wait for the next data"
+          raise TimeoutError, "timed out while waiting for more data"
         end
         begin
           c = @sock.sysread(1024 * 1024)
@@ -480,14 +534,14 @@
               buf = preprocess(c)
               rest = ''
             end
-         else
-           # Not Telnetmode.
-           #
-           # We cannot use preprocess() on this data, because that
-           # method makes some Telnetmode-specific assumptions.
-           buf = c
-           buf.gsub!(/#{EOL}/no, "\n") unless @options["Binmode"]
-           rest = ''
+          else
+            # Not Telnetmode.
+            #
+            # We cannot use preprocess() on this data, because that
+            # method makes some Telnetmode-specific assumptions.
+            buf = c
+            buf.gsub!(/#{EOL}/no, "\n") unless @options["Binmode"]
+            rest = ''
           end
           @log.print(buf) if @options.has_key?("Output_log")
           line += buf