43.1. Getting started

Using the code browser, define a package named Dice or any name your like.

Object subclass: #Die
	instanceVariableNames: 'faces'
	classVariableNames: ''
	package: 'Dice'

Die >> initialize 
	super initialize.
	faces := 6

TestCase subclass: #DieTest
	instanceVariableNames: ''
	classVariableNames: ''
	package: 'Dice'

DieTest >> testInitializeIsOk
    self shouldnt: [ Die new ] raise: Error

43.2. Rolling a die

To roll a die we will use the method from Number atRandom which draws randomly a number between one and the receiver. For example 10 atRandom draws number between 1 to 10. Therefore we define the method roll as follows.

Die >> roll
    ^ faces atRandom

Now we can create an instance Die new and send it the message roll and get a result. Do Die new inspect and then type in the bottom pane self roll. You should get an inspector like the one shown in Figure 43.1. With it you can interact with a die by writing expression in the bottom pane.

DieTest >> testRolling
	
	| d |
	d := Die new. 
	10 timesRepeat: [ self assert: (d roll between: 1 and: 6) ]

43.3. Instance creation interface

We would like to get a simpler way to create Dice. For example we want to create a 20-faces die as follows: Dice faces: 20. Let us define a test for it.

DieTest >> testCreationIsOk
	
	self shouldnt: [ Die faces: 20 ] raise: Error

We define the class method faces: as follows. It creates an instance then send the message faces: to it and returns the instance.

Die class >> faces: aNumber

	| instance |
	instance := self new.
	instance faces: aNumber.
	^ instance

This method is strictly equivalent to the one below. The trick is that yourself is a simple method defined on Object class. yourself returns the receiver of a message and the use of ; sends the message to the receiver of the previous message (here faces:), therefore yourself is sent to the object resulting from the execution of the expression self new (which returns a new instance of the class Dice).

Die class >> faces: aNumber
	
	^ self new faces: aNumber; yourself

If you execute it will not work since we did not create yet the method faces: this is now the time to define it.

Die >> faces: aNumber

	faces := aNumber

Now your tests should run.

So even if the class Die could implement more behavior, we are ready to implement a dice handle.

43.4. First specification of a dice handle

Let us define a new class DiceHandle that represents a dice handle. Here is the API that we would like to offer for now. We create a new instance of the handle then add some dice to it.

DiceHandle new 
	addDie: (Die faces: 6);
	addDie: (Die faces: 10);
	yourself

Of course we will define a test for this new class. We define the class DiceHandleTest as follow.

TestCase subclass: #DiceHandleTest
	instanceVariableNames: ''
	classVariableNames: ''
	package: 'Dice'

DiceHandleTest >> testCreationAdding

	| handle |
	handle := DiceHandle new 
			addDie: (Die faces: 6);
			addDie: (Die faces: 10);
			yourself.
	self assert: handle diceNumber = 2.

DiceHandleTest >> testAddingTwiceTheSameDice

	| handle |
	handle := DiceHandle new. 
	handle addDie: (Die faces: 6).
	self assert: handle diceNumber = 1.
	handle addDie: (Die faces: 6).
	self assert: handle diceNumber = 2.

43.4.2. Defining the DiceHandle class

This class defines one instance variable to hold dice it contains.

Object subclass: #DiceHandle
	instanceVariableNames: 'dice'
	classVariableNames: ''
	package: 'Dice'

We simply initialize it so that its instance variable dice contains an OrderedCollection.

DiceHandle >> initialize
	super initialize.
	dice := OrderedCollection new.

Then we define a simple method to add a die to the list of dice of the handle.

DiceHandle >> addDie: aDie 
	dice add: aDie

Now you can execute the code snippet and inspect it. You should get an inspector as shown in Figure 43.2

DiceHandle new 
	addDie: (Die faces: 6);
	addDie: (Die faces: 10);
	yourself

Finally we should add the method diceNumber to the DiceHandle class to be able to get the number of dice of the handle. We just return the size of the dice collection.

DiceHandle >> diceNumber  

	^ dice size

Now your tests should run and this is good moment to save and publish your code.

43.5. Improving programmer experience

Now when you open an inspector you cannot see well the dice that compose the dice handle. Click on the dice instance variable and you will only get a list of a Dice without further information.

DiceHandle new 
	addDie: (Die faces: 6);
	addDie: (Die faces: 10);
	yourself

So we will enhance the printOn: method of the Die class to provide more information. Here we simply add the number of faces surrounded by parenthesis.

Die >> printOn: aStream

	super printOn: aStream.
	aStream nextPutAll: ' (', faces printString, ')'

Now in your inspector you can see effectively the number of faces a dice handle has as shown by Figure 43.3 and it is now easier to check the dice contained inside a handle (See Figure 43.4).

43.6. Rolling a dice handle

Now we can define the rolling of a handle of dice by simply summing the dice rolls.

DiceHandle >> roll
	
	| res |
	res := 0.
	dice do: [ :each | res := res + each roll ].
	^ res

Now we can send the message roll to a dice handle.

handle := DiceHandle new 
		addDie: (Die faces: 6);
		addDie: (Die faces: 10);
		yourself.
handle roll

43.7. Role playing syntax

Now we are ready to offer a syntax following practice of role playing game, i.e., using 2 D20 to create a handle of two 20 faces dice. For this purpose we will define class extensions: we will define methods in the class Integer but these methods will be only available when the package Dice will be loaded.

But first let us specify what we would like to obtain by writing a new test in the class DiceHandleTest. Remember to always take any opportunity to write tests. When we execute 2 D20 we should get a new handle composed of two dice and can verify that. This is what the method testSimpleHandle is doing.

DiceHandleTest >> testSimpleHandle

	self assert: 2 D20 diceNumber = 2.

Verify that the test is not working! It is much more satisfactory to get a test running when it was not working before. Now define the method D20 with a category name that is '*Dice' (if you named your package Dice). This method simply creates a new dice handle, add the correct number of dice to this handle and return it.

Integer >> D20
	
	| handle |
	handle := DiceHandle new.
	self timesRepeat: [ handle addDie:  (Die faces: 20)].
	^ handle

Now you test should pass and this is probably a good moment to save your work either by publishing your package to SmalltalkHub and to save your image.

Now we could do the same for the default dice with different faces number: 4, 6, 10, and 20. But we should avoid duplicating logic and code. So first we will introduce a new method D: and based on it we will define all the others

Integer >> D: anInteger
	
	| handle |
	handle := DiceHandle new.
	self timesRepeat: [ handle addDie:  (Die faces: anInteger)].
	^ handle

Integer >> D4
	
	^ self D: 4

Integer >> D6
	
	^ self D: 6

Integer >> D10
	
	^ self D: 10

Integer >> D20
	
	^ self D: 20

We have now a compact form to create dice and we are ready for the last part: the addition of handles.

DiceHandleTest >> testSumming

	| handle |
	handle := 2 D20 + 3 D10.
	self assert: handle diceNumber = 5.

DiceHandle >> + aDiceHandle

	| handle |
	handle := self class new.
	self dice do: [ :each | handle addDie: each ].
	aDiceHandle dice do: [ :each | handle addDie: each ].
	^ handle

43.8. Conclusion

This chapter illustrates how to create a small DSL based on the definition of some domain classes (here Dice and DiceHandle) and the extension of core class such Integer. It shows that in Pharo we can use usual operators to express natural models.