NAME

PostScript::ScheduleGrid - Print a schedule in a grid format

VERSION

This document describes version 0.05 of PostScript::ScheduleGrid, released August 22, 2015 as part of PostScript-ScheduleGrid version 0.05.

SYNOPSIS

  use DateTime;
  use PostScript::ScheduleGrid;

  sub dt # Trivial parser to create DateTime objects
  {
    my %dt = qw(time_zone local);
    @dt{qw( year month day hour minute )} = split /\D+/, $_[0];
    while (my ($k, $v) = each %dt) { delete $dt{$k} unless defined $v }
    DateTime->new(\%dt);
  } # end dt

  my $grid = PostScript::ScheduleGrid->new(
    start_date => dt('2011-10-02 18'),
    end_date   => dt('2011-10-02 22'),
    categories => {
      G  => 'Solid',
      GR => [qw( Stripe direction right )],
    },
    resource_title => 'Channel',
    resources => [
      { name => '2 FOO',
        schedule => [
          [ dt('2011-10-02 18'), dt('2011-10-02 19'), 'Some hour-long show', 'G' ],
          [ dt('2011-10-02 19'), dt('2011-10-02 20'), 'Another hour-long show' ],
          [ dt('2011-10-02 20'), dt('2011-10-02 20:30'), 'Half-hour show', 'GR' ],
          [ dt('2011-10-02 21'), dt('2011-10-02 22'), 'Show order insignificant' ],
          [ dt('2011-10-02 20:30'), dt('2011-10-02 21'), 'Second half-hour' ],
        ],
      }, # end resource 2 FOO
      { name => '1 Channel',
        schedule => [
          [ dt('2011-10-02 18'), dt('2011-10-02 22'),
            'Unlike events, the order of resources is significant.' ],
        ],
      }, # end resource 1 Channel
    ],
  );

  $grid->output('/tmp/testgrid.ps');

DESCRIPTION

PostScript::ScheduleGrid generates a printable schedule in a grid format commonly used for TV listings. (If you are considering using it for actual TV listings, you should look at PostScript::ScheduleGrid::XMLTV, which creates a PostScript::ScheduleGrid from TV listings data gathered by XMLTV. http://xmltv.org)

A schedule is comprised of resources in which events take place at specified times. For a television schedule, each TV channel is a resource, and each show is an event. For a conference, each meeting room is a resource, and each talk is an event.

The printed grid has a row for each resource, with times as columns. The position and size of an event indicates the time it begins and ends, as well as which resource it's associated with. It's not possible for an event to be associated with more than one resource. If you need that, you can simulate it by assigning similar events to each resource.

If you want to save the schedule as a PDF, you can pass a ScheduleGrid object to "psconvert" in PostScript::Convert (instead of calling the output method).

ATTRIBUTES

Grid Data

These attributes supply the data that will appear in the grid.

end_date

This is the date and time at which the listings will end. Required.

resource_title

This is the header that will be displayed (in the cell_font) at the top and bottom of the column of resource names. The default is to have no header. (For TV listings, you might set this to Channel.)

resources

This is an arrayref of resource information. Resources are listed in the order they appear. Each resource is represented by a hashref with the following keys:

name

The resource name as it should appear in the grid.

lines

The number of lines that should be used for event listings (default 1).

schedule

An arrayref of events associated with this resource. Each event is represented by a 4-element arrayref: [START, STOP, NAME, CATEGORY].

START and STOP are the start and stop times (as DateTime objects). NAME is the name of the event as it should appear in the grid. The optional CATEGORY causes the event to be displayed specially. If present, it must be one of the keys in the categories attribute.

The arrayref will be modified during the grid processing. Events may be listed in any order; the arrayref will be sorted automatically.

All other keys are reserved. Any key beginning with an uppercase letter is reserved for use by programs using PostScript::ScheduleGrid (and will be ignored by this module).

As an example, in a grid displaying TV listings, each channel would be a resource, and each program airing on that channel would be an event.

start_date

This is the date and time at which the listings will begin. Required.

time_zone

The time zone that the listings are in. Any floating times will be converted to this time zone. Defaults to your local time zone.

Grid Formatting

These attributes affect the PostScript::File object, or control the formatting of the grid. All dimensions are in points.

bottom_margin

This is the bottom margin (default 36, or 1/2 inch).

categories

This is not a normal attribute; you may supply a value to the constructor, but it cannot be accessed afterwards. It is a hashref keyed by category name. Category names are arbitrary strings. Each event may be assigned to one category.

The value associated with the category name defines the style that will be applied to events in this category. It is either a string (a class name), or an arrayref of class name and parameters: [ CLASS, KEY1, VALUE1, KEY2, VALUE2, ... ].

The class name is prefixed with PostScript::ScheduleGrid::Style:: unless it begins with = (which is removed). The class must do the Style role.

The standard styles are Solid (for a solid background) and Stripe (for a diagonally striped background).

Note: If you list the same style class (with the same parameters) more than once, only one copy of that style will be created.

cell_bot

This is the space between the bottom of a cell and the baseline of the text inside it (default 2.5).

cell_font

This is the name of the font used for event titles in the grid (default Helvetica).

cell_font_size

This is the size of the font used for event titles in the grid (default 7).

cell_left

This is the space between the left of a cell and the beginning of the text inside it (default 1.4).

extra_height

This is the height added to line_height for a row with multiple lines. The height of a row is (line_height + (lines-1) * extra_height). Defaults to cell_font_size.

five_min_width

This is the width of five minutes in the grid (all durations are rounded to the nearest five minutes). You should probably keep the default value, which is calculated based on the page margins and the title_width.

grid_hours

This is the number of hours that one grid will span (default 4 in portrait mode, 6 in landscape mode).

heading_baseline

This is the space between the baseline of the heading and the top line of the grid (default 3).

heading_font

This is the name of the font used for the date shown above the grid (default Helvetica-Bold).

heading_font_size

This is the size of the font used for the date (default 12).

heading_format

This is the CLDR format used for the date shown above the grid (default EEEE, MMMM d, y).

landscape

If set to a true value, the listings will be printed in landscape mode. The default is false.

left_margin

This is the left margin (default 22, or about 0.3 inch).

line_height

This is the height of a single-line row on the grid (default 10).

paper_size

This the paper size (default Letter). See "paper" in PostScript::File.

ps_parameters

This is a hashref of additional parameters to pass to PostScript::File's constructor. These values will override the parameters that PostScript::ScheduleGrid generates itself (but you should reserve this for things that can't be controlled through other PostScript::ScheduleGrid attributes).

