===================================================================
RCS file: /cvs/trango/Net-Telnet-Trango/lib/Net/Telnet/Trango.pm,v
retrieving revision 1.25
retrieving revision 1.27
diff -u -r1.25 -r1.27
--- trango/Net-Telnet-Trango/lib/Net/Telnet/Trango.pm	2007/01/17 20:48:46	1.25
+++ trango/Net-Telnet-Trango/lib/Net/Telnet/Trango.pm	2007/01/31 18:53:29	1.27
@@ -1,5 +1,5 @@
 package Net::Telnet::Trango;
-# $RedRiver: Trango.pm,v 1.24 2007/01/17 19:00:51 andrew Exp $
+# $RedRiver: Trango.pm,v 1.26 2007/01/17 23:15:13 andrew Exp $
 use strict;
 use warnings;
 use base 'Net::Telnet';
@@ -8,7 +8,8 @@
 
 =head1 NAME
 
-Net::Telnet::Trango - Perl extension for accessing the Trango telnet interface
+Net::Telnet::Trango
+- Perl extension for accessing the Trango telnet interface
 
 =head1 SYNOPSIS
 
@@ -52,14 +53,20 @@
 
 =pod
 
-=item new
+=item B<new>
 
-Same as new from L<Net::Telnet> but has defaults for the trango 'Prompt'
+- Creates a new Net::Telnet::Trango object.
 
+	new([Options from Net::Telnet,]
+	    [Decode => 0,]);
+
+Same as new from L<Net::Telnet> but sets the default Trango Prompt: 
+'/#> *$/'
+
 It also takes an optional parameter 'Decode'.  If not defined it
 defaults to 1, if it is set to 0, it will not decode the output and
-instead return an array of the lines that were returned from the
-command.
+instead return a reference to an array of the lines that were returned 
+from the command.
 
 =cut
 
@@ -168,65 +175,72 @@
 
 =head2 ACCESSORS
 
+These are usually only set internally.
+
 =over
 
-=item Host
+=item B<firmware_version>
 
-returns the name of the host that you are accessing
+- returns the firmware version
 
-=item firmware_version
+Returns the firmware version if available, otherwise undef.
 
-returns the firmware version on the trango if available otherwise undef.  
-Available after a successful open()
-This is usually only set internally
+It should be available after a successful open().
 
-=item host_type
+=item B<host_type>
 
+- return the type of host you are connected to.
+
 returns the type of host from the login banner for example M5830S or M5300S.  
-Available after a successful open()
-This is usually only set internally
 
-=item is_connected
+Should be available after a successful open().
 
-returns 1 after a successful open() otherwise undef
-This is usually only set internally
+=item B<is_connected>
 
-=item logged_in
+- Status of the connection to host.
 
-returns 1 after a successful login() 0 if it failed and undef if 
-login() was never called
-This is usually only set internally
+returns 1 when connected, undef otherwise.
 
-=item login_banner
+=item B<logged_in>
 
+- Status of being logged in to the host.
+
+returns 1 after a successful login(), 0 if it failed and undef if 
+login() was never called.
+
+=item B<login_banner>
+
+- The banner when first connecting to the host.
+
 returns the banner that is displayed when first connected at login.  
-Only set after a successful open()
+Only set after a successful open().
 
-This is usually only set internally
+=item B<last_lines>
 
-=item last_lines
+- The last lines of output from the last cmd().
 
-returns the output from the last cmd() that was run as an array ref
-This is usually only set internally
+returns, as an array ref, the output from the last cmd() that was run.
 
-=item last_error
+=item B<last_error>
 
-returns the last error reported.  Should contain the the last entry in
-last_lines
+- A text output of the last error that was encountered.
 
+returns the last error reported.  Probably contains the last entry in
+last_lines.
+
 =back
 
 =head2 ALIASES
 
 =over
 
-=item bye
+=item B<bye>
 
-alias of exit()
+- alias of L<exit()>.
 
-=item restart
+=item B<restart>
 
