HalfDuplex.pm

filter: Statementstmt 89.6% 26 / 29 Branchbran 37.5% 6 / 16 Conditioncond 60.0% 3 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 100% 5 / 5 Podpod 100% 1 / 1 totaltotal 69.4% 41 / 59 CC 9 SCAR 21.2
CC
9
Cov
70%
_probe_backends
14.8
new
4.2
BEGIN
1.0
CRAP 8.3
« HalfDuplex/SysctlPoll.pm ↑ Summary HalfDuplex/PTrace.pm »
1 #!/usr/bin/env perl
2 # vim: fdm=marker sw=4 et
3 package IO::Pty::HalfDuplex;
4 # POD header {{{
5  
6 =head1 NAME
7  
8 IO::Pty::HalfDuplex - Treat interactive programs like subroutines
9  
10 =head1 SYNOPSIS
11  
12 use IO::Pty::HalfDuplex;
13  
14 my $pty = IO::Pty::HalfDuplex->new;
15  
16 $pty->spawn("nethack");
17  
18 $pty->read;
19 # => "\nNetHack, copyright...for you? [ynq] "
20  
21 $pty->write("nvd");
22 $pty->read;
23  
24 # => "... Velkommen sorear, you are a lawful dwarven Valkyrie.--More--"
25  
26 =head1 DESCRIPTION
27  
28 C<IO::Pty::HalfDuplex> is designed to perform impedence matching between
29 driving programs which expect commands and responses, and driven programs
30 which use a terminal in full-duplex mode. In this vein it is somewhat like
31 I<expect>, but less general and more robust (but see CAVEATS below).
32  
33 This module is used in object-oriented style. IO::Pty::HalfDuplex objects
34 are connected to exactly one system pseudoterminal, which is allocated on
35 creation; input and output are done using methods. The interface is
36 deliberately kept similar to Jesse Luehrs' L<IO::Pty::Easy> module; notable
37 incompatibilities from the latter are:
38  
39 =over
40  
41 =item *
42  
43 The spawn() method reports failure to exec inline, on output followed
44 by an exit. I see no reason why exec failures should be different from post-exec failures such as "dynamic library not found", and it considerably simplifes the code.
45  
46 =item *
47  
48 write() does not immediately write anything, but merely queues data to be released all at once by read(). It does not have a timeout parameter.
49  
50 =item *
51  
52 read() should generally not be passed a timeout, as it finds the end of output automatically.
53  
54 =item *
55  
56 The two-argument form of kill() interprets its second argument in the opposite sense.
57  
58 =back
59  
60 =head1 METHODS
61  
62 =cut
63  
64 # }}}
65 # Imports {{{
66 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
67 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
68  
69 5 ▶use 5.006_002;
Subroutine BEGIN: called CC=1 SCAR=0.0
70  
71 5 our $VERSION = '0.02';
72 # }}}
73 # new {{{
74 # Most of this is handled by IO::Pty, thankfully
75  
76 =head2 new(%args)
77  
78 Allocates and returns a IO::Pty::HalfDuplex object. The named argument
79 'backend' selects a backend, other arguments, if any, are in the backend's
80 documentation. If the backend is not specified, one will be defaulted based
81 on platform, or using C<$ENV{IO_PTY_HALFDUPLEX_BACKEND}> if it exists.
82 Currently supported backends:
83  
84 =over 2
85  
86 =item JobControl
87  
88 Using POSIX job control. Theoretically portable to all UNIXes, in practice
89 bugs require workarounds on many systems. Most BSDs (but not recent Darwin)
90 have a kernel issue which makes this unusably slow (several seconds per read).
91 The default on UNIX.
92  
93 =item SysctlPoll
94  
95 Using BSD-style C<sysctl> process access. The default on FreeBSD, OpenBSD,
96 and NetBSD.
97  
98 =item PTrace
99  
100 Using the highly nonportable I<ptrace> call. Could be ported to most Unixes,
101 but at present only works on i386 and amd64 FreeBSD; other popular platforms
102 support simpler methods.
103  
104 =back
105  
106 =cut
107  
108 5 my $_default_backend = $ENV{IO_PTY_HALFDUPLEX_BACKEND};
109 5 ▶undef $_default_backend unless ($_default_backend || '') =~ /^[A-Za-z0-9_]+$/;
Branch: 1 branch
BranchTrueFalseTotal
unless ($_default_backend || "") =~ /^[A-Za-z0-9_]+$/ 5 0 5
Condition50%1/2
$_default_backend || ''
l!l
05
MC/DC0%0/1
$_default_backend || ''
$_default_backend
Truth table50%1/2
A
A= $_default_backend
Aresult
11
00
110  
111 4 ▶sub _probe_backends {
Subroutine _probe_backends: called CC=6 SCAR=26.9
112 # Only one backend can possibly work for these
113 4 ▶ return 'DOS' if $^O eq 'dos';
Branch: 1 branch
BranchTrueFalseTotal
if $^O eq "dos" 0 4 4
114 4 ▶ return 'WinDebug' if $^O eq 'MSWin32';
Branch: 1 branch
BranchTrueFalseTotal
if $^O eq "MSWin32" 0 4 4
115  
116 # anything else is either unsupported or a unix-a-like
117 # JobControl is the most portable, but is very inefficient
118 # on BSDkin other than Darwin
119  
120 4 ▶ return 'JobControl' unless $^O =~ /bsd/i;
Branch: 1 branch
BranchTrueFalseTotal
unless $^O =~ /bsd/i 4 0 4
121  
122 0 ▶ return 'SysctlPoll' if IO::Pty::HalfDuplex::SysctlPoll->can('_is_waiting');
Branch: 1 branch
BranchTrueFalseTotal
if "IO::Pty::HalfDuplex::SysctlPoll"->can("_is_waiting") 0 0 0
123 0 ▶ return 'PTrace' if IO::Pty::HalfDuplex::PTrace->can('_fork_traced');
Branch: 1 branch
BranchTrueFalseTotal
if "IO::Pty::HalfDuplex::PTrace"->can("_fork_traced") 0 0 0
124 0 return 'JobControl';
125 }
126  
127 6 ▶sub new {
Subroutine new: called CC=4 SCAR=14.2
Pod documented
128 6 my $class = shift;
129 6 my %args = @_;
130  
131 6 ▶ if (! defined $args{backend}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $args{"backend"}) 6 0 6
132 6 ▶ $args{backend} = ($_default_backend ||= _probe_backends());
Condition66%2/3
$_default_backend ||= _probe_backends()
l!l&&r!l&&!r
240
MC/DC0%0/2
$_default_backend ||= _probe_backends()
$_default_backend _probe_backends()
Truth table66%2/3
A ||= B
A= $_default_backendB= _probe_backends()
ABresult
1X1
011
000
133 }
134  
135 6 eval "require IO::Pty::HalfDuplex::$args{backend}";
136 6 ▶ die $@ if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 6 6
137  
138 6 ("IO::Pty::HalfDuplex::" . $args{backend})->new(@_);
139 }
140  
141 # If any XS-based backends were build, we need to load them now.
142 # If not, or if your system doesn't support XS, you can still use
143 # the pure-Perl backends (JobControl and maybe Stupid).
144  
145 5 eval {
146 5 local $SIG{__DIE__};
147  
148 5 require XSLoader;
149 5 &XSLoader::load("IO::Pty::HalfDuplex", $VERSION);
150 };
151  
152 5 1;
153  
154 __END__
« HalfDuplex/SysctlPoll.pm ↑ Summary HalfDuplex/PTrace.pm »