advent_of_utils/
lib.rs

1/*!
2# Introduction
3`Advent of Utils` helps you solving your [Advent of Code](https://adventofcode.com/) challenges. Not by implementing the solutions for you, but by handling the boilerplate work so you can focus on solving the puzzles.
4
5# Table of Contents
6- [Features](#features)
7- [Setup](#setup)
8- [Usage](#usage)
9- [CLI Reference](#cli-reference)
10- [Disclaimer](#disclaimer)
11
12# Features
13- 🚀 Automatic input fetching with local caching
14- 📊 Built-in performance benchmarking
15- 🔧 Simple macro-based setup
16- 💾 Session token management
17
18# Setup
19
20## Prerequisites
211. An Advent of Code account and session token
222. Rust toolchain installed
23
24## Installation
25Add this to your `Cargo.toml`:
26```toml
27[dependencies]
28advent-of-utils = "0.2.0"
29
30[lib]
31crate-type = ["cdylib"]
32```
33
34Install the CLI using:
35```bash
36cargo install advent-of-utils-cli
37```
38
39## Environment Setup
40
41Set your Advent of Code session token:
42
43```bash
44# Linux/MacOS
45export AOC_SESSION=your_session_token
46
47# Windows (PowerShell)
48$env:AOC_SESSION="your_session_token"
49```
50
51You will find your session token in the cookies on the [Advent of Code](https://adventofcode.com/) page when you are logged in.
52
53# Usage
54
55## 1. Create Your Solution Structure
56
57First, create a new Rust project for your solutions:
58
59```bash
60cargo new aoc-2023
61cd aoc-2023
62```
63
64## 2. Set Up Your Project
65
66In your project's `lib.rs`, use the `add_days!` macro to generate the boilerplate for your solutions:
67
68```rust
69use advent_of_utils::add_days;
70
71// Generate modules for days 1 through 25
72add_days!(1..=25);
73```
74
75## 3. Implement Solutions
76
77For each day you want to solve, implement the `Solution` trait in the corresponding module. You need to create a file for all the days you added yet to your macro or the compiler will complain. Here's an example for day 1:
78
79```rust
80// src/day01.rs
81
82use advent_of_utils::{Solution, AocOption};
83
84pub struct Day01;
85
86impl Solution for Day01 {
87    fn part1(&self, input: String) -> AocOption {
88        // Your solution for part 1
89        1.into()
90    }
91
92    fn part2(&self, input: String) -> AocOption {
93        // Your solution for part 2
94        "part2 result".into()
95    }
96}
97```
98
99## 4. Run Solutions
100
101Once your solutions are implemented and your code compiles you can run the your code through the `aou` CLI:
102
103# CLI Reference
104
105## Basic Commands
106
107```bash
108# Run a specific day's solution
109aou run <YEAR> <DAY>
110
111# Run all implemented solutions
112aou run <YEAR>
113```
114
115For more informations on your options for the CLI run:
116
117```bash
118aou --help
119```
120*/
121#![warn(missing_docs)]
122mod options;
123mod solution;
124
125/// A procedural macro that generates boilerplate code for Advent of Code solution modules.
126///
127/// This macro takes a comma-separated list of day numbers and generates:
128/// - Individual modules for each day which have to be populated with your solutions
129///
130/// # Arguments
131///
132/// * Takes a comma-separated list of expressions representing the day numbers (e.g., `add_days!(1..10, 12, 13)`)
133///
134/// # Generated Code
135///
136/// For each day number, the macro:
137/// 1. Creates a module declaration (`mod dayXX`)
138/// 3. Generates a HashMap mapping day numbers to solution implementations which is accessed by the
139///    CLI
140///
141/// # Example
142///
143/// ```rust
144/// add_days!(1, 2, 15);
145/// ```
146///
147/// This will generate:
148/// - Modules: `mod day01;`, `mod day02;`, `mod day15;`
149/// - Solution mapping in a HashMap
150pub use advent_of_utils_macros::add_days;
151pub use options::AocOption;
152pub use solution::Solution;
advent_of_utils/lib.rs

advent_of_utils/
lib.rs
