help-PharoSmalltalk.txt

Pharo
-----
http://pharo.org

A clean, innovative, open-source Smalltalk-inspired environment.

Pharo has a simple dynamically-typed object model:
- Everything is an object (an instance of a class).
- Classes are objects too.
- Computation happens only via message sends (and variable assignment).
- There is single inheritance between classes.
- Instance variables are protected.
- Methods are public.
- Blocks are lexical closure a.k.a. anonymous methods.
- Traits are groups of methods that can be reused orthogonally to inheritance.

Pharo is:
- Pure & elegant
- Fun
- Simple
- Highly productive
- Excellent for teaching
- Empowering
- Fully accessible


Learn Pharo
-----------
http://pharo.org
http://pharo.org/documentation
https://github.com/pharo-open-documentation/pharo-wiki
https://pharoweekly.wordpress.com/
https://thepharo.dev

Learn Pharo in Pharo itself by using professor Stef:
	ProfStef go.
	ProfStef next.
	ProfStef previous.

Massive Open Online Course  http://mooc.pharo.org
Pharo Books                 http://books.pharo.org
                            	Pharo by Example
                            	Entreprise Pharo
                            	Deep into Pharo
                            	Dynamic Web with Seaside: http://book.seaside.st
Updated Pharo by Example    https://github.com/SquareBracketAssociates/UpdatedPharoByExample
Numerical Methods           https://github.com/SquareBracketAssociates/NumericalMethods

Screen casts                https://www.youtube.com/channel/UCp3mNigANqkesFzdm058bvw
Presentations               http://www.slideshare.net/pharoproject/
Cheat-sheet                 https://files.pharo.org/media/flyer-cheat-sheet.pdf
Misc Articles               https://medium.com/concerning-pharo
                            https://medium.com/concerning-pharo/elegant-pharo-code-bb590f0856d0


Notes below are primarily learned from these resources.



The Complete Syntax on a Postcard
---------------------------------

exampleWithNumber: x
	"This method illustrates the complete syntax."
	<aMethodAnnotation>

	|y|
	true & false not & (nil isNil)
		ifFalse: [ self halt ].
	y := self size + super size.
	#($a #a 'a' 1 1.0)
		do: [ :each | Transcript
			show: (each class name);
			show: (each printString);
			show: ' ' ].
	^x<y



Comments
--------
"This is a comment in Pharo Smalltalk"


Assignment
----------
:=


Separator
---------
. is a separator (not a terminator).


Variable Declaration
--------------------
| foo |       "Declaration of one variable"
| foo bar |   "Declaration of two variables"



Messages, Selectors, Methods
----------------------------
Selector:  Name of a message.
Message:   Selector with parameter values.
Method:    Code found in class for responding to message.

A method is called by sending a message to an object, the message receiver; the message returns an object. Messages are modeled from natural languages, with a subject, a verb and complements.

There are three types of messages:
- unary,
- binary,
- keyword.


A unary message is one with no arguments:

	Array new.          The message new is sent to the class Array (instance creation).
	2 squared.          The message squared is sent to an integer.
	-3 abs.             The message absolute is sent to an integer.
	#(1 2 3) size.      The message size is sent to an array.


A binary message takes only one argument and is named by one or more symbol characters:

	3 + 4.                The + message is sent to the object 3 with 4 as the argument.
	’Hello’, ’ World’.    The string ’Hello’ receives the message , (comma) with ’ World’ as the argument.


A keyword message can take one or more arguments that are inserted in the message name:

	’Smalltalk’ allButFirst: 5.  Sends the message allButFirst: to a string, with the argument 5 (this returns the string ’talk’).
	3 to: 10 by: 2.              Sends to:by: to 3, with arguments 10 and 2 (this returns an interval (a collection) containing 3, 5, 7 and 9).



Class methods
-------------
Class methods are normal methods.
Most class methods create new instances.
	- but they can be used for other things like parsing.



Message Precedence
------------------
Unary messages are executed first, then binary messages and finally keyword messages:

	Unary > Binary > Keyword


Or more precise:

	Parentheses > Unary > Binary > Keyword, and finally from left to right.


	2 + 3 squared.            Returns 11.
	2 raisedTo: 3 + 2.        Returns 32


Between messages of similar precedence, expressions are executed from left to right:
	-3 abs negated reciprocal.


Use parentheses to change order of evaluation
	(2 + 3) squared.
	(2 raisedTo: 3) + 2.


The rule suffers no exception: Operators are just binary messages with no notion of mathematical precedence.
Traditional precedence rules from mathematics do not apply in Pharo!
Remember that all messages always follow a simple left-to-right precedence rule.
	2 * 10 + 2.
	2 + 2 * 10.
	2 + (2 * 10).


Cascading Messages
------------------
Multiple messages can be sent to the same receiver with ; (semicolon).
; is the cascade operator.

	OrderedCollection new
		add: #abc;
		add: #def;
		add: #ghi.

The value of the whole message cascade is the value of the last message sent.
To return the receiver of the message cascade instead, make sure to send yourself as the last message of the cascade.

    OrderedCollection new
        add: #abc;
        add: #def;
        add: #ghi;
        yourself.


Classes
-------
Object: An instance of some class.
Class:  Defines behaviour of instances.

Classes are defined by sending the message subclass: to the class Object.
Class names start with uppercase.

Object subclass: #Counter
 instanceVariableNames: 'count'

Object subclass: #Point
 instanceVariableNames: 'x y'


A class is an object.
A class is an instance of another class called a metaclass.
A metaclass is just a class whose instances are classes.
Class X is always the unique instance of the class called "X class"
The class called "X class" is automatically created; it is the metaclass.

A class can receive messages.
Method lookup works the same.
Sending a message to a class is handled similarly as sending a message to an instance, because a class is an instance: it is the instance of a metaclass.


Variable Class
--------------
A variable class defines variable size objects.
E.g. Arrays are variable size objects:

	Array new: 10
	> #(nil nil nil nil nil nil nil nil nil nil)

	Array new: 5
	> #(nil nil nil nil nil)


Defined by using message variableSubclass: instead of subclass:

	ArrayedCollection variableSubclass: #Array
		instanceVariableNames: ''
		classVariableNames: ''
		package: 'Collections-Sequenceable-Base'

Instances of a variable class have a variable size (indexed) zone after the named variables.
Only one indexed instance variable per class (always the last one).
First element starts at index 1.

Create Variable Class instances with new: aMaxValue
	myArray := Array new: 4

Access indexed values with at: and at:put:
	myArray at: 1
	myArray at: 2 put: 'yes yes'.

size returns the number of indexed instance variables:
	myArray size


Possible variable classes:
	#variableSubclass:                example: Array
	#variableByteSubclass:            example: ByteString
	#variableWordSubclass:            example: Bitmap

Some methods related to these variable classes:
	isPointers
	isBits
	isBytes
	isFixed
	isVariable

Please note:
- Classes defined using subclass: can have any kind of subclasses.
- Classes defined using variableSubclass: can only have variableSubclass: subclasses



Metaclasses
-----------
Advanced topic, for details see MOOC or Deep Into Pharo.

Metaclasses in seven Points:
1. Every object is an instance of a class.
2. Every class eventually inherits from Object.
3. Every class is an instance of a metaclass.
4. The metaclass hierarchy parallels the class hierarchy.
5. Every metaclass inherits from Class up to Behavior.
6. Every metaclass is an instance of Metaclass.
7. The metaclass of Metaclass is an instance of Metaclass.

Class Object represents the common object behavior:
- Error handling, halting, announcements.
- All classes eventually inherit from Object.

Every class is an instance of a metaclass.
Classes are objects too!
Every class X is the unique instance of its metaclass, called X class.

Metaclasses are automatically created when creating a class.
Metaclass is responsible for creating and initializing a metaclass’s sole instance (a Class).

Where is method new defined?
- When not overridden, sending message new to a class executes method new defined in Behavior.
- The class Behavior is responsible for creating new instances.



Object/Instance Creation
------------------------
The new method is a class method.
When you send the new message to a class, it creates a new instance of that class and returns it.

Sending the messages new or new: to a class:
	Counter new.
	Array new: 6

Sending an instance-creation messages to a class:
	Counter startingAt: 5.

Sending a message to another object:
	10@20                     "Creates a point"
	'Pharo', ' is Cool'       "Creates a string"


"self class" always returns the class of the receiver.
"self class new" returns an instance of the receiver.
"self class new" returns an instance of a potential subclass in case of inheritance.


#TODO, is this correct?
The initialize method is an instance method.
It is called automatically by the new method just after an instance is created.
The purpose of the initialize method is to set up the initial state of the newly created object.


Standard implementation of new is:

    new
        ^self basicNew initialize

#basicNew is a primitive that just creates the object, but does no initialization.
All instance variables will be nil after basicNew.



Class Initialization
--------------------
How and when are classes initialized?
An object is initialized at creation time.
Classes are objects too.
A class is initialized through the class method initialize.
A class is initialized:
- either at load time after its methods are loaded
- or explicitly by the programmer.

Warning:
- Don’t write super initialize in a class initialize method!
- This will initialize superclasses that are already initialized (at load time).



Inheritance
-----------
Inheritance allows a class to refine state and behavior.
A class extends the definition of its superclass.
A subclass can:
- add state and behavior;
- use superclass behavior and state;
- specialize and redefine superclass behavior.
A class has 1 and only 1 superclass.
A class eventually inherits from Object.
Object is the root of most classes.
ProtoObject is Object’s superclass (it is for special purposes).

