Gladvent
An Advent Of Code runner for Gleam
This library is intended to be imported to your gleam project and used as a command runner for your advent of code project in gleam.
To add this library to your project run: gleam add gladvent
and add import gladvent
to your main gleam file.
Using the library
This library provides 2 options to run your advent of code solvers,
once you’ve added gladvent as a dependency via gleam add gladvent
:
- The easiest way: call it via
gleam run -m gladvent [ARGS]
, not requiring a custommain()
function. - The easy way: simply add
gladvent.main()
to the end of your project’smain
function.
Multi-year support
Gladvent now comes with out-of-the-box multi-year support via the --year
flag when running it.
For convenience it defaults to the current year. Therefore, passing --year=YEAR
to either the run
, run all
or new
commands will use the year specified or the current year if the flag was not provided.
Available commands
This project provides your application with 2 commands, new
and run
:
-
new
: createsrc/days/*.gleam
andinput/*.txt
files that correspond to the specified days- format:
gleam run -m gladvent new a b c ...
- used like
gleam run -m gladvent new 1 2
with days 1 and 2 createsinput/day_1.txt
andinput/day_2.txt
as well assrc/days/day_1.gleam
andsrc/days/day_2.gleam
- format:
-
run
: run the specified days- format:
gleam run -m gladvent run a b c ...
- flags:
--timeout
:gleam run -m gladvent run --timeout={timeout in ms} a b c ...
- usage example:
gleam run run --timeout=1000 1 2
with timeout 1000 milliseconds and days 1 and 2, runs and prints the output of running therun
function ofday_1.gleam
andday_2.gleam
- usage example:
--allow-crash
: runs days without the use ofrescue
functionality, rendering output text more verbose but also allowing for stacktraces to be printed- usage example:
gleam run -m gladvent run 1 2 3 --allow-crash
- usage example:
- format:
-
run all
: run all registered days- format:
gleam run -m gladvent run all
- flags:
--timeout
:gleam run -m gladvent run all --timeout={timeout in ms}
- usage example:
gleam run run --timeout=1000 1 2
with timeout 1000 milliseconds and days 1 and 2, runs and prints the output of running therun
function ofday_1.gleam
andday_2.gleam
- usage example:
--allow-crash
: runs days without the use ofrescue
functionality, rendering output text more verbose but also allowing for stacktraces to be printed- usage example:
gleam run -m gladvent run all --allow-crash
- usage example:
- format:
Note:
- the
new
command creates source files insrc/aoc_<YEAR>/
and input files in theinput/<YEAR>
directory. - the
run
command expects input files to be in theinput/<YEAR>
directory, and code to be insrc/aoc_<YEAR>/
- any triggered
assert
will be captured and printed, for example:error: assert - Assertion pattern match failed in module days/day_1 in function pt_1 at line 2 with value 2
- any message in a
todo
will be captured and printed, for example:error: todo - test in module days/day_1 in function pt_2 at line 7
Seeing help messages
- To see available subcommands:
gleam run -m gladvent -- --help
- To see help for the
run
command:gleam run -m gladvent run --help
- To see help for the
run
command:gleam run -m gladvent run all --help
- To see help for the
new
command:gleam run -m gladvent new --help
General Workflow
Where X is the day you’d like to add (when using gladvent.main()
):
Note: this method requires all day solutions be in src/days/
with filenames day_X.gleam
, each solution module containing fn pt_1(String) -> Int
and a fn pt_2(String) -> Int
- run
gleam run -m gladvent run new X
- add your input to
input/<YEAR>/day_X.txt
- add your code to
src/aoc_<YEAR>/day_X.gleam
- run
gleam run -m gladvent run X
Reusable parse funtions
As of v0.7.0
gladvent supports modules with functions that provide a pub fn parse(String)->a
where the type a
matches with the type of the argument for the runner functions pt_1
and pt_2
. If this function is present, gladvent will pick it up and run it only once, providing the output to both runner functions.
An example of which looks like this:
pub fn parse(input: String) -> Int {
let assert Ok(i) = int.parse(input)
i
}
pub fn pt_1(input: Int) -> Int {
i + 1
}
pub fn pt_2(input: Int) -> Int {
i + 2
}
Note: gladvent
now leverages gleam’s export package-interface
functionality to type-check your parse
and pt_{1|2}
functions to make sure that they are compatible with each other.
FAQ
Why did you make this?
It seemed fun, I like small command line utilities and I wanted a way to get advent of code done in gleam without having the additional overhead of lots of copy-pasting and connecting things to get it to run
Why does this not download the input from the advent of code website?
A few reasons:
- I wanted to keep this utility as simple as possible to start with
- I like the advent of code website and I felt like it was a shame to circumvent visiting it, especially since you should access it to read the daily challenge. On top of that, I would like to avoid spamming the
advent of code
api if possible.
Why run as a command line utility and not just use unit tests?
I thought a lot about that and I prefer the overall interactivity of a CLI better, as well as allowing for endless runs or runs with configurable timeouts. Having it run as part of eunit
doesnt provide as much flexibility as I would like.