<commit_before>% Filters

In Ginger, filters and functions are the same thing, the difference is in the
syntax: `{{ var|filter(arg) }}` is exactly the same thing as `{{ filter(var,
arg) }}`. We provide both for two reasons: one, Jinja2 and Twig *do* make a
difference, and we want to support both use cases; and two, sometimes one is
more readable, sometimes the other.

# List Of Builtin Filters / Functions

Note: all functions are given in function-call syntax; filter syntax is valid
for every one of them as well, just remove the first argument.

## `raw(value)`

Forces Ginger to interpret `value` as pre-encoded HTML source.

## `abs(value)`

The absolute value of a number.

## `any(items)`

Test if any of the `items` is true-ish.

## `all(items)`

Test if all of the `items` is falsy.

## `capitalize(str)`

Upper-cases the first code point in `str`.

## `ceil(number)`

Rounds a `number` to the next larger integer.

## `center(str, width=80, pad=' ')`

Aligns a string `str` to fit in `width` characters. If `str` is shorter than
`width`, it gets truncated; if it is longer, `pad` characters are added on both
sides to make it fit.

## `concat(arg0, arg1, ...)`

Concatenates all arguments into one.

## `contains(list, elem)`

Checks whether `list` contains `elem`.

## `dateformat(date, format, tz=null, locale=null)`

*Alias:* `date`

Converts `datetime` to a proper date/time value, and then formats it according
to the given `format`.

- `date` can be one of:
  - a string containing a preformatted date or date+time, in one of the
    following formats:
    - `%Y-%m-%dT%H:%M:%S%Z`
    - `%Y-%m-%d %H:%M:%S`
    - `%Y-%m-%d %H:%M:%S%z`
    - `%Y-%m-%d %H:%M:%S%Z`
    - `%Y-%m-%d`
  - A list of date parts, in the ordering:
    `[ year, month, day, hour, minute, second, timezone ]`; partial lists are
    allowed, leaving out the timezone or the timezone and the time-of-day part.
