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::InfoBase

NAME

ClearCase::Vob::Info::InfoBase - Base class for ClearCase::Vob::Info::<module> classes

VERSION

This document describes version 0.18, released October, 2005.

DEPENDENCIES

Dependencies for this class include the following.

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

SYNOPSIS

use "ClearCase::Vob::Info";
$ClearTool = "ClearCase::Vob::Info";

$objRef = $ClearTool->run( "<ClearTool subcommand w/options>" );

$value  = $objRef->get('paramName');

$objRef->set('paramName', "New Value");

DESCRIPTION

This is an abstract base class that defines ALL methods for ALL subclasses. Defining additional methods in subclasses will work, but that violates standard polymorphism rules (substitution principles).

As shown in the SYNOPSIS section, above, objects of this class are not intended to be instantiated directly. This class provides the interface inheritance necessary to keep all subclasses polymorphic.

WARN: This base class is used elsewhere. Be careful when making any changes. For example, this class is also the base for subclass ClearCase::Migrate::Element::ElementBase.

NOTE: The run method in the ClearCase::Vob::Info class will create a new and separate cleartool process for each and every command that is run. To create a persistent cleartool or multitool process see the ClearCase::Proc::ClearTool class.

Constructor

new

Create a reference to a new object of this class. This class is not intended to be instantiated directly. This class is used by designers of various subclasses that parse the output of cleartool and multitool sub-commands.

See the SYNOPSIS section, above, for intended usage. See the Public Methods section, below, for an overview of the intended interface.

Public Methods

get ( Attribute )
getAttr ( Attribute )

Obtain the value for a given attribute. Each object that is a subclass of this class will contain attributes with widely varying names.

Use the dump method, described below, as a quick and easy way to determine what attributes are available in a given object based on this class. This is useful when developing modules that access parsed cleartool/multitool output.

getCmd
getMatch
getElemType

Obtain information, when available, about

The cleartool/multitool command used to generate the current output,

The match criteria used to collect a subset of the current output,

The type of the ClearCase element for which the current object is a
representation.
isaBranch
notBranch

Determine the element type of the current object.

Note that this assumes the appropriate parsing subclass has detected and set this attribute using the "setBranch", "setFile", "setDirectory" or "setSymlink" method as appropriate for the current object.

$objRef->isaBanch;          # will return 1 or 0
$objRef->notBanch;          # will return 1 or 0
isaFile
notFile

Determine the element type of the current object. See additional notes under the isaBranch/notBranch methods, above.

$objRef->isaFile;           # will return 1 or 0
$objRef->notFile;           # will return 1 or 0
isaDirectory
notDirectory

Determine the element type of the current object. See additional notes under the isaBranch/notBranch methods, above.

$objRef->isaDirectory;      # will return 1 or 0
$objRef->notDirectory;      # will return 1 or 0

Determine the element type of the current object. See additional notes under the isaBranch/notBranch methods, above.

$objRef->isaSymlink;        # will return 1 or 0
$objRef->notSymlink;        # will return 1 or 0
isaView
notView

Determine the element type of the current object.

$objRef->isaView;           # will return 1 or 0
$objRef->notView;           # will return 1 or 0
isUnknown
typeUnknown
unknownType

If no element type was set for the current object, then the type is unknown. See additional notes under the isaBranch/notBranch methods, above.

$objRef->isUnknown;         # will return 1 or 0
$objRef->typeUnknown;       # will return 1 or 0
isActive
notActive

Determine if the current View is "active." (This requires that the appropriate parsing subclass detect and set this attribute using the protected setActive method.)

$objRef->isActive;          # will return 1 or 0
$objRef->notActive;         # will return 1 or 0
isCheckedout
notCheckedout

Determine if the current object is "checked out." (This requires that the appropriate parsing subclass detect and set this attribute using the protected setCheckedout method.)

$objRef->isCheckedout;      # will return 1 or 0
$objRef->notCheckedout;     # will return 1 or 0
isObsolete
notObsolete

Determine if the current object is "locked obsolete." (This requires that the appropriate parsing subclass detect and set this attribute using the protected setObsolete method.)

$objRef->isObsolete;        # will return 1 or 0
$objRef->notObsolete;       # will return 1 or 0
isLocked
unLocked
notLocked

Determine if the current object is "locked." (This requires that the appropriate parsing subclass detect and set this attribute using the protected setLocked method.)

