ClearCase::ClearTool, cleartool - Interface for executing cleartool(1) subcommands.


  use ClearCase::ClearTool;

  ## Use an *explicit* 'ClearTool' object to execute 'cleartool' commands
  my $ct = new ClearCase::ClearTool;
     ## get help
     ## different syntax for the same 'lsco' invocation
  $ct->lsco(-recurse, -me, -short, '/vobs/myproj/src');
  $ct->lsco( qw(-recurse -me -short /vobs/myproj/src) );

  ## Use an *implicit* 'ClearTool' object to execute 'cleartool' commands
     ## get help
  cleartool 'help';
     ## different syntax for the same 'lsco' invocation
  cleartool qw(lsco -recurse -me -short /vobs/myproj/src);
  cleartool 'lsco', -recurse, -me, -short, '/vobs/myproj/src';
  cleartool 'lsco', qw(-recurse -me -short /vobs/myproj/src);
  cleartool->lsco(-recurse, -me, -short, '/vobs/myproj/src');
  cleartool->lsco( qw{-recurse -me -short /vobs/myproj/src} );


perl5.004, ClearCase::Config


By default, nothing is exported. The functions cleartool, cleartool_output, cleartool_status, cleartool_success and cleartool_open may be exported upon explicit request.


ClearCase::ClearTool is both a module and a class. As a class, it defines an abstract baseclass and interface for objects that correspond to the cleartool command that is part of ClearCase. A ClearTool object may be created for executing cleartool subcommands.

As a module, ClearCase::ClearTool provides a function cleartool() that may also be used to execute cleartool subcommands. The difference between executing subcommands using the cleartool() function versus invoking methods on a ClearTool object is that the former uses an implicit (or default) ClearTool object while the latter uses an object explicitly created by the user.


By default, the result of invoking a cleartool subcommand method (either implicitly or explicitly) of a ClearTool object will return the standard output of the subcommand:

  my $output = cleartool->ls;

The returned result is a single string corresponding to what the subcommand printed on its standard output (by default, the trailing newline is removed).

If invoked in an array context, rather than returning a lone string, an array of strings is returned (one per line of output):

  my @lines = cleartool->ls;

Each element of the array @output will, by default, have any trailing newline removed before the result is returned to the user.

For the cleartool() function, there is a universal exception to this rule: Whenever cleartool() is invoked with no arguments, it ALWAYS returns a reference to the implicit ClearTool object it is currently using! This makes sense because if no arguments are given, then no (sub)command was executed (so there is no output or exit status to examine). In fact, this is precisely what allows us to invoke cleartool() using both procedural and object syntax, as in:

  my $output = cleartool 'ls';
  $output = cleartool->ls;

The second invocation given above actually invokes the ls() method of the object returned by invoking cleartool() with zero arguments!

Now, back to our story ....

The removal of trailing newlines may be disabled and (re)enabled by specifying the -nochomping option when invoking the cleartool() function, or when invoking a subcommand:

  ## Disable "chomping" of newlines, only lasts for a single invocation
  my $output = cleartool ['-nochomping'], 'ls';

  ## Same as above using an explicit ClearTool object
  $output = cleartool->ls( ['-nochomping'] );

  ## Same as above using an explicit ClearTool object
  $output = $ct->ls( ['-nochomping'] );

The -nochomping keyword is an example of an exec-option: an option that controls the execution or return value of cleartool. Other exec-options can be used to make the return value be the exit-status instead of the subcommand output; a filehandle from which to read the output of the subcommand; or even a boolean value corresponding to whether or not the command returned a 0 exit status for ``success.'' See ClearCase::ExecOpts for a complete description of the name and meaning of all possible exec-options.


For a given cleartool subcommand, exec-options which override any defaults for the subcommand invocation may be specified by giving a list of arguments similar to the list accepted by an ExecOpts constructor, or else an explicit ExecOpts object may be specified.

Note that exec-options must always precede any subcommand options! The exec-options may be passed as an array-ref, in which case the array should look much the same as the argument list to the ClearCase::ExecOpts constructor. It may also be passed as a hash-ref, like the return result from the execopts_parse function. Or it can be passed as a reference to an explicit ClearCase::ExecOpts object. Finally, as a special case, if only one exec-option is needed and the option itself takes no arguments, then it may optionally be specified as the first parameter to a subcommand provided that it uses a '+' suffix instead of '-'. Hence, the following are all equivalent:

   cleartool ['-status'], qw(lsco -short);
   cleartool {'-returns' => 'status'}, qw(lsco -short);
   cleartool ClearCase::Execopts->new('-status'), qw(lsco -short);
   cleartool qw(+status lsco -short);

   cleartool->lsco(['-status'], -short);
   cleartool->lsco({'-returns' => 'status'}, -short);
   cleartool->lsco(ClearCase::Execopts->new('-status'), '-short');
   cleartool->lsco('+status -short');