- `format` supports UNIX-style date/time format strings, as per [this
specification](http://hackage.haskell.org/package/time-1.6.0.1/docs/Data-Time-Format.html#formatTime).
- `tz` can be either a dictionary containing the keys `minutes`,
  `summerOnly`, and `name`, to explicitly define a timezone, or a string
  containing anything the `"%z"` format string understands.
- `locale` is the name of a locale; in order to resolve it, the `getlocale`
  function is called. `getlocale` does not come with Ginger, you have to
  define it yourself and add it to the Ginger execution context. This is
  because we want to keep Ginger agnostic of the chosen host monad, and any
  method of using the OS's locale system would involve `IO` somehow. If
  `getlocale` is not defined, `date` uses a "default locale" (roughly
  equivalent to the "C locale").


## `default(value, def)`

*Alias:* `d`

Return `value` if it is truthy, otherwise return `def`.

## `dictsort(dict, case_sensitive=false, by="key")`

Sort a dictionary-like object by keys (the default) or values (`by="val"`),
keeping key-value relationships intact.

## `difference(arg0, arg1, ...)`

A variadic subtraction function. `difference(a, b, c, d)` is equivalent to `a -
b - c - d`.

## `equals(arg0, arg1, ...)`

A variadic equality comparison function. Returns true iff all arguments are
equal to one another. Uses loose equality.

## `escape()`

*Alias:* `e`

Explicitly HTML-encode `arg`.

## `filesizeformat(size_bytes, base2=false)`

Format a file size (given in number of bytes) to a human-readable string. If
`base2` is truthy, use 2-based units (GiB, MiB, kiB), otherwise use 10-based
units (GB, MB, kB). Works up to petabytes (both PiB and PB).

## `filter(list, predicate)`

Filters a `list`, retaining only those elements for which `predicate` returns
`true`.

## `floor(num)`

Returns the largest integer smaller than or equal to `num`.

## `format(fmt, arg0, arg1, ...)`<commit_msg>Documented `eval`<commit_after>% Filters

In Ginger, filters and functions are the same thing, the difference is in the
syntax: `{{ var|filter(arg) }}` is exactly the same thing as `{{ filter(var,
arg) }}`. We provide both for two reasons: one, Jinja2 and Twig *do* make a
difference, and we want to support both use cases; and two, sometimes one is
more readable, sometimes the other.

# List Of Builtin Filters / Functions

Note: all functions are given in function-call syntax; filter syntax is valid
for every one of them as well, just remove the first argument.

## `raw(value)`

Forces Ginger to interpret `value` as pre-encoded HTML source.

## `abs(value)`

The absolute value of a number.

## `any(items)`

Test if any of the `items` is true-ish.

## `all(items)`

Test if all of the `items` is falsy.

## `capitalize(str)`

Upper-cases the first code point in `str`.

## `ceil(number)`

Rounds a `number` to the next larger integer.

## `center(str, width=80, pad=' ')`

Aligns a string `str` to fit in `width` characters. If `str` is shorter than
`width`, it gets truncated; if it is longer, `pad` characters are added on both
sides to make it fit.

## `concat(arg0, arg1, ...)`

Concatenates all arguments into one.

## `contains(list, elem)`

Checks whether `list` contains `elem`.

## `dateformat(date, format, tz=null, locale=null)`

*Alias:* `date`

Converts `datetime` to a proper date/time value, and then formats it according
to the given `format`.

- `date` can be one of:
  - a string containing a preformatted date or date+time, in one of the
    following formats:
    - `%Y-%m-%dT%H:%M:%S%Z`
    - `%Y-%m-%d %H:%M:%S`
    - `%Y-%m-%d %H:%M:%S%z`
    - `%Y-%m-%d %H:%M:%S%Z`
    - `%Y-%m-%d`
  - A list of date parts, in the ordering:
    `[ year, month, day, hour, minute, second, timezone ]`; partial lists are
    allowed, leaving out the timezone or the timezone and the time-of-day part.
- `format` supports UNIX-style date/time format strings, as per [this
specification](http://hackage.haskell.org/package/time-1.6.0.1/docs/Data-Time-Format.html#formatTime).
- `tz` can be either a dictionary containing the keys `minutes`,
  `summerOnly`, and `name`, to explicitly define a timezone, or a string
  containing anything the `"%z"` format string understands.
- `locale` is the name of a locale; in order to resolve it, the `getlocale`
  function is called. `getlocale` does not come with Ginger, you have to
  define it yourself and add it to the Ginger execution context. This is
  because we want to keep Ginger agnostic of the chosen host monad, and any
  method of using the OS's locale system would involve `IO` somehow. If
  `getlocale` is not defined, `date` uses a "default locale" (roughly
  equivalent to the "C locale").


## `default(value, def)`

*Alias:* `d`

Return `value` if it is truthy, otherwise return `def`.

## `dictsort(dict, case_sensitive=false, by="key")`

Sort a dictionary-like object by keys (the default) or values (`by="val"`),
keeping key-value relationships intact.

## `difference(arg0, arg1, ...)`

A variadic subtraction function. `difference(a, b, c, d)` is equivalent to `a -
b - c - d`.

## `equals(arg0, arg1, ...)`

A variadic equality comparison function. Returns true iff all arguments are
equal to one another. Uses loose equality.

## `escape()`

*Alias:* `e`

Explicitly HTML-encode `arg`.

## `eval(src, context)`

Evaluate Ginger source code `src` in given `context`, returning the
captured output of the evaluation.

Evaluation runs in a "clean" environment, that is, none of the functions or
variables defined in the current run state are available; `eval` only sees the
standard functions (everything on this page), plus the variables defined
through the `context` parameter.

Because of this "sandboxing", Ginger's `eval` is considerably safer than
comparable functions in, say, JavaScript or PHP.

## `filesizeformat(size_bytes, base2=false)`

Format a file size (given in number of bytes) to a human-readable string. If
`base2` is truthy, use 2-based units (GiB, MiB, kiB), otherwise use 10-based
units (GB, MB, kB). Works up to petabytes (both PiB and PB).

## `filter(list, predicate)`

Filters a `list`, retaining only those elements for which `predicate` returns
`true`.

## `floor(num)`

Returns the largest integer smaller than or equal to `num`.

## `format(fmt, arg0, arg1, ...)`
{'fraction_non_alphanumeric': 0.12588178058866456, 'fraction_numerical': 0.004864996351252737, 'mean_word_length': 4.057195571955719, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1332017', 'n_tokens_mistral': 2688, 'n_tokens_neox': 2617, 'n_words': 1131}