=================================================================== RCS file: /cvs/todotxt/Text-Todo/lib/Text/Todo/Entry.pm,v retrieving revision 1.11 retrieving revision 1.12 diff -u -r1.11 -r1.12 --- todotxt/Text-Todo/lib/Text/Todo/Entry.pm 2010/01/09 07:08:45 1.11 +++ todotxt/Text-Todo/lib/Text/Todo/Entry.pm 2010/01/10 00:13:14 1.12 @@ -1,6 +1,6 @@ package Text::Todo::Entry; -# $RedRiver: Entry.pm,v 1.9 2010/01/08 17:41:56 andrew Exp $ +# $RedRiver: Entry.pm,v 1.11 2010/01/09 07:08:45 andrew Exp $ use warnings; use strict; @@ -98,7 +98,7 @@ return $text_of{$ident}; } - sub depri { pri( @_, '' ) } + sub depri { pri( $_[0], '' ) } sub pri { my ( $self, $new_pri ) = @_; @@ -174,137 +174,188 @@ =head1 NAME -Text::Todo::Entry - [One line description of module's purpose here] +Text::Todo::Entry - An object for manipulating an entry on a Text::Todo list =head1 VERSION -This document describes Text::Todo::Entry version 0.0.1 +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.12 2010/01/10 00:13:14 andrew Exp $ + =head1 SYNOPSIS use Text::Todo::Entry; -=for author to fill in: - Brief code example(s) here showing commonest usage(s). - This section will be as far as many users bother reading - so make it as educational and exeplary as possible. - - + my $entry = Text::Todo::Entry->new('text of entry'); + + $entry->append('+project'); + + if ($entry->in_project('project') && ! $entry->priority) { + print $entry->text, "\n"; + } + + =head1 DESCRIPTION -=for author to fill in: - Write a full description of the module and its features here. - Use subsections (=head2, =head3) as appropriate. +This module creates entries in a Text::Todo list. +It allows you to retrieve information about them and modify them. +For more information see L + =head1 INTERFACE -=for author to fill in: - Write a separate section listing the public components of the modules - interface. These normally consist of either subroutines that may be - exported, or methods that may be called on objects belonging to the - classes provided by the module. - =head2 new +Creates an entry that can be manipulated. + + my $entry = Text::Todo::Entry->new(['text of entry']); + +If you don't pass any text, creates a blank entry. + =head2 text +Returns the text of the entry. + + print $entry->text, "\n"; + +=head2 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. + +=head2 depri + +A convenience function that unsets priority by calling pri(''). + + $entry->depri; + =head2 priority -=head2 contexts +Returns the priority of an entry which may be an empty string if it is -=head2 in_context + my $priority = $entry->priority; -=head2 projects +=head2 tags -=head2 in_project +Each tag type generates two accessor functions {tag}s and in_{tag}. -=head2 replace +Current tags are context (@) and project (+). -=head2 prepend +=over -=head2 append +=item {tag}s -=head2 do + @tags = $entry->{tag}s; -=head2 done +=item in_{tag} -=head2 pri +returns true if $entry is in the tag, false if not. -=head2 depri + if ($entry->in_{tag}('tag')) { + # do something + } -=head1 DIAGNOSTICS +=back -=for author to fill in: - List every single error and warning message that the module can - generate (even the ones that will "never happen"), with a full - explanation of each problem, one or more likely causes, and any - suggested remedies. +=head3 context +These are matched as a word beginning with @. + =over -=item C<< Error message here, perhaps with %s placeholders >> +=item contexts -[Description of error here] +=item in_context -=item C<< Another error message here >> +=back -[Description of error here] +=head3 project -[Et cetera, et cetera] +This is matched as a word beginning with +. +=over + +=item projects + +=item in_project + =back +=head2 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'); + +=head2 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'); + +=head2 append + +Adds text to the end of an entry. +Useful for adding tags, or just additional information. + + $entry->append('@specific_store'); + +=head2 do + +Marks an entry as completed. + + $entry->do; + +Does this by prepending an 'x' to the beginning of the entry. + +=head2 done + +Returns true if an entry is marked complete and false if not. + + if (!$entry->done) { + # remind me to do it + } + + +=head1 DIAGNOSTICS + =head1 CONFIGURATION AND ENVIRONMENT -=for author to fill in: - A full explanation of any configuration system(s) used by the - module, including the names and locations of any configuration - files, and the meaning of any environment variables or properties - that can be set. These descriptions must also include details of any - configuration language used. - Text::Todo::Entry requires no configuration files or environment variables. -=head1 DEPENDENCIES +=head1 DEPENDENCIES -=for author to fill in: - A list of all the other modules that this module relies upon, - including any restrictions on versions, and an indication whether - the module is part of the standard Perl distribution, part of the - module's distribution, or must be installed separately. ] +Class::Std::Utils +List::Util +version -None. - =head1 INCOMPATIBILITIES -=for author to fill in: - A list of any modules that this module cannot be used in conjunction - with. This may be due to name conflicts in the interface, or - competition for system or program resources, or due to internal - limitations of Perl (for example, many modules that use source code - filters are mutually incompatible). - None reported. =head1 BUGS AND LIMITATIONS -=for author to fill in: - A list of known problems with the module, together with some - indication Whether they are likely to be fixed in an upcoming - release. Also a list of restrictions on the features the module - does provide: data types that cannot be handled, performance issues - and the circumstances in which they may arise, practical - limitations on the size of data sets, special cases that are not - (yet) handled, etc. - 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 C, or through the web interface at