User guide

Subcommands

coctus help

Use coctus help to see available commands. You can see more detailed information about each of the subcommands by running coctus subcommand --help.

coctus status

The status subcommand is used to show information about the tool state. It can tell you which clash is currently active and the locations where the tool is storing its data and configuration.

coctus show

The show subcommand renders a clash (or puzzle) statement to the terminal. By default it will print the currently active clash, but you can also give it a handle to show a specific clash without changing the currently active clash.

coctus next

The next subcommand is the primary way to change the currently active clash. By default it will choose any random clash, but you can give it arguments to select a specific clash or clash type. See coctus next --help for details.

coctus run

The run subcommand is used to test a solution against the test cases of a problem. You must specify a command that runs your solution (the command should read the input from STDIN, and print the solution to STDOUT). If you are using a compiled language you may use --build-command to specify a command that is only ran once before the tests so your solution code won't be re-compiled for every test case.

Examples:

$ coctus run --command 'python3 solution.py'
$ coctus run --command 'tr A-Za-z a-zA-Z'
$ coctus run --build-command 'rustc -o sol.exe solution.rs' --command './sol.exe'

coctus fetch

The fetch subcommand is used to download puzzles from the CodinGame website. You must specify a handle (that's the last part of the URL on the contribution page, for example if the URL is https://www.codingame.com/contribute/view/682102420fbce0fce95e0ee56095ea2b9924 then the handle is 682102420fbce0fce95e0ee56095ea2b9924).

coctus showtests

The showtests subcommand is used to inspect testcase inputs and/or outputs. On CodinGame every other testcase is a "validator" which are not visible when solving a problem on the site, but they are used to validate the submissions. When using coctus showtests the evenly numbered tests are validators. For example coctus showtests 1,2,3 would print the first test (1), the first validator (2), and the second test (3). If you don't specify any testcases by number, showtests will print all testcases for the currently active clash.

coctus json

The json subcommand prints the currently active clash in JSON format. It is mostly useful for accessing parts of the puzzles that are not yet supported by coctus or debugging coctus itself. The output may be piped to jq for pretty printing or further processing. For example coctus json | jq .codingamerHandle prints the id of the user who authored the currently active clash.

coctus generate-stub

The generate-stub subcommand prints a template file (a "stub") that contains code for reading the input into variables. You must specify a programming language to use. Stubs are currently only supported for python, ruby, rust, c, and cpp. In typical usage the output of the command is redirected to a file:

$ coctus generate-stub python > sol.py
$ nano sol.py

coctus generate-shell-completion

generate-shell-completion can be used to enable auto-completion on the command line. Enabling auto-completion lets you press tab to complete incomplete subcommand and argument names (for example --c<tab> -> --command). You must provide a shell name as an argument. The supported shells are bash, fish, zsh, powershell and elvish. You may want to consult your shell's documentation on details about auto-completion as the conventions vary between different shells, but these are the typical commands you would run to enable shell completions for most common ones:

$ coctus generate-shell-completion bash >> ~/.config/bash_completion
$ coctus generate-shell-completion fish > ~/.config/fish/completions/coctus.fish
$ coctus generate-shell-completion powershell >> $PROFILE.CurrentUserCurrentHost

Tips and Tricks

Auto-refreshing using entr or nodemon

We recommend using a program such as entr or nodemon to refresh the statement when the current clash changes and/or automatically run tests when a file is saved. Combining coctus with one of these tools allows you to never need to leave your text editor while clashing.

Example 1: Automatically show the new problem when it changes

This example uses entr (or nodemon) to detect changes to the file that keeps track of the current clash and run the command coctus show. The -c flag to entr clears the terminal before running the command. Press Ctrl-c to stop.

# Option 1: using entr (Linux only)
ls ~/.local/share/coctus/current | entr -c coctus show

# Option 2: using nodemon (PowerShell on Windows only)
nodemon --watch "$env:APPDATA\CoCtus\coctus\data\current" --exec coctus show

Example 2: Automatically run code when a file is saved

This example uses entr (or nodemon) to watch over .py files in the current directory and run python3 sol.py when any of them are saved to disk. The --auto-advance flag automatically does the equivalent of coctus next when you pass all the test cases. Press Ctrl-c to stop.

# Option 1: using entr (Linux only)
ls *.py | entr coctus run --auto-advance --command "python3 sol.py"

# Option 2: using nodemon (works on both Linux and Windows)
nodemon --ext py --exec coctus -- run --auto-advance --command "python3 sol.py"

Disabling color output

You may disable colors by setting the NO_COLOR environment variable to any non-empty value:

$ NO_COLOR=1 coctus show