NAME

VCS::CMSynergy::Project - convenience methods for VCS::CMSynergy::Objects of type "project"

SYNOPSIS

VCS::CMSynergy::Project is a subclass of VCS::CMSynergy::Object with additional methods for Synergy projects.

use VCS::CMSynergy;
$ccm = VCS::CMSynergy->new(%attr);
...
$proj = $ccm->object("editor-1_project:1");
print ref $proj;			# "VCS::CMSynergy::Project"

$proj->chdir_into_wa;

$proj->traverse(
  sub { print "  " x VCS::CMSynergy::Traversal::depth(), $_, "\n"; } );

This synopsis only lists the major methods.

WORKAREA METHODS

chdir_into_wa

my $old_pwd = $proj->chdir_into_wa;

Changes into the toplevel workarea directory of project $proj. Returns undef if $proj doesn't maintain a workarea or the chdir() failed, otherwise returns the name of current working directory before the call.

PROJECT TRAVERSAL

traverse

$proj->traverse(\&wanted, $dir);
$proj->traverse(\%options, $dir);

traverse walks the tree below directory $dir in the invocant project without the need for a workarea. It is modelled on File::Find.

&wanted is a code reference described in "wanted function" below. $dir must be a VCS::CMSynergy::Object. If $dir is omitted, it defaults to the top level directory of the invocant.

wanted function

&wanted is called once for all objects below $dir including $dir itself. It will also be called on subprojects of the incocant project, but traverse will not recurse into subprojects unless the subprojects flag is specified (see "options" below).

On each call to &wanted, $_ will be bound to the currently traversed object (a VCS::CMSynergy::Object).

@VCS::CMSynergy::Traversal::dirs will be bound to an array of VCS::CMSynergy::Objects of cvtype dir representing the path from $dir to $_ (in the context of the invocant project). In particular, @VCS::CMSynergy::Traversal::dirs[-1] is the parent dir of $_.

The convenience function VCS::CMSynergy::Traversal::path() returns the filesystem path for $_. It is short for

join($pathsep, map { $_->name } @VCS::CMSynergy::Traversal::dirs, $_)

where $pathsep is your platforms path separator.

The convenience function VCS::CMSynergy::Traversal::depth() returns the current depth, where the top level project has depth 0. It is short for

scalar @VCS::CMSynergy::Traversal::dirs

Similarly @VCS::CMSynergy::Traversal::projects represents the subproject hierarchy starting with the invocant project. In particular, $_ is a member of $VCS::CMSynergy::Traversal::projects[-1].

Note: @VCS::CMSynergy::Traversal::dirs and @VCS::CMSynergy::Traversal::projects are both readonly arrays, i.e. you can't modify them in any way.

You may set $VCS::CMSynergy::Traversal::prune to a true value in &wanted to stop recursion into sub directories (or subprojects) (this makes only sense when &wanted is called on a dir or project object).

If recursion into subprojects is specfied, &wanted will be called once for the project object and also for the top level dir of the subproject.

options

The first argument of traverse may also be a hash reference. The following keys are supported:

wanted (code reference)

The value should be a code reference. It is described in "wanted function".

bydepth (boolean)

If this option is set, traverse calls &wanted on a directory (or project) only after all its entries have been processed. It is "off" by default.

preprocess (code reference)

The value should be a code reference. It is used to preprocess the children of a dir or project, i.e. before traverse starts traversing it. You can use it to impose an ordering among "siblings" in the traversal. You can also filter out objects, so that wanted will never be called on them (and traversal will not recurse on them in case of dirs or projects).

The preprocessing function is called with a list of VCS::CMSynergy::Objects and is expected to return a possibly reordered subset of this list. Note that the list may contain dir and project objects. When the preprocessing function is called, $_ is bound to the parent object (which is always of cvtype dir or project).

postprocess (code reference)

The value should be a code reference. It is invoked just before leaving the current dir or project.

When the postprocessing function is called, $_ is bound to the current object (which is always of cvtype dir or project).

subprojects (boolean)

If this option is set, traverse will recurse into subprojects. It is "off" by default.

attributes (array ref)

This option is only useful if ":cached_attributes" is in effect. It should contain a reference to an array of attribute names. If present, traverse uses query_object_with_attributes rather than query_object for the traversal. Hence all objects encountered in the traversal (e.g. $_ when bound in wanted or the elements of the directory stack @VCS::CMSynergy::Traversal::dirs) have their attribute caches primed for the given attributes, cf. query_object_with_attributes.

