@ofzza/adventofcode

adventofcode

Task runner for AdventOfCode.com solutions

Installation

To use with ease, install as a global NPM module:

$ npm install -g @ofzza/adventofcode

Then check out help for usage info, or read on:

$ adventofcode --help

Usage

Advent of Code runner executes and times your Advent of Code solutions.

Config

To use the runner, just create a config JSON file (comments allowed) by running the following:

$ adventofcode init

The created configuration file ./aoc.json will have the following schema:

{
  // General information
  "author": "ofzza",
  "year": 2021,

  // Runnable tasks
  "tasks": [
    // Test task
    {
      "name": "test-01",
      "type": "test",
      "command": "bash",
      "args": ["./task1.sh"]
    },

    // Test task with expected value
    {
      "name": "test-02",
      "type": "test",
      "command": "bash",
      "args": ["./task2.sh"],
      "value": "Hello world"
    },

    // Solution test task with dynamic arguments
    {
      "name": "solution-A",
      "type": "solution",
      "command": "bash",
      "args": ["./task3.sh", "--name", "{{:name}}", "{{verbose??--verbose}}", "{{obfuscate??--obfuscate}}"],
      "value": "Hello world"
    }

    // Solution task with multiple inputs and expected values
    {
      "name": "solution-B",
      "type": "solution",
      "command": "bash",
      "args": ["{{input??:input}}", "--name", "{{:name}}", "{{arg??--some-argument :arg}}"],
      "runs": [
        { "name": "solution-B1", "input": "./multi-task.sh", "arg": "1", "value": "Hello world" },
        { "name": "solution-B2", "input": "./multi-task.sh", "arg": "2", "value": "Hello world" },
        { "name": "solution-B3", "input": "./multi-task.sh", "arg": "3" },
        { "name": "solution-B4", "input": "./multi-task.sh", "arg": "4" }
      ]
    }

    // ...
  ]
}

Configuration properties for each task:

• (Optional) name

  Task name. Used as a task descriptor and can be used to select which task(s) to run.

• (Optional) type

  Task type. Use any value here, it is used to select which task(s) to run.

• command

  Command to execute to run the task. All paths are relative to the parent directory of the configuration file.

• (Optional) args

  Command arguments to execute the command with. Arguments can use dynamic argument syntax as described below.

  Dynamic arguments:

  Startup arguments, and any property of a configuration can be used to modify arguments sent to a task command as dynamic arguments:

  • Dynamic argument expressions should be placed inside double brackets and are made of a condition and a syntax part ({{condition??syntax}}), separated with a ??, or just the syntax part ({{syntax}}).

  • the (optional) condition part specifies a name of the startup argument or configuration property whose existence is used as a condition for the argument being used at all.

  • the syntax part will be used verbatim with the exception of :variables which will be replaced with values of startup arguments or configuration properties of the same name as the variable.

  EXAMPLES, following startup arguments execute different dynamic tasks:

  Startup arguments	Task(s) executed	Expected value
  $ adventofcode run -n solution-A	$ task3.sh --name "solution-A"	Hello world
  $ adventofcode run -n solution-A --verbose	$ task3.sh --name "solution-A" --verbose	Hello world
  $ adventofcode run -n solution-A --obfuscate	$ task3.sh --name "solution-A" --obfuscate	Hello world
  $ adventofcode run -n solution-B --verbose --obfuscate	$ multi-task.sh --name "solution-B1" --some-argument "1"	Hello world
  	$ multi-task.sh --name "solution-B2" --some-argument "2"	Hello world
  	$ multi-task.sh --name "solution-B3" --some-argument "3"
  	$ multi-task.sh --name "solution-B4" --some-argument "4"

• (Optional) value

The value optional property of the task definition, will be compared to the last line output by the process being run out to stdout to determine the task value as valid or invalid. Your program can output debug information, but only the last line will count as its final result.

• (Optional) runs

Definition for multiple runs of the task - on each run, this configuration will be overridden with properties from the run and additional properties can be added

CLI

Description	Syntax	Output	Explanation
List tasks	$ adventofcode list	bash ./task1.sh	Command(s)
		bash ./task2.sh
		bash ./task3.sh
List tasks from custom config	$ adventofcode list -c ./dir/conf.json	bash ./task1.sh	Command(s)
		bash ./task2.sh
		bash ./task3.sh
List tasks verbosely	$ adventofcode list -v	> Found 3 runnable tasks:	Full info
		001. test-01, test (bash ./task1.sh)
		002. test-02, test (bash ./task2.sh)
		003. solution-A, solution (bash ./task3.sh)

If custom --config is not specified, ./aoc.json is presumed.

Description	Syntax	Output	Explanation
Run all tasks	$ adventofcode run	✘ 141ms 123	Outputs success, execution time and result
		✓ 142ms 123
		✘ 136ms 123
Run cherry picked task(s)	$ adventofcode run -t 1 -t 3	✘ 141ms 123	Only runs 1st and 3rd tasks
		✘ 136ms 123
Ran tasks by name	$ adventofcode run -n test	✘ 141ms 123	Runs tasks with names starting with "test"
		✓ 142ms 123
Run tasks by type	$ adventofcode run -p solution	✘ 136ms 123	Runs tasks with type "solution"
Runs tasks from custom config	$ adventofcode run -c ./dir/conf.json	✘ 141ms 123	Runs from custom config
		✓ 142ms 123
		✘ 136ms 123
Runs tasks verbosely	$ adventofcode run -v	[Verbose output with summary]	Runs with verbose output
Runs tasks and obfuscate result	$ adventofcode run -b	[Obfuscated output with summary]	Runs with obfuscated output
Run tasks with fully piped	$ adventofcode run -v -o	[Verbose output with summary]	Runs with full stdout piped to output
stdout output		[and full stdout piped through]

If custom --config is not specified, ./aoc.json is presumed.