Skip to content

README.md

Latest commit

 

History

History
78 lines (48 loc) · 3.88 KB

README.md

File metadata and controls

78 lines (48 loc) · 3.88 KB
Raw

Exercism GDScript Representer

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

Implementation Details

The representer is written in Python. It relies on gdtoolkit 4.5.0 and lark 1.3.1. It represents the solution using Lark's pretty() output.

Normalizations

  • Comments: The generated AST does not include comments so comments are removed.
  • Whitespace: The generated AST does not include input whitespace so whitespace is normalized.
  • Docstrings: Module docstrings are dropped from the output.
  • String expressions: Function docstrings are treated as any "string expression". String expressions (expressions that contain only a string) are dropped.
  • Variable names: Function variables are replaced with placeholders. This does not cover module variables or class variables.
  • Function names: User defined functions have their names replaced with placeholders.

Run the representer

To create a representation for a single solution, 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 a solution 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 a single solution 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>/expected_representation.txt and tests/<test-name>/expected_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>/expected_representation.txt and tests/<test-name>/expected_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>/expected_representation.txt and tests/<test-name>/expected_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>/expected_representation.txt and tests/<test-name>/expected_mapping.json file.

Benchmarking

There are two scripts you can use to benchmark the representer:

  1. ./bin/benchmark.sh: benchmark the representer code
  2. ./bin/benchmark-in-docker.sh: benchmark the Docker image

These scripts can give a rough estimation of the representer's performance. Bear in mind though that the performance on Exercism's production servers is often lower.