The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
ClearCase-Tools-0.01
/ ClearCase::Vob::Info

NAME

ClearCase::Vob::Info - Parse output from Rational's ClearCase "cleartool" command interpreter.

VERSION

This document describes version 0.21, released June, 2004.

This module has been tested with ClearCase and MultiSite versions 4.2 through 6.0.

DEPENDENCIES

Dependencies for this class include the following.

1)  Rational's ClearCase "cleartool" command interpreter.

2)  Additional Perl modules including the following.
    PTools::Loader,  PTools::Proc::Backtick

SYNOPSIS

use ClearCase::Vob::Info;

$ctObj = new ClearCase::Vob::Info;              # "object" methods
$ClearTool = "ClearCase::View::Info";           # "class" methods

$objRef = $ctObj->run( $ClearCaseCmd );         # "object" methods
$objRef = $ctObj->run( $ClearCaseCmd, $matchCriteria );

$objRef = $ClearTool->run( $ClearCaseCmd );     # "class" methods
$objRef = $ClearTool->run( $ClearCaseCmd, $matchCriteria );

$objRef = $ctObj->parse( $text );               # "object" methods
$objRef = $ctObj->parse( @text );

$objRef = new ClearCase::Vob::Info( $text );    # "class" methods
$objRef = new ClearCase::Vob::Info( @text );

$objRef = $ClearTool->parse( $text );           # "class" methods
$objRef = $ClearTool->parse( @text );


$ctObj->getViewContext;      # returns "" or current view name

$ctObj->getView;             # returns result from last getViewContext
$ctObj->inView;              # returns 0 or 1 from last getViewContext
$ctObj->noView;              # returns 0 or 1 from last getViewContext


$ctObj->getVersionContext;   # returns ClearCase version string

$ctObj->atVer( 3 );          # returns 0 or 1 from last getVersionContext
$ctObj->atVer( 6 );

$ctObj->isVer( "3.2" );      # returns 0 or 1 from last getVersionContext
$ctObj->isVer( "2003.06.00" );

DESCRIPTION

This class starts a unique 'cleartool' command process for each and every subcommand that is run. For performance improvements the ClearCase::Proc::ClearTool and MultiSite::Proc::MultiTool classes should be used. These create a persistent process and provide hooks for using this parser class (or another parser).

Given the widely varing types of output generated by the ClearCase and MultiSite systems, these classes could easily violate the Liskov Substitution Principle. Make sure that any methods are available for ALL of the parser Subclasses. See the base class ClearCase::Vob::Info::InfoBase for the currently defined methods.

Liskov Substitution Principle ("LSP"):
"Subclasses should be substitutable for their base classes."

Output from the following cleartool/multitool subcommands is recognized and automatically parsed into unique objects.

                                                             works w/
cleartool commands currently parsed into unique objects     multitool?
----------------------------------------------------------  ----------
ct describe -l [-local] brtype:$branchname                     yes
ct describe -l hlink:Type@LinkID[@/vobtag[/subdir/path]]       yes
ct describe -l [-local] lbtype:$labelname                      yes
ct describe -l [-local] trtype:$triggername                    yes
ct describe -l [-local] replica:${repltag}@$vobtag             yes
ct describe -l [-local] vob:$vobtag                            yes
ct describe -l [-local] { $element | <wildcard> }              yes

ct dump [-l] $element                                          no
ct hostinfo -l                                                 no
ct lshistory [-l] { $element | <wildcard> }                    no
ct lsreplica -l [ -invob $vobtag ]                             yes

ct lstype -l [-local] -kind brtype [ -invob $vobtag ]          yes
ct lstype -l [-local] -kind lbtype [ -invob $vobtag ]          yes
ct lstype -l [-local] -kind trtype [ -invob $vobtag ]          yes
ct lstype -l brtype:${branchname}@${vobtag}                    yes
ct lstype -l lbtype:${labelname}@${vobtag}                     yes
ct lstype -l trtype:${triggername}@${vobtag}                   yes

ct lsview -l [ -properties [ -full ]] [ $viewtag [ ... ]]      no
ct lsview -l [ -host $hostname ]                               no

ct lsvob  -l $vobtag                                           no
ct lsvtree [-s] [-nrecurse] [-all] [-obs] [-merge] $element    no
ct -version                                                    yes
ct -verall                                                     yes

Output from all other commands is placed into a default 'List' object. This is useful for '-short' listings that result in lists of items. See the first code snippet in EXAMPLES section, below.

                                                             works w/
