@ofzza/adventofcode
Version:
Task runner for AdventOfCode.com tasks
184 lines (139 loc) • 11.3 kB
Markdown
# adventofcode
Task runner for AdventOfCode.com solutions
## Installation
To use with ease, install as a global NPM module:
```sh
$ npm install -g /adventofcode
```
Then check out help for usage info, or read on:
```sh
$ 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:
```sh
$ adventofcode init
```
The created configuration file `./aoc.json` will have the following schema:
```js
{
// 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.