View on
MetaCPAN
Jack Burton > Pick-TCL-0.03 > Pick::TCL

Download:
Pick-TCL-0.03.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.03   Source   Latest Release: Pick-TCL-0.06

NAME ^

Pick::TCL - class to run commands in a Pick TCL shell

VERSION ^

Version 0.03

SYNOPSIS ^

    use Pick::TCL;

    # Establish connection
    my $ap = Pick::TCL->new(%options);
    
    # Execute commands
    my $output = $ap->exec('TCL.COMMAND PARAMS (OPTIONS)');
    my $unsanitised = $ap->execraw('TCL.COMMAND PARAMS (OPTIONS)');

    # Clean up
    $ap->logout();

DESCRIPTION ^

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,

Local connections

require either IPC::Run or Net::OpenSSH to be installed and usable.

Remote connections

require Net::OpenSSH to be installed and usable.

Note that Pick::TCL will croak if used when neither IPC::Run nor Net::OpenSSH are usable.

CLASS METHODS ^

new(%options)

Returns a new Pick::TCL object on success (or undef on failure). %options is optional and if present may contain any combination of the following keys:

HOST

The hostname of the Pick host. If specified, all calls to Pick will be made via a Net::OpenSSH link to the host of the supplied name; if not specified, Pick is presumed to be running on the local host and Net::OpenSSH is not used (unless IPC::Run is missing and HOST is not specified, in which case HOST will be set implicitly to localhost).

PORT

Only valid if HOST is also set. Specifies the TCP port on which to connect to sshd(8) on HOST. Defaults to 22.

SSHUSER

Only valid if HOST is also given. Specifies the Unix username to supply to the remote sshd(8) on HOST. Defaults to the current local username.

SSHPASS

Only valid if HOST is also given. Specifies that password authentication should be used, with the given Unix password. If HOST is given but SSHPASS is not, public key authentication is used instead of password authentication.

SSHCMD

Only valid if HOST is also given. Specifies the full path to the ssh(1) binary (in case Net::OpenSSH cannot find it). If not specified, only /usr/local/bin/ssh, /usr/bin/ssh and /bin/ssh (in that order) are tried.

VM

The name of the Pick virtual machine to which to connect. Defaults to pick0.

USER

The user name with which to log on to VM. Defaults to the value of SSHUSER (or to the current Unix username if HOST is not given).

PASS

The password with which to log on to VM, if required.

MD

The Pick master dictionary to log onto, if required.

MDPASS

Only valid if MD is also given. The password for MD, if required.

PICKBIN

The full path to the Pick binary on HOST. Defaults to /usr/bin/ap.

OPTVM

The switch to pass to PICKBIN indicating that the next parameter is a VM / config-file name. Defaults to -n.

OPTSILENT

The switch to pass to PICKBIN in order to suppress logon and logoff messages. Defaults to -s.

OPTDATA

The switch to pass to PICKBIN indicating that the next parameter contains "stacked" data for input to the Pick session. Defaults to -d.

All keys are optional, with the caveats that if PORT, SSHUSER and/or SSHPASS are specified, for those options to take effect HOST must also be specified; and likewise MDPASS has no effect without MD.

Note:

new() does not actually try to log on to VM -- where Pick is local, the %options are merely stored in the Pick::TCL object for later use; on the other hand if HOST is set (i.e. Pick is remote), new() will establish a Net::OpenSSH link to HOST or croak() trying.

INSTANCE METHODS ^

$ap->exec($tclcmd, @input)

Executes the Pick TCL command $tclcmd on the Pick VM associated with the Pick::TCL object $ap and returns the output.

In order to cope with the wide variety of terminal settings found on different Pick systems in the wild (or in some cases, even on different ports of the same VM, allocated dynamically...), line endings in the returned output are sanitised: any sequence of one or more control characters (other than tabs) is treated as a single line ending. As a consequence, any consecutive line endings are collapsed.

In list context, returns a list of output lines; in scalar context, returns all output lines joined with line feeds.

The second parameter, @input, is optional. If specified, its elements, joined with carriage returns, are supplied as input to the TCL session.

On caller or Pick error (including if Pick or ssh emit anything on stderr), returns false, sets $! and emits a suitable message. Likewise on ssh error, except that exit codes 11 and 255 are ignored, in order to support ancient versions of sshd(8)).

croak()s if the call to a local VM fails outright.

$ap->execraw($tclcmd, @input)

Does the same thing as the exec() method but without any output sanitisation.

This is useful when dealing with binary output, or when consecutive line breaks in output are significant. However, in those circumstances the caller will need to know in advance the pertinent terminal settings of the port to which it is connecting on the target Pick system and do its own filtering of extraneous nulls, form feeds, etc. to suit.

$ap->logout()

Destroys the connection. Not required to be called explicitly before exit; does nothing when Pick is local.

CAVEATS ^

Escaping metacharacters

The commands sent to exec() and execraw() are always interpreted by the Pick TCL interpreter -- so be sure to escape anything that needs escaping in TCL before feeding it to exec() or execraw() (no different from running native).

If HOST is set, there's also the remote login shell to consider. Pick::TCL uses Net::OpenSSH (which does auto-escaping of most metacharacters) for the remote link, so this should not cause problems either, so long as the remote user's login shell is set to the Bourne shell, or at least something that's sufficiently compatible with it.

Note especially that when HOST is set, parentheses around options to TCL commands must be balanced (even though the Pick TCL interpreter does not normally require that), as unbalanced parentheses will likely confuse the remote shell.

Pick flavours

Pick::TCL has only been tested with D3/Linux as the target Pick platform (setting PICKBIN to /usr/bin/d3). It should also work unmodified with targets running D3/AIX, D3/SCO or legacy Advanced Pick systems (on any host OS on which an sshd can be found or built).

No attempt has been made thus far to cater specifically to other / licensee / "Pick-like" target platforms, although the configurability provided through %OPTIONS may be sufficient to work with some.

AUTHOR ^

Jack Burton, <jack@saosce.com.au>

BUGS ^

Please report any bugs or feature requests to bug-pick-tcl at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pick-TCL. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS ^

Thanks to Jemalong Wool who provided funding for initial development.

LICENSE AND COPYRIGHT ^

Copyright 2013 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.

syntax highlighting: