Exercism Standard ML Track

Exercism exercises in Standard ML.

Contributing Guide

Any type of contribution is more than welcome!

The first step is to get familiar with this guideline.

Setup

Even though there are multiple Standard ML implementations, we'll stick to PolyML.

Please read INSTALLATION.md for more info.

Exercise structure

Every exercise must have at least these files:

example.sml: Example solution
{{ slug }}.sml: Stub file with the same functions as example.sml
README.md: Exercise description
HINTS.md: (Optional)
test.sml: Test suite
testlib.sml Test helper

`testlib.sml`

This helper has this structures:

structure Expect:
  sig
    val anyError: (unit -> 'a) -> expectation
    val equalTo: ''a -> ''a -> expectation
    val error: exn -> (unit -> 'a) -> expectation
    datatype expectation = Fail of string * string | Pass
    val falsy: bool -> expectation
    val nearTo: real -> real -> expectation
    val truthy: bool -> expectation
  end
structure Test:
  sig
    val run: testnode -> 'a
    datatype testnode =
        Test of string * (unit -> Expect.expectation)
      | TestGroup of string * testnode list
  end
val describe = fn: string -> Test.testnode list -> Test.testnode
val test = fn: string -> (unit -> Expect.expectation) -> Test.testnode

Usage example:

use "foo.sml";
use "testlib.sml";

infixr |>
fun x |> f = f x

val testsuite =
  describe "Examples" [
    test "foo"
      (fn _ => foo ("foo") |> Expect.equalTo "foo-foo"),
    
    test "bar"
      (fn _ => bar () |> Expect.truthy),
    
    test "something that baz does"
      (fn _ => baz (123) |> Expect.nearTo 123.10),
    
    test "an exception from 'qux'"
      (fn _ => (fn _ => qux (0, 0))) |> Expect.error QuxError),
  ]

val _ = Test.run testsuite

Adding an exercise

The easiest way to start is by running the generator:

bin/generate {{ slug }}

It will create the exercise directory, test and stub files.

Generator

usage: generate [-h] [--force] [--test-only] [--stub-only] [--example-only]
                exercises [exercises ...]

positional arguments:
  exercises

optional arguments:
  -h, --help      show this help message and exit
  --force         Type inference will be disabled and "string" will be
                  assumed. Test cases will need to be modified to match the
                  right data type.
  --test-only     Generate only "test.sml"
  --stub-only     Generate only "<exercise>.sml"
  --example-only  Generate only "example.sml"

Note:

You need Python 3.5+.
It may fail with some exercises. Reasons:
- canonical-data.json does not exist
- type mismatch (in these situation you can use --force option)

In those cases you will have to create the files manually. testlib.sml can be copied from lib/testlib.sml. When in doubt, feel free to open an issue.

In order to generate README.md you will need an up to date copy of problem-specifications. This should be located at the same level as your sml clone. Then you can execute:

bin/fetch-configlet
bin/configlet generate . -o {{ slug }}

Testing

For a single exercise:

If you are at the top level:

make test-{{ slug }}

if you are in exercises/{{slug}}

make -C ../../ test-{{ slug }}

If you want to run all the tests:

make test

Pull request

Do not forget to add your exercise to config.json. Please read this.

joshmhanson/sml