$objRef->isLocked;          # will return 1 or 0
$objRef->notLocked;         # will return 1 or 0
getList ( [ ListAttribute ] )
getHash ( [ HashAttribute [, KeyValue ] ] )

Return a reference to (in scalar mode) or a list of (in list mode) values stored in a List or Hash attribute in the current object.

By default the ListAttribute name is 'list', and the HashAttribute name is 'hash'. For HashAttrobutes if a KeyValue is passed, only that particular value (or null) is returned.

count ( [ ListAttribute ] )

Return a zero-based count of the items found in the specified ListAttribute. By default the ListAttribute name is 'list'.

reiterate ( [ ListAttribute ] )

Rewind the iterator associated with a list attribute. When no attribute name is passed as a parameter, the default iterator named list is reset to zero.

$objRef->reiterate;                # rewind iterator for 'list' attribute
$objRef->reiterate( 'dirList' );   # rewind iterator for 'dirList' attribute
iterate ( [ ListAttribute ] )

Iterate through each entry in an attribute list. If no iterator exists for the given ListAttribute, a new iterator is created and initialized to zero upon first access.

Example: Iterate through each subdirectory in a directory object. This example assumes that 1) a dirList attribute exists in the $dirObj object and 2) that this attribute is a reference to a list (array) of subdirectory names.

while (my $dirEnt = $dirObj->iterate('dirList')) {

    print "  directory entry = '$dirEnt'\n";
}

Example: Iterate through each element type entry found in $vobTag via a cleartool command. This example makes use of the default list iterator that, conveniently, just happens to be created by this class when creating the $elemObj shown here.

use ClearCase::Vob::Info;

$ClearTool = "ClearCase::Vob::Info";     

$elemObj = $ClearTool->run( "lstype -local -l -kind eltype -invob $vobTag" );

while( my $elemName = $elemObj->iterate ) {

       $elemInfoObj = $elemObj->get( $elemName );

       next unless $elemInfoObj->unparsed;

       print "Oops: unparsed data in item $elemName\n";

       $errorCount++;
}
print "$errorCount parsing errors\n";

Background for this example: The $elemObj contains a collection of objects that each contain specific informational details pertaining to each eltype (element type) defined in the VOB indicated by $vobTag.

Information for each element type is packaged up as one or more sub-objects during creation of the $elemObj. These are stored in this outter object each in a simple named attribute.

Since multiple objects may exist, the name of each sub-object is collected in the default list attribute. This provides for convenient access via the iterator method.

Iterating through the list attribute simply returns the name of each sub-object that is then retrieved from the outter object. Then the get method is used to fetch each $elemInfoObj stored in the $elemObj.

Working with multiple objects and sub-objects gets a bit confusing at first. An easy way to see the internal workings of the various objects during development is by using the dump method, explained below.

getIterate ( [ ListAttribute ] )
getNextInList ( [ ListAttribute ] )

As noted above, a 'list' of values is often used to keep track of multiple sub-objects stored in a 'container' object. Using the iterate method, above, returns the next 'name' in a list. Usually, in these cases, what we really want is the next sub-object itself and not just its name.

To further complicate things, the programmer sometimes will know that there should only be one item in the list, and s/he just wants the item (object or whatever) that is named by that single value.

This situation resulted in some rather obnoxious syntax, especially since, in these cases, the container object is simply discarded. E.g.:

$elemObj = $ClearTool->run( "desc -l \"$elemName\"" );

$elemObj = $elemObj->get( $elemObj->getList );    # Yuck!

This method, getIterate (a.k.a. getNextInList), along with the next one, below, were added to alleviate such poor syntax. It's quite similar to the iterate method, above. However, this method returns the object (or whatever) that is named by the item in the 'list' we are iterating.

$elemObj = $ClearTool->run( "desc -l \"$elemName\"" );

$elemObj = $elemObj->getIterate;           # A little better!
getFirstInList ( [ ListAttribute ] )

This method combines both the reiterate and getIterate methods to return the object (or whatever) that is named by the first item in an 'iterator list.'

$elemObj = $ClearTool->run( "desc -l \"$elemName\"" );

$elemObj = $elemObj->getFirstInList        # Even better!

This, when used as shown here or combined with the method alias getNextInList, shown above, provides for improved semantics in code that uses this class.

Note that immediately after a call to the reiterate method for a given list attribute, both this method and the getNextInList method will return the value for the first item defined in that list. In other words, this method is only necessary when semantics dictate.

status
stat
err