-alias of reboot()
+- alias of L<reboot()>.
 
 =back
 
@@ -239,73 +253,92 @@
 
 =over
 
-=item tftpd
+=item B<tftpd>
 
-Returns a hash ref of the decoded output from the command. 
+- Returns a hash ref of the decoded output from the 
+command. 
 
-Also see enable_tftpd() and disable_tftpd() as those check for correct output
+Also see enable_tftpd() and disable_tftpd() as those check that it was 
+successfully changed.
 
-=item ver
+=item B<ver>
 
-Returns a hash ref of the decoded output from the command. 
+- Returns a hash ref of the decoded output from the 
+command. 
 
-=item sysinfo
+=item B<sysinfo>
 
-Returns a hash ref of the decoded output from the command. 
+- Returns a hash ref of the decoded output from the 
+command. 
 
-=item exit
+=item B<exit>
 
-exits the command session with the trango and closes the connection
+- exits the command session with the Trango and closes 
+the connection
 
-=item reboot
+=item B<reboot>
 
-reboots the trango and closes the connection
+- reboots the Trango and closes the connection
 
-=item remarks
+=item B<remarks>
 
+- Set or retrieve the remarks.
+
 Takes an optional argument, which sets the remarks.  
 If there is no argument, returns the current remarks.
 
-=item sulog
+  my $old_remarks = $t->remarks();
+  $t->remarks($new_remarks);
 
-returns an array ref of hashes containing each log line.
+=item B<sulog>
 
-=item save_sudb
+- returns an array ref of hashes containing each log 
+line.
 
-returns true on success, undef on failure
+=item B<save_sudb>
 
-=item syslog
+- returns true on success, undef on failure
 
-returns the output from the syslog command
+=item B<syslog>
 
-=item pipe
+- returns the output from the syslog command
 
-returns the output from the pipe command
+=item B<pipe>
 
-=item maclist
+- returns the output from the pipe command
 
-returns the output from the maclist command
+=item B<maclist>
 
-=item maclist_reset
+-  returns the output from the maclist command
 
-resets the maclist.  No useful output.
+=item B<maclist_reset>
 
-=item eth_list
+- resets the maclist.  
 
-returns the output from the eth list command
+No useful output.
 
-=item su_info
+=item B<eth_list>
 
-You need to pass in args => <suid> and it will return the info for that suid.
+- returns the output from the eth list command
 
-=item save_ss
+=item B<su_info>
 
-saves the config.  Returns 1 on success, undef on failure.
+- returns information about the SU.
 
+You need to pass in the $suid and it will return the info for that suid.
+
+  $t->su_info($suid);
+
+=item B<save_ss>
+
+- saves the config.  
+
+Returns 1 on success, undef on failure.
+
 =cut
 
 
-my $success = 'Success.';
+my $success = 'Success\\.';
 my %COMMANDS = (
   tftpd       => { decode => 'all',   expect => $success },
   ver         => { decode => 'all' },
@@ -334,12 +367,12 @@
 my %ALIASES = (
   bye     => 'exit',
   restart => 'reboot',
+  Host    => 'host',
 );
 
 my %ACCESS = map { $_ => 1 } qw( 
   firmware_version 
   host_type 
-  Host 
   is_connected 
   logged_in
   login_banner
@@ -379,8 +412,10 @@
 
 =pod
 
-=item open
+=item B<open>
 
+- Open a connection to a Trango AP.
+
 Calls Net::Telnet::open() then makes sure you get a password prompt so
 you are ready to login() and parses the login banner so you can get
 host_type() and firmware_version()
@@ -392,7 +427,7 @@
   my $self = shift;
 
   unless ( $self->SUPER::open(@_) ) {
-    $self->last_error("Couldn't connect to " . $self->Host . ":  $!");
+    $self->last_error("Couldn't connect to " . $self->host . ":  $!");
     return undef;
   }
 
@@ -401,7 +436,7 @@
       -match => '/password: ?$/i',
       -errmode => "return",
     ) ) {
-    $self->last_error("problem connecting to host (" . $self->Host . "): " . 
+    $self->last_error("problem connecting to host (" . $self->host . "): " . 
         $self->lastline);
     return undef;
   }
@@ -415,8 +450,10 @@
 
 =pod
 
-=item login
+=item B<login>
 
+- Login to the AP.
+
 Calls open() if not already connected, then sends the password and sets
 logged_in() if successful
 
@@ -437,7 +474,7 @@
     -match => $self->prompt,
     -errmode => "return",
   ) ) {
-    $self->last_error("login ($self->Host) failed: " . $self->lastline);
+    $self->last_error("login ($self->host) failed: " . $self->lastline);
     return undef;
   }
 
