Provided by: libhtml-calendarmonth-perl_2.04-1_all bug

NAME

       HTML::CalendarMonth - Generate and manipulate HTML calendar months

SYNOPSIS

        use HTML::CalendarMonth;

        # Using regular HTML::Element creation
        my $c = HTML::CalendarMonth->new( month => 8, year => 2010 );
        print $c->as_HTML;

        # Full locale support via DateTime::Locale
        my $c2 = HTML::CalendarMonth->new(
          month  => 8,
          year   => 2010,
          locale => 'zu-ZA'
        );
        print $c2->as_HTML;

        # HTML-Tree integration
        my $tree = HTML::TreeBuilder->parse_file('cal.html');
        $tree->find_by_attribute(class => 'hcm-calendar')->replace_with($c);
        print $tree->as_HTML;

        # clean up if you're not done, HTML::Element structures must be
        # manually destroyed
        $c->delete; $c2->delete;

DESCRIPTION

       HTML::CalendarMonth is a subclass of HTML::ElementTable. See HTML::ElementTable(3) for how
       that class works, for it affects this module on many levels. Like HTML::ElementTable,
       HTML::CalendarMonth is an enhanced HTML::Element with methods added to facilitate the
       manipulation of the calendar table elements as a whole.

       The primary interaction with HTML::CalendarMonth is through items rather than cell
       coordinates like HTML::ElementTable uses. An item is merely a string that represents the
       content of the cell of interest within the calendar. For instance, the element
       representing the 14th day of the month would be returned by "$c->item(14)". Similarly, the
       element representing the header for Monday would be returned by "$c- >item('Mo')". If the
       year happened to by 2010, then "$c- >item(2010)" would return the cell representing the
       year. Since years and particular months change frequently, it is probably more useful to
       take advantage of the "month()" and "year()" methods, which return their respective
       values. The following is therefore the same as explicitely referencing the year:
       "$c->item($c- >year())".

       Multiple cells of the calendar can be manipulated as if they were a single element. For
       instance, "$c->item(15)->attr(class => 'fancyday')" would alter the class of the cell
       representing the 15th. By the same token, "$c->item(15, 16, 17, 23)->attr(class =>
       'fancyday')" would do the same thing for all cells containing the days passed to the
       "item()" method.

       Underneath, the calendar is still nothing more than a table structure, the same as
       provided by the HTML::ElementTable class. In addition to the item based access methods
       above, calendar cells can still be accessed using row and column grid coordinates using
       the "cell()" method provided by the table class. All coordinate-based methods in the table
       class are accessible to the calendar class.

       The module includes support for week-of-the-year numbering, arbitrary 1st day of the week
       definitions, and locale support.

       Dates that are beyond the range of the built-in time functions of perl are handled either
       by the ncal/cal command, Date::Calc, DateTime, or Date::Manip. The presence of any one of
       these utilities and modules will suffice for these far flung date calculations. One of
       these utilities (with the exception of 'cal') is also required if you want to use week-of-
       year numbering.

       Full locale support is offered via DateTime::Locale. For a full list of supported locale
       id's, look at HTML::CalendarMonth::Locale->locales().

