% -*- mode: latex; -*- mustache tags:  
\ifx\wholebook\relax\else

	\documentclass[10pt,twoside,english]{root/support/latex/sbabook/sbabook}
  \usepackage{import}
  \subimport{root/support/latex/}{common.tex}

  \hypersetup{pdfinfo = {
    Title = {{Pharo Mooc}},
    Author = {},
    Keywords = {pharo, smalltalk}}}
  \begin{document}
\fi

\chapter{Developing a simple counter}
To get started in Pharo, we invite you to implement a simple counter by following the steps given below. In this exercise you will learn how to create packages classes, method, instances. You will learn how to define tests and more. This simple tutorial covers most of the important actions that we do when developing in Pharo. 

Note that the development flow promoted by this little tutorial is \textit{traditional} in the sense that you will define a package, a class, \textit{then} define its instance variable \textit{then} define its methods \textit{and} finally execute it. The companion video follows also such programming development flow. Now in Pharo, developers often follows a \textit{totally} different style (that we call live coding) where they execute an expression that raises errors and they code in the debugger and let the system define some instance variables and methods on the fly for them. Once you will have finish this tutorial, you will feel more confident with Pharo and we strongly suggest you to try the other style by following the second video showing such different development practices.
\section{Our use case}
Here is our use case: We want to be able to create a counter, increment it twice, decrement it and check that its value is correct. It looks like this little use case will fit perfectly a unit test - you will define one later. 

\begin{displaycode}{smalltalk}
| counter |
counter := Counter new.
counter increment; increment.
counter decrement.
counter count = 1
\end{displaycode}

Now we will develop all the mandatory class and methods to support this scenario.


\begin{figure}

\begin{center}
\includegraphics[width=1.0\textwidth]{figures/CounterPackageCreated.png}\caption{Package created and class creation template.\label{figpackageCreated}}\end{center}
\end{figure}

\section{Create your own class}
In this part, you will create your first class. In Pharo, a class is defined in a package. You will create a package then a class. The steps we will do are the same ones every time you create a class, so memorize them well. 
\subsection{Create a package}
Using the Browser create a package. The system will ask you a name, write \textcode{Counter}. This new package is then created and added to the list. Figure \ref{figpackageCreated} shows the result of creating such a package.
\subsection{Create a class}
Creating a class requires five steps. They consist basically in editing the class definition template to specify the class you want to create.

\begin{itemize}
\item Superclass Specification. First, you should replace the word \textcode{NameOfSuperclass} with the word \textcode{Object}. Thus, you specify the superclass of the class you are creating. Note that this is not always the case that \textcode{Object} is the superclass, since you may to inherit behavior from a class specializing already \textcode{Object}.
\end{itemize}

\begin{itemize}
\item Class Name. Next, you should fill in the name of your class by replacing the word \textcode{NameOfClass} with the word \textcode{Counter}. Take care that the name of the class starts with a capital letter and that you do not remove the \#sign in front of \textcode{NameOfClass}. This is because the class we want to create does not exist yet, so we have to give its name, and we use a Symbol (a unique string in Pharo) to do so. 
\end{itemize}

\begin{itemize}
\item Instance Variable Specification. Then, you should fill in the names of the instance variables of this class. We need one instance variable called \textcode{count}. Take care that you leave the string quotes!
\end{itemize}

\begin{itemize}
\item Class Variable Specification. As we do not need any class variable make sure that the argument  for the class instance variables is an empty string \textcode{classInstanceVariableNames: ''}.
\end{itemize}

You should get the following class definition.

\begin{displaycode}{smalltalk}
   Object subclass: #Counter
      instanceVariableNames: 'count'
      classVariableNames: ''
      package: 'MyCounter'
\end{displaycode}

Now we should compile it. We now have a filled-in class definition for the class \textcode{Counter}. To define it, we still have to \textit{compile} it. Therefore, select the accept menu item. The class \textcode{Counter} is now compiled and immediately added to the system.

Figure \ref{figclassCreated} illustrates the resulting situation that the browser should show.

\begin{figure}

\begin{center}
\includegraphics[width=1.0\textwidth]{figures/CounterClassCreated.png}\caption{Class created.\label{figclassCreated}}\end{center}
\end{figure}


The tool runs automatically some code critic and some of them are just inaccurate, so do not care for now. 