@@ -448,8 +485,11 @@
 
 =pod
 
-=item parse_login_banner
+=item B<parse_login_banner>
 
+- Converts the login_banner to some useful 
+variables.
+
 Takes a login banner (what you get when you first connect to the Trango)
 or reads what is already in login_banner() then parses it and sets
 host_type() and firmware_version() as well as login_banner()
@@ -478,11 +518,15 @@
 
 =pod
 
-=item su_password
+=item B<su_password>
 
-C<su_password('new_password'[, 'suid'])> If no suid is specified,
+- Set the password on SUs connected to the AP.
+
+su_password('new_password'[, 'suid']) If no suid is specified,
 the default is "all".
 
+  $t->su_password('good_pass', 5);
+
 =cut
 
 sub su_password
@@ -506,10 +550,15 @@
 
 =pod
 
-=item su_ipconfig
+=item B<su_ipconfig>
 
-C<su_ipconfig( 'suid', 'new_ip', 'new_subnet', 'new_gateway' )>
+- Change IP configuration on SUs connected to 
+the AP.
 
+su_ipconfig( 'suid', 'new_ip', 'new_subnet', 'new_gateway' )
+
+  $t->su_ipconfig( 5, '10.0.1.5', '255.255.255.0', '10.0.1.1' );
+
 =cut
 
 sub su_ipconfig
@@ -550,15 +599,12 @@
 
 =pod
 
-=item sudb_view
+=item B<sudb_view>
 
-returns a reference to an array of hashes each containing:
+- Returns the output from the sudb view command
 
-  suid
-  type
-  cir
-  mir
-  mac
+returns a reference to an array of hashes each containing these keys
+'suid', 'type', 'cir', 'mir' and 'mac'
 
 =cut
 
@@ -571,7 +617,7 @@
   return undef unless @lines;
 
   unless ($PRIVATE{'Decode'}) {
-    return @lines;
+    return \@lines;
   }
 
   my @sus;
@@ -598,7 +644,7 @@
 
 =pod
 
-=item sudb_add
+=item B<sudb_add>
 
 Takes the following paramaters
 
@@ -610,6 +656,8 @@
 
 and returns true on success or undef otherwise.
 
+  $t->sudb_add($suid, 'reg', $cir, $mir, $mac);
+
 You should save_sudb() after calling this, or your changes  will be lost 
 when the AP is rebooted.
 
@@ -665,11 +713,13 @@
 
 =pod
 
-=item sudb_delete
+=item B<sudb_delete>
 
 Takes either 'all' or the  suid of the su to delete
 and returns true on success or undef otherwise.
 
+  $t->sudb_delete($suid);
+
 You should save_sudb() after calling this, or your changes  will be lost 
 when the AP is rebooted.
 
@@ -691,9 +741,9 @@
 
 =pod
 
-=item sudb_modify
+=item B<sudb_modify>
 
-Takes either the  suid of the su to delete
+Takes either the  suid of the su to change
 as well as what you are changing, either "cir, mir or su2su"
 and returns true on success or undef otherwise.
 
@@ -701,6 +751,8 @@
 
 su2su takes a group id parameter that is in hex.
 
+  $t->sudb_modify($suid, 'cir', 512);
+
 You should save_sudb() after calling this, or your changes  will be lost 
 when the AP is rebooted.
 
