NAME

ClearCase::Argv - ClearCase-specific subclass of Argv

SYNOPSIS

    # OO interface
    use ClearCase::Argv;
    ClearCase::Argv->dbglevel(1);
    # Note how the command, flags, and arguments are separated ...
    my $describe = ClearCase::Argv->new('desc', [qw(-fmt %c)], ".");
    # Run the basic "ct describe" command.
    $describe->system;
    # Run it with with stderr turned off.
    $describe->stderr(0)->system;
    # Run it without the flags.
    $describe->system(-);
    # Create label type iff it doesn't exist
    ClearCase::Argv->new(qw(mklbtype -nc XX))
		if ClearCase::Argv->new(qw(lstype lbtype:XX))->stderr(0)->qx;

    # functional interface
    use ClearCase::Argv qw(ccsystem ccexec ccqx);
    ccsystem('pwv');
    my @lsco = ccqx(qw(lsco -avobs -s));
    # Similar to OO example: create label type iff it doesn't exist
    ccsystem(qw(mklbtype -nc XX)) if !ccqx({stderr=>0}, "lstype lbtype:XX");

There are more examples in the ./examples subdir that comes with this module. Also, the test script is designed as a demo and benchmark; it's probably your best source for cut-and-paste code.

DESCRIPTION

This is a subclass of Argv for use with ClearCase. It basically overrides the prog() method to recognize the fact that ClearCase commands have two words, e.g. "cleartool checkout' or 'multitool lsepoch'.

It also provides a special method 'ipc_cleartool' which, as the name implies, enables use of the IPC::ClearTool module such that all cleartool commands are run as a coprocess. Attempts to use this method on platforms where IPC::ClearTool is not available will result in a warning and execution will continue using traditional fork/exec.

Functionally ClearCase::Argv is identical to its base class, so see "perldoc Argv" for substantial further documentation.

FUNCTIONAL INTERFACE

For those who don't like OO style, or who want to convert existing scripts with the least effort, the execution methods are made available as traditional functions. Examples:

use ClearCase::Argv qw(ccsystem ccexec ccqx);
my $cwv = ccqx(pwv -s);
ccsystem('mklbtype', ['-global'], 'FOO') && exit $?>>8;
my @vobs = ccqx({autochomp=>1}, 'lsvob -s');

or if you prefer you can override the "real" Perl builtins. This is easier for converting a script which already uses system(), exec(), or qx() a lot:

use ClearCase::Argv qw(system exec qv);
my $cwv = qv(cleartool pwv -s);
system('cleartool', 'mklbtype', ['-global'], 'FOO') && exit $?>>8;
my @vobs = qv({autochomp=>1}, 'lsvob -s');

Note that when using an overridden system() et al you must still specify 'cleartool' as the program, whereas ccsystem() and friends handle that.

CAREFUL PROGRAMMERS WANTED

If you're the kind of programmer who tends to execute whole strings such as system("cleartool pwv -s") or who uses backquotes in a void context, this module won't help you much. These are bad habits regardless of whether you use ClearCase::Argv and you should strive to overcome them.

STICKINESS

A subtlety: when an execution attribute is set in a void context, it's "sticky", meaning that it's set until explicitly reset. But in a non-void context the new value is temporary or "non-sticky"; it's pushed on a stack and popped off after being used once. This applies to both class and instance uses. It's done this way to allow the following locutions:

ClearCase::Argv->stdout(0);	# turns off stdout for all objects
$obj->stdout(0);		# turns off stdout for this object, forever
$obj->stdout(0)->system;	# suppresses stdout, this time only

Which allows you to set up an object with some sticky attributes and keep it around, executing it at will and overriding other attrs temporarily. In the example below, note that another way of setting sticky attrs is shown:

my $obj = ClearCase::Argv->new({autofail=>1, autochomp=>1});
my $view = $obj->cmd('pwv -s')->qx;
my $exists = $obj->cmd('lstype', 'brtype:FOO')->autofail(0)->qx;

Here we keep an object with attrs 'autofail' and 'autochomp' around and use it to exec whatever commands we want (autofail means to exit on any failure), but we suppress the autofail attr when we're just looking to see if a type exists yet.

BUGS

I suspect there are still some special cleartool quoting situations unaccounted for in the quote method. This will need to be refined over time. Bug reports or patches gratefully accepted.

PORTABILITY

This module should work on all ClearCase platforms. It's primarily tested on Solaris 7 and NT 4.0, with CC 3.2.1 and 4.0, using Perl5.004 and 5.005. The CAL stuff doesn't work with CC <3.2.1.

AUTHOR

David Boyce <dsb@world.std.com>

Copyright (c) 1999,19100 David Boyce. All rights reserved. This Perl program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), Argv, IPC::ClearTool, IPC::ChildSafe

cpanm ClearCase::Argv

perl -MCPAN -e shell
install ClearCase::Argv