libs-steptalk/Documentation/Smalltalk.txt

Smalltalk language extensions to NSObjects
------------------------------------------

Contents:
    1. Source
    2. Symbolic Selectors
    3. Iterators and cycles
    4. Exception handling

1. Source
---------

Smalltalk script can be list of methods or just list of statements. List of
statements is like single method without method name.

List of methods
---------------

Source begins with '[|' (left square bracket) and is followed by optional list
of script variables. Methods are separated by '!' and are encoles by ']' (right
square bracket).

Example without vars:
[| 
    main
        self other.
        ^self
    !
    other
        Transcript showLine:'This is other'.
    !
 ]

Example with vars:

[| :var1 :var2

    main
        "Your code here...".
        ^self
    !
    other
        "Your code here...".
        ^self
    !
 ]


Simple script (statements)
--------------------------

Simple script is just list of smalltalk statements. It is like contents of one
method.


Why source begins with '[|' and not just '['? 
---------------------------------------------
Look at this example:

    [one two three]

It has more meanings. It can be:

    - list of methods with one method named 'one'. 'two' is target object and
      'three' is a message.
    
    or
    
    - simple statement with block. 'one' is target object and 'two' and 'three'
      are messages.



2. Symbolic selectors
---------------------

In StepTalk symbolic selectors are mapped to normal selectors.

Comparison operators (NSObject)
-------------------------------


    Symb. sel.     Real sel.
    -------------------------------------
    =              isEqual:
    ==             isSame:
    ~=             notEqual:
    ~~             notSame:
    <              isLessThan:
    >              isGreatherThan:
    <=             isLessOrEqualThan:
    >=             isGreatherOrEqualThan:


Target type    Selector    Argument Type     Real Selector
-----------------------------------------------------------------------
NSArray          @         NSNumber          objectAtIndex:
NSArray          ,         any               arrayByAddingObject:
NSArray          +         any               arrayByAddingObject:
NSMutableArray   +=        any               addObject:
NSMutableArray   -=        any               removeObject:

NSDictionary     @         any               objectForKey:
NSUserDefaults   @         any               objectForKey:

NSString         ,         NSString          stringByAppendingString:
NSString         /         NSString          stringByAppendingPathComponent:
NSString         @         NSNumber          characterAtIndex:
NSMutableString  +=        NSString          appendString:

NSSet            <         NSSet             isSubsetOfSet:
NSMutableSet     +=        any               addObject:
NSMutableSet     -=        any               removeObject:

NSDate           -         NSDate            timeIntervalSinceDate:

NSNumber         +,-,*,/   NSNumber          add:,subtract:,multiply:,divide:



Special selectors to create objects from two NSNumbers

Symb.sel. Real sel.    Result   Methods
-------------------------------------------------------
<>        rangeWith:   range    location, length
@         pointWith:   point    x, y
@@        sizeWith:    size     width, height

Examples:
    str := 'This is string.'.
    substr := str substringWithRange: (8 <> 3)
    range := str rangeOfString: 'str'.
    newRange := ( (range location) <> 6).

3. Iterator and cycles
----------------------
Cycles
------
To create a cycle, you may use whileTrue: or whileFalse: on NSBlock

    conditionBlock whileTrue: toDoBlock.
    
To use a sequence of numbers, you may use to:do: or to:step:do: on NSNumber
    
    min to: max do: block
    min to: max step: step do: block

Array iterators
---------------

Following methods will iterate through all objects in receiver.

Selector     Description
-------------------------------------------------------------------------------
do:          Evaluate block for each object in array and return last evaluated 
             expression
select:      Create new array which will contain those objects from receiver, 
             for which value of block was true
reject:      Create new array which will contain those objects from receiver, 
             for which value of block was false
collect:     Create new array from block return values.
detect:      Return first object for which block evaluation result is true. 
             Othervise return nil.


4. Exception handling
---------------------

If you want to handle an exception, you may do so by using blocks. You send
handler: message to guarded block.

    guardedBlock handler: handlerBlock.
    
If exception occures in guarded block, then handler block is evaluated.