Macros by Example exercise

[coriolinus]

Macros are a powerful part of a Rust programmer's toolkit, and macros by example are a relatively simple way to access this power. However, to beginners in the language, they're just scary black magic; while println! and vec! are frequently used, they're not something you'd write on your own. At least, that's how I felt when I was starting in the language.

The Rust track needs an exercise which is best solved by using this tool, as a way of introducing people to the concept. To some extent, we have exercises which are implicitly similar if macros are available. For example, the decimal example is implemented in terms of macros. However, there's nothing currently which explicitly suggests the use of macros in a case where they'd make sense.

The elephant in the room WRT a macro exercise is that there is no way to guarantee that the student has actually used macros in their solution; anything which can be generated by macro can be hand-written by a student with a sufficiently high threshold for tedium.

My intent is to use this issue as a space to bat back and forth some proposals for macro exercises, and collaboratively come to a design which makes sense.

[coriolinus]

The first idea comes from recent work on the perfect-numbers tests: we could invert the typical exercism flow by providing a working toy program, and having the student write a macro which generates a bunch of tests for it.

Pros:

• It's a place where it's plausible to use macros in the real world

Cons:

• Difficulty in writing a metatest which ensures that all the test cases we expect from the student have been implemented
• Reversing the normal exercism flow for the student will likely lead to some confusion

[coriolinus]

Another possibility for a macro exercise would be to frame it as an opportunity for compile-time numeric processing. The idea is to take advantage of the fact that LLVM will simplify constant expressions, including those produced by macros, during compilation.

If we went this route, we'd want to have at least two macros exercises: one fairly early in the exercise list which was only about numeric processing, and another later on which dealt with a more powerful usage.

The hardest part of this will be choosing an appropriate function, for which the answer is hard to work out by hand, but relatively straightforward to write macros for. Ideally it'll involve not just expression assembly, but also some branching based on macro pattern matching.

Pros:

• Standard exercism workflow and tests
• Plausible rationale for macro use

Cons:

• Nothing stops the student from writing a non-macro-based implementation, or even computing the result by hand and pasting that in.

[coriolinus]

A third possibility, my current favorite, would be to have students implement their own version of a real-world macro from a library. I think the hashmap! macro from the maplit crate would be a good candidate for that.

Pros:

• Not too complicated (real world example is 15 lines long)
• Not too simple (at minimum, requires student to know about repetition operators and recursion (for optional trailing comma))
• Solves a real need (crate from which this example is taken has over 50,000 downloads)
• Easy for students to understand, and the Rust book includes an analogous example

Cons:

• Students might be tempted to simply import the crate instead of writing their own implementation
• Incomplete implementations don't just fail tests, they won't compile at all. Tests are all-or-nothing.

[petertseng]

and having the student write a macro which generates a bunch of tests for it.
Reversing the normal exercism flow for the student will likely lead to some confusion

A previous Exercism-wide exercise (in theory, but in practice only implemented by one track) that reverses the flow was deprecated in exercism/problem-specifications#80. The fact that I have provided this information is not permitted to be interpreted as a vote either for or against taking this approach in this track.

compile-time numeric processing
at least two macros exercises: one fairly early in the exercise list which was only about numeric processing, and another later on which dealt with a more powerful usage.

OK, makes it sound like this suggestion is to be taken in addition to another (rather than an alternative possibility of "there's only one macro exercise, we must choose only one of these options")

own version of a real-world macro from a library
Incomplete implementations don't just fail tests, they won't compile at all. Tests are all-or-nothing.

I'm hoping it'll be sufficient to show them the flags to output the result of the macro expansion

[coriolinus]

I'm part-way through an implementation of variant three, implementing the hashmap macro from the library. Showing how to emit the macro expansion is indeed part of the README.