.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Remind::PDF 3pm"
.TH Remind::PDF 3pm 2024-04-29 "perl v5.38.2" "VERSION 04.03.07"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Remind::PDF \- Render a month's worth of Remind data to PDF
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.ie n .SS "Remind::PDF\->create_from_stream($in, $specials_accepted)"
.el .SS "Remind::PDF\->create_from_stream($in, \f(CW$specials_accepted\fP)"
.IX Subsection "Remind::PDF->create_from_stream($in, $specials_accepted)"
This method reads data from an open file handle \f(CW$in\fR.  \f(CW$specials_accepted\fR
is a hashref of SPECIAL reminder types to accept; the key is the name of the
SPECIAL (all lower-case) and the value should be 1.  Any SPECIAL reminders
not in the hash are ignored.
.PP
This function returns a two-element array: \f(CW\*(C`($obj, $err)\*(C'\fR.  On success,
\&\f(CW$obj\fR will be a \f(CW\*(C`Remind::PDF\*(C'\fR object and \f(CW$err\fR will be undef.  On
failure, \f(CW$obj\fR will be undef and \f(CW$err\fR will be an error message.
.ie n .SS "Remind::PDF\->create_from_hash($hash, $specials_accepted)"
.el .SS "Remind::PDF\->create_from_hash($hash, \f(CW$specials_accepted\fP)"
.IX Subsection "Remind::PDF->create_from_hash($hash, $specials_accepted)"
This method takes data from a hash \f(CW$hash\fR, which must be one month's
worth of data from \f(CW\*(C`remind \-ppp\*(C'\fR output.  \f(CW$specials_accepted\fR is a
hashref of SPECIAL reminder types to accept; the key is the name of
the SPECIAL (all lower-case) and the value should be 1.  Any SPECIAL
reminders not in the hash are ignored.
.PP
This function returns a two-element array: \f(CW\*(C`($obj, $err)\*(C'\fR.  On success,
\&\f(CW$obj\fR will be a \f(CW\*(C`Remind::PDF\*(C'\fR object and \f(CW$err\fR will be undef.  On
failure, \f(CW$obj\fR will be undef and \f(CW$err\fR will be an error message.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.ie n .SS "read_one_month($in, $first_line, $specials_accepted)"
.el .SS "read_one_month($in, \f(CW$first_line\fP, \f(CW$specials_accepted\fP)"
.IX Subsection "read_one_month($in, $first_line, $specials_accepted)"
This function reads one month's worth of data from the file handle
\&\f(CW$in\fR.  \f(CW$first_line\fR is the line that was read from \f(CW$in\fR
just before calling this function.  \f(CW$specials_accepted\fR is a
hashref as documented above.
.PP
The return value is the same \f(CW\*(C`($obj, $err)\*(C'\fR two-element array
as \f(CW\*(C`create_from_stream\*(C'\fR returns.
.ie n .SS "read_one_month_p($in, $specials_accepted)"
.el .SS "read_one_month_p($in, \f(CW$specials_accepted\fP)"
.IX Subsection "read_one_month_p($in, $specials_accepted)"
This function reads one month's worth of data from the file handle
\&\f(CW$in\fR, assuming the original "remind \-p" format.
\&\f(CW$specials_accepted\fR is a hashref as documented above.
.PP
The return value is the same \f(CW\*(C`($obj, $err)\*(C'\fR two-element array
as \f(CW\*(C`create_from_stream\*(C'\fR returns.
.SS "parse_oldstyle_line ($line)"
.IX Subsection "parse_oldstyle_line ($line)"
This method parses an old-style "remind \-p" line
and returns a hashref containing some or all of the
hash keys found in the newer "remind \-pp" JSON output.
.SS setup_daymap
.IX Subsection "setup_daymap"
Set up the array that maps ($row, \f(CW$col\fR) to day number (or \-1
for rows/cols out of range.)
.ie n .SS "read_one_month_pp($in, $specials_accepted)"
.el .SS "read_one_month_pp($in, \f(CW$specials_accepted\fP)"
.IX Subsection "read_one_month_pp($in, $specials_accepted)"
This function reads one month's worth of data from the file handle
\&\f(CW$in\fR, assuming the "remind \-pp" partial-JSON format.
\&\f(CW$specials_accepted\fR is a hashref as documented above.
.PP
The return value is the same \f(CW\*(C`($obj, $err)\*(C'\fR two-element array
as \f(CW\*(C`create_from_stream\*(C'\fR returns.
.ie n .SS "accept_special($hash, $specials_accepted)"
.el .SS "accept_special($hash, \f(CW$specials_accepted\fP)"
.IX Subsection "accept_special($hash, $specials_accepted)"
Given a hashref \f(CW$hash\fR consisting of one entry parsed
from the "remind \-p" stream and a \f(CW$specials_accepted\fR hash,
return 1 if we should include this entry in the calendar or
0 if not.
.ie n .SS "find_last_special($special, $entries)"
.el .SS "find_last_special($special, \f(CW$entries\fP)"
.IX Subsection "find_last_special($special, $entries)"
Given an array of Reminder entries, find the last
\&\f(CW$special\fR\-type SPECIAL in the array.  Return
the entry if one was found or undef if not.
.ie n .SS "render($cr, $settings)"
.el .SS "render($cr, \f(CW$settings\fP)"
.IX Subsection "render($cr, $settings)"
Render a calendar for one month.  \f(CW$cr\fR is a Cairo
drawing context, and \f(CW$settings\fR is a settings hash
passed in by the caller.  See the source code of
\&\f(CW\*(C`rem2pdf\*(C'\fR for the contents of \f(CW$settings\fR
.ie n .SS "draw_row($cr, $settings, $so_far, $row, $start_day, $start_col)"
.el .SS "draw_row($cr, \f(CW$settings\fP, \f(CW$so_far\fP, \f(CW$row\fP, \f(CW$start_day\fP, \f(CW$start_col\fP)"
.IX Subsection "draw_row($cr, $settings, $so_far, $row, $start_day, $start_col)"
Draw a single row in the calendar.  \f(CW$cr\fR is a Cairo drawing context
and \f(CW$settings\fR is the settings hash passed to \f(CW\*(C`render\*(C'\fR.  \f(CW$so_far\fR
is the Y\-coordinate of the top of the row; drawing starts at this
coordinate.  \f(CW$start_day\fR is the day of the month at which the
row starts and \f(CW$start\fR col is the column number (0\-6) at which
to start drawing from \f(CW$start_day\fR
.PP
Returns the Y coordinate at which to start drawing the \fInext\fR
calendar row.
.ie n .SS "col_box_coordinates($so_far, $col, $height, $settings)"
.el .SS "col_box_coordinates($so_far, \f(CW$col\fP, \f(CW$height\fP, \f(CW$settings\fP)"
.IX Subsection "col_box_coordinates($so_far, $col, $height, $settings)"
Returns a four-element array \f(CW\*(C`($x1, $y1, $x2, $y2)\*(C'\fR representing
the bounding box of the calendar box at column \f(CW$col\fR (0\-6).  \f(CW$height\fR
is the height of the box and \f(CW$settings\fR is the settings hashref
passed to \f(CW\*(C`render\*(C'\fR.
.ie n .SS "draw_day($cr, $settings, $so_far, $day, $col, $height)"
.el .SS "draw_day($cr, \f(CW$settings\fP, \f(CW$so_far\fP, \f(CW$day\fP, \f(CW$col\fP, \f(CW$height\fP)"
.IX Subsection "draw_day($cr, $settings, $so_far, $day, $col, $height)"
Renders a single day's worth of reminders.  \f(CW$cr\fR is a Cairo
drawing context and \f(CW$settings\fR is the settings hash passed
to \f(CW\*(C`render\*(C'\fR.  \f(CW$so_far\fR is the Y\-coordinate of the top
of the box and \f(CW$col\fR is the column number.
.PP
\&\f(CW$height\fR is the height of the box.  If \f(CW$height\fR is passed
in as zero, then do not actually render anything... instead,
compute how high the box should be.  If \f(CW$height\fR is non-zero,
then it is the height of the box.
.PP
Returns the height required for the calendar box.
.ie n .SS "draw_daynames($cr, $settings, $so_far)"
.el .SS "draw_daynames($cr, \f(CW$settings\fP, \f(CW$so_far\fP)"
.IX Subsection "draw_daynames($cr, $settings, $so_far)"
Draw the weekday names heading.  \f(CW$cr\fR is a Cairo drawing context
and \f(CW$settings\fR is the settings hash passed to \f(CW\*(C`render\*(C'\fR.  \f(CW$so_far\fR
is the Y\-coordinate of the top of the row; drawing starts at this
coordinate.
.PP
Returns the Y coordinate at which to start drawing the first
calendar row.
.ie n .SS "draw_title($cr, $settings)"
.el .SS "draw_title($cr, \f(CW$settings\fP)"
.IX Subsection "draw_title($cr, $settings)"
Draw the title ("Monthname Year") at the top of the calendar.
\&\f(CW$cr\fR is a Cairo drawing context
and \f(CW$settings\fR is the settings hash passed to \f(CW\*(C`render\*(C'\fR.
.PP
Returns the Y coordinate at which to start drawing the row
containing the weekday names.
.ie n .SS "draw_small_calendar($cr, $x, $y, $width, $height, $settings, $month, $days, $start_wkday)"
.el .SS "draw_small_calendar($cr, \f(CW$x\fP, \f(CW$y\fP, \f(CW$width\fP, \f(CW$height\fP, \f(CW$settings\fP, \f(CW$month\fP, \f(CW$days\fP, \f(CW$start_wkday\fP)"
.IX Subsection "draw_small_calendar($cr, $x, $y, $width, $height, $settings, $month, $days, $start_wkday)"
Draw a small calendar on the Cairo context \f(CW$cr\fR.  The top left-hand
corner of the box is at \f(CW\*(C`($x, $y)\*(C'\fR and the size of the box is
\&\f(CW\*(C`($width, $height\*(C'\fR).  \f(CW$settings\fR is the settings hashref passed to
\&\f(CW\*(C`render\*(C'\fR.  \f(CW$month\fR is the name of the month to draw and \f(CW$days\fR is
the number of days in the month.  Finally, \f(CW$start_wkday\fR is the
weekday (0=Sunday, 6=Saturday) on which the month starts
.SH NAME
Remind::PDF::Multi \- A container for multiple months' worth of calendar data
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`remind \-ppp\*(C'\fR output consists of a JSON array with each element
representing one month's worth of reminders.  \f(CW\*(C`Remind::PDF::Multi\*(C'\fR
reads this output and returns an instance of itself containing
an array of \f(CW\*(C`Remind::PDF\*(C'\fR objects, one object for each month.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.ie n .SS "Remind::PDF::Multi\->create_from_stream($in, $specials_accepted)"
.el .SS "Remind::PDF::Multi\->create_from_stream($in, \f(CW$specials_accepted\fP)"
.IX Subsection "Remind::PDF::Multi->create_from_stream($in, $specials_accepted)"
This method reads data from an open file handle \f(CW$in\fR.  \f(CW$specials_accepted\fR
is a hashref of SPECIAL reminder types to accept; the key is the name of the
SPECIAL (all lower-case) and the value should be 1.  Any SPECIAL reminders
not in the hash are ignored.
.PP
This function returns a two-element array: \f(CW\*(C`($obj, $err)\*(C'\fR.  On
success, \f(CW$obj\fR will be a \f(CW\*(C`Remind::PDF::Multi\*(C'\fR object and \f(CW$err\fR
will be undef.  On failure, \f(CW$obj\fR will be undef and \f(CW$err\fR will be
an error message.
.ie n .SS "Remind::PDF::Multi\->create_from_json($json, $specials_accepted)"
.el .SS "Remind::PDF::Multi\->create_from_json($json, \f(CW$specials_accepted\fP)"
.IX Subsection "Remind::PDF::Multi->create_from_json($json, $specials_accepted)"
This method takes data from a JSON string <$json>.  \f(CW$specials_accepted\fR
is a hashref of SPECIAL reminder types to accept; the key is the name of the
SPECIAL (all lower-case) and the value should be 1.  Any SPECIAL reminders
not in the hash are ignored.
.PP
This function returns a two-element array: \f(CW\*(C`($obj, $err)\*(C'\fR.  On
success, \f(CW$obj\fR will be a \f(CW\*(C`Remind::PDF::Multi\*(C'\fR object and \f(CW$err\fR
will be undef.  On failure, \f(CW$obj\fR will be undef and \f(CW$err\fR will be
an error message.
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.ie n .SS "render($cr, $settings)"
.el .SS "render($cr, \f(CW$settings\fP)"
.IX Subsection "render($cr, $settings)"
Iterate through all the \f(CW\*(C`Remind::PDF\*(C'\fR objects
and call their \f(CW\*(C`render\*(C'\fR methods.  This method
renders as many months worth of calendar data
as were read from the \f(CW\*(C`remind \-ppp\*(C'\fR stream