# `Localize.DateTime.Format.AppendItems`
[🔗](https://github.com/elixir-localize/localize/blob/v1.4.0/lib/localize/datetime/format/append_items.ex#L1)

TR35's append-item path for flexible date-time patterns.

A locale ships a finite set of available formats, so a skeleton may ask
for a field combination CLDR does not carry. TR35 resolves this by
matching the closest format that *is* available and then appending each
requested field the match omits, using the locale's `appendItems`
templates. English asking for `:yMMMdQ` matches `yMMMd` and appends the
quarter as "Jul 6, 2024 (quarter: Q3)".

Each template is a substitution list where `0` is the matched pattern,
`1` is the missing field's own pattern, and `2` is the field's localized
display name. Fields are appended one at a time, each round's output
becoming the next round's `{0}`.

# `augment`

```elixir
@spec augment(atom() | String.t(), Localize.locale(), atom(), Keyword.t()) ::
  {:ok, String.t()} | :error | {:error, Exception.t()}
```

Resolves a skeleton no available format covers by augmenting the closest
subset match with append-item templates.

### Arguments

* `skeleton` is the requested skeleton, an atom or a string.

* `locale_id` is a resolved locale identifier.

* `calendar_type` is a CLDR calendar name.

* `options` are the formatting options, used to resolve pattern variants.

### Returns

* `{:ok, pattern}` where `pattern` is the augmented pattern string. When
  no format carries any requested field, the pattern starts from the first
  field in CLDR's canonical order, as CLDR's reference pattern generator
  does.

* `:error` when a field the pattern would have to append is not one TR35
  names as an append item.

* `{:error, exception}` if the locale's data cannot be read.

### Examples

`en` has no format with a quarter, so the closest match takes the
locale's append item for it:

    iex> Localize.DateTime.Format.AppendItems.augment(:yMMMdQ, :en, :gregorian)
    {:ok, "MMM d, y ('quarter': Q)"}

# `resolve_pattern`

```elixir
@spec resolve_pattern(atom() | String.t(), Localize.locale(), atom(), Keyword.t()) ::
  {:ok, String.t()} | :error | {:error, Exception.t()}
```

Resolves a skeleton to a pattern, using the append-item path when no
available format carries every requested field.

This is the whole resolution chain in one call: an exact available
format, else the closest match with its field widths adjusted to the
request, in the calendar's own formats and then in the Gregorian
calendar's, which TR35 has most calendars inherit; else a subset match
from either, augmented with append items.

### Arguments

* `skeleton` is the requested skeleton, an atom or a string.

* `locale_id` is a resolved locale identifier.

* `calendar_type` is a CLDR calendar name.

* `options` are the formatting options, used to resolve pattern variants.

### Returns

* `{:ok, pattern}`.

* `:error` when the skeleton cannot be resolved at all.

* `{:error, exception}` if the locale's data cannot be read.

### Examples

    iex> Localize.DateTime.Format.AppendItems.resolve_pattern(:yMMMd, :en, :gregorian)
    {:ok, "MMM d, y"}

    iex> Localize.DateTime.Format.AppendItems.resolve_pattern(:yMMMdQ, :en, :gregorian)
    {:ok, "MMM d, y ('quarter': Q)"}

---

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