README.md

Saulve

A framework for computer programming challenge.

For the moment, only Advent of Code is supported.

Usage

A few terms need to be defined first. A challenge is a source of programming puzzles (such as Advent of code. A puzzle is a given problem within a challenge (such as multiple of 3 or 5 in Project Euler.

The following example will setup an environment to solve Project Euler puzzles. Start with a python project to store your challenges and create an euler package in it. The name of the euler can be anything you want.

my_challenges/
  __init__.py
  euler/
    __init__.py

Saulve discovers puzzle by scanning modules in the euler package. Each module having a puzzle attribute that is an instance of saulve.Puzzle will be loaded.

# file: my_challenges/euler/problem_001.py
import saulve

puzzle = saulve.Puzzle(name="Multiple of 3 or 5")

Solutions to puzzles are registered by decorating functions with Puzzle.solution.

# file: my_challenges/euler/problem_001.py

@puzzle.solution
def solve():
    return 12

Last thing to do is to tell Saulve where to find this Euler challenge. Saulve entry point is an app attribute at the root module of your package. The app attribute must be an instance of saulve.App.

# file: my_challenges/__init__.py
from saulve import App
from saulve.challenges.generic import GenericLoader
from . import euler

app = App()

app.register_challenge('project-euler', GenericLoader(euler))

The call to register_challenge tells Saulve that a challenge must be registered under the project-euler name (can be anything, it does not need to match the euler package name). The challenge are loaded from the euler package using a GenericLoader (challenge in a given package, one puzzle per module as described above).

You are now ready to use the Saulve cli. You need to tell Saulve where your app attribute is using the --app argument (or by setting a SAULVE_CHALLENGES env variable). Each puzzle is identified by its module name.

You can list all puzzles registered under a challenge:

$ saulve --app challenges project-euler list

To run the solutions functions of a given puzzle:

$ saulve --app challenges project-euler solve problem_001
Multiple of 3 or 5:
  233168

The first argument (project-euler) tells saulve that you want to use the euler registered challenge.

Advent of code support

For advent of code, each puzzle must be in a module named after the puzzle day (ex: day_06.py). A module puzzle must have a puzzle attribute and some registered solution steps.

# file: my_challenges/advent_of_code/year_2022/day_01.py
import saulve

puzzle = saulve.Puzzle(name='Calorie Counting')

@puzzle.solution
def solve_first_star():
    return 121

@puzzle.solution
def solve_second_star():
    retuirn 1932

You then need to tell Saulve to register your advent of code package using an AdventOfCode loader. This loader understand the year/month package.

# file my_challenge/__init__.py
from saulve import App
from saulve.challenges.advent_of_code import AdventOfCodeLoader
from . import advent_of_code

app = App()

app.register_challenge('aoc', AdventOfCodeLoader(advent_of_code))

You can now solve your challenge as before:

$ saulve --app my_challenges aoc solve 2022 01
Calorie Counting:
  121
  1932