cleartool commands that return a "List" object              multitool?
----------------------------------------------------------  ----------
ct describe -s brtype:$branchname                              yes
ct describe -s replica:${repltag}@$vobtag                      yes
ct lsview -s                                                   no

For commands that do not generate any text output, the result is ignored and no object is created.

To reiterate, the object methods for each resulting object are defined in the base class ClearCase::Vob::InfoBase while each of the various attributes are created by the particular subclasses during parsing. While parsing the resulting output, any unknown or unrecognized text is placed in an attribute and the text is available via the getUnparsed method.

Constructor

new

Create a variable for use as a 'cleartool' command output parser. Functions in this class can be invoked as 'class' or 'object' methods.

$ctObj = new ClearCase::Vob::Info;              # "object" methods
$ClearTool = "ClearCase::View::Info";           # "class" methods

$objRef = new ClearCase::Vob::Info( $text );    # "class" methods
$objRef = new ClearCase::Vob::Info( @text );

Methods

run ( ClearCaseCommand [, MatchCriteria ] )

Run a 'cleartool' command interpreter and parse the output. Remember, a separate cleartool process is created for each command that is run.

$objRef = $ctObj->run( $ClearCaseCmd );         # "object" methods
$objRef = $ctObj->run( $ClearCaseCmd, $matchCriteria );

$objRef = $ClearTool->run( $ClearCaseCmd );     # "class" methods
$objRef = $ClearTool->run( $ClearCaseCmd, $matchCriteria );
parse ( Text )

Attempt to parse arbitrary text w/out running a cleartool process.

$objRef = $ctObj->parse( $text );               # "object" methods
$objRef = $ctObj->parse( @text );

$objRef = new ClearCase::Vob::Info( $text );    # "class" methods
$objRef = new ClearCase::Vob::Info( @text );

$objRef = $ClearTool->parse( $text );           # "class" methods
$objRef = $ClearTool->parse( @text );
getViewContext

Determine if the current process is running under a ClearCase view.

This method performs the correct processing to determine the current view context. It returns the proper View Tag when the current working directory happens to be in a view other than the currently 'set' view name.

Since this adds overhead it is a separate method from the getView method, described below. As such, if a script that uses this class changes the working directory to various View Tags during execution, the getViewContext method should be used to determine the current view context for a given viewspace subdirectory.

Due to the performance penalty, this method must be invoked directly, before calling the following methods.

getView
inView
noView

Determine if the current process is running under a ClearCase view based on the results of the last getViewContext call.

Examples:

$ctObj->getViewContext;  # Determine the view context

$ctObj->getView;         # returns result from last getViewContext
$ctObj->inView;          # returns 0 or 1 from last getViewContext
$ctObj->noView;          # returns 0 or 1 from last getViewContext
getVersionContext

Determine the current ClearCase (or MultiSite) version.

Due to the performance penalty, this method must be invoked directly, before calling the following methods.

getVersion

Return the entire version string obtained from the "-verall" subcommand.

getBaseVer

Return only the major version number obtained from the "-verall" subcommand.

atVer

Determine if the major version is exactly a certain level or not.

isVer

Determine if the entire version string is equal to a specific value.

minVer
atLeastVer

Determine if the major version is at least a certain level or not.

I.e., if the current major version is 4, than minVer (and atLeastVer) will return true for arguments 2, 3 and 4, but will return false for arguments 5 and greater.

Examples:

$ctObj->getVersionContext;   # Determine the version context

$ctObj->atVer( 3 );          # returns 0 or 1 from last getVersionContext
$ctObj->atVer( 6 );

$ctObj->isVer( "3.2" );      # returns 0 or 1 from last getVersionContext
$ctObj->isVer( "2003.06.00" );
getAtriaHome
getAtriaBin
getAtriaHome
getAtriaBin
getAtriaConfig
getAtriaEtc
getAtriaJava
getAtriaLib
getAtriaShip
getAtriaShlib
getClearTool
getMultiTool

Return the current directory paths, relative to AtriaHome. Note that the ATRIAHOME environment variable, when set, will override any attempts by this class to determine the correct value for the AtriaHome directory.

Examples:

$atriaHome = $ctObj->getAtriaHome;
$atriaBin  = $ctObj->getAtriaBin;

$cleartool = $ctObj->getClearTool
$multitool = $ctObj->getMultiTool

INHERITANCE

This class inherits from ClearCase::Vob::Info::InfoBase.

SEE ALSO

See ClearCase::Vob::Info::InfoBase, PTools::Loader and PTools::Proc::Backtick.

AUTHOR

Chris Cobb

COPYRIGHT

Copyright (c) 2002-2004 by Hewlett-Packard. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.