As we are disciplined developers, we add a comment to \textcode{Counter} class by clicking Comment button. You can write the following comment:

\begin{displaycode}{smalltalk}
Counter is a simple concrete class which supports incrementing and decrementing a counter.
Its API is 
- decrement, increment
- count
Its creation API is message withValue: 
\end{displaycode}

Select menu item 'accept' to store this class comment in the class.
\section{Define protocols and methods}
In this part you will use the browser to learn how to add protocols and methods.

The class we have defined has one instance variable named \textcode{count}. You should remember that in Pharo, (1) everything is an object, (2) that instance variables are private to the object, and (3) that the only way to interact with an object is by sending messages to it.

Therefore, there is no other mechanism to access the instance variable values from outside an object than sending a message to the object. What you can do is to define messages that return the value of the instance variable. Such methods are called \textit{accessors}, and it is a common practice to always define and use them. We start to create an accessor method for our instance variable \textcode{count}.

A method is usually sorted into a protocol. These protocols are just a group of methods without any language semantics, but convey important navigation information for the reader of your class. Although protocols can have any name, Pharo programmers follow certain conventions for naming these protocols. If you define a method and are not sure what protocol it should be in, first go through existing code and try to find a fitting name.
\subsection{Create a method}
Now let us create the accessor methods for the instance variable \textcode{count}. Start by selecting the class \textcode{Counter} in a browser, and make sure the you are editing the instance side of the class (i.e., we define methods that will be sent to instances) by deselecting the Class side radio button.

Create a new protocol by bringing the menu of methods protocol list. Select the newly created protocol. Then in the bottom pane, the edit field displays a method template laying out the default structure of a method. As a general hint, double click at the end of or beginning of the text and start typing your method.
Replace the template with the following method definition:

\begin{displaycode}{smalltalk}
count
   "return the current value of the value instance variable"
   ^ count
\end{displaycode}

This defines a method called \textcode{count}, taking no arguments, having a method comment and returning the instance variable \textcode{count}. Then choose \textit{accept} in the menu to compile the method. You can now test your new method by typing and evaluating the next expression in a Playground, or any text editor.

\begin{displaycode}{smalltalk}
   Counter new count
   > nil
\end{displaycode}

This expression first creates a new instance of \textcode{Counter}, and then sends the message \textcode{count} to it. It retrieves the current value of the counter. This should return \textcode{nil} (the default value for non-initialised instance variables). Afterwards we will create instances with a reasonable default initialisation value.
\subsection{Adding a setter method}
Another method that is normally used besides the accessor method is a so-called setter method. Such a method is used to change the value of an instance variable from a client. For example, the expression \textcode{Counter new count: 7} first creates a new \textcode{Counter} instance and then sets its value to 7:

The snippets shows that the counter effectively contains its value.

\begin{displaycode}{smalltalk}
   | c |
   c := Counter new count: 7.
   c count
   > 7
\end{displaycode}

This setter method does not currently exist, so as an exercise write the method \textcode{count:} such that, when invoked on an instance of \textcode{Counter},  instance variable is set to the argument given to the message. Test your method by typing and evaluating the expression above.
\section{Define a Test Class}
Writing tests is an important activity that will support the evolution of your application. Remember that a test is written \textit{once and executed million} times. For example if we have turned the expression above into a test we could have checked automatically that our new method is correctly working. 

To define a test case we will define a class that inherits from \textcode{TestCase}. Therefore define a class named \textcode{CounterTest} as follows:

\begin{displaycode}{smalltalk}
   TestCase subclass: #CounterTest
      instanceVariableNames: ''
      classVariableNames: ''
      package: 'Counter'
\end{displaycode}

Now we can write a first test by defining one method. Test methods should start with \textit{text} to be automatically executed by the TestRunner or when you press on the icon of the method. Now to make sure that you understand in which class we define the method we prefix the method body with the class name and \textcode{\textgreater{}\textgreater{}}.
\textcode{CounterTest\textgreater{}\textgreater{}} means that the method is defined in the class \textcode{CounterTest}.

Define the following method. It first creates an instance, sets its value and verifies that the value is correct. The message \textcode{assert:} is a special message verifying if the test passed or not.

\begin{displaycode}{smalltalk}
CounterTest >> testCountIsSetAndRead
   | c |
   c := Counter new.
   c count: 7.
   self assert: c count = 7
