ClearTool - run a bidirectional pipe to a cleartool process

NAME

IPC::ClearTool, ClearTool - run a bidirectional pipe to a cleartool process

SYNOPSIS

  use IPC::ClearTool;

  my $CT = IPC::ClearTool->new;
  $CT->cmd("pwv");
  $CT->cmd("lsview");
  $CT->cmd("lsvob -s");
  for ($CT->stdout) { print }
  $CT->finish;

ALTERNATE SYNOPSES

  use IPC::ClearTool;

  $rc = $CT->cmd("pwv");                # Assign return code to $rc

  $CT->notify;                          # "notify mode" is default;
  $rc = $CT->cmd("pwv");                # same as above

  $CT->store;                           # "Store mode" - hold stderr for
  $rc = $CT->cmd("pwv -X");             # later retrieval via $CT->stderr
  @errs = $CT->stderr;                  # Retrieve it now

  $CT->ignore;                          # Discard all stdout/stderr and
  $CT->cmd("pwv");                      # ignore nonzero return codes

  $CT->cmd("ls foo@@");                 # In void context, store stdout,
                                        # print stderr immediately,
                                        # exit on error.

  my %results = $CT->cmd("pwv");        # Place all results in %results,
                                        # available as:
                                        #   @{$results{stdout}}
                                        #   @{$results{stderr}}
                                        #   @{$results{status}}

  $CT->cmd();                           # Clear all accumulators

  $CT->stdout;                          # In void context, print stored output

DESCRIPTION

This module invokes the ClearCase 'cleartool' command as a child process and opens pipes to its standard input, output, and standard error. Cleartool commands may be sent ``down the pipe'' via the $CT->cmd() method. All stdout resulting from commands is stored in the object and can be retrieved at any time via the $CT->stdout method. By default, stderr from commands is sent directly to the real (parent's) stderr but if the store attribute is set as shown above, stderr will accumulate just like stdout and must be retrieved via $CT->stderr.

If $CT->cmd is called in a void context it will exit on error unless the ignore attribute is set, in which case all output is thrown away and error messages suppressed. If called in a scalar context it returns the exit status of the command. In a list context it returns a hash containing keys stdout, stderr, and <status>.

When used with no arguments and in a void context, $CT->cmd simply clears the stdout and stderr accumulators.

The $CT->stdout and $CT->stderr methods behave much like arrays; when used in a scalar context they return the number of lines currently stored. When used in a list context they return an array containing all currently stored lines, and then clear the internal stack.

The $CT->finish method ends the child process and returns its exit status.

This is only a summary of the documentation. There are more advanced methods for error detection, data return, etc. documented as part of IPC::ChildSafe. Note that IPC::ClearTool is simply a small subclass of ChildSafe; it provides the right defaults to the constructor for running cleartool and adds a few ClearCase-specific methods. In other ways it's identical to ChildSafe, and all ChildSafe documentation applies.

BUGS

Comments
Comments present a special problem. If a comment is prompted for, it will likely hang the child process by interrupting the tag/eot sequencing. So we prefer to pass comments on the command line with -c. Unfortunately, the quoting rules of cleartool are insufficient to allow passing comments with embedded newlines using -c. The result being that there's no clean way to handle multi-line comments.
To work around this, a method $CT->comment is provided which registers a comment to be passed to the next $CT->cmd() command. It's inserted into the stdin stream with a ``\n.\n'' appended. The subsequent command must have a -cq flag, e.g.:
```
    $CT->comment("Here's a\nmultiple line\ncomment");
    $CT->cmd("ci -cq foo.c");
```
If your script hangs and the comment for the last element checked in is "pwd -h", then you were burned by such a sync problem.
UNIX/Win32 Semantics Skew
On UNIX, this module works by running cleartool as a child process. On Windows, the ClearCase Automation Library (a COM API) is used instead. This provides the same interface but be warned that there's a subtle semantic difference! On UNIX you can send a setview command to the child and it will run in the new view while the parent's environment remains unchanged. On Windows there's no subprocess; thus the setview would change the context of the ``parent process''. The same applies to chdir commands. It's unclear which behavior is ``better'' overall, but in any case portable applications must take extra care in using such stateful techniques.
As a partial remedy, a chdir method is provided. This simply does the cd in both parent and child processes in an attempt to emulate the in-process behavior. Emulating an in-process setview is harder because on UNIX, setview is implemented with a fork/chroot/exec sequence so (a) it's hard to know how a single-process setview should behave and (b) I wouldn't know how to do it anyway, especially lacking the privileges required by chroot(2). Of course in most cases you could work around this by using chdir to work in view-extended space rather than a set view.

In some cases the ability to set the child process into a different view or directory is a feature so no attempt is made to stop you from doing that.
Win32::OLE Behavior with IClearTool
Due to the way Win32::OLE works, on Windows the results of each command are passed back as a single string, possibly with embedded newlines. For consistency, in a list context we split this back into lines and return the list.

AUTHOR