/ 
ClearCase-Argv-1.02
River stage one • 2 direct dependents • 3 total dependents
/ ClearCase::Argv

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 XX 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(ctsystem ctexec ctqx);
    ctsystem('pwv');
    my @lsco = ctqx(qw(lsco -avobs -s));
    # Similar to OO example: create label type XX iff it doesn't exist
    ctsystem(qw(mklbtype XX)) if !ctqx({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 overrides the Argv->prog() method to recognize the fact that ClearCase commands have two words, e.g. "cleartool checkout".

It also provides a special method 'ipc_cleartool' which, as the name implies, enables use of the IPC::ClearTool module such that subsequent cleartool commands are sent to a coprocess.

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

OVERRIDDEN METHODS

A few methods of the base class Argv are overridden with modified semantics. These include:

  • prog

    As mentioned above, ClearCase::Argv->prog prepends the word 'cleartool' to each command line.

  • outpathnorm

    On Windows, cleartool's way of handling pathnames is underdocumented and complex. Given a choice, it always prefers and uses the native (\-separated) format. Though it will understand and (sometimes) preserve /-separated pathnames, any path information it adds (notably version-extended data) is always \-separated. For example:

    cleartool ls -s -d x:/vobs_xyz/foo/bar

    will return something like

    x:/vobs_xyz/foo\bar@@\main\3

    Note that the early forward slashes are retained (though the last / before the @@ becomes a \ for some reason, perhaps just a bug in ls). And all version info after the @@ uses \.

    There's no way to determine with certainty which lines in the output of a cleartool command are intended to be interpreted as pathnames and which might just happen to look like one. I.e. the phrase "either/or" might occur in a comment returned by cleartool describe; should we interpret it as a pathname?

    The strategy taken by the Argv->outpathnorm attribute of the base class is to "fix" each line of output returned by the ->qx method iff, when considered as a pathname it refers to an existing file. This can miss pathnames which are not alone on a line, as well as version-extended pathnames within a snapshot view. But having the advantage of knowing about ClearCase, the overridden ClearCase::Argv->outpathnorm extends the above strategy to also modify any strings internal to the line which (a) look like pathnames and (b) contain @@. This errs on the side of caution: it will rarely convert strings in error but may not convert pathnames in formats where they are neither alone on the line nor contain version-extended info. It can also be foiled by pathnames containing whitespace.

    In summary, ClearCase::Argv->outpathnorm will normalize (a) all version-extended pathnames and (b) paths of any type which are alone on a line and refer to an existing filesystem object.

IPC::ClearTool INTERFACE

The 'ipc_cleartool' method creates an IPC::ClearTool object and sends subsequent commands to it. This method is highly context-sensitive:

  • When called with no arguments and a non-void context, it returns the underlying ClearTool object (in case you want to use it directly).

  • When called with a non-zero argument it creates an IPC::ClearTool object; if this fails for any reason a warning is printed and execution continues in 'normal mode'. The warning may be suppressed or turned to a fatal error by specifying different true values; see examples below.

  • When called with an argument of 0, it shuts down any existing ClearTool object; any further executions would revert to 'normal mode'.

Examples

# use IPC::ClearTool if available, else continue silently
ClearCase::Argv->ipc_cleartool(1);
# use IPC::ClearTool if available, else print warning and continue
ClearCase::Argv->ipc_cleartool(2);
# same as above since default == 2
ClearCase::Argv->ipc_cleartool;
# use IPC::ClearTool, die if not available
ClearCase::Argv->ipc_cleartool(3);
# shut down the IPC::ClearTool coprocess
ClearCase::Argv->ipc_cleartool(0);
# Use the IPC::ClearTool object directly
ClearCase::Argv->ipc_cleartool->cmd('pwv');

Typically ipc_cleartool will be used as a class method to specify a place for all cleartool commands to be sent. However, it may also be invoked on an object to associate just that instance with a coprocess.

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(ctsystem ctexec ctqx);
my $cwv = ctqx(pwv -s);
ctsystem('mklbtype', ['-global'], 'FOO') && exit $?>>8;
my @vobs = ctqx({autochomp=>1}, 'lsvob -s');

If you prefer you can override the "real" Perl builtins. This is easier for converting an existing script which makes heavy use of system(), exec(), or qx():

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 ctsystem() and friends handle that. Also, the qx operator cannot be overridden so we use qv() instead.

CAREFUL PROGRAMMERS WANTED

If you're the kind of programmer who tends to execute whole strings such as system("cleartool pwv -s") reflexively or who uses backquotes in a void context, this module won't help you much because it can't easily support those styles. 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 read once. This applies to both class and instance uses. It's done this way to allow the following locutions:

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

This allows you to set up an object with various 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->argv('pwv -s')->qx;
my $exists = $obj->argv('lstype', 'brtype:FOO')->autofail(0)->qx;

Here we keep an object with attrs 'autochomp' and 'autofail' (autofail means to exit on any failure) around and use it to exec whichever commands we want. While checking to see if a type exists, we suppress autofail temporarily. On the next use the object will have both attributes again.

BUGS

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

PORTABILITY

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

FILES

This is a subclass of Argv and thus requires it to be installed. If running in ipc mode it will also need IPC::ClearTool.

SEE ALSO

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

AUTHOR

David Boyce <dsb@boyski.com>

COPYRIGHT

Copyright (c) 1999-2001 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.