\end{displaycode}

Verify that the test passes by executing either pressing the icon in front of the method or using the TestRunner available in the Tools menus (selecting your package).
Since you have a first green test. This is a good moment to save your work. 


\begin{figure}

\begin{center}
\includegraphics[width=1.0\textwidth]{figures/CounterAddingRepo.png}\caption{Selecting a new kind of repository to the list of possible places to commit the package.\label{figSelectingARepo}}\end{center}
\end{figure}



\begin{figure}

\begin{center}
\includegraphics[width=1.0\textwidth]{figures/CounterEditingProject.png}\caption{Editing the repository information.\label{figAddingARepo}}\end{center}
\end{figure}

\section{Saving your work}
Several ways to save your work exist. 

\begin{itemize}
\item \textit{Using plain files}. You can save the class or a method by clicking on it and selecting the fileout menu item. You will get a file containing the source code on your hard-disc - This is not the favorite way to save your code. 
\item \textit{Using a version control system}. It is better to use a version control system. In Pharo you can use Monticello and Git (even if it is more for advanced users).
\end{itemize}

In this tutorial we explain the simplest way to get you done. Note that the complete set of Pharo packages is managed via Monticello (which is a distributed versioning control system - there is are chapters in \textbf{Pharo by Example} and \textbf{Deep into Pharo} books \url{http://books.pharo.org}).

Use the \textbf{Monticello Browser} (available in Tools) to save your work. You can save a package locally on your harddisc or on a remote server on the web such \url{http://www.smalltalkhub.com}
\subsection{Saving using Monticello}
Using Monticello you can save your work:

\begin{itemize}
\item \textit{Locally}. You can store your packages in a folder on your disc (use directory as a kind of repository).
\item \textit{Remotely}. Using an account on a free server such \url{http://www.smalltalkhub.com/}. You can save your work and share it with others.
\end{itemize}

Note each time you load or save a package, this package is also be stored on the folder named 'package-cache' on your hard-disc.
\subsubsection{Add a repository.}
Go to \url{http://www.smalltalkhub.com/} and create a member account then register a new project. You get an HTTP entry that refers to your project. Define a new HTTP repository using the Monticello Browser as shown by Figures \ref{figSelectingARepo} and \ref{figAddingARepo}.

Figure \ref{figSelectingARepo} shows that you package is dirty: this is indicated with the little '*' in front of the packages. 

Example. We are saving our examples into a special team named PharoMooc in the the Counter project so the template is the following one 

\begin{displaycode}{smalltalk}
MCHttpRepository
	location: 'http://smalltalkhub.com/mc/PharoMooc/Counter/main'
	user: ''
	password: ''
\end{displaycode}

So the template is the following: 

\begin{displaycode}{smalltalk}
MCHttpRepository
	location: 'http://smalltalkhub.com/mc/YourAccountOrTeamAccount/YourProject/main'
	user: 'YourAccountID'
	password: 'YourAccountPassword'
\end{displaycode}
\subsubsection{Saving your package.}
To save your work, simply select your package and the repository you want to save it to and save it using the Save button. This will open a dialog where you can give a comment, version numbers and blessing. From then on, other people can load it from there, in the same way that you would use cvs or other multi-user versioning systems. Saving the image is also a way to save your working environment, but not a way to version and publish it in a way that can be easily shared.

You can of course both publish your package (so that other people can load it, and that you can compare it with other versions, etc.) and save your image (so that next time that you start your image you are in the same working environment).
\section{Adding more messages}
Before implementing the following messages we define first a test.
We define one test for the method \textcode{increment} as follows:

\begin{displaycode}{smalltalk}
CounterTest >> testIncrement
   | c |
   c := Counter new.
   c count: 0 ; increment; increment.
   self assert: c count = 2
\end{displaycode}

\begin{itemize}
\item Propose a definition for the method \textcode{increment}.
\item Define a test and method for the method \textcode{decrement}.
\item Implement the following methods \textcode{increment} and \textcode{decrement} in the protocol 'operation'.
\item Implement also a new test method for the method \textcode{decrement}
\end{itemize}

\begin{displaycode}{smalltalk}
Counter >> increment
   self count: self count + 1
\end{displaycode}

\begin{displaycode}{smalltalk}
Counter >> decrement
   self count: self count - 1
\end{displaycode}


\begin{figure}

\begin{center}
\includegraphics[width=1.0\textwidth]{figures/CounterClassTestCreated.png}\caption{Class with green tests.\label{figclassTestCreated}}\end{center}
\end{figure}


Run your tests they should pass (as shown in Figure \ref{figclassTestCreated}). Again this is a good moment to save your work. Saving at point where tests are green
is always a good process. 
\section{Better object description}
When you open an inspect (putting a \textcode{self halt} inside a method definition) you obtain an inspector or when you select the expression \textcode{Counter new} and print its result (using the Print it menu of the editor) you obtain a simple string \textcode{'a Counter'}.

\begin{displaycode}{smalltalk}
   Counter new
   > a Counter
\end{displaycode}

We would like to get a much richer information for example knowing the counter value. Implement the following methods in the protocol \textcode{printing}

\begin{displaycode}{smalltalk}
Counter >> printOn: aStream
   super printOn: aStream.
   aStream nextPutAll: ' with value: ', self count printString.
\end{displaycode}

Note that the method \textcode{printOn:} is used when you print an object using print it (See Figure \ref{figBetterDescription}) or click on \textcode{self} in an inspector.


\begin{figure}

\begin{center}
\includegraphics[width=1.0\textwidth]{figures/CounterBetterDescription.png}\caption{Better description.\label{figBetterDescription}}\end{center}
\end{figure}

\section{Instance initialization method}
Right now the initial value of our counter is not set as the following expression shows it.

\begin{displaycode}{smalltalk}
   Counter new count
   > nil
\end{displaycode}

Let us write a test checking that a newly created instance has 0 as a default value.

\begin{displaycode}{smalltalk}
CounterTest >> testValueAtCreationTimeIsZero
   self assert: Counter new count = 0
\end{displaycode}

If you run it, it will turn yellow indicating a failure (a situation that you anticipated but that is not correct) - by opposition to an error which is an anticipated situation leading to failed assertion. 
\subsection{Define an initialize method}
Now we have to write an initialization method that sets a default value of the \textcode{count} instance variable. However, as we mentioned the \textcode{initialize} message is sent to the newly created instance. This means that the \textcode{initialize} method should be defined at the instance side as any method that is sent to an instance of \textcode{Counter} (like \textcode{increment}) and \textcode{decrement}. The \textcode{initialize} method is responsible to set up the instance variable default values.

Therefore at the instance side, you should create a protocol \textcode{initialization}, and create the following method (the body of this method is left blank. Fill it in!).

\begin{displaycode}{smalltalk}
Counter >> initialize
  "set the initial value of the value to 0"
\end{displaycode}

Now create a new instance of class \textcode{Counter}. Is it initialized by default? The following code should now work without problem:

\begin{displaycode}{smalltalk}
    Counter new increment
\end{displaycode}

and the following one should return 2

\begin{displaycode}{smalltalk}
   Counter new increment; increment; count
   > 2
\end{displaycode}

Again save your work before starting the next step.
\section{Define a new instance creation method}
We would like to show you the difference between an instance method (i.e. sent to instances) and a class method (i.e. to a class).
In fact the only difference is the place to define them. An instance method is defined in the instance side of Code Browser while class methods
are defined on the class side (Pressing the button Class). 

Define a different instance creation method named \textcode{withValue:}. This method receives an integer as argument and returns an instance of \textcode{Counter} with the specified value.

Let us define a test:

\begin{displaycode}{smalltalk}
CounterTest >> testAlternateCreationMethod
  self assert: ((Counter withValue: 19) increment ; count) = 20
\end{displaycode}

Here the message \textcode{withValue:} is sent to the class \textcode{Counter} itself.

Your implementation should look like

\begin{displaycode}{smalltalk}
Counter class >> withValue: anInteger
	| c |
	c := self new count: anInteger. 
	^ c 
\end{displaycode}

Note that \textcode{self} in such method refers to the class \textcode{Counter} itself. 
\section{Conclusion}
In this tutorial you learned how to define packages, classes, methods, and define tests.
The flow of programming that we chose for this first tutorial is similar to most of programming languages.
In Pharo you can use a different flow that is based on defining a test first, executing it and when the execution raises error to define the corresponding classes, methods, and instance variable often from inside the debugger. We suggest you now to redo the exercise following the second companion video.



\ifx\wholebook\relax\else
\end{document}
\fi