Any exec-options that are not explicitly specified in a cleartool subcommand invocation will default to the settings in the ExecOpts object that is associated with the corresponding ClearTool object.


The following methods are used to create or initialize a ClearTool object.


Create a new ClearTool object.

    ## Create a new ClearTool object for executing subcommands
    my $ct1 = ClearCase::ClearTool->new;

    ## Same as above, but used a different syntax
    my $ct2 = new ClearCase::ClearTool;

    ## Create new ClearTool object, and have the default return
    ## value for subcommands be a reference to the object rather
    ## than the output.
    my $ct3 = ClearCase::ClearTool->new( +NoChomping );

    ## Create new ClearTool object which uses the 'cleartool' executable
    ## residing in the specified directory.
    my $ct4 = new ClearCase::ClearTool( +ExecPath => '/site_local/bin' );


The following methods may be invoked for a constructed ClearTool object.


Return standard output of the specified subcommand

    my $output_str = $ct->output('subcmd', $arg1, $arg2, @rest);
    my @output_lines = $ct->output("subcmd $arg1 $arg2 @rest");

In a scalar context, this method executes the specified subcommand and returns the output as a single string. In an array context, it returns an array of output lines. If you wish to control whether or not the return value has trailing newlines removed, look at the -chomping and -nochomping exec-options.


Execute a subcommand and return its status, or else the exit-status of the last subcommand executed.

    ## Execute a subcommand and return its status
    $exit_status = $ct->status("subcmd $arg1 $arg2 @rest");

    ## Same thing, but specify the subcommand as a list
    $exit_status = $ct->status('subcmd', $arg1, $arg2, @rest);

    ## Get status of last subcommand executed
    my $exit_status = $ct->status();

The value returned will be similar to that returned by the builtin system function, and contained in the $? variable.

NOTE that this method ignores the -abort exec-option! If auto-abort handling was performed, then the exit-status would only ever be one value upon a successful subcommand execution. Therefore it is assumed that since the exit-status is explicitly requested, the caller would prefer to perform their own ``handling'' based upon the status returned.


Return true if the last subcommand returned an exit-value of zero.

    if ($ct->success) {
       print "Last executed subcommand succeeded!\n";
    else {
       print "Last executed subcommand failed!\n";

This method will compare the exit-status of the last executed subcommand against a value of zero (0). If the comparison is equal, then a true (non-zero) value will be returned. Otherwise a false value (0 or ``'') will be returned.


Return an IO::Handle object for reading the output of a subcommand

   my $fhandle = $ct->open("subcmd $arg1 $arg2 @rest");
   while (<$fhandle>) { ... }

This method will return a filehandle or else a tied handle object that may be used to read the output of the given subcommand line at a time instead of shoving the output into a string or an array all at once. NOTE that the caller is responsible for invoking close() on the returned result. If the subcommand could not be ``opened'' then the undefined value (undef) is returned.


By default, ClearCase::ClearTool exports nothing, however several functions with a ``cleartool'' prefix may be imported if desired. Each one of the importable functions behaves much like a corresponding object method, but uses and implicit default ClearTool object.


Execute a cleartool subcommand or return the ``default'' ClearTool object.

   my $output = cleartool 'ls', '-long';
       ## same as above, but different syntax
   $output = cleartool qw(ls -long);

       ## obtain the corresponding object and run a subcommand
   my $default_ct = cleartool();
   $output = $default_ct->pwv('-short');
       ## same as above, but in a single statement
   $output = cleartool->pwv('-short');

The cleartool() function will treat its parameters as a subcommand name and its arguments (including any exec-options and subcommand options). It will then execute()the subcommand and return the result, as qualified by the specified exec-options for the default ClearTool object. If no arguments are given, then cleartool() returns a reference to the default ClearTool object.


Like cleartool(), but always returns output via the output() method.


Like cleartool(), but always returns status via the status() method.


Like cleartool(), but always returns success via the success() method.


Like cleartool(), but always returns a handle via the open() method.


Brad Appleton <>


ClearCase::ExecOpts, ClearCase::Config