blib/lib/Pick/TCL.pm

filter: Statementstmt 20.0% 58 / 290 Branchbran 11.1% 18 / 162 Conditioncond 8.3% 1 / 12 MC/DCmcdc 0.0% 0 / 7 Subroutinesub 47.8% 11 / 23 Podpod 100% 10 / 10 totaltotal 19.4% 98 / 504 CC 87 SCAR 45.4
CC
87
Cov
17%
spawn
240.0
is_ready
182.0
_bring_up_ssh
132.0
CRAP 93.7
↑ Summary
1 package Pick::TCL;
2  
3 4 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 4 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 4 ▶use Errno;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 4 ▶use IO::Select;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 4 ▶use IO::Socket;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 4 ▶use Socket;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 =head1 NAME
13  
14 Pick::TCL - class to run commands in a Pick TCL shell
15  
16 =head1 VERSION
17  
18 Version 0.06
19  
20 =cut
21  
22 ###################
23 # PACKAGE GLOBALS #
24 ###################
25  
26 4 our $VERSION = '0.06';
27 4 our %_mods;
28  
29 #########################
30 # OPTIONAL DEPENDENCIES #
31 #########################
32  
33 BEGIN
34 4 ▶{
Subroutine BEGIN: called CC=3 SCAR=11.6
35 4 %_mods = ();
36 4 ▶ if (eval { require IPC::Run; })
Branch: 1 branch
BranchTrueFalseTotal
if (eval { do { require IPC::Run } }) 4 0 4
37 {
38 4 $_mods{'local'} = 'IPC::Run';
39 }
40 4 ▶ if (eval { require Net::OpenSSH; })
Branch: 1 branch
BranchTrueFalseTotal
if (eval { do { require Net::OpenSSH } }) 0 4 4
41 {
42 0 $_mods{'remote'} = 'Net::OpenSSH';
43 }
44 }
45  
46 4 ▶if (scalar(keys %_mods) == 0)
Branch: 1 branch
BranchTrueFalseTotal
if (scalar keys %Pick::TCL::_mods == 0) 0 4 4
47 {
48 0 croak "Pick::TCL requires either IPC::Run or Net::OpenSSH";
49 }
50  
51 =head1 SYNOPSIS
52  
53 use Pick::TCL;
54  
55 # Establish connection
56 my $ap = Pick::TCL->new(%options);
57
58 # Execute commands
59 my $output = $ap->exec('TCL.COMMAND PARAMS (OPTIONS)');
60 my $unsanitised = $ap->execraw('TCL.COMMAND PARAMS (OPTIONS)');
61  
62 # Spawn, check & retrieve output of long-running commands
63 $ap->spawn('TCL.COMMAND PARAMS (OPTIONS)')} = 1;
64 # ...
65 do_something_with($ap->output) if $ap->is_ready;
66  
67 # Clean up
68 $ap->logout();
69  
70 =head1 DESCRIPTION
71  
72 C<Pick::TCL> provides a class to run arbitrary B<TCL> (that's
73 I<Terminal Control Language>, not the "other" TCL) commands in a
74 local or remote Pick or Pick-like environment, either synchronously
75 (blocking until execution has completed) or asynchronously.
76  
77 =over 4
78  
79 =item Local connections
80  
81 require either L<IPC::Run> or L<Net::OpenSSH> to be installed and usable.
82  
83 =item Remote connections
84  
85 require L<Net::OpenSSH> to be installed and usable.
86  
87 =back
88  
89 Note that C<Pick::TCL> will croak() if used when neither L<IPC::Run>
90 nor L<Net::OpenSSH> are usable.
91  
92 =cut
93  
94 ###################
95 # Private methods #
96 ###################
97  
98 # Get an ssh link. Returns 1 on success. On failure returns undef
99 # and sets $!
100 sub _bring_up_ssh
101 0 ▶{
Subroutine _bring_up_ssh: not called CC=11 SCAR=48.8
102 0 my $self = shift;
103  
104 # Build connection string
105 0 my %options = %{$$self{'_OPTIONS'}};
106 0 ▶ my $cs = defined($options{'SSHUSER'}) ? $options{'SSHUSER'} : "";
Branch: 1 branch
BranchTrueFalseTotal
defined $options{'SSHUSER'} ? : 0 0 0
107 0 ▶ $cs .= ':'.$options{'SSHPASS'} if defined($options{'SSHPASS'});
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"SSHPASS"} 0 0 0
108 0 ▶ $cs .= '@' unless $cs eq '';
Branch: 1 branch
BranchTrueFalseTotal
unless $cs eq "" 0 0 0
109 0 $cs .= $options{'HOST'};
110 0 ▶ $cs .= ':'.$options{'PORT'} if defined($options{'PORT'});
Branch: 1 branch
BranchTrueFalseTotal
if defined $options{"PORT"} 0 0 0
111  
112 # Survive in Taint mode
113 0 local %ENV;
114 0 $ENV{'PATH'} = "";
115
116 # Find ssh binary
117 0 ▶ unless (defined($options{'SSHCMD'}))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $options{"SSHCMD"}) 0 0 0
118 {
119 0 my $cmd = '';
120 0 foreach my $c (qw[/usr/local/bin/ssh /usr/bin/ssh /bin/ssh])
121 {
122 0 ▶ next unless -x $c;
Branch: 1 branch
BranchTrueFalseTotal
unless -x $c 0 0 0
123 0 $cmd = $c;
124 0 last;
125 }
126 0 ▶ croak "Pick::TCL: can't find ssh" unless $cmd;
Branch: 1 branch
BranchTrueFalseTotal
unless $cmd 0 0 0
127 0 $$self{'_OPTIONS'}->{'SSHCMD'} = $cmd;
128 }
129  
130 # Bring up link
131 croak "Pick::TCL: No usable module found for remote connections"
132 0 ▶ unless $_mods{'remote'};
Branch: 1 branch
BranchTrueFalseTotal
unless $Pick::TCL::_mods{"remote"} 0 0 0
133 0 my $ssh = undef;
134 $ssh = Net::OpenSSH->new($cs, ssh_cmd => $$self{'_OPTIONS'}->{'SSHCMD'},
135 master_stderr_discard => 1,
136 0 timeout => $$self{'_OPTIONS'}->{'TIMEOUT'}, kill_ssh_on_timeout => 1,
137 default_ssh_opts => [ '-oConnectionAttempts=0' ] );
138 0 my $e = $ssh->error;
139 0 ▶ if ($e)
Branch: 1 branch
BranchTrueFalseTotal
if ($e) 0 0 0
140 {
141 0 carp "Pick::TCL: Failed to bring up ssh link: $e";
142 0 $! = &Errno::ETIMEDOUT;
143 0 return undef;
144 }
145 0 $$self{'_SSH'} = \$ssh;
146 0 return 1;
147 }
148  
149 # Tear down & re-establish an ssh link
150 sub _reconnect_ssh
151 0 ▶{
Subroutine _reconnect_ssh: not called CC=2 SCAR=17.9
152 0 my $self = shift;
153 0 ▶ if (ref($$self{'_SSH'}))
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self->{"_SSH"}) 0 0 0
154 {
155 0 ${$$self{'_SSH'}}->DESTROY;
156 }
157 0 delete($$self{'_SSH'});
158 0 return $self->_bring_up_ssh();
159 }
160  
161 # Generate user logon sequence
162 sub _mklogon
163 0 ▶{
Subroutine _mklogon: not called CC=3 SCAR=24.8
164 0 my $self = shift;
165 0 my $logon = '';
166 0 foreach my $k (qw/USER PASS MD MDPASS/)
167 {
168 0 ▶ next unless defined($$self{'_OPTIONS'}->{$k});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_OPTIONS"}{$k} 0 0 0
169 0 $logon .= $$self{'_OPTIONS'}->{$k} . "\n";
170 }
171 0 return $logon;
172 }
173  
174 # Build Pick command
175 sub _mkpickcmd
176 0 ▶{
Subroutine _mkpickcmd: not called CC=1 SCAR=6.9
177 0 my $self = shift;
178 0 my $tclcmd = shift;
179 0 my @args;
180 0 push @args, $$self{'_OPTIONS'}->{'PICKBIN'};
181 0 push @args, $$self{'_OPTIONS'}->{'OPTVM'};
182 0 push @args, $$self{'_OPTIONS'}->{'VM'};
183 0 push @args, $$self{'_OPTIONS'}->{'OPTSILENT'};
184 0 push @args, $$self{'_OPTIONS'}->{'OPTDATA'};
185 0 push @args, $self->_mklogon . $tclcmd . "\r";
186 0 return @args;
187 }
188  
189 =head1 CLASS METHODS
190  
191 =head2 new(%options)
192  
193 Returns a new C<Pick::TCL> object on success (or C<undef>
194 on failure). C<%options> is optional and if present may contain
195 any combination of the following keys:
196  
197 =over 4
198  
199 =item HOST
200  
201 The hostname of the Pick host. If specified, all calls to Pick
202 will be made via a L<Net::OpenSSH> link to the host of the
203 supplied name; if not specified, Pick is presumed to be running
204 on the local host and L<Net::OpenSSH> is not used
205 (unless L<IPC::Run> is missing and C<HOST> is not specified, in
206 which case C<HOST> will be set implicitly to C<localhost>).
207  
208 =item PORT
209  
210 Only valid if C<HOST> is also set. Specifies the TCP port on
211 which to connect to sshd(8) on C<HOST>. Defaults to 22.
212  
213 =item SSHUSER
214  
215 Only valid if C<HOST> is also given. Specifies the Unix username
216 to supply to the remote sshd(8) on C<HOST>. Defaults to the
217 current local username.
218  
219 =item SSHPASS
220  
221 Only valid if C<HOST> is also given. Specifies that password
222 authentication should be used, with the given Unix password.
223 If C<HOST> is given but C<SSHPASS> is not, public key
224 authentication is used instead of password authentication.
225  
226 =item SSHCMD
227  
228 Only valid if C<HOST> is also given. Specifies the full path
229 to the ssh(1) binary (in case L<Net::OpenSSH> cannot find
230 it). If not specified, only F</usr/local/bin/ssh>,
231 F</usr/bin/ssh> and F</bin/ssh> (in that order) are tried.
232  
233 =item TIMEOUT
234  
235 Only valid if C<HOST> is also given. Specifies the maximum
236 number of seconds for which to wait for a response from a
237 remote Pick system.
238  
239 =item VM
240  
241 The name of the Pick virtual machine to which to connect.
242 Defaults to C<pick0>.
243  
244 =item USER
245  
246 The user name with which to log on to C<VM>. Defaults
247 to the value of C<SSHUSER> (or to the current Unix username
248 if C<HOST> is not given).
249  
250 =item PASS
251  
252 The password with which to log on to C<VM>, if required.
253  
254 =item MD
255  
256 The Pick I<master dictionary> to log onto, if required.
257  
258 =item MDPASS
259  
260 Only valid if C<MD> is also given. The password for C<MD>,
261 if required.
262  
263 =item PICKBIN
264  
265 The full path to the Pick binary on C<HOST>. Defaults
266 to F</usr/bin/ap>.
267  
268 =item OPTVM
269  
270 The switch to pass to C<PICKBIN> indicating that the
271 next parameter is a VM / config-file name. Defaults to
272 C<-n>.
273  
274 =item OPTSILENT
275  
276 The switch to pass to C<PICKBIN> in order to suppress
277 logon and logoff messages. Defaults to C<-s>.
278  
279 =item OPTDATA
280  
281 The switch to pass to C<PICKBIN> indicating that the
282 next parameter contains "stacked" data for input to
283 the Pick session. Defaults to C<-d>.
284  
285 =back
286  
287 All keys are optional, with the caveats that if C<PORT>,
288 C<SSHUSER>, C<SSHPASS> and/or C<TIMEOUT> are specified,
289 for those options to take effect C<HOST> must also be
290 specified; and likewise C<MDPASS> has no effect without
291 C<MD>.
292  
293 =head3 Note:
294  
295 new() does not actually try to log on to C<VM> -- where
296 Pick is local, the C<%options> are merely stored in the
297 C<Pick::TCL> object for later use; on the other hand if
298 C<HOST> is set (i.e. Pick is remote), new() will establish
299 a L<Net::OpenSSH> link to C<HOST> or croak() trying.
300  
301 =cut
302  
303 sub new
304 2 ▶{
Subroutine new: called CC=16 SCAR=34.0
Pod documented
305 2 my $class = shift;
306 2 ▶ if (ref($class))
Branch: 1 branch
BranchTrueFalseTotal
if (ref $class) 0 2 2
307 {
308 # Reset existing login
309 0 $class->logout();
310 0 $class = ref($class);
311 }
312 2 my $self = {};
313  
314 # Check/set options
315 2 ▶ croak "Pick::TCL constructor options must be a balanced hash"
Branch: 1 branch
BranchTrueFalseTotal
unless scalar(@_) % 2 == 0 0 2 2
316 unless scalar(@_) % 2 == 0;
317 2 my %options = @_;
318 2 ▶ $options{'VM'} = 'pick0' unless defined($options{'VM'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options{"VM"} 2 0 2
319 2 ▶ unless (defined($options{'USER'}))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $options{"USER"}) 2 0 2
320 {
321 # Default Pick username to remote Unix username if set
322 2 my $u = $options{'SSHUSER'};
323 # Otherwise local username
324 2 ▶ $u = eval { getpwuid($<); } unless defined($u);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $u 2 0 2
325 # Handle platforms without a working getpwuid()
326 2 ▶ $u = getlogin() unless defined($u);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $u 0 2 2
327 }
328 2 ▶ $options{'PICKBIN'} = '/usr/bin/ap' unless defined($options{'PICKBIN'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options{"PICKBIN"} 2 0 2
329 2 ▶ $options{'OPTDATA'} = '-d' unless defined($options{'OPTDATA'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options{"OPTDATA"} 2 0 2
330 2 ▶ $options{'OPTSILENT'} = '-s' unless defined($options{'OPTSILENT'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options{"OPTSILENT"} 2 0 2
331 2 ▶ $options{'OPTVM'} = '-n' unless defined($options{'OPTVM'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options{"OPTVM"} 2 0 2
332 2 ▶ if (defined($options{'TIMEOUT'}))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $options{'TIMEOUT'}) { } 0 2 2
333 {
334 0 $options{'TIMEOUT'} = 0 + $options{'TIMEOUT'};
335 } else {
336 2 $options{'TIMEOUT'} = 15;
337 }
338 2 ▶ if ((not defined($options{'HOST'})) && (not defined($_mods{'local'})))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $options{"HOST"} or defined $Pick::TCL::_mods{"local"}) 0 2 2
Condition33%1/3
defined $options{"HOST"} or defined $Pick::TCL::_mods{"local"}
l!l&&r!l&&!r
020
MC/DC0%0/2
defined $options{"HOST"} or defined $Pick::TCL::_mods{"local"}
defined $options{"HOST"} defined $Pick::TCL::_mods{"local"}
Truth table33%1/3
A or B
A= defined $options{"HOST"}B= defined $Pick::TCL::_mods{"local"}
ABresult
1X1
011
000
339 {
340 # For a local VM, if we're missing IPC::Run, just ssh to the
341 # loopback interface instead
342 0 $options{'HOST'} = 'localhost';
343 }
344 2 $$self{'_OPTIONS'} = \%options;
345 2 bless $self, $class;
346  
347 # Check ssh host reachable
348 2 ▶ if ($options{'HOST'})
Branch: 1 branch
BranchTrueFalseTotal
if ($options{"HOST"}) 0 2 2
349 {
350 0 ▶ return undef unless $self->_bring_up_ssh();
Branch: 1 branch
BranchTrueFalseTotal
unless $self->_bring_up_ssh 0 0 0
351 }
352  
353 2 return $self;
354 }
355  
356 =head1 INSTANCE METHODS
357  
358 =head2 $ap->exec($tclcmd, @input)
359  
360 Executes the Pick B<TCL> command C<$tclcmd> on the Pick VM associated
361 with the C<Pick::TCL> object C<$ap> synchronously and returns the output.
362  
363 In order to cope with the wide variety of terminal settings found on
364 different Pick systems in the wild (or in some cases, even on different
365 ports of the same VM, allocated dynamically...), line endings in the
366 returned output are sanitised: any sequence of one or more control
367 characters (other than tabs) is treated as a single line ending. As a
368 consequence, any consecutive line endings are collapsed.
369  
370 In list context, returns a list of output lines; in scalar context,
371 returns all output lines joined with line feeds.
372  
373 The second parameter, C<@input>, is optional. If specified, its
374 elements, joined with carriage returns, are supplied as input to
375 the B<TCL> session.
376  
377 On caller or Pick error (including if Pick or ssh emit anything
378 on C<stderr>), returns false, sets C<$!> and emits a suitable
379 message. Likewise on B<ssh> error, except that exit codes 11 and 255
380 are ignored, in order to support ancient versions of L<sshd(8)>).
381  
382 croak()s if the call to a local VM fails outright.
383  
384 =head2 $ap->execraw($tclcmd, @input)
385  
386 Does the same thing as the exec() method but without any
387 output sanitisation.
388  
389 This is useful when dealing with binary output, or when consecutive
390 line breaks in output are significant. However, in those circumstances
391 the caller will need to know in advance the pertinent terminal settings
392 of the port to which it is connecting on the target Pick system and do
393 its own filtering of extraneous nulls, form feeds, etc. to suit.
394  
395 =cut
396  
397 sub execraw
398 0 ▶{
Subroutine execraw: not called CC=11 SCAR=48.8
Pod documented
399 0 my $self = shift;
400 0 my $func = 'Pick::TCL::execraw()';
401 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
402 0 ▶ if (scalar(@_) == 0)
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @_ == 0) 0 0 0
403 {
404 0 carp "$func: cowardly refusing to execute a null TCL command";
405 0 $! = &Errno::ENOMSG;
406 0 return undef;
407 }
408 0 my $tclcmd = shift;
409 0 my $input = undef;
410 0 ▶ $input = join "\r", @_ if scalar(@_) > 0;
Branch: 1 branch
BranchTrueFalseTotal
if scalar @_ > 0 0 0 0
411 0 my @args = $self->_mkpickcmd($tclcmd);
412  
413 # Run command
414 0 my ($result, $err) = ("", "");
415 0 $ENV{'PATH'} = "";
416 0 ▶ if (defined($$self{'_SSH'}))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{'_SSH'}) { } 0 0 0
417 {
418 # Remote VM
419 0 ▶ unless ($self->_reconnect_ssh())
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->_reconnect_ssh) 0 0 0
420 {
421 0 carp "$func: $!";
422 0 return undef;
423 }
424 0 my $ssh = $$self{'_SSH'};
425 0 ($result, $err) = $$ssh->capture2({stdin_data => $input}, @args);
426 0 my $serr = $$ssh->error();
427 0 ▶ if (($serr) && ($serr ne 'child exited with code 11')
Branch: 1 branch
BranchTrueFalseTotal
if ($serr and $serr ne "child exited with code 11" and $serr ne "child exited with code 255") 0 0 0
Condition0%0/6
$serr and $serr ne "child exited with code 11" and $serr ne "child exited with code 255"
!ll&&!rl&&r
000
$serr and $serr ne "child exited with code 11"
!ll&&!rl&&r
000
MC/DC0%0/3
$serr and $serr ne "child exited with code 11" and $serr ne "child exited with code 255"
$serr $serr ne "child exited with code 11" $serr ne "child exited with code 255"
Truth table0%0/4
A and B and C
A= $serrB= $serr ne "child exited with code 11"C= $serr ne "child exited with code 255"
ABCresult
0XX0
10X0
1100
1111
428 && ($serr ne 'child exited with code 255'))
429 {
430 0 carp "$func: fatal error: $serr detail ($! $?): $err";
431 0 carp "$func: stdout was $result";
432 0 $! = &Errno::EBADFD;
433 0 return undef;
434 }
435 } else {
436 # Local VM
437 0 ▶ IPC::Run::run(\@args, \$input, \$result, \$err)
Branch: 1 branch
BranchTrueFalseTotal
IPC::Run::run(\@args, \$input, \$result, \$err) or croak("Broken pipe to Pick: $!") 0 0 0
438 or croak "Broken pipe to Pick: $!";
439 0 ▶ if ($err)
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 0 0 0
440 {
441 0 carp "$func: $err";
442 0 $! = &Errno::EBADFD;
443 0 return undef;
444 }
445 }
446 0 return $result;
447 }
448  
449 sub exec
450 0 ▶{
Subroutine exec: not called CC=7 SCAR=40.3
Pod documented
451 0 my $self = shift;
452 0 my $func = 'Pick::TCL::exec()';
453 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
454 0 ▶ if (scalar(@_) == 0)
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @_ == 0) 0 0 0
455 {
456 0 carp "$func: cowardly refusing to execute a null TCL command";
457 0 $! = &Errno::ENOMSG;
458 0 ▶ return wantarray ? () : undef;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
459 }
460  
461 # Get response & sanitise
462 0 ▶ my $raw = $self->execraw(@_) or return wantarray ? () : undef;
Branch: 2 branches
BranchTrueFalseTotal
my $raw = $self->execraw(@_) or return wantarray ? () : undef 0 0 0
wantarray ? : 0 0 0
463 0 my @lines = split /[^\x09\x20-\x7e]+/m, $raw;
464 0 ▶ return wantarray ? @lines : join "\n", @lines;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
465 }
466  
467 =head2 $ap->spawn($tclcmd, @input)
468  
469 Spawns C<$tclcmd> for asynchronous execution on the Pick VM associated
470 with C<$ap>.
471  
472 On success, returns true. On failure, returns C<undef> and sets C<$!>.
473  
474 Output can be retrieved later with the output() method (see below).
475  
476 =cut
477  
478 sub spawn
479 0 ▶{
Subroutine spawn: not called CC=15 SCAR=54.8
Pod documented
480 0 my $self = shift;
481 0 my $func = 'Pick::TCL::spawn()';
482 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
483 0 ▶ if (scalar(@_) == 0)
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @_ == 0) 0 0 0
484 {
485 0 carp "$func: cowardly refusing to execute a null TCL command";
486 0 $! = &Errno::ENOMSG;
487 0 return undef;
488 }
489 0 my $tclcmd = shift;
490 0 my $input = undef;
491 0 ▶ $input = join "\r", @_ if scalar(@_) > 0;
Branch: 1 branch
BranchTrueFalseTotal
if scalar @_ > 0 0 0 0
492 0 my @args = $self->_mkpickcmd($tclcmd);
493  
494 # Run command
495 0 $ENV{'PATH'} = "";
496 0 ▶ if (defined($$self{'_SSH'}))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{'_SSH'}) { } 0 0 0
497 {
498 # Remote VM
499 0 ▶ unless ($self->_reconnect_ssh())
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->_reconnect_ssh) 0 0 0
500 {
501 0 carp "$func: $!";
502 0 return undef;
503 }
504 0 my $ssh = $$self{'_SSH'};
505 0 my ($socket, $pid) = $$ssh->open2socket({}, @args);
506 0 my $serr = $$ssh->error();
507 0 ▶ if ($serr)
Branch: 1 branch
BranchTrueFalseTotal
if ($serr) 0 0 0
508 {
509 0 carp "$func: fatal error: $serr: $! $?";
510 0 $! = &Errno::EBADFD;
511 0 return undef;
512 }
513 0 ▶ if (defined($input))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $input) 0 0 0
514 {
515 0 ▶ while (length($input) > 0)
Branch: 1 branch
BranchTrueFalseTotal
if (length $input > 0) 0 0 0
516 {
517 0 my $bytes = syswrite $socket, $input;
518 0 ▶ unless (defined($bytes))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $bytes) 0 0 0
519 {
520 0 carp "$func: socket write error: $!";
521 0 return undef;
522 }
523 0 $input = susbtr($input, $bytes);
524 }
525 }
526 0 $socket->blocking(0);
527 0 my $set = IO::Select->new();
528 0 $set->add($socket);
529 0 $$self{'_SOCKET'} = $socket;
530 0 $$self{'_SOCKSET'} = $set;
531 0 $$self{'_PID'} = $pid;
532 } else {
533 # Local VM -- IPC::Run cannot detect EOF when spawning asynchronously,
534 # so just fork() & run() instead
535 0 my ($child, $parent);
536 0 ▶ unless (socketpair($child, $parent, AF_UNIX, SOCK_STREAM, PF_UNSPEC))
Branch: 1 branch
BranchTrueFalseTotal
unless (socketpair $child, $parent, 1, 1, 0) 0 0 0
537 {
538 0 carp "$func: socketpair(): $!";
539 0 return undef;
540 }
541 0 $child->autoflush(1);
542 0 $parent->autoflush(1);
543  
544 0 my $pid = fork();
545 0 ▶ unless (defined($pid))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $pid) 0 0 0
546 {
547 0 my $errno = $!;
548 0 carp "$func: fork(): $errno";
549 0 $child->close;
550 0 $parent->close;
551 0 $! = $errno;
552 0 return undef;
553 }
554 0 ▶ if ($pid)
Branch: 1 branch
BranchTrueFalseTotal
if ($pid) 0 0 0
555 {
556 # In parent, act just like we would for a remote VM
557 0 $parent->close;
558 0 my $set = IO::Select->new();
559 0 $set->add($child);
560 0 $$self{'_SOCKET'} = $child;
561 0 $$self{'_SOCKSET'} = $set;
562 0 $$self{'_PID'} = $pid;
563 0 return 1;
564 }
565 # In child, act just like we would for synchronous execution
566 0 $child->close;
567 0 my ($result, $err) = ('', '');
568 0 ▶ my $ran = IPC::Run::run(\@args, \$input, \$result, \$err)
Branch: 1 branch
BranchTrueFalseTotal
my $ran = IPC::Run::run(\@args, \$input, \$result, \$err) or croak("Broken pipe to Pick: $!") 0 0 0
569 or croak "Broken pipe to Pick: $!";
570 0 ▶ croak "$func: $err" if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 0 0
571 0 print $parent $result;
572 0 exit 0;
573 }
574 0 return 1;
575 }
576  
577 =head2 $ap->is_ready
578  
579 Returns true if a previously spawned job has completed. Returns false
580 but defined if the job is still running. Returns C<undef> if the job
581 has aborted or if no job was spawned in the first place.
582  
583 =cut
584  
585 sub is_ready
586 0 ▶{
Subroutine is_ready: not called CC=13 SCAR=52.0
Pod documented
587 0 my $self = shift;
588 0 my $func = 'Pick::TCL::is_ready()';
589 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
590  
591 # Same approach for local or remote VM
592 # -- both use sockets for asyncrhonous execution
593 0 ▶ unless (defined($$self{'_SOCKSET'}))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_SOCKSET"}) 0 0 0
594 {
595 0 $! = &Errno::ENOENT;
596 0 return undef;
597 }
598 0 my $buf = '';
599 0 my $errflag = 0;
600 0 my $errno = 0;
601 0 while(1)
602 {
603 0 my $readable = scalar($$self{'_SOCKSET'}->can_read(0));
604 0 ▶ unless (defined($readable))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $readable) 0 0 0
605 {
606 0 ▶ return 0 unless defined($$self{'_PARTIAL'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_PARTIAL"} 0 0 0
607 0 $errflag++;
608 0 $errno = $!;
609 0 last;
610 }
611 0 ▶ $$self{'_PARTIAL'} = '' unless defined($$self{'_PARTIAL'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_PARTIAL"} 0 0 0
612 0 ▶ last if $readable == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $readable == 0 0 0 0
613 0 my $res = sysread $$self{'_SOCKET'}, $buf, 65536, length($buf);
614 0 ▶ unless (defined($res))
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $res) 0 0 0
615 {
616 0 ▶ carp "$func: socket error: $!" unless $! == &Errno::EAGAIN;
Branch: 1 branch
BranchTrueFalseTotal
unless $! == &Errno::EAGAIN 0 0 0
617 0 $errno = $!;
618 0 $errflag++;
619 0 last;
620 }
621 0 ▶ last if $res == 0;
Branch: 1 branch
BranchTrueFalseTotal
if $res == 0 0 0 0
622 }
623 0 $$self{'_PARTIAL'} .= $buf;
624 0 ▶ if (($errflag) && ($errno == 0))
Branch: 1 branch
BranchTrueFalseTotal
if ($errflag and $errno == 0) 0 0 0
Condition0%0/3
$errflag and $errno == 0
!ll&&!rl&&r
000
MC/DC0%0/2
$errflag and $errno == 0
$errflag $errno == 0
Truth table0%0/3
A and B
A= $errflagB= $errno == 0
ABresult
0X0
100
111
625 {
626 0 return 0;
627 }
628 0 $$self{'_SOCKSET'}->remove($$self{'_SOCKET'});
629 0 $$self{'_SOCKET'}->close;
630 0 waitpid($$self{'_PID'}, 0);
631 0 delete $$self{'_SOCKSET'};
632 0 delete $$self{'_SOCKET'};
633 0 delete $$self{'_PID'};
634 0 ▶ if ($errflag)
Branch: 1 branch
BranchTrueFalseTotal
if ($errflag) 0 0 0
635 {
636 0 $! = $errno;
637 0 return undef;
638 }
639 0 return 1;
640 }
641  
642 =head2 $ap->output
643  
644 =head2 $ap->outputraw
645  
646 Returns the (raw or cooked) output of a previously spawned job if
647 it has completed.
648  
649 Sets C<$!> and returns C<undef> (or, for the cooked form, the empty
650 list if called in list context) if no job has been spawned.
651  
652 =cut
653  
654 sub outputraw
655 0 ▶{
Subroutine outputraw: not called CC=4 SCAR=30.0
Pod documented
656 0 my $self = shift;
657 0 my $func = 'Pick::TCL::outputraw()';
658 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
659 0 ▶ $$self{'_PARTIAL'} = '' unless defined($$self{'_PARTIAL'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_PARTIAL"} 0 0 0
660  
661 # Same approach for local or remote VM
662 # -- both use sockets for asyncrhonous execution
663 0 ▶ $! = &Errno::ENOENT unless defined($$self{'_PARTIAL'});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_PARTIAL"} 0 0 0
664 0 return $$self{'_PARTIAL'};
665 }
666  
667 sub output
668 0 ▶{
Subroutine output: not called CC=5 SCAR=34.0
Pod documented
669 0 my $self = shift;
670 0 my $func = 'Pick::TCL::output()';
671 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
672  
673 # Get response & sanitise
674 0 my $raw = $self->outputraw;
675 0 my $errno = $!;
676 0 ▶ if (defined($raw))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $raw) 0 0 0
677 {
678 0 my @lines = split /[^\x09\x20-\x7e]+/m, $raw;
679 0 ▶ return wantarray ? @lines : join "\n", @lines;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
680 }
681 0 $! = $errno;
682 0 ▶ return wantarray ? () : undef;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
683 }
684  
685 =head2 $ap->partialoutput
686  
687 =head2 $ap->partialoutputraw
688  
689 Returns the (raw or cooked) output of a previously spawned job
690 that may not yet have completed.
691  
692 Returns C<undef> (or, for the cooked form, the empty list if
693 called in list context) if a previously spawned job does not
694 have any output yet or no job has been spawned.
695  
696 =cut
697  
698 sub partialoutputraw
699 0 ▶{
Subroutine partialoutputraw: not called CC=2 SCAR=17.9
Pod documented
700 0 my $self = shift;
701 0 my $func = 'Pick::TCL::partialoutputraw()';
702 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
703 0 return $$self{'_PARTIAL'};
704 }
705  
706 sub partialoutput
707 0 ▶{
Subroutine partialoutput: not called CC=5 SCAR=34.0
Pod documented
708 0 my $self = shift;
709 0 my $func = 'Pick::TCL::partialoutput()';
710 0 ▶ croak "$func is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 0 0
711 0 my $raw = $self->partialoutputraw;
712 0 ▶ if (defined($raw))
Branch: 1 branch
BranchTrueFalseTotal
if (defined $raw) 0 0 0
713 {
714 0 my @lines = split /[^\x09\x20-\x7e]+/m, $raw;
715 0 ▶ return wantarray ? @lines : join "\n", @lines;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
716 }
717 0 ▶ return wantarray ? () : undef;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 0 0
718 }
719
720  
721 =head2 $ap->logout
722  
723 Destroys the connection. Not required to be called explicitly before
724 exit; does nothing when Pick is local.
725  
726 =cut
727  
728 sub logout
729 1 ▶{
Subroutine logout: called CC=3 SCAR=14.2
Pod documented
730 1 my $self = shift;
731 1 ▶ croak "Pick::TCL::logout() is not a class method" unless ref($self);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $self 0 1 1
732 1 ▶ if (ref($$self{'_SSH'}))
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self->{"_SSH"}) 0 1 1
733 {
734 0 my $ssh = $$self{'_SSH'};
735 0 $$ssh->DESTROY();
736 0 delete $$self{'_SSH'};
737 }
738 }
739  
740 =head1 CAVEATS
741  
742 =head2 Escaping metacharacters
743  
744 The commands sent to exec() and execraw() are always interpreted by
745 the Pick B<TCL> interpreter -- so be sure to escape anything that needs
746 escaping in B<TCL> before feeding it to exec() or execraw() (no
747 different from running native).
748  
749 If C<HOST> is set, there's also the remote login shell to consider.
750 C<Pick::TCL> uses L<Net::OpenSSH> (which does auto-escaping of most
751 metacharacters) for the remote link, so this should not cause problems
752 either, so long as the remote user's login shell is set to the Bourne
753 shell, or at least something that's sufficiently compatible with it.
754  
755 Note especially that when C<HOST> is set, parentheses around options
756 to B<TCL> commands must be balanced (even though the Pick B<TCL>
757 interpreter does not normally require that), as unbalanced parentheses
758 will likely confuse the remote shell.
759  
760 =head2 Parallel asynchronous commands
761  
762 Each C<Pick::TCL> object can only spawn() or exec() one B<TCL>
763 command at a time. If the caller needs to spawn() multiple B<TCL>
764 commands in parallel (or exec() a B<TCL> command while waiting
765 for an asynchronous one to complete), it should instantiate a
766 separate C<Pick::TCL> object for each B<TCL> command.
767  
768 =head2 Pick flavours
769  
770 C<Pick::TCL> has only been tested with D3/Linux as the target Pick
771 platform (setting C<PICKBIN> to F</usr/bin/d3>). It should also work
772 unmodified with targets running D3/AIX, D3/SCO or legacy Advanced
773 Pick systems (on any host OS on which an sshd can be found or built).
774  
775 No attempt has been made thus far to cater specifically to other /
776 licensee / "Pick-like" target platforms, although the configurability
777 provided through C<%OPTIONS> may be sufficient to work with some.
778  
779 =head1 AUTHOR
780  
781 Jack Burton, C<< <jack@saosce.com.au> >>
782  
783 =head1 BUGS
784  
785 Please report any bugs or feature requests
786 to C<bug-pick-tcl at rt.cpan.org>, or through the web interface
787 at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pick-TCL>.
788 I will be notified, and then you'll automatically be notified of
789 progress on your bug as I make changes.
790  
791 =head1 ACKNOWLEDGEMENTS
792  
793 Thanks to Jemalong Wool who provided funding for initial development.
794  
795 =head1 LICENSE AND COPYRIGHT
796  
797 Copyright 2013, 2014 Jack Burton.
798  
799 This program is free software; you can redistribute it and/or modify it
800 under the terms of either: the GNU General Public License as published
801 by the Free Software Foundation; or the Artistic License.
802  
803 See http://dev.perl.org/licenses/ for more information.
804  
805 =cut
806  
807 4 1; # End of Pick::TCL
↑ Summary