3 =head1 NAME $RCSfile: Element.pm,v $
5 Object oriented interface to Clearcase Elements
13 Andrew DeFaria <Andrew@ClearSCM.com>
21 Thu Dec 29 12:07:59 PST 2005
25 $Date: 2011/11/16 19:46:13 $
31 Provides access to information about Clearcase Elements.
33 my $element = new Clearcase::Element (pname => "element");
35 display "Element:\t" . $element->pname;
36 display "Version:\t" . $element->version;
37 display "Pred:\t\t" . $element->pred;
39 display "Activities:";
41 if (my %activities = $element->activities) {
42 display "\t\t$_: $activities{$_}" foreach (keys %activities);
47 display "Attributes:";
49 if (my %attributes = $element->attributes) {
50 display "\t\t$_=$attributes{$_}" foreach (keys %attributes);
55 display "Hyperlinks:";
57 if (my @hyperlinks = $element->hyperlinks) {
58 display "\t\t$_" foreach (@hyperlinks);
65 if ($element->comments) {
66 display "\t\t" . $element->comments;
71 display "Create_date:\t" . $element->create_date;
72 display "User:\t\t" . $element->user;
73 display "Group:\t\t" . $element->group;
74 display "User_mode:\t" . $element->user_mode;
75 display "Group_mode:\t" . $element->group_mode;
76 display "Other_mode:\t" . $element->other_mode;
77 display "Mode:\t\t" . $element->mode;
81 if (my @labels = $element->labels) {
82 display "\t\t$_" foreach (@labels);
87 display "Rule:\t\t" . $element->rule;
88 display "Xname:\t\t" . $element->xname;
92 This module implements a Clearcase Element object.
96 The following routines are exported:
100 package Clearcase::Element;
109 sub collapseOverExtendedVersionPathname ($) {
110 my ($versionStr) = @_;
114 =head2 collapseOverExtendedVersionPathname
116 This utility function will collapse an "over extended" version pathname. These
117 over extended pathnames can occur when we are not operating in the UCM view
118 from which the version was generated. Clearcase gives us enormous,technically
119 correct but hard to read, view/vob extended path names. Here's an example
120 (broken by lines for readability):
122 /vob/component/branch1@@/main/branch1_Integration/1/src/main/branch1_
123 /2/com/main/branch1_Integration/2/company/main/branch1_Integration/2/
124 ManagerPlatform/main/branch1_Integration/2/nma/main/
125 branch1_Integration/devbranch_17/1/common/main/devbranch_17/3/exception/
126 main/mainline/devbranch_r17/1/Exception.java/main/mainline/1
128 We want this to read:
130 element: /vob/component/src/com/company/ManagerPlatform/nma/
131 common/exception/Exception.java
132 version: /main/mainline/1
136 =for html <blockquote>
142 This is the over extended version pathname
146 =for html </blockquote>
150 =for html <blockquote>
156 A hash containing the element's name and version string collapsed
160 =for html </blockquote>
167 $versionStr =~ s/\\/\//g;
169 my ($name, $version) = split /$Clearcase::SFX/, $versionStr;
172 extended_name => $versionStr,
178 unless $element{version};
180 while ($element{version} =~ s/.*?\/\d+\/(.*?)\///) {
181 $element{name} .= "/$1";
184 $element{version} = "/$element{version}"
185 if $element{version} !~ /^\//;
188 } # collapseOverExtendedVersionPathname
191 my ($class, $pname) = @_;
197 Construct a new Clearcase Element object.
201 =for html <blockquote>
209 =for html </blockquote>
213 =for html <blockquote>
217 =item Clearcase Element object
221 =for html </blockquote>
229 my ($version, $rule);
231 my ($status, @output) = $Clearcase::CC->execute ("ls -d $pname");
236 # Sometimes ls -d puts out more than one line. Join them...
237 if ((join ' ', @output) =~ /^.*\@\@(\S+)\s+Rule: (.*)$/m) {
242 $self->{rule} = $rule;
243 $self->{version} = $version;
250 # Get information that can only be gotten with describe -long. These fields
251 # lack a -fmt option.
253 my ($status, @output) = $Clearcase::CC->execute (
254 "describe -long $self->{pname}"
264 $section = 'hyperlinks';
266 } elsif (/Attached activities:/) {
267 $section = 'activities';
272 if ($section eq 'activities') {
273 if (/activity:(.*)\s+\"(.*)\"/) {
274 ${$self->{activities}}{$1} = $2;
276 } elsif ($section eq "hyperlinks") {
278 push @{$self->{hyperlinks}}, $1;
285 if (/User : \S+\s*: (.*)/) {
286 $self->{user_mode} = $1;
287 } elsif (/Group: \S+\s*: (.*)/) {
288 $self->{group_mode} = $1;
289 } elsif (/Other:\s+: (.*)/) {
290 $self->{other_mode} = $1;
294 # Change modes to numeric
297 $self->{mode} += 400 if $self->{user_mode} =~ /r/;
298 $self->{mode} += 200 if $self->{user_mode} =~ /w/;
299 $self->{mode} += 100 if $self->{user_mode} =~ /x/;
300 $self->{mode} += 40 if $self->{group_mode} =~ /r/;
301 $self->{mode} += 20 if $self->{group_mode} =~ /w/;
302 $self->{mode} += 10 if $self->{group_mode} =~ /x/;
303 $self->{mode} += 4 if $self->{other_mode} =~ /r/;
304 $self->{mode} += 2 if $self->{other_mode} =~ /w/;
305 $self->{mode} += 1 if $self->{other_mode} =~ /x/;
317 Returns a hash of activity name/value pairs
321 =for html <blockquote>
329 =for html </blockquote>
333 =for html <blockquote>
337 =item Hash of activity name/value pairs
341 =for html </blockquote>
346 unless $self->{activities};
348 return $self->{activities} ? %{$self->{activities}} : ();
358 Returns a hash of attribute name/value pairs
362 =for html <blockquote>
370 =for html </blockquote>
374 =for html <blockquote>
378 =item Hash of attribute name/value pairs
382 =for html </blockquote>
386 $self->updateElementInfo
387 unless $self->{attributes};
389 return %{$self->{attributes}};
399 Returns the comments associated with the current version element.
403 =for html <blockquote>
411 =for html </blockquote>
415 =for html <blockquote>
423 =for html </blockquote>
427 $self->updateElementInfo
428 unless $self->{comments};
430 return $self->{comments};
440 Returns the date of creation of the element.
444 =for html <blockquote>
452 =for html </blockquote>
456 =for html <blockquote>
464 =for html </blockquote>
468 $self->updateElementInfo
469 unless $self->{create_date};
471 return $self->{create_date};
481 Returns the group of the element.
485 =for html <blockquote>
493 =for html </blockquote>
497 =for html <blockquote>
505 =for html </blockquote>
509 $self->updateElementInfo
510 unless $self->{group};
512 return $self->{group};
522 Returns the group mode of the element
526 =for html <blockquote>
534 =for html </blockquote>
538 =for html <blockquote>
546 =for html </blockquote>
551 unless $self->{group_mode};
553 return $self->{group_mode};
563 Returns a hash of hyperlink name/value pairs
567 =for html <blockquote>
575 =for html </blockquote>
579 =for html <blockquote>
583 =item Hash of hyperlink name/value pairs
587 =for html </blockquote>
592 unless $self->{hyperlinks};
594 return @{$self->{hyperlinks}}
604 Returns an array of labels
608 =for html <blockquote>
616 =for html </blockquote>
620 =for html <blockquote>
624 =item Array of labels
628 =for html </blockquote>
632 $self->updateElementInfo
633 unless $self->{labels};
635 return @{$self->{labels}};
645 Returns the numeric mode representing the element's access mode
649 =for html <blockquote>
657 =for html </blockquote>
661 =for html <blockquote>
665 =item Array of activities
669 =for html </blockquote>
674 unless $self->{mode};
676 return $self->{mode};
686 Returns the mode for other for the element.
690 =for html <blockquote>
698 =for html </blockquote>
702 =for html <blockquote>
706 =item A string repesenting the other mode
710 =for html </blockquote>
715 unless $self->{other_mode};
717 return $self->{other_mode};
727 Returns the pname of the element.
731 =for html <blockquote>
739 =for html </blockquote>
743 =for html <blockquote>
751 =for html </blockquote>
755 return $self->{pname};
765 Returns the predecessor version of this element
769 =for html <blockquote>
777 =for html </blockquote>
781 =for html <blockquote>
785 =item Predecessor version
789 =for html </blockquote>
793 $self->updateElementInfo
794 unless $self->{pred};
796 return $self->{pred};
806 Returns the config spec rule that selected this element's version.
810 =for html <blockquote>
818 =for html </blockquote>
822 =for html <blockquote>
830 =for html </blockquote>
834 return $self->{rule};
844 Returns the element's type
848 =for html <blockquote>
856 =for html </blockquote>
860 =for html <blockquote>
868 =for html </blockquote>
872 $self->updateElementInfo
873 unless $self->{type};
875 return $self->{type};
885 Returns the element's object kind
889 =for html <blockquote>
897 =for html </blockquote>
901 =for html <blockquote>
905 =item element's object kind
909 =for html </blockquote>
913 $self->updateElementInfo
914 unless $self->{objkind};
916 return $self->{objkind};
926 Returns the element's OID
930 =for html <blockquote>
938 =for html </blockquote>
942 =for html <blockquote>
950 =for html </blockquote>
954 $version .= $Clearcase::SFX
955 unless $version =~ /$Clearcase::SFX$/;
957 my ($status, @output) = $Clearcase::CC->execute ('dump "' . $version . '"');
962 @output = grep {/^oid=/} @output;
964 if ($output[0] =~ /oid=(.+?)\s+/) {
976 Returns the username of the owner of this element.
980 =for html <blockquote>
988 =for html </blockquote>
992 =for html <blockquote>
1000 =for html </blockquote>
1004 $self->updateElementInfo
1005 unless $self->{user};
1007 return $self->{user};
1017 Returns the mode for the user for the element.
1021 =for html <blockquote>
1029 =for html </blockquote>
1033 =for html <blockquote>
1037 =item A string repesenting the other mode
1041 =for html </blockquote>
1046 unless $self->{user_mode};
1048 return $self->{user_mode};
1058 Returns this element's version
1062 =for html <blockquote>
1070 =for html </blockquote>
1074 =for html <blockquote>
1082 =for html </blockquote>
1086 return $self->{version};
1096 Returns the view extended path name (xname) of an element version.
1100 =for html <blockquote>
1108 =for html </blockquote>
1112 =for html <blockquote>
1120 =for html </blockquote>
1124 $self->updateElementInfo
1125 unless $self->{xname};
1127 return $self->{xname};
1131 my ($self, $comment) = @_;
1137 Returns creates a new element
1141 =for html <blockquote>
1147 Creation comment. Default -nc.
1151 =for html </blockquote>
1155 =for html <blockquote>
1161 Status from cleartool
1165 Ouput from cleartool
1169 =for html </blockquote>
1173 $comment = Clearcase::_setComment $comment;
1175 return $Clearcase::CC->execute ("mkelem $comment $self->{pname}");
1179 my ($self, $comment) = @_;
1185 Checks out the element
1189 =for html <blockquote>
1195 Checkout comment. Default -nc.
1199 =for html </blockquote>
1203 =for html <blockquote>
1209 Status from cleartool
1213 Ouput from cleartool
1217 =for html </blockquote>
1221 $comment = Clearcase::_setComment $comment;
1223 return $Clearcase::CC->execute ("checkout $comment $self->{pname}");
1227 my ($self, $comment) = @_;
1233 Checks in the element
1237 =for html <blockquote>
1243 Check in comment. Default -nc.
1247 =for html </blockquote>
1251 =for html <blockquote>
1257 Status from cleartool
1261 Ouput from cleartool
1265 =for html </blockquote>
1269 $comment = Clearcase::_setComment $comment;
1271 return $Clearcase::CC->execute ("checkin $comment $self->{pname}");
1274 sub updateElementInfo () {
1277 # Get all information that can be gotten using -fmt
1278 my $fmt = 'Attributes:%aEndAttributes:'
1279 . 'Comment:%cEndComment:'
1280 . 'Create_date:%dEndCreate_date:'
1281 . 'Group:%[group]pEndGroup:'
1282 . 'Labels:%NlEndLabels:'
1283 . 'Pred:%PSnEndPred:'
1284 . 'Type:%[type]pEndType:'
1285 . 'ObjectKind:%mEndObjectKind:'
1286 . 'User:%[owner]pEndUser:'
1287 . 'Xname:%XnEndXname:';
1289 my ($status, @output) =
1290 $Clearcase::CC->execute ("describe -fmt \"$fmt\" $self->{pname}");
1293 unless $status == 0;
1295 # We need to make sure that fields are filled in or empty because we are using
1296 # undef as an indication that we have not called updateElementInfo yet.
1297 $self->{attributes} =
1298 $self->{labels} = ();
1301 $self->{create_date} =
1307 $self->{xname} = '';
1310 # This output is wrapped with parenthesis...
1311 if (/Attributes:\((.*)\)EndAttributes:/) {
1312 my @attributes = split ", ", $1;
1315 foreach (@attributes) {
1316 if (/(\w+)=(\w+)/) {
1321 $self->{attributes} = %attributes ? \%attributes : ();
1324 if (/Comments:(.*)EndComments:/) {
1325 $self->{comments} = $1;
1328 if (/Create_date:(.*)EndCreate_date:/) {
1329 $self->{create_date} = $1;
1332 if (/Group:(.*)EndGroup:/) {
1333 $self->{group} = $1;
1336 if (/Labels:(.*)EndLabels:/) {
1337 my @labels = split " ", $1;
1338 $self->{labels} = @labels ? \@labels : ();
1341 if (/Pred:(.*)EndPred:/) {
1345 if (/Type:(.*)EndType:/) {
1349 if (/ObjectKind:(.*)EndObjectKind:/) {
1350 $self->{objkind} = $1;
1353 if (/User:(.*)EndUser:/) {
1357 if (/Xname:(.*)EndXname:/) {
1358 $self->{xname} = $1;
1363 } # updateElementInfo
1369 =head3 ClearSCM Perl Modules
1371 =for html <p><a href="/php/scm_man.php?file=lib/Clearcase.pm">Clearcase</a></p>
1373 =head2 INCOMPATABILITIES
1377 =head2 BUGS AND LIMITATIONS
1379 There are no known bugs in this module.
1381 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
1383 =head2 LICENSE AND COPYRIGHT
1385 Copyright (c) 2007, ClearSCM, Inc. All rights reserved.