| 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
Condition50%1/2
$_default_backend || ''
MC/DC0%0/1
$_default_backend || ''
$_default_backend
Truth table50%1/2
A
A= $_default_backend
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 114 | 4 | ▶ | return 'WinDebug' if $^O eq 'MSWin32'; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 121 | |||||||||||||||||||||
| 122 | 0 | ▶ | return 'SysctlPoll' if IO::Pty::HalfDuplex::SysctlPoll->can('_is_waiting'); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 123 | 0 | ▶ | return 'PTrace' if IO::Pty::HalfDuplex::PTrace->can('_fork_traced'); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 132 | 6 | ▶ | $args{backend} = ($_default_backend ||= _probe_backends()); | ||||||||||||||||||
|
Condition66%2/3
$_default_backend ||= _probe_backends()
MC/DC0%0/2
$_default_backend ||= _probe_backends()
$_default_backend
_probe_backends()
Truth table66%2/3
A ||= B
A= $_default_backendB= _probe_backends()
| |||||||||||||||||||||
| 133 | } | ||||||||||||||||||||
| 134 | |||||||||||||||||||||
| 135 | 6 | eval "require IO::Pty::HalfDuplex::$args{backend}"; | |||||||||||||||||||
| 136 | 6 | ▶ | die $@ if $@; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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__ | ||||||||||||||||||||