File Coverage

blib/lib/Net/CLI/Interact/Transport/Base.pm
Criterion Covered Total %
statement 11 11 100.0
branch 1 2 50.0
condition n/a
subroutine 5 5 100.0
pod 1 1 100.0
total 18 19 94.7


line stmt bran cond sub pod time code
1             package Net::CLI::Interact::Transport::Base;
2             { $Net::CLI::Interact::Transport::Base::VERSION = '2.400000' }
3              
4 1     1   635 use Moo;
  1         3  
  1         6  
5 1     1   324 use MooX::Types::MooseLike::Base qw(InstanceOf);
  1         2  
  1         162  
6              
7             with "Net::CLI::Interact::Transport::Role::StripControlChars";
8              
9             BEGIN {
10 1     1 1 12 sub is_win32 { return ($^O eq 'MSWin32') }
11              
12 1 50   1   5 extends (is_win32()
13             ? 'Net::CLI::Interact::Transport::Platform::Win32'
14             : 'Net::CLI::Interact::Transport::Platform::Unix');
15             }
16              
17             {
18             package # hide from pause
19             Net::CLI::Interact::Transport::Options;
20 1     1   126 use Moo;
  1         3  
  1         3  
21             extends 'Net::CLI::Interact::Transport::Platform::Options';
22             }
23              
24             has 'logger' => (
25             is => 'ro',
26             isa => InstanceOf['Net::CLI::Interact::Logger'],
27             required => 1,
28             );
29              
30             1;
31              
32             =pod
33              
34             =head1 NAME
35              
36             Net::CLI::Interact::Transport::Base - Spawns an Interactive CLI Session
37              
38             =head1 DESCRIPTION
39              
40             This module provides a generic cross-platform API with the purpose of
41             interacting with a command line interface.
42              
43             On Windows the L<IPC::Run> module is used and on Unix when L<IO::Pty> is
44             available (it requires a compiler) L<Net::Telnet>, else C<IPC::Run>. In all
45             cases, a program such as openssh is started and methods provided to send and
46             receive data from the interactive session.
47              
48             You should not use this class directly, but instead inherit from it in
49             specific Transport that will set the application command line name, and
50             marshall any runtime options. The OS platform is detected automatically.
51              
52             =head1 INTERFACE
53              
54             =head2 init
55              
56             This method I<must> be called before any other, to bootstrap the application
57             wrapper module (IPC::Run or Net::Telnet). However, via L<Net::CLI::Interact>'s
58             C<cmd>, C<match> or C<find_prompt> it will be called for you automatically.
59              
60             Two attributes of the specific loaded Transport are used. First the
61             Application set in C<app> is of course required, plus the options in the
62             Transport's C<runtime_options> are retrieved, if set, and passed as command
63             line arguments to the Application.
64              
65             =head2 connect_ready
66              
67             Returns True if C<connect> has been called successfully, otherwise returns
68             False.
69              
70             =head2 disconnect
71              
72             Undefines the application wrapper flushes any output data buffer such that
73             the next call to C<cmd> or C<macro> will cause a new connection to be made.
74             Useful if you intentionally timeout a command and end up with junk in the
75             output buffer.
76              
77             =head2 do_action
78              
79             When passed a L<Net::CLI::Interact::Action> instance, will execute the
80             contained instruction on the connected CLI. This might be a command to
81             C<send>, or a regular expression to C<match> in the output.
82              
83             Features of the commands and prompts are supported, such as Continuation
84             matching (and slurping), and sending without an I<output record separator>.
85              
86             On failing to succeed with a Match, the module will time-out (see C<timeout>,
87             below) and raise an exception.
88              
89             Output returned after issuing a command is stored within the Match Action's
90             C<response> and C<response_stash> slots by this method, with the latter then
91             marshalled into the correct C<send> Action by the
92             L<ActionSet|Net::CLI::Interact::ActionSet>.
93              
94             =head2 put( @data )
95              
96             Items in C<@data> are joined together by an empty string and sent as input to
97             the connected program's interactive session.
98              
99             =head2 pump
100              
101             Attempts to retrieve pending output from the connected program's interactive
102             session. Returns true if there is new data available in the buffer, else
103             will time-out and raise a Perl exception. See C<buffer> and C<timeout>.
104              
105             =head2 flush
106              
107             Empties the buffer used for response data returned from the connected CLI, and
108             returns that data as a single text string (possibly with embedded newlines).
109              
110             =head2 timeout( $seconds? )
111              
112             When C<do_action> is polling for response data matching a regular expression
113             Action, it will eventually time-out and throw an exception if nothing matches
114             and no more data arrives.
115              
116             The number of seconds to wait is set via this method, which will also return
117             the current value of C<timeout>. The default value is 10 seconds.
118              
119             =head2 irs_re
120              
121             Returns the Regular Expression reference used to split lines of response from
122             the connected device. In the end, you will only receive data from this module
123             separated by the C<ors> value (by default a newline character). The C<irs_re>
124             is used internally by the module and is:
125              
126             qr/(?:\015\012|\015|\012)/ # i.e. CRLF or CR or LF
127              
128             =head2 ors
129              
130             Line separator character(s) appended to a command sent to the connected CLI.
131             This defaults to a newline on the application's platform.
132              
133             =head2 logger
134              
135             Slot for storing a reference to the application's
136             L<Logger|Net::CLI::Interact::Logger> object.
137              
138             =head2 is_win32
139              
140             Returns true if the current platform is Windows. Can be called as either a
141             class or instance method.
142              
143             =head2 app
144              
145             Location and name of the program used to establish an interactive CLI session.
146             On Unix platforms this will be C<ssh> (openssh), C<telnet>, or C<cu> (serial
147             line). On Windows this must be the C<plink.exe> program.
148              
149             =head2 connect_options
150              
151             Slot for storing a set of options for the specific loaded Transport, passed by
152             the user of Net::CLI::Interact as a hash ref. Do not access this directly, but
153             instead use C<runtime_options> from the specific Transport class.
154              
155             =head2 wrapper
156              
157             Slot for storing the application wrapper instance (IPC::Run or Net::Telnet).
158             Do not mess with this unless you know what you are doing.
159              
160             =head2 buffer
161              
162             After C<pump> returns successfully, the output most recently received is
163             stored in this slot. Do not access this directly, but instead use the C<flush>
164             method.
165              
166             =head2 stash
167              
168             During long sections of output, this slot allows more efficient detection of
169             matches. Older data is placed here, and only the most recent line of data is
170             stored in the C<buffer>. That's why C<flush> is the only way to ensure you get
171             all the output data in one go.
172              
173             =head1 NOTES
174              
175             B<FIXME>: On Unix, when the Telnet transport is selected but C<IP::Pty> is
176             unavailable, C<Net::Telnet> can still be used, but currently C<IPC::Run> is
177             used instead.
178              
179             =cut
180