Home

Awesome

ESB - ElfScript Brigade

Script your way to rescue Christmas as part of the ElfScript Brigade team.

This tool transforms Advent of Code into a CLI adventure

<img src="https://raw.githubusercontent.com/luxedo/esb/refs/heads/main/doc/assets/logo/png/logo-color-small.png" alt="ElfScript Brigade Logo"/>

PyPI - Version PyPI - Python Version License: GPL v3 GitHub Actions Workflow Status Codecov CodeFactor Grade

In the bureaucratic workshop of Santa's IT department, where the spirit of Christmas and the magic of coding converge, a special group of coding elves emerged known as the ElfScript Brigade. These skilled and whimsical elves were bestowed with the mission of safeguarding the joyous essence of Christmas through the power of scripting and coding.

esb is a CLI tool to help us elves save Christmas for the yearly Advent of Code events. (Thank you, Eric! 😉)

This tool allows us elves to:

  1. Fetch puzzle statement and puzzle data
  2. Create language agnostic boilerplate code<sup>*Check supported languages</sup>
  3. Test run and submit solutions
  4. Shiny dashboards
  5. Follow the rules of automation

Check out an example repo created using esb!

Table of Contents

Installation

pip install esb

Usage

TLDR;

mkdir my_aoc_repo && cd my_aoc_repo

# Initializes ESB repo
esb init

# Create boilerplate code and fetches input data
esb start --lang rust --year 2023 --day 13

# Code, code, code...

# Run code and submit answer
esb run --lang rust --year 2023 --day 13 --part 1 --submit

# Collect stars!

Initializing the repository

Create a git repository and initialize an esb repository too.

mkdir my_aoc_repo
cd my_aoc_repo
git init
esb init
git commit -m  "I now pledge to help, and I will forever help, saving christmas."

Add your credentials

Set your credentials by locating your session cookie or save it in a .env file. If the cookie expires, you'll have to redo this step for fetching and submitting data.

export AOC_SESSION_COOKIE="<my_current_cookie>"
# Or
echo "<my_current_cookie>" > .env

How to find your Session Cookie? Check SESSION_COOKIE.md.

Fetching problems

Downloads puzzle statement, data and correct answers (if already solved).

esb fetch --year 2016 --day 9

# Hint: Use brace expansion for fetching multiple days or years
esb fetch --year 2023 --day {1..25}

Also fetches default testing files. Check TESTING.md for more information.

Creating boilerplate code

Run start command to create code for the given language. It also fetches data if necessary

esb start --lang rust --year 2023 --day 13

Running tests

Runs tests or selected tests with:

esb test --lang rust --year 2016 --day 9 --part 1

To select tests, pass --filter and select the test name:

esb test --lang rust --year 2016 --day 9 --part 1 --filter "test_01"

Check TESTING.md for more information.

Running for real

Runs the code for the given input. Also can submit solutions.

esb run --lang rust --year 2016 --day 9 --part 1

# Run solution and then submit
esb run --lang rust --year 2016 --day 9 --part 1 --submit

💡 Hint: --lang, --year, --day and --part arguments are cached.

esb start --lang python --year 2018 --day 4
esb test  # Will test the solution created above

Check current cached arguments with esb status Eg:

= Working on: python, 2018 day 4 part 1 =

Check your progress in the command line

esb status shows current collected stars and some additional information.

esb status

esb stats

Viewing problem statement and inputs

To read the problem statements run esb show. The flags --show-input and --show-test might be helpful for viewing the inputs.

esb show --year 2019 --day 19

The dashboards

esb generates two dashboards.

  1. A section in README.md to place a summary of the solutions;
  2. A section in REPORT.md with detailed data on solution attempts and timing;

⚠️ Both files are editable and can be modified manually, except for the section in between the tags <!-- Do not delete ....

The dashboards are updated automatically when solutions are correct. It's possible to generate again by running:

esb dashboard

Currently supported languages

Currently there are built in 3 supported languages. They set up the basic code for a given day that allows esb to run and test solutions. Check the documentation for each language and how to create your own boilerplate.

Any program that supports the FIREPLACEv1 prococol can use esb tooling.

FAQ

Rules of Automation

ElfScript Brigade does follow the automation guidelines on the /r/adventofcode community wiki Specifically:

Once inputs are downloaded, they are cached locally in the .cache directory.

⚠️ This cache data is .gitignonre'd along with the database used to track user progress. If you wish to store this information, please do it in private repositores given that sharing some of this data goes against the "Code of Conduct" for AoC.

If you suspect your input is corrupted, you can manually request a fresh copy using esb fetch ... --force The User-Agent header for the HTTP requests is set to me @luxedo since I maintain this tool :)

License

ESB - Script your way to rescue Christmas as part of the ElfScript Brigade team. Copyright (C) 2024 Luiz Eduardo Amaral luizamaral306@gmail.com

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.