Calendrical.Format (Calendrical v0.13.0)

Renders Calendrical calendars as years, months, weeks, and days using a pluggable formatter.

Calendrical.Format walks a calendar at year, month, or week granularity and delegates the actual rendering to a formatter module that implements the Calendrical.Formatter behaviour. The library ships with HTML and Markdown formatters; the default formatter is returned by default_formatter_module/0.

Custom formatters can be added by implementing the Calendrical.Formatter behaviour (format_year/3, format_month/4, format_week/5, and format_day/4).

All entry points (year/2, month/3) accept a keyword list of options.

Summary

Functions

default_calendar_css_class()

Returns the default CSS class used by the HTML formatters when wrapping a calendar in a container element.

default_formatter_module()

Returns the default formatter module used when no :formatter option is given to year/2 or month/3.

formatter_module?(formatter)

Returns true if the given module appears to implement the Calendrical.Formatter behaviour.

month(year, month, options \\ [])

Formats one calendar month using the configured formatter.

year(year, options \\ [])

Formats one calendar year using the configured formatter.

Functions

default_calendar_css_class()

@spec default_calendar_css_class() :: String.t()

Returns the default CSS class used by the HTML formatters when wrapping a calendar in a container element.

Returns

A string. Currently "cldr_calendar".

Examples

iex> Calendrical.Format.default_calendar_css_class()
"cldr_calendar"

default_formatter_module()

@spec default_formatter_module() :: module()

Returns the default formatter module used when no :formatter option is given to year/2 or month/3.

Returns

The module name of the default HTML formatter.

Examples

iex> Calendrical.Format.default_formatter_module()
Calendrical.Formatter.HTML.Basic

formatter_module?(formatter)

@spec formatter_module?(module()) :: boolean()

Returns true if the given module appears to implement the Calendrical.Formatter behaviour.

The check is a runtime duck-typing check: the module is loaded and inspected for an exported format_year/3 function.

Arguments

formatter is a module name.

Returns

true if the module exports format_year/3, otherwise false.

Examples

iex> Calendrical.Format.formatter_module?(Calendrical.Formatter.HTML.Basic)
true

iex> Calendrical.Format.formatter_module?(String)
false

month(year, month, options \\ [])

@spec month(Calendar.year(), Calendar.month(), Keyword.t() | map()) :: any()

Formats one calendar month using the configured formatter.

Arguments

year is the year of the calendar to be formatted.
month is the month of the calendar to be formatted.
options is a keyword list of options.

Options

:calendar is the Calendrical calendar module to format. Defaults to Calendrical.Gregorian.
:formatter is the formatter module. Defaults to the value of default_formatter_module/0.
:locale is a locale identifier atom, string, or a Localize.LanguageTag.t/0. The default is Localize.get_locale/0.
Any additional formatter-specific options are passed through to the formatter callbacks.

Returns

The value returned by the format_month/4 callback of the configured formatter. The built-in formatters return a string.
{:error, exception} if the options are invalid.

Examples

iex> month = Calendrical.Format.month(2019, 4)
iex> String.starts_with?(month, "<table class=\"cldr_calendar\">")
true

iex> Calendrical.Format.month(2019, 4, formatter: NotAFormatter)
{:error, %Calendrical.Formatter.UnknownFormatterError{formatter: NotAFormatter}}

year(year, options \\ [])

@spec year(Calendar.year(), Keyword.t() | map()) :: any()

Formats one calendar year using the configured formatter.

Arguments

year is the year of the calendar to be formatted.
options is a keyword list of options.

Options

:calendar is the Calendrical calendar module to format. Defaults to Calendrical.Gregorian.
:formatter is the formatter module. Defaults to the value of default_formatter_module/0.
:locale is a locale identifier atom, string, or a Localize.LanguageTag.t/0. The default is Localize.get_locale/0.
Any additional formatter-specific options are passed through to the formatter callbacks.

Returns

The value returned by the format_year/3 callback of the configured formatter. The built-in formatters return a string.
{:error, exception} if the options are invalid.

Examples

iex> year = Calendrical.Format.year(2019)
iex> String.starts_with?(year, "<div class=\"cldr_calendar_year\">")
true

iex> markdown = Calendrical.Format.year(2019, formatter: Calendrical.Formatter.Markdown)
iex> is_binary(markdown)
true