The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Todo-v0.2.2
River stage zero No dependents
2 ++
/ Text::Todo::Entry

NAME

Text::Todo::Entry - An object for manipulating an entry on a Text::Todo list

VERSION

Since the $VERSION can't be automatically included, here is the RCS Id instead, you'll have to look up $VERSION.

    $Id: Entry.pm,v 1.30 2010/02/16 01:13:12 andrew Exp $

SYNOPSIS

    use Text::Todo::Entry;

    my $entry = Text::Todo::Entry->new('text of entry');

    $entry->append('+project');

    if ($entry->in_project('project') && ! $entry->priority) {
        print $entry->text, "\n";
    }

DESCRIPTION

This module creates entries in a Text::Todo list. It allows you to retrieve information about them and modify them.

For more information see http://todotxt.com

INTERFACE

new

Creates an entry that can be manipulated.

    my $entry = Text::Todo::Entry->new([
    'text of entry' | { 
        [ text => 'text of entry' ,]  
        [ tags => { additional_arg => 'identfier' }, ]
    } ]);

If you don't pass any text, creates a blank entry.

See tags below for a description of additional tags.

text

Returns the text of the entry.

    print $entry->text, "\n";

pri

Sets the priority of an entry. If the priority is set to an empty string, clears the priority.

    $entry->pri('B');

Acceptible entries are an empty string, A-Z or a-z. Anything else will cause an error.

depri

A convenience function that unsets priority by calling pri('').

    $entry->depri;

priority

Returns the priority of an entry which may be an empty string if it is

    my $priority = $entry->priority;

tags

Each tag type generates two accessor functions {tag}s and in_{tag}.

Default tags are context (@) and project (+).

When creating a new object you can pass in new tags to recognize.

    my $entry = Text::Todo::Entry->new({ 
        text => 'do something DUE:2011-01-01',
        tags => { due_date => 'DUE:' } 
    });

    my @due_dates = $entry->due_dates;

then @due_dates is ( '2011-01-01' );

and you could also:

    if ($entry->in_due_date('2011-01-01')) {
        # do something
    }
{tag}s
    @tags = $entry->{tag}s;
in_{tag}

returns true if $entry is in the tag, false if not.

    if ($entry->in_{tag}('tag')) {
        # do something
    }

learn_tag($tag, $sigal)

    $entry->learn_tag('due_date', 'DUE:');

Teaches the entry about an additional tag, same as passing a tags argument to new(). See tags()

You can simulate forgetting a tag by setting the sigal to undef or an empty string.

known_tags

    $known_tags = $entry->known_tags;

$known_tags by default would be:

    { context => '@',
      project => '+',
    }

context

These are matched as a word beginning with @.

contexts
in_context

project

This is matched as a word beginning with +.

projects
in_project

replace

Replaces the text of an entry with completely new text. Useful if there has been manual modification of the entry or just a new direction.

    $entry->replace('replacment text');

prepend

Attaches text (with a trailing space) to the beginning of an entry. Puts it after the done() "x" and the priority() letter.

    $entry->prepend('NEED HELP');

append

Adds text to the end of an entry. Useful for adding tags, or just additional information.

    $entry->append('@specific_store');

do

Marks an entry as completed.

    $entry->do;

Does this by prepending "x `date '%Y-%m-%d'`" to the beginning of the entry.

done

Returns true if an entry is marked complete and false if not.

    if (!my $status = $entry->done) {
        # remind me to do it
    }

If the entry starts as 'x date', for example 'x 2010-01-01', $status is now '2010-01-01'. If the entry just starts with 'x', then $status will be 'x'.

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

Text::Todo::Entry requires no configuration files or environment variables.

DEPENDENCIES

Class::Std::Utils List::Util version

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Known limitations:

Sometimes leading whitespace may get screwed up when making changes. It doesn't seem to be particularly a problem, but if you use whitespace to indent entries for some reason it could be.

Please report any bugs or feature requests to bug-text-todo@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Andrew Fresh <andrew@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2009, Andrew Fresh <andrew@cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.