File Coverage

lib/Command/Interactive/Interaction.pm
Criterion Covered Total %
statement 16 16 100.0
branch 6 6 100.0
condition n/a
subroutine 6 6 100.0
pod 2 2 100.0
total 30 30 100.0


line stmt bran cond sub pod time code
1             package Command::Interactive::Interaction;
2              
3 7     7   55 use strict;
  7         10  
  7         251  
4 7     7   28 use warnings;
  7         10  
  7         347  
5              
6             our $VERSION = 1.1;
7              
8 7     7   26 use Moose;
  7         8  
  7         34  
9              
10             =head1 NAME
11              
12             Command::Interactive::Interaction - Models a result that may occur during an
13             interactive command invoked by Command::Interactive.
14              
15             =head1 SYNOPSIS
16              
17             This module is used to describe a single expected result (a string or a regex)
18             that can appear in the output of a system command invoked by
19             Command::Interactive. Optionally this class can model the string to be sent in response to the expected string (e.g., a password in response to a password prompt).
20              
21             use Command::Interactive::Interaction;
22             my $password_prompt = Command::Interactive->new({
23             expected_string => 'password:',
24             response => 'secret',
25             });
26              
27             my $result = Command::Interactive->new({
28             interactions => [ $password_prompt ],
29             })-run("ssh user@somehost");
30              
31             =head1 FIELDS
32              
33             =head2 expected_string (REQUIRED)
34              
35             The string (or regular expression) that Command::Interactive should look for in the output of the invoked command. To specify a regular expression, also set C<is_regex> to a true value.
36              
37             =cut
38              
39             has expected_string => (
40             is => 'rw',
41             isa => 'Str',
42             required => 1,
43             );
44              
45             =head2 response
46              
47             Optionally, a response that can be sent after the expected_string is found in the command output. This string will include a newline if C<send_newline_with_response> is true.
48              
49             =cut
50              
51             has response => (
52             is => 'rw',
53             isa => 'Str',
54             );
55              
56             =head2 expected_string_is_regex (DEFAULT: FALSE)
57              
58             Whether the C<expected_string> should be treated as a Perl regular expression.
59              
60             =cut
61              
62             has expected_string_is_regex => (
63             is => 'rw',
64             isa => 'Bool',
65             default => 0,
66             );
67              
68             =head2 send_newline_with_response (DEFAULT: TRUE)
69              
70             Whether to send a newline at the end of the C<response> string when expected_string is discovered.
71              
72             =cut
73              
74             has send_newline_with_response => (
75             is => 'rw',
76             isa => 'Bool',
77             default => 1,
78             );
79              
80             =head2 is_error (DEFAULT: FALSE)
81              
82             Whether expected_string should be considered the indication of an error. If
83             is_error is set to true and Command::Interactive encounters
84             <expected_string>, processing of the invoked command will cease and
85             Command::Interactive will return an error result indicating the discovered value of <expected_string> that was understood to indicate an error.
86              
87             =cut
88              
89             has is_error => (
90             is => 'rw',
91             isa => 'Bool',
92             default => 0,
93             );
94              
95             =head2 is_required (DEFAULT: FALSE)
96              
97             Whether the C<expected_string> must be seen prior to the termination of the
98             command invoked by Command::Interactive. If this field is set to true and
99             C<expected_string> is not encountered prior to the end of the command output,
100             Command::Interactive will return an error result indicating that the command was not successful due to the fact that C<expected_string> was not found.
101              
102             =cut
103              
104             has is_required => (
105             is => 'rw',
106             isa => 'Bool',
107             default => 0,
108             );
109              
110             =head2 max_allowed_occurrences (DEFAULT: 1)
111              
112             The number of times that C<expected_string> can be found before
113             Command::Interactive returns an error. This field exists to prevent infinite loops in which (e.g.) a password is requested over and over. To disable this checking altogether, set C<max_allowed_occurrences> to 0. You may also set it to a higher value if you actually expect the same string to appear more than once.
114              
115             =cut
116              
117             has max_allowed_occurrences => (
118             is => 'rw',
119             isa => 'Int',
120             default => 1,
121             );
122              
123             =head1 METHODS
124              
125             =head2 actual_response_to_send
126              
127             Returns the actual string to send in response to discovering C<expected_string>, including any newlines that might be added to the end of the string.
128              
129             =cut
130              
131             sub actual_response_to_send {
132 4     4 1 8 my $self = shift;
133 4 100       111 return $self->response
    100          
134             ? $self->response . ($self->send_newline_with_response ? "\n" : '')
135             : undef;
136             }
137              
138             =head2 type
139              
140             Returns 'string' or 'regex' based on C<is_regex>. Useful in routines internal to
141             Command::Interactive ewhich create human-readable explanations of failure conditions.
142              
143             =cut
144              
145             sub type {
146 12     12 1 24 my $self = shift;
147 12 100       396 return $self->expected_string_is_regex ? 'regex' : 'string';
148             }
149              
150 7     7   34541 no Moose;
  7         14  
  7         31  
151             __PACKAGE__->meta->make_immutable;
152              
153             1;
154              
155             =head1 AUTHOR
156              
157             Binary.com, <perl@binary.com>
158              
159             =head1 LICENSE
160              
161             This module is free software; you can redistribute it and/or modify it under the
162             same terms as Perl itself.
163              
164             =cut
165