cheatsheet.cheatmd

# Cheatsheet

This document provides an at-a-glance overview on how to use "Advent of Code
Utils". In-depth information on each topic can be found in the relevant docs.

## The Basics
{: .col-3}

### Solution modules

A solution for a day is written in a _solution module_. These modules are
written using the `AOC.aoc/3` macro.

```
import AOC

aoc <year>, <day> do
  def p1(input) do
    # part 1 solution goes here
  end

  def p2(input) do
    # part 2 solution goes here
  end

  def another_function do
    # arbitrary code goes here
  end

  # any code that is valid in an
  # elixir module is valid here
end
```
This generates a standard elixir module named `Y<year>.D<day>`.

### iex interaction

Inside iex, you can use the functions described in `AOC.IEx` to test your
solution:

#### Test solutions
- `AOC.IEx.p1e/1`
- `AOC.IEx.p1i/1`
- `AOC.IEx.p2e/1`
- `AOC.IEx.p2i/1`
- `AOC.IEx.p1/2`
- `AOC.IEx.p2/2`

#### Get module (to test helpers)
- `AOC.IEx.mod/1`

#### Get puzzle / example data
- `AOC.IEx.input_path/1`
- `AOC.IEx.example_path/1`
- `AOC.IEx.input_string/1`
- `AOC.IEx.example_string/1`
- `AOC.IEx.list_examples/1`
### Mix tasks

mix is used to fetch the input for a puzzle and to create boilerplate code.

#### Fetch input / example
* `mix aoc.get`

#### Generate code skeleton
* `mix aoc.gen`

#### Fetch + Generate
* `mix aoc`

## Handling Examples
{: .col-2}

When using `mix aoc.get` (or `mix aoc`), Advent of Code utils fetches all the
code blocks on the puzzle page and stores them as examples.

- Any code block on the puzzle page is treated as an example, so some false
  positives may be present.
- Running `mix aoc.get` after solving part 1 will fetch any new examples from
  the puzzle page if your session cookie is set.
- Example fetching can be disabled by passing `--no-example` to `mix aoc` or
  `mix aoc.get`, or by setting `fetch_example?` to false.

### Interacting with examples in iex

```
iex> p1e()
# Runs p1 of the current day with the first example input.
iex> p1e(n: 0)
# Same as above, examples are numbered starting from 0
iex> p1e(n: 3)
# Run p1 of the current day on the 4th example found.
iex> p2e(n: 3)
# Run p2 of the current day on the 4th example found.
iex> list_examples()
# Show all available examples
```


## Specifying time and date
{: .col-2}

### In iex

```
iex> p1i()
# Runs p1 of the current day
# with the input string of that day
iex> p1i(day: 8)
# Runs p1 of day 8 of the current
# year with the input string of that day
iex> p1i(day: 8, year: 1991)
# Runs p1 of day 8 of 1991
# with the input string of that day
iex> p1i(year: 1991)
# Uses the current day of the month,
# but in 1991
iex> p1("some input", day: 8)
# Runs p1 of day 8 of the current
# year with the provided input string
```
A day can be specified like this for all `AOC.IEx` functions.

### Specifying year or day in `config.exs`

Year or day may also be specified in the `config/config.exs` file:

```
import Config

config :advent_of_code_utils,
  day: 8,
  year: 1991
```

Setting the year is, for instance, useful when going back to finish previous
years.

### When using mix tasks

* `mix aoc --day <day> --year <year>`
  * Generates code + fetches input for the given year and day.
* `mix aoc -d <day> -y <year>`
  * Same as above, but shorter.
* `mix aoc --day <day>`
  * Generates code + fetches input for the current year with the given day.
* `mix aoc --year <year>`
  * Generates code + fetches input for the given year with the current day.

The same options can be passed to `mix aoc.gen` and `mix aoc.get`.

### Precedence

Mix tasks and the `AOC.IEx` helpers use the year and date from the following
sources, using the first that matches.

1. Options passed as argument to a function or as a flag to a mix task.
2. Year or day as specified in the application configuration (i.e. in
   `config/config.exs`).
3. The local year and month of day.

## Tests
{: .col-2}

Advent of Code utils offers optional support for generating and
writing (doc)tests.

### Test modules

`AOC.aoc_test/4` can be used to generate a unit test module for a solution
module.

```
import AOC

aoc_test <year>, <day> do
  # test code goes here
end
```
This generates an elixir module named `Y<year>.D<day>.AOCTest` which `use`s
`AOC.Case`.

This code can be generated by `mix aoc.gen`.

### accessing (puzzle) input

Inside the `aoc_test` module or inside the doctests, you can access the puzzle
input and the example input using the following functions:

- `input_string/0`
- `example_string/1`
- `input_path/0`
- `example_path/1`

`AOC.aoc_test/4` also `import/2`s the solution module, so you can access any
of its functions as well.

### doctests

`AOC.aoc_test/4` automatically calls the doctests of the solution module.
This enables you to write your solution module as follows:
```
aoc <year>, <day> do
  @doc """
      iex> p1(example_string(0))
      # solution to part 1 here
  """
  def p1(input), do: ...
end
```
`mix aoc.gen` can automatically generate doctests skeletons for your solution
module.

### Running the tests

`AOC.aoc_test/4` injects several module tags into the test case, which can be
used to make `mix test` only run the (doc)tests you want. See `AOC.Case` for
more infomation.

#### Run the test of a specific day
* `mix test --only day:<day>`
#### Run the test of a specific day if your repository spans multiple years
* `mix test --only aoc:<year>-<day>`
* `mix test test/<year>/<day>_test.exs`
#### Run all tests of a year
* `mix test --only year:<year>`
#### Run all tests
* `mix test`

## Configuration & Setup

We recommend going through the full [Setup & Use](readme.html#setup-use)
section of the [readme](readme.html).

### Available configuration options

| Option | Used by | Default |
| ------ | ------- | ------- |
| `day` | `AOC.IEx` `mix aoc.get` `mix aoc.gen` | Current day of month |
| `year` | `AOC.IEx` `mix aoc.get` `mix aoc.gen` | Current year |
| `time_zone` | `AOC.IEx` `mix aoc.get` `mix aoc.gen` | `:local` |
| `session` | `mix aoc.get` | |
| `fetch_example?` | `mix aoc.get` | `true` |
| `auto_compile?` | `AOC.IEx` | `false` |
| `time_calls?` | `AOC.IEx` | `false` |
| `gen_tests?` | `mix aoc.gen` | `false` |
| `gen_doctests?` | `mix aoc.gen` | value of `gen_tests?` |
| `code_path` | `mix aoc.gen` | `"lib/:year/:day.ex"` |
| `test_path` | `mix aoc.gen` | `"test/:year/:day_test.exs"` |
| `input_path` | `AOC.IEx` `mix aoc.get` | `"input/:year_:day.txt"` |
| `example_path` | `AOC.IEx` `mix aoc.get` | `"input/:year_:day_example_:n.txt"` |

### Other recommended tweaks

* Add `import AOC.IEx` to
  [the `.iex.exs` file](https://hexdocs.pm/iex/IEx.html#module-the-iex-exs-file).
  This allows you to call `AOC.IEx.p1i/1` and similar in iex without the need
  to prefix it.
* Add `config :iex, inspect: [charlists: :as_lists]` to `config/config.exs`.
  This prevents elixir from displaying lists of integers as strings.