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 platform's 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.

pathsep (string)

The path separator to use for VCS::CMSynergy::Traversal::path(). The default is your platform's path separator.

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 passes it down to query_object during 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.

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

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, has_child

These are convenience methods to enumerate all members of a directory (is_child_of) or all directories that contain the object (has_child), both in the context of the invocant project

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

  $parents = $proj->has_child($obj, @keywords);

are exactly the same as

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

  $parents = $proj->ccm->query_object(
    "has_child('$obj','$proj')", @keywords);

For has_child, $obj may be any VCS::CMSynergy::Object.

For is_child_of, $dir is optional; if 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.

project_grouping, process_rule

  $pg = $proj->project_grouping(@keywords);

  $pr = $proj->process_rule(@keywords);

These are convenience methods to return the project_grouping (as a VCS::CMSynergy::Projectgrouping) and process_rule (as a VCS::CMSynergy::Object) of the invocant project.

are exactly the same as

  $pg = $proj->is_project_grouping_of(@keywords)->[0];

  $pr = $proj->is_reconfigure_template_of(@keywords)->[0];

Note that static projects have neither project_grouping nor process_rule; in that case undef is returned.

If you supply @keywords these are passed down to is_..._of as additional keywords.

object_from_path

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

Returns the VCS::CMSynergy::Object identified by workarea path $path in project $proj.

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

See "object_from_proj_ref" in VCS::CMSynergy for details.

project_tree

  $hash = $proj->project_tree(\%options);

is exactly the same as

  $hash = $proj->ccm->project_tree(\%options, $proj);

See "project_tree" in VCS::CMSynergy.

top_dir

  $dir = $proj->top_dir(@keywords);

Returns the VCS::CMSynergy::Object representing the top level directory of project $proj.

If you supply @keywords these are passed down to "query_object" in VCS::CMSynergy as additional keywords.

MISCELLANEOUS

show_reconfigure_properties

Note: This method is obsolete in Synergy 7.2 and up, as the underlying command ccm reconfigure_properties doesn't exist anymore. Use show_object on the project's project grouping to obtain similar information.

  $objects = $proj->show_reconfigure_properties($what, @keywords, \%options);

Shows information about the project's reconfigure properties depending on $what. @keywords and \%options are optional. Returns a reference to an array of VCS::CMSynergy::Objects.

$what must be one of the following strings:

"tasks": shows tasks that are directly in the project's reconfigure properties
"folders": shows folders that are in the project's reconfigure properties
"tasks_and_folders": shows tasks and folders that are directly in the project's reconfigure properties
"all_tasks": shows all tasks that are directly or indirectly in the project's reconfigure properties (indirectly means the task is in a folder that is in the project's reconfigure properties)
"objects": shows objects in the task that are either directly or indirectly in the project's reconfigure properties

See the description of "query_hashref" in VCS::CMSynergy or "query_object" in VCS::CMSynergy, resp., for the meaning of @keywords.

show_reconfigure_properties also accepts an optional trailing hash reference. Possible keys are:

subprojects (boolean): whether to include the reconfigure properties of sub projects (recursively), default: false
automatic (boolean): whether automatic tasks are to be shown, default: false; this option is only relevant if $what is "tasks", "tasks_and_folders" or "all_tasks"

Example:

  $tasks = $proj->show_reconfigure_properties(
             all_tasks => qw/task_synopsis completion_date/,
             { subprojects => 1, automatic => 0 });

To install VCS::CMSynergy, copy and paste the appropriate command in to your terminal.

cpanm

cpanm VCS::CMSynergy

CPAN shell

perl -MCPAN -e shell
install VCS::CMSynergy

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

WORKAREA METHODS

chdir_into_wa

PROJECT TRAVERSAL

traverse

wanted function

options

CONVENIENCE METHODS

recursive_is_member_of, hierarchy_project_members

is_child_of, has_child

project_grouping, process_rule

object_from_path

project_tree

top_dir

MISCELLANEOUS

show_reconfigure_properties

Module Install Instructions