https://github.com/exercism/gleam-representer
https://github.com/exercism/gleam-representer
exercism-representer exercism-tooling
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/exercism/gleam-representer
- Owner: exercism
- License: agpl-3.0
- Created: 2023-07-11T14:22:02.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-25T06:36:09.000Z (about 1 year ago)
- Last Synced: 2024-05-01T11:25:17.775Z (about 1 year ago)
- Topics: exercism-representer, exercism-tooling
- Language: Shell
- Homepage:
- Size: 32.2 KB
- Stars: 1
- Watchers: 7
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Exercism Representer Template
This repository is a [template repository](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-template-repository) for creating [representers][representers] for [Exercism][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/-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](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template) 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](#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. Build the representer, conforming to the [Representer interface specification](https://github.com/exercism/docs/blob/main/building/tooling/representers/interface.md).
- 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](https://github.com/exercism/exercism/issues/new?title=%5BTRACK%5D+Request+Representer+Repository) 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 `
Once the representer has finished, its results will be written to `/representation.txt` and `/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 `
Once the representer has finished, its results will be written to `/representation.txt` and `/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][golden] that compare the `representation.txt` and `mapping.json` generated by running the current state of the code against the "known good" `tests//representation.txt` and `tests//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//representation.txt` and `tests//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][golden] that compare the `representation.txt` and `mapping.json` generated by running the current state of the code against the "known good" `tests//representation.txt` and `tests//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//representation.txt` and `tests//mapping.json` file.
[representers]: https://github.com/exercism/docs/tree/main/building/tooling/representers
[golden]: https://ro-che.info/articles/2017-12-04-golden-tests
[exercism]: https://exercism.io