Build representer

[ErikSchierboom]

In Exercism v3, we're introducing a new (optional) tool: the representer. The goal of the representer is to take a solution and returning a representation, which is an extraction of a solution to its essence with normalized names, comments, spacing, etc. but still uniquely identifying the approach taken. Two different ways of solving the same exercise must not have the same representation.

Each representer is track-specific. When a new solution is submitted, we run the track's representer, which outputs two JSON files that describe the representation.

Once we have a normalized representation for a solution, a team of vetted mentors will look at the solution and comment on it (if needed). These comments will then automatically be submitted to each new solution with the same representation. A notification will be sent for old solutions with a matching representation.

The representer is an optional tool though, which means that if a track does not have a representer, it will still function normally.

Goal

Build a representer for your track according to the spec. Check this page to help you get started with building a representer.

Note that the simplest representer is one that merely returns the solution's source code.

It can be very useful to check how other tracks have implemented their representer.

If your track already has a working representer, please close this issue and ensure that the .status.representer key in the track config.json file is set to true.

Choosing between representer and analyzer

There is some overlap between the goals of the representer and the analyzer. If you want to build both, we recommend starting by building the representer for the following reasons:

• Representers are usually (far) easier to implement
• Representers can have a far bigger impact on the mentoring load than analyzers by empowering mentors
• Representers apply to all exercises, whereas analyzers usually target specific exercises or a subset

Tracking

https://github.com/exercism/v3-launch/issues/52

[berson-andrew]

Is it required that the zig representer be written in zig?

[kotp]

I do not believe there really is a language requirement for the representer. It might be nice to have it as Zig, since the maintainers of the track would by default know that language. The requirement would be that it does what it is meant to do, rather than that it must be a specific language.

[ErikSchierboom]

There is no requirement for the representer to be written in Zig, but as a proper representer will need access to the code's structure in code (usually an Abstract Syntax Tree), often that sort of functionality is only available within the language itself.

And as kotp mentioned, having it be written in Zig makes it far more likely that the existing maintainers can work on it. So I'd say: use the actual language unless there is a very good reason and the maintainers have agreed on another language to write the representer in.

[berson-andrew]

That makes sense, thank you. I found an article on the AST used internally in the Zig compiler Zig Parser and AST Layout , so I think that will be a big help

[theodesp]

Zig does not have an AST Visitor or an AST NodeTransformer yet. The closest thing I've seen is the AST -> source code renderer https://github.com/ziglang/zig/blob/master/lib/std/zig/render.zig

However this is not a Visitor so you cannot plug visitor methods to transform the code. It would be a great exercise.

[jelemux]

I've implemented a representer in zig by using a modified version of std/zig/render.zig and I'd like to contribute it. You can have a look at it here: https://github.com/jelemux/zig-representer

It implements all the recommended normalizations except sorting top-level declarations. Though I'm sure that's possible as well. Because I copied code from the standard library, we may have to have a look at licensing. I added a copyright notice to the copied code as required by MIT which should cover it, but IANAL so idk.

Please tell me how we should proceed.

[ee7]

@jelemux Cool. I had a very quick look - it looks promising. Are you happy with the test coverage for the implemented features?

It implements all the recommended normalizations except sorting top-level declarations.

That'd be nice to have, but I think it's not necessary for merging the initial representer PRs.

Because I copied code from the standard library, we may have to have a look at licensing. I added a copyright notice to the copied code as required by MIT which should cover it, but IANAL so idk.

Yes, we just have to comply with the conditions of the MIT License. That is, include the license text and the copyright notice.

Please tell me how we should proceed.

We've created https://github.com/exercism/zig-representer. Please create a PR there, and we'll go from there. There's some guidance in the repo, and in the Exercism representer docs, which I imagine you've already seen.

Thanks! Let me know if you have questions.