ClearCase::ExecOpts - Execution options for cleartool
use ClearCase::ExecOpts;
my $ct_opts = execopts_parse(
-status,
-chomping,
-execpath => '/usr/atria/local/bin'
);
print "return type is ", $ct_opts{'-returns'}, "\n";
my $ct_cmdline = execopts_cmdline($ct_opts, 'lsco', '-short'); system $ct_cmdline;
or
my $ct_opts = new ClearCase::ExecOpts(
-status,
-chomping,
-execpath => '/usr/atria/local/bin'
);
if (! $ct_opts->getopts('-output')) {
$ct_opts->setopts('-output');
}
## Now $ct_opts can be used with ClearCase::ClearTool ## or with a ClearTool object
perl5.004
execopts_parse and execopts_cmdline
ClearCase::ExecOpts lets users specify and customize the execution options and the type of return value for a corresponding ClearTool object. Users may provide special keywords prefixed by ``-'' or ``+'' to indicate the desired form of return-value for cleartool subcommand, or to indicate special run-time behavior for cleartool subcommands. These keywords are referred to as execution options for ClearCase::ClearTool objects and their derivations (abbreviated as exec-options or exec-opts).
The set of available execution options is given below. Please note that these options may use a prefix of ``+'' instead of the traditional ``-'' prefix if desired. This is so they may be easily distinguished from command-line options to cleartool(1) and its subcommands. Character-case is ignored when recognizing an exec-option.
Some of the exec-options accept an argument; This is indicated by a ``=>'' between the option-name and its argument.
Return the exit status of the subcomand.
Return true if the exit-status of the command indicates success. Return false otherwise.
Return an open file-handle (or tied handle) for reading the output of the subcommand line-by-line.
Use the result of standard output as the return value (this is the default). In a scalar context, all of the output is returned as a single string, with any embedded newlines intact (with the possible exception of the last newline). In an array context, a list of output lines is returned. See the -chomping and -nochomping exec-options regarding the disposition of trailing newlines.
When standard output is to be returned, then this value controls whether or not the returned result is to be ``chomped'' using the chomp built-in. If -chomping is specified (which is the default), then in a scalar context, the last newline (if any) of the resulting output is removed. In an array context, the last newline of each line in the returned list is removed.
Returned unchomped results (trailing newlines intact) when output is being captured.
Specify redirection for standard output of the subcommand. If the string
'&stdnull' is given, then it means output should be suppressed (neither
printed nor captured). If the undefined value (undef) is supplied, it means the same thing as a value of '&stdnull'. If the
string '&stderr' is given then output should be sent to the same place
that diagnostic error messages are currently being directed to. Otherwise,
if the given string begins with '>', '>>', or '|', then standard
output is redirected to the named file or command-filter.
Equivalent to specifying -stdout => undef.
Specify redirection for standard diagnostic error output of the subcommand.
If the string '&stdnull' is given, then it means errors should be
suppressed (neither printed nor captured). If the undefined value (undef) is supplied, it means the same thing as a value of '&stdnull'. If the
string 'stdout' is given then errors should be sent to the same place that
standard output currently being directed to. Otherwise, if the given string
begins with '>' or '>>' then error messages are redirected to the
named file.
Equivalent to specifying -stderr => undef.
If status/success indicator is not being returned, and if an unsuccessful exit-status is returned by the
subcommand, then automatically abort by invoking croak/die with the
specified message text, or else by invoking the referred-to subroutine. If
a hash-ref is given, then it may specify both the message text and the error subroutine by using -errmsg
and -errsub keyword (respectively). A value of undef means do not abort!
If status/success indicator is not being returned, and if an unsuccessful exit-status is returned by the
subcommand, then do not abort! It is equivalent to specifying -abort => undef.
TO BE DETERMINED
TO BE DETERMINED
The file-system path to the executable cleartool command to use. If the given pathname corresponds to a directory, then it is assumed that an executable file
named cleartool resides in that directory. If no -execpath is specified, then the default path to use will be the value of the CLEARTOOL attribute from ClearCase::Config.
If the given pathname is a relative path, then it will be resolved by the native operating system (which usually means looking in the PATH environment variable). As a special case, if a pathname of ``'' (the empty string) is given, then it is assumed to be ``cleartool'' (even if there is a subdirectory named cleartool om the current directory).
## return a hash-ref corresponding to the set of parsed options my $exec_opts = execopts_parse @option_list;
Returns a reference to an associative array (hash) indicating all the exec-option settings. The resulting hash will have the following keys and their corresponding values:
Indicates the type of return value to use. The corresponding value for this key will be a string set to one of ``output'', ``status'', ``success'', or ``open''. These correspond respectively to the exec-options -output, -status, -success, and -open.
The corresponding value will evalute to true if -chomping is in effect, and will evaluate to false otherwise (e.g. -nochomping).
The corresponding value will be the empty string if no explicit value was
supplied for standard output redirection; Otherwise it will be the value
specified to the -stdout exec-option, which will correspond to a filename (preceded by '>' or
'>>'), a command-filter (preceded by '|'), standard-error-output (the
string 'stderr'), or undef
(meaning output is suppressed).
The corresponding value will be the empty string if no explicit value was
supplied for standard error redirection; Otherwise it will be the value
specified to the -stderr exec-option, which will correspond to a filename (preceded by '>' or
'>>'), standard-output (the string 'stdout'), or undef (meaning error messages are suppressed).
The corresponding value will be the empty string or undef if no automatic-aborting is to be performed; otherwise it will be a
hash-ref where the -errmsg key indicates the error message to be printed (if any), and the -errsub key indicated the error-handler (if any) to use instead of die/croak.
The corresponding value will be undef if no special interrupt processing was specified. If interrupts are to be disabled (-nointr) then the value will be the empty string. If interrupts are to be fielded by an interrupt-handler, then the value will be [TO BE DETERMINED] the subroutine that handles the interrupt.
The corresponding value will be the full pathname to the executable that is used to invoke cleartool subcommands.
## return a string for invoking the corresponding cleartool subcommand my $cmd_str = execopts_cmdline($exec_opts, 'lsco -short');
## Same as above but return an array instead my $cmd_argv = execopts_cmdline($exec_opts, 'lsco', '-short');
Returns a string (or an array when in an array context) corresponding to the command-line invocation to use for the given set of exec-options and the given (sub)command and arguments.
Constructs a new ClearCase::ExecOpts object:
## Create a new ExecOpts object for cleartool subcommands
my $ct_opts1 = ClearCase::ExecOpts->new (
-status,
-chomping,
-execpath => '/usr/atria/local/bin'
);
## Same as above, but used a different syntax
my $ct_opts2 = new ClearCase::ExecOpts (
-status,
-chomping,
-execpath => '/usr/atria/local/bin'
);
Queries exec-option settings:
if ($ct_opts->getopts('-chomping')) {
print "removing trailing newlines output\n";
}
my $returns = $ct_opts->getopts('-returns');
print "-returns is $returns\n";
my ($abort, $execpath) = $ct_opts->getopts('-abort', '-execpath');
my %optvals = $ct_opts->getopts();
getopts() will return the value of the specified exec-option. If more than one exec-option is specified, then a list of corresponding exec-option values is returned. If no exec-options are specified, then a hash, of the same form returned by execopts_parse, is returned to the caller.
The arguments to getopts should be the names of one or more exec-options. Since getopts queries exec-option values, none of the exec-option names take any arguments. In particular, this means that:
-returns corresponds to a value that matches
/^(output|status|success|open)$/.
Any other exec-option that takes an argument returns the corresponding argument value.
Any other exec-option that does not take an argument returns a boolean result, based on whether or not that option is set.
So if both -returns and -chomping are specified to getopts, this would correspond to two values: the first would be a string and the second would be a boolean result.
Modifies exec-option settings:
$ct_opts->setopts('-intr' => undef);
if ($ct_opts->getopts('-chomping')) {
$ct_opts->setopts('-nochomping');
}
$ct_opts->setopts('-returns' => 'output');
$ct_opts->setopts('-output', '-execpath' => '/my/local/path/ct');
my %optvals = $ct_opts->getopts();
$ct_opts->setopts( \%optvals );
setopts() will set the specified exec-options. It accepts the same argument syntax as the new constructor. In addition, if the first parameter given is a reference to a list or a hash, then setopts assumes the corresponding hash is of the same form that is returned by execopts_parse, and uses it to reset all the exec-options. This may be useful when you want to restore the exec-options to their original state after modifying them:
my $save_opts = $ct_opts->getopts;
$ct_opts->setopts( qw{ -status -nocapture -nointr } );
## ... do some things using the current settings
## now restore the old settings
$ct_opts->setopts( \%save_opts );
It should be noted that setopts does not return any particular value.
Brad Appleton <brad@bradapp.net>
ClearCase::ClearTool, ClearCase::Config