/ 
PostScript-Calendar-1.02
River stage zero No dependents
/ PostScript::Calendar

NAME

PostScript::Calendar - Generate a monthly calendar in PostScript

VERSION

This document describes version 1.02 of PostScript::Calendar, released June 13, 2015.

SYNOPSIS

use PostScript::Calendar;

my $cal = PostScript::Calendar->new($year, $month, phases => 1,
                                    mini_calendars => 'before');
$cal->output('filename');

# Or, if you want PDF output instead of PostScript:
use PostScript::Convert;
psconvert($cal, "filename.pdf");

DESCRIPTION

PostScript::Calendar generates printable calendars using PostScript.

PostScript::Calendar uses Date::Calc's *_to_Text functions, so you can change the language used by calling Date::Calc's Language function before creating your calendar.

Years must be fully specified (e.g., use 1990, not 90). Months range from 1 to 12. Days of the week can be specified as 0 to 7 (where Sunday is either 0 or 7, Monday is 1, etc.).

All dimensions are specified in PostScript points (72 per inch).

Colors can be specified either as a number in the range 0 to 1 (where 0 is black and 1 is white), or an arrayref of three numbers [ Red, Green, Blue ] where each number is in the range 0 to 1.

In addition, you can specify an RGB color in the HTML hex triplet form prefixed by # (like #FFFF00 or #FF0 for yellow).

METHODS

new

$cal = PostScript::Calendar->new($year, $month, [key => value, ...])

This constructs a new PostScript::Calendar object for $year and $month.

There are a large number of parameters you can pass to customize how the calendar is displayed. They are all passed as name => value pairs.

border

If false, omit the border around the calendar grid (only internal grid lines are drawn). The default is true.

border_width

The width of the border drawn around the calendar grid (assuming border is true). The default is 0.72 points, which is 3 pixels on a 300dpi printer.

condense

If true, reduce calendars that would span 6 rows down to 5 rows by combining either the first or last day with its neighbor. The default is false.

day_height

