Bumping the version

principles
- statically typed
  - Type information is known at compile time and in some circumstances given to the runtime for reflection; though it's rarely needed as compile time reflection provides almost all the same benefits.
- compile time reflection
  - When specifying a type for a variable or a parameter the compiler will resolve that type at compile time by executing it as if it were code. It runs within the scope of the imports allowing a layering of compilation. This allows libraries to generate types and methods and effectively act like macros without introducing more syntax for macros. It also allows compile time constants to be then/else tested.
- memory management
  - All memory management is manual and explicit. This isn't as onerous as a Smalltalk developer might at first think. With the use of allocation arenas and the magic runtime context variable almost all memory management seems to melt away.
- runtime context
  - All message sends, unless explicitly declared not to, accept a hidden parameter called runtime-context. This contains useful information such as the active memory allocator.
- static dispatch
  - There is no dynamic dispatch (yet). This might change in the future, but the language is designed to feel like you are using dynamic dispatch even when under the hood it is not implemented that way. You do not have messages like perform: for selectors, but you do have messages like evaluate: for blocks.
- multi-threaded
  - Multi-threading is achieved using platform capabilities but the language is designed around the idea of immutable data as much as possible. To share data between threads the data must be immutable. Multi-threaded arenas allow for multiple threads to mutate a shared piece of memory at the same time using threading primitives.
- shoot yourself in the foot
  - Smalltalk Zero is designed to be a power tool. We take the feel of Smalltalk but remove the guard rails to allow high performant application development. It is not the right tool for every job. Smalltalk, as a dynamic language, is fantastic. It solved most dynamic language design issues in the 1980s; some of what it knows should be brought back to the static language world.
- references and mutability
  - By design any object you have in your scope is mutable. While this is opposite to the modern aesthetic that everything is immutable, unless you set your method parameters to receive parameters those parameters will be copy-on-write and not modify the callers versions.
  - self is copy-on-write, the original person is not modified, person is likely passed by reference
  - ```
  // non-ref to non-ref
  [self example] [:Person | name: 'B'].
  person := {Person | name: 'A'}.
  person example.
  person name. // 'A'
```
- self is read-write, the original person is modified
- ```
// non-ref to ref
[self example] [:&Person | name: 'B'].
person := {Person | name: 'A'}.
person example.
person name. // 'B'
```
  - self is copy-on-write, the original person is not modified, person is passed by reference
  - ```
  // ref to non-ref
  [self example] [:Person | name: 'B'].
  person := {Person | name: 'A'}.  
  (&person) example. // force person to be a reference
  person name. // 'A'
```
- self is copy-on-write, the non-reference variant is chosen
- ```
// non-ref to non-ref chosen
[self example] [:Person | name: 'B'].
[self example] [:&Person | name: 'C'].
person := {Person | name: 'A'}.
person example.
person name. // 'A'.
```
  - self is read-write, the original person is modified, the reference variant is chosen
  - ```
  // ref to ref chosen
  [self example] [:Person | name: 'B'].
  [self example] [:&Person | name: 'C'].
  person := {Person | name: 'A'}.
  (&person) example.
  person name. // 'C'.
```
- Forcing a call to a mutable version of a method is not a common thing. The only circumstance where you'd need this is if there were two variants of the same method for non-ref and ref. It's also not a common thing to implement two methods in that fashion unless you wanted explicit ref passing only.
- The syntax to do it is also a little funky given that & has low precedence it will apply to a whole expression, eg: &person example will actually return a reference to whatever example returns, not to the person.
- The usual read/write paradigm looks like this:
- ```
[self capitalised-name] [:Person -> :String | name to-uppercase].
[self capitalised-name: new-name] [:&Person | name: new-name to-uppercase].
```

syntax

strings
- There are three forms of string though they all behave exactly the same. This is for convenience. If your string needs a single-quote in it, you can use the double-quote version of a string, and vice versa. And if you need both double and single quotes in your string, you can use the back-tick version.
- ```
'string'
"string"
`string`
```
- There are three kinds of String in the base library:
- ```
regular-string: String = "Hello World".
escaped-string: EscapeString = "Hello\tWorld\n".
template-string: TemplateString = "Hello [name]".
```
booleans
- ```
true
false
```

integers

