NAME

Tasks - Perl module for the tasks / projects and time tracking

SYNOPSIS

  use Tasks;

  my $tasks = new Tasks;
  my $ret = $tasks->read('tasks.xml');
  die("Error in reading tasks file: $ret") if $ret;

  # Create the new tasklist 'tasklist'
  $tasks->add_tasklist({'name' => 'tasklist'});

  # Create the new task 'task1'
  my $task = $tasks->add_task(undef, {'name' => 'task1',
                                      '_text' => 'task1 description'});

  # Set time for the work on task1 10 minutes starting now
  my $time = time();
  $tasks->add_time($task, $time, $time + 600, 'hanging around');

  # Print all the tasks in the task file
  $ret = undef; # no need to return anything in this case
  my $tasklist = $tasks->tasklist();
  $tasklist = $tasklist->[0]; # Use the first tasklist (our)
  $tasks->traverse_task_tree($tasklist, \&print_task, $ret);

  # Save the tasks
  $tasks->save();

  exit 0;

  sub print_task {
    my ($task, $ret, $level) = @_;
    my $prefix = ' 'x$level;

    print $prefix."$task->{name}\n";
    return $ret;
  }


  NOTE: Before trying this example you need to create an
    empty tasks.xml file which will looks like the following:
  <tasklist name="example" version="1.0">
  </tasklist>

DESCRIPTION

Module to track the tasks / projects and time spend on each task. This module allows to keep the hierarchical list of the tasks, including the time logs for every task.

All information is saved in XML file.

METHODS

new() - This is a class method, the constructor for Tasks.

read($fname) - Read tasks file. Parameter: $fname - file name to read tasks from. (optional, if not defined ~/.tasks.xml will be used. Returns '' if Ok, error string otherwise.

add_tasklist($attr) - Add new tasklist. Parameter: $attr - pointer to the hash with task attributes (e.g. 'name', '_text') Returns pointer to the new tasklist or undef if error. See STRUCTURES for more info on how tasklist looks like.

add_task($parent, $attr) - Add new task Parameter: $parent - pointer to parent task (if undef, the first tasklist is used) $attr - pointer to the hash with task attributes (e.g. 'name', 'priority', '_text') Returns pointer to the new task or undef if error

save($fname) - Save tasks to the file Parameter: $fname - (optional) file name to save to. If not supplied, the same file is used as in read() Returns: '' if Ok, error in case of error

add_time($task, $start, $finish, $desc) - Add times to task. Parameters: $task - pointer to task $start - start time (in sec. since 1/1/70 $finish - finish time (if undef the current time will be used) $desc - description (optional)

get_task($id) - Get task pointer by task ID Parameters: $id - task ID Returns: list ($parent, $task) if task found, undef otherwise. where: $parent - pointer to parent task $task - pointer to task (see STRUCTURES)

zero_time($task, $this_only, $till) - Reset / Zero all the times for the task. Parameters: $task - pointer to task, if undef, resets all the times $this_only - flag. If to zero this task only without subtasks $sec - time (in sec.) till which to times should be reset (all times entries with 'start' time less than this will be zeroed)

get_total_time($task, $options) - Get total time spend on this task Parameters: $task - pointer to task, if undef, calculates total $options - pointer to options, possible options: this_only - flag. If set when calculate this task only without subtasks start - start time to take in account (in sec. from 1970) private - take into account private tasks Returns: time in seconds

traverse_task_tree($task, $func, $ret, $level) - Traverse task tree and use supplied function on any task. Parameters: $task - task to start from $func - pointer to function to apply for every task function should get 3 arguments: $task, $ret, $level where $ret is result of this function for previous tasks and $level is level in within the tree $ret - result of this function for previous tasks $level - level in the tree Returns: $ret from last call in recursion

print_tasks() - Print the tasklist to STDERR, usefull for debugging.

STRUCTURES

task - Single task structure. Includes the following fields: 'id' - unique ID of the task (generated automatically) 'name' - name of task '_text' - some text (e.g. description) '_tasks' - pointer to the array with subtasks hashes '_times' - pointer to the array with 'time' hashes Any other attributes can be added (e.g. 'priority')

tasklist - Tasklist (Single file can contain more than one tasklist) 'name' - name of the tasklist '_text' - some text (e.g. description) '_tasks' - pointer to the array with subtasks hashes

time - Time structure (contained in '_times' arrays) 'start' - start time in seconds since jan 1 1970 'finish' - finish time in seconds since jan 1 1970 '_text' - some text (e.g. description)

AUTHOR

Sergey Gribov, sergey@sergey.com

Copyright (c) 2001 Sergey Gribov. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1).