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!
Follow these steps to get started on your first AoC puzzle today!
In a Hurry? Just go to the "TL; DR" section.
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.13"},
]
endThen call mix deps.get before following the rest of this guide.
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: trueTip: 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]
]
endThe cookie is used to authenticate with the AoC website. This library will only use it to fetch your inputs and save them locally.
Retrieve your cookie from the AoC website (with you browser developer tools) and
write the session ID in $HOME/.adventofcode.session. It should be a long hex
number like 53616c7415146f5f1d5792d97e...
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 -dThis 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.
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.
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
endAlright, 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.
- The
parse/2function should be focused on transforming the input text into a data structure of your design. Imagine a good model for your data and the algorithms will be simpler to write. - The
part_one/1function receives the output ofparse/2. It is separated so you can test to call it with made up data, and focus on the problem. Of course, you can just return the input as-is fromparse/2and do everything inpart_one/2. - Uncomment the
part_two/1function when you have done part 1.
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)
endFinally, 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!
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)
endYou 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:
- Add more example tests.
- Customize the
solve/2function to your liking, maybe with somedbg()orIO.inspect/2calls. - Use your own ExUnit case template.
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 :)
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()-
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
-
Configuration: Set up your configuration and environment.
# config/config.exs import Config config :aoc, prefix: MyApp.Solutions
-
Authentication: Save your AoC session cookie value in
$HOME/.adventofcode.session. -
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
-
Generate the files:
# Generate solution files mix aoc.create
-
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
-
Implement
parse/2andpart_one/1in your module. Use the tests to verify with the example:# Run tests mix aoc.test # Or mix test
-
Run your solution:
# Run the solution mix aoc.run -
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()
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.
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:
- Using the
AOC_BROWSERenvironment variable. - Using the
BROWSERenvironment variable. - Fallback to
xdg-open.
mix aoc.open [options]-y, --year <integer>- Year of the puzzle. Defaults to today's year or custom default.-d, --day <integer>- Day of the puzzle. Defaults to today's day or custom default.--help- Displays this help.
This task will execute the following operations:
- Download the input from Advent of Code website into the
priv/inputsdirectory. - Create the solution module.
- Create a test module.
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
mix aoc.create [options]-y, --year <integer>- Year of the puzzle. Defaults to today's year or custom default.-d, --day <integer>- Day of the puzzle. Defaults to today's day or custom default.--help- Displays this help.
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:123In 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]
]
endmix aoc.test [options]-y, --year <integer>- Year of the puzzle. Defaults to today's year or custom default.-d, --day <integer>- Day of the puzzle. Defaults to today's day or custom default.--trace- forward option tomix test.--stale- forward option tomix test.--failed- forward option tomix test.--seed <integer>- forward option tomix test.--max-failures <integer>- forward option tomix test.--help- Displays this help.
Runs your solution with the corresponding year/day input from priv/inputs.
mix aoc.run [options]-y, --year <integer>- Year of the puzzle. Defaults to today's year or custom default.-d, --day <integer>- Day of the puzzle. Defaults to today's day or custom default.-p, --part <integer>- Part of the puzzle. Defaults to both parts.-b, --benchmark- Runs the solution repeatedly for 5 seconds to print statistics about execution time. Defaults tofalse.--help- Displays this help.
This task will fetch the puzzle into priv/inputs.
It will not overwrite an existing input file.
mix aoc.fetch [options]-y, --year <integer>- Year of the puzzle. Defaults to today's year or custom default.-d, --day <integer>- Day of the puzzle. Defaults to today's day or custom default.--help- Displays this help.
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')mix aoc.url [options]-y, --year <integer>- Year of the puzzle. Defaults to today's year or custom default.-d, --day <integer>- Day of the puzzle. Defaults to today's day or custom default.--help- Displays this help.
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.
mix aoc.set --year 2022– Set the default year to 2022.mix aoc.set --day 12– Set the default day.mix aoc.set --year 2022 --day 12– Set both defaults.mix aoc.set --reset --day 12– Set the default day and delete other default values.mix aoc.set --reset– Delete every default values.
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 prefix.