Return the status and error text, when status is non-zero, of last operation.

($stat,$err) = $objRef->status;

$stat  = $objRef->stat;           # scalar context returns status number
($err) = $objRef->stat;           # array context returns error message

($err) = $objRef->err;
getUnparsed
unparsed

Determine if the current object contains unparsed data. (This requires that the appropriate parsing subclass detect and set this attribute using the 'addUnparsed' method.)

    $objRef->unparsed;          # returns "" or the unparsed
or  $objRef->getUnparsed;       #   portion of the text
warnIfUnparsed
abortIfUnparsed

Generate a warning or abort message. Terminate after abort message.

dump
toStr

Generating debugging output to determine object state.

print $objRef->dump;                # show contents, don't expand refs
print $objRef->dump("expand");      # expand all non-object refs
print $objRef->dump("objects");     # expand all refs to $maxDepth
print $objRef->dump("objects",1);   # expand all refs only to 1st level
print $objRef->dump("objects",9);   # expand all refs to 9th level

By default $maxDepth = 5; objects and references are only expanded down to the 5th level. Beyond that the output is long and difficult to read. As an alternative, select sub-objects and "dump" them separately.

compare

Compare two objects that inherit from this class.

    $diff = $objA cmp $objB;

or  $diff = $objA->compare($objB);
    $diff = $objA->compare($objB,"","",@attributeList);

or  $diff = $objA->compare($objA,$objB);
    $diff = $objA->compare($objA,$objB,"",@attributeList););

Private Methods

addList ( Attribute, Value[s] )
addHash ( Attribute, Key, Value )
addUnparsed ( Text )

These methods are used by various subclasses to add entries to collections of data during the parsing of cleartool/multitool output.

set ( Attribute, Value )
setAttr ( Attribute, Value )
setList ( ListAttribute, Value )
setHash ( HashAttribute, Value )

These methods are used by various subclasses to initialize attributes during the parsing of cleartool/multitool output.

del ( Attribute )
delList ( ListAttribute )
delHash ( HashAttribute )

These methods are available to delete various attributes from the current object.

The del method will delete any attribute that is set while the delList and delHash methods will only delete the attribute if it is currently contains a reference of the corresponding type (list reference or hash reference).

Each of these will methods return the current contents of the named attribute, if any. In addition, if no attribute is currently defined for the given attribute name the delList method will return an empty list reference and the delHash method will return an empty hash reference.

setErr ( Status, TextString )
setError ( Status, TextString )

This method is used to indicate that an internal error state was detected during parsing.

setCmd

When the cleartool/multitool command that was used to generate the current output is known, it is saved in the _cmd attribute.

setMatch ( MatchCriteria )

When match criteria was used to limit the output generated by the cleartool/multitool command, it is saved in the _match attribute.

Match criteria is usually only used in combination with the -s option to a given cleartool/multitool subcommand.

setBranch
setFile
setDirectory
setView
setUnknown

The various parsing subclasses detect and set the _ISA attribute. The value of this attribute can then be tested using public methods described above.

setActive
resetActive

The various parsing subclasses detect and set the _active attribute.

setCheckedout
resetCheckedout

The various parsing subclasses detect and set the _checkedout attribute. During normal processing invoking objects can call the resetCheckedout method if/when the state is known to have changed.

$objRef->setCheckedout;     # flag object as "checkedout"
$objRef->resetCheckedout;   # flag object not "checkedout"
setObsolete
resetObsolete

The various parsing subclasses detect and set the _locked attribute to the value of "Obsolete". During normal processing invoking objects can call the resetObsolete method if/when the state is known to have changed.

$objRef->setObsolete;     # flag object as "obsolete"
$objRef->resetObsolete;   # flag object not "obsolete"
setLocked
resetLocked

The various parsing subclasses detect and set the _locked attribute to the value of "Locked". During normal processing invoking objects can call the resetLocked method if/when the state is known to have changed.

$objRef->setLocked;     # flag object as "locked"
$objRef->resetLocked;   # flag object not "locked"
compareRef
expandRef

Internal methods used when comparing two objects that inherit from this class.

INHERITANCE

Many concrete subclasses inherit from this class. These classes are not intended to be created directly, but via the ClearCase::Vob::Info class.

SEE ALSO

See ClearCase::Vob::Info and ClearCase::Proc::ClearTool.

AUTHOR

Chris Cobb, <chris@ccobb.net>

COPYRIGHT

Copyright (c) 2002-2003 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.