NAME

Remind::Parser - parse `remind -lp' output

SYNOPSIS

    use Remind::Parser;

    $parser = Remind::Parser->new(...);

    $parser->parse(\*STDIN);

    $reminders = $parser->reminders;
    foreach $rem (@$reminders) {
        ($Y, $M, $D) = @$rem{qw(year month day)};
        $descrip = $rem->{'description'};
    }

    $days = $parser->days;
    foreach $day (@$days) {
        $reminders_for_day = $day->{'reminders'};
        foreach $rem (@$reminders_for_day) {
            ...
        }
    }

DESCRIPTION

Remind::Parser parses a stream produced by remind(1) and intended for back-end programs such as rem2ps(1) or wyrd(1).

The input must have been produced by invoking remind -l -p[num]; for details on this format, see rem2ps(1).

PUBLIC METHODS

new(%args)

    $parser = Remind::Parser->new;
    $parser = Remind::Parser->new('strict' => 1);

Create a new parser. The following (key, value) pairs may be supplied; they have the same effect as calling the mutator method with the same name; see below.

strict

strip_times

fill_gaps

strict([boolean])

    $is_strict = $parser->strict;
    $parser->strict(1);  # Be strict
    $parser->strict(0);  # Don't be strict

Get or set the parser's strict property. If strict is set, the parse method will complain about invalid input, e.g., lines of input following the # rem2ps end line.

This option is off by default.

strip_times([boolean])

    $will_strip_times = $parser->strip_times;
    $parser->strip_times(1);  # Strip times
    $parser->strip_times(0);  # Don't strip times

Setting the strip_times option will result in a reminder's time being stripped from the beginning of the reminder. It's much better to invoke remind using -b2 instead if you don't want these times to appear, but this option is available just in case you need it for some reason.

This option is off by default.

fill_gaps([boolean])

    $will_fill_gaps = $parser->fill_gaps;
    $parser->fill_gaps(1);  # Fill gaps
    $parser->fill_gaps(0);  # Don't fill gaps

If fill_gaps is set, then when the days method is called, any days that have no reminders but that fall within the operative date range will be represented in the value returned.

This may also be specified on a case-by-case basis when calling days.

parse($filehandle)

    $reminders = Remind::Parser->parse(\*STDIN);

Parse the contents of a filehandle, returning a reference to a list of reminders. The input must have been produced by invoking remind -l -p[num]; otherwise, it will not be parsed correctly. (If remind's -pa option was used, "pre-notification" reminders are correctly parsed but cannot be distinguished from other reminders.)

Each reminder returned is a hash containing the following elements:

description

The reminder description (taken from the MSG portion of the remind(1) source).

date

The reminder's date, in ISO8601 compact format, e.g., 20080320.

date_time

The reminder's date (and time, if it's a timed event), in ISO8601 compact format, e.g., 20080320 or 20080320T104500. Keep in mind that remind doesn't assume any particular time zone.

year

month

day

day_of_week

The day, month, year, and day of week of the reminder. Days of the week are numbered 1 to 7 and start with Monday.

all_day

If this element is present and has a true value, the reminder is an all-day event. Otherwise, it's a timed event.

hour

minute

The hour and minute of the reminder, if it's a timed reminder. Absent otherwise.

duration

If the reminder has a duration, this is set to a reference to a hash with hours, minutes, and seconds elements with the appropriate values. Otherwise, there is no duration element.

tag

The TAG string from the remind(1) source. Absent if no TAG string was present.

special

The SPECIAL string from the remind(1) source. Absent if no SPECIAL string was present.

line

file

The line number and file name of the file containing the reminder.

event

instance

These two elements, both integers, together uniquely identify a reminder. Multiple reminders that are all triggered from the same line in the same file share the same event identifier but have distinct instance identifiers.

reminders

    $reminders = $parser->reminders;

This method returns a reference to the same array of reminders that was returned by the parse method.

days

    $days = $parser->days;                    # Rely on $parser_fill_gaps
    $days = $parser->days('fill_gaps' => 1);  # Override $parser->fill_gaps
    $days = $parser->days('fill_gaps' => 0);  # Override $parser->fill_gaps

Returns a reference to an array of days for each of which one or more reminders was triggered. (If the fill_gaps option is set, then days that have no reminders but that fall within the operative date range will also be present.)

Each day is represented by a hash with the following elements:

date

The date in YYYYmmdd form.

year

month

day

day_of_week

The date expressed in all the same ways as it is in reminders.

reminders

A reference to an array of reminders for the day. Each reminder is a reference to a hash whose members are as described above. (In fact, each element in reminders is a reference to the same hash found in the return values of the parse and reminders methods.)

BUGS

There are no known bugs. Please report any bugs or feature requests via RT at http://rt.cpan.org/NoAuth/Bugs.html?Queue=Remind-Parser; bugs will be automatically passed on to the author via e-mail.

TO DO

Offer an option to read the reminder's source?

Parse formats other than that produced by remind -l -p[a|num]?

Add an option to skip reminders with unrecognized SPECIALs?

AUTHOR

Paul Hoffman (nkuitse AT cpan DOT org)

COPYRIGHT

Copyright 2007-2009 Paul M. Hoffman.

This is free software, and is made available under the same terms as Perl itself.

SEE ALSO

remind(1), rem2ps(1), wyrd(1)