# `Tptp.Printer.Format`
[🔗](https://github.com/jcschuster/tptp/blob/v0.1.3/lib/tptp/printer/format.ex#L1)

Rewrites a file's layout without altering its token sequence.

Backs `mix tptp.format`. The guarantee is stronger than the canonical printer's:
the tokens are unchanged — not the same structure, but the same tokens, in the
same order, with the same spellings. Only the white space between them differs.

    iex> Tptp.Printer.Format.to_string("fof( a,axiom,p&q ).  % why\n")
    "fof(a, axiom, p & q).  % why\n"

## Relation to the canonical printer

`Tptp.Printer.Canonical` reconstructs output from the tree, so anything the
grammar admits in more than one form is emitted in the canonical one. That is
correct for a canonical form and incorrect for a formatter, which must not alter
a file it was asked to lay out. This module therefore operates on the tokens,
which are what the source contained.

## Comment placement

Reattaching comments is ordinarily the difficult part of a format-preserving
printer. Here comments and statements are already ordered by position, so
merging the two sequences and examining the white space preceding each item
determines the placement:

  * no newline before a comment indicates that something preceded it on its
    line, so it is a trailing comment and remains one;
  * one newline places it on its own line;
  * two or more preserve the blank line above it, since paragraphing carries
    information.

This requires a single pass and no position-keyed map.

## Unparseable input

A source containing a lexical error is returned unchanged. A formatter is
invoked precisely when a file is in an inconsistent state, and rewriting one
whose tokens are not trustworthy risks discarding content.

# `item`

```elixir
@type item() :: {non_neg_integer(), non_neg_integer(), :statement | :comment, term()}
```

A statement or a comment, with where it starts and ends.

# `format_file`

```elixir
@spec format_file(Path.t()) :: {:ok, :changed | :unchanged} | {:error, File.posix()}
```

Reformat a file in place, reporting whether it changed.

# `to_iodata`

```elixir
@spec to_iodata(binary()) :: iodata()
```

Reformat TPTP source, as iodata.

# `to_string`

```elixir
@spec to_string(binary()) :: binary()
```

Reformat TPTP source.

---

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