Exercism Representer Template

This repository is a template repository for creating representers for Exercism tracks.

Using the Representer Template

Ensure that your track has not already implemented a representer. If there is, there will be a https://github.com/exercism/<track>-representer repository (i.e. if your track's slug is python, the representer repo would be https://github.com/exercism/python-representer)
Follow GitHub's documentation for creating a repository from a template repository
- Name your new repository based on your language track's slug (i.e. if your track is for Python, your representer repo name is python-representer)
Remove this Exercism Representer Template section from the README.md file
Replace TRACK_NAME_HERE with your track's name in the README.md file
Build the representer, conforming to the Representer interface specification.
- Update the files to match your track's needs. At the very least, you'll need to update bin/run.sh, Dockerfile and the test solutions in the tests directory
- Tip: look for TODO: comments to point you towards code that need updating
- Tip: look for OPTIONAL: comments to point you towards code that could be useful

Once you're happy with your representer, open an issue on the exercism/exercism repo to request an official representer repository for your track.

Default Implementation

The default implementation works as follows:

The representation.txt contains the concatenated solution files
- Solution files are separated by an empty line
- Solution files are identified via the the .files.solution[] property in the .meta/config.json file
The mapping.json contains an empty JSON object ({})

Normalizations

Blank files in the solution files are removed in the representation.txt
Line-based trailing whitespace in the solution files is removed in the representation.txt

Exercism TRACK_NAME_HERE Representer

The Docker image to automatically create a representation for TRACK_NAME_HERE solutions submitted to Exercism.

Run the representer

To create a representation for an arbitrary exercise, do the following:

Open a terminal in the project's root
Run ./bin/run.sh <exercise-slug> <solution-dir> <output-dir>

Once the representer has finished, its results will be written to <output-dir>/representation.txt and <output-dir>/mapping.json.

Run the representer on an exercise using Docker

This script is provided for testing purposes, as it mimics how representers run in Exercism's production environment.

To create a representation for an using the Docker image, do the following:

Open a terminal in the project's root
Run ./bin/run-in-docker.sh <exercise-slug> <solution-dir> <output-dir>

Once the representer has finished, its results will be written to <output-dir>/representation.txt and <output-dir>/mapping.json.

Run the tests

To run the tests to verify the behavior of the representer, do the following:

Open a terminal in the project's root
Run ./bin/run-tests.sh

These are golden tests that compare the representation.txt and mapping.json generated by running the current state of the code against the "known good" tests/<test-name>/representation.txt and tests/<test-name>/mapping.json. All files created during the test run itself are discarded.

When you've made modifications to the code that will result in a new "golden" state, you'll need to generate and commit a new tests/<test-name>/representation.txt and tests/<test-name>/mapping.json file.

Run the tests using Docker