Pick-TCL

Provides a class to run arbitrary TCL (that's Terminal Control Language,
not the "other" TCL) commands in a local or remote Pick or Pick-like
environment, either synchronously or asynchronously.

Essentially it acts as a wrapper around IPC::Run or Net::OpenSSH,
providing an extra layer of abstraction so that Perl scripts which
need to communicate with a Pick or Pick-like system can use a single
module to do so regardless of whether that system is local or remote.

Beyond that there are only three additional features, as described below.

* Output sanitisation

In the author's experience, many older Pick deployments have been
encountered in the wild configured with non-standard terminal settings
in the same dynamically allocated port range. For various reasons,
those systems' maintainers tend to be highly resistent to making
changes to port terminal settings.

In order to work around the resultant inconsistencies in TCL output,
the exec() method collapses any sequence of one or more control
characters other than tabs into a single newline.

That approach works well except when consecutive newlines in the output
are significant or when binary data are output (both of which are quite
rare in the Pick world). The execraw() method, which does no output
sanitisation, is provided for use in such circumstances.

* Error suppression

Many older Pick deployments still (as of 2013) tend to be found
running on host systems where only long-obsolete releases of
sshd are available. When used with certain (also long-obsolete)
releases of AP or D3, these tend to return false error conditions
at seemingly random intervals.

Of course, the correct solution in such cases is to update to
supported releases of both sshd and D3. However in some legacy
environments that has not proved commercially or politically
feasible.

To work around such circumstances, Pick::TCL ignores exit codes
11 and 255 when the target Pick environment is remote.

* Asynchronous execution

TCL commands can be spawned to run asynchronously, checked for
completion and have their output retrieved on completion (or
partial output earlier).

DEPENDENCIES

To communicate with remote Pick environments, Pick::TCL requires
Net::OpenSSH. Additionally, the remote user's login shell must be set to
a Bourne-compatible shell.

To communicate with local Pick environment, Pick::TCL requires either
IPC::Run or Net::OpenSSH. If IPC::Run is missing (but Net::OpenSSH is
present), any attempt to connect to a local Pick environment is
silently converted into a remote connection with HOST set to localhost.
Otherwise, IPC::Run is used.

Although Pick::TCL works without IPC::Run, IPC::Run is still listed
in BUILD_REQUIRES, as there's no way to specify alternate BUILD_REQUIRES
and we need one or the other in order to pass any tests -- and IPC::Run
seems more likely than Net::OpenSSH to be installed most places. To
install Pick::TCL without installing IPC::Run, just set CPAN's
build_requires_install_policy to 'no'.

Obviously, for Pick::TCL to be of any use, a working (local or remote)
Pick environment is also required.

INSTALLATION

To install this module, run the following commands:

	perl Makefile.PL
	make
	make test
	make install

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc Pick::TCL

You can also look for information at:

    RT, CPAN's request tracker (report bugs here)
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pick-TCL

    AnnoCPAN, Annotated CPAN documentation
        http://annocpan.org/dist/Pick-TCL

    CPAN Ratings
        http://cpanratings.perl.org/d/Pick-TCL

    Search CPAN
        http://search.cpan.org/dist/Pick-TCL/

LICENSE AND COPYRIGHT

Copyright (C) 2013, 2014 Jack Burton

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.