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
$ct->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>) { ... }
$fhandle->close();
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 <brad@bradapp.net>
ClearCase::ExecOpts, ClearCase::Config