Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

ClearCase::Argv
ClearCase-specific subclass of Argv

ClearCase::Argv - ClearCase-specific subclass of 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('-');

    # Run it through a pipe.

    $describe->pipe(sub { print shift; return 1; });

    # 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 ctpipe);

    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");

    ClearCase::Argv->pipecb(sub { print "GOT: " . shift() . "\n"; 1 });

    ctpipe({autochomp => 1},'lsview', ['-l']);

There are more examples in the ./examples subdir that comes with this module. Also, the test script is designed as a demo and benchmark and is a good source for cut-and-paste code.


DESCRIPTION

ClearCase::Argv is a subclass of Argv for use with ClearCase. It exists to provide an abstraction layer over the cleartool command-line interface. A program written to this API can be told to send commands to ClearCase via the standard technique of executing cleartool or via the ClearCase::CtCmd module or via a pipe to cleartool (aka IPC mode) by flipping a switch.

To that end it provides a couple of special methods ctcmd and ipc. The ctcmd method can be used to cause cleartool commands to be run in the current process space using ClearCase::CtCmd. Similarly, ipc will send commands to a cleartool co-process. See the documentation of these modules for details on what they do, and see ALTERNATE EXECUTION INTERFACES below for how to invoke them. Sample scripts are packaged with ClearCase::Argv in ./examples.

As ClearCase::Argv is in most other ways identical to its base class, 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
  • ClearCase::Argv->prog prepends the word cleartool to each command line when in standard (not ->ctcmd or ->ipc) mode.

  • quote
  • The cleartool ``shell'' has its own quoting rules. Therefore, when using ->ctcmd or ->ipc modes, command-line quoting must be adjusted to fit cleartool's rules rather than those of the native system shell, so the ->quote method is extended to handle that case.

  • readonly
  • It's sometimes useful to set the following class attribute:
    
        ClearCase::Argv->readonly('auto');

    This does nothing by itself but it modifies the behavior of the ->noexec attribute: instead of skipping execution of all commands, it only skips commands which modify ClearCase state.

    Consider a script which does an lsview to see if view XYZ exists followed by a mkview to create it if not, and has a -n flag to say show what you would do without doing it, implemented internally by setting ->noexec. Without this setting it wouldn't even do the lsview so you can't find out if it would do the mkview. With it, however, the lsview would be performed while the mkview would be shown but skipped as intended. Running read commands while skipping write commands causes scripts to behave far more realistically in ->noexec mode.

  • outpathnorm
  • On Windows, cleartool's way of handling pathnames is underdocumented, complex, and arguably broken. Apparently, given a choice, cleartool on Windows always prefers and uses the native (\-separated) format. Though it will understand and (mostly) 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 but the last / before the @@ becomes a \, while all version info after the @@ uses \. It looks like CC splits the path into dirname and basename, does whatever it's asked to do, then pastes the path back together using the native separator character before printing it.

    Normalizing pathnames is difficult because there's no way to determine with certainty which lines in the output of a cleartool command are 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 the entire line, when considered as a pathname, 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.

    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 or by a change in the extended naming symbol from @@.

    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.

ADDITIONAL METHODS

These are methods not offered by Argv.

  • comment
  • Any text passed to the ->comment method will be provided to the next cleartool command as a comment. E.g.:
    
        ClearCase::Argv->ci('foo')->comment("Multi-line\nComment")->system;

    This is useful because it takes care of the quoting and other machinations necessary to deal with the different execution methods. For instance in IPC mode the comment will be fed to cleartool on stdin whereas in exec mode it will be passsed on the command line. When supplying text via the comment method it is your responsibility to ensure that the very next command is one which takes a standard ClearCase comment. You may also want to turn off stdout for the same command in order to suppress the comment prompt.


ALTERNATE EXECUTION INTERFACES

The ->ctcmd method allows you to send cleartool commands directly to ClearCase via the CtCmd interface rather than by exec-ing cleartool itself.

When called with no argument it returns a boolean indicating whether CtCmd mode is on or off. When called with a numerical argument, it sets the CtCmd mode as follows: if the argument is 0, CtCmd mode is turned off and subsequent commands are sent to real cleartool via the standard execution interface. With an argument of 1, it attempts to use CtCmd mode. If CtCmd fails to load for any reason it will (silently) run commands via CAL instead. With an argument of 2 the behavior is the same but a warning (``CtCmd not found - using CAL instead'') is printed. With an argument of 3 the warning becomes a fatal error, thus using CtCmd only if the compiled version is installed.

Examples


    # Use CtCmd if available, else continue silently using CAL

    ClearCase::Argv->ctcmd(1);

    # Use CtCmd if available, else print warning and use CAL

    ClearCase::Argv->ctcmd(2);

    # Use CtCmd if available, else die with error msg

    ClearCase::Argv->ctcmd(3);

    # Turn off use of CtCmd

    ClearCase::Argv->ctcmd(0);

Typically ->ctcmd 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 CtCmd.

A similar sequence is observed for ->ipc mode except for the different method name, e.g.:


    # Use IPC if available, else abort

    ClearCase::Argv->ipc(3);

Note: you can tell which mode is in use by turning on the dbglevel attribute. Verbosity styles are as follows:


    + cleartool pwv             # standard (fork/exec)

    +> pwv                      # CtCmd

    => pwv                      # IPC

CtCmd mode is not compatible with the ->ctpipe method. Therefore, when a pipe is requested it will result in a new process created by the traditional execution interface.

A final note on IPC and CtCmd modes: turning on one will automatically, and silently, turn off the other. I.e. the sequence


    ClearCase::Argv->ipc(2);

    ClearCase::Argv->ctcmd(2);

will not throw any exceptions and will leave you in CtCmd mode. The coprocess will be shut down.


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 ctpipe);

        my $cwv = ctqx(pwv -s);

        ctsystem('mklbtype', ['-global'], 'FOO') && exit $? >> 8;

        my @vobs = ctqx({autochomp=>1}, 'lsvob -s');

        ctpipe('lsview', ['-l'], sub { print "GOT: " . shift() . "\n"; 1 });

These interfaces may also be imported via the :functional tag:


        use ClearCase::Argv ':functional';


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 deprecated techniques 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

    $obj1->stdout(0);           # turn off stdout for this object, forever

    $obj2->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 illustrated:


    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 supported ClearCase platforms and versions. It's currently maintained on Solaris 9 and Windows XP with CC 7.0 using Perl5.8.x. Viability on other platforms and/or earlier versions is untestable by me.


FILES

This is a subclass of Argv and thus requires Argv to be installed. ClearCase::CtCmd is required for ctcmd mode.


SEE ALSO

perl(1), Argv, ClearCase::CtCmd


AUTHOR

David Boyce <dsbperl AT boyski.com>


COPYRIGHT

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


GUARANTEE

Double your money back!

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy