View Source 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

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

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

  def another_function do
    # arbitrary code goes here

  # any code that is valid in an
  # elixir module is valid here

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

Get module (to test helpers)

Get puzzle / example data

Mix tasks

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

Fetch input / example

Generate code skeleton

Fetch + Generate

Specifying time and date

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.


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.


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

This generates an elixir module named Y<year>.D<day>.AOCTest which uses 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/0
  • input_path/0
  • example_path/0

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


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())
      # solution to part 1 here
  def p1(input), do: ...

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

Configuration & Setup

We recommend going through the full Setup & Use section of the readme.

Available configuration options

OptionUsed byDefault
dayAOC.IEx mix aoc.get mix aoc.genCurrent day of month
yearAOC.IEx mix aoc.get mix aoc.genCurrent year
time_zoneAOC.IEx mix aoc.get mix aoc.gen:local
sessionmix aoc.get
gen_tests?mix aoc.genfalse
gen_doctests?mix aoc.genvalue of gen_tests?
code_pathmix aoc.gen"lib/:year/:day.ex"
test_pathmix aoc.gen"test/:year/:day_test.exs"
input_pathAOC.IEx mix aoc.get"input/:year_:day.txt"
example_pathAOC.IEx mix aoc.get"input/:year_:day_example.txt"
  • Add import AOC.IEx to 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.