# -*- mode: org -*-

#+TITLE: Exercism Scheme Track
#+AUTHOR: Jason Lewis

[![Configlet Status](https://github.com/exercism/scheme/workflows/configlet/badge.svg)]
[![Exercise Test Status](https://github.com/exercism/scheme/workflows/scheme%20%2F%20main/badge.svg)]

Exercisms in scheme.

** Overview

   Welcome to the home of the exercism scheme track! Many parts of the
   track are specified inside scheme and then output in various
   formats. For example, exercism wants a =config.json= file, which is
   actually specified in [[file:config/track.ss][config/track.ss]]. Everything including the
   exercise implementations, and the documentation is also done from
   scheme. In general, the way to modify the track is to edit
   something in the [[file:input/][input/]] directory. Exercism problem implementations
   live in [[file:input/exercises/][input/exercises/]]. Student facing documentation (like
   resources and links) is built from files in [[file:input/docs/][input/docs/]].
    
** Setup

    To work on the scheme track you'll need [[https://cisco.github.io/ChezScheme/][ChezScheme]] and [[https://www.gnu.org/software/guile/][GNU
    Guile]]. The goal is for exercises to be implemented such that they
    work in either scheme. Each exercise has tests and an example
    solution and, as part of the build process, it is checked that
    these tests pass in both schemes.

    There is a small json library (borrowed from [[https://github.com/weinholt/packrat][packrat]]) in
    =code/json.sls=, which relies on some modules from the [[https://github.com/fedeinthemix/chez-srfi][srfi]]
    collection. ChezScheme finds libraries through an environment
    variable =CHEZSCHEMELIBDIRS=. So, you'll need to make sure the
    location of your downloaded srfi is added to
    =CHEZSCHEMELIBDIRS=. Instructions for installing the srfi
    collection can be found at [[https://github.com/fedeinthemix/chez-srfi/blob/master/srfi/INSTALL.chez][srfi/INSTALL.chez]]. If you're using
    either the [[https://guix.gnu.org/][guix]] or [[https://nixos.org/nix/][nix]] package managers, you can find the srfis
    pre-packaged.

** Working on the Scheme track

    To work the track, you should start by heading to this directory
    and firing up a Scheme REPL. Enter =(load "load.ss")=, which
    orchestrates loading the appropriate files.

    Exercises are typically specified in [[https://github.com/exercism/problem-specifications][problem-specifications]], a
    repository that has descriptions, versions, and tests described
    through JSON files. The [[file:Makefile][Makefile]] will clone it; the scheme in
    [[file:code/][code/]] will read problem information from that JSON. It is,
    however, also possible to define novel exercises if you wish.

*** Requirements

    Exercises have a few required parts, taking the exercise
    [[file:input/exercises/pascals-triangle/][input/exercises/pascals-triangle/]] as an example.
    + The [[file:input/exercises/pascals-triangle/example.scm][example.scm]] file which is an example solution that must pass
      the tests. It must also use only =r6rs= scheme features so that
      it can run in both Guile and Chez scheme.
    + A stub file [[file:input/exercises/pascals-triangle/pascals-triangle.scm][pascals-triangle.scm]] usually named after the problem
      that the student will be given to write their solultion.
    + The [[file:input/exercises/pascals-triangle/test.ss][test.ss]] which builds the test cases as well as problem
      metadata (such as problem versions, read from the
      specifications) and extra documentation (if needed). The crucial
      part of this file is a call to ~put-problem!~, a procedure
      defined in [[file:code/track.ss][code/track.ss]] that defines the problem whose name is
      a symbol (eg ='pascals-triangle=) and an association list with
      the following form

#+begin_src scheme :exports code
(let ((spec (get-test-specification 'pascals-triangle)))
  (put-problem!
   'pascals-triangle
   `((test . ,(spec->tests spec))
     (stubs pascals-triangle)
     (version . ,(lookup 'version spec))
     (skeleton . "pascals-triangle.scm")
     (solution . "example.scm")
     (markdown . ,(splice-exercism 'pascals-triangle)))))
#+end_src

    The tests are parsed in a fairly horrible and ad-hoc way:

#+begin_src scheme :exports code
(define (spec->tests spec)
  (map parse-test
       (lookup 'cases
               (car
                (lookup 'cases spec)))))
#+end_src

    due to the fairly irregular problem specifications. =parse-test=
    is defined:

#+begin_src scheme :exports code
(define (parse-test test)
  `(test-success ,(lookup 'description test)
                 equal?
                 pascals-triangle
                 '(,(cdar (lookup 'input test)))
                 ',(lookup 'expected test)))
#+end_src

    =pascals-triangle= has a fairly friendly specification. An example
    of a less straightforward one from [[file:input/exercises/change/test.ss][change]] is the following:

#+begin_src scheme
(define (parse-test test)
  (let ((expected (lookup 'expected test))
        (input (lookup 'input test)))
    (if (or (null? expected)
            (number? (car expected)))
        `(test-success ,(lookup 'description test)
                       (lambda (out expected)
                         (equal? (list-sort < out) (list-sort < expected)))
                       change
                       '(,(lookup 'target input)
                         ,(lookup 'coins input))
                       ',expected)
        `(test-error ,(lookup 'description test)
                     change
                     '(,(lookup 'target input)
                       ,(lookup 'coins input))))))
#+end_src

    There are test cases expected to fail and a more elaborate passing
    predicate to allow students to return answers in any order.

    Final requirement:

     + Add the problem to the configuration expression in
      [[file:config/track.ss][config/track.ss]]. You need to provide a uuid, which can be
      generated from the scheme repl by calling =(configlet-uuid)=
      (which is just a wrapper for the configlet binary). Finally,
      include the problem in the list of implementations in the
      [[https://github.com/exercism/scheme/blob/master/Makefile][Makefile]].

    When [[file:Makefile][building]] the track, the makefile reads each exercise
    directory and uses the =test.ss= files to generate the [[file:exercises/pascals-triangle/test.scm][test.scm]]
    files that the students use. The procedure =spec->tests= reads the
    parsed specification json and turns that into runnable scheme
    tests. The json is parsed through a procedure
    ~get-test-specification~.

    Basically, =test.ss= defines each problem as an instance of an
    exercism problem, having the parts described above, which are used
    to output the files that the students get.

*** Extras
    
    Helpful and useful procedures include:

     - To start a new exercise, use =(stub-exercism 'change)=. This
       creates rough stubs for =test.ss=, =change.scm=, and
       =example.scm= in the directory [[file:input/exercises/change/][input/exercises/change/]].
     - =(verify-exercism 'change)= checks that the solution passes
       generated test suite. It ought to work under both =Guile= and
       =Chez=, with =(rnrs)= as the imported library.

*** Adding problems not in exercism/problem-specifications

    New problems from outside of the specifications are welcome as
    well. Develop them as described above in the =code/exercises=
    directory, following pretty much the same process as above. The
    main difference is that instead of parsing test cases from the
    problem-specifications repository, you'll write them by hand in a
    =test.ss= file.

** Scheme icon

   The Scheme logo was created by
 https://en.wikipedia.org/wiki/User:Matthias.f and released under the
 Creative Commons Attribution-Share Alike 3.0 Unported license.  We
 adapted the logo, creating a pink/black version to use on Exercism.