Inheritance of state is static (i.e. during class creation).
Inheritance of behavior is dynamic (i.e. during execution).

Inheritance of instance variables:
- happens during class definition;
- computed from the class own instance variables and the ones of its superclasses,

Inheritance of behavior:
- happens at runtime;
- the method is searched starting from the receiver’s class then going to the superclass.



Inheritance, Method Lookup, self, super
---------------------------------------
Sending a message is a two-step process:
1. Look up the method matching the message.
2. Execute this method on the receiver.


Method lookup:
- Maps a message to a method.
- Method lookup starts in the class of the receiver
  - if the method is defined in the class, it is returned
  - if the method is not found the search continues in the superclass (it goes up in the hierarchy).


self always represents the receiver of the message.
self in Pharo, this in Java.
The method lookup starts in the class of the receiver.

super refers to the receiver of the message (just like self) !!!
super changes where the lookup starts.
The method lookup starts in the superclass of the class containing the super expression !!!

NOTE this WRONG definition: super looks for the method in the superclass of the receiver’s class.
    So, the key distinction is that super refers to the superclass of the class containing the super
    expression and not necessarily to the superclass of the actual runtime class of the object.
    So, super always refers to the superclass of the class containing the super expression and is
    not dependent on the runtime class of the object.

 So, super refers to the receiver, but the method lookup starts in the superclass of the class
 defining the method.


When no method is found during lookup in the class hierarchy:
- doesNotUnderstand: is sent to the receiver.
- The initial message is passed as parameter.
- When doesNotUnderstand: arrives at Object instance, an error is raised.
- doesNotUnderstand: is a message and any class can implement the corresponding method;
	used for automatic delegation, proxy, distribution.
- When no class redefines doesNotUnderstand: it is executed in Object:
		- It raises a MessageNotUnderstood exception;
		- When not handled, this exception opens a debugger.


Catching MessageNotUnderstood Error:

	[ self sayHi ]
	    on: MessageNotUnderstood
	    do: [ Transcript show: 'Something wrong here' ]



Return Values
-------------
Use the caret ^ to return a value from a method.
The caret ^ always terminates the method.
A method returns self by default (a method with no caret ^ returns self).

A block returns the result of its last expression.



Variables
---------
Lowercase are used for local/private/temporary variables.
Uppercase are used for shared or global variables.

Local variables start with lowercase (temporary variables, instance variables, arguments,...).

	CounterTest >> testIncrement
	 |c|
	 c := Counter new.
	 ...


Shared or global variables start with uppercase (class, class variables).

	Object is a class globally accessible:
	 Object subclass: #Point

	Transcript is an object that is globally accessible (a kind of stdout):
	 Transcript cr.
	 Transcript show: 'hello world'.


Class variables are shared variables:
- Shared by the instances of the class and subclasses.
- Accessible from instance and class methods.
- Start with an uppercase letter.
- Class variables are initialized at the class side.
- Class variables are listed in the classVariableNames section:

		Object subclass: #CombinedChar
		 instanceVariableNames: 'codes combined'
		 classVariableNames: 'Compositions Decompositions Diacriticals'
		 package: 'Kernel−BasicObjects'


Class instance variables:
- A class can have instance variables like any object.
- A class is an instance of a class (its metaclass).
- Accessible from class methods only.
- Start with a lowercase letter.
- A metaclass lists its class instance variables in the instanceVariableNames section:

		RPackageSet class
			instanceVariableNames: 'cachePackages'

- A class instance variable specifies one value for each instance (each class).
- A metaclass has one direct instance: its associated class.
- A metaclass has several indirect instances: the ones of its subclasses.
- Each subclass inherits the variable and has its own value for the variable.


Special variables cannot be changed: true, false, nil self, super, thisContext
	- true, false are the Booleans
		- true is the unique instance of the class True
		- false is the unique instance of the class False

 	- nil is a global and special variable that refers to the only instance of class UndefinedObject.
	- nil is the unique instance of the class UndefinedObject

	- self refers to the receiver of the message (this in Java).
	- super refers to the receiver but the method lookup starts in the superclass of the class defining the method.

	- thisContext refers to the current execution stack (advanced)



Characters
----------
A Character is instantiated using $ operator:
	$A.
	$A class.
	$B charCode.

Unprintable characters:
	Character space.
	Character tab.
	Character cr.

Print all 256 characters of the ASCII extended set:
	Character allByteCharacters.

Code point (Unicode value) of a character:
		$A codePoint.
		$λ codePoint.
		'I love Pharo' collect: #codePoint as: Array.


Strings
-------
A String is a collection of characters, delimited by single quotes.
Use single quotes to create a String object.

	'ProfStef'.
	'ProfStef' size.
	'ProfStef' first.
	'ProfStef' last.
	'abc' asUppercase.
	'abc' asLowercase.
	'Hello World' reverse.

You can access each character using at: message. Index starts at 1, not at 0.
	'ProfStef' at: 1.

String concatenation uses the comma operator:
	'ProfStef' , ' is cool'.