The maximum height of a date row. This is useful to prevent portrait-mode calendars from taking up the entire page (which just doesn't look right). The default is 0, which means there is no maximum value. I recommend 96 for a portrait-mode calendar on US letter size paper.

grid

If false, omit the internal grid lines in the calendar (only the external border is drawn). The default is true.

grid_width

The width of the internal grid lines in the calendar (assuming grid is true). The default is 0.72 points, which is 3 pixels on a 300dpi printer.

mini_calendars

This causes small calendars for the previous and next months to be printed. The value should be "before" to put them before the first of the month, "after" to put them after the last day of the month, or "split" to put the previous month before and the next month after. The default is a false value (which means no mini calendars).

phases

If true, the phase of the moon icons are printed (requires Astro::MoonPhase 0.60). The default is false.

title

The title to be printed at the top of the calendar. The default is "Month YEAR" (where Month comes from Month_to_Text, and YEAR is numeric.) Setting this to the empty string automatically sets title_size and title_skip to 0 (completely suppressing the title).

days

An arrayref specifying the days of the week to be included in the calendar. The first day must be in the range 0 to 6 (where Sunday is 0, Monday is 1, etc.). Subsequent days must be in ascending order, up to the initial day + 6.The default is [ 0 .. 6 ] (meaning Sunday thru Saturday). Other popular values are [ 1 .. 7 ] for Monday thru Sunday or [ 1 .. 5 ] for Monday thru Friday (no weekends).

You may skip over days if you don't want them included. For example, [ 3, 5, 8 ] would display Wednesday, Friday, and Monday (with weeks starting on Wednesday).

day_names

Arrayref of the column labels. Defaults to passing the (normalized) values from days thru Date::Calc's Day_of_Week_to_Text, which is probably what you want.

title_font

The font to use for the title. Defaults to Helvetica-iso.

title_size

The size of the title_font to use. Defaults to 14.

title_skip

Extra space (in points) to leave below the title. Defaults to 5.

label_font

The font to use for the days of the week. Defaults to title_font.

label_size

The size of the label_font to use. Defaults to title_size.

label_skip

Extra space (in points) to leave below the weekday labels. Defaults to title_skip.

date_font

The font to use for the dates of the month. Defaults to Helvetica-Oblique-iso.

date_size

The size of the date_font to use. Defaults to title_size.

event_font

The font to use for text events (added by add_event). Defaults to Helvetica-iso.

event_size

The size of the event_font to use. Defaults to 8.

event_skip

Extra space (in points) to leave between lines of event text. Defaults to 2.

mini_font

The font to use for mini calendars. Defaults to Helvetica-iso.

mini_size

The size of the mini_font to use. Defaults to 6.

mini_skip

Extra space (in points) to leave between the lines of mini calendars. Defaults to 3.

date_right_margin

Space (in points) to leave between the date and the gridline. Defaults to 4.

date_top_margin

Space (in points) to leave between the date and the gridline. Defaults to 2.

event_margin

This is used as the default value for event_top_margin, event_left_margin, and event_right_margin.

event_top_margin

The space (in points) to leave above event text. Defaults to event_margin, or 2 if event_margin is not specified.

event_left_margin

The space (in points) to leave to the left of event text. Defaults to event_margin, or 3 if event_margin is not specified.

event_right_margin

The space (in points) to leave to the right of event text. Defaults to event_margin, or 2 if event_margin is not specified.

mini_margin

This is used as the default value for mini_top_margin and mini_side_margins. Defaults to 4.

mini_top_margin

The space (in points) to leave above mini calendars. Defaults to mini_margin.

mini_side_margins

The space (in points) to leave on each side of mini calendars. Defaults to mini_margin.

moon_dark

The color to use for the dark portions of the moon icon. Defaults to 0 (black).

moon_light

The color to use for the light portions of the moon icon. Defaults to 1 (white).

moon_margin

Space to leave above and to the left of the moon icon. Defaults to 6.

shade_color

The default background color used by the shade method. Defaults to 0.85 (a light gray).

shade_days_of_week

An arrayref of days of the week to be passed to the shade_days_of_week method. (I found it convenient to be able to pass this to the constructor instead of making a separate method call.)

The first element of the arrayref may be a hashref of options.

margin

This is used as the default value for top_margin, side_margins, and bottom_margin.

side_margins

The space (in points) to leave on each side of the calendar. Defaults to margin, or 24 if margin is not specified.

top_margin

The space (in points) to leave above the calendar. Defaults to margin, or 36 if margin is not specified.

bottom_margin

The space (in points) to leave below the calendar. Defaults to margin, or 24 if margin is not specified.

paper

The paper size to pass to PostScript::File. Defaults to "Letter". Not used if you supply ps_file.

landscape

If true, print calendar in landscape mode. Defaults to false. Not used if you supply ps_file.

ps_file

Allows you to pass in a PostScript::File (or compatible) object for the calendar to use. By default, a new PostScript::File object is created. Passing an explicit undef also creates a new object.

add_event

$cal->add_event($date, $message)

This prints the text $message on $date, where $date is the day of the month. You may call this multiple times for the same date. Messages will be printed in the order they were added. $message may contain newlines to force line breaks.

generate

$cal->generate

This actually generates the calendar, placing it in the PostScript::File object. You shouldn't need to call this, because output calls it automatically.

output

$cal->output($filename)

This passes its parameters to PostScript::File::output (after calling generate if necessary). Normally, you just pass the filename to write. Note that PostScript::File will append ".ps" to the output filename.

ps_file

$cal->ps_file

This returns the PostScript::File object that $cal is using. Only needed for advanced techniques.

shade

$cal->shade( [\%options,] $date, ...)

This colors the background of the specified date(s), where $date is the day of the month. Any number of dates can be given.

Optionally, the first argument may be a hashref containing options. The recognized options are:

shade_color

The color to shade the day's background. Defaults to the value passed to the constructor.

moon_dark

The color to use for the dark portions of the moon phase indicator (if present). Defaults to the value passed to the constructor.

moon_light

The color to use for the light portions of the moon phase indicator (if present). Defaults to the value passed to the constructor.

shade_days_of_week

$cal->shade_days_of_week( [\%options,] $day, ...)

This calls shade for all dates that fall on the specified day(s) of the week. Each $day should be 0-7 (where Sunday is either 0 or 7).

Optionally, the first argument may be a hashref containing options. See "shade" for the available options.

DIAGNOSTICS

WARNING: Event text for YYYY-MM-DD doesn't fit

You supplied more event text for the specified date than would fit in the box. You'll have to use a smaller font, smaller margins, or less text.

CONFIGURATION AND ENVIRONMENT

PostScript::Calendar requires no configuration files or environment variables.

DEPENDENCIES

Date::Calc (5.0 or later) and PostScript::File (2.20 or later).

If you want to display phases of the moon, you'll need Astro::MoonPhase (0.60 or later).

All of these are available on CPAN.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-PostScript-Calendar AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-Calendar.

You can follow or contribute to PostScript-Calendar's development at https://github.com/madsen/postscript-calendar.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

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 LICENSE, 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.