Exercism Representer Template

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

Using the Representer Template

1. 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)
2. 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)
3. Remove this Exercism Representer Template section from the README.md file
4. Replace TRACK_NAME_HERE with your track's name in the README.md file
5. Replace any occurances of exercism/representer with exercism/<track>-representer (e.g. exercism/python-representer)
6. 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. The existing test solutions are suggestions for you could be testing, but remember to add your track-specific files too
   • 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:

1. Open a terminal in the project's root
2. 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:

1. Open a terminal in the project's root
2. 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:

1. Open a terminal in the project's root
2. 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

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

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

1. Open a terminal in the project's root
2. Run ./bin/run-tests-in-docker.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.