@@ -740,8 +792,10 @@
 
 =pod
 
-=item enable_tftpd
+=item B<enable_tftpd>
 
+- enable the TFTP server
+
 runs C<tftpd(args =E<gt> 'on')> and makes sure that Tftpd is now 'listen'ing
 
 =cut
@@ -761,8 +815,10 @@
 
 =pod
 
-=item disable_tftpd
+=item B<disable_tftpd>
 
+- disable the TFTP server
+
 runs C<tftpd(args =E<gt> 'off')> and makes sure that Tftpd is now 'disabled'
 
 =cut
@@ -782,32 +838,49 @@
 
 =pod
 
-=item cmd
+=item B<cmd>
 
+- runs a command on the AP.
+
 This does most of the work.  At the heart, it calls Net::Telnet::cmd()
 but it also does some special stuff for Trango.
 
 Normally returns the last lines from from the command
 
-Also accepts these options:
+If you are using this, rather than one of the "easy" methods above, 
+you probably want to read through the source of this module to see how 
+some of the other commands are called.
 
+In addition to the Net::Telnet::cmd() options, it also accepts these:
+
 I<decode>
+
 - if this is true, then it will send the output lines to _decode_lines()
 and then returns the decoded output
 
+I<no_prompt>
+
+- if this is true, it does not wait for a prompt, so you are not stuck 
+waiting for something that will never happen.
+
 I<cmd_disconnects>
+
 - if this is true, it then sets logged_in() to false, then it will
-close() the connection and then sets is_connected() to false
+close() the connection and set is_connected() to false
 
 I<expect>
+
 - if this is set (usually to 'Success.') it will check for that in the
 last line of output and if it does not, will return undef because the
 command probably failed
 
 I<args>
+
 - a string containing the command line options that are passed to the
 command
 
+	$t->cmd( String => 'exit', no_prompt => 1, cmd_disconnects => 1 );
+
 =cut
 
 sub cmd
@@ -899,7 +972,7 @@
     if ($PRIVATE{'Decode'} && $cfg{'decode'}) {
       return $vals;
     } else {
-      return @lines;
+      return \@lines;
     }
   } else {
     $self->last_error("Error with command ($cfg{'String'}): $last");
@@ -917,6 +990,7 @@
 
   my $key = '';
   my $val = undef;
+  my @vals;
   my $in_key = 0;
   my $in_val = 1;
 
@@ -941,7 +1015,7 @@
           $key =~ s/^\s+//;
           $key =~ s/\s+$//;
 
-          if (defined $val) {
+          if ($val) {
             $val =~ s/^\s+//;
             $val =~ s/\s+$//;
           }
@@ -953,11 +1027,13 @@
             $key = $new . " " . $key;
           }
 
-          $last_key = $key;
           $conf{$key} = $val;
+          $last_key = $key;
           $key = '';
-          $val = '';
-        }
+        } elsif ($val) {
+			push @vals, $val;
+		}
+        $val = '';
 
       } elsif ($c eq ']') {
         $in_val = 1;
@@ -973,7 +1049,20 @@
     }
   }
 
+  unless ($key) {
+    push @vals, $val;
+  }
+
+  if (@vals == 1) {
+    $val = $vals[0];
+  } elsif (@vals) {
+    $val= \@vals;
+  } else {
+    $val = undef;
+  }
+
   if (%conf) {
+    $conf{_pre} = $val if $val;
     return \%conf;
   } else {
     return $val;
@@ -1076,8 +1165,7 @@
 
 =head1 SEE ALSO
 
-Trango Documentation - 
-http://www.trangobroadband.com/support/product_docs.htm
+Trango Documentation - http://www.trangobroadband.com/support/product_docs.htm
 
 L<Net::Telnet>
 
@@ -1098,11 +1186,10 @@
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright (C) 2005 by Andrew Fresh
+Copyright (C) 2005,2006,2007 by Andrew Fresh
 
 This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.8.7 or,
 at your option, any later version of Perl 5 you may have available.
-
 
 =cut