right_margin

This is the right margin (default 22, or about 0.3 inch).

time_headers

This is an arrayref of two strings containing the CLDR formats used for the headers displaying the time (default ['h a', 'h:mm']). The first string is used on the hour, and the second is used on the half-hour.

title_baseline

This is the space between the baseline of a resource name or time and the grid line below it (default 1.6875).

title_font

This is the name of the font used for resource names & times (default Helvetica-Bold).

title_font_size

This is the size of the font used for resource names & times (default 9).

title_width

This is the width of the resources column in the grid. By default, it is calculated to be just wide enough for the longest resource name.

top_margin

This is the top margin (default 36, or 1/2 inch).

Other Attributes

You will probably not need to use these attributes unless you are trying advanced tasks.

ps

This is the PostScript::File object containing the grid.

METHODS

output

  $rpt->output($filename [, $dir]) # save to file
  $rpt->output($filehandle)        # print to open filehandle
  $rpt->output()                   # return as string

This method takes the same parameters as "output" in PostScript::File. You can pass a filename (and optional directory name) to store the listings in a file. (No extension will be added to $filename, so it should normally end in ".ps".)

You can also pass an open filehandle (anything recognized by "filehandle" in Scalar::Util) to print the PostScript code to that filehandle. The filehandle will not be closed afterwards.

If you don't pass a filename or filehandle, then the PostScript code is returned as a string.

SEE ALSO

PostScript::ScheduleGrid::XMLTV, for creating a grid with TV listings from XMLTV.

DIAGNOSTICS

%s does not do PostScript::ScheduleGrid::Role::Style

A class used as a category style must do the correct role. The specified class doesn't.

%s is not a supported value for 'lines' in resource %s

The number of lines must be a positive integer. The specified resource tried to use a different value.

All resources must have a name

One of the hashrefs in resources did not have a name key.

Category name cannot be empty

You cannot define the empty string as a category. Instead of changing the default style, you must assign every cell a category.

Invalid category '%s' in %s event at %s

The event associated with the specified resource and start time had a category that doesn't exist.

CONFIGURATION AND ENVIRONMENT

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

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-ScheduleGrid AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-ScheduleGrid.

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

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.

cpanm PostScript::ScheduleGrid

perl -MCPAN -e shell
install PostScript::ScheduleGrid