# `Calendrical.Format`

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.

# `default_calendar_css_class`

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`

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?`

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`

```elixir
@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
  `t: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.

### Examples

    => Calendrical.Format.month(2019, 4)

    => Calendrical.Format.month(2019, 4)

    => Calendrical.Format.month(2019, 4, formatter: Calendrical.Formatter.Markdown, locale: "fr")

# `year`

```elixir
@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
  `t: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.

### Examples

    => Calendrical.Format.year(2019)

    => Calendrical.Format.year(2019, formatter: Calendrical.Formatter.Markdown)

    => Calendrical.Format.year(2019, formatter: Calendrical.Formatter.Markdown, locale: "fr")

---

*Consult [api-reference.md](api-reference.md) for complete listing*