# `Calendrical.Formatter`

Calendar formatter behaviour.

This behaviour defines a set of callbacks that are invoked during
the formatting of a calendar.

At each point in the formatting process the callbacks are invoked
from the "inside out". That is, `format_day/4` is invoked for each
day of the week, then `format_week/5` is called, then
`format_month/4` and finally `format_year/3` is called if
required.

# `format_day`

```elixir
@callback format_day(
  date :: Date.t(),
  year :: Calendar.year(),
  month :: Calendar.month(),
  options :: map()
) :: any()
```

Returns the formatted calendar for a day.

### Arguments

* `date` is the `t:Date.t/0` of the day being formatted.

* `year` is the year for which the calendar is requested.

* `month` is the month for which the calendar is requested.

* `options` is a keyword list of formatter options.

### Returns

* An arbitrary result as required by the implementing formatter,
  which is passed to `format_week/5`.

# `format_month`

```elixir
@callback format_month(
  formatted_weeks :: String.t(),
  year :: Calendar.year(),
  month :: Calendar.month(),
  options :: map()
) :: any()
```

Returns the formatted calendar for a month.

### Arguments

* `formatted_weeks` is the result returned by `format_week/5`.

* `year` is the year for which the calendar is requested.

* `month` is the month for which the calendar is requested.

* `options` is a keyword list of formatter options.

### Returns

* An arbitrary result as required by the implementing formatter,
  which is either returned (if called by `Calendrical.Format.month/3`)
  or passed to `format_year/3` if not.

# `format_week`

```elixir
@callback format_week(
  formatted_days :: String.t(),
  year :: Calendar.year(),
  month :: Calendar.month(),
  week_number :: {Calendar.year(), pos_integer()},
  options :: map()
) :: any()
```

Returns the formatted calendar for a week.

### Arguments

* `formatted_days` is the result returned by `format_day/4`.

* `year` is the year for which the calendar is requested.

* `month` is the month for which the calendar is requested.

* `week_number` is a 2-tuple of the form `{year, week_number}`
  that represents the week-of-year for the week to be formatted.

* `options` is a keyword list of formatter options.

### Returns

* An arbitrary result as required by the implementing formatter,
  which is passed to `format_month/4`.

# `format_year`

```elixir
@callback format_year(
  formatted_months :: String.t(),
  year :: Calendar.year(),
  options :: map()
) :: any()
```

Returns the formatted calendar for a year.

### Arguments

* `formatted_months` is the result returned by `format_month/4`.

* `year` is the year for which the calendar is requested.

* `options` is a keyword list of formatter options.

### Returns

* An arbitrary result as required by the implementing formatter.

---

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