METHODS

       All arguments appearing in [brackets] are optional, and do not represent anonymous array
       references.

   Constructor
       new()
           With no arguments, the constructor will return a calendar object representing the
           current month with a default appearance. The initial configuration of the calendar is
           controlled by special attributes. Non- calendar related attributes are passed along to
           HTML::ElementTable. Any non-table related attributes left after that are passed to
           HTML::Element while constructing the <table> tag. See HTML::ElementTable if you are
           interested in attributes that can be passed along to that class.

           Special Attributes for HTML::CalendarMonth:

           month
               1-12, or Jan-Dec.  Defaults to current month.

           year
               Four digit representation. Defaults to current year.

           head_m
               Specifies whether to display the month header. Default 1.

           head_y
               Specifies whether to display the year header. Default 1.

           head_dow
               Specifies whether to display days of the week header. Default 1.

           head_week
               Specifies whether to display the week-of-year numbering. Default 0.

           locale
               Specifies the id of the locale in which to render the calendar. Default is
               'en-US'. By default, this will also control determine which day is considered to
               be the first day of the week. See HTML::CalendarMonth::Locale for more
               information. If for some reason you prefer to use different labels than those
               provided by "locale", see the "alias" attribute below. NOTE: DateTime::Locale
               versions 0.92 and earlier use underscores rather than dashes, e.g. 'en_US'.

           full_days
               Specifies whether or not to use full day names or their abbreviated names. Default
               is 0, use abbreviated names. Use -1 for 'narrow' mode, the shortest (not
               guaranteed to be unique) abbreviations.

           full_months
               Specifies whether or not to use full month names or their abbreviated names.
               Default is 1, use full names. Use -1 for 'narrow' mode, the shortest (not
               guaranteed to be unique) abbreviations.

           alias
               Takes a hash reference mapping labels provided by "locale" to any custom label you
               prefer. Lookups, such as "day('Sun')", will still use the locale string, but when
               the calendar is rendered the aliased value will appear.

           week_begin
               Specify first day of the week, which can be 1..7, starting with Sunday.  In order
               to specify Monday, set this to 2, and so on. By default, this is determined based
               on the locale.

           enable_css
               Set some handy CSS class attributes on elements, enabled by default.  Currently
               the classes are:

                 hcm-table       Set on the E<lt>tableE<gt> tag of the calendar
                 hcm-day-head    Set on the day-of-week E<lt>trE<gt> or E<lt>tdE<gt> tags
                 hcm-year-head   Set on the E<lt>tdE<gt> tag for the year
                 hcm-month-head  Set on the E<lt>tdE<gt> tag for the month
                 hcm-week-head   Set on the E<lt>tdE<gt> tags for the week-of-year

           semantic_css
               Sets some additional CSS class attributes on elements, disabled by default. The
               notion of 'today' is taken either from the system clock (default) or from the
               'today' parameter as provided to new(). Currently these classes are:

                 hcm-today    Set on the E<lt>tdE<gt> tag for today, if present
                 hcm-past     Set on the E<lt>tdE<gt> tags for prior days, if present
                 hcm-future   Set on the E<lt>tdE<gt> tags for subsequent days, if present

           today
               Specify the value for 'today' if different from the local time as reported by the
               system clock (the default). If specified as two or less digits, it is assumed to
               be one of the days of the month in the current calendar. If more than two digits,
               it is assumed to be a epoch time in seconds. Otherwise it must be given as a
               string of the form 'YYYY-mm- dd'. Note that the default value as determined by the
               system clock uses localtime rather than gmtime.

           historic
               This option is ignored for dates that do not exceed the range of the built- in
               perl time functions. For dates that do exceed these ranges, this option specifies
               the default calculation method. When set, if the 'ncal' or 'cal' command is
               available on your system, that will be used rather than the Date::Calc or
               Date::Manip modules. This can be an issue since the date modules blindly
               extrapolate the Gregorian calendar, whereas ncal/cal will revert to the Julian
               calendar during September 1752. If either ncal or cal are not available on your
               system, this attribute is meaningless. Defaults to 1.

   Item Query Methods
       The following methods return lists of item *symbols* (28, 29, 'Thu', ...) that are related
       in some way to the provided list of items. The returned symbols may then be used as
       arguments to the glob methods detailed further below.

       row_items(item1, [item2, ...])
           Returns all item symbols in rows shared by the provided item symbols.

       col_items(item1, [item2, ...])
           Returns all item symbols in columns shared by the provided item symbols.

       daycol_items(col_item1, [col_item2, ...])
           Same as col_items(), but the returned item symbols are limited to those that are not
           header items (month, year, day-of-week).

       row_of(item1, [item2, ...])
           Returns the row indices of rows containing the provided item symbols.

       col_of(item1, [item2, ...])
           Returns the column indices of columns containing the provided item symbols.

       lastday()
           Returns the day number (symbol) of the last day of the month.

       dow1st()
           Returns the column index for the first day of the month.

       days()
           Returns a list of all days of the month as numbers.

       week_nums()
           Returns a list of week-of-year numbers for this month.

       dayheaders()
           Returns a list of all day headers (Su..Sa)

       headers()
           Returns a list of all headers (month, year, dayheaders)

       items()
           Returns a list of all item symbols (day number, header values) in the calendar.

       last_col()
           Returns the index of the last column of the calendar (note that this could be the
           week-of-year column if head_week is enabled).

       last_day_col()
           Returns the index of the last column of the calendar containing days of the month
           (same as last_col() unless week-of-year is enabled).

       first_week_row()
           Returns the index of the first row of the calendar containing day items (ie, the first
           week).

       last_row()
           Returns the index of the last row of the calendar.

       today()
           Returns the day of month for 'today', if present in the current calendar.

       past_days()
           Returns a list of days prior to 'today'. If 'today' is in a future month, all days are
           returned. If 'today' is in a past month, no days are returned.

       future_days()
           Returns a list of days after 'today'. If 'today' is in a past month, all days are
           returned. If 'today' is in a future month, no days are returned.

   Glob Methods
       Glob methods return references that are functionally equivalent to an individual calendar
       cell. Mostly, they provide item based analogues to the glob methods provided in
       HTML::ElementTable. In methods dealing with rows, columns, and boxes, the globs include
       empty calendar cells (which would otherwise need to be accessed through native
       HTML::ElementTable methods). The row and column numbers returned by the item methods above
       are compatible with the grid based methods in HTML::ElementTable.

       For details on how these globs work, check out HTML::ElementTable and HTML::ElementGlob.

       item(item1, [item2, ...])
           Returns all cells containing the provided item symbols.

       item_row(item1, [item2, ...])
           Returns all cells in all rows occupied by the provided item symbols.

       item_day_row(item1, [item2, ...])
           Same as item_row() except excludes week-of-year cells, if present.

       item_col(item1, [item2, ...])
           Returns all cells in all columns occupied by the provided item symbols.

       item_daycol(item1, [item2, ...])
           Same as item_col() except limits the cells to non header cells.

       item_week_nums()
           Returns all week-of-year cells, if present.

       item_box(item1a, item1b, [item2a, item2b, ...])
           Returns all cells in the boxes defined by the item pairs provided.

       allheaders()
           Returns all header cells.

       alldays()
           Returns all non header cells, including empty cells.

       all()
           Returns all cells in the calendar, including empty cells.

   Transformation Methods
       The following methods provide ways of translating between various item symbols,
       coordinates, and other representations.

       coords_of(item)
           Returns the row and column coordinates of the provided item symbol, for use with the
           grid based methods in HTML::ElementTable.

       item_at(row,column)
           Returns the item symbol of the item at the provided coordinates, for use with the item
           based methods of HTML::CalendarMonth.

       monthname(monthnum)
           Returns the name (item symbol) of the month number provided, where monthnum can be
           1..12.

       monthnum(monthname)
           Returns the number (1..12) of the month name provided. Only a minimal case-insensitive
           match on the month name is necessary; the proper item symbol for the month will be
           determined from this match.

       dayname(daynum)
           Returns the name (item symbol) of the day of week header for a number of a day of the
           week, where daynum is 1..7.

       daynum(dayname)
           Returns the number of the day of the week given the symbolic name for that day
           (Su..Sa).

       daytime(day)
           Returns the number in seconds since the epoch for a given day. The day must be present
           in the current calendar.

   Other Methods
       default_css()
           Returns a simple style sheet as a string that can be used in an HTML document in
           conjunction with the classes assigned to elements when css is enabled.

REQUIRES

       HTML::ElementTable

OPTIONAL

       Date::Calc, DateTime, or Date::Manip (only if you want week-of- year numbering or non-
       contemporary dates on a system without the cal command)

AUTHOR

       Matthew P. Sisk, <sisk@mojotoad.com>

COPYRIGHT

       Copyright (c) 1998-2015 Matthew P. Sisk. All rights reserved. All wrongs revenged. This
       program is free software; you can redistribute it and/or modify it under the same terms as
       Perl itself.

SEE ALSO

       A useful page of examples can be found at
       http://www.mojotoad.com/sisk/projects/HTML-CalendarMonth.

       For information on iso639 standards for abbreviations for language names, see
       http://www.loc.gov/standards/iso639-2/englangn.html

       HTML::ElementTable(3), HTML::Element(3), perl(1)