To add a quote in a string just type it twice (escape with '):
	'It''s not correct'

Other ways to create strings:
	12 asString
	12 printString
	String with: $a
	String with: $a with: $b
	#mac asString

String is a collection:
    'Hello there' do: [:each | Transcript show: each ; cr ]

Trim whitespace like spaces and tabs:
	' Hello World ' trim.
	' Hello World ' trimLeft.
	' Hello World ' trimRight.

Remove characters from a string:
    'ProfStef' copyWithout: $f.
    'ProfStef' copyWithoutAll: 'fP'.
    ('ip is it' copyWithout: ' ') reverse capitalized.

Splitting a string on a certain character, for example a space:
    ' ' split: 'eclair au chocolat'
    Character space split: 'eclair au chocolat'
        > an OrderedCollection('eclair' 'au' 'chocolat')

    Character space split: 'A Symbol is a String which is guaranteed to be globally unique'

Splitting a string on a dash:
    $- split: '1969-07-20'
    '-' split: '1969-07-20'
    ('-' split: '1969-07-20') first

Joining an array of strings with a specific character:
    Character space join: #('This' 'is' 'crazy')
    $_ join: #('This' 'is' 'crazy')

    $/ join: ($- split: '1969-07-20') reverse
    '/' join: ('-' split: '1969-07-20') reverse


Collection of lines:
    String>>#lines returns a collection containing substrings separated by \n, \r, or \r\n

    multiLineString lines


Copy and slice strings:
    s := 'abcdefg'.

    s first. "$a"
    s allButFirst.  "bcdefg"

    s last.  "$g"
    s allButLast.  "abcdef"

Pass a number argument to change the number of characters removed/kept:
    s first: 2.  "ab"
    s allButFirst: 2.  "cdefg"

    s last: 2.  "fg"
    s allButLast: 2.  "abcde"

To get the middle of a string use SequenceableCollection>>#copyFrom:to:
    s := 'abcdefg'.
    s copyFrom: 2 to: 6. "bcdef"

To count back from the end of the string use the size selector
    s := 'abcdefg'
    s copyFrom: 2 to: s size - 1


Note:
- Take care with message concatenations. Can generate useless intermediate versions.
- Benchmark it.
- If this is worth, use a stream to avoid creating multiple intermediary strings.

    String streamContents: [ :stream |
	    stream nextPutAll: 'This'; nextPutAll: ' is '; nextPutAll: 'crazy' ]

    String streamContents: [ :stream |
        stream nextPutAll: 'abcdefg';
        space;
        nextPutAll: '123456';
        space.
        '7890' putOn: stream. ].


Symbols
-------
Symbols are unique immutable strings.
A symbol starts with a #: #ProfStef

Two symbols with the same representation points to the same object.
Two strings with the same representation may be different objects depending on compiler optimisations.

Symbols vs. Strings:
- A symbol is a read-only and unique object.
- A string is a mutable object (for now; might change in future Pharo version).
- Symbols are used as method selectors.
- Symbols are good candidates for identity based dictionaries (IdentityDictionary).


There is one and only one Symbol #ProfStef.
There may be several 'ProfStef' String objects.
(Message == returns true if the two objects are the SAME).

'ProfStef' asSymbol.
#ProfStef asString.
(2 asString) == (2 asString).
(2 asString) asSymbol == (2 asString) asSymbol.
(Smalltalk globals at: #ProfStef ProfStef) next.



Numbers, Fractions, Floats
--------------------------
#TODO: =, ~=, ==


Number - Integer
----------------
SmallInteger -> Integer -> Number -> Magnitude

1 class.
1 class maxVal.

9 squared.
5 between: 4 and: 6
1 max: 3.

1 odd.
2 even.
-3 abs.
3 negated.
3 reciprocal.
5 factorial

Integer primesUpTo: 14
(Integer primesUpTo: 14) sum


Integer expressed in binary:
	2r100		"4"
	2r101		"5"


Integer expressed in hexadecimal
	16r7	"7'
	16rA	"10'
	16rF	"15'


Numbers - Fraction
------------------
Fraction -> Number -> Magnitude

1/3.
(1/3) class.          "This is a Fraction"
(1/3) + (4/5).


Number - Real/Float
-------------------
SmallFloat64 -> Float -> Number -> Magnitude

1.5
2.4e1		"24"
2.4e2		"240"
2.4e3		"2400"

(1/3) asFloat.        "This is a float"
Float pi.
355 / 113 closeTo: Float pi



Booleans, Conditions
--------------------
true is the unique instance of class True.
false is the unique instance of class False.

& | not
or: and: 			"lazy evaluation"
xor:
ifTrue:ifFalse:
ifFalse:ifTrue: ...


true
false
false not.
true | false.
true & false.

true or: false.
true and: false.

3 < 10
	ifTrue: [Transcript show: 'Indeed, 3 is less than 10'].

myProtocol
  ifEmpty: [ 'As yet unclassified' ]

self listItems
  ifNotEmpty: [ :aList | aList at: index ]

Notice that when the receiver is not empty we get it as argument (no need to ask it again).



Associations / Pairs
--------------------
An Association defines a key/value pair:
	'January' -> 31.
	('January' -> 31) key.
	('January' -> 31) value.


Teapot configure: { #defaultOutput −> #json. #port −> 8181 . #debugMode −> true }.



Console Output
--------------
Transcript open.
Transcript show: 'Hello '.
Transcript show: 'Pharo'.
Transcript cr.
Transcript clear


Using the cascade operator:

	Transcript
		   show: 'Hello ';
		   show: 'Pharo';
		   cr.


Loops
-----
Loops are high-level collection iterators, implemented as regular methods. Some loops:
  to:do:
  to:by:do:
  timesRepeat:

1 to: 100 do: [:i | Transcript show: i asString; cr].
1 to: 100 by: 3 do: [:i | Transcript show: i asString; cr].
100 to: 0 by: -2 do: [:i | Transcript show: i asString; cr].

3 timesRepeat: [Transcript show: 'Yes yes';cr]


whileTrue:
whileFalse:



Collections
===========
First element is at index 1.
Collections can contain any sort of objects (collections are heterogenous).
Common collections:
- Array 							(fixed size, direct access)
- OrderedCollection 	(dynamically growing)
- Set 								(no duplicates)
- Dictionary					(key-based, aka. maps)


Common messages working on all collections:
1. Creation: with: anElt, with:with:, withAll: aCollection
2. Accessing: size, at: anIndex, at: anIndex put: anElt
3. Testing: isEmpty, includes: anElt, contains: aBlock
4. Adding: add: anElement, addAll: aCollection
5. Removing: remove: anElt, remove: anElt ifAbsent: aBlock, removeAll: aCollection
6. Enumerating: do: aBlock, collect: aBlock, select: aBlock, reject: aBlock, detect: aBlock, ...
7. Converting: asBag, asSet, asOrderedCollection, asSortedCollection, asArray


Collections - Arrays
--------------------
Collections and thus Arrays start at index 1 (so not 0).

#(7 7 3 13).
#(7 'test' 3 'yes yes').
#(2 4 4 4 5 5 7 9) stdev.
#(2 4 4 4 5 5 7 9) average.
#(2 4 4 4 5 5 7 9) - 1.

Array new: 3.
> #(nil nil nil)


(Array new: 3)
	at: 1 put: 'I';
	at: 2 put: 'am';
	at: 3 put: 'crazy';
	yourself.


#('I' 'am' 'crazy') at: 3.

| me |
me := #('I' 'am' 'crazy').
me at: 3 put: 'not crazy'.


Array with: 'I' with: 'am' with: 'crazy'.


Types of arrays:
- Literal array
- Dynamic arrays

Literal array can only contain objects that have a textual (literal) representation: numbers, strings, nil, symbols, boolean
Literal arrays are created at parse time.
Literal arrays are not created using messages.

	Examples:

	#(1 2 3).
	#(1 2 3 #(4 5 6)).
	#(45 'milou' 1300 true #tintin)

	#(1 2 3 #(4 5 6)) size.
	#(1 2 4) isEmpty.
	#(1 2 3) first.
	#(1 2 3) last.
	#(1 2 3) at: 3.


Dynamic arrays are created at runtime using messages.
Literal arrays are created at compile time by the parser when the expression is read and not during the execution.
Dynamic arrays execute expressions.

	Examples:

	Array with: 45 with: 38 with: 'milou' with: 8
	#('hello' 'World') at: 2 put: 'Pharo'; yourself.


Defining dynamic arrays is tedious:
	| array |
	array := (Array new: 2).
	array at: 1 put: 10 @ 10 ; at: 2 put: (Point x: 100 y: 200). array

{ expression1 . expression2 } is syntactic sugar to create dynamic arrays:

	{ (2+3) . (6*6) }.
	{ (2+3) . (6*6) . 'hello', ' Stef'}

	{(10@20) . (100@200)}
	{Point x: 10 y: 20 . Point x: 100 y: 200}


{} executes expressions while #() does not!
() inside a literal array produces a nested literal array!


Three ways to create arrays:
- Literal syntax: #( ) (no message)
- Using messages: Array new: 3, Array with: 45
- Syntactic sugar: Dynamic { . . }


Collections - OrderedCollection
-------------------------------
- Sequenceable
- Growing size
- add:
- remove:
- addFirst:


OrderedCollection new: 3.

OrderedCollection new: 3 withAll: 'a'
> an OrderedCollection('a' 'a' 'a')

OrderedCollection withAll: #(7 7 3 13)
> an OrderedCollection(7 7 3 13)

OrderedCollection new
  add: 56;
  add: 33;
  yourself.


| ordCol |
ordCol := OrderedCollection new.
ordCol add: 'Two'; add: 'Three'; addFirst: 'One'.


Collections - Set
-----------------
- Mathematical set, so no duplicates.
- Growing size.
- Can contain any object including other Sets.
- add:
- remove:


Set newFrom: #(1 2 3).
Set newFrom: {1. 2. 3}.
Set withAll: #(1 2 3).

Set with: 1 with:2 with 3.


#(1 2 3) asSet.
#(1 2 3) as: Set.

{1. 2. 3} asSet.
{1. 2. 3} as: Set.


Set withAll: #(7 7 3 13).
> a Set( 7 3 13).


#(a b c d e f) asSet intersection: #(f d b) asSet


Collections - Dictionary
------------------------
- Key/values.
- Growing size.
- Accessing: at:, at:ifAbsent:, keys, values.
- Changing/adding: at:put:, at:ifAbsentPut:
- Iterating: do:, keysDo:, valuesDo:, keysAndValuesDo:


| days |
days := Dictionary new.
days
	at: #January put: 31;
	at: #February put: 28;
	at: #March put: 31.


| days |
days := { #January -> 31. #February -> 28. #March -> 31} asDictionary.
days at: #February.
days at: #FakeMonth.
days at: #FakeMonth ifAbsent: [0]   "Hmmm, I still get a KeyNotFound in Pharo 8 MOOC..."


days keys.
days values.

days keysDo: [ :key | Transcript show: key; cr ].
days valuesDo: [ :value | Transcript show: value; cr ]
days keysAndValuesDo: [ :k :v | Transcript show: k asString, ' is having ', v asString  , ' days' ; cr].


Collections - Conversion
------------------------
Collections can be converted simply to other collections:
- asOrderedCollection
- asSet
- asArray



Blocks (closures)
-----------------
Blocks are objects containing code that is executed on demand (anonymous functions).
Blocks are anonymous methods that can be stored into variables and executed on demand.
Blocks are the basis for control structures like conditionals and loops.
Blocks are delimited by square brackets: [].
Blocks are executed when they are evaluated.
Block execution returns the value of the last expression.
Blocks may contain temporary variables.
Use blocks with 2 or 3 arguments maximum.
A block encapsulates only one computation.

Blocks look like functions:

	f := [ :x | x * x + 3 ]          "f(x) = x*x+3"
	f value: 2                       "f(2)""


[:x | x * x ] value:12.
[:x :y | x + y] value:3 value:5.
[GTPlayground open] value.
[ProfStef next] value.

|b|
b := [:x | x+2].
b value: 12.


2 = 2
	ifTrue: [Error signal: 'Help'].

#('Hello World' 'I like Pharo') do: [:e | Transcript show: e].



( ) vs. [ ]:
- ( ) just changes the priority of an execution but the program is executed
- [ ] blocks program execution: the program is NOT executed
- ( ) is about changing the order of a computation
- [ ] is freezing the computation and controlling it


Use [ expressions ] when:
- expressions may not be executed at all (if, and, ...)
- expressions may be executed multiple times (while, ...)



Iterators
---------
With iterators we tell the collection (Array, Set, OrderedCollection) to iterate on itself.
As a client we do not have to know the internal logic of the collection.

do:              Iterate and apply the block on each element ('side effect').
collect:         Iterate and collect results of the block evalutation.
select:          Select matching elements (filter).
reject:          Reject matching elements (filter; selects non-matching elements).
detect:          Get first element matching.
detect:ifNone:   Get first element matching or a default value.
includes:        Test inclusion.


NOTE: When a block is just one UNARY message, no block is needed. These are equivalent:

	#(16 11 68 19) select: [ :i | i odd ]
	#(16 11 68 19) select: #odd


#(11 38 3 -2 10) collect: [:each | each abs].
#(11 38 3 -2 10) collect: [:each | each odd].

#(11 38 3 -2 10) select: [:each | each odd].
#(11 38 3 -2 10) select: [:each | each > 10].

#(11 38 3 -2 10) reject: [:each | each > 10].


(1 to: 10) asOrderedCollection collect: [ :i | i squared ].
(1 to: 10) asOrderedCollection collect: #squared.


(1914 to: 1945) select: [:each | Year isLeapYear: each].		"Show the leap years between 1914 and 1945"
(1914 to: 1945) count: [:each | Year isLeapYear: each].			"Count the leap years between 1914 and 1945"


#(11 38 3 -2 10)
	do: [:each | Transcript show: each; cr].

#(11 38 3 -2 10)
     do: [:each | Transcript show: each ]
     separatedBy: [Transcript show: '.'].


#(a b c d e f) includesAll: #(f d b)



To find the first element that matches, use detect:

	#(16 11 68 19) detect: [ :i | i odd ]

To find the first element that matches else return a (default) value, use detect:ifNone:

	#(16 12 68 20) detect: [ :i | i odd ] ifNone: [ 0 ]
	>0


Some other powerful iterators
-----------------------------
anySatisfy:          Tests if one object is satisfying the criteria.
allSatisfy:          Tests if all objects are satisfying the criteria.
reverseDo:           Do an action on the collection starting from the end.
doWithIndex:         Do an action with the element and its index.
pairsDo:             Evaluate aBlock with my elements taken two at a time.
permutationsDo:      xxxx


Iterating two structures use with:do: (requires two structures of the same length):

	#(1 2 3)
		with: #(10 20 30)
		do: [ :x :y | Transcript show: (y * x) ; cr ]


Use do:separatedBy:              <<< #TODO, check

	String streamContents: [ :s |
		#('a' 'b' 'c')
			do: [ :each | s << each ]
			separatedBy: [ s << ', ' ] ]

	> 'a, b, c'



To group elements according to a grouping function use groupedBy:

	#(1 2 3 4 5 6 7) groupedBy: #even
	> OrderedDictionary(false−>#(1 3 5 7) true−>#(2 4 6) )



To remove one level of nesting in a collection use flatCollect:

	#((3 4) (1 2)) flatCollect: [:each | each ]
	> #(3 4 1 2)




Instances
---------
Objects are instances of their class. Usually, we send the message #new to a class for creating an instance of this class.

	SimpleButtonMorph new
		label: 'A nice button';
		openCenteredInWorld.


The message #allInstances sent to a class answers an Array with all instances of this class.

	SimpleButtonMorph allInstances size.


	SimpleButtonMorph allInstances last
		label: 'ProfStef is cooooool !';
		color: Color red.

Delete it and ask the system to clean the memory:

	SimpleButtonMorph allInstances last delete.
	Smalltalk garbageCollect.
	SimpleButtonMorph allInstances size.


Click on the button to go to next lesson:

	SimpleButtonMorph new
		label: 'Go to next lesson';
		target: [ProfStef next.
				   SimpleButtonMorph allInstances last delete];
		actionSelector: #value;
		openCenteredInWorld.



yourself
--------

Object >> yourself
	^ self


|s|
s := Set new.
s add: 2.
s

Equivalent to:

Set new
  add:2;
  yourself


	Note: The method add: returns its argument, not the receiver.
	  Set new add: 2
	  >2
	We get 2 and not the set!


The cascade returns the value of the last message sent to the object.
When creating a new object, after sending several messages to configure it with a cascade,
yourself is the simplest way to get the new object as a result of the whole expression.
Using yourself makes sure the code returns the new instance.



Streams
-------
Streams iterate over a sequence of elements (e.g. collection, file, network).
A stream can read from and write to collections, files and network.
A stream maintains a current position.
The current position separates past from future.
Streams are implemented for example by a.o. an Array and a position.
A stream can help create collections.

When sending readStream or writeStream to an object, always make sure to close the stream. Even better, use auto-closing messages such as readStreamDo: and writeStreamDo:.


Creating:
- anObject readStream
- anObject writeStream
- Collection streamContents: [:stream | ... ]
- ReadStream on: aCollection
- WriteStream on: aCollection

Reading elements:
 - next
 - upTo: anObject
 - upToEnd

Writing elements:
- nextPut: anElement
- nextPutAll: aCollection


Create and read stream:

	| stream |
	stream := #($a $b $c $d $e $f) readStream.
	stream next.
	 > $a
	stream upTo: $d.
	 > #($b $c)
	stream position.
	 >4
	stream upToEnd
	 > #($e $f)


Position in stream:

	stream position.
	"reset postion to 0"
	stream reset.


Create and write stream:

	stream := (Array new: 6) writeStream.
	stream nextPut: 1.
	stream contents.
	 > #(1)
	stream nextPutAll: #(4 8 2 6 7).
	stream contents.
	 > #(1 4 8 2 6 7)


It is not mandatory to reserve elements an array:

	stream := Array new writeStream.
	stream nextPut: 1.
	stream nextPutAll: #(2 3 4 5 6).


Writing to a File:

	stream := 'hello.txt' asFileReference writeStream.
	stream nextPutAll: 'Hello Pharo!'.
	stream close.


Reading from a File:

	stream := 'hello.txt' asFileReference readStream.
	stream next.
	 > $H
	stream next.
	 > $e
	stream upToEnd.
	 > 'llo Pharo!'
	stream close.


Create a collection by writing to a stream:

	stream := OrderedCollection new writeStream.
	stream nextPut: 1.
	stream contents      "Returns a collection with number 1 inside."


Create a collection by writing to a stream (alternative):

	OrderedCollection
		streamContents: [:stream | stream nextPut: 1]



Reflection, Introspection
-------------------------
Introspection is the ability for a program to observe and therefore reason about its own state.

Intercession is the ability for a program to modify its own execution state or alter its own interpretation or meaning.

Accessing and setting object state:
	Object >> instVarAt: aNumber
	Object >> instVarAt: aNumber put: anObject
	Object >> instVarNamed: aString
	Object >> instVarNamed: aString put: anObject

	This VIOLATES ENCAPSULATION !
	But this may be useful for tools and during development.

	aPoint := 5@6.
	aPoint class allInstVarNames.
	aPoint instVarNamed: 'x'.
	aPoint instVarNamed: 'y'.
	aPoint instVarNamed: 'y' put: 66


Accessing the class of an object:

	'hello' class
	(5@6) class
	Smalltalk class
	Class class
	Class class class


Querying the System:

	Number allSuperclasses.
	Number subclasses.
	Number allSubclasses.
	Point  allInstVarNames.
	Point  instVarNames.
	Number selectors.
	Number allSelectors.
	Number selectors select: #isUnary.
	Number respondsTo: #isNumber.
	Number linesOfCode.

	(Number>>#abs) definition.
	(Number>>#abs) comment.

	(True>>#ifTrue:) definition.
	(True>>#ifTrue:) comment.

	Date today inspect.
	Date browse.

	SystemNavigation default browseAllImplementorsOf: #,
	SystemNavigation default browseAllImplementorsOf: #minute


	ctrl-b on selected text (class, object, method)			Class browser
	ctrl-m on selected text (class, object, method) 		Implementors
	ctrl-n on selected text (class, object, method)			Senders


Getting All Instances of a class:
	Dictionary allInstances

Getting All Pointers to an Object; returns all objects that store a reference to anObject:
 anObject pointersTo


Sending a message by its name:

	Object >> perform: aSymbol
	Object >> perform: aSymbol with: arg

	Asks an object to execute a message.
	Normal lookup is performed.

	 5 factorial
	 5 perform: #factorial


Executing a compiled method:

	CompiledMethod >> valueWithReceiver:arguments:

	No lookup performed!

	(Integer>>#factorial)
 		valueWithReceiver: 5 arguments: #()


Inspector on a compiled method:

	(Point >> #degrees) inspect
	(Number >> #abs) inspect



Symmetric Pointer Swapping:
	anObject become: anotherObject

	All the pointers to anObject point now to anotherObject
	And "the inverse" atomically

		| pt1 pt2 pt3 |
		pt1 := 0@0.
		pt2 := pt1.
		pt3 := 100@100.
		pt1 become: pt3.
		self assert: pt2 = (100@100).
		self assert: pt3 = (0@0).
		self assert: pt1 = (100@100)


Asymmetric Pointer Swapping:
	anObject becomeForward: anotherObject

	Swap all the pointers from one object to the other (asymmetric)

		| pt1 pt2 pt3 |
		pt1 := 0@0.
		pt2 := pt1.
		pt3 := 100@100.
		pt1 becomeForward: pt3.
		self assert: pt1 = (100@100).
		self assert: pt1 == pt2.
		self assert: pt2 == pt3.


Changing the Class of an Object
	Class >> adoptInstance: anInstance
	"Change the class of anInstance to me. Returns the class rather than the modified instance"

	Limited reflective feature.
	Target class should have the same format as the original one


Changing Instance Specific Behavior
	primitiveChangeClassTo: anObject
	"Change the class of the receiver into the class of the argument given that the format of the receiver matches the format of the argument's class.""

For example, an Anonymous Classes For Spying (refer MOOC):

	| logClass set |
	logClass := Behavior new.
	logClass superclass: Set;
		setFormat: Set format.
	logClass compile: 'add: anObject
		Transcript show: ''adding '', anObject printString; cr.
		^ super add: anObject'.
	set := Set new.
	set add: 1.
	set class.
	set primitiveChangeClassTo: logClass basicNew.
	set add: 2.


Conclusion for (advanced) reflection:
- Reflection is a solid foundation for innovation and language extensibility.
- Avoid using reflective operations in domain code!
- Understand when you absolutely need reflection.



thisContext
-----------
thisContext is a pseudovariable like self and super.
thisContext refers to the current execution stack (advanced topic).
Returns an object that represents the method activation.
You can walk and change the stack.

The pseudo variable thisContext reifies the execution stack.
- The context that created the current one is accessed by sending message sender to thisContext.
- To access the method, the message method must be sent.


thisContext sender method returns a compiled method. It is used for example in conditional halt implementation:

	Halt class>> if: condition
		"This is the typical message to use for inserting breakpoints during
		debugging.
		The argument can be one of the following:
			- a block: if the Block has one arg, the calling object is bound to that.
			- an expression
	 		- a selector: Halt if found in the call chain"

		LocalRecursionStopper during: [
			condition isSymbol ifTrue: [
				^ self haltIfCallChain: thisContext home sender contains: condition ].
			condition isBlock ifTrue: [
				^ self haltIfBlock: condition withCallingObjectFrom: thisContext home sender].
			condition ifTrue: [self signalIn: thisContext home sender ].
		]

	Halt class>> haltIfCallChain: haltSenderContext contains: aSelector
		| cntxt |
		cntxt := haltSenderContext.
		[ cntxt isNil ] whileFalse: [
			cntxt selector = aSelector ifTrue: [ self signalIn: haltSenderContext ].
			cntxt := cntxt sender ]


Fetching/setting a temporary variable in the calling method:
	thisContext sender tempAt: 1
	thisContext sender tempAt: 1 put: 22



Benchmarking in Pharo
---------------------
Check profiling applications chapter in Deep into Pharo (at http://books.pharo.org).

[ anExpression ] timeToRun
[ anExpression ] bench
TimeProfiler spyOn: [ anExpression ]


Measuring Execution Speed:

	[ 1000 factorial ] timeToRun
	[ 1000 factorial ] bench
	[ 1000 factorial ] benchFor: 2 seconds

	bench by default returns how many times the code can get executed in 5 seconds.


Time Profiler is a sampling-based code profiler.
At regular interval, it take information from the execution stack.

	TimeProfiler
		spyOn: [ 20 timesRepeat:
			[ Transcript show: 1000 factorial printString ] ]



Files (source MOOC)
-------------------
Some standard directories (but still FileLocators)

	FileLocator home.          "User's home directory (~)"
	FileLocator root.          "File system's root (/)"
	FileLocator C.             "Windows C:\"


Path of a directory (returns a string):

	FileLocator home pathString.


Parent of a directory (a FileLocator):

	FileLocator home parent


Children of a directory (array of FileLocators):

	FileLocator home children.


Use message / to build a path (pointing to a FileLocator):

	| home |
	home := FileLocator home.
	home / 'dev'
	(home / 'dev' / 'myhero') pathString

	(home / 'dev') parent
	(home / 'dev') parent pathString


Create directory:

	(home / 'dev' / 'tempDir') isDirectory.
	(home / 'dev' / 'tempDir') ensureCreateDirectory.
	(home / 'dev' / 'tempDir') createDirectory.

	createDirectory
		Verifies that the directory does not exist and only creates if necessary.
		Do not remove files contained if they exist.
		If the parents do not exist return an exception.

	ensureCreateDirectory
		Verifies that the directory does not exist and only creates if necessary.
		Do not remove files contained if they exist.
		Creates the parents if needed.


Delete directory:

	(home / 'dev' / 'tempDir') delete.


Finding children:

	(home / 'dev' / 'tempDir') allChildrenMatching: '*.txt'.

		is equivalent to

	(home / 'dev' / 'tempDir') allChildren
		select: [ :each | each basename endsWith: 'txt' ]



Collecting information about a file:

	| myFile |
	myFile := '/home/eric/dev/tempDir/temp1.txt' asFileReference.
	myFile exists.
	myFile isDirectory.
	myFile isFile.
	myFile basename.
	myFile extension.
	myFile size.
	myFile parent.
	myFile parent pathString.


Reading from a file:

	myFile := '/home/eric/dev/tempDir/temp1.txt' asFileReference.
	myFile exists.
	stream := myFile readStream.
	stream next.
	stream next.
	stream upToEnd.
	stream close.


	myFile := '/home/eric/dev/tempDir/temp1.txt' asFileReference.
	stream := myFile readStream.
	stream contents.
	stream close.


Reading from a file (automatically closing file stream):

	myFile := '/home/eric/dev/tempDir/temp1.txt' asFileReference.
	myFile readStreamDo: [ :stream | stream contents ]


Writing to a file:

	myFile := '/home/eric/dev/tempDir/temp1.txt' asFileReference.
	myFile exists.
	stream := myFile writeStream.
	stream nextPutAll: 'Hello Pharo!'.
	stream close.


Writing to a file (automatically closing file stream):

	myFile := '/home/eric/dev/tempDir/temp1.txt' asFileReference.
	myFile writeStreamDo: [ :stream | stream nextPutAll: 'Hello Pharo World'].


++++
	| file |
	file := '/home/eric/dev/tempDir/temp4.txt' asFileReference.
	(file parent / 'test') writeStream

	file parent parent / 'test'
++++



File Manipulation (source Pharo image)
--------------------------------------

FileSystem is a low-level protocol for interacting with filesystems.
FileSystem instances know two methods that return a Reference object: workingDirectory and root.

FileSystem disk workingDirectory.                  "FileReference on working directory"
FileSystem disk root.                              "FileReference on root"

FileSystem disk workingDirectory files.
FileSystem disk workingDirectory directories.


FileReference provides methods for navigating the filesystem, performing filesystem operations and opening and closing files.
It is the primary mechanism for working with files and directories.


FileLocator refers to a file or directory in relation to a well-known location on the filesystem, called an origin.
When asked to perform concrete operation, I look up the current location of my origin, and resolve my path against it.

FileLocator documents.
FileLocator documents pathString.

FileLocator workingDirectory
FileLocator workingDirectory filesMatching: '*.pdf'

FileLocator desktop.
FileLocator desktop basename.
FileLocator home basename.

FileLocator image.
FileLocator imageDirectory

FileLocator vmDirectory parent pathString
FileLocator vmBinary asAbsolute pathString
FileLocator vmBinary pathString



Exceptions
----------
- Can be resumed, restarted, and signaled as new exception.
- Two important classes:
	- Error
	- Notification
- defaultAction is executed when an exception occurs and it is not trapped.

Types of exceptions:
- Error:          All errors (subscript, message not understood, division by zero
- Notification    Non fatal exceptions (deprecation, warning, timedout)
- Halt:           To stop the execution (and get a debugger).
- UnhandledError: When an error occurs that is not trapped.


Raising an exception:
- Create an instance of exception
- Send it message signal or signal:

		anException signal
		anException signal: aMessage

		Usually classes have a shortcut:

			(Warning new messageText: 'Pay attention') signal
			Warning signal: 'Pay attention'


Handling/catching an exception (= installing an exception handler):

	[ do Something ] on: ExceptionClass do: [ :ex | something ]

	Example, catching an exception:

		[7/0]
			on: ZeroDivide
			do: [ :exception | Transcript show: exception description; cr]


	Example, catching an exception, with return value 0:

		[7/0]
			on: ZeroDivide
			do: [ :exception | Transcript show: exception description; cr. 0]


	Note: The message on:do: must be sent to a block. Otherwise, the error would be triggered before on:do: gets a chance to handle it!


To test that an Exception occurs SUnit offers:
- should:raise:
- shouldnt:raise:

	testNameOfMonth
		self assert: (Date nameOfMonth: 1) equals: #January.
		self
			shouldnt: [ Date nameOfMonth: 2 ]
			raise: SubscriptOutOfBounds.
		self
			should: [ Date nameOfMonth: 13 ]
			raise: SubscriptOutOfBounds.


Exception Sets:

	[ do some work ]
		on: ZeroDivide, Warning
		do: [ :ex | what you want ]

	or, alternatively

	| exceptionSets |
	exceptionSets := ExceptionSet with: ZeroDivide with: Warning.
	[do some work]
		on: exceptionSets
		do: [ :ex | what you want ]


Exception Helpers:

- Message ensure: ensures that an expression is always executed (even if the program fails before).
		[ doSomething ] ensure: [ alwaysExecuteThis ]

- Message ifCurtailed: ensures that an expression is executed only if the program fails or returns.
		[ doSomething ] ifCurtailed: [ onProblem ]


Handling Exceptions (detailed info):
Within an handler [ ... ] on: anExceptionClass do: [ anHandler ], we can:
- Return an alternative result for the protected block (return:)
- Retry the protected block or a different block (retryUsing:)
- Resume the protected block at the failure point (resume:)
- Pass the caught exception to the enclosing handler (pass)
- Resignal a different exception (resignalAs:)


	[ Notification signal. 'Value from protected block' ]
		on: Notification
		do: [ :ex |ex return: 'Value from handler' ]

	> 'Value from handler'


	Warning, Notification and subclasses are resumable.
	Message resume: restores the context and the value returns normally
	as if the notification did not occur:

	[ Notification signal. 'Value from protected block' ]
		on: Notification
		do: [ :ex | ex resume: 'Value from handler' ]

	> 'Value from protected Block'.



Debugging
----------
The system is alive: Communicate with it.

The debugger is your best friend. Don’t be afraid of it.
- communicate with objects of the context
- check state
- send messages to specific objects
- compile code on the fly
- continue without restarting from scratch

Some developers develop a lot in the debugger!


You can set breakpoints too:
	Halt now (or self halt)    Pauses the program and invokes the debugger.

Single-Shot Halt:
	Halt once                   If enabled pauses the program, opens a debugger, disables itself.
                              To enable it: Halt enableHaltOnce

Halt After n Iterations:
	Halt onCount: 10

Conditional Halt:
	Halt if: aSelector          Stops when invoked from a aSelector.
	Halt if: aBlock             Stops if the block evaluates to true.

	Example, method faces will stop only when invoked from printString:
		Dice >> faces
		...
		Halt if: #printString



Thread
------
# java: new Thread (() -> this.doSomething()).start();

[self doSomething] fork



System info
-----------
SmalltalkImage current aboutThisSystem.
SystemVersion current.



Date and Time
-------------
Date today.
Date yesterday.
Date today + 3 weeks.
Date today < Date yesterday.

Time now.
DateAndTime today.



Unit Testing
------------
SUnit is the Unit Tests framework in Pharo.
Extremely simple (4 classes).
Originally developed by Kent Beck.

A test must be implemented:
- in a method whose name has a test prefix
- in a class that subclasses TestCase.

Each method starting with "test" is automatically executed.
The results of the test are collected in a TestResult object.


Example:

	TestCase subclass: #TBPostTest
		instanceVariableNames: ''
		classVariableNames: ''
		package: 'TinyBlog-Tests'


	TBPostTest >> testNewPostVisible
		| post |
		post := TBPost title: 'First Post' text: 'My first tiny post inside Pharo' category: 'Pharo'.
		post beVisible.

		self assert: post title equals: 'First Post'.
		self assert: post text equals: 'My first tiny post inside Pharo'.
		self assert: post date equals: Date today.
		self assert: post category equals: 'Pharo'.
		self assert: post isVisible.


To run a test manually:

	<TestClass> run: #<testCaseMethod>

	TBPostTest run: #testNewPostVisible


Examples of assert/deny statements:

	self assert: mySet size = 1.
	self assert: mySet size equals: 1.
	self assert: anInteger positive.

	self assert: rootEntry isDirectory.
	self deny: rootEntry isFile.

	self assert: anObject equals: anotherObject   "if assert fails the debugger allows to compare the unequal objects."
	self assert: anObject = anotherObject         "in this case apparently not; #TODO; test"
	self deny: anObject ~= anotherObject


To test that an error must be raised:
	should:raise:

	self
		should: [ Date nameOfMonth: 13 ]
		raise: SubscriptOutOfBounds.


To test that an error must not be raised:
	shouldnt:raise:

	self
		shouldnt: [ Date nameOfMonth: 2 ]
		raise: SubscriptOutOfBounds.


Test fixture:
- setUp and tearDown messages.
- Executed systematically before and after each test run.
- setUp allows us to specify and reuse the context.
- tearDown to clean after.


- A TestCase represents one test.
- A TestSuite is a group of tests.
- A TestResult represents the test execution results.
- A TestResource is an object which is needed by a number of Test Cases and whose instantiation is so costly in terms of time or resources that it becomes advantageous to only initialize it once for a Test Suite run.
- A TestResource is invoked once before any test is run.


NOTE: There exist libraries for mocking for example BabyMock.



Encoding/Decoding
-----------------
Convert String to ByteArray
	'éèç' utf8Encoded.
	'éèç' encodeWith: #latin1.

Decode ByteArray to String
	#[72 101 108 108 111] utf8Decoded.
	#[72 101 108 108 111] decodeWith: #latin1.



ZnClient, Zinc HTTP Client
--------------------------
ZnClient, a full featured HTTP client.
An object to build, execute and process HTTP client requests.
Part of Zinc HTTP Components.

Some examples:

	ZnClient new
		get: 'http://zn.stfx.eu/zn/numbers.txt'.

	ZnClient new
		url: 'http://pharo.org';
		get.

	ZnClient new
		get: 'http://pharo.org'.


An explicit constructed HTTP request:

	ZnClient new
		systemPolicy;
		accept: ZnMimeType textPlain;
		http;
		host: 'zn.stfx.eu';
		path: 'zn/numbers.txt';
		contentReader: [ :entity | entity contents lines collect: [ :each | each asNumber ] ];
		ifFail: [ :exception | self inform: 'I am sorry: ', exception printString ];
		get.



ZnEasy, HTTP Client
-------------------
A simplified HTTP client for occasional use.
It uses ZnClient.
For most requests it returns a response object.

	ZnEasy get: 'http://zn.stfx.eu/zn/small.html'.


For a couple of messages, it returns an image Form:

	ZnEasy getGif: 'http://zn.stfx.eu/zn/Hot-Air-Balloon.gif'

	ZnEasy getPng: 'http://pharo.org/files/pharo.png'.

	ZnEasy getJpeg: 'http://stfx.eu/sun-fire-x2100.jpg'.



| url |.
url := 'http://pharo.org/web/files/pharo.png'.
(ZnEasy getPng: url) asMorph openInWorld.
(ZnEasy getPng: url) asMorph openInWindow


| anEmail md5Email url |.
anEmail := 'Stephane.Ducasse@inria.fr' trimBoth asLowercase.
md5Email := (MD5 new hashMessage: anEmail) hex.
url := 'http://www.gravatar.com/avatar/' , md5Email , '.jpg'.
(ZnEasy getJpeg: url) asMorph openInWorld.



ZnUrl
-----
ZnUrl, an implementation of an interpreted URL/URI.
URLs are used to describe/identify resources,
Part of Zinc HTTP Components.


Creating a ZnUrl:

	'http://www.pharo.org' asUrl.
	'http://www.pharo.org' asZnUrl.

	ZnUrl fromString: 'http://www.pharo.org'.
	ZnUrl fromString: 'http://www.google.com/search?q=Smalltalk'.
	ZnUrl fromString: 'www.example.com' defaultScheme: #http

  ZnUrl new
    scheme: #https;
    host: 'encrypted.google.com';
    addPathSegment: 'search';
    queryAt: 'q' put: 'Smalltalk';
    yourself.


Manipulating a ZnUrl:

  'http://www.google.com/?one=1&two=2' asZnUrl
    queryAt: 'three' put: '3';
    queryRemoveKey: 'one';
    yourself.


Convenience method #retrieveContents to download the resource a ZnUrl points to:

	'http://www.pharo.org' asUrl retrieveContents.
	'http://www.pharo.org' asZnUrl retrieveContents.

  'http://zn.stfx.eu/zn/numbers.txt' asZnUrl retrieveContents.



ZnServer, HTTP Server
---------------------

(ZnServer startDefaultOn: 8080)
  onRequestRespond: [ :request |
    ZnResponse ok: (ZnEntity with: DateAndTime now printString) ]

Go to http://localhost:8080 to see the current date and time



Seaside
-------
A Web Framework.

Seaside               http://www.seaside.st
Seaside book          http://book.seaside.st
                      https://github.com/SquareBracketAssociates/DynamicWebDevelopmentWithSeaside
Seaside tutorial      http://www.swa.hpi.uni-potsdam.de/seaside/
Seaside tutorial      http://seaside.gemtalksystems.com/tutorial.html
TinyBlog tutorial     https://lms.fun-mooc.fr/asset-v1:inria+41024+session01+type@asset+block/TinyBlog-EN.pdf


Define reusable and stateful components.
Use a DSL for rendering components into HTML.
Compose components:
- Build coarser-grained components by encaspulation.
- Schedule components with call: and answer: messages.
A web application is just a root component.
Debug your application on the fly.
Use metadata to generate forms.

A component is:
- an instance of a subclass of WAComponent
- a reusable and stateful part of a Web page
- rendered in HTML

A Web application has a root component.
Register web application component by:

	WAAdmin register: WACounter asApplicationAt: 'counter'.


Example WACounter component:

	WAComponent subclass: #WACounter
		instanceVariableNames: 'count'
		classVariableNames: ''
		package: 'Seaside−Examples−Misc'.

	WACounter >> initialize
		super initialize.
		count := 0

	WACounter >> increase
		count := count + 1

	WACounter >> decrease
		count := count − 1


Components are converted into valid HTML by method renderContentOn:
Seaside sends this message automatically to components.
renderContentOn: has a parameter named html (WAHtmlCanvas).
html defines a DSL like API to generate valid HTML.
The canvas, html, is responsible for drawing components.


	WACounter >> renderContentOn: html
		html heading: count.
		html anchor callback: [ self increase ]; with: '++'.
		html space.
		html anchor callback: [ self decrease ]; with: '−−'


A counter dealing with browser back button.
Declare the component state to be preserved:

	WACounter >> states
		^ Array with: self


Example of callback with a user value

Greeter >> renderContentOn: html
	html form: [
		html text: 'Username:'.
		html textInput
			callback: [ :value | username := value ].
		html submitButton
			callback: [ self inform: 'Hi ', username ];
			text: 'Say Hello'. ].



Generating a Title:

	<div id="title">Title</div>

	html div id: 'title'; with: 'Title'


Generating a List:

	html div id: 'list';
		with: [
			html span class: 'item'; with: 'Item 1'.
			html span class: 'item'; with: 'Item 2' ]

	<div id="list">
		<span class="item">Item 1</span>
		<span class="item">Item 2</span>
	</div>


Generating a List with a Loop:

	html unorderedList
		id: 'list';
		with: [
			1 to: 5: do: [ :i |
				html listItem
					class: 'item';
					with: 'Item ', i asString ]]

	<ul id="list">
		<li class="item">Item 1</li>
		<li class="item">Item 2</li>
		<li class="item">Item 3</li>
		<li class="item">Item 4</li>
		<li class="item">Item 5</li>
	</ul>


	html unorderedList
		id: 'list';
		with: [
			1 to: 5 do: [ :i |
				html listItem
					class: 'itemodd' if: i odd;
					class: 'itemeven' if: i even;
					with: 'Item ', i asString ]]

	<ul id="list">
		<li class="itemodd" >Item 1</li>
		<li class="itemeven">Item 2</li>
		<li class="itemodd" >Item 3</li>
		<li class="itemeven">Item 4</li>
		<li class="itemodd" >Item 5</li>
	</ul>



Twitter Bootstrap, Rendering Twitter Alerts:

	renderExampleOn: html
		html heading level: 2; with: 'Examples'.
		html tbsAlert
			beSuccess;
			with: [ html strong: 'Well done!'. html text: ' You successfully read this important alert message.' ].
		html tbsAlert
			beInfo;
			with: [ html strong: 'Heads up!'. html text: ' This alert needs your attention, but it''s not super important.' ].


Twitter Bootstrap, Rendering Twitter Buttons:

	renderExampleOn: html
		html tbsButtonGroup: [
			html tbsButton beDefault; with: 'Left'.
			html tbsButton beDefault; with: 'Middle'.
			html tbsButton beDefault; with: 'Right' ].


Implement a Counter using Twitter Bootstrap:

	Subclass WACounter:

		WACounter subclass: #WATwitterCounter
			instanceVariableNames: ''
			classVariableNames: ''
			package: 'Seaside−Examples−Misc'

	Use JQuery and Bootstrap libraries:

		WATwitterCounter class >> initialize
			| app |
			app := WAAdmin register: self asApplicationAt: 'twittercounter '.
			app
				addLibrary: JQDeploymentLibrary;
				addLibrary: TBSDevelopmentLibrary

	Redefine renderContentOn:

		WATwitterCounter >> renderContentOn: html
			html tbsContainer: [
				html form: [
					html tbsButtonGroup beSmall; with: [
						html tbsButton beDefault; callback: [ self increase ]; with: '+'.
						html tbsButton beDefault; callback: [ self decrease ]; with: '−' ].
						html space; tbsBadge: self count ] ]

	Apply your own css rules:

		WATwitterCounter >> renderContentOn: html
			html tbsContainer: [
				html form: [
					"..."
					html space.
					html tbsBadge
						class: 'odd' if: self count odd;
						with: self count ] ]

		WATwitterCounter >> style
			^ '.odd { color: red; }'



Three mechanisms to reuse components:
- Components aggregation
- The call: / answer: mechanism
- Definition of workflows (Task)


Component aggregation: How to compose components?
With a composite:
- Stores subcomponents in an instance variable (e.g. a collection of counters).
- Sends render: to subcomponents in its renderContentOn: method.
- Redefines children to return the collection of its subcomponents.

	Example, aggregating the same subcomponents:

		WAExampleComponent subclass: #WAMultiCounter
			instanceVariableNames: 'counters'
			classVariableNames: ''
			package: 'Seaside−Examples−Misc'.

		WAMultiCounter >> initialize
			super initialize.
			counters := (1 to: 5) collect: [ :each | WACounter new ].

		WAMultiCounter >> children
			^ counters

		WAMultiCounter >> renderContentOn: html
			counters do: [ :each | html render: each ]


	Example, aggregating different subcomponents:

		WAExampleComponent subclass: #MyApp
			instanceVariableNames: 'children'
			classVariableNames: ''
			package: 'Seaside−Examples−Misc'.

		MyApp >> initialize
			super initialize.
			children := { Greeter new. WATwitterCounter new. WACounter new }.

		MyApp >> children
			^ children

		MyApp >> renderContentOn: html
			children
				do: [ :each | html render: each ]
				separatedBy: [ html line ]


	Example, rendering only one subcomponent

		MyApp >> initialize
			"..."
			selectedChild := children first

		MyApp >> renderContentOn: html
			self renderMenuOn: html.
			html render: selectedChild

		MyApp >> renderMenuOn: html
			html unorderedList: [
				self children do: [ :child |
					html listItem: [
						html anchor
							class: 'active' if: child = selectedChild;
							callback: [ selectedChild := child ];
							with: child className ]]]



The call: / answer: mechanism:
- When a component wants to be replaced by another component, it has to send the message call: to itself with the replacement component as parameter.
- When a component terminates its job, it has to send the message answer: to itself with the returned value as argument.

		WATwitterCounter >> renderContentOn: html
			"..."
			html tbsButton
				beDefault;
				callback: [ self setCountToUserValue ];
				with: 'Set Value'
			"..."

		WATwitterCounter >> setCountToUserValue
			| webDialog newCounterValueByUser |
			webDialog := WAInputDialog new
				addMessage: 'Enter a new value for the counter:';
				default: '0';
				label: 'Ok';
				yourself.
			newCounterValueByUser := self call: webDialog.      <<<<< The call part
			count := newCounterValueByUser asNumber

		WAInputDialog:
		- is a reusable component
		- it answer: a result


		WAInputDialog >> renderContentOn: html
			html form
				defaultAction: [ self answer: value ];
				with: [
					html div: [
						html textInput on: #value of: self.
						html space.
						html submitButton
							callback: [ self answer: value ];           <<<<< The answer part
							text: self label ] ]



Definition of workflows (Task)
- By tasks
- Tasks are simple components:
	- No UI part (i.e. no renderContentOn:)
	- Orchestrating several components
		- implemented by request: and inform:
		- use call:/answer: behind the scene


		Example, a simple web task

			WATask subclass: #Adder
				instanceVariableNames: ''
				classVariableNames: ''
				package: 'SeaExample'

			Adder >> go
				| value1 value2 |
				value1 := self request: 'first number'.                <<<<< request
				value2 := self request: 'second number'.
				self inform: value1 asNumber + value2 asNumber         <<<<< inform

			WAAdmin register: self asApplicationAt: 'Adder'.


		How is request: implemented?
		request: uses call: / answer: on a WAInputDialog

			WAComponent >> request: aRequestString label: aLabelString default: aDefaultString onAnswer: aBlock
				"Display an input dialog with the question aRequestString,
				 the button label aLabelString and the default string aDefaultString.
				 Passes the answer into aBlock."

				self
					call: (WAInputDialog new
						addMessage: aRequestString;
						default: aDefaultString;
						label: aLabelString;
						yourself)
					onAnswer: aBlock

		How is inform: implemented?
		inform: uses call: / answer: on a WAFormDialog

			WAComponent >> inform: aString onAnswer: aBlock
				"Display a dialog with aString to the user until he clicks the ok button.
				Continue by evaluating aBlock."

				self
					call: (WAFormDialog new
						addMessage: aString;
						yourself)
					onAnswer: aBlock


Summarizing, Seaside provides:
- Stateful components
- Components composition (children)
- Components scheduling using call: / answer:
- Tasks to encapsulate workflows

Moreover:
- No manual request parsing
- No request routing
- No hardcoding of next page
- No XML configuration files



Forms Report Builder
-------------------
Magritte:
- Meta-description framework.
- Write descriptions for your data.
- Describe once, generate many times.
- Use these descriptions:
	- to generate HTML forms.
	- to generate reports, etc.
	- to validate input/objects/databases.
- No more manually created forms.
- Seaside component automatic generation.



Persistence
-----------
Voyage framework:
- API for NoSQL databases
- MongoTalk, Riak

Garage framework:
- API for Relational databases
- Postgres, mysql, sqlite, opendbx


Voyage
------
Object-Document Mapper for MongoDB
MongoDB is an open-source NoSQL Object Database
MongoDB is cocument oriented,
Voyage Features:
- Simple
- Ensure object identity
- Provide error-handling
- Implement a connection pool


Setting a In Memory connection (for prototyping; later you can easily switch to a MongoDB):
	| repository |
	repository := VOMemoryRepository new.
	repository enableSingleton.


Setting a connection for a real MongoDB:
	| repository |
	repository := VOMongoRepository
		host: 'localhost'
		database: 'demo'.
	repository enableSingleton.


Example:
#TODO
Hero-1--*-Power

Object subclass: #Power instanceVariableNames: 'name' classVariableNames: '' package: 'SuperHeroes'. Power>>name ^ name Power>>name: aString name := aString


A Voyage developer needs to declare which classes are database documents. This is done by implementing the class method isVoyageRoot to a model class.

 When an object is ready to be saved in a Voyage database, it is necessary to send it the save message.



Teapot, Web Framework
---------------------
Teapot is micro web framework for Pharo Smalltalk on top of the Zinc HTTP components.

Teapot source and documentation:	https://github.com/zeroflag/Teapot


Example of a simple HTTP Teapot server running on (default) port 1701 with one route (for welcome):

		Teapot on
		    GET: '/welcome' -> 'Hello World!';
		    start.

		Do it and view it at: http://localhost:1701/welcome


Please note: Normally, the first letter of a method name (and corresponding message) should be lower case, that's the recommended naming scheme.
In this case, the author of Teapot decided to ignore this scheme to better reflect the HTTP protocol where verbs (such as GET, POST, PUT and DELETE) are typically written uppercased.


"The Teapot HTTP server"
books := Dictionary new.
teapot := Teapot configure: { #defaultOutput −> #json. #port −> 8181 }.
teapot
 GET: '/' −> '<h1>A simple book server</h1>';output: #html;
 GET: '/books' −> books;
 GET: '/books/<id:IsInteger>'
 	−> [ :request | books at: (request at: #id) asString];
 POST: '/books/<id>'
 	−> [ :request | | book |
 			book := { 'author' −> (request at: #author). 'title' −> (request at: #title) } asDictionary.
 			books at: (request at: #id) put: book ];
 start.


"Add a book via HTTP client"
ZnClient
 new url: 'http://localhost:8181/books/1';
 formAt: 'author' put: 'van Caekenberghe et al';
 formAt: 'title' put: 'Enterprise Pharo';
 post.


"Get a book via HTTP client"
ZnClient new
 url: 'http://localhost:8181/books/1';
 get.



Tealight
--------
https://github.com/astares/Tealight

Tealight is a project defining a few extensions to the Teapot framework to make the (tea) time you spend with the Pharo Teapot system even easier.



Common Pharo Coding Errors
--------------------------
- Missing Period; separate instructions with period.
  Example of symptom: MessageNotUnderstood exception regarding message self

- Missing brackets. Keyword messages are built out of fragments.
  The message is the longest sequence of fragments.
  Use parentheses to delimit multiple keyword messages
  Symptom: Error: Message includes:ifTrue: does not exist
           Error: Message assert:includes: does not exist

- Forgotten yourself. Send yourself after a sequence of messages if you want the receiver.
  Symptom: you get an argument value, instead of the (created) object.

- Uninitialized variable.
  Symptom: Error: nil does not understand <message:>

- Using class True/False instead of instance true/false.
  Symptom: Error: Class True does not understand ifFalse:

- Forgetting to return the result.
  In a method, self is returned by default.
  Do not forget the caret ^ to return something else.

- Infinite loops in overridden methods.
  Use super (instead of self) in overridden methods.
  Symptom: Error: System is frozen



Anti If Campaign
----------------
Branching (with if) based on the type of an object is bad:
- Adding a new type requires modifying all such code.
- Methods will become very long and full of details.
- Send messages instead.
- A message acts as a better if!
- Do not return nil. nil forces every client to check for nil.
- Avoid error codes because they require if in clients.
- When possible, replace if by polymorphic objects:
	- when returning a collection, return an empty one.
	- when returning a number, return 0.
- For exceptional cases, replace nil by exceptions.


Bad:

	Main >> showHappiness: animal
		animal isDog
			ifTrue: [ animal shakeTail ].
		animal isDuck
			ifTrue: [ animal quack ].
		animal isCat
			ifTrue: [ animal miaow].

Good:

	Dog >> showHappiness
		self shakeTail
	Duck >> showHappiness
		self quack
	Cat >> showHappiness
		self miaow



Avoid Null Checks
-----------------
- Avoid null checks, return polymorphic objects instead.
- Initialize your variables.
	- By default instance variables are initialized with nil.
- Use lazy initialization if necessary.
	-  You can defer initialization of a variable to its first use
- Sometimes you have to check before doing an action if you can, turn the default case into an object.
- If you can, create objects representing default behavior.
- Use NullObject:
	- A null object proposes a polymorphic API and embeds default actions/values.
	- Woolf, Bobby (1998). "Null Object". In Pattern Languages of Program Design 3. Addison-Wesley.



Template Methods
----------------
A template method sends messages to self for subclasses to adapt its behavior.
The variation points are called hook methods.
A template Method is a very common design pattern.
A template method specifies a skeleton.
The skeleton has hooks, i.e., places to be customized.
Hooks may or may not have a default behavior.


Copy is a template method.

	Object Copy:

		Object >> copy
			"Answer another instance just like the receiver. Subclasses typically override postCopy. Copy is a template method in the sense of Design Patterns. So do not override it. Override postCopy instead. Pay attention that normally you should call postCopy of your superclass too."
			^ self shallowCopy postCopy

		Object >> shallowCopy
			"Answer a copy of the receiver which shares the receiver's instance variables. Subclasses that need to specialize the copy should specialize the postCopy hook method."
			<primitive: 148> ...


	Default hook:

		Object >> postCopy
			"I'm a hook method in the sense of Design Patterns TemplateHook/Methods. I'm called by copy. self is a shallow copy, subclasses should copy fields as necessary to complete the full copy"
			^ self


	Example of postCopy refinement:

		Collection subclass: #Bag
			instanceVariableNames: 'contents'
			classVariableNames: ''
			package: 'Collections−Unordered'

		Bag >> postCopy
			super postCopy.
			contents := contents copy



printString is Another Template Method:

	printString
		"Answer a String whose characters are a description of the receiver.
		If you want to print without a character limit, use fullPrintString."
		^ self printStringLimitedTo: 50000

	printStringLimitedTo: limit
		"Answer a String whose characters are a description of the receiver.
		If you want to print without a character limit, use fullPrintString."
		^self printStringLimitedTo: limit using: [:s | self printOn: s]


	Default hook is printOn:

		printOn: aStream
			"Append to the argument, aStream, a sequence of characters that
			identifies the receiver."

			| title |
			title := self class name.
			aStream
				nextPutAll: (title first isVowel ifTrue: ['an '] ifFalse: ['a ']);
				nextPutAll: title


		Example print results:

			Node new
			> a Node

			Apple new
			> an Apple


	Example printOn redefinition in class False:

		False >> printOn: aStream
			aStream nextPutAll: 'false'

		Print result:

			true not
			> false



Collection>>detect:ifFound:ifNone: and Collection>>collect: are template methods because each one sends to self the message do: and Collection>>do: is abstract. For the same reason, Collection>>addAll: is a template method.


Collection>>do: and Collection>>add: are abstract methods.



Abstract Base Class
-------------------
In Pharo an abstract method is defined by sending the message subclassResponsibility to self.
These methods have no behavior on their own.
If executed, an abstract method throws an exception.

method
	self subclassResponsibility



Singleton Design Pattern
------------------------
Enforce that a class has only one instance.
A solution: Keep the instance in a variable of the class.

Singleton with a class instance variable:

		WebServer class
			instanceVariableNames: 'uniqueInstance'

		WebServer class >> new
			self error: 'Can''t create a new instance'

		WebServer class >> uniqueInstance
			^ uniqueInstance
				ifNil: [ uniqueInstance := super new ]

		Consequence:
		- Each subclass has its own value for uniqueInstance.
		- Each subclass of WebServer has its own singleton.


Singleton with a class variable:

		Object subclass: #WebServer
			instanceVariableNames: ''
			classVariableNames: 'UniqueInstance'
			package: 'Web'

		WebServer class >> new
			self error: 'Can''t create a new instance'

		WebServer class >> uniqueInstance
			^ UniqueInstance
				ifNil: [ UniqueInstance := super new ]

		Consequence: Only one singleton for the complete class hierarchy (class variable values are shared)



Note this refactoring
---------------------
Before:

	Node >> averageRatio
		^ 55

After:

	Node >> averageRatio
		^ averageRatio ifNil: [ self defaultAverageRatio ]

	Node >> defaultAverageRatio
		^ 55

	Node >> averageRatio: aNumber
		averageRatio := aNumber


Advantage:
- Subclasses can override the value class.
- Users can set the value.



Misc
----
MenubarMorph reset.       "hdpi displays; resets the menubar when you've adjusted the scale factor and/or font sizes"

GTPlayground open.        "Open a playground"
Workspace open.           "Open a workspace"

'Hello World' asMorph openInWindow .

Color red
Color purple
Color r:1 g:0 b:0.



Misc - Calculating a Sum
------------------------

Iterate on collection:

	sum := 0.
	#(21 23 53 66 87) do: [:each | sum := sum + each].


Iterate on collection using inject (that initializes sum value):

	#(21 23 53 66 87) inject: 0 into: [ :sum :each |  sum + each ].


For sure not like this:

	sum := 0.
	numbers := #(21 23 53 66 87).
	i := 1.
	[i <= numbers size]
		whileTrue: [sum := sum + (numbers at: i). i := i + 1 ].



Misc - Calculating Standard Deviation
-------------------------------------
| array |
array := #(2 4 4 4 5 5 7 9).
((array - array average) squared sum / (array size - 1)) sqrt

[ :input | ((input - input average) squared sum / (input size - 1)) sqrt ] value: #(2 4 4 4 5 5 7 9)

#(2 4 4 4 5 5 7 9) in: [ :input | ((input - input average) squared sum / (input size - 1)) sqrt ]

#(2 4 4 4 5 5 7 9) stdev



Misc - Regex
------------
Basic grep on a single file:
- The pattern String is converted to an object that knows how to match lines.
- The file is opened by taking its contents and converting it to lines which are selected when they match.


'^.*.jpg' asRegex in: [ :regex |
  '/tmp/foo.txt' asFileReference contents lines
    select: [ :line | regex matches: line ] ]


Docker
------
https://thepharo.dev/2021/02/24/running-pharo-9-in-docker/


Morphic Halo
------------
The Morphic Halo is a user interface component in the Morphic graphical user interface.
It provides a set of interactive controls and handles that can be displayed around a Morph (a graphical object).
It enables various operations and manipulations on that Morph.

Activate the Halo: Alt-Shift or Fn-Shift and click on any element on the screen.


MOOC - Todo
-----------
4.11 Voyage summary, see #TODO.

Exercises/challenges Todo:
	2.14.3.[Mini-project] Chap.3 TinyBlog: Extending and Testing the Model
	3.14.2 challenge 2
	4.12 - 4.14
	5.11, 5.12
	6.10, 6.11