Note that for any particular dir (or project) object, the above code references are always called in order preprocess, wanted, postprocess.

Example:

my $proj = $ccm->object('toolkit-1.0:project:1');

$proj->traverse(
  sub { print VCS::CMSynergy::Traversal::path(), "\n" } );

This prints the directory tree of project toolkit-1.0:project:1 similar to the Unix command find. The order of entries in a directory is unspecified and sub projects are not traversed:

toolkit
toolkit/makefile
toolkit/makefile.pc
toolkit/misc
toolkit/misc/toolkit.ini
toolkit/misc/readme

Another example:

  $proj->traverse(
    {
      wanted => sub {
	return unless $_->cvtype eq "project";
	my $proj_depth = @VCS::CMSynergy::Traversal::projects;
	print "  " x $proj_depth, $_->displayname, "\n";
      },
      preprocess => sub { sort { $a->name cmp $b->name } @_; },
      subprojects => 1,
    });

This prints the complete project hierarchy rooted at toolkit-1.0:project:1. Only projects will be shown, entries are sorted by name and are intended according to their depth:

toolkit-1.0
  calculator-1.0
  editor-1.0
  guilib-1.0

get_member_info_hashref, get_member_info_object

NOTE: This methods are only useful if you have the optional Synergy command get_member_info (from the "PC Integrations" package) installed, cf. README.get_member_info for details.

 $members1 = $proj->get_member_info_hashref(@keywords, \%options);
 $members2 = $proj->get_member_info_object(@keywords, \%options);

 while (my ($path, $member) = each %$members2) 
 {
   print "$path $member\n";
 }

get_member_info_hashref and get_member_info_object execute ccm get_member_info to obtain the members of project $proj. They both return a reference to a hash where the keys are the workarea (relative) pathnames of the members. For get_member_info_hashref, the value is a hash of attributes similar to "query_hashref" in VCS::CMSynergy. For get_member_info_object, the value is the member itself (a CVS::CMSYnergy::Object), similar to "query_object" in VCS::CMSynergy.

If there was an error, undef is returned.

See the description of "query_hashref" in VCS::CMSynergy or "query_object" in VCS::CMSynergy, resp., for the meaning of @keywords. Both methods also accept an optional trailing hash reference. Possible keys are:

subprojects: whether to list members of sub projects (recursively), default: false
pathsep: separator to use for the workarea pathnames, default: the platform's native path separator

Note the following deficiencies inherited from ccm get_member_info:

The member hash does not contain any directories (i.e. Synergy objects with cvtype "dir"). This usually not a problem since (1) directories don't carry much information relevant to version control and (2) their existence is easily inferred from the pathnames. But information about empty directories will be lost.
If option subprojects is true the member hash contains all members of all sub projects, but doesn't give any information which sub project a certain member belongs to.

Note the following differences from ccm get_member_info:

Workarea pathnames are always relative (to the top of the workarea), irrespective whether $proj currently maintains a workarea or not.

CONVENIENCE METHODS

recursive_is_member_of, hierarchy_project_members

These are convenience methods to enumerate recursively all members of the invocant project or just the sub projects.

$members = $proj->recursive_is_member_of($order_spec, @keywords);
$sub_projs = $proj->hierarchy_project_members($order_spec, @keywords);

are exactly the same as

$members = $proj->ccm->query_object(
  "recursive_is_member_of('$proj',$order_spec)", @keywords);
$sub_projs = $proj->ccm->query_object(
  "hierarchy_project_members('$proj',$order_spec)", @keywords);

$order_spec and @keywords are optional. If $order_spec is undef or not supplied, "none" is used. If you supply @keywords these are passed down to "query_object" in VCS::CMSynergy as additional keywords.

is_child_of

These are convenience methods to enumerate all members of a directory in the context of the invocant project.

$members = $proj->is_child_of($dir, @keywords);

is exactly the same as

$members = $proj->ccm->query_object(
  "is_child_of('$dir','$proj')", @keywords);

$dir and @keywords are optional. If $dir is supplied it must be a VCS::CMSynergy::Object of type "dir". If $dir is undef or not supplied, is_child_of returns the toplevel directory of the invocant project (NOTE: the return value is actually a reference to an array with one element). If you supply @keywords these are passed down to "query_object" in VCS::CMSynergy as additional keywords.

object_from_proj_ref

$obj = $proj->object_from_proj_ref($path, @keywords);
$obj = $proj->object_from_proj_ref(\@path_components, @keywords);