You are currently browsing the tag archive for the ‘dsl’ tag.

My latest objective has been to construct a DSL for asserting whether a chess piece, within the context of a game, can make a particular move. I have managed to construct a syntax that resembles:

pawn canMove Straight towards Black

Some alternative examples are :

pawn canMove Straight by 2 towards Black
pawn canMove Diagonally towards (Black, King)

With this syntax it is possible to construct executable specifications using Specs that read:

"a pawn that has already been moved and is not blocked" should {
    "be able to move one square towards opposite colour" in {
      pawn canMove Straight towards Black must beTrue

Operator notation is what enables the building of this kind of syntax. It is the ability to omit the dot and parentheses on any function call with exactly one parameter. It is not possible to achieve this when there is 2 or more parameters (both dot and parentheses are required) or when there are zero (the parentheses are optional, but the dot is required).

Without operator notation, the initial example above would be written as:


Straight-line movement

In order to facilitate this structure, Piece.canMove(m: Movement) implies an instance of CanMove (a case class). CanMove.towards(o: Orientation) decides whether the move can proceed. Both Straight and Black are case objects.

class Piece(val colour: Colour, val role: Role, val position: Position) {
  def canMove[M >: Movement](m: M): CanMove[M] = CanMove(m, this)

case class CanMove[M >: Movement](m: M, p: Piece) {
  var dist = 1
  def towards(o: Orientation): Boolean = {
    m match {
      case Straight => p.role match {
        case Pawn => dist == 1 && o.equals(opposite of p.colour)
        case _ => false
      case _ => false

At this stage, only the behaviour for “a pawn that has already been moved and is not blocked” has been specified. As such it is a simple case statement. If the movement is Straight and the piece is a Pawn, check that it is trying to move 1 space and that it is moving toward the opposite coloured side.

Diagonal Movement

Queries regarding diagonal movement require additional thought, as the direction is a composite of both Colour (Black or White) and Role with Orientation (Queen or King). In this case, a towards function is provided that takes a Tuple2 of these two parameters.

def towards(o: Tuple2[Colour, Role with Orientation]): Boolean = false

The function currently returns false, because there is no specification written yet that would require it to be true. Following BDD means the simplest possible implementation that would work is in place.

Using a Tuple2 instead of two input parameters permits operator notation to be used. That is, it is a single parameter comprised of two values. Although denoting the tuple does require the use of parentheses and a comma, but I think the effect is still readable.

"a pawn that has already been moved and is not blocked" should {
  "not be able to move diagonally towards black queen" in {
    pawn canMove Diagonally towards (Black, Queen) must beFalse

Movement greater than 1 square

In order to support movement in a direction over multiple squares, the CanMove class is provided a by(distance: Int) function that sets the distance on the instance, and returns the instance again for a chained function call.

def by(distance: Int) = {
  dist = distance

This permits the interspersing of ‘by n‘ as an optional term. On the downside, it also permits the illogical interspersing of multiple calls to ‘by n‘. Such as:

pawn canMove Straight by 1 by 9 by 4 towards Black

The pawn movement specification for this function utilises ScalaCheck to test a range of conditions of n from 2 upwards. This testing tool executes the specification with 100 arbitrary values of n that are 2 or greater.

"a pawn that has already been moved and is not blocked" should {
  "not be able to move more than one square towards opposite colour" in {
    forAll { n: Int => n >= 2 ==>
            (pawn canMove Straight by n towards Black equals false)
    } must pass

Source code

The complete code (as a work in progress) lives on github. I welcome any advice on how to improve the approach I’ve taken.