# `Expresso`
[🔗](https://github.com/rellen/expresso/blob/main/lib/expresso.ex#L1)

Expresso makes one HTML document from a deck

A deck comes from one of two input paths. A module declares a deck with the
DSL of this module, or a script makes an `Expresso.Deck` struct with the
functions of `Expresso.Builder`. The two paths run the same transformers and
verifiers. `to_deck/1` accepts the value of either path.

`main/2` is the entry point of the command `mix expresso <input> [output]` and
of the binary that Burrito makes. It reads the input script, it makes the HTML,
and it writes the HTML to the output path or to the standard output.

`docs/architecture.md` gives the render pipeline, the templates and the
elements.

### Options

* `:extensions` (list of module that adopts `Spark.Dsl.Extension`) - A list of DSL extensions to add to the `Spark.Dsl`

* `:otp_app` (`t:atom/0`) - The otp_app to use for any application configurable options

* `:fragments` (list of `t:module/0`) - Fragments to include in the `Spark.Dsl`. See the fragments guide for more.

# `from_dsl_state`

```elixir
@spec from_dsl_state(map()) :: Expresso.Deck.t()
```

Make a deck from the state of the DSL

The state comes from a module that uses the DSL, or from
`Expresso.Builder.deck/2`. The transformers of the DSL already ran on it.

# `load_file`

```elixir
@spec load_file(Path.t()) :: {:ok, Expresso.Deck.t()} | {:error, String.t()}
```

Read an input file, and return its deck

The function returns `{:ok, deck}`, or `{:error, message}` for a file that it
cannot find, or for a script that does not return a deck. With `-` as the
path, the function reads the script from the standard input. An exception,
an exit or a throw of the script also returns an error tuple.
`Expresso.Check` reads the deck with this function.

# `load_templates`

```elixir
@spec load_templates() :: :ok
```

Load all the custom deck and slide templates

# `main`

```elixir
@spec main(Path.t() | nil, Path.t() | nil) :: :ok | {:error, String.t() | :closed}
```

Make an HTML document from an input script

The function writes the HTML to `output_path`. With `nil` or `-` as the output
path, the function writes the HTML to the standard output. With `-` as the
input path, the function reads the script from the standard input.

With `nil` as the input path, the function writes the usage text to the
standard error and returns an error tuple. The commands do not give `nil`:
`Expresso.CommandLine` writes the usage text for a command with no argument.

For each other error, the function writes the message to the standard error
and returns an error tuple. The standard output then holds no text. A failed
write of the output file is an error too.

When the standard output closes before the function writes all the HTML, as
for `| head`, the function returns `{:error, :closed}` and writes no message.

# `parse`

```elixir
@spec parse(module()) :: Expresso.Deck.t()
```

Make a deck from a module that uses the DSL

# `render_file`

```elixir
@spec render_file(Path.t()) :: {:ok, String.t()} | {:error, String.t()}
```

Make the HTML document of an input file, and give it

The function gives `{:ok, html}`, or `{:error, message}` for a file that it
cannot find or render. An exception, an exit or a throw of the script also
gives an error tuple, so the function does not raise. The function writes
nothing. `Expresso.Watch` renders the deck with this function after each
change.

# `to_deck`

```elixir
@spec to_deck(term()) :: {:ok, Expresso.Deck.t()} | {:error, String.t()}
```

Make a deck from the value of an input script

An input script returns one of three values. It returns a deck, or a module that
uses the DSL, or the tuple of a `defmodule` expression.

---

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