/ 
Timex-6.24
/ Timex::Project

NAME

Timex::Project - manage a list of projects

SYNOPSIS

use Timex::Project;
$root = new Timex::Project;
$helloproject = $root->project('hello');
$helloproject->start_time;
$helloproject->end_time;

DESCRIPTION

Timex::Project is a project manager, primarily for the programs ctimex and tktimex. This module supports the following methods:

new

$project = new Timex::Project $label

Construct a new Timex::Project object with label $label.

clone

$new_project = clone Timex::Project $old_project
$new_project = $old_project->clone

Clone a new Timex::Project object from an old one.

concat

$project = concat Timex::Project [-flat => 1,] $proj1, $proj2 ...

Concats the specified projects and create a new one. The concatenated projects are not cloned.

If -flat is set to a true value, then projects are not seen as complete project hierarchies (i.e. root element is not a real project).

shuffle

$new_project = $project->shuffle($in => $out);

Shuffle the projects in level $in to level $out. The special level "leaf" can be used to shuffle to the leaf. Note: only $in == 1 is implemented yet. Top level is level == 1.

icon

$icon = $project->icon;
$project->icon($icon);

Get or set icon for project.

jobnumber

$jobnumber = $project->jobnumber;
$project->jobnumber($jobnumber);

Get or set jobnumber for project.

jobnumber_from_parent

$jobnumber = $project->jobnumber_from_parent;

Get jobnumber for this project, either from the project itself or from any of the parents. Return undef if no jobnumber could be found.

note

@notes = $project->note;

Get notes for project.

set_note

$project->note("First note", "Second note");
$project->note(["First note", "Second note"]);

has_note

$project->has_note

Return, if $project has a note attached.

last_times

$time_ref = $project->last_times;

Return an array reference to the last activity of the project, or undef if there was no activity at all.

last_time_subprojects

$time_ref = $project->last_time_subprojects;

Return the time of the last activity of all subprojects, or undef if there was no activity at all. Note that the method is spelled "time" instead of "times".

interval_times

@times = $project->interval_times("daily", %args)

Return the @times array (like $project->{'times'}) aggregated to an interval. Valid argument values are: "" (no aggregation), daily, weekly, monthly and yearly.

Further options:

-recursive

If given and true, sum times for all subprojects too.

-asref

If given and true, then the returned value is a reference to an array. This is useful for the "" interval, because it returns the @times array of the project itself, which makes it easier for manipulation.

-annotations

Include annotations as 3th element in times array.

COMPATIBILITY: In Timex::Project prior 3.48, the order of an element array was: [from_time, to_time, interval] (interval only with aggregation). Since 3.48, this is [from_time, to_time, annotation, interval].

daily_times

@times = $project->daily_times;

Same as interval_times('daily').

top_parent

$top_parent = $project->top_parent

Return real top parent (that is, not the root project) of $project.

reparent

$project->reparent($newparent)

Use this method only if there is already a parent. Otherwise, use the parent method.

root

$root = $p->root;

Return root node of the given project $p.

delete

$p->delete;

Delete project $p. Note that you cannot delete the root project itself.

subproject

$root->subproject([$label,[-useid => 1]]);

With label defined, create a new subproject labeled $label. Without label, return either an array of subprojects (in array context) or a reference to the array of subprojects (in scalar context).

sorted_subprojects

$root->sorted_subprojects($sorted_by)

Return subprojects according to $sorted_by. If $sorted_by is 'name', sorting is done lexically by name. If $sorted_by is 'time', sorting is done by time (more time consuming subprojects come first). If $sorted_by is 'latest', the last active projects come first. If $sorted_by is not given or is 'nothing', no sorting is done.

all_subprojects

@sub = $root->all_subprojects()

Return all projects below $root (recurse into tree) as an flat array of Projects.

find_by_pathname

$project = $root->find_by_pathname($pathname);

Search and return the corresponding $project (or undef if no such project exists) for the given $pathname.

find_by_regex

@projects = $root->find_by_regex($regex);

Search and return the projects, which labels match with $regex. The returndes project objects are accumulated in an array.

find_by_regex_pathname

@projects = $root->find_by_regex_pathname($regex);

Search and return the projects, which pathnames match with $regex. The returndes project objects are accumulated in an array.

delete_times

$root->delete_times($index1, $index2 ...)

Delete the times definitions by the given indexes. If index is "all", then all times definitions are deleted.

move_times_after

$root->move_times_after($index_from, $index_before);

Move the times definition at $index_from after $index_before.

sum_time

$time = $project->sum_time($since, $until, %args)

Return the time the given project accumulated since $since until $until. If $until is undefined, return the time until now. If -recursive is set in the %args hash to a true value, recurse into subprojects of $project.

update_cached_time

$project->update_cached_time

STUB: Update the cached_time field of the project object. NOW: Invalidate the cached_time field, so it may be racalculated by sum_time.

restricted_times

@flattimes = $project->restricted_times($since, $until)

Return the times from the given project and subprojects since $since until $until. If $until is undefined, return the time until now. The returned array consists of elements with the following form:

[$project, $from, $to]

get_from_upper

$value = $project->get_from_upper($attribute)
$project->get_from_upper($attribute, $value)

Get the value for an attribute for this project, or, if undefined, for one of the parents of this project.

With two arguments, set the value of the attribute of this project.

An alias _get_from_upper exists for backward compatibility.

archived

$archived = $project->archived

Return true if the project or one of the parent projects are archived. Use $project->{'archived'} for the value of *this* project.

$project->archived($archived)

Set the archived attribute (0 or 1) for this project.

modified

$modfied = $project->modified

Return true if the root project is modified, that is, one of root's #' subprojects are modified.

$project->modified($modified)

Set the modified attribute (0 or 1) for the root project.

next_id

$id = $project->next_id

Return the next free id in the project tree.

id

$id = $project->id

Return the id of the project.

rate

$rate = $project->rate
$project->rate($rate)

Get or set the rate for this project.

domain

Get the project domain. A domain is just a user-specified label, which can be used to separate private from corporate projects.

get_all_domains

Return a list of all domains.

get_all_annotations

@annotations = $project->get_all_annotations($since, $until, %args)

Return all annotations as an array for the given project since $since until $until. If $until is undefined, return the time until now.

notimes

$notimes = $project->notimes
$project->notimes($notimes)

Get or set the notimes flag for this project.

separator

$separator = $project->separator

Return the separator for this tree (the root project). Defaults to /.

$project->separator($separator);

Set the separator for this tree (the root project) to $separator.

current

$p = $project->current

Return the current project for this tree.

set_current

$p->set_current

Set project $p as the current project for the tree. XXX Should start/stop be called automatically?

no_current

$p->no_current

Undef the current project setting for the project tree.

save

$project->save($file, ...);

Save the project to file $file. If the optional argument -skeleton is set to true, do not save times.

Return 1 if the saving was successful, otherwise undef or 0.

load

$r = $project->load($filename, %args)

Load the project file $filename and returns true if the loading was successfull. New data is merged to the existing project.

With -skeleton set to a true value, just load the project tree, but no times.

is_project_file

$r = Timex::Project->is_project_file($filename);

Return TRUE if $filename is a project file.

last_project

$last_project = $root->last_project

Return the last running project.

last_project

$last_project = $root->last_projects([$nr])

Return the $nr last projects as an array. If $nr is not defined, return the last project (same as the last_project method).

merge

($modified, $new_proj_ref, $changed_proj_ref) = $project->merge($other_p)