From 27932781e744b7c2717d7ee4235224728af41255 Mon Sep 17 00:00:00 2001 From: Remo Senekowitsch Date: Wed, 13 Sep 2023 08:21:16 +0200 Subject: [PATCH] Add tera filter to_hex for use in test templates and improve documentation about creating test templates --- .gitignore | 1 + bin/symlink_problem_specifications.sh | 12 +++++ docs/CONTRIBUTING.md | 69 ++++++++++++++++++++++++- rust-tooling/src/exercise_generation.rs | 16 +++++- 4 files changed, 96 insertions(+), 2 deletions(-) create mode 100755 bin/symlink_problem_specifications.sh diff --git a/.gitignore b/.gitignore index edcc454ae..5af0f3619 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ tmp exercises/*/*/Cargo.lock exercises/*/*/clippy.log .vscode +.prob-spec diff --git a/bin/symlink_problem_specifications.sh b/bin/symlink_problem_specifications.sh new file mode 100755 index 000000000..bf86ebaa9 --- /dev/null +++ b/bin/symlink_problem_specifications.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +set -eo pipefail + +cd "$(git rev-parse --show-toplevel)" + +for exercise in exercises/practice/*; do + name="$(basename "$exercise")" + if [ -d "problem-specifications/exercises/$name" ]; then + [ -e "$exercise/.prob-spec" ] && rm "$exercise/.prob-spec" + ln -s "../../../problem-specifications/exercises/$name" "$exercise/.prob-spec" + fi +done diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index a0eb8e3a8..7d2e57e05 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -33,6 +33,7 @@ Run `just add-practice-exercise` and you'll be prompted for the minimal information required to generate the exercise stub for you. After that, jump in the generated exercise and fill in any todos you find. This includes most notably: + - adding an example solution in `.meta/example.rs` - Adjusting `.meta/test_template.tera` @@ -41,12 +42,14 @@ The input of the template is the canonical data from [`problem-specifications`]. if you want to exclude certain tests from being generated, you have to set `include = false` in `.meta/tests.toml`. +Find some tips about writing tera templates [here](#tera-templates). + [Tera]: https://keats.github.io/tera/docs/ [`problem-specifications`]: https://github.com/exercism/problem-specifications/ Many aspects of a correctly implemented exercises are checked in CI. I recommend that instead of spending lots of time studying and writing -documentation about the process, *just do it*. +documentation about the process, _just do it_. If something breaks, fix it and add a test / automation so it won't happen anymore. @@ -87,6 +90,70 @@ Run `just update-practice-exercise` to update an exercise. This outsources most work to `configlet sync --update` and runs the test generator again. +When updaing an exercise that doesn't have a tera template yet, +a new one will be generated for you. +You will likely have to adjust it to some extent. + +Find some tips about writing tera templates [in the next section](#tera-templates). + +## Tera templates + +The full documentation for tera templates is [here][tera-docs]. +Following are some approaches that have worked for our specific needs. + +You will likely want to look at the exercise's `canonical-data.json` +to see what structure your input data has. +You can use `bin/symlink_problem_specifications.sh` to have this data +symlinked into the actual exercise directory. Handy! + +The name of the input property is different for each exercise. +The default template will be something like this: + +```txt +let input = {{ test.input | json_encode() }}; +``` + +You will have to add the specific field of input for this exercise, e.g. + +```txt +let input = {{ test.input.integers | json_encode() }}; +``` + +Some exercises may have error return values. +You can use an if-else to render something different, +depending on the structure of the data: + +```txt +let expected = {% if test.expected is object -%} + None +{%- else -%} + Some({{ test.expected }}) +{%- endif %}; +``` + +If every test case needs to do some crunching of the inputs, +you can add utils functions at the top of the tera template. +See [`word-count`'s template][word-count-tmpl] for an example. + +Some exercises have multiple functions that need to be implemented +by the student and therefore tested. +The canonical data contains a field `property` in that case. +The template also has access to a value `fn_names`, +which is an array of functions found in `lib.rs`. +So, you can construct if-else-chains based on `test.property` +and render a different element of `fn_names` based on that. +See [`variable-length-quantity`'s template][var-len-q-tmpl] for an example. + +There is a custom tera fiter `to_hex`, which formats ints in hexadecimal. +Feel free to add your own in the crate `rust-tooling`. +Custom filters added there will be available to all templates. +How to create such custom filters is documented int he [tera docs][tera-docs-filters]. + +[tera-docs]: https://keats.github.io/tera/docs/#templates +[word-count-tmpl]: /exercises/practice/word-count/.meta/test_template.tera +[var-len-q-tmpl]: /exercises/practice/variable-length-quantity/.meta/test_template.tera +[tera-docs-filters]: https://keats.github.io/tera/docs/#filters + ## Syllabus The syllabus is currently deactivated due to low quality. diff --git a/rust-tooling/src/exercise_generation.rs b/rust-tooling/src/exercise_generation.rs index 028776a61..9e403d2e0 100644 --- a/rust-tooling/src/exercise_generation.rs +++ b/rust-tooling/src/exercise_generation.rs @@ -1,3 +1,5 @@ +use std::collections::HashMap; + use tera::Context; use crate::{ @@ -81,6 +83,13 @@ fn extend_single_cases(single_cases: &mut Vec, cases: Vec) -> tera::Result { + Ok(serde_json::Value::String(format!( + "{:x}", + value.as_u64().unwrap() + ))) +} + fn generate_tests(slug: &str, fn_names: Vec) -> String { let cases = get_canonical_data(slug).cases; let excluded_tests = get_excluded_tests(slug); @@ -90,6 +99,7 @@ fn generate_tests(slug: &str, fn_names: Vec) -> String { .add_raw_template("test_template.tera", TEST_TEMPLATE) .unwrap(); } + template.register_filter("to_hex", to_hex); let mut single_cases = Vec::new(); extend_single_cases(&mut single_cases, cases); @@ -100,5 +110,9 @@ fn generate_tests(slug: &str, fn_names: Vec) -> String { context.insert("fn_names", &fn_names); context.insert("cases", &single_cases); - template.render("test_template.tera", &context).unwrap().trim_start().into() + template + .render("test_template.tera", &context) + .unwrap() + .trim_start() + .into() }