{"id":13571764,"url":"https://github.com/gobanos/cargo-aoc","last_synced_at":"2025-04-04T08:32:22.361Z","repository":{"id":33586628,"uuid":"159042902","full_name":"gobanos/cargo-aoc","owner":"gobanos","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-07T17:11:05.000Z","size":369,"stargazers_count":471,"open_issues_count":49,"forks_count":53,"subscribers_count":4,"default_branch":"v0.3","last_synced_at":"2025-03-29T06:15:39.111Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gobanos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-25T14:55:43.000Z","updated_at":"2025-03-12T15:50:16.000Z","dependencies_parsed_at":"2023-11-25T15:23:25.010Z","dependency_job_id":"e23ccfba-cab5-4035-b682-5233d5a3f441","html_url":"https://github.com/gobanos/cargo-aoc","commit_stats":{"total_commits":111,"total_committers":13,"mean_commits":8.538461538461538,"dds":"0.29729729729729726","last_synced_commit":"76b4a43ec7c7bb13511374f9a4ff89df7d6b12fc"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobanos%2Fcargo-aoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobanos%2Fcargo-aoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobanos%2Fcargo-aoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gobanos%2Fcargo-aoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gobanos","download_url":"https://codeload.github.com/gobanos/cargo-aoc/tar.gz/refs/heads/v0.3","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247147738,"owners_count":20891753,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T14:01:05.909Z","updated_at":"2025-04-04T08:32:17.352Z","avatar_url":"https://github.com/gobanos.png","language":"Rust","funding_links":[],"categories":["Rust","Project Templates"],"sub_categories":[],"readme":"# Cargo Advent of Code Helper\n\n`cargo-aoc` is a simple CLI tool that aims to be a helper for the [Advent of Code](https://adventofcode.com). \n\nImplement your solution. Let us handle the rest.\n\n# Features\n* Input downloading \n* Running your solution \n* Automatic benchmarking of your solution using [Criterion](https://github.com/japaric/criterion.rs)\n\n# Getting started\n\n## Install `cargo aoc`\n\n`cargo-aoc` is hosted as a binary on crates.io.\nBoot a terminal and install the program using `cargo install cargo-aoc`\n\n## Setting up the CLI\n\nYou will need to find your session token for the AoC in order for cargo-aoc to work. Thankfully, finding your token is easy since it is stored in your Browser's cookies. Open up the devtools of your browser, and then :\n\n* Firefox: \"Storage\" tab, Cookies, and copy the \"Value\" field of the `session` cookie.\n* Google Chrome / Chromium: \"Application\" tab, Cookies, and copy the \"Value\" field of the `session` cookie.\n\nOnce you have it, simply run : `cargo aoc credentials {token}`\n\nYou're now ready to start coding ! \n\nNOTE: If for some reason your token has changed, dont forget to change it back. \n\n`cargo aoc credentials` will show the currently stored user token\n\n## Setting up the project\n\nIn order for `cargo-aoc` to work properly, you have to set the project up correctly. \n\nIf you get lost during the process, you can take [this example repository of AoC 2015](https://github.com/gobanos/advent-of-code-2015) as a template.\n\nFirst, you must add a dependency on `aoc-runner` and `aoc-runner-derive` in your `Cargo.toml`.\nAt the end of the `src/lib.rs`, you will have to use the macro `aoc_lib!{ year = XXXX }`, where XXXX is the\nyear of the AoC puzzles being solved.\n\nWhen implementing a solution for a day, you have to provide functions and tag them accordingly.\nA function is either a **solver** or a **generator**. \n\nThose two types of functions are being executed and benchmarked seperately. Lets have a closer look : \n\n### Generator functions\n\nGenerators allows you to provide a custom type to the solver functions. Sometimes in AoC, you have to parse \nan input and extract a logical structure out of it, before you can actually solve the problem. \n\nGenerator functions are tagged `#[aoc_generator(dayX)]`.\n\nBecause examples are worth a thousand words, lets take a look at [Year 2015, Day 2](https://adventofcode.com/2015/day/2) : \n\nFrom the puzzle's description, we know that `[we] have a list of the dimensions (length l, width w, and height h) of each present`, each present on one line, represented like so: `{L}x{W}x{H}`.\n\nWe might want to first parse the input and extract logical `Gift` structs out of it, like: \n\n```\npub struct Gift {\n    l: u32,\n    w: u32,\n    h: u32\n}\n``` \n\nIn @Gobanos' reference implementation, we can see that he instead chose to settle for a custom type :\n`type Gift = (u32, u32, u32);`.\n\nThus, writing a generator for `Gift`s is fairly simple: \n\n```\n#[aoc_generator(day2)]\npub fn input_generator(input: \u0026str) -\u003e Vec\u003cGift\u003e {\n    input\n        .lines()\n        .map(|l| {\n            let mut gift = l.trim().split('x').map(|d| d.parse().unwrap());\n            (\n                gift.next().unwrap(),\n                gift.next().unwrap(),\n                gift.next().unwrap(),\n            )\n        }).collect()\n}\n``` \n\nAs you can see, generators take a `\u0026str` (or a `\u0026[u8]`) type as an input, and outputs any type that you want, so you can then use it in `solver` functions.\n\n[link to doc](https://docs.rs/aoc-runner-derive/latest/aoc_runner_derive/attr.aoc_generator.html)\n\n### Solver functions \n\nSolver functions are typically your algorithms, they take any input type provided by a generator, and return any type that you want to use, provided that it implements the `Display` trait.\n\nSolver functions are tagged `#[aoc(day2, part1)]`. \nOptionally, you can have multiple implementation for the same part of a day. You must then use a name to tag them correctly, for example : `#[aoc(day2, part1, for_loop)]`. \n\nFollowing with the previous example, implementing a solver for the part one could be done like this :\n\n```\n#[aoc(day2, part1)]\npub fn solve_part1(input: \u0026[Gift]) -\u003e u32 {\n    input\n        .iter()\n        .map(|\u0026(l, w, h)| {\n            let (s1, s2) = smallest_side((l, w, h));\n            2 * l * w + 2 * w * h + 2 * h * l + s1 * s2\n        })\n        .sum()\n}\n``` \n\nNotice how we're taking the `Gift`s generated previously, and using Rust's iterators to solve the problem efficiently, all the while keeping the code maintainable. \n\nThe output of this particular solver is an `u32`, which of course implements `Display`.\nWhen running your solution using `cargo aoc`, said result will then get printed in the console, along with other informations about execution time.\n\n[link to doc](https://docs.rs/aoc-runner-derive/latest/aoc_runner_derive/attr.aoc.html)\n\n# Downloading your input manually\n\n`cargo aoc input` will download an input and store it in `input/{year}/day{day}.txt`. \n\nPlease note that by default, we're taking today's date as the argument. Of course, you can change this using : `cargo aoc input -d {day} -y {year}`\n\n# Running your solution\n\n`cargo aoc` will run the latest implemented day, downloading your input beforehand. It will show you the result, and a short summary of how well it did perform.\n\nExample output on my Chromebook, running [@Gobanos' AOC2015](https://github.com/gobanos/advent-of-code-2015) : \n```\n[olivier@olivier-pc advent-of-code-2015]$ cargo aoc\n    Finished dev [unoptimized + debuginfo] target(s) in 0.12s\n   Compiling aoc-autobuild v0.1.0 (/home/olivier/Workspace/Rust/advent-of-code-2015/target/aoc/aoc-autobuild)\n    Finished release [optimized] target(s) in 0.87s\n     Running `target/release/aoc-autobuild`\nAOC 2015\nDay 5 - Part 1 : 238\n        generator: 18.122µs,\n        runner: 420.958µs\n\nDay 5 - Part 2 : 69\n        generator: 5.499µs,\n        runner: 1.142373ms\n```\n\nIf you want to run an older puzzle, or only a specific part, specify those using `cargo aoc -d {day} -p {part}`.\n\n# Benchmarking your solution\n\nBenchmarking is powered by [Criterion](https://github.com/japaric/criterion.rs). Use `cargo aoc bench` to launch the benchmarks, just like you would use `cargo aoc`.\n\nBenchmarks for each days are then generated in `target/aoc/aoc-autobench/target/criterion`.\n\nYou can open the benchmark automatically in your Browser afterwards, using `cargo aoc bench -o` \n\nSoon(tm), you will also be able to use our (free) online platform, to compare your results with those of the community.\n\n------\n\nHappy Advent of Code !   \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgobanos%2Fcargo-aoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgobanos%2Fcargo-aoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgobanos%2Fcargo-aoc/lists"}