Advent Of Code

This is a small collection of command line tools to help with Advent of Code by managing inputs, tests and boilerplate code while you focus on problem solving!

Quickstart Guide

Follow these steps to get started on your first AoC puzzle today!

In a Hurry? Just go to the "TL; DR" section.

Install the library

This framework is distributed as a library as it consists mostly of mix tasks. You may add the dependency to your project, or add it to a new project created with mix new my_app.

defp deps do
  [
    {:aoc, "~> 0.16"},
  ]
end

Then call mix deps.get before following the rest of this guide.

Configuration

If it does not exist, create a configuration file in your application:

mkdir -p config
touch config/config.exs

Then add the configuration for the module prefix. This is the namespace of all solution modules generated by aoc. It must start with your app name.

# config/config.exs

import Config

config :aoc,
  # The prefix is used when creating solutions and test modules with
  # `mix aoc.create`.
  prefix: MyApp.Solutions,

  # Optional

  # Include help comments when generating modules and tests.
  generate_comments: true

Tip: The configuration can be defined in config/runtime.exs instead.

In order to run the aoc.test command described later in this document, you need to declare that command as a test environment command.

In yourmix.exs file, declare the following function:

# mix.exs
def cli do
  [
    preferred_envs: ["aoc.test": :test]
  ]
end

Install your cookie

The cookie is used to authenticate with the AoC website. This library will only use it to fetch your inputs and save them locally.

First, retrieve your cookie from the AoC website (with you browser developer tools) and write its content to a file in your home directory.

Unix based systems

The file will be read from $HOME/.adventofcode.session, for instance /home/Alice/.adventofcode.session.

Windows

The file will be read from %USERPROFILE%\.adventofcode.session, for instance C:\Users\Alice\.adventofcode.session.

Are you trying this library before December 1st ?

The aoc commands use dynamic default values: they will always default to the current year and day, as they are intended to be used during the event.

If you want to try this library right now and be ready for day one, why not try a simple puzzle from a previous year?

Just chose a year and a day, for instance 2023 Dec. 1st, and set that as your new default values:

mix aoc.set --year 2023 --day 1

# short version
mix aoc.set -y 2023 -d

This is also useful if you need to focus on a puzzle for more than one year.

Remember to call mix aoc.set --reset when you want to use the dynamic default values.

Let's write some code!

Note that this guide uses 2023 day 1 for its examples.

Also ... this tools gives a strong importance to testing and TDD practice. If you are playing the race game, it may not be worth it, but you can still use all the file generation part.

Alright, now that you are set up, you can automatically download the input and generate the files to work on your solution.

Generate the files

Call mix aoc.create to do just that.

The generated module will look like that:

defmodule MyApp.Solutions.Y23.Day01 do
  alias AoC.Input

  def parse(input, _part) do
    Input.read!(input)
  end

  def part_one(problem) do
    problem
  end

  # def part_two(problem) do
  #   problem
  # end
end

Alright, I lied, the module is also full of comments to help you understand what you can do in there. See the configuration section to disable those.

There are three functions in there.

There is also a generated test in your test directory. Inside, you can find the following test:

  test "part one example" do
    input = ~S"""
    This is an
    example input.
    replace with
    an example from
    the AoC website.
    """

    assert CHANGE_ME == solve(input, :part_one)
  end

Finally, give a look at your input downloaded in priv/input/2023/day-01.inp, this may give you a hint about what to do before writing the tests. Or you can just try to solve the example before, your choice!

Solve the example

It's time to read the puzzle if you haven't already. You can call mix aoc.open as a shortcut.

After having carefully read the the puzzle description, copy it's first example and paste it in lieu of the current placeholder. The puzzle also gives the answer for that example: 142. This is what we are going to use for the assertion.

In the end, we should have this:

  test "part one example" do
    input = ~S"""
    1abc2
    pqr3stu8vwx
    a1b2c3d4e5f
    treb7uchet
    """

    assert 142 == solve(input, :part_one)
  end

You may then use mix aoc.test to test your implementation with that example.

Or you can just call mix test or mix test test/2023/day_01.exs. After all, this test is nothing special to the aoc library, you can do whatever you want in there:

Solve the puzzle

Finally, once your tests seem correct, you can use mix aoc.run to run your solution with the actual input. It will print something like that:

Solution for 2023 day 1
part_one: 1014171 in 17.16ms

And it's time to submit your first answer to the AoC website. Hopefully, it will be right!

When you have the right solution, just uncomment the test "part two example" block in your test, and the part_two/1 function in your solution module, and you're ready for part two.

Happy coding :)

Call your solution module manually

If you want to call your module directly from custom tests or from a runner of your own, just pass the path of your input and :part_one | :part_two to the parse/2 function, and pipe that to the part_one/1 or part_two/1 function:

solution_for_p1 =
  "path/to/input/file"
  |> MyApp.Y23.Day1.parse(:part_one)
  |> MyApp.Y23.Day1.part_one()

TL; DR

  1. Installation: Add the dependency and fetch it. 

    # mix.exs
defp deps do
  [
    {:aoc, "~> 0.11"},
  ]
end

def cli do
  [
    preferred_envs: ["aoc.test": :test]
  ]
end

# Run in terminal
mix deps.get

  2. Configuration: Set up your configuration and environment. 

    # config/config.exs
import Config
config :aoc, prefix: MyApp.Solutions

  3. Authentication: Save your AoC session cookie value in $HOME/.adventofcode.session.

  4. Before the event: Set default values for previous days. 

    # Force defaults to 2023 day 1
mix aoc.set -y 2023 -d 1
# Reset on December 1st
mix aoc.set --reset

  5. Generate the files: 

    # Generate solution files
mix aoc.create

  6. Import the example: 

    # Copy input and expected result from the example in
# the generated test.
test "part one example" do
  input = ~S"""
  1abc2
  pqr3stu8vwx
  a1b2c3d4e5f
  treb7uchet
  """

  assert 142 == solve(input, :part_one)
end

  7. Implementparse/2 and part_one/1 in your module. Use the tests to verify with the example: 

    # Run tests
mix aoc.test
# Or
mix test

  8. Run your solution: 

    # Run the solution
mix aoc.run

  9. Manual Execution: Directly call solution functions if needed. 

    # Manual call
solution_for_p1 =
  "path/to/input/file"
  |> MyApp.Solutions.Y23.Day1.parse(:part_one)
  |> MyApp.Solutions.Y23.Day1.part_one()

Available Commands

The following commands will use default year and day based on the current date.

It is possible to override the defaults with the mix aoc.set command, or provide the --year and --day options to any of them.

The following docs are generated from the tasks modules documentation. You can get any of them using mix help <command>, for instance mix help aoc.create.

You may also get a quick summary of options by calling those commands with the --help flag, as in mix aoc.create --help.

mix aoc.open

Opens the puzzle page with your defined browser on on adventofcode.com.

The command to call with the URL will be defined in the following order:

Usage

mix aoc.open [options]

Options

mix aoc.create

This task will execute the following operations:

Existing files will not be overwritten. It is safe to call the command again if you need to regenerate a deleted file.

The generated files will contain some comment blocks to help you get accustomed to using this library. This can be annoying after some time. You may disable generating those comments by setting the appropriate configuration option:

config :aoc, generate_comments: false

Usage

mix aoc.create [options]

Options

mix aoc.test

Runs your test file for the Advent of Code puzzle.

Note that test files generated by the mix aoc.create command are regular ExUnit tests.

You can always run mix test or a test specified by a file and an optional line number like this:

mix test test/2023/day01_test.exs:123

In order to use this command, you should define it as a test environment command in your mix.exs file by defining a cli/0 function:

def cli do
  [
    preferred_envs: ["aoc.test": :test]
  ]
end

Usage

mix aoc.test [options]

Options

mix aoc.run

Runs your solution with the corresponding year/day input from priv/inputs.

Usage

mix aoc.run [options]

Options

mix aoc.fetch

This task will fetch the puzzle into priv/inputs.

It will not overwrite an existing input file.

Usage

mix aoc.fetch [options]

Options

mix aoc.url

Outputs the on adventofcode.com URL for a puzzle.

Useful to use in custom shell commands.

Note that due to Elixir compilation outputs you may need to grep for the URL. For instance:

xdg-open $(mix aoc.url | grep 'https')

Usage

mix aoc.url [options]

Options

Custom default values for commands

The mix aoc.set command allows to set the default year and day. Those values are used by default when other commands are not called with --year or --day options.

This is useful when working on a problem from a previous year, or when you finish the last days after December 25th, so your CLI history or bash scripts can just call mix aoc.test or mix aoc.run without options.

Upgrading to 0.12

If you have been using this library in the past, there have been quite some changes in the way the generated files are located.

You will need to rename your modules for days 1 to 9 with a leading 0, for instance day 1:

find lib  -type f -exec sed -i -e 's/.Day1\b/.Day01\b/' {} \;
find test -type f -exec sed -i -e 's/.Day1\b/.Day01\b/' {} \;
find test -type f -exec sed -i 's/.Day1Test/.Day01Test/' {} \;

Do this for all 9 days, then call mix deps.get and mix mod.relocate -i to move your old modules.

Sorry for the inconvenience. That change was necessary to have a clean ordering of files in the solutions directories and to allow everyone to generate the modules in a directory according to their preferred namespace.