1234567890
-1234567890
1_234_567_890
-1_234_567_890
0b0110101001
0o71727375
-0o71727375
0xF23BEEF
-0xF23BEEF

floats

1234.56789
-1234.56789
1_234.567_89
-1_234.567_89

comments
- ```
// single line comment
```
statements
- expression. expression. expression.
- Statements are an ordered list of expressions separated by full-stop. In other languages it is common to see semi-colon used for this purpose, or for newlines too. While newlines are appealing, the ability to manipulate whitespace as you want is worth requiring an expression termination character.
- Semi-colon has a special meaning in Smalltalk, so we opt for the 'sentence like' approach of Smalltalk and using full-stop to end our "sentence" of code.
subexpressions
- (expression) (CastingType | expression)
- There is no implicit casting. To select the correct method to call the types must match; or you call a generic method which will generate itself based on the parameter types and then test if the method can make sense.
- A subexpression can be given a CastingType to transform the value in to that type if there is a casting method for it. Casting methods have the name cast and a type of A → B.
- ```
1 * (2 + 3).
1.5 * (Float | 2 + 3).
```
- An example of how casting creates transforms:
- ```
Celsius :: {temperature: Number}.
[self cast] [:Number -> :Celsius | {temperature: self}.

room-temperature: Celsius = 20.
// transforms into:
// room-temperature: Celsius = {temperature: 20}.
```
variable declaration
- identifier : type
- Define the variable without setting the value. Its initial value will be the zero-value of the type. All types have a zero-value.
- ```
my-name: String
```
variable assignment
- identifier : type = expression
- ```
my-name: String = "Fallen"
```
variable assignment with type deduction
- identifier := expression
- The type of an identifier is deduced only once. You can assign to it as many times as you like but the new values must match the type deduced the first time.
- ```
my-name := "Fallen"
```
constant declaration
- identifier :: literal
- Constants are immutable in their runtime scope. They are created in the compilation scope and preserved for the runtime scope.
- ```
my-name :: "Fallen"
```
object creation
- {Type | statements}
- Create a new object of a known type (at compile time). Inside the squiggle-bracketed scope {}, the receiver is the new object. Each key: value like thing is actually a message send, you can send anything you like but all message sends have no left-hand-side receiver.
- ```
{Person | name: "Bob", age: 27, jump}.
bob: Person = {name: "Bob", age: 27, jump}.
```
object focus
- expression {statements}
- This is syntactic sugar, what it does is change the receiver temporarily inside the squiggle-bracketed scope {}. It takes the place of cascading message sends in Smalltalk.
- ```
bob := {Person | name: "Bob"}.

bob {age: 27, height: 175}.
// the focused block is equivalent to:
// bob age: 27.
// bob height: 175.
```
type declarations (classes)
- identifier :: {variable-name : type} identifier :: {variable-name : type = default-value expression} identifier :: {variable-name : type, variable-name : type} ...etc identifier :: {variable-name, variable-name : type}
- ```
Person :: {name: String}.
Person :: {name: String = "Fallen"}.
Person :: {name: String, age: u64}.
Person :: {name, nickname: String, age: u64}.
```
- member scoping
  - identifier :: {#module variable-name : type} identifier :: {#private variable-name : type}
  - There is no #public as it is the default.
  - ```
  Person :: {name: String, #module has-changed: Bool}.
```
- member alignment
  - identifier :: {#alignment: 1} identifier :: {#alignment: 4}
  - By default all classes align based on the platform at compile time. This pragma allows overriding that default.
- subtypes
  - identifier :: {...Supertype, variable-name : type} ...etc identifier :: {...Supertype1, ...Supertype2, variable-name : type} ...etc
  - Subtypes are automatically grouped by their supertypes. A method that accepts a parameter of Supertype now also accepts any subtype. If a supertype is the type of a member, it will be stored as typeid + value.
  - Subtyping is treated the same way as combining maps. Newer merges replace existing values. This means Supertype2 overwrites Supertype1 if there is a conflict.
  - ```
  FunPerson :: {...Person, fun-level: u64}.
  AI :: {...Person, ...Machine, intelligence: u64}.
```
- distinct types
  - identifier :: {value: OriginType}
  - There is no special syntax for a distinct type. Any type that contains only one member is effectively a distinct type. It can be transformed back in to its origin type or created from its origin type but all the methods you can send to the origin type are not accessible.
  - Unlike subtypes, distinct types are not grouped by their origin type; they inherit no methods and are fundamentally a different type to the origin. They can be transformed back in to the origin type iff they have the same shape.
  - ```
  // A simple distinct type
  UUIDv7 :: {value: u128}.
```
- ```
// The base library facility for distinct types
DistinctType ::
 {#module #generic origin-type: Type,
  #module          value:       origin-type}.

// Creating the DistintType from the origin-type:
[self cast] [self: Type -> DistinctType[self] | {value: self}].

// Getting the origin-type back from the DistinctType:
[self cast] [self: DistinctType -> self origin-type | value].

// Using it:
UUIDv7 :: DistinctType[u128].
```
- generic types
  - identifier :: {#generic variable-name : type}
  - You cannot create data that is a generic type, but you can use a generic type as a parameter to a method. You can also have a reference to it which will be a double field of type+pointer. This is the broadest form of a tagged union, where the tag list is all potential types.
  - ```
  List ::
    {#generic element-type: Type,
     origin: MemoryAddress[element-type]}.
  
  [list do-something] [:&List -> :String | #required].
  [list do-something-else] [:&List -> :String | 'Hello World: List'].
  
  SubList :: {...List[u64]}.
  [sublist do-something] [:&SubList -> :String | 'Hello World: SubList'].
  [sublist do-something-else] [:&SubList -> :String | #deleted].
```
- List is generic and requires element-type to be defined when used. By giving it an element-type (eg: List[u64]) we make a new variant of it, a subtype, that is fulfilled. It is still unusable because List[u64] does not implement do-something.
- SubList fulfils that by implementing do-something. SubList also deletes the inherited do-something-else.
tagged unions
- Type + Type + Type ...etc
- A tagged union is a set of types that are stored in memory with their type id. The type id is limited to only those types in its union.
- Subtyping and tagged unions operate in much the same way. Tagged unions allow you to take a disparate set of types and combine them together in to a group, while subtyping auto-groups them based on their supertypes.
- ```
FoodOrNotFood :: Food + NotFood
```
enumeration declaration
- identifier :: {value1, value2, value3} identifier :: {value1 = first-value expression, value2, value3} identifier :: {BaseType | value1, value2, value3}
- ```
cardinals :: {north, east, south, west}.
cardinals :: {north = 1, east, south = 8, west}.
cardinals :: {Integer | north = -1, east, south, west}.
```
arrays
- {expression, expression, expression} {ElementType | expression, expression, expression}
- ```
{}
{1, 1 + 1, 3}
{Float | }
{Float | 1, 2, 3}
```
- combining arrays
  - {...expression, expression} {expression, ...expression, expression}
  - The ... spread operation runs from left to right when building the array. To copy an array you can use {...original}.
  - ```
  group-a := {1, 2, 3}.
  group-b := {4, ...group-a, 5}.
```
- subarrays (slicing)
  - expression[start:] expression[:stop] expression[::length] expression[start:stop] expression[start::length]
  - Also known as slicing, a subarray is still an array since arrays are a pointer+length (although the length might be known at compile time and compiled away at runtime). Creating a 'slice' returns an array that references the innards of the source array. The bounds are checked.
  - Both start and stop are inclusive. Making a zero length slice cannot be done with start:stop, but can be done with start::length. The indices are zero-based.
  - ```
  {1, 2, 3, 4, 5}[1:3].  // {2, 3, 4}
  {1, 2, 3, 4, 5}[1:].   // {2, 3, 4, 5}
  {1, 2, 3, 4, 5}[:3].   // {1, 2, 3, 4}
  {1, 2, 3, 4, 5}[::3].   // {1, 2, 3}
  {1, 2, 3, 4, 5}[2::2]. // {3, 4}
```
- access and mutation ^68d31467-60b8-4587-8573-c915ff93e243
  - expression[expression] expression[expression] = expression
  - When accessing an array, the indices are zero based offsets from the base.
  - ```
  {1, 2, 3}[2].
  people[0] = {name: "Zero", age: 0}.
```
maps
- {variable-or-literal : expression, variable-or-literal : expression} {KeyType, ValueType | variable-or-literal : expression, variable-or-literal : expression}
- ```
{"A": 64, "B": 65, "C": 66}.
{String, Integer | }.
{String, Integer | "A": 64, "B": 65, "C": 66}.
```
- combining maps
  - {...variable-or-literal, variable-or-literal : expression} {KeyType, ValueType | variable-or-literal : expression, ...variable-or-literal, variable-or-literal : expression}
  - Like arrays, the ... spread operator here also runs from left to right. It will overwrite existing keys that already exist.
  - ```
  group-a := {"A": 64, "B": 65, "C": 66}.
  group-b := {"Z": 0, ...group-a, "X": 1}.
```
- maps with computed keys
  - {(expression): expression} {...(expression), (expression): expression}
  - ```
  a-character := "A".
  a-value := 65.
  group-a := {(a-character): a-value}.
  group-b := {...(group-a)}.
```
- access and mutation
  - expression[expression] expression[expression] = expression
  - ```
  {"A": 65, "B": 66}["B"].
  {"A": 65, "B": 66}["B"] = 67.
```
reference type
- &Type
- A Reference is memory address of another object and a length fixed to 1. It has a null state. It cannot be changed like a memory address and does not act like an array like a memory address.
- ```
PersonRef :: &Person.
```

method sends

unary method sends
- expression selector
- ```
person name
```
binary operator sends
- expression op expression
- ```
1 + 2 * 3
```
binary method sends
- expression selectorop* expression*
- ```
{1, 2, 3} merge-with> {2, 3, 4} print-into> stdout
```
keyword method sends
- expression selector-part: expression selector-part: expression
- Unlike the binary method send, any selector part that ends in a colon (:) is combined with previous selector parts in to a single method selector. Below is calling the method draw-line-from:to:.
- ```
gc draw-line-from: {0, 0} to: {15, 15}
```

precedence

precedence	thing
9	unary method sends
8	* / % &
7	+ - ~
6	= ≠ < > ≤ ≥
5	&&
4	││
3	[index] [start:stop] [start::length]
2	binary method sends
1	keyword method sends
0	reference &

methods
- [signature] [Types | statements]
- The order and number of types must match the signature.
- In the annotation type, when the parameter has no name, the name is taken from the signature. The annotation type allows you to specify the name and type together.
- You can also name the return type which allows you to send messages to it and also use it as a way to return from the current scope back to that explicit scope. This is useful in nested blocks.
- ```
[foo bar] [:Integer -> :String | ].
[foo bar] [foo: Integer -> bar: String | ].

[foo bar: baz and: qaz] [:Integer, :Integer, :Integer -> :String | ].
[foo bar: baz and: qaz] [foo: Integer, baz: Integer, qaz: Integer -> blah: String | ].

[foo + baz] [:Integer, :Integer -> :String | ].
[foo bar> baz] [:Integer, :Integer -> :String | ].
```
- You can have methods with no return value, but you cannot have a method that has no parameters. There is always at least a receiver.
- ```
[self print-my-name] [:Person | name print].
```
- You can also have methods inside methods.
- generic methods
  - Generic methods have one or more of their parameters specified without a type. This requires the compiler to fill in the gap when it is called using the type of the parameter supplied. If that type needs to be deduced, there is a compilation error.
  - ```
  [foo bar] [foo -> bar | ].
  [foo bar: baz] [foo, baz -> blah | ].
```
- resolving subtypes and tagged unions
  - You can use blocks to resolve subtypes and tagged unions with a message send. Overloading method parameters creates implicit overload lists.
  - ```
  Animal :: {}.
  Cat :: {...Animal}.
  Dog :: {...Animal}.
  
  [living-creature my-method] [:Animal |
  	[cat switch] [:Cat | cat chase-yarn].
  	[dog switch] [:Dog | dog chase-ball].
  	[animal switch] [:Animal | animal stare-intently].
  	living-create switch].
```
- In this example we create a switch method inside our method so its scope isn't visible to the rest of the application. By calling it the compiler type-matches against living-creature and runs the appropriate block of code.
- At runtime if the type is ambiguous, the generated code will check the typeid (0 = Animal, 1 = Cat, 2 = Dog) and call the appropriate method. The generated code is roughly equivalent to this:
- ```
{animal_switch, cat_switch, dog_switch}[living-creature type-id] evaluate: living-creature value.
```
blocks
- [Type | statements]
- Blocks are anonymous methods. If they reference variables outside its scope, it will attempt to close over them. They will not close over variables if the block escapes this execution context (it is returned from the method or it is assigned in to an object) in which case there is a compilation error.
- Block closures are still being considered, though in manually memory management they become a tripping hazard.
- ```
[:Integer -> :String | ].
[foo: Integer, bar: Integer -> baz: String | ].
[:String | ].
```
- Unlike methods you can have blocks that have no parameters but return a value.
- ```
[ -> :String | "Hello World"].
```
- generic blocks
  - Generic blocks are extremely common; the context around them are information rich allowing the resolution of the parameters most of the time.
  - ```
  [foo, bar | ].
  [foo, bar -> baz | ].
  
  people select> [age ≥ 18] do> [person | stdout print: person].
```
- generic return values
  - Generic blocks can also be a mixture of known and unknown types and that includes an unknown return value.
  - ```
  [a: String, b: Integer -> return | return <- a + b print].
```
- quick blocks
  - A quick block has no defined parameters or return values, but it assumes there is one parameter - a receiverless parameter, and one return value, which may be ignored. These blocks write code immediately and do not have a bar |
  - ```
  [+ 1] evaluate: 2. // answer is 3
  people select> [age ≥ 18]. // all the adults
```
return values
- When you have nested blocks inside of methods it can become trick to 'escape' out of that block back to the scope level you want. Other languages use keywords such as break, continue, return to achieve this. STZ instead allow the return value to be labelled. You can assign to it or you can return from its scope.
- ```
[self my-method] [:Person -> method_return: Integer |
  self do-something: [:Person -> block1_return: Integer |
    self do-something-else: [:Person -> block2_return: Integer |
      // leave this block
      block2_return <- 20000.
      
      // leave the parent block
      block1_return <- 2000.
      
      // leave the method
      method_return <- 200.
      
      // the block ends naturally
      20].
    
    // leave this block
    block1_return <- 1000.
    
    // leave the method
    method_return <- 100.
    
    // the block ends naturally
    10].
  
  // leave the method
  method_return <- 1.
  
  // the method ends naturally
  0]
```
- It's common to want a quick exit from a block, but usually the block above you not the one you're currently in. That is why each one needs to be labelled (if they're to be used). Returning from a block that has no return value, though, would be a little awkward with the ← syntax.
- The Smalltalk-ANSI syntax for return is ^ and many languages use a keyword of return. STZ solves this by allowing <- to have no right hand side.
- ```
words do: [index, word -> return |
  word = "soup" then: [
    foundIndex := index.
    return <-]].
```
- Another example:
- ```
[self save] [:&DatabaseRecord -> return |
  has-changed else: [return <-].
  write-to-database]
```
- Early existing from a loop is a common thing which is why do> has been implemented with a generic return value. That makes it possible to do this:
- ```
foundIndex := words
  do> [index, word -> return |
    word = "soup" then: [return <- index]]
  else: -1.
```
- This iterates the loop and if the loop completes it will return a Result of NotFound. Most calls to do> ignore the return value, but we can use it here paired with an else: call to implement 'index-of'. It is better to return an Either than giving -1 a special meaning though, so this example is also contrived.

base library
- Boolean
  - true false
  - ```
  4 is-even then: ["It's even" print].
  4 is-odd else: ["It's even" print].
  
  4 is-even
    then: ["It's even" print]
    else: ["It's odd" print].
   
  true && false. // false
  true || false. // true
  true not. // false
```
- Maybe
  - Maybe wraps up a value in a state of either instantiated or uninstantiated. This is typically done with a value + a boolean, but in the case of a MemoryAddress it efficiently acts as a distinct type where 0 is the false state and > 0 is the true state.
  - You can resolve a Maybe in several ways:
  - ```
  // with boolean operations
  maybe then: [value | ... ].
  maybe else: [ ...no value... ].
  maybe else: default-value.
  
  // with binary operations
  maybe then> [value | ... ] else> [ ...no value... ].
  
  // violently
  maybe value-or-panic.
```
- Result
  - Any kind of outcome be it an Error, Failure, or Success. These are used as the standard way to return a result, instead of the C approach of returning an integer.
  - ```
  // Make a new kind of Result
  OutOfMemory :: {...Result}.
  memory := (allocator allocate: 5 bytes) else> [:OutOfMemory | "We ran out of memory" panic].
  
  // Make many new kinds of Result using an enum.
  FileOpResults :: {Result | OK, FileNotFound, FileAccessDenied}.
  contents := "test.txt" as-filename open-read
    else> [:FileNotFound | "Where is it?" panic]
    else> [:FileAccessDenied | "We cannot read that one" panic]
    then> [get-contents].
```
- Either
  - Either is the mechanism used to return a value or a result. They are constructed using / to indicate either A or B:
  - ```
  [filename open-read] [:Filename -> :FileHandle / FileOpResult | ... ].
```
- Much like a Maybe, you can resolve an Either in several ways:
- ```
// with boolean operations
either then: [truth | ...].
either else: [non-truth | ...].
either else: default-value.

// with binary operations
either then> [truth | ...] else> [non-truth | ...].

// violently
either then-value-or-panic.
either else-value-or-panic.
```
  - Like Maybe, only one side of the Either is instantiated at any time. You cannot access the wrong side of the Either safely which is why boolean and binary operations are the best approach to resolving them.
- Numbers
  - Integer UnsignedInteger
  - Float
- Memory
  - MemoryAddress[element-type = u8]
    - Containing an integer representing a pointer on the platform. This class is memory unsafe in that you can create one pointing anywhere you want and then attempt to write to read or memory with it. You can also do arithmetic operations with it.
    - ```
    home := {MemoryAddress | base: 0}
    
    // read from the start of memory
    home[0].
    
    // write to the start of memory
    home[0] = 0xFF.
    
    // create a new address offset from home
    home + 0xDFFF.
```
- It goes without saying that this is a power tool and generally not used in most code. Instead, use Array and Reference.
- Reference[type]
- MemoryAllocator
  - While it is fairly normal in Smalltalk code to call new, it is not that common in STZ. Creating one single object to put on the heap requires advanced automated memory management and usually garbage collection to clean it up later.
  - ```
  [MemoryAddress base: offset]
    [:Class, :UnsignedInteger -> :MemoryAddress |
      self new {base: offset} // calling new, creating an instance on the heap].
  
  home := MemoryAddress base: 0. // allocated on the heap somewhere of type &MemoryAddress[u8]
  home free. // release the allocated memory
```
  - It's more typical in STZ to create the object on the stack and either pass it around to calls you're making by reference, or copy it around. Most objects are quite small. This is a foot-gun power tool where making a decision can best be informed with performance testing.
  - The memory arenas are efficient and you tend to create a temporary arena to create lots of objects and then throw them away in bulk, but they aren't as efficient as the stack.
  - A common pattern is to be handed a reference to an object to alter rather than making it yourself and returning it. That allows the caller to have an Array or Map of objects that it is managing and providing to your method to do some sort of processing with.
  - ```
  [person grow-older] [:&Person -> ø | age: age + 1].
```
  - This method will now work whether the Person is on the heap or on the stack. No decision about memory management is being forced upon the caller.
  - When memory is being used it will typically keep the memory allocator itself so that it can free things as needed. List and Map are both dynamically allocated and both do this.
  - ```
  memory-arena: HeapAllocator.
  people: List[Person] = {allocator: memory-arena, grow-to-atleast: 1}.
  people[0] grow-older. // auto-referenced to match the grow-older method
  people free // return object space back to the memory-arena, unncessary given the next call
  memory-arena free // free the entire arena, people becomes invalid
```
  - Note that defining our own allocator is unnecessary as the default allocator on runtime-context is already a HeapAllocator.
  - A TemporaryAllocator[Person] would mean no free is necessary since it allocates on the stack, but otherwise acts like any other allocator. This allows you to avoid malloc/free calls when constructing strings, for instance, and is a common technique to avoid overloading the HeapAllocator on the runtime-context there for the developer to use, rather than the library you're calling.
- Collections
  - Array[element-type] Array[element-type, length]
  - List[element-type]
  - Map[key-type, value-type]