[v3] Implement new Concept Exercise: variables

[TheLostLambda]

This document describes how to implement the variables concept exercise for the Common Lisp track.

Getting started

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read up on the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercise and how they are structured?

Please also watch the following video:

• The Anatomy of a Concept Exercise.

Goal

The goal of this exercise is to familiarize students with the definition and scoping of variables in Common Lisp. Students should be able to create local, global, and constant variables and understand dynamic vs lexical scoping.

The use of earmuffs (*var*) and the equivalent convention for constants (+var+) should be encouraged, as should the use of docstrings in global definitions.

Learning objectives

• Know how to use defparameter to define global, dynamic variables
• Know how to use defconstant to define global constants
• Know how to add docstrings to defparameter and defconstant
• Be aware of the naming conventions regarding global variables (earmuffs)
• Know how to use let and let* to define lexically scoped variables
• Understand the distinction between lexically and dynamically scoped values
• Understand how to temporarily rebind a dynamic variable with let

Out of scope

• The distinction between defvar and defparameter
• Local functions with flet
• Assignment with setf, setq, etc.
• Places and the functions for handling them (rotatef, incf, etc.)
• Binding functions (destructuring-bind, multiple-value-bind, etc.)
• The dynamic *standard-output* variable and other built-in dynamic variables
• Streams and stream functions

Concepts

• constants
• variables

Prerequisites

• arithmetic
• expressions
• floating-point-numbers
• integers
• printing

Resources to refer to

• https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node67.html
• http://www.gigamonkeys.com/book/variables.html

Hints

• https://lisp-lang.org/learn/variables

After

Naming conventions could be explored:

• https://www.cliki.net/Naming+conventions
• https://lisp-lang.org/style-guide/

Additionally, a brief exploration into the difference between defparameter and defvar could be included.

Point out that defconstant should be kept to chars, symbols, and numbers. Things that aren't eql, like lists or strings, can have their inner items mutated.

Perhaps show off what rebinding *standard-output* looks like and how it can be used to neatly build up strings.

Representer

• Currently, no extra logic needs to be added to the representer.

Analyzer

• Currently, no extra logic needs to be added to the analyzer.

Implementing

To ensure that students are using docstrings, you can use the documentation function in the test-suite.

Using defconstant may cause issues if the student reloads there code with a new value. This should be mentioned in the instruction.md or introduction.md so that the student is made aware of this pitfall and can avoid it.

When demonstrating dynamic variables, save rebinding *standard-output* for the after.md. It's a good example, but requires an understanding of streams first, which the student is not guaranteed to have.

Help

If you have any questions while implementing the exercise, please post the questions as comments in this issue.

[verdammelt]

I think defconstant will need to be handled carefully in this exercise. If we have the student define it they would easily get into a state where they reload their solution file and get dropped into the debugger because the value is not eql. I think we could explain the situation in instruction.md - but perhaps we should call this out in "implementing" as something that needs handling.

[verdammelt]

Also there is mention that *standard-output* is out of scope but is mentioned in "Implementing" as something to use as an example... can we clarify this potential contradiction?

[TheLostLambda]

I've added a note about defconstant thanks for pointing that out! Additionally, I've tweaked the wording a bit. I think it would be okay to show off in the after.md but we should probably not teach streams in this exercise or expect the student to know them already. Let me know if that helps clarify any!

[verdammelt]

That is definitely clearer to me thanks.