Bug-fixes for the Slate emacs mode.

[cslatevm.git] / doc / progman.lyx

#LyX 1.5.3 created this file. For more info see http://www.lyx.org/
\lyxformat 276
\begin_document
\begin_header
\textclass article
\language english
\inputencoding auto
\font_roman bookman
\font_sans default
\font_typewriter default
\font_default_family default
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\float_placement !htp
\paperfontsize default
\spacing single
\papersize default
\use_geometry true
\use_amsmath 1
\use_esint 0
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\leftmargin 1.5in
\rightmargin 1.5in
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip smallskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\author "" 
\author "" 
\end_header

\begin_body

\begin_layout Title
The Slate Programmer's Reference Manual
\end_layout

\begin_layout Author
Brian T.
 Rice, Lee Salzman, Timmy Douglas
\end_layout

\begin_layout Standard
\begin_inset LatexCommand tableofcontents

\end_inset


\end_layout

\begin_layout Standard
\begin_inset FloatList figure

\end_inset


\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Section
Introduction
\end_layout

\begin_layout Standard
Slate is a member of the Smalltalk
\begin_inset LatexCommand index
name "Smalltalk"

\end_inset

 family of languages which supports an object model in a similar prototype-based
 style as Self
\begin_inset LatexCommand index
name "Self"

\end_inset


\begin_inset LatexCommand cite
key "SelfPR"

\end_inset

, extended and re-shaped to support multiple-dispatch methods.
 However, unlike Self, Slate does not rely on a literal syntax that combines
 objects and blocks, using syntax more akin to traditional Smalltalk.
 Unlike a previous attempt at providing prototype-based languages with multiple
 dispatch
\begin_inset LatexCommand cite
key "Cecil"

\end_inset


\begin_inset LatexCommand index
name "Cecil"

\end_inset

, Slate is dynamic and more free-form in style, supporting the simplicity
 and flexibility of syntax and environment of the Smalltalk family.
 It is intended that both Smalltalk and Self styles of programs can be ported
 to Slate with minimal effort.
 Finally, Slate contains extensions
\begin_inset LatexCommand index
name "extensions"

\end_inset

 including optional keywords, optional type-declarations, subjective dispatch
 and syntactic macros, that can be used to make existing programs and environmen
t organizations much more powerful than in traditional object-based programming.
\end_layout

\begin_layout Subsection
Conventions
\end_layout

\begin_layout Standard
Throughout this manual, various terms will be highlighted in different ways
 to indicate the type of their significance.
 If some concept is a certain programming utility in Slate with a definite
 implementation, it will be formatted in a 
\family typewriter
typewriter-style
\family default
.
 If a term is technical with a consistent definition in Slate, but cannot
 have a definite implementation, it will be set in 
\noun on
small capital letters
\noun default
.
 Emphasis on its own is denoted by 
\emph on
italics
\emph default
.
 When expression/result patterns are entered, typewriter-style text will
 be used with a 
\family typewriter
Slate>
\family default
 prompt before the statement and its result will be set in 
\family typewriter
\emph on
italicized typewritten text
\family default
\emph default
 below the line.
\end_layout

\begin_layout Subsection
Terms
\end_layout

\begin_layout Standard
Slate is an object-oriented language, and as such works with some terms
 worth describing initially for clarity.
 These are primarily inspired by the metaphor of computational entities
 which communicate via messages, as follows:
\end_layout

\begin_layout Description
Object
\begin_inset LatexCommand index
name "object (terminology)"

\end_inset

 is some thing in the system that can be identified.
\end_layout

\begin_layout Description
Method
\begin_inset LatexCommand index
name "method (terminology)"

\end_inset

 is some behavior or procedure that is defined on some objects or class
 of objects.
\end_layout

\begin_layout Description
Message
\begin_inset LatexCommand index
name "message (terminology)"

\end_inset

 is the act of requesting a behavior or procedure from some objects, the
 message's 
\emph on
arguments
\emph default
.
 The requestor is known as the 
\emph on
sender
\emph default
.
\end_layout

\begin_layout Description
Answer
\begin_inset LatexCommand index
name "answer (terminology)"

\end_inset

 is the response to a message; a value that expressions evaluate into or
 return to the message's sender.
\end_layout

\begin_layout Description
Selector
\begin_inset LatexCommand index
name "selector (terminology)"

\end_inset

 is the name of a method or a message-send.
\end_layout

\begin_layout Description
Inheritance
\begin_inset LatexCommand index
name "inheritance (terminology)"

\end_inset

 is a relationship between objects that confers one object's (the parent)
 behavior on another (the child).
\end_layout

\begin_layout Description
Dispatch
\begin_inset LatexCommand index
name "dispatch (terminology)"

\end_inset

 is the process of determining, from a message-send, what method is appropriate
 to invoke to implement the behavior.
 This is also referred to as 
\emph on
lookup
\emph default
.
\end_layout

\begin_layout Section
Language Reference
\end_layout

\begin_layout Subsection
Objects
\end_layout

\begin_layout Standard

\noun on
\begin_inset LatexCommand index
name "objects"

\end_inset

Objects
\noun default
 are fundamental in Slate; everything in a running Slate system consists
 of objects.
 Slate objects consist of a number of slots and roles: slots
\begin_inset LatexCommand index
name "slots"

\end_inset

 are mappings from 
\family typewriter
Symbol
\family default
s to other objects, and roles
\begin_inset LatexCommand index
name "roles"

\end_inset

 are a means of organizing code that can act on the object.
 Slots themselves are accessed and updated by a kind of message-send which
 is not distinguishable from other message-sends syntactically, but have
 some important differences.
\end_layout

\begin_layout Standard
Objects in Slate are created by 
\emph on
cloning
\begin_inset LatexCommand index
name "cloning"

\end_inset


\emph default
 existing objects, rather than instantiating a class.
 When an object is cloned, the created object has the same slots and values
 as the original one.
 The new object will also have the access and update methods for those slots
 carried over to the new object.
 Other methods defined on the object will propagate through an analogue
 of a slot called a role, explained in section 
\begin_inset LatexCommand ref
reference "sub:Methods"

\end_inset

 on Methods.
\end_layout

\begin_layout Standard
Both control flow and methods are implemented by specialized objects called
 blocks
\begin_inset LatexCommand index
name "blocks"

\end_inset

, which are code closures
\begin_inset LatexCommand index
name "code closures"

\end_inset

.
 These code closures contain their own slots and create activation objects
 to handle run-time context when invoked.
 They can also be stored in slots and sent their own kinds of messages.
\end_layout

\begin_layout Subsubsection
Code Blocks
\end_layout

\begin_layout Standard
\begin_inset LatexCommand label
name "sub:Block-Closures"

\end_inset

A code block
\begin_inset LatexCommand index
name "code block"

\end_inset

 is an object representing an encapsulable context of execution, containing
 local variables, input variables, the capability to execute expressions
 sequentially, and finally answers a value to its point of invocation.
 The default return value for a block is the last expression's value; an
 early return via 
\family typewriter
^
\family default
 (see 
\begin_inset LatexCommand vref
reference "sub:Early-Returns"

\end_inset

)
\begin_inset LatexCommand index
name "return, early"

\end_inset

 can override this.
\end_layout

\begin_layout Standard
Blocks have a special syntax for building them up syntactically.
 Block expressions are delimited by square brackets.
 The block's optional header can specify input and local slots between vertical
 bars (
\family typewriter
||
\family default
), and then a sequence of expressions which comprises the block's body.
 The input syntax allows specification of the slot names desired at the
 beginning.
 For example,
\end_layout

\begin_layout LyX-Code
Slate> [| :arg num | num: 4.
 arg + num].
\newline

\emph on
[]
\end_layout

\begin_layout Standard
creates and returns a new block.
 Within the header, identifiers that begin with a colon such as 
\family typewriter
:arg
\family default
 above are parsed as input slots
\begin_inset LatexCommand index
name "input slots"

\end_inset

.
 The order in which they are specified is the order that arguments matching
 them must be passed in later to evaluate the block.
 If the block is evaluated later, it will return the expression after the
 final stop (the period) within the brackets, 
\family typewriter
arg\InsetSpace ~
+\InsetSpace ~
num
\family default
.
 In this block, 
\family typewriter
arg
\family default
 is an input slot, and 
\family typewriter
num
\family default
 is a local slot
\begin_inset LatexCommand index
name "local slots"

\end_inset

 which is assigned to and then used in a following expression.
 The order of specifying the mix of input and local slots does not affect
 the semantics, but the order of the input slots directly determines what
 order arguments need to be passed to the block to assign them to the correct
 slots.
\end_layout

\begin_layout Standard
Using the term "slot" for local and input variables is not idle: the block
 is an actual object with slots for each of these variables, and accessors
 defined on them which are even callable from outside the block, considering
 it as an object.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "block invocation"

\end_inset

In order to invoke a block, the caller must know how many and in what order
 it takes input arguments.
 Every block responds to 
\family typewriter
applyTo:
\begin_inset LatexCommand index
name "applyTo: (message)"

\end_inset


\family default
, which takes an array of the input values as its other argument.
 The block is immediately evaluated, and the result of the evaluation is
 the block's execution result.
 For example,
\end_layout

\begin_layout LyX-Code
Slate> [| :x :y | x quo: y] applyWith: 17 with: 5.
\newline

\emph on
3
\newline

\emph default
Slate> [| :a :b | (a raisedTo: 2) - (4 * b)] 
\newline
 applyTo: {3.
 4}.
\newline

\emph on
-7
\end_layout

\begin_layout Standard
Arguments can also be passed in using some easier messages.
 Blocks that don't expect any inputs respond to 
\family typewriter
do
\family default

\begin_inset LatexCommand index
name "do (message)"

\end_inset

, as follows:
\end_layout

\begin_layout LyX-Code
Slate> [| a b | a: 4.
 b: 5.
 a + b] do.
\newline

\emph on
9
\end_layout

\begin_layout Standard
Blocks that take one, two, or three inputs, each have special messages 
\family typewriter
applyWith:
\family default

\begin_inset LatexCommand index
name "applyWith: (message)"

\end_inset

, 
\family typewriter
applyWith:with:
\family default

\begin_inset LatexCommand index
name "applyWith:with: (message)"

\end_inset

, and 
\family typewriter
applyWith:with:with:
\begin_inset LatexCommand index
name "applyWith:with:with: (message)"

\end_inset


\family default
 which pass in the inputs in the order they were declared in the block header.
\end_layout

\begin_layout Standard
If a block is empty
\begin_inset LatexCommand index
name "block, empty"

\end_inset

, contains an empty body, or the final expression is terminated with a period
\begin_inset LatexCommand index
name "block, termination with a period"

\end_inset

, it returns 
\family typewriter
Nil
\family default
 when evaluated:
\end_layout

\begin_layout LyX-Code
Slate> [] do.
\newline

\emph on
Nil
\emph default

\newline
Slate> [| :a :b |] applyTo: {0.
 2}.
\newline

\emph on
Nil
\newline

\emph default
Slate> [3.
 4.] do.
\newline

\emph on
Nil
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "variable arguments"

\end_inset


\begin_inset LatexCommand index
name "rest parameter"

\end_inset

If more arguments are passed than the block expects as inputs, an error
 is raised unless the block specifies a single 
\begin_inset Quotes eld
\end_inset

rest
\begin_inset Quotes erd
\end_inset

 argument parameter, using an asterisk prefix for the argument identifier
 in its header (e.g.
 
\family typewriter
*rest
\family default
), in which case the slot is bound to an array of the inputs not otherwise
 bound.
\end_layout

\begin_layout Standard
Blocks furthermore have the property that, although they are a piece of
 code and the values they access may change between defining the closure
 and invoking it, the code will 
\begin_inset Quotes eld
\end_inset

remember
\begin_inset Quotes erd
\end_inset

 what objects it depends on, regardless of what context it may be passed
 to as a slot value.
 It is called a lexical closure
\begin_inset LatexCommand index
name "lexical closure"

\end_inset


\begin_inset LatexCommand index
name "closure, lexical"

\end_inset

 since it 
\begin_inset Quotes eld
\end_inset

closes over
\begin_inset Quotes erd
\end_inset

 the environment and variables used in its definition, the lexical context
 where it was born.
 This is critical for implementing good control structures in Slate, as
 is explained later.
 Basically a block is an activation of its code composed with an environment
 that can be saved and invoked (perhaps multiple times) long after it is
 created, and always do so in the way that it reads where it was defined.
\end_layout

\begin_layout Subsubsection
Slots
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "slot properties"

\end_inset


\begin_inset LatexCommand index
name "slot mutability"

\end_inset


\begin_inset LatexCommand index
name "slots, delegation"

\end_inset

Slots may be mutable or immutable, and explicit slots or delegation (inheritance
) slots.
 These four possibilities are covered by primitive methods defined on all
 objects.
\end_layout

\begin_layout Standard
Slate provides several primitive messages to manage 
\noun on
data slots
\noun default
 (or 
\emph on
non-delegating
\emph default
 slots):
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addSlot: (message)"

\end_inset

obj\InsetSpace ~
addSlot:\InsetSpace ~
slotSymbol
\family default
 adds a slot using the 
\family typewriter
Symbol
\family default
 as its name, initialized to 
\family typewriter
Nil
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addSlot:valued: (message)"

\end_inset

obj\InsetSpace ~
addSlot:\InsetSpace ~
slotSymbol\InsetSpace ~
valued:\InsetSpace ~
val
\family default
 adds a slot under the given name and initializes its value to the given
 one.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "addImmutableSlot:valued: (message)"

\end_inset


\family typewriter
addImmutableSlot:valued:
\family default
 performs the same as the above method, only without installing a mutator
 method.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "removeSlot: (message)"

\end_inset

obj\InsetSpace ~
removeSlot:\InsetSpace ~
slotSymbol
\family default
 removes the slot with the given name on the object directly and returns
 whatever value it had.
\end_layout

\begin_layout Standard
The effect of all of the slot addition methods when a slot of the same name
 is present is to update the value and attributes of the slot rather than
 duplicate or perform nothing.
\end_layout

\begin_layout Subsubsection
Inheritance
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "delegation"

\end_inset

Slate's means of sharing and conferring behavior involves the use of a 
\noun on
delegation array
\noun default
, whereby each object can name and access each object it inherits from.
 
\end_layout

\begin_layout Standard
The delegates' inheritance role involves a precedence order which affects
 the lookup of messages; from the object's perspective, the delegate slot
 array goes from least important to most important.
 Section 
\begin_inset LatexCommand vref
reference "sub:Lookup-Semantics"

\end_inset

 explains the details of lookup semantics.
\end_layout

\begin_layout Standard
The relevant primitives specific to delegation slots are:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addDelegate: (message)"

\end_inset


\begin_inset LatexCommand index
name "addDelegate:valued: (message)"

\end_inset

obj\InsetSpace ~
addDelegate:\InsetSpace ~
val
\family default
 and 
\family typewriter
\series bold
obj\InsetSpace ~
insertDelegate:\InsetSpace ~
val
\family default
\series default
 add a delegate.
 The delegates array for an object is stored in the object's map.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "delegates (message)"

\end_inset


\begin_inset LatexCommand index
name "delegates: (message)"

\end_inset


\family typewriter

\begin_inset ERT
status collapsed

\begin_layout Standard

\family typewriter

\backslash
_{}
\end_layout

\end_inset

delegates and
\family default
 
\family typewriter
\series bold

\begin_inset ERT
status collapsed

\begin_layout Standard

\family typewriter
\series bold

\backslash
_{}
\end_layout

\end_inset

delegates:
\family default
\series default
 allow for finer control over manipulating delegates, since they explicitly
 set the delegate array.
 Use with care.
\end_layout

\begin_layout Subsection
Sending Messages
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "expressions"

\end_inset

Expressions in Slate mainly consist of messages sent to argument objects.
 The left-most argument is not considered an implicit receiver as it is
 with most message-passing languages, however.
 This means that when identifying a variable, it is really a message that
 is being sent to the context or argument.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "case sensitivity"

\end_inset


\begin_inset LatexCommand index
name "whitespace sensitivity"

\end_inset

An important issue is that every message selector (and slot name) is 
\emph on
case-sensitive
\emph default
 in Slate, that is, there is a definite distinction between what 
\family typewriter
AnObject
\family default
, 
\family typewriter
anobject
\family default
, and 
\family typewriter
ANOBJECT
\family default
 denote even in the same context.
 Furthermore, the current implementation is 
\emph on
whitespace-sensitive
\emph default
 as well, in the sense that whitespace must be used to separate messages
 in order for them to be considered separate.
 For example, 
\family typewriter
ab+4
\family default
 will be treated as one message, but 
\family typewriter
ab\InsetSpace ~
+\InsetSpace ~
4
\family default
 is a send of a binary message.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "messages, types"

\end_inset

There are three basic types of messages, with different syntaxes and associativi
ties: unary, binary, and keyword messages.
 
\emph on

\begin_inset LatexCommand index
name "messages, precedence"

\end_inset


\begin_inset LatexCommand index
name "precedence, messages"

\end_inset

Precedence
\emph default
 is determine entirely by the syntactic form of the expression, but it can
 of course be overridden by enclosing expressions in parentheses.
 An implicit left-most argument can be used with all of them.
 The default precedence for forms is as follows:
\end_layout

\begin_layout Enumerate
Literal syntax: arrays, blocks, block headers, statement sequences.
\end_layout

\begin_layout Enumerate
Unary messages.
\end_layout

\begin_layout Enumerate
Binary messages.
\end_layout

\begin_layout Enumerate
Keyword messages.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "selector"

\end_inset

A concept that will be often used about message-sends is that of the name
 of a message, its 
\noun on
selector
\noun default
.
 This is the 
\family typewriter
Symbol
\family default
 used to refer to the message or the name of a method that matches it.
 Slate uses three styles of selectors, each with a unique but simple syntax.
\end_layout

\begin_layout Subsubsection
\begin_inset LatexCommand label
name "sub:Unary-Message-sends"

\end_inset

Unary Messages
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "unary messages"

\end_inset


\begin_inset LatexCommand index
name "messages, unary"

\end_inset

A 
\noun on
unary message
\noun default
 does not specify any additional arguments.
 It is written as a name following a single argument; it has a post-fix
 form.
\end_layout

\begin_layout Standard
Some examples of unary message-sends to explicit arguments include:
\end_layout

\begin_layout LyX-Code
Slate> 42 print.
\newline

\emph on
'42'
\newline

\emph default
Slate> 'Slate' clone.
\newline

\emph on
'Slate'
\end_layout

\begin_layout Standard
Unary sends associate from left to right.
 So the following prints the factorial of 5:
\end_layout

\begin_layout LyX-Code
Slate> 5 factorial print.
\newline

\emph on
'120'
\end_layout

\begin_layout Standard
Which works the same as:
\end_layout

\begin_layout LyX-Code
Slate> (5 factorial) print.
\newline

\emph on
'120'
\end_layout

\begin_layout Standard
Unary selectors can be most any alpha-numeric identifier, and are identical
 lexically to ordinary identifiers of slot names.
 This is no coincidence, since slots are accessed via a type of unary selector.
\end_layout

\begin_layout Subsubsection
Binary Messages
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "messages, binary"

\end_inset


\begin_inset LatexCommand index
name "binary messages"

\end_inset

A 
\noun on
binary message
\noun default
 is named by a special non-alphanumeric symbol and 'sits between' its two
 arguments; it has an infix form.
 Binary messages are also evaluated from left to right; there is no special
 
\emph on
precedence
\emph default
 difference between any two binary message-sends.
\begin_inset Foot
status open

\begin_layout Standard
This removes a source of grammatical complexity in a language where anyone
 can add new binary selectors or implementations.
 It is our policy that conventional mathematical notation and visual convenience
 belong in user interface libraries.
\end_layout

\end_inset

 
\end_layout

\begin_layout Standard
These examples illustrate the precedence and syntax:
\end_layout

\begin_layout LyX-Code
Slate> 3 + 4.
\newline

\emph on
7
\emph default

\newline
Slate> 3 + 4 * 5.
\newline

\emph on
35
\emph default

\newline
Slate> (3 + 4) * 5.
\newline

\emph on
35
\emph default

\newline
Slate> 3 + (4 * 5).
\newline

\emph on
23
\end_layout

\begin_layout Standard
Binary messages have lower 
\emph on
precedence
\emph default
 than unary messages.
 Without any grouping notation, the following expression's unary messages
 will be evaluated first and then passed as arguments to the binary message:
\end_layout

\begin_layout LyX-Code
Slate> 7 factorial + 3 negated.
\newline

\emph on
5037
\newline

\emph default
Slate> (7 factorial) + (3 negated).
\newline

\emph on
5037
\newline

\emph default
Slate> (7 factorial + 3) negated.
\newline

\emph on
-5043
\end_layout

\begin_layout Standard
Binary selectors can consist of one or more of the following characters:
\end_layout

\begin_layout LyX-Code
# $ % ^ * - + = 
\begin_inset ERT
status open

\begin_layout Standard


\backslash
~{}
\end_layout

\end_inset

 / 
\backslash
 ? < > , ;
\end_layout

\begin_layout Standard
However, these characters are reserved:
\end_layout

\begin_layout LyX-Code
@ [ ] ( ) { } .
 : ! | ` &
\end_layout

\begin_layout Subsubsection
Keyword Messages
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "keyword messages"

\end_inset


\begin_inset LatexCommand index
name "messages, keyword"

\end_inset

A 
\noun on
keyword message
\noun default
 is an alternating sequence of keywords and expressions, generally being
 a continued infix form.
 Keywords are identifiers beginning with a letter and ending with a colon.
 Keyword messages start with the left-most argument along with the longest
 possible sequence of keyword-value pairs.
 
\begin_inset LatexCommand index
name "selector, of keyword message"

\end_inset

The 
\noun on
selector
\noun default
 of the message is the joining-together of all the keywords into one 
\family typewriter
Symbol
\family default
, which is the 
\emph on
name
\emph default
 of the message.
 For example,
\end_layout

\begin_layout LyX-Code
Slate> 5 min: 4 max: 7.
\newline

\emph on
7
\end_layout

\begin_layout Standard
is a keyword message-send named 
\family typewriter
min:max:
\family default
 which has 3 arguments: 5, 4, and 7.
 However,
\end_layout

\begin_layout LyX-Code
Slate> 5 min: (4 max: 7).
\newline

\emph on
5
\end_layout

\begin_layout Standard
is a different kind of expression.
 
\emph on
Two
\emph default
 keyword message-sends are made, the first being 
\family typewriter
max:
\family default
 sent to 4 and 7, and 
\family typewriter
min:
\family default
 sent to 5 and the first result.
 Note however, that even though the first expression evaluates to the same
 value as:
\end_layout

\begin_layout LyX-Code
Slate> (5 min: 4) max: 7.
\newline

\emph on
7
\end_layout

\begin_layout Standard
that this is still a distinct expression from the first one, with two message-se
nds of one keyword each instead of one send with two keywords.
 Actually, this expresses the definition of 
\family typewriter
min:max:
\family default
, although this is perhaps one of the most trivial uses of method names
 with multiple keywords.
\end_layout

\begin_layout Standard
Keywords have the lowest 
\emph on
precedence
\emph default
 of message-sends, so arguments may be the results of unary or binary sends
 without explicit grouping required.
 For example, the first expression here is equivalent to the latter implicitly:
\end_layout

\begin_layout LyX-Code
Slate> 5 + 4 min: 7 factorial max: 8.
\newline

\emph on
9
\emph default

\newline
Slate> (5 + 4) min: (7 factorial) max: 8.
\newline

\emph on
9
\end_layout

\begin_layout Subsubsection
Implicit-context Messages
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "sends, implicit-context"

\end_inset


\begin_inset LatexCommand index
name "implicit-context sends"

\end_inset


\begin_inset LatexCommand index
name "lexical scope"

\end_inset


\begin_inset LatexCommand index
name "scope, lexical"

\end_inset

Within methods, blocks, and even at the top-level, some expressions may
 take the surrounding context as the first argument.
 There is an order for the determination of which object becomes the first
 argument, which is entirely based on lexical scoping.
 So, within a block, an implicit send will take the block's run-time context
 as argument.
 The next outer contexts follow in sequence, up to the top-level and what
 it inherits from, which generally turns out to be the global object that
 roots the current session.
\end_layout

\begin_layout Standard
Specifically, any non-literal expression following a statement-separator
 or starting an expression within parentheses or other grouping is an implicit-c
ontext send.
\end_layout

\begin_layout Standard
There are some very common uses of implicit-context sends.
 In particular, accessing and modifying local variables of a block or method
 is accomplished entirely this way, as well as returns.
 For example,
\end_layout

\begin_layout LyX-Code
[| :i j k |
\newline
 j: i factorial.
\newline
 k: (j raisedTo: 4).
\newline
 j < k ifTrue: [| m |
\newline
   j:
 j - i.
 m: j.
 ^ (m raisedTo: 3)].
\newline
 k: k - 4.
\newline
 k
\newline
].
\end_layout

\begin_layout Standard
is a block which, when invoked, takes one argument and has another two to
 manipulate.
 Notice that the local slot 
\family typewriter
j
\family default
 is available within the enclosed block that also has a further slot 
\family typewriter
m
\family default
.
 Local blocks may also 
\emph on
override
\emph default
 the slots of their outer contexts with their input and local slots.
 In this case, the identifiers 
\family typewriter
j
\family default
 and 
\family typewriter
j:
\family default
, for example, are automatically-generated accessing and update methods
 on the context.
 Because 
\family typewriter
j:
\family default
 is a keyword message, if the assigned value is a keyword message-send result,
 it must be enclosed in parentheses to distinguish the keyword pattern.
 The 
\family typewriter
^\InsetSpace ~
(m\InsetSpace ~
raisedTo:\InsetSpace ~
3)
\family default
 message
\begin_inset LatexCommand index
name "early return"

\end_inset

 causes the context to exit prematurely, returning as its value the result
 of the right-hand argument.
 All methods have this method defined on them, and it will return out to
 the nearest named block or to the top-level.
\end_layout

\begin_layout Standard
The way this is currently implemented is that the compiler will detect when
 a local slot is read or modified and it will turn the command into a 
\family typewriter
loadVariable
\family default
 or 
\family typewriter
storeVariable
\family default
 bytecode.
 If the a read or write is done to a variable in a parent block, it will
 be compiled to a 
\family typewriter
loadFreeVariable
\family default
 or 
\family typewriter
storeFreeVariable
\family default
 which will get the value from the current closure's lexical window array.
\end_layout

\begin_layout Subsection
Sequencing Expressions
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "expression sequences"

\end_inset


\begin_inset LatexCommand index
name ". (period)"

\end_inset


\begin_inset LatexCommand index
name "stop mark"

\end_inset

Statements are the overall expressions between stop-marks, which are periods.
 In an interactive evaluation context, expressions aren't evaluated until
 a full (top-level) statement is expressed.
 The stop mark also means that statement's expression results aren't directly
 carried forward as an argument to the following expression; side-effects
 must be used to use the results.
 More specifically, each expression in the sequence must be evaluated in
 order, and one expression's side-effects must effectively occur before
 the next expression begins executing and before any of its side-effects
 occur.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "parentheses"

\end_inset


\begin_inset LatexCommand index
name "() (parentheses)"

\end_inset

Slate provides for a bare expression sequence syntax that can be embedded
 within any grouping parentheses, as follows:
\end_layout

\begin_layout LyX-Code
Slate> 3 + 4.
\newline

\emph on
7
\end_layout

\begin_layout LyX-Code
Slate> (7 factorial.
 5
\newline
 negated) min: 6.
\newline

\emph on
-5
\end_layout

\begin_layout Standard
The parentheses are used just as normal grouping, and notably, the 
\family typewriter
5\InsetSpace ~
negated
\family default
 expression wraps over a line, but still evaluates that way.
\begin_inset Foot
status collapsed

\begin_layout Standard
We do not consider this expression good style, but it illustrates the nature
 of the syntax.
\end_layout

\end_inset

 If the parentheses are empty, or the last statement in a sequence is followed
 by a period before ending the sequence, an 
\begin_inset LatexCommand index
name "empty expression"

\end_inset


\begin_inset Quotes eld
\end_inset

empty expression
\begin_inset Quotes erd
\end_inset

 value is returned, which is 
\family typewriter

\begin_inset LatexCommand index
name "Nil (object)"

\end_inset

Nil
\family default
 by convention.
\end_layout

\begin_layout Subsection
Methods
\end_layout

\begin_layout Standard

\noun on
\begin_inset LatexCommand index
name "methods"

\end_inset


\begin_inset LatexCommand index
name "blocks, code"

\end_inset


\begin_inset LatexCommand index
name "code blocks"

\end_inset


\begin_inset LatexCommand label
name "sub:Methods"

\end_inset

Methods
\noun default
 in Slate are basically annotated code blocks (documented in 
\begin_inset LatexCommand ref
reference "sub:Block-Closures"

\end_inset

), coupled with annotations of the objects' roles that dispatch to them.
\end_layout

\begin_layout Subsubsection
Roles
\end_layout

\begin_layout Standard
A relatively unique concept in the language is that objects relate to their
 methods via an 
\emph on
implicit
\emph default
 idea called a 
\begin_inset LatexCommand index
name "role"

\end_inset


\noun on
role
\noun default
.
 A role is an association between an object and a method that applies to
 it that is similar to a slot, but not directly a slot as it is in 
\begin_inset LatexCommand index
name "Self"

\end_inset

Self.
 Instead of simply being a storage reference, a role associates the object
 with a 
\emph on
position
\emph default
 in the signature of a method.
 This is a way of stating that the object 
\begin_inset Quotes eld
\end_inset

plays a role
\begin_inset Quotes erd
\end_inset

 in a certain behavior, reinforcing the idea that behavior arrives through
 cooperation.
 Furthermore, the behavior is shared among the cooperators, so methods are
 not 
\begin_inset Quotes eld
\end_inset

owned
\begin_inset Quotes erd
\end_inset

 by particular objects; they are not properties.
\end_layout

\begin_layout Standard
However, because dispatch can happen on many combinations of arguments,
 a method name plus the object's position is not sufficient to identify
 a single method; instead, a group of methods of the same name may be associated
 via a role with an object at a certain signature position.
 During method lookup, the appropriate method is found through knowing all
 of the objects in the signature and knowing which take precedence over
 others.
 So a specific role consists of a triple-association between an object,
 its position in a signature for a method, and the method itself.
\end_layout

\begin_layout Standard
When referring to an object's 
\begin_inset Quotes eld
\end_inset

roles
\begin_inset Quotes erd
\end_inset

 in general, it usually means the collection of these associations as a
 whole; what relates the object to the behaviors it participates in.
\end_layout

\begin_layout Subsubsection
Method Definitions
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "method definition"

\end_inset


\begin_inset LatexCommand index
name "method template"

\end_inset

Method definition syntax is handled relatively separately from normal precedence
 and grammar.
 It essentially revolves around the use of the reserved character 
\begin_inset Quotes eld
\end_inset


\family typewriter
@
\family default

\begin_inset Quotes erd
\end_inset


\begin_inset LatexCommand index
name "\\char `\\@ (at)"

\end_inset

.
 If any identifier in a message-send argument position is found to contain
 the character, the rest of the same send is examined for other instances
 of the 
\family typewriter
Symbol
\family default
, and the whole send-expression is treated as a template.
 The parser treats the expression or identifier to the right of the 
\family typewriter
@
\family default
 characters as dispatch targets
\begin_inset LatexCommand index
name "dispatch targets"

\end_inset

 for the method's argument positions; the actual objects returned by the
 expressions are annotated with a role for their positions.
\end_layout

\begin_layout Standard
After the message-send template, there is expected a block expression of
 some kind, whether a literal or an existing block.
 Whichever is specified, the parser creates a new block out of it with adjustmen
ts so that the identifiers in the dispatching message-send become input
 slots in the closure.
 The block should be the final expression encountered before the next stop
 (a period).
\begin_inset LatexCommand index
name "period"

\end_inset


\begin_inset LatexCommand index
name ". (period)"

\end_inset


\begin_inset LatexCommand index
name "stop mark"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "underscore"

\end_inset


\begin_inset LatexCommand index
name "\\_ (underscore)"

\end_inset

There is a further allowance that an input slot-name specifier may be solely
 an underscore (but not an underscore followed by anything else), in which
 case the argument to the method at that position is 
\emph on
not
\emph default
 passed in to the block closure.
\end_layout

\begin_layout Standard
This syntax is much simpler to recognize and create than to explain.
 For example, the following are a series of message definitions adding to
 boolean control of evaluation:
\end_layout

\begin_layout LyX-Code
_@True ifTrue: block ifFalse: _ [block do].
\newline
_@False ifTrue: _ ifFalse: block
 [block do].
\newline

\newline
bool@(Boolean traits) ifTrue: block
\newline
"Some sugaring for ifTrue:ifFalse:.
"
\newline
[ 
\newline
 bool ifTrue: block ifFalse: []
\newline
].
\end_layout

\begin_layout Standard
The first two represent good uses of dispatching on a particular individual
 object (dispatching the ignored argument named 
\begin_inset Quotes eld
\end_inset


\family typewriter
_
\family default

\begin_inset Quotes erd
\end_inset

 to 
\family typewriter
True
\family default
 and 
\family typewriter
False
\family default
, respectively) as well as the syntax for disregarding its value.
 Within their blocks, 
\family typewriter
block
\family default
 refers to the named argument to the method.
 What's hidden is that the block given as the code is re-written to include
 those arguments as inputs in the header.
 Also, the objects given to the dispatch annotation are configured to install
 this method in appropriate roles; because this is hidden, roles are normally
 an implicit concept and should not concern the user except as an explanation
 for dispatch.
\end_layout

\begin_layout Standard
The latter method appears to have a slightly-different syntax, but this
 is an illusion: the parentheses are just surrounding a Slate expression
 which evaluates to an object, much as 
\family typewriter
True
\family default
 and 
\family typewriter
False
\family default
 evaluate to particular objects; really, any Slate expression can be placed
 there, assuming that the result of it is what is wanted for dispatch.
 As a side note, this last method is defined in terms of the first two and
 is shared, since 
\family typewriter
True
\family default
 and 
\family typewriter
False
\family default
 both delegate to 
\family typewriter
Boolean\InsetSpace ~
traits
\family default
 (the object carrying the common behavior of the boolean objects).
\end_layout

\begin_layout Subsubsection
Expression-based Definitions
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "methods, dynamic generation"

\end_inset


\begin_inset LatexCommand index
name "asMethod:on: (message)"

\end_inset

The specialized syntax using the 
\begin_inset Quotes eld
\end_inset


\family typewriter
@
\family default

\begin_inset Quotes erd
\end_inset

 special has an equivalent in regular Slate syntax which is often useful
 for generating new methods dynamically in a non-ambiguous way.
 This is a reflective call on the evaluator to compile a method using a
 certain symbolic name and a sequence of objects that are used for dispatching
 targets.
 For example:
\end_layout

\begin_layout LyX-Code
[| :x :y | Nil] asMethod: #+ on: {True.
 False}.
\end_layout

\begin_layout Standard
and
\end_layout

\begin_layout LyX-Code
_@True + _@False [Nil].
\end_layout

\begin_layout Standard
are equivalent (while not recommendable) expressions.
 This raises the question of a place-filler for an argument position which
 is not dispatched.
 In that case, Slate provides a unique primitive 
\family typewriter
NoRole
\begin_inset LatexCommand index
name "NoRole (object)"

\end_inset


\family default
 for this purpose, which provides an analogous role to 
\family typewriter
Nil
\family default
: 
\family typewriter
NoRole
\family default
 cannot be dispatched upon.
 Essentially, this means that the following method definition:
\end_layout

\begin_layout LyX-Code
c@(Set traits) keyAt: index
\newline
[
\newline
  c array at: index
\newline
].
\end_layout

\begin_layout Standard
is semantically equivalent to:
\end_layout

\begin_layout LyX-Code
c@(Set traits) keyAt: index@NoRole
\newline
[
\newline
  c array at: index
\newline
].
\end_layout

\begin_layout Standard
and furthermore to:
\end_layout

\begin_layout LyX-Code
[| :c :index | c array at: index] asMethod: #keyAt:
\newline
                   on:
 {Set traits.
 NoRole}.
\end_layout

\begin_layout Subsubsection
\begin_inset LatexCommand label
name "sub:Lookup-Semantics"

\end_inset

Lookup Semantics
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "dispatch, message"

\end_inset


\begin_inset LatexCommand index
name "message dispatch"

\end_inset


\begin_inset LatexCommand index
name "lookup semantics"

\end_inset

Message dispatch in Slate is achieved by consulting all of the arguments
 to that message, and considering what roles they have pertaining to that
 message name and their position within the message-send.
 Slate's dispatch semantics are termed 
\begin_inset LatexCommand index
name "multiple dispatch"

\end_inset


\begin_inset LatexCommand index
name "dispatch, multiple"

\end_inset


\begin_inset Quotes eld
\end_inset

multiple dispatch
\begin_inset Quotes erd
\end_inset

 to distinguish from 
\begin_inset Quotes eld
\end_inset

single dispatch
\begin_inset Quotes erd
\end_inset

 which is typical of most languages based on objects and messages.
 Whereas most languages designate on object as the receiver of a message,
 Slate considers all objects involved cooperating participants.
 During the dispatch process, more than one method can be discovered as
 a potential candidate.
 The most 
\emph on
specific
\emph default
 candidate is chosen as soon as its place in the order is determined.
\end_layout

\begin_layout Standard
The algorithm achieves a full ordering of arguments: the specificity of
 the first argument counts more than the second, the second more than the
 third, and so on.
 However, where normal multiple dispatch looks at each argument and uses
 the most specific supertype to determine specificity (or rather, the most
 specific parameter type of which the argument is a subtype), Slate instead
 interprets specificity as 
\noun on
distance
\noun default
 in the directed graph of delegations, starting from the particular argument
 in question as the root.
\end_layout

\begin_layout Standard
The 
\noun on
distance
\noun default
 notion has the following properties:
\end_layout

\begin_layout Itemize
It is determined by a depth-first traversal over the delegate slots, considering
 delegates at a higher index in the array before lower ones.
\end_layout

\begin_layout Itemize
Delegations that lead to cycles are not traversed.
\end_layout

\begin_layout Itemize
Repeated finds of a same method do not alter the distance value for it;
 the first one found is retained.
\end_layout

\begin_layout Itemize
The closer (smaller) the 
\noun on
distance
\noun default
 of the role to the argument, the more specific it is.
\end_layout

\begin_layout Standard
So, Slate's lookup algorithm visits each argument in turn, determining candidate
 applicable methods as ordered by the 
\noun on
distance
\noun default
 notion, and traverses further to look for other possible candidates, unless
 it rules out the possibility of a more applicable method than a singly-identifi
ed one.
\end_layout

\begin_layout Standard
The resulting dispatched method satisfies the property that: for any of
 the arguments, we can find the method on some role reachable by traversing
 delegations, and that is the closest such method we can find, where former
 arguments count as being 
\begin_inset Quotes eld
\end_inset

closer
\begin_inset Quotes erd
\end_inset

 than any subsequent arguments, and 
\family typewriter
NoRole
\family default
 behaves like an 
\begin_inset Quotes eld
\end_inset

omega distance
\begin_inset Quotes erd
\end_inset

, as far away as possible.
\end_layout

\begin_layout Subsubsection
Optional Keyword Arguments
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "arguments, optional keyword"

\end_inset


\begin_inset LatexCommand index
name "optional keyword arguments"

\end_inset


\begin_inset LatexCommand index
name "keyword arguments, optional"

\end_inset

The mechanism in Slate for specifying optional input arguments uses 
\emph on
optional keywords
\emph default
 for a syntax.
 They can be added to a method definition, a message-send, or a block header
 equally.
 Also, optional keywords can apply to unary, binary, and keyword message
 syntaxes equally.
 However, optional arguments cannot affect dispatch, can be provided in
 any order, and when not provided will start with a 
\family typewriter
Nil
\family default
 value, due to their being incidental to the core semantics of the given
 block or method.
\end_layout

\begin_layout Paragraph
In Method Definitions
\begin_inset LatexCommand index
name "optional keywords (in a method definition)"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ampersand"

\end_inset


\begin_inset LatexCommand index
name "\\& (ampersand)"

\end_inset

Method definitions may be annotated with optionals that they support by
 extending the signature with keyword-localname pairs in arbitrary order
 as 
\begin_inset Quotes eld
\end_inset


\family typewriter
&keywordName:\InsetSpace ~
argName
\family default

\begin_inset Quotes erd
\end_inset

.
 This compiles the method to support 
\family typewriter
argName
\family default
 as a local, with optional input.
\end_layout

\begin_layout Paragraph
In Message Sends
\begin_inset LatexCommand index
name "optional keywords (in a message send)"

\end_inset


\end_layout

\begin_layout Standard
An optional keyword argument is passed to a method by forming keyword-value
 pairs as 
\begin_inset Quotes eld
\end_inset


\family typewriter
&keywordName:\InsetSpace ~
someValue
\family default

\begin_inset Quotes erd
\end_inset

 after the main selector and arguments as normal.
 Following keywords that have the 
\family typewriter
&
\family default
-prefix will be collected into the same message-send.
 A following non-optional keyword will be treated as beginning a new surrounding
 message-send, but in general, optional keywords raise the precedence of
 the basis message signature to a keyword level, instead of just unary or
 binary.
 Again, the order of the keyword-value pairs is ignored.
\end_layout

\begin_layout Paragraph
In Code Blocks
\begin_inset LatexCommand index
name "optional keywords (in a block header)"

\end_inset


\end_layout

\begin_layout Standard
A block can declare optional input keywords in its block header in any order,
 using 
\begin_inset Quotes eld
\end_inset


\family typewriter
&argName
\family default

\begin_inset Quotes erd
\end_inset

 as an input variable declaration, called with the normal convention (when
 using the block with 
\family typewriter
do
\family default
/
\family typewriter
applyTo:
\family default
/etc.), whenever the block is invoked with a message-send.
\end_layout

\begin_layout Subsubsection
Resending messages or Dispatch-overriding
\begin_inset OptArg
status collapsed

\begin_layout Standard
Resends
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "messages, resending"

\end_inset


\begin_inset LatexCommand index
name "resending messages"

\end_inset


\begin_inset LatexCommand index
name "overriding, dispatch"

\end_inset


\begin_inset LatexCommand index
name "dispatch-overriding"

\end_inset

Because Slate's methods are not centered around any particular argument,
 the resending of messages is formulated in terms of giving the method activatio
n itself a message.
 The following are the various primitive protocols involved in resends:
\end_layout

\begin_layout Description

\family typewriter
resend
\begin_inset LatexCommand index
name "resend (message)"

\end_inset


\family default
 is the simplest form of resending.
 It acts on the context to find the next-most-applicable method and invokes
 it with the exact same set of arguments (including optional parameters
 passed) as an expression.
 The result of the 
\family typewriter
resend
\family default
 message is the returned result of that method, just like calling any other
 method.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "findOn: (message)]"

\end_inset

methodName\InsetSpace ~
findOn:\InsetSpace ~
argumentArray
\family default
 locates and answers the method for the given 
\family typewriter
Symbol
\family default
 name and group of argument objects.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "findOn:after: (message)"

\end_inset

methodName\InsetSpace ~
findOn:\InsetSpace ~
argumentArray\InsetSpace ~
after:\InsetSpace ~
aMethod
\family default
 locates and answers the method following the given one with the same type
 of arguments as above.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "sendTo: (message)"

\end_inset

methodName\InsetSpace ~
sendTo:\InsetSpace ~
argumentArray
\family default
 is an explicit application of a method, useful when the 
\family typewriter
Symbol
\family default
 name of the method needs to be provided at run-time.
 It returns the result of the method.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "sendWith: (message)"

\end_inset


\begin_inset LatexCommand index
name "sendWith:with: (message)"

\end_inset


\begin_inset LatexCommand index
name "sendWith:with:with: (message)"

\end_inset

sendWith:
\family default
, 
\family typewriter
\series bold
sendWith:with:
\family default
\series default
 and 
\family typewriter
\series bold
sendWith:with:with:
\family default
\series default
 take one, two, and three arguments respectively as above without creating
 an array to pass the arguments in.
 It returns the result of the method.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "sendTo:through: (message)"

\end_inset

methodName\InsetSpace ~
sendTo:\InsetSpace ~
argumentArray\InsetSpace ~
through:\InsetSpace ~
dispatchArray
\family default
 is an extra option to specify a different signature (the 
\family typewriter
dispatchArray
\family default
, where the new lookup starts) for the method than that of the actual argument
 objects.
 It returns the result of the method.
\end_layout

\begin_layout Standard
Also, both 
\family typewriter
sendTo:
\family default
 and 
\family typewriter
sendTo:through:
\family default
 accept an 
\family typewriter
&optionals:
\family default
 optional keyword which is passed an 
\family typewriter
Array
\family default
 of the alternating keyword 
\family typewriter
Symbol
\family default
s (not the names of the locals: those are defined per method) and values
 to use.
\end_layout

\begin_layout Subsubsection
Subjective Dispatch (currently disabled)
\begin_inset OptArg
status collapsed

\begin_layout Standard
Subjective Dispatch
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "dispatch, subjective"

\end_inset


\begin_inset LatexCommand index
name "subjective dispatch"

\end_inset

The multiple dispatch system has an extended dynamic signature form which
 can be used to give a 
\begin_inset Quotes eld
\end_inset

subjective
\begin_inset Quotes erd
\end_inset

 or 
\begin_inset Quotes eld
\end_inset

layered
\begin_inset Quotes erd
\end_inset

 customization of the Slate environment.
 This is an implementation and slight modification of the Us
\begin_inset LatexCommand index
name "Us"

\end_inset

 language features conceived of by the Self authors
\begin_inset LatexCommand cite
key "Subjective"

\end_inset

.
\end_layout

\begin_layout Paragraph
Basic mechanisms
\end_layout

\begin_layout Enumerate
Slate dispatch signatures are 
\begin_inset Quotes eld
\end_inset

enlarged
\begin_inset Quotes erd
\end_inset

 to support two implicit endpoints: one before the first argument and one
 after the last argument.
 We refer to the first role as an 
\begin_inset Quotes eld
\end_inset

adviser
\begin_inset Quotes erd
\end_inset

 or 
\family typewriter
Layer
\family default

\begin_inset LatexCommand index
name "Layer (object)"

\end_inset

, and to the second as a 
\family typewriter
Subject
\begin_inset LatexCommand index
name "Subject (object)"

\end_inset


\family default
 or 
\begin_inset Quotes eld
\end_inset

interleaver
\begin_inset Quotes erd
\end_inset

.
 The layer role, being 
\begin_inset Quotes eld
\end_inset

to the left
\begin_inset Quotes erd
\end_inset

 of the explicit argument positions, has higher precedence than any of them;
 the subject role has a correspondingly opposite role: it has the lowest
 precedence of all.
\end_layout

\begin_layout Enumerate
\begin_inset LatexCommand index
name "seenFrom: (message)"

\end_inset

Two primitive context-handling methods were added to support invoking code
 with a different object used for one of these new roles.
 What happens is that you execute a block 
\family typewriter
[]\InsetSpace ~
seenFrom:\InsetSpace ~
someSubject
\family default
 in order to make all methods defined within dispatched with that object
 as the subject, and all methods looked up in that context (or any other
 context 
\begin_inset Quotes eld
\end_inset

seen from
\begin_inset Quotes erd
\end_inset

 that object) used with that subject in the dispatch.
\end_layout

\begin_layout Standard
The effect of combining these two mechanisms is that there is a means for
 the user to dynamically (and transparently) extend existing libraries.
 The 
\family typewriter
Layer
\family default
 usage has a more 
\begin_inset Quotes eld
\end_inset

absolute
\begin_inset Quotes erd
\end_inset

 power to override, since without dispatching on any other arguments, a
 method defined in a layer will match a message before any other can.
 The 
\family typewriter
Subject
\family default
 usage has a more fine-tuned (or weaker, in another sense) ability to override,
 since without any other dispatching, a method defined with a certain subject
 will never be called.
 However, taking an existing method's signature and defining a customized
 version with a subject will allow customizing that specific method without
 affecting any other method with that selector.
\end_layout

\begin_layout Paragraph
Important features
\end_layout

\begin_layout Itemize
Methods defined with a special subject or layer 
\emph on
persist
\emph default
 with those objects, since they are just dispatch participants accessible
 via roles.
\end_layout

\begin_layout Itemize
Resending messages works just the same within subjective methods as in normal
 methods; the same dispatch mechanism is in effect, so the ability to combine
 or extend functionality is available.
\end_layout

\begin_layout Itemize
Nesting subjective scopes has a 
\emph on
dynamic scoping
\emph default
 effect: the actions taken within have run-time scope instead of corresponding
 exactly to how code is lexically defined.
 This gives the compositional effect that should be apparent when viewing
 nested subjective scopes.
\end_layout

\begin_layout Itemize
Methods defined in non-subjective contexts have no subject or layer rather
 than any 
\begin_inset Quotes eld
\end_inset

default
\begin_inset Quotes erd
\end_inset

 subject: they are for most purposes, 
\begin_inset Quotes eld
\end_inset

objective
\begin_inset Quotes erd
\end_inset

.
\end_layout

\begin_layout Paragraph
The core elements
\end_layout

\begin_layout Description

\family typewriter
Subject
\begin_inset LatexCommand index
name "subject (terminology)"

\end_inset


\family default
 the type of object which provides an appropriate handle for subjective
 interleaving behavior in dynamically overriding or extending other methods'
 behaviors.
\end_layout

\begin_layout Description

\family typewriter
Layer
\begin_inset LatexCommand index
name "layer (terminology)"

\end_inset


\family default
 the type of object which provides an appropriate handle for subjective
 layering behavior in dynamically overriding or extending other methods'
 behaviors.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "seenFrom: (message)"

\end_inset

[]\InsetSpace ~
seenFrom:\InsetSpace ~
aSubject
\family default
 executes the contents of the block with the given 
\family typewriter
Subject
\family default
 dynamically affecting the execution of the expressions.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "layering: (message)"

\end_inset

aLayer\InsetSpace ~
layering:\InsetSpace ~
[]
\family default
 executes the contents of the block with the given 
\family typewriter
Layer
\family default
 dynamically affecting the execution of the expressions.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "withoutSubject (message)"

\end_inset

[]\InsetSpace ~
withoutSubject
\family default
 executes the contents of the block without any subject.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "withoutLayers (message)"

\end_inset

[]\InsetSpace ~
withoutLayers
\family default
 executes the contents of the block without any layer.
\end_layout

\begin_layout Subsection
Type Annotations
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "type annotations"

\end_inset

Input and local slots' types can be specified statically for performance
 or documentation reasons, if desired.
 The special character 
\begin_inset LatexCommand index
name "bang character"

\end_inset


\begin_inset LatexCommand index
name "exclamation mark"

\end_inset


\begin_inset LatexCommand index
name "\\char `\\! (exclamation mark)"

\end_inset


\begin_inset Quotes eld
\end_inset


\family typewriter
!
\family default

\begin_inset Quotes erd
\end_inset

 is used in the same manner as the dispatch annotation 
\begin_inset Quotes eld
\end_inset


\family typewriter
@
\family default

\begin_inset Quotes erd
\end_inset

, but type-annotations can occur anywhere.
 The type system and inference system in Slate is part of the standard library,
 and so is explained later in 
\begin_inset LatexCommand vref
reference "sub:Types"

\end_inset

.
 
\end_layout

\begin_layout Subsection
Macro Message-sends
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "macro message-sends"

\end_inset


\begin_inset LatexCommand index
name "message-sends, macro"

\end_inset

In order to manipulate syntax trees or provide annotations on source code,
 Slate provides another form of message-send called a 
\emph on
macro-level
\emph default
 message send.
 Sends of this sort have as their arguments the objects built for the expression
s' shapes.
 Furthermore, the results of evaluation of macro-sends are placed in the
 syntax tree in the same location as the macro-send occupied.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "` (back-tick)"

\end_inset


\begin_inset LatexCommand index
name "back-tick"

\end_inset

Preceding any selector with a back-tick (
\family typewriter
`
\family default
) will cause it to be sent as a macro.
 This means that the message sent will be dispatched on Slate's 
\family typewriter

\begin_inset LatexCommand index
name "Syntax Node (object)"

\end_inset

Syntax\InsetSpace ~
Node
\family default
 objects, which are produced by the parser and consumed by the compiler.
 Macros fit into the process of compiling in this order: the text is processed
 by the 
\family typewriter
Lexer
\begin_inset LatexCommand index
name "Lexer (object)"

\end_inset


\family default
 into a stream of tokens, which are consumed by the 
\family typewriter
Parser
\begin_inset LatexCommand index
name "Parser (object)"

\end_inset


\family default
 to produce a (tree-)stream of 
\family typewriter
Syntax\InsetSpace ~
Node
\family default
s.
 Before being passed to the compiler, the 
\family typewriter
macroexpand
\begin_inset LatexCommand index
name "macroexpand (message)"

\end_inset


\family default
 method is recursively called on these syntax trees, which invokes every
 macro-level message-send and performs the mechanics of replacing the macro-send
 with the result of the method invoked.
 With this in mind, the Slate macro system is offered as a flexible communicatio
n system between the code-writer and the compiler or other tools or even
 other users, using parse trees as the medium.
\end_layout

\begin_layout Standard
As an example of the expressiveness of this system, we can express the type
 annotation and comment features of the Slate language in terms of macros:
\end_layout

\begin_layout Itemize
Type-annotation via 
\begin_inset Quotes eld
\end_inset


\family typewriter
expression!type
\family default

\begin_inset Quotes erd
\end_inset

 could be replaced by 
\begin_inset Quotes eld
\end_inset


\family typewriter
someExpression `type: assertedTypeExpression
\family default

\begin_inset Quotes erd
\end_inset

 where the 
\family typewriter
`type:
\family default
 macro simply sets the 
\family typewriter
type
\family default
 slot for the expression object.
\end_layout

\begin_layout Itemize
Comments could be applied specifically to particular expressions.
 For example, following a syntax element with a comment could be implemented
 by 
\begin_inset Quotes eld
\end_inset


\family typewriter
theExpression `comment: commentString
\family default

\begin_inset Quotes erd
\end_inset

, wrapping the syntax node with a comment annotation.
\end_layout

\begin_layout Itemize
Compile-time evaluation of any expression can be accomplished by calling
 
\family typewriter
`evaluate
\family default
 on it.
 This also subsumes the 
\family typewriter
#
\family default
-prefix for array literals and expression sequences which accomplishes that
 for those syntax forms.
\end_layout

\begin_layout Subsubsection
Defining new Macro-methods
\end_layout

\begin_layout Standard
Macros must be dispatched (if at all) upon the traits of expressions' syntactic
 representation.
 This introduces a few difficulties, in that some familiarity is needed
 with the parse node types in order to name them.
 However, only two things need to be remembered:
\end_layout

\begin_layout Enumerate
The generic syntax node type is 
\family typewriter
Syntax\InsetSpace ~
Node\InsetSpace ~
traits
\family default
, and this is usually all that is necessary for basic macro-methods.
\end_layout

\begin_layout Enumerate
Syntax node types of various objects and specific expression types can be
 had by simply quoting them and asking for their traits, although this might
 be too specific in some cases.
 For example, 
\family typewriter
4\InsetSpace ~
`quote\InsetSpace ~
traits
\family default
 is suitable for dispatching on Integers, but not Numbers in general, or
 
\family typewriter
(3\InsetSpace ~
+\InsetSpace ~
4)\InsetSpace ~
`quote\InsetSpace ~
traits
\family default
 will help dispatch on binary message-sends, but not all message-sends.
 Luckily, 
\family typewriter
[]\InsetSpace ~
`quote\InsetSpace ~
traits
\family default
 works for blocks as well as methods.
\end_layout

\begin_layout Subsubsection
Quoting and Unquoting
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "quoting"

\end_inset


\begin_inset LatexCommand index
name "unquoting"

\end_inset


\begin_inset LatexCommand index
name "`quote (message)"

\end_inset


\begin_inset LatexCommand index
name "`unquote (message)"

\end_inset

A fundamental application of the macro message-send system is the ability
 to obtain syntax trees for any expression at run-time.
 The most basic methods for this are 
\family typewriter
`quote
\family default
, which causes the surrounding expression to use its quoted value as the
 input for even normal methods, and 
\family typewriter
`unquote
\family default
 results in an inversion of the action of 
\family typewriter
`quote
\family default
, so it can only be provided within quoted expressions.
\end_layout

\begin_layout Standard
An abbreviated form of quotation may be used by surrounding an expression
 with 
\family typewriter
`()
\family default
 which has the same effect as sending 
\family typewriter
`quote
\family default
.
 The parentheses may be omitted if the inner expression cannot be interpreted
 as a message-send (applicable to literal blocks, arrays, numbers, and so
 on).
\begin_inset Foot
status collapsed

\begin_layout Standard
Lisp macro system users will note that this effectively makes 
\family typewriter
`quote
\family default
 the same as quasi-quotation.
\end_layout

\end_inset


\end_layout

\begin_layout Paragraph
Labelled Quotation
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "quotation, labelled"

\end_inset


\begin_inset LatexCommand index
name "labelled quotation"

\end_inset

In experience with Lisp macros, nested quotation is often found necessary.
 In order to adequately control this, often the quotation prefix symbols
 have to be combined in non-intuitive ways to produce the correct code.
 Slate includes, as an alternative, two operations which set a label on
 a quotation and can unquote within that to the original quotation by means
 of referencing the label.
\end_layout

\begin_layout Standard
Most users need time to develop the understanding of the need for higher-order
 macros, and this relates to users who employ them.
 For reference, a Lisp book which covers the subject of higher-order macros
 better than any other is 
\emph on
On Lisp
\emph default

\begin_inset LatexCommand cite
key "OnLisp"

\end_inset

.
 However, it's also been said that Lisp's notation and the conceptual overhead
 required to manage the notation in higher-order macros keeps programmers
 from entering the field, so perhaps this new notation will help.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "`quote: (message)"

\end_inset


\begin_inset LatexCommand index
name "`unquote: (message)"

\end_inset

The operators are 
\family typewriter
expr1\InsetSpace ~
`quote:\InsetSpace ~
aLiteral
\family default
 and 
\family typewriter
expr2\SpecialChar \-
\InsetSpace ~
`unquote:\SpecialChar \-
\InsetSpace ~
aLiteral
\family default
, and in order for this to work syntactically, the labels must be equal
 in value and must be literals.
 As well, the unquoting expression has to be a sub-expression of the quotation.
 The effect is that nesting an expression more deeply does not require altering
 the quotation operators to compensate, and it does indicate better what
 the unquoting is intended to do\SpecialChar \@.

\end_layout

\begin_layout Subsubsection
Message Cascading
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "cascade, message"

\end_inset


\begin_inset LatexCommand index
name "message cascading"

\end_inset


\begin_inset LatexCommand index
name "`>> (macro)"

\end_inset

Many object-oriented code idioms involve repeated message-sends to the same
 object.
 This is common in creating and setting up a new object, or activating many
 behaviors in sequence on the same thing (used in a lot of UI code - or
 more generally with objects that have many variables or are "facade" objects).
 Take notice of the period after the last message in the block.
 If you forget, you'll return the last result instead of the original object
 your cascading into.
\end_layout

\begin_layout Standard
Smalltalk-80 included a syntax feature to elide the first argument when
 repeating message-sends.
 In Slate, the first argument of a message send is not a special "receiver",
 so support in the basic syntax does not make sense.
 The solution is a macro-method which takes an expression (well, its result)
 and a block, and enhances the block so that the result of the expression
 becomes the implicit context for statement-level (top-level) message expression
s.
 For example:
\end_layout

\begin_layout LyX-Code
Slate> (addPrototype: #Something derivedFrom: {Cloneable})
\newline
  `>> [addSlot:
 #foo.
 addSlot: #bar.
 ].
\end_layout

\begin_layout LyX-Code

\end_layout

\begin_layout LyX-Code
("Something traitsWindow" bar: Nil.
 foo: Nil)
\end_layout

\begin_layout Standard
In this expression, a prototype is created and returned by the first expression,
 and the block is evaluated with that object substituted for the context,
 so that the 
\family typewriter
addSlot:
\family default
 calls apply to it directly.
 We recommend you don't define things this way.
 Instead use 
\family typewriter
namespace define: #Something &parents: {Cloneable} &slots: {#foo -> Nil.
 #bar -> Nil }.
\end_layout

\begin_layout Standard
There is an additional possibility that it takes care of by allowing the
 user to specify an input variable to the block, which will also allow the
 code within to refer to the object explicitly.
 Also, the default return value for empty-last-statements is modified to
 be this object instead of the usual 
\family typewriter
Nil
\family default
.
 Without such features, a method which returns its only argument is needed;
 in Smalltalk-80, the 
\family typewriter
yourself
\family default
 method performs this role at the end of a cascade.
 To see the effect this would have on Slate library code, take a collection
 creation method as an example:
\end_layout

\begin_layout LyX-Code
set@(Set traits) new &capacity: n
\newline
[| newSet |
\newline
  newSet: set clone.
\newline
  newSet
 contents: (set contents new &capacity: ((n ifNil: [0]) max: 1)).
\newline
  newSet
 tally: 0.
\newline
  newSet
\newline
].
\end_layout

\begin_layout Standard
could become:
\end_layout

\begin_layout LyX-Code
set@(Set traits) new &capacity: n
\newline
[set clone `>>
\newline
  [contents: (set contents
 new &capacity: ((n ifNil: [0]) max: 1)).
\newline
  tally: 0.
 ]
\newline
].
\end_layout

\begin_layout Standard
So in this new method, an object is made by cloning the argument 
\family typewriter
Set
\family default
, and then the contents and tally are assigned as before, but not needing
 to refer to the object explicitly, and then returning the object (if the
 ending period is left off, it'll return the value of the last explicit
 expression, just as normal blocks).
 However, the message-sends which are not leading a statement do not (and
 cannot) use the object as implicit context.
 This is intentional, as the results of this kind of pervasive change are
 more drastic and would be an entirely different kind of idiom.
 If a reference to the implicit context argument is needed in the block,
 an input argument may be specified in the block header, and the macro method
 will bind it to that object.
 A notable property of the 
\family typewriter
`>>
\family default
 method, since it returns resulting values and has a binary selector, is
 composability in a data-flow manner.
\end_layout

\begin_layout Subsubsection
Slots as Block Variables
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "`withSlotsDo: (macro)"

\end_inset

Another macro allows for the slots of an object to appear as local variables
 in a method, responding both to accessors and mutators in the appropriate
 way (by modifying the object's slots).
\end_layout

\begin_layout Standard
So, the following expression names some slots in the first argument which
 should be available as inputs to the second argument, a block.
 This is analogous to having Smalltalk's direct slot reference syntax (or
 Self's, for that matter), or to Lisp's with-slots macro.
 (Again, you shouldn't generally shouldn't create objects this way.)
\end_layout

\begin_layout LyX-Code
Slate> Cloneable clone 
\newline
  `>> [addSlot: #x valued: 2.
 addSlot: #y valued: 2]
\newline
  `withSlotsDo: [| :x :y | x + y].
 
\newline
4
\end_layout

\begin_layout Subsubsection
Expression Substitution (Not Yet Implemented)
\begin_inset OptArg
status open

\begin_layout Standard
Expression Substitution
\end_layout

\end_inset


\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "`with:as: (message)"

\end_inset

`with:as:
\family default
 is a proposed protocol for transparent substitution of temporary or locally-pro
vided proxies for environment values and other system elements.
 This should provide an effective correspondent of the functionality of
 Lisp's "
\family typewriter
with-
\family default
" style macros.
\end_layout

\begin_layout Subsubsection
Source Pattern-matching (Not Yet Implemented)
\begin_inset OptArg
status collapsed

\begin_layout Standard
Source Pattern Matching
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "pattern-matching"

\end_inset

A future framework for expansion will involve accommodating the types of
 source-level pattern-matching used in tools for manipulating code for developme
nt, as in the Smalltalk Refactoring Browser.
\end_layout

\begin_layout Subsection
Literal Syntax
\begin_inset OptArg
status collapsed

\begin_layout Standard
Literals
\end_layout

\end_inset


\begin_inset LatexCommand index
name "literal syntax"

\end_inset


\begin_inset LatexCommand index
name "syntax, literal"

\end_inset


\end_layout

\begin_layout Subsubsection
Numbers
\end_layout

\begin_layout Paragraph
Integers
\end_layout

\begin_layout Standard
Integers are read in as an arbitrary-precision sequence of digits, without
 separators.
\end_layout

\begin_layout Paragraph
Floats
\end_layout

\begin_layout Standard
Floats are read in as an arbitrary-precision sequence of digits, with a
 period noting the decimal position.
\end_layout

\begin_layout Paragraph
Radix Prefixes
\end_layout

\begin_layout Standard
Integers or Floats may be entered with radix up to 36, using the digits
 0 to 9 and then A to Z in order, by prefixing the literal with the radix
 (numeric base) and '
\family typewriter
r
\family default
'.
 So 
\family typewriter
3r100
\family default
 evaluates to 9, and 
\family typewriter
2r0.1
\family default
 evaluates to 
\family typewriter
0.5
\family default
.
 Case is disregarded for the extra-decimal digits.
 The Float radix notation is always read in as a Float, and not an infinite-prec
ision Fraction.
\end_layout

\begin_layout Subsubsection
Characters
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "characters"

\end_inset


\begin_inset LatexCommand index
name "dollar sign"

\end_inset


\begin_inset LatexCommand index
name "\\$ (dollar sign)"

\end_inset

Slate's default support for character literals uses the 
\family typewriter
$
\family default
 symbol as a prefix.
 For example, 
\family typewriter
$a
\family default
, 
\family typewriter
$3
\family default
, 
\family typewriter
$>
\family default
, and 
\family typewriter
$$
\family default
 are all Character object literals for 
\family typewriter
a
\family default
, 
\family typewriter
3
\family default
, 
\family typewriter
>
\family default
, and 
\family typewriter
$
\family default
, respectively.
 Printable and non-printable characters require backslash escapes as shown
 and listed in Table 
\begin_inset LatexCommand vref
reference "cap:Character-Literal-Escapes"

\end_inset

.
\end_layout

\begin_layout Standard
\align center
\begin_inset LatexCommand index
name "characters, special"

\end_inset


\begin_inset LatexCommand index
name "special characters"

\end_inset


\begin_inset LatexCommand index
name "escape (character literal)"

\end_inset


\begin_inset LatexCommand index
name "newline (character literal)"

\end_inset


\begin_inset LatexCommand index
name "carriage return (character literal)"

\end_inset


\begin_inset LatexCommand index
name "tab (character literal)"

\end_inset


\begin_inset LatexCommand index
name "backspace (character literal)"

\end_inset


\begin_inset LatexCommand index
name "null (character literal)"

\end_inset


\begin_inset LatexCommand index
name "bell (character literal)"

\end_inset


\begin_inset LatexCommand index
name "form feed (character literal)"

\end_inset


\begin_inset LatexCommand index
name "vertical feed (character literal)"

\end_inset


\begin_inset LatexCommand index
name "space (character literal)"

\end_inset


\begin_inset LatexCommand index
name "backslash (character literal)"

\end_inset


\begin_inset Float table
placement h
wide false
sideways false
status open

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="12" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Character name
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Literal
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Escape
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
e
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Newline
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
n
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Carriage Return
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
r
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Tab
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
t
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Backspace
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
b
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Null
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
0
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Bell
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
a
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Form Feed
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
f
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Vertical Feed
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
v
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Space
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash
s
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Backslash
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
$
\backslash

\backslash

\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Character-Literal-Escapes"

\end_inset

Character Literal Escapes
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Strings
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "strings"

\end_inset


\begin_inset LatexCommand index
name "quotes, single"

\end_inset


\begin_inset LatexCommand index
name "single quotes"

\end_inset


\begin_inset LatexCommand index
name "' (single quote)"

\end_inset

Strings are comprised of any sequence of characters surrounded by single-quote
 characters.
 Strings can include the commenting character (double-quotes) without an
 escape.
 Embedded single-quotes can be provided by using the backslash character
 to escape them (
\family typewriter

\backslash
'
\family default
).
 Slate's character literal syntax also embeds into string literals, omitting
 the 
\family typewriter
$
\family default
 prefix.
 All characters that require escapes in character literal syntax also require
 escapes when used within string literals, with the exception of double-quote
 marks and the addition of single-quote marks.
\end_layout

\begin_layout Standard
The following are all illustrative examples of Strings in Slate:
\end_layout

\begin_layout LyX-Code
'a string comprises any sequence of characters, surrounded by single quotes'
\end_layout

\begin_layout LyX-Code
'strings can include the "comment delimiting" character'
\end_layout

\begin_layout LyX-Code
'and strings can include embedded single quote characters by escaping
\backslash
' them'
\end_layout

\begin_layout LyX-Code
'strings can contain embedded
\end_layout

\begin_layout LyX-Code
newline characters'
\end_layout

\begin_layout LyX-Code
'and escaped 
\backslash
ncharacters'
\end_layout

\begin_layout LyX-Code
'
\begin_inset ERT
status inlined

\begin_layout Standard

{}
\end_layout

\end_inset

' "and don't forget the empty string"
\end_layout

\begin_layout Subsubsection
Symbols
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "symbols"

\end_inset


\begin_inset LatexCommand index
name "pound sign"

\end_inset


\begin_inset LatexCommand index
name "\\# (pound sign)"

\end_inset


\family typewriter
Symbol
\family default
 literal syntax starts with the pound sign character (
\family typewriter
#
\family default
) and consists of all following characters up to the next non-escaped whitespace
 or reserved character (whichever comes first), unless the pound sign is
 followed exactly by a string literal (in single quotes), in which case
 the string's contents become the identifier for the 
\family typewriter
Symbol
\family default
.
 So, for example, the following are all valid 
\family typewriter
Symbol
\family default
s and 
\family typewriter
Symbol
\family default
 literals:
\end_layout

\begin_layout LyX-Code
#$
\end_layout

\begin_layout LyX-Code
#20
\end_layout

\begin_layout LyX-Code
#+
\end_layout

\begin_layout LyX-Code
#key:word:expression:
\end_layout

\begin_layout LyX-Code
#something_with_underscores
\end_layout

\begin_layout LyX-Code
#'A full string with a 
\backslash
nnewline in it.'
\end_layout

\begin_layout LyX-Code
#'@'
\end_layout

\begin_layout Standard
A property of 
\family typewriter
Symbols
\family default
 and their literals is that any literal with the same value as another also
 refers to the 
\emph on
same instance
\emph default
 as any other 
\family typewriter
Symbol
\family default
 literal with that value in a Slate system.
 This allows fast hashes and comparisons by identity rather than value hashes.
 In particular, as with Slate identifiers, a 
\family typewriter
Symbol
\family default
's value is case-sensitive, so 
\family typewriter
#a
\family default
 and 
\family typewriter
#A
\family default
 are distinct.
\end_layout

\begin_layout Standard
Internally, Slate currently keeps one global table for 
\family typewriter
Symbol
\family default
s, and uses individual context objects to hold local bindings.
\begin_inset Foot
status open

\begin_layout Standard
Future, bootstrapped releases may provide for partitioning of the global
 table.
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Arrays
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "arrays"

\end_inset


\begin_inset LatexCommand index
name "literal arrays"

\end_inset


\begin_inset LatexCommand index
name "curly braces"

\end_inset


\begin_inset LatexCommand index
name "\\{\\} (curly braces)"

\end_inset

Arrays can be literally and recursively specified by curly-brace notation
 using stops as separators.
 
\begin_inset LatexCommand index
name "array indices"

\end_inset


\begin_inset LatexCommand index
name "indices, array"

\end_inset

Array indices in Slate are 0-based.
 So:
\end_layout

\begin_layout LyX-Code
{4.
 5.
 {foo.
 bar}}.
\end_layout

\begin_layout Standard
returns an array with 4 in position 0, 5 at 1, and an array with objects
 
\family typewriter
foo
\family default
 and 
\family typewriter
bar
\family default
 inserted into it at position 2.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "array syntax, immediate"

\end_inset


\begin_inset LatexCommand index
name "immediate array syntax"

\end_inset


\begin_inset LatexCommand index
name "pound sign"

\end_inset


\begin_inset LatexCommand index
name "\\# (pound sign)"

\end_inset

Immediate array syntax - 
\family typewriter
#{4.\InsetSpace ~
5.\InsetSpace ~
{foo.\InsetSpace ~
bar}}
\family default
 - is provided as an alternative to create the array when the method is
 compiled, instead of creating a new array on each method invocation.
 The syntax is identical except that the first opening brace is preceded
 by the pound sign.
 The disadvantage is that no run-time values will be usable.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "array syntax, literal"

\end_inset


\begin_inset LatexCommand index
name "literal array syntax"

\end_inset


\begin_inset LatexCommand index
name "() (parentheses)"

\end_inset


\begin_inset LatexCommand index
name "parentheses"

\end_inset

A special 
\begin_inset Quotes eld
\end_inset

literal array
\begin_inset Quotes erd
\end_inset

 syntax is also provided, in the manner of Smalltalk-80,
\begin_inset LatexCommand index
name "Smalltalk"

\end_inset

 in which all tokens within are treated symbolically, evaluating to an array
 of literals as read (but not evaluated) by Slate.
 Naturally, these are all evaluated when the surrounding context is compiled.
 For example:
\end_layout

\begin_layout LyX-Code
Slate> #(1 2 3).
\newline

\emph on
{1.
 2.
 3}
\emph default

\newline
Slate> #(3 + 4).
\newline

\emph on
{3.
 #'+'.
 4}
\emph default

\newline
Slate> #(quux: a :bar).
\newline

\emph on
{#quux:.
 #a.
 #:bar}
\emph default

\newline
Slate> #(1 .
 _ 2e3).
\newline

\emph on
{1.
 #'.'.
 #_.
 2000.0}
\end_layout

\begin_layout Subsubsection
Blocks
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "blocks"

\end_inset


\begin_inset LatexCommand index
name "square brackets"

\end_inset


\begin_inset LatexCommand index
name "[] (square brackets)"

\end_inset

Block syntax basics were covered in 
\begin_inset LatexCommand ref
reference "sub:Block-Closures"

\end_inset

; the precise, full specification includes more features and outlines some
 necessary logical rules.
 Primarily, blocks are square-bracket-delimited statement sequences with
 an optional header that specifies input and local slots (input slots being
 
\emph on
arguments
\emph default
).
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "colon character"

\end_inset


\begin_inset LatexCommand index
name ": (colon)"

\end_inset

Slot names must be valid unary message selectors (see 
\begin_inset LatexCommand ref
reference "sub:Unary-Message-sends"

\end_inset

).
 Inputs are distinguished by a prefix colon character (
\family typewriter
:
\family default
), and must occur in the same positional order that the invocation will
 use or expect, although they can be interspersed among other slot declarations
 at will.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "optional keyword arguments"

\end_inset


\begin_inset LatexCommand index
name "arguments, optional keyword"

\end_inset


\begin_inset LatexCommand index
name "keyword arguments, optional"

\end_inset


\begin_inset LatexCommand index
name "\\& (ampersand)"

\end_inset


\begin_inset LatexCommand index
name "ampersand"

\end_inset

Optional keyword arguments are specified with an ampersand prefix character
 (
\family typewriter
&
\family default
), and may occur in any order.
\end_layout

\begin_layout Standard
For example,
\end_layout

\begin_layout LyX-Code
[| x :y &z :w | ]
\end_layout

\begin_layout Standard
evaluates to a block which takes inputs 
\family typewriter
y
\family default
 and 
\family typewriter
w
\family default
 in that order, has locals 
\family typewriter
x
\family default
 (and 
\family typewriter
z
\family default
), and takes an optional parameter to specify 
\family typewriter
z
\family default
's value when called.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "rest arguments"

\end_inset


\begin_inset LatexCommand index
name "arguments, rest"

\end_inset


\begin_inset LatexCommand index
name "\\* (asterisk)"

\end_inset


\begin_inset LatexCommand index
name "asterisk"

\end_inset

A single 
\begin_inset Quotes eld
\end_inset

rest
\begin_inset Quotes erd
\end_inset

 parameter which becomes an array containing all extra positional (non-keyword)
 arguments passed may be specified once in the header in any position relative
 to the other parameters, prefixed with an asterisk (e.g.
 
\family typewriter
*rest
\family default
).
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "compile-time blocks"

\end_inset


\begin_inset LatexCommand index
name "blocks, compile-time"

\end_inset


\begin_inset LatexCommand index
name "\\#[] (pound-square brackets)"

\end_inset

Blocks may be used to perform arbitrary compile-time calculations, using
 the 
\family typewriter
#
\family default
-prefix as used for literal arrays and strings.
 So 
\family typewriter
#[3\InsetSpace ~
+\InsetSpace ~
4]
\family default
 will result in 
\family typewriter
7
\family default
 in the resulting code for the surrounding context (perhaps a method or
 top-level expression), as though the block were never there.
\end_layout

\begin_layout Section
The Slate World
\end_layout

\begin_layout Subsection
Overall Organization
\end_layout

\begin_layout Subsubsection
The lobby
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "lobby (object)"

\end_inset


\begin_inset LatexCommand index
name "objects, global"

\end_inset


\begin_inset LatexCommand index
name "global objects"

\end_inset

The 
\family typewriter
lobby
\family default
 is the root namespace object for the Slate object system; it is the 
\begin_inset Quotes eld
\end_inset

room
\begin_inset Quotes erd
\end_inset

 by which objects enter the Slate world.
 All 
\begin_inset Quotes eld
\end_inset

global
\begin_inset Quotes erd
\end_inset

 objects are really only globally accessible because the lobby is delegated
 to by lexical contexts, directly or indirectly.
 The lobby in turn may (and often does) delegate to other namespaces which
 contain different categorized objects of interest to the applications programme
r, and this can be altered at run-time.
\end_layout

\begin_layout Standard
Every object reference which is not local to a block closure is sent to
 the enclosing namespace for resolution, which by default is the root namespace,
 the 
\family typewriter
lobby
\family default
 (nested closures refer first to their surrounding closure).
 
\begin_inset LatexCommand index
name "lobby (slot)"

\end_inset

The 
\family typewriter
lobby
\family default
 contains a loopback slot referring to itself by that name.
 To add or arrange globals, either implicit sends or explicit references
 to the lobby can be made.
 (Consider it good style to directly reference it.)
\end_layout

\begin_layout Standard
The lobby is essentially a threading context, and in the future bootstrap
 will be instantiable in that sense.
\end_layout

\begin_layout Subsubsection
Naming and Paths
\end_layout

\begin_layout Standard
The 
\family typewriter
lobby
\family default
 provides access to the major 
\family typewriter
Namespaces
\family default

\begin_inset LatexCommand index
name "Namespace (object)"

\end_inset

, which are objects suitable for organizing things (for now, they are essentiall
y just 
\family typewriter
Cloneable
\family default
 objects).
 The most important one is 
\family typewriter
prototypes
\family default

\begin_inset LatexCommand index
name "prototypes (object)"

\end_inset

, which contains the major kinds of shared behavior used by the system.
 Objects there may be cloned and used directly, but they should not themselves
 be manipulated without some design effort, since these are global resources,
 having a name-path identifier which can be freely shared.
 
\family typewriter
prototypes
\family default
 is inherited by the lobby, so it is not necessary to use the namespace
 path to identify, for example, 
\family typewriter
Collection
\family default
 or 
\family typewriter
Boolean
\family default
.
 However, without explicitly mentioning the path, adding slots will use
 the lobby or the local context by default.
 To use the current namespace, an implicit-context message 
\family typewriter
here
\begin_inset LatexCommand index
name "here (message)"

\end_inset


\family default
 is provided which will answer the nearest surrounding namespace object
 in the context, which is the 
\family typewriter
lobby
\family default
 by default, but is polymorphic to namespace shifts.
\end_layout

\begin_layout Standard
The 
\family typewriter
prototypes
\family default
 namespace further contains inherited namespaces for, by example, collections,
 and can be otherwise enhanced to divide up the system into manageable pieces.
\end_layout

\begin_layout Subsection
Core Behaviors
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement htbp
wide true
sideways false
status open

\begin_layout Standard
\begin_inset VSpace defskip
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Graphics
        filename core-web.eps

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace defskip
\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Core-delegation"

\end_inset

Core Object Inheritance
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
Slate defines several subtle variations on the core behavior of objects:
\end_layout

\begin_layout Description

\family typewriter
Root
\begin_inset LatexCommand index
name "Root (object)"

\end_inset


\family default
 The "root" object, upon which all the very basic methods of slot manipulation
 are defined.
\end_layout

\begin_layout Description

\family typewriter
Oddball
\begin_inset LatexCommand index
name "Oddball (object)"

\end_inset


\family default
 The branch of 
\family typewriter
Root
\family default
 representing non-cloneable objects.
 These include built-in 'constants' such as the 
\family typewriter
Boolean
\family default
s, as well as literals (value-objects) such as 
\family typewriter
Character
\family default
s and 
\family typewriter
Symbol
\family default
s.
 Note that 
\family typewriter
Oddball
\family default
 itself defines a 
\family typewriter
clone
\begin_inset LatexCommand index
name "clone (message)"

\end_inset


\family default
 method, but that method will only work once, in that you can clone 
\family typewriter
Oddball
\family default
 but not objects made by cloning 
\family typewriter
Oddball
\family default
.
\end_layout

\begin_layout Description

\family typewriter
Nil
\begin_inset LatexCommand index
name "Nil (object)"

\end_inset


\family default
 
\family typewriter
Nil
\family default
 is an 
\family typewriter
Oddball
\family default
 representing "no-object".
\end_layout

\begin_layout Description

\family typewriter
NoRole
\begin_inset LatexCommand index
name "NoRole (object)"

\end_inset


\family default
 
\family typewriter
NoRole
\family default
 is an 
\family typewriter
Oddball
\family default
 representing a non-dispatching participant in a method definition.
 Methods cannot be defined directly on 
\family typewriter
NoRole
\family default
.
\end_layout

\begin_layout Description

\family typewriter
Derivable
\begin_inset LatexCommand index
name "Derivable (object)"

\end_inset


\family default
 
\family typewriter
Derivable
\family default
 objects respond to 
\family typewriter
derive
\begin_inset LatexCommand index
name "derive (message)"

\end_inset


\family default
, which means they can be readily used for extension.
\end_layout

\begin_layout Description

\family typewriter
Cloneable
\begin_inset LatexCommand index
name "Cloneable (object)"

\end_inset


\family default
 A 
\family typewriter
Derivable
\family default
 that can be 
\family typewriter
clone
\family default
d.
\end_layout

\begin_layout Description

\family typewriter
Method
\begin_inset LatexCommand index
name "Method (object)"

\end_inset


\family default
 A 
\family typewriter
Cloneable
\family default
 object with attributes for supporting execution of blocks (with closure
 semantics, notably) and holding compiled code and its attributes.
\end_layout

\begin_layout Subsubsection
Default Object Features
\end_layout

\begin_layout Description
Identity
\begin_inset LatexCommand index
name "identity (terminology)"

\end_inset


\begin_inset LatexCommand index
name "== (message)"

\end_inset


\begin_inset LatexCommand index
name "\\~{}== (message)"

\end_inset

 
\family typewriter
==
\family default
 returns whether the two arguments are identical, i.e.
 the same object, and 
\family typewriter

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
~{}
\end_layout

\end_inset

==
\family default
 is its negation.
 Value-equality (
\family typewriter
=
\family default
 and its negation 
\family typewriter

\begin_inset ERT
status collapsed

\begin_layout Standard


\backslash
~{}
\end_layout

\end_inset

=
\family default
) defaults to this.
\end_layout

\begin_layout Description
Printing
\begin_inset LatexCommand index
name "printing"

\end_inset

 
\family typewriter
printString
\begin_inset LatexCommand index
name "printString (message)"

\end_inset


\family default
 returns a printed (string) representation of the object.
 
\family typewriter
printOn:
\begin_inset LatexCommand index
name "printOn: (message)"

\end_inset


\family default
 places the result of printing onto a designated 
\family typewriter
Stream
\family default

\begin_inset LatexCommand index
name "Stream (object)"

\end_inset

 (
\family typewriter
print
\begin_inset LatexCommand index
name "print (message)"

\end_inset


\family default
 will invoke 
\family typewriter
printOn:
\family default
 on the 
\family typewriter
Console
\family default
).
 This should be overridden for clarity.
\end_layout

\begin_layout Description
Delegation-testing
\begin_inset LatexCommand index
name "delegation testing"

\end_inset


\begin_inset LatexCommand index
name "testing, delegation"

\end_inset

 
\family typewriter
isReally:
\begin_inset LatexCommand index
name "isReally: message"

\end_inset


\family default
 returns whether the first object has the second (or its traits object if
 it is not a 
\family typewriter
Trait
\family default
) as one of its delegated objects, directly or indirectly.
\end_layout

\begin_layout Description
Kind-testing
\begin_inset LatexCommand index
name "testing, kind"

\end_inset


\begin_inset LatexCommand index
name "kind testing"

\end_inset

 
\family typewriter
is:
\begin_inset LatexCommand index
name "is: (message)"

\end_inset


\family default
 returns whether the first object has the same kind as the second object,
 or some derived kind from the second object's kind.
 By default, 
\family typewriter
is:
\family default
 is 
\family typewriter
isReally:
\family default
; overrides can allow the user to adapt or abuse this notion where delegation
 isn't appropriate but kind-similarity still should hold.
 
\family typewriter
isSameAs:
\begin_inset LatexCommand index
name "isSameAs: (message)"

\end_inset


\family default
 answers whether the arguments have the same traits object.
\end_layout

\begin_layout Description
Hashing
\begin_inset LatexCommand index
name "hashing"

\end_inset

 A quick way to sort by object value that makes searching collections faster
 is the 
\family typewriter
hash
\begin_inset LatexCommand index
name "hash (message)"

\end_inset


\family default
 method, which by default hashes on the object's identity (available separately
 as 
\family typewriter
identityHash
\family default

\begin_inset LatexCommand index
name "identityHash (message)"

\end_inset

), essentially by its birth address in memory.
 More importantly, this is how value-equality
\begin_inset LatexCommand index
name "equality, value"

\end_inset


\begin_inset LatexCommand index
name "value equality"

\end_inset

 is established for collections; if an object type overrides =
\begin_inset LatexCommand index
name "= (equal sign)"

\end_inset


\begin_inset LatexCommand index
name "equal sign"

\end_inset

, it must also override the 
\family typewriter
hash
\family default
 method's algorithm so that 
\family typewriter
a\InsetSpace ~
=\InsetSpace ~
b
\family default
 
\begin_inset Formula $\Rightarrow$
\end_inset

 
\family typewriter
a\InsetSpace ~
hash\InsetSpace ~
=\InsetSpace ~
b\InsetSpace ~
hash
\family default
.
\end_layout

\begin_layout Description
Cloning
\begin_inset LatexCommand index
name "cloning"

\end_inset

 The 
\family typewriter
clone
\begin_inset LatexCommand index
name "clone (message)"

\end_inset


\family default
 method is fundamental for Slate objects.
 It creates and returns a new object identical in slot names and values
 to the argument object, but with a new unique identity.
 As such, it has a very specific meaning and should only be used that way.
\end_layout

\begin_layout Description
Copying
\begin_inset LatexCommand index
name "copying"

\end_inset

 The 
\family typewriter
copy
\begin_inset LatexCommand index
name "copy (message)"

\end_inset


\family default
 method makes a value-equal (
\family typewriter
=
\family default
) object from the argument and returns the new object.
 This should be overridden as necessary where 
\family typewriter
=
\family default
 is overridden.
 The default case is to clone the original object.
\end_layout

\begin_layout Description
Conversion/coercion
\begin_inset LatexCommand index
name "coercion"

\end_inset


\begin_inset LatexCommand index
name "conversion"

\end_inset

 the 
\family typewriter
as:
\begin_inset LatexCommand index
name "as: (message)"

\end_inset


\family default
 protocol provides default conversion methods between types of objects in
 Slate.
 Some primitive types, such as 
\family typewriter
Number
\family default
, override this.
 The 
\family typewriter
as:
\family default
 method has a default implementation on root objects: if no converter is
 found or if the objects are not of the same type, the failure will raise
 a condition.
 Precisely, the behavior of 
\family typewriter
a\InsetSpace ~
as:\InsetSpace ~
b
\family default
 is to produce an object based on 
\family typewriter
a
\family default
 which is as much like 
\family typewriter
b
\family default
 as possible.
\end_layout

\begin_layout Subsubsection
Oddballs
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "oddballs"

\end_inset

There are various 
\family typewriter
Oddball
\family default
s in the system, and they are non-cloneable in general.
 However, 
\family typewriter
Oddball
\family default
 itself may be cloned, for extension purposes.
\end_layout

\begin_layout Subsection
Introspection
\end_layout

\begin_layout Subsubsection
Slot Queries
\end_layout

\begin_layout Standard
Objects may be queried directly for various attributes that they have.
 These should not be used in ordinary 
\begin_inset Quotes eld
\end_inset

non-private
\begin_inset Quotes erd
\end_inset

 code, only in specific uses which need to operate on arbitrary object-slot
 structures or inside of accessor methods.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "atSlotNamed: (message)"

\end_inset

atSlotNamed:
\family default
 answers the value of the slot with the given name.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "atSlotNamed:put: (message)"

\end_inset

atSlotNamed:put:
\family default
 fills the delegate slot with the given name.
 It answers the object modified.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "slotNames (message)"

\end_inset

slotNames
\family default
 answers an 
\family typewriter
Array
\family default
 of the names of the object's direct slots.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "delegates (message)"

\end_inset


\begin_inset ERT
status collapsed

\begin_layout Standard

\family typewriter

\backslash
_{}
\end_layout

\end_inset

delegates
\family default
 answers an 
\family typewriter
Array
\family default
 of the names of the object's direct delegate slots.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "slotsDo: (message)"

\end_inset

slotsDo:
\family default
 applies a block to each slot's value.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "delegatesDo: (message)"

\end_inset

delegatesDo:
\family default
 applies a block to each delegate slot's value.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addAccessorFor: (message)"

\end_inset

addAccessorFor:
\family default
 defines a default accessor (aka 
\begin_inset Quotes eld
\end_inset

getter
\begin_inset Quotes erd
\end_inset

) method for the slot with the given name.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addMutatorFor: (message)"

\end_inset

addMutatorFor:
\family default
 defines a default mutator (aka 
\begin_inset Quotes eld
\end_inset

setter
\begin_inset Quotes erd
\end_inset

) method for the slot with the given name.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addAccessor:for: (message)"

\end_inset

addAccessor:for:
\family default
 installs the given method as accessor for the slot with the given name.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addMutator:for: (message)"

\end_inset

addMutator:for:
\family default
 installs the given method as mutator for the slot with the given name.
\end_layout

\begin_layout Subsubsection
Method Queries
\end_layout

\begin_layout Standard
Slate includes a protocol for common query operations on 
\family typewriter
Method
\family default
 objects:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "selector (message)"

\end_inset

selector
\family default
 answers the 
\family typewriter
Symbol
\family default
 naming the 
\family typewriter
Method
\family default
 if it has been defined and installed under some objects' roles, or 
\family typewriter
Nil
\family default
 if it is unnamed (an ordinary block).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "isNamed (method)"

\end_inset

isNamed
\family default
 answers whether the 
\family typewriter
Method
\family default
 is a named method; that is, whether it is installed with a dispatch signature
 and selector.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "arity (message)"

\end_inset

arity
\family default
 answers the number of arguments expected as input to the 
\family typewriter
Method
\family default
.
 This excludes any optional keyword arguments or rest arguments that it
 may accept.
 This also applies to the quoted form of a literal method.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "acceptsAdditionalArguments (message)"

\end_inset

acceptsAdditionalArguments
\family default
 answers whether the 
\family typewriter
Method
\family default
 takes a rest parameter.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "allSelectorsSent (message)"

\end_inset

allSelectorsSent
\family default
 answers an 
\family typewriter
Array
\family default
 of all 
\family typewriter
Symbol
\family default
s that the block directly (in its defining source) sends.
 This also applies to the quoted form of a literal method.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "methodsNamed: (message)"

\end_inset

methodsNamed:
\family default
 answers all distinct 
\family typewriter
Method
\family default
 objects with the given name stored in roles on the given object.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "methodsAt: (message)"

\end_inset

methodsAt:
\family default
 answers all distinct 
\family typewriter
Method
\family default
 objects stored in the role position given on the given object.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "methodsNamed:at: (message)"

\end_inset

methodsNamed:at:
\family default
 answers all distinct 
\family typewriter
Method
\family default
 objects stored in roles on the given object with the given name and at
 the given role position.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "methodsCalling: (message)"

\end_inset

methodsSending:
\family default
 answers all distinct 
\family typewriter
Method
\family default
 objects stored in roles on the given object which send the given selector.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "signature (message)"

\end_inset

signature\InsetSpace ~
&in:
\family default
 answers a 
\family typewriter
Signature
\family default
 object (roles plus selector) corresponding to the given (named) 
\family typewriter
Method
\family default
's definition.
 This currently involves a search and takes a variable amount of time.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "implementations (message)"

\end_inset

Symbol\InsetSpace ~
implementations
\family default
 answers a 
\family typewriter
Set
\family default
 of all 
\family typewriter
Method
\family default
s whose 
\family typewriter
selector
\family default
 is the argument.
 An 
\family typewriter
&in:
\family default
 optional parameter restricts the search to one object (as namespace).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "callers (message)"

\end_inset

Symbol\InsetSpace ~
senders
\family default
 answers a 
\family typewriter
Set
\family default
 of all 
\family typewriter
Method
\family default
s which send the argument selector.
 An 
\family typewriter
&in:
\family default
 optional parameter restricts the search to one object (as namespace).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "macroCallers (message)"

\end_inset

Symbol\InsetSpace ~
macroSenders
\family default
 answers a 
\family typewriter
Set
\family default
 of all 
\family typewriter
Method
\family default
s which send the argument selector.
 An 
\family typewriter
&in:
\family default
 optional parameter restricts the search to one object (as namespace).
\end_layout

\begin_layout Subsection
Traits
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "traits"

\end_inset

Slate objects, from the root objects down, all respond to the message 
\family typewriter
traits
\family default

\begin_inset LatexCommand index
name "traits (message)"

\end_inset

, which is conceptually shared behavior but is not as binding as a class
 is.
 It returns an object which is, by convention, the location to place shared
 behavior.
 Most Slate method definitions are defined upon some object's 
\family typewriter
traits
\family default
 object.
 This is significant because cloning an object with a traits delegation
 slot will result in a new object with the same object delegated-to, so
 all methods defined on that traits object apply to the new clone.
 There is one core method which drives derivation:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "derive (message)"

\end_inset

myObject\InsetSpace ~
derive\InsetSpace ~
&mixins:\InsetSpace ~
&rejects:
\family default
 will return a new clone of the 
\family typewriter
Derivable
\family default
 object with a traits object which is cloned from the original's traits
 object, and an immutable delegation slot set between the traits objects.
 If mixins are given, it will include more immutable delegation links between
 the new traits and the traits of the array's objects, in the given order,
 which achieves a structured, shared behavior of static multiple delegation.
 Note that the delegation link addition order makes the right-most delegation
 target override the former ones in that order.
 One interesting property of this method is that the elements of the mixins
 do not have to be 
\family typewriter
Derivable
\family default
.
\end_layout

\begin_layout Standard
In practice, the following wrapper is the appropriate method to use in common
 situations, since it handles the installation of the prototype in a cleaner
 manner:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addPrototype:derivedFrom:"

\end_inset

obj\InsetSpace ~
addPrototype:\InsetSpace ~
name\InsetSpace ~
derivedFrom:\InsetSpace ~
parentsArray
\family default
 will perform the effects of 
\family typewriter
derive
\family default
 using all the elements of the 
\family typewriter
Sequence
\family default
 in the same order as 
\family typewriter
derive
\family default
.
 It also assigns the name to the traits object's name attribute (which should
 be a 
\family typewriter
Symbol
\family default
) as well as using the name for the attribute between the surrounding object
 and the new prototype.
 Finally, it will compare the delegation pattern of the new object with
 the old, and only replace the old if they differ.
 In either case, the installed object is what is returned, and the existing
 traits object will be re-used if there is one.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "define: (message)"

\end_inset

obj\InsetSpace ~
define:\InsetSpace ~
name\InsetSpace ~
&parents:\InsetSpace ~
parentsArray\InsetSpace ~
&slots:\InsetSpace ~
slotSpecs
\family default
 performs the effects of 
\family typewriter
derive
\family default
 using all the elements of the 
\family typewriter
Sequence
\family default
 in the same order as 
\family typewriter
derive
\family default
.
 The default parent is just 
\family typewriter
Cloneable
\family default
.
 It also assigns the name to the traits object's name attribute (which should
 be a 
\family typewriter
Symbol
\family default
) as well as using the name for the attribute between the surrounding object
 and the new prototype.
 The 
\family typewriter
slotSpecs
\family default
 needs to be an array with either 
\family typewriter
Symbol
\family default
s or 
\family typewriter
Association
\family default
s from 
\family typewriter
Symbol
\family default
s to values, to specify (mutable) state-slots and their attributes.
 Finally, it will compare the delegation pattern of the new object with
 the old, and only replace the old if they differ.
 In either case, the installed object is what is returned, and the existing
 traits object will be re-used if there is one.
 A 
\family typewriter
define:&builder:
\family default
 form is also provided which takes a block and uses its resulting value
 for the object; 
\family typewriter
&builder:
\family default
 can be used in conjuction with 
\family typewriter
&slots:
\family default
, but not with 
\family typewriter
&parents:
\family default
, as no derivation is relevant.
\end_layout

\begin_layout Standard
As with any method in Slate, these may be overridden to provide additional
 automation and safety in line with their semantics.
\end_layout

\begin_layout Paragraph
Traits Windows
\end_layout

\begin_layout Standard
Beneath this simple system is a level of indirection which allows for greater
 control 
\emph on
when necessary
\emph default
 over the combination of parent behaviors; for most purposes, they may be
 ignored.
 What is actually the case is that each object points to an object in a
 
\family typewriter
traitsWindow
\family default
 delegation slot.
 
\family typewriter
traitsWindow
\family default
 is defined to be the first delegate in an object's delegates array and
 
\family typewriter
traits
\family default
 is defined to be the last delegate in an object's 
\family typewriter
traitsWindow
\family default
.
\end_layout

\begin_layout Standard
Because the delegates of an object are easily changed, there is a great
 deal of control over the order of precedence This means that nearly all
 of the problems of precedence in a multiple inheritance graph may be resolved
 flexibly.
\begin_inset Foot
status collapsed

\begin_layout Standard
The classical illustration of multiple inheritance issues is the 
\begin_inset Quotes eld
\end_inset

diamond
\begin_inset Quotes erd
\end_inset

 problem where one parent is inherited via two different paths indirectly.
 Solutions that involve choosing inheritance graph traversal orders for
 the whole language are insufficiently flexible in dealing with multiple
 inheritance confusion, since various protocols need to interact independently.
\end_layout

\end_inset

 There is also a hint to the lookup procedure in the 
\family typewriter
traitsWindow
\family default
 objects that a meta-level has been reached.
 Once one meta-transition has occurred during lookup, the algorithm will
 not traverse such a transition again; thus Slate avoids a lookup confusion
 between methods meant for regular objects and those meant for the traits
 themselves.
\end_layout

\begin_layout Subsection
Blocks, Booleans, and Control-Flow
\begin_inset OptArg
status collapsed

\begin_layout Standard
Control-flow
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Boolean Logic
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "boolean logic"

\end_inset

Slate's evaluator primitively provides the objects 
\family typewriter
True
\begin_inset LatexCommand index
name "True (object)"

\end_inset


\family default
 and 
\family typewriter
False
\family default

\begin_inset LatexCommand index
name "False (object)"

\end_inset

, which are clones of 
\family typewriter
Boolean
\family default

\begin_inset LatexCommand index
name "Boolean (object)"

\end_inset

, and delegate to 
\family typewriter
Boolean\InsetSpace ~
traits
\family default
.
 Logical methods are defined on these in a very minimalistic way.
 Table 
\begin_inset LatexCommand vref
reference "cap:Basic-Logical-Operators"

\end_inset

 shows the non-lazy logical methods and their meanings.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "boolean messages"

\end_inset


\begin_inset LatexCommand index
name "and"

\end_inset


\begin_inset LatexCommand index
name "\\char `\\/\\char `\\\\ (message)"

\end_inset


\begin_inset LatexCommand index
name "or"

\end_inset


\begin_inset LatexCommand index
name "\\char `\\\\\\char `\\/ (message)"

\end_inset


\begin_inset LatexCommand index
name "not (message)"

\end_inset


\begin_inset LatexCommand index
name "eqv: (message)"

\end_inset


\begin_inset LatexCommand index
name "xor: (message)"

\end_inset


\begin_inset Float table
wide false
sideways false
status open

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="6" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0pt">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Description
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Selector
\end_layout

\end_inset
</cell>
</row>
<row bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
AND/Conjunction
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
/
\backslash

\end_layout

\end_inset
</cell>
</row>
<row>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\noun on
OR
\noun default
/Disjunction
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter

\backslash
/
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
NOT/Negation
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
not
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
EQV/Equivalence
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
eqv:
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
XOR/Exclusive-OR
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard

\family typewriter
xor:
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Basic-Logical-Operators"

\end_inset

Basic Logical Operators
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Basic Conditional Evaluation
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "conditional evaluation"

\end_inset


\begin_inset LatexCommand index
name "evaluation, conditional"

\end_inset

Logical methods are provided which take a block as their second argument
 (
\family typewriter
/
\backslash

\family default
, 
\family typewriter

\backslash
/
\family default
, 
\family typewriter
and:
\family default
, 
\family typewriter
or:
\family default
, 
\family typewriter
xor:
\family default
, 
\family typewriter
eqv:
\family default
).
 By accepting a block as the second argument, they can and do provide conditiona
l evaluation of the second argument only in the case that the first does
 not decide the total result automatically
\begin_inset Foot
status collapsed

\begin_layout Standard
However, support for blocks in the second argument position may be incorporated
 into the non-lazy selectors as different methods in the future, making
 some of these obsolete.
\end_layout

\end_inset

.
 
\begin_inset LatexCommand index
name "evaluation, lazy"

\end_inset


\begin_inset LatexCommand index
name "lazy evaluation"

\end_inset

Blocks that evaluate logical expressions can be used lazily in these logical
 expressions.
 For example,
\end_layout

\begin_layout LyX-Code
(x < 3) /
\backslash
 [y > 7].
\end_layout

\begin_layout Standard
only evaluates the right-hand block argument if the first argument turns
 out to be 
\family typewriter
True
\family default
.
\end_layout

\begin_layout LyX-Code
(x < 3) 
\backslash
/ [y > 7].
\end_layout

\begin_layout Standard
only evaluates the right-hand block argument if the first argument turns
 out to be 
\family typewriter
False
\family default
.
\end_layout

\begin_layout Standard
In general, the basic of booleans to switch between code alternatives is
 to use 
\family typewriter
ifTrue:
\family default

\begin_inset LatexCommand index
name "ifTrue: (message)"

\end_inset

, 
\family typewriter
ifFalse:
\family default

\begin_inset LatexCommand index
name "ifFalse: (message)"

\end_inset

, and 
\family typewriter
ifTrue:ifFalse:
\begin_inset LatexCommand index
name "ifTrue:ifFalse: (message)"

\end_inset


\family default
 for the various combinations of binary branches.
 For example,
\end_layout

\begin_layout LyX-Code
x isNegative ifTrue: [x: x negated].
\end_layout

\begin_layout Standard
ensures that 
\family typewriter
x
\family default
 is positive by optionally executing code to assign a positive form if it's
 not.
 Of course if only the result is desired, instead of just the side-effect,
 the entire expression's result will be the result of the executed block,
 so that it can be embedded in further expressions.
\end_layout

\begin_layout Standard
Conditional evaluation can also be driven by whether or not a slot has been
 initialized, or whether a method returns 
\family typewriter
Nil
\family default
.
 There are a few options for conditionalizing on 
\family typewriter
Nil
\family default
:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ifNil: (message)"

\end_inset


\begin_inset LatexCommand index
name "ifNotNil: (message)'"

\end_inset

expr\InsetSpace ~
ifNil:\InsetSpace ~
block
\family default
 and 
\family typewriter
\series bold
expr\InsetSpace ~
ifNotNil:\InsetSpace ~
block
\family default
\series default
 execute their blocks based on whether the expression evaluates to Nil,
 and returns the result.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ifNil:ifNotNil: (message)"

\end_inset

expr\InsetSpace ~
ifNil:\InsetSpace ~
nilBlock\InsetSpace ~
ifNotNil:\InsetSpace ~
otherBlock
\family default
 provides both options in one expression.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ifNotNilDo: (message)"

\end_inset


\begin_inset LatexCommand index
name "ifNil:ifNotNilDo: (message)"

\end_inset

expr\InsetSpace ~
ifNotNilDo:\InsetSpace ~
block
\family default
 applies the block to the expression's result if it turns out to be non-
\family typewriter
Nil
\family default
, so the block given must accept one argument.
 
\family typewriter
\series bold
ifNil:ifNotNilDo:
\family default
\series default
 is also provided for completeness.
\end_layout

\begin_layout Standard
There is also a 
\begin_inset Quotes eld
\end_inset

case-switch
\begin_inset Quotes erd
\end_inset

 style idiom:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "caseOf: (message)"

\end_inset


\begin_inset LatexCommand index
name "caseOf:otherwise: (message)"

\end_inset

expr\InsetSpace ~
caseOf:\InsetSpace ~
cases\InsetSpace ~
otherwise:\InsetSpace ~
defaultBlock
\family default
 takes the result of the first argument and the 
\family typewriter
cases
\family default
 array of 
\family typewriter
Association
\family default
s (made with 
\family typewriter
->
\family default
) from objects to blocks and executes the first block associated with a
 value equal to the expression.
 If none match, the last argument is executed; the otherwise: clause may
 be omitted, to just do / return nothing.
\end_layout

\begin_layout Subsubsection
\begin_inset LatexCommand label
name "sub:Early-Returns"

\end_inset

Early Returns
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "early return"

\end_inset


\begin_inset LatexCommand index
name "return, early"

\end_inset

Control-flow within methods can be skipped with a return value using the
 
\family typewriter
^
\family default
 message to the context.
 
\family typewriter
^
\family default
 takes its second argument and exits the nearest surrounding lexical scope
 that is a named method (and not an anonymous code block) with that value.
 This message is a real binary message with no special precedence, so disambigua
tion is often needed.
 For example,
\end_layout

\begin_layout LyX-Code
^ 4
\end_layout

\begin_layout LyX-Code
^ n factorial
\end_layout

\begin_layout Standard
return the expressions on the left as a whole, but
\end_layout

\begin_layout LyX-Code
^ 3 + 4
\end_layout

\begin_layout LyX-Code
^ (3 + 4)
\end_layout

\begin_layout LyX-Code
^ set collect: [| :each | each name]
\end_layout

\begin_layout LyX-Code
^ (set collect: [| :each | each name])
\end_layout

\begin_layout Standard
represent expression variations where a lack of disambiguation results in
 returning an unintended answer.
\end_layout

\begin_layout Subsubsection
Looping
\begin_inset LatexCommand label
name "sub:Looping"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "looping"

\end_inset

Slate includes various idioms for constructing basic loops.
 These are all built from ordinary methods which work with code blocks,
 and any ordinary code may define similar idioms rather quickly.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "loop (message)"

\end_inset

loop
\family default
 executes the block repeatedly, indefinitely
\begin_inset Foot
status collapsed

\begin_layout Standard
This is currently implemented through a compiler rule.
\end_layout

\end_inset

.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "timesRepeat: (message)"

\end_inset

n\InsetSpace ~
timesRepeat:\InsetSpace ~
block
\family default
 executes the block 
\family typewriter
n
\family default
 times.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "whileTrue: (message)"

\end_inset


\begin_inset LatexCommand index
name "whileFalse: (message)"

\end_inset

condition\InsetSpace ~
whileTrue:\InsetSpace ~
block
\family default
 and 
\family typewriter
\series bold
condition\InsetSpace ~
whileFalse:\InsetSpace ~
block
\family default
\series default
 execute their blocks repeatedly, checking the condition before each iteration
 (implying that the body block will not be executed if the condition is
 initially false).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "whileTrue (message)"

\end_inset


\begin_inset LatexCommand index
name "whileFalse (message)"

\end_inset

whileTrue
\family default
 and 
\family typewriter
\series bold
whileFalse
\family default
\series default
 execute their blocks repeatedly, checking the return value before repeating
 iterations (so that they will always execute at least one time).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "upTo:do: (message)"

\end_inset


\begin_inset LatexCommand index
name "downTo:do: (message)"

\end_inset

a\InsetSpace ~
upTo:\InsetSpace ~
b\InsetSpace ~
do:\InsetSpace ~
block
\family default
 and 
\family typewriter
\series bold
b\InsetSpace ~
downTo:\InsetSpace ~
a\InsetSpace ~
do:\InsetSpace ~
block
\family default
\series default
 executes the block with each number in turn from 
\family typewriter
a
\family default
 to 
\family typewriter
b
\family default
, inclusive.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "upTo:by:do: (message)"

\end_inset


\begin_inset LatexCommand index
name "downTo:by:do: (message)"

\end_inset

upTo:by:do:
\family default
 and 
\family typewriter
\series bold
downTo:by:do:
\family default
\series default
 executes the block with each number in turn in the inclusive range, with
 the given stepping increment.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "below:do: (message)"

\end_inset


\begin_inset LatexCommand index
name "above:do: (message)"

\end_inset

a\InsetSpace ~
below:\InsetSpace ~
b\InsetSpace ~
do:\InsetSpace ~
block
\family default
 and 
\family typewriter
\series bold
b\InsetSpace ~
above:\InsetSpace ~
a\InsetSpace ~
do:\InsetSpace ~
block
\family default
\series default
 act identically to the previous method except that they stop just before
 the last value.
 This assists in iterating over array ranges, where the 0-based indexing
 makes a difference in range addresses by one, avoiding excessive use of
 
\family typewriter
size\InsetSpace ~
-\InsetSpace ~
1
\family default
 calls.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "below:by:do: (message)"

\end_inset


\begin_inset LatexCommand index
name "above:by:do: (message)"

\end_inset

below:by:do:
\family default
 and 
\family typewriter
\series bold
above:by:do:
\family default
\series default
 vary on the previous methods with the given stepping increment.
\end_layout

\begin_layout Standard
\begin_inset Note Note
status collapsed

\begin_layout Standard
Slate's looping control structures can easily be extended without concern
 due to the fact that the evaluator 
\emph on
did
\emph default
 at one point unroll properly tail-recursive blocks into low-level loop
 code that re-uses the same activation frame.
 So basically structuring custom looping code so that it calls itself last
 within its own body and returns that value will avoid the need for increasing
 stack space per iteration.
 (Turn this back into a paragraph if it is implemented again.)
\end_layout

\end_inset


\end_layout

\begin_layout Subsubsection
Method Operations
\end_layout

\begin_layout Standard
Slate provides some powerful methods for operating on 
\family typewriter
Method
\family default
 (block) objects themselves.
 The answers of these operations are also fully-fledged 
\family typewriter
Method
\family default
 objects which respond to all of the normal queries and are useful anywhere
 that a 
\family typewriter
Method
\family default
 is accepted.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "** (message)"

\end_inset


\begin_inset LatexCommand index
name "method composition"

\end_inset

**
\family default
 composes two 
\family typewriter
Method
\family default
s in a functional manner, so that 
\begin_inset Formula $(F\circ G)(x)=F(G(x))$
\end_inset

; basically the result of applying the first to the result of the second
 (which in turn consumes the input).
 This operation is associative, so grouping of continued applications should
 not be a concern.
 This semantics assumes that the inner/right function 
\begin_inset Formula $G$
\end_inset

 may take any number of arguments, and that 
\begin_inset Formula $F$
\end_inset

 takes 1.
 If both of these are false, then there is an extended form of the semantics
 where the arity of 
\begin_inset Formula $F$
\end_inset

 is used to group the results of applying 
\begin_inset Formula $G$
\end_inset

 to each element in the argument array.
 The groups are then passed as a whole to one invocation of 
\begin_inset Formula $F$
\end_inset

.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "`er (macro)"

\end_inset

`er
\family default
 takes a literal 
\family typewriter
Symbol
\family default
 taken as a message selector and expands into an appropriate 
\family typewriter
Method
\family default
 which takes an appropriate number of arguments for the selector and sends
 the selector to those arguments, answering the result.
 E.g.
 
\family typewriter
#+`er
\family default
 expands into 
\family typewriter
[| :x :y | x + y]
\family default
 and 
\family typewriter
#name`er
\family default
 expands into 
\family typewriter
[| :x | x name]
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "converse (message)"

\end_inset

converse
\family default
 takes a 
\family typewriter
Method
\family default
 and answers a new 
\family typewriter
Method
\family default
 with the same body but with input argument order reversed.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "<- (message)"

\end_inset


\begin_inset LatexCommand index
name "currying"

\end_inset


\family typewriter
<-
\family default
 takes a 
\family typewriter
Method
\family default
 and an object and returns a new 
\family typewriter
Method
\family default
 with the same body but with the object substituted for the first argument,
 so it takes one less argument.
 This is also known as 
\emph on
currying
\emph default
.
 
\family typewriter
<-1
\family default
, 
\family typewriter
<-2
\family default
, 
\family typewriter
<-3
\family default
, and 
\family typewriter
<-*
\family default
 curry the next three argument positions and the last argument, respectively.
 
\family typewriter
fill:with:
\family default
 fills the N'th argument.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "`commutatively (macro)"

\end_inset

`commutatively
\family default
 takes a literal 
\family typewriter
MethodDefinition
\family default
 and defines it with two signatures, one reversed from the original definition,
 with the same body.
\end_layout

\begin_layout Subsection
Symbols
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Symbol (object)"

\end_inset


\begin_inset LatexCommand index
name "symbol table"

\end_inset


\begin_inset LatexCommand index
name "intern (message)"

\end_inset


\begin_inset LatexCommand index
name "intern: (message)"

\end_inset


\begin_inset LatexCommand index
name "name (message)"

\end_inset


\family typewriter
Symbol
\family default
s in Slate are basically a large group of 
\family typewriter
String
\family default
s sorted by identity into a global table 
\family typewriter
Symbols
\family default
.
 A new 
\family typewriter
Symbol
\family default
 is created or identified by taking a 
\family typewriter
String
\family default
 and calling the 
\family typewriter
intern
\family default
 method on it (or alternately, the context message 
\family typewriter
intern:
\family default
).
 Repeatedly 
\family typewriter
intern
\family default
'ing a same 
\family typewriter
String
\family default
 value or 
\family typewriter
Symbol
\family default
 object will return the exact same 
\family typewriter
Symbol
\family default
 object.
 In order to perform 
\family typewriter
String
\family default
 operations (see the 
\family typewriter
Sequence
\family default
 and 
\family typewriter
String
\family default
 sections
\begin_inset LatexCommand ref
reference "sub:Sequences"

\end_inset

), the 
\family typewriter
Symbol
\family default
 must be asked for its 
\family typewriter
name
\family default
 which gives a separate 
\family typewriter
String
\family default
 with its value; the results of these operations will still be 
\family typewriter
String
\family default
s and again must be 
\family typewriter
intern
\family default
'ed to create a new 
\family typewriter
Symbol
\family default
.
\end_layout

\begin_layout Subsection
Magnitudes and Numbers
\end_layout

\begin_layout Subsubsection
Basic Types
\begin_inset LatexCommand index
name "basic types"

\end_inset


\begin_inset LatexCommand index
name "types, basic"

\end_inset


\end_layout

\begin_layout Description

\family typewriter
Magnitude
\begin_inset LatexCommand index
name "Magnitude (object)"

\end_inset


\family default
 the abstract protocol for linearly-comparable objects, following 
\family typewriter
<
\family default
, 
\family typewriter
>
\family default
, 
\family typewriter
<=
\family default
, 
\family typewriter
>=
\family default
, and 
\family typewriter
=
\family default
.
\end_layout

\begin_layout Description

\family typewriter
Number
\begin_inset LatexCommand index
name "Number (object)"

\end_inset


\family default
 the abstract type of dimensionless quantities.
\end_layout

\begin_layout Description

\family typewriter
Integer
\begin_inset LatexCommand index
name "Integer (object)"

\end_inset


\family default
 integral quantities, generally.
\end_layout

\begin_layout Description

\family typewriter
SmallInteger
\begin_inset LatexCommand index
name "SmallInteger (object)"

\end_inset


\family default
 machine-word-limited integer values (minus 1 bit for the immediate-value
 flag).
 Their normal protocol will not produce errors inconsistent with mathematic
 behavior of 
\family typewriter
Integer
\family default
s, however: instead of overflows, 
\family typewriter
BigInteger
\family default
 objects of the appropriate value are returned.
\end_layout

\begin_layout Description

\family typewriter
BigInteger
\begin_inset LatexCommand index
name "BigInteger (object)"

\end_inset


\family default
 larger 
\family typewriter
Integer
\family default
s, implemented by wrapping 
\family typewriter
ByteArray
\family default

\begin_inset LatexCommand index
name "ByteArray (object)"

\end_inset

s with the appropriate behavior.
\end_layout

\begin_layout Description

\family typewriter
Fraction
\begin_inset LatexCommand index
name "Fraction (object)"

\end_inset


\family default
 An exact representation of a quotient, or rational number.
\end_layout

\begin_layout Description

\family typewriter
Float
\begin_inset LatexCommand index
name "Float (object)"

\end_inset


\family default
 A low-level floating-point numeric representation, being inexact.
 Floats are currently only implemented as 
\family typewriter
SingleFloat
\begin_inset LatexCommand index
name "SingleFloat (object)"

\end_inset


\family default
, a single-precision floating-point number representation.
\end_layout

\begin_layout Description

\family typewriter
Complex
\begin_inset LatexCommand index
name "Complex (object)"

\end_inset


\family default
 A complex number, similar to a pair of real numbers.
\end_layout

\begin_layout Subsubsection
Basic Operations
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "operations, basic"

\end_inset


\begin_inset LatexCommand index
name "basic operations"

\end_inset


\begin_inset LatexCommand index
name "plus"

\end_inset


\begin_inset LatexCommand index
name "+ (plus)"

\end_inset


\begin_inset LatexCommand index
name "addition"

\end_inset


\begin_inset LatexCommand index
name "operations, arithmetic"

\end_inset


\begin_inset LatexCommand index
name "arithmetic operations"

\end_inset


\begin_inset LatexCommand index
name "minus"

\end_inset


\begin_inset LatexCommand index
name "subtraction"

\end_inset


\begin_inset LatexCommand index
name "- (minus)"

\end_inset


\begin_inset LatexCommand index
name "multiplication"

\end_inset


\begin_inset LatexCommand index
name "times"

\end_inset


\begin_inset LatexCommand index
name "asterisk"

\end_inset


\begin_inset LatexCommand index
name "* (asterisk)"

\end_inset


\begin_inset LatexCommand index
name "division"

\end_inset


\begin_inset LatexCommand index
name "slash, forward"

\end_inset


\begin_inset LatexCommand index
name "forward slash"

\end_inset


\begin_inset LatexCommand index
name "\\char `\\/ (forward slash)"

\end_inset

All of the normal arithmetic operations (i.e.
 
\family typewriter
+
\family default
, 
\family typewriter
-
\family default
, 
\family typewriter
*
\family default
, 
\family typewriter
/
\family default
) are supported primitively between elements of the same type.
 Type coercion has to be done entirely in code; no implicit coercions are
 performed by the virtual machine.
 However, the standard library includes methods which perform this coercion.
 The interpreter also transparently provides unlimited-size integers, although
 the bootstrapped system may not do so implicitly.
\end_layout

\begin_layout Standard
The following are the rest of the primitive operations, given with an indication
 of their "signatures":
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "raisedTo: (message)"

\end_inset


\begin_inset LatexCommand index
name "exponentiation"

\end_inset


\begin_inset LatexCommand index
name "power, raising to a"

\end_inset

Float\InsetSpace ~
raisedTo:\InsetSpace ~
Float
\family default
 is simple floating-point exponentiation.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "as: (message)"

\end_inset


\begin_inset LatexCommand index
name "conversion, number"

\end_inset


\begin_inset LatexCommand index
name "number conversion"

\end_inset

Integer\InsetSpace ~
as:\InsetSpace ~
Float
\family default
 extends an integer into a float.
\end_layout

\begin_layout Description

\family typewriter
Float\InsetSpace ~
as:\InsetSpace ~
Integer
\family default
 truncates a float.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "bitOr: (message)"

\end_inset


\begin_inset LatexCommand index
name "bit operations"

\end_inset


\begin_inset LatexCommand index
name "operations, bit"

\end_inset

Integer\InsetSpace ~
bitOr:\InsetSpace ~
Integer
\family default
 performs bitwise logical 
\shape smallcaps
OR
\shape default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "bitXor: (message)"

\end_inset

Integer\InsetSpace ~
bitXor:\InsetSpace ~
Integer
\family default
 performs bitwise logical 
\shape smallcaps
XOR
\shape default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "bitAnd: (message)"

\end_inset

Integer\InsetSpace ~
bitAnd:\InsetSpace ~
Integer
\family default
 performs bitwise logical 
\shape smallcaps
AND
\shape default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "bitShift: (message)"

\end_inset

Integer\InsetSpace ~
bitShift:\InsetSpace ~
Integer
\family default
 performs bitwise logical right-shift (left-shift if negative).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "bitNot (message)"

\end_inset

Integer\InsetSpace ~
bitNot
\family default
 performs bitwise logical 
\shape smallcaps
NOT
\shape default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name ">> (message)"

\end_inset

Integer\InsetSpace ~
>>\InsetSpace ~
Integer
\family default
 performs logical right-shift.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "<< (message)"

\end_inset

Integer\InsetSpace ~
<<\InsetSpace ~
Integer
\family default
 performs logical left-shift.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "quo: (message)"

\end_inset


\begin_inset LatexCommand index
name "quotient"

\end_inset


\begin_inset LatexCommand index
name "division, integer"

\end_inset


\begin_inset LatexCommand index
name "integer division"

\end_inset

Integer\InsetSpace ~
quo:\InsetSpace ~
Integer
\family default
 returns a quotient (integer division).
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "mod: (mesage)"

\end_inset


\begin_inset LatexCommand index
name "reciprocal: (message)"

\end_inset


\begin_inset LatexCommand index
name "min: (message)"

\end_inset


\begin_inset LatexCommand index
name "max: (message)"

\end_inset


\begin_inset LatexCommand index
name "between:and: (message)"

\end_inset


\begin_inset LatexCommand index
name "lcm: (message)"

\end_inset


\begin_inset LatexCommand index
name "gcd: (message)"

\end_inset


\begin_inset LatexCommand index
name "Fraction (object)"

\end_inset

Many more useful methods are defined, such as 
\family typewriter
mod:
\family default
, 
\family typewriter
reciprocal
\family default
, 
\family typewriter
min:
\family default
, 
\family typewriter
max:
\family default
, 
\family typewriter
between:and:
\family default
, 
\family typewriter
lcm:
\family default
, and 
\family typewriter
gcd:
\family default
.
 Slate also works with 
\family typewriter
Fractions
\family default
 when dividing Integers, keeping them lazily reduced.
\end_layout

\begin_layout Subsubsection
Non-core Operations
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "zero (message)"

\end_inset

zero
\family default
 The zero element for the type of number.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "isZero (message)"

\end_inset

isZero
\family default
 Whether the number is the zero element for its type.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "isPositive (message)"

\end_inset


\begin_inset LatexCommand index
name "isNegative (message)"

\end_inset

isPositive
\family default
/
\family typewriter
isNegative
\family default
 Whether it's positive or negative.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "abs (message)"

\end_inset

abs
\family default
 The absolute value of the number.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "sign (message)"

\end_inset

sign
\family default
 The sign of the number.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "negated (message)"

\end_inset

negated
\family default
 Returns 
\emph on
-x
\emph default
 for 
\emph on
x
\emph default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "gcd: (message)"

\end_inset

gcd:
\family default
 Greatest common divisor.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "lcm: (message)"

\end_inset

lcm:
\family default
 Least common multiple.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "factorial (message)"

\end_inset

factorial
\family default
 Factorial.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "mod: (message)"

\end_inset


\begin_inset LatexCommand index
name "rem: (message)"

\end_inset


\begin_inset LatexCommand index
name "quo: (message)"

\end_inset

mod:
\family default
/
\family typewriter
rem:
\family default
/
\family typewriter
quo:
\family default
 Modulo division, remainder, and quotient.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "reciprocal (message)"

\end_inset

reciprocal
\family default
 Constructs a new fraction reciprocal.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "min: (message)"

\end_inset

min:
\family default
 The lesser of the arguments.
 The least in cases of 
\family typewriter
min:min:
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "max: (message)"

\end_inset

max:
\family default
 The greater of the arguments.
 The greatest in cases of 
\family typewriter
max:max:
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "between:and: (message)"

\end_inset

a\InsetSpace ~
between:\InsetSpace ~
b\InsetSpace ~
and:\InsetSpace ~
c
\family default
 Whether 
\family typewriter
a
\family default
 is between 
\family typewriter
b
\family default
 and 
\family typewriter
c
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "truncated (message)"

\end_inset


\begin_inset LatexCommand index
name "fractionPart (message)"

\end_inset

truncated
\family default
/
\family typewriter
fractionPart
\family default
 answers the greatest integer less than the number, and the corresponding
 difference as a fraction (or a float for 
\family typewriter
Float
\family default
).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "reduced (message)"

\end_inset

reduced
\family default
 Only defined on 
\family typewriter
Fraction
\family default
, this is the lazily-applied reducer; it will be invoked automatically for
 arithmetic operations as necessary, but is useful when only the reduced
 form is needed.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "readFrom: (message)"

\end_inset

readFrom:
\family default
 This takes a 
\family typewriter
String
\family default
 or a 
\family typewriter
Stream
\family default
 with compatible contents and parses the first available data as the type
 of the argument.
 If the return value is not the same as the argument type, an error is signalled
 (beyond any normal parsing errors).
 If the value is valid, it is returned; otherwise only 
\family typewriter
Nil
\family default
 will be available.
\end_layout

\begin_layout Subsubsection
Limit Numerics
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "limits, numeric"

\end_inset


\begin_inset LatexCommand index
name "numeric limits"

\end_inset


\begin_inset LatexCommand index
name "PositiveInfinity (object)"

\end_inset

PositiveInfinity
\family default
 is greater than any other 
\family typewriter
Magnitude
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "NegativeInfinity (object)"

\end_inset

NegativeInfinity
\family default
 is lesser than any other 
\family typewriter
Magnitude
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "LargeUnbound (object)"

\end_inset

LargeUnbounded
\family default
 A 
\family typewriter
Magnitude
\family default
 designed to represent non-infinite, but non-bounded (
\begin_inset Quotes eld
\end_inset

as large as you like
\begin_inset Quotes erd
\end_inset

) quantities.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "PositiveEpsilon (object)"

\end_inset

PositiveEpsilon
\family default
 is as small as you like, but positive and greater than zero.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "NegativeEpsilon (message)"

\end_inset

NegativeEpsilon
\family default
 is as small as you like, but negative and lesser than zero.
\end_layout

\begin_layout Subsubsection
Dimensioned Units
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "SI units"

\end_inset


\begin_inset LatexCommand index
name "dimensioned units"

\end_inset


\begin_inset LatexCommand index
name "units, dimensioned"

\end_inset


\begin_inset LatexCommand index
name "units, SI"

\end_inset


\begin_inset LatexCommand index
name "English units"

\end_inset


\begin_inset LatexCommand index
name "units, English"

\end_inset

There is an entire system for handling dimensioned units and their various
 combinations and mathematical operations.
 There is included support for SI units, and common English units; furthermore,
 any object may conceivably be used as a base unit.
 See the '
\family typewriter
src/lib/dimensioned.slate
\family default
' file for an overview.
\end_layout

\begin_layout Subsection
Collections
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "collections"

\end_inset


\begin_inset LatexCommand index
name "Collection (object)"

\end_inset


\begin_inset LatexCommand index
name "Mapping (object)"

\end_inset


\begin_inset LatexCommand index
name "ExtensibleCollection (object)"

\end_inset


\begin_inset LatexCommand index
name "Sequence (object)"

\end_inset


\begin_inset LatexCommand index
name "LinkedCollection (object)"

\end_inset


\begin_inset LatexCommand index
name "Bag (object)"

\end_inset


\begin_inset LatexCommand index
name "NoDuplicatesCollection (object)"

\end_inset


\begin_inset LatexCommand index
name "ExtensibleSequence (object)"

\end_inset


\begin_inset LatexCommand index
name "LinkedList (object)"

\end_inset


\begin_inset LatexCommand index
name "Tree (object)"

\end_inset


\begin_inset LatexCommand index
name "Graph (object)"

\end_inset


\begin_inset LatexCommand index
name "Tuple (object)"

\end_inset


\begin_inset LatexCommand index
name "Cord (object)"

\end_inset


\begin_inset LatexCommand index
name "Set (object)"

\end_inset


\begin_inset LatexCommand index
name "SortedSequence (object)"

\end_inset


\begin_inset LatexCommand index
name "Array (object)"

\end_inset


\begin_inset LatexCommand index
name "ByteArray (object)"

\end_inset


\begin_inset LatexCommand index
name "String (object)"

\end_inset


\begin_inset LatexCommand index
name "Range (object)"

\end_inset


\begin_inset LatexCommand index
name "Buffer (object)"

\end_inset


\begin_inset LatexCommand index
name "Dictionary (object)"

\end_inset


\begin_inset LatexCommand index
name "SortedSet (object)"

\end_inset


\begin_inset LatexCommand index
name "InsertionSequence (object)"

\end_inset

Slate's collection hierarchy makes use of composing multiple behaviors (via
 inheritance) to provide a collection system that can be reasoned about
 with greater certainty, and that can be extended more easily than other
 object-oriented languages' collection types.
 Primarily Slate collections are mutable, which means that basic modifications
 occur destructively on the collection object.
\end_layout

\begin_layout Standard
Figure 
\begin_inset LatexCommand ref
reference "cap:Collections-delegation"

\end_inset

 shows the overview of the collection types, and how their inheritance is
 patterned.
\end_layout

\begin_layout Standard
\begin_inset Float figure
placement htbp
wide true
sideways false
status open

\begin_layout Standard
\begin_inset VSpace defskip
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Graphics
        filename collection-web.eps

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace defskip
\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Collections-delegation"

\end_inset

Core Collections Inheritance
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Standard
All collections support a minimal set of methods, including support for
 basic internal iteration and testing.
 The following are representative core methods, and are by no means the
 limit of collection features:
\end_layout

\begin_layout Paragraph
\begin_inset LatexCommand index
name "testing, collections"

\end_inset


\begin_inset LatexCommand index
name "collection testing"

\end_inset

Testing Methods
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "isEmpty (message)"

\end_inset

isEmpty
\family default
 answers whether or not the collection has any elements in it.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "includes: (message)"

\end_inset

includes:
\family default
 answers whether the collection contains the object.
\end_layout

\begin_layout Paragraph
\begin_inset LatexCommand index
name "properties, collections"

\end_inset


\begin_inset LatexCommand index
name "collection properties"

\end_inset

Properties
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "size (message)"

\end_inset

size
\family default
 answers the number of elements in it.
 This is often calculated dynamically for extensible collections, so it's
 often useful to cache it in a calling method.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "capacity (message)"

\end_inset

capacity
\family default
 answers the size that the collection's implementation is currently ready
 for.
\end_layout

\begin_layout Paragraph
\begin_inset LatexCommand index
name "creation, collections"

\end_inset


\begin_inset LatexCommand index
name "collection creation"

\end_inset

Making new collections
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newSize: (message)"

\end_inset

new\InsetSpace ~
&capacity:
\family default
 answers a new (empty) collection of the same type that is sized to the
 optional argument or a sensible default per type.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newSizeOf: (message)"

\end_inset

newSizeOf:
\family default
 answers a new collection of the same type that is sized to same size that
 the argument has.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "as:newWithAll: (message)"

\end_inset


\begin_inset LatexCommand index
name "newWithAll: (message)"

\end_inset

as:
\family default
\emph on
\InsetSpace ~
via
\family typewriter
\emph default
\InsetSpace ~

\series bold
newWithAll:
\family default
\series default
 has extensive support in the collection types to produce collections of
 the type of the second with the contents of the first collection (
\emph on
vice versa
\emph default
 for 
\family typewriter
newWithAll:
\family default
 arguments).
\end_layout

\begin_layout Paragraph
\begin_inset LatexCommand index
name "collection iteration"

\end_inset


\begin_inset LatexCommand index
name "iteration, collections"

\end_inset

Iterating
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "do: (message)"

\end_inset


\begin_inset LatexCommand index
name "each: (message)"

\end_inset

do:
\family default
 executes a block with 
\family typewriter
:each
\family default
 (the idiomatic input slot for iterating) of the collection's elements in
 turn.
 It answers the original collection.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "collect: (message)"

\end_inset

collect:
\family default
 also takes a block, but answers a collection with all the results of those
 block-applications put into a new collection of the appropriate type.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "select: (message)"

\end_inset

select:
\family default
 takes a block that answers a 
\family typewriter
Boolean
\family default
 and answers a new collection of the elements that the block filters (answers
 
\family typewriter
True
\family default
).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "reject: (message)"

\end_inset

reject:
\family default
 performs the logical opposite of 
\family typewriter
select:
\family default
, answering elements for which the block answers 
\family typewriter
False
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "inject:into: (message)"

\end_inset

inject:\InsetSpace ~
init\InsetSpace ~
into:\InsetSpace ~
accumulator
\family default
 takes a two-argument accumulation block and applies it across the collection's
 elements.
 The initial value given becomes the first argument, and is replaced through
 the iterations with the result of the block.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "reduce: (message)"

\end_inset

reduce:
\family default
 takes a two-argument block and performs the same action as 
\family typewriter
inject:into:
\family default
 only using one of the collection's elements as an initial value.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "project: (message)"

\end_inset


\family typewriter
project:
\family default
 takes a block, answering a 
\family typewriter
Dictionary
\family default
 or 
\family typewriter
Mapping
\family default
 in general with each argument (member of the original collection) mapped
 to the result of applying the block to it.
\end_layout

\begin_layout Subsubsection
Extensible Collections
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "extensible collections"

\end_inset


\begin_inset LatexCommand index
name "collections, extensible"

\end_inset


\begin_inset LatexCommand index
name "ExtensibleCollection (object)"

\end_inset

Collections derived from 
\family typewriter
ExtensibleCollection
\family default
 can be modified by adding or removing elements in various ways.
 The core protocol is:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "add: (message)"

\end_inset

add:
\family default
 inserts the given object into the collection.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "remove: (message)"

\end_inset

remove:
\family default
 removes an object equal to the given one from the collection.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addAll: (message)"

\end_inset

addAll:
\family default
 inserts all elements from the first collection contained in the second.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "removeAll: (message)"

\end_inset

removeAll:
\family default
 removes all elements from the first collection contained in the second.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "clear (message)"

\end_inset

clear
\family default
 removes all the elements from the collection.
\end_layout

\begin_layout Subsubsection
Sequences
\begin_inset LatexCommand label
name "sub:Sequences"

\end_inset


\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "Sequence (object)"

\end_inset


\begin_inset LatexCommand index
name "Mapping (object)"

\end_inset

Sequences
\family default
 are 
\family typewriter
Mappings
\family default
 from a range of natural numbers to some objects, sometimes restricted to
 a given type.
 Slate sequences are all addressed from a base of 0.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "at: (message)"

\end_inset

at:
\family default
 answers the element at the index given.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "at:put: (message)"

\end_inset

at:put:
\family default
 replaces the element at the index given with the object that is the last
 argument.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "doWithIndex: (message)"

\end_inset

doWithIndex:
\family default
 operates as do:, but applying the block with both the element as first
 argument and the index of the element in the Sequence as the second argument.
\end_layout

\begin_layout Paragraph
Arrays
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "Array (object)"

\end_inset


\begin_inset LatexCommand index
name "WordArray (object)"

\end_inset


\begin_inset LatexCommand index
name "ByteArray (object)"

\end_inset


\begin_inset LatexCommand index
name "String (object)"

\end_inset

Arrays
\family default
 are fixed-length sequences of any kind of object and are supported primitively.
 Various parameter types of 
\family typewriter
Array
\family default
 are supported primitively, such as 
\family typewriter
WordArray
\family default
, 
\family typewriter
ByteArray
\family default
, and 
\family typewriter
String
\family default
.
\end_layout

\begin_layout Paragraph
Vectors
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "Vector (object)"

\end_inset


\begin_inset LatexCommand index
name "Tuple (object)"

\end_inset


\begin_inset LatexCommand index
name "Point (object)"

\end_inset


\begin_inset LatexCommand index
name "comma"

\end_inset


\begin_inset LatexCommand index
name ", (comma)"

\end_inset

Vectors
\family default
 and 
\family typewriter
Tuples
\family default
 are fixed-length sequences constructed for geometrical purposes.
 
\family typewriter
Points
\family default
 happen to be 
\family typewriter
Tuples
\family default
.
 The constructor message for these types is 
\begin_inset Quotes eld
\end_inset


\family typewriter
,
\family default

\begin_inset Quotes erd
\end_inset

.
\end_layout

\begin_layout Paragraph
Subsequences / Slices
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "Subsequence (object)"

\end_inset

Subsequences
\family default
 allow one to treat a segment of a sequence as a separate sequence with
 its own addressing scheme; however, modifying the subsequence will cause
 the original to be modified.
\end_layout

\begin_layout Paragraph
Cords
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "Cord (object)"

\end_inset


\begin_inset LatexCommand index
name "semicolon"

\end_inset


\begin_inset LatexCommand index
name "; (semicolon)"

\end_inset


\begin_inset LatexCommand index
name ";; (message)"

\end_inset

Cords
\family default
 are a non-copying representation of a concatenation of 
\family typewriter
Sequence
\family default
s.
 Normal concatenation of Sequences is performed with the 
\family typewriter
;
\family default
 method, and results in copying both of the arguments into a new 
\family typewriter
Sequence
\family default
 of the appropriate type; the 
\family typewriter
;;
\family default
 method will construct a 
\family typewriter
Cord
\family default
 instead.
 They efficiently implement accessing via 
\family typewriter
at:
\family default
 and iteration via 
\family typewriter
do:
\family default
, and 
\family typewriter
Cord\InsetSpace ~
as:\InsetSpace ~
Sequence
\family default
 will 
\begin_inset Quotes eld
\end_inset

flatten
\begin_inset Quotes erd
\end_inset

 the 
\family typewriter
Cord
\family default
 into a 
\family typewriter
Sequence
\family default
.
\end_layout

\begin_layout Paragraph
Extensible and Sorted Sequences
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "ExtensibleSequence (object)"

\end_inset

An 
\family typewriter
ExtensibleSequence
\family default
 is an extensible 
\family typewriter
Sequence
\family default
 with some special methods to treat both ends as queues.
 It provides the following additional protocol:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addFirst: (message)"

\end_inset

addFirst:
\family default
 inserts the given object at the beginning of the sequence.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "addLast: (message)"

\end_inset

addLast:
\family default
 inserts the given object at the end of the sequence.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "add: (message)"

\end_inset

add:
\family default
 inserts the given object at the end of the sequence (it's addLast:).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "first: (message)"

\end_inset

first:
\family default
 answers a sequence of the first N elements.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "last: (message)"

\end_inset

last:
\family default
 answers a sequence of the final N elements.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "removeFirst (message)"

\end_inset

removeFirst
\family default
 removes the first element from the sequence.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "removeLast (message)"

\end_inset

removeLast
\family default
 removes the final element from the sequence.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "SortedSequence (object)"

\end_inset


\begin_inset LatexCommand index
name "remove: (message)"

\end_inset


\begin_inset LatexCommand index
name "Heap (object)"

\end_inset

A 
\family typewriter
SortedSequence
\family default
 behaves similarly except that it will arrange for its members to remain
 sorted according to a block closure that compares two individual elements;
 as a result, it should not be manipulated except via 
\family typewriter
add:
\family default
 and 
\family typewriter
remove:
\family default
 since it maintains its own ordering.
 A 
\family typewriter
Heap
\family default
 is a 
\family typewriter
SortedSequence
\family default
 designed for collecting elements in arbitrary order, and removing the first
 elements.
\end_layout

\begin_layout Paragraph
Stacks
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Stack (object)"

\end_inset


\begin_inset LatexCommand index
name "push: (message)"

\end_inset


\begin_inset LatexCommand index
name "pop (message)"

\end_inset


\begin_inset LatexCommand index
name "top (message)"

\end_inset

A 
\family typewriter
Stack
\family default
 is an 
\family typewriter
ExtensibleSequence
\family default
 augmented with methods to honor the stack abstraction: 
\family typewriter
push:
\family default
, 
\family typewriter
pop
\family default
, 
\family typewriter
top
\family default
, etc.
\end_layout

\begin_layout Paragraph
Ranges
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Range (object)"

\end_inset

A 
\family typewriter
Range
\family default
 is a 
\family typewriter
Sequence
\family default
 of 
\family typewriter
Number
\family default
s between two values, that is ordered consecutively and has some stepping
 value; they include the 
\family typewriter
start
\family default
 value and also the 
\family typewriter
end
\family default
 value unless the stepping doesn't lead to the 
\family typewriter
end
\family default
 value exactly, in which case the last value is the greatest value in the
 sequence that is still before the end marker value.
 Creating ranges is identical to the numeric iteration protocol in 
\begin_inset LatexCommand ref
reference "sub:Looping"

\end_inset

, without the final 
\family typewriter
do:
\family default
 keyword, and sending the 
\family typewriter
do:
\family default
 message to a 
\family typewriter
Range
\family default
 performs the identical function.
\end_layout

\begin_layout Paragraph
Buffers
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Buffer (object)"

\end_inset


\begin_inset LatexCommand index
name "RingBuffer (object)"

\end_inset


\begin_inset LatexCommand index
name "ReadBufferStream (object)"

\end_inset


\begin_inset LatexCommand index
name "WriteBufferStream (object)"

\end_inset

A 
\family typewriter
RingBuffer
\family default
 is a special 
\family typewriter
ExtensibleSequence
\family default
 that takes extra care to only use one underlying array object, and also
 stores its elements in a 
\begin_inset Quotes eld
\end_inset

wrap-around
\begin_inset Quotes erd
\end_inset

 fashion, to make for an efficient queue for Streams (see 
\family typewriter
ReadBufferStream
\family default
 and 
\family typewriter
WriteBufferStream
\family default
 (
\begin_inset LatexCommand vref
reference "des:ReadBufferStream"

\end_inset

)).
 One consequence of this is that a 
\family typewriter
RingBuffer
\family default
 has a limited upper bound in size which the client must handle, although
 the capacity can be grown explicitly.
\end_layout

\begin_layout Subsubsection
Strings and Characters
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "String (object)"

\end_inset

Strings
\family default
 in Slate are non-extensible, mutable 
\family typewriter
Sequence
\family default
s of 
\family typewriter
Character
\family default
s (although 
\family typewriter
ExtensibleSequence
\family default
s can easily be made for them via, say, 
\family typewriter
as:
\family default
).
 
\family typewriter
String
\family default
s and 
\family typewriter
Character
\family default
s have a special literal syntax, and methods specific to dealing with text;
 most of the useful generic methods for strings are lifted to the 
\family typewriter
Sequence
\family default
 type.
 Strings provide the following specific protocol:
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "lexicographicallyCompare: (message)"

\end_inset


\family typewriter
lexicographicallyCompare:
\family default
 performs an in-order comparison of the codes of the constituent 
\family typewriter
Character
\family default
s of the 
\family typewriter
String
\family default
 arguments, returning the sign of comparison, 
\family typewriter
+1
\family default
 if the first argument is greater, 
\family typewriter
0
\family default
 if equal, and 
\family typewriter
-1
\family default
 if lesser.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "capitalize (message)"

\end_inset

capitalize
\family default
 uppercases in-place the first 
\family typewriter
Character
\family default
 in the 
\family typewriter
String
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "toUppercase (message)"

\end_inset

toUppercase
\family default
 uppercases in-place all 
\family typewriter
Character
\family default
s in the 
\family typewriter
String
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "toLowerCase (message)"

\end_inset

toLowercase
\family default
 lowercases in-place all 
\family typewriter
Character
\family default
s in the 
\family typewriter
String
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "toSwapCase (message)"

\end_inset

toSwapCase
\family default
 toggles in-place the case of all 
\family typewriter
Character
\family default
s in the 
\family typewriter
String
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "toCamelCase (message)"

\end_inset

toCamelCase\InsetSpace ~
&separators:
\family default
 splits the 
\family typewriter
String
\family default
 up according to the given separators (defaulting to whitespace), joining
 
\family typewriter
capitalize
\family default
'd versions of each element.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "fromCamelCase (message)"

\end_inset

fromCamelCase\InsetSpace ~
&separator:
\family default
 splits the 
\family typewriter
String
\family default
 up according to capitalization transition boundaries and joins the elements
 together with the given separator.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "escaped (message)"

\end_inset

escaped
\family default
 answers a new 
\family typewriter
String
\family default
 based on adding slash-escapes for literal printing so it can be read in
 as the same value.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "unescaped (message)"

\end_inset

unescaped
\family default
 answers a new 
\family typewriter
String
\family default
 based on removing slash-escapes, the same way that parsing is done.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "readFrom: (message)"

\end_inset

readFrom:
\family default
 takes a 
\family typewriter
String
\family default
 or a 
\family typewriter
Stream
\family default
 with compatible contents and parses the first available data as a 
\family typewriter
String
\family default
 with the relevant escape interpretation.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "plural (message)"

\end_inset


\family typewriter
plural
\family default
 uses English rules to answer a new regular plural form of the argument
 
\family typewriter
String
\family default
.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "asAn (message)"

\end_inset


\family typewriter
asAn
\family default
 uses English rules to answer a new String with 
\family typewriter
'a\InsetSpace ~
'
\family default
 or 
\family typewriter
'an\InsetSpace ~
'
\family default
 prepended.
\end_layout

\begin_layout Subsubsection
Collections without Duplicates
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "NoDuplicationCollection (object)"

\end_inset


\begin_inset LatexCommand index
name "include: (message)"

\end_inset

NoDuplicatesCollection
\family default
 forms a special protocol that allows for extension in a well-mannered way.
 Instead of an 
\family typewriter
add:
\family default
 protocol for extension, these collections provide 
\family typewriter
include:
\family default
, which ensures that at least one element of the collection is the target
 object, but doesn't do anything otherwise.
 Using 
\family typewriter
include:
\family default
 will never add an object if it is already present.
 These collection types still respond to 
\family typewriter
add:
\family default
 and its variants, but they will behave in terms of the 
\family typewriter
include:
\family default
 semantics.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Set (object)"

\end_inset

The default implementation of this protocol is 
\family typewriter
Set
\family default
, which stores its elements in a (somewhat sparse) hashed array.
\end_layout

\begin_layout Subsubsection
Mappings and Dictionaries
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "Mapping (object)"

\end_inset


\begin_inset LatexCommand index
name "Association (object)"

\end_inset


\begin_inset LatexCommand index
name "keysDo: (message)"

\end_inset


\begin_inset LatexCommand index
name "valuesDo: (message)"

\end_inset


\begin_inset LatexCommand index
name "keysAndValuedDo: (message)"

\end_inset


\begin_inset LatexCommand index
name "Dictionary (object)"

\end_inset

Mapping
\family default
s provide a general protocol for associating the elements of a set of keys
 each to a value object.
 A 
\family typewriter
Dictionary
\family default
 is essentially a 
\family typewriter
Set
\family default
 of these 
\family typewriter
Association
\family default
s, but they are generally used with 
\family typewriter
Symbol
\family default
s as keys.
\end_layout

\begin_layout Standard

\family typewriter
Mapping
\family default
 defines the general protocol 
\family typewriter
at:
\family default
 and 
\family typewriter
at:put:
\family default
 that 
\family typewriter
Sequence
\family default
s use, which also happen to be Mappings.
 Mappings also support iteration protocols such as 
\family typewriter
keysDo:
\family default
, 
\family typewriter
valuesDo:
\family default
, and 
\family typewriter
keysAndValuesDo:
\family default
.
\end_layout

\begin_layout Subsubsection
Linked Collections
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "LinkedCollection (object)"

\end_inset

A 
\family typewriter
LinkedCollection
\family default
 provides a type of collection where the elements themselves are central
 to defining what is in the collection and what is not.
\end_layout

\begin_layout Paragraph
Linked Lists
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "LinkedList (object)"

\end_inset


\begin_inset LatexCommand index
name "Link (object)"

\end_inset

The usual 
\family typewriter
LinkedList
\family default
 type, comprised of individual 
\family typewriter
Link
\family default
s with forward and backward directional access, is provided as a flexible
 but basic data structure.
 This type does require that its elements follow the 
\family typewriter
Link
\family default
 protocol, however, so it does require some advanced preparation to use
 it.
\end_layout

\begin_layout Paragraph
Trees
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "trees"

\end_inset


\begin_inset LatexCommand index
name "trees, binary"

\end_inset


\begin_inset LatexCommand index
name "binary trees"

\end_inset


\begin_inset LatexCommand index
name "trees, red-black"

\end_inset


\begin_inset LatexCommand index
name "red-black trees"

\end_inset


\begin_inset LatexCommand index
name "trees with ordered elements"

\end_inset


\begin_inset LatexCommand index
name "ordered elements, trees"

\end_inset


\begin_inset LatexCommand index
name "tries"

\end_inset

Slate includes libraries for binary trees, red-black trees, trees with ordered
 elements, and tries.
\end_layout

\begin_layout Paragraph
Graphs
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "graphs"

\end_inset


\begin_inset LatexCommand index
name "Digraph (object)"

\end_inset


\begin_inset LatexCommand index
name "Node (object)"

\end_inset


\begin_inset LatexCommand index
name "Edge (object)"

\end_inset


\begin_inset LatexCommand index
name "KeyedDigraph (object)"

\end_inset

A directed graph, or 
\family typewriter
Digraph
\family default
 (directed graph) type, is provided with associated 
\family typewriter
Node
\family default
 and 
\family typewriter
Edge
\family default
 types.
 A 
\family typewriter
KeyedDigraph
\family default
 provides the same behavior with a keyed access, similar to that in a 
\family typewriter
Mapping
\family default
, although there is an allowance for various kinds of non-determinism, which
 makes this useful for creating Non-deterministic Finite Automata.
\end_layout

\begin_layout Subsubsection
Vectors and Matrices
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "vectors"

\end_inset


\begin_inset LatexCommand index
name "matrices"

\end_inset

Slate includes the beginnings of a mathematical vector and matrix library.
 See the '
\family typewriter
src/lib/matrix.slate
\family default
' file for an overview.
\end_layout

\begin_layout Subsection
Streams and Iterators
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "streams"

\end_inset


\begin_inset LatexCommand index
name "iterators"

\end_inset

Streams are objects that act as a sequential channel of elements from (or
 even 
\emph on
to
\emph default
) some source.
\end_layout

\begin_layout Subsubsection
Basic Protocol
\end_layout

\begin_layout Standard
Streams respond to a number of common messages.
 However, many of these only work on some of the stream types, usually according
 to good sense:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "next (message)"

\end_inset

next\InsetSpace ~
&onExhaustion:
\family default
 reads and answers the next element in the stream.
 This causes the stream reader to advance one element.
 If no further elements are available to return, then the block supplied
 to 
\family typewriter
&onExhaustion:
\family default
 is invoked (with no arguments), or if the optional argument was not supplied,
 an 
\family typewriter
Exhaustion
\family default
 condition is signalled.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "peek (message)"

\end_inset

peek\InsetSpace ~
&onExhaustion:
\family default
 reads and answers the next element in the stream.
 This does 
\emph on
not
\emph default
 advance the stream reader.
 If no further elements are available to return, the 
\family typewriter
&onExhaustion:
\family default
 argument is processed as for 
\family typewriter
next
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "next: (message)"

\end_inset

next:
\family default
 draws the next 
\family typewriter
n
\family default
 number of elements from the stream and delivers them in a 
\family typewriter
Sequence
\family default
 of the appropriate type.
 If fewer than n elements are available before the end of stream (when 
\family typewriter
next
\family default
 would have signalled 
\family typewriter
Exhaustion
\family default
), then a shorter 
\family typewriter
Sequence
\family default
 than asked for, possibly even empty, is returned.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "next:putInto: (message)"

\end_inset

next:putInto:
\family default
 reads the next N elements into the given 
\family typewriter
Sequence
\family default
 starting from index 0.
 Returns the number of elements actually read and inserted.
 As for 
\family typewriter
next:
\family default
, the returned number may be smaller than actually asked for.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "next:putInto:startingAt: (message)"

\end_inset

next:putInto:startingAt:
\family default
 reads the N elements into the given 
\family typewriter
Sequence
\family default
 starting from the given index.
 Returns the number of elements read and inserted, exactly as for 
\family typewriter
next:putInto:
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "nextPutInto: (message)"

\end_inset

nextPutInto:
\family default
 reads into the given 
\family typewriter
Sequence
\family default
 the number of elements which will fit into it.
 Returns a result exactly as for 
\family typewriter
next:putInto:
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "nextPut: (message)"

\end_inset

nextPut:\InsetSpace ~
&onExhaustion:
\family default
 writes the object to the stream.
 If the stream is full, and will not accept the object, the 
\family typewriter
&onExhaustion:
\family default
 optional argument is processed as for 
\family typewriter
next
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "nextPutAll: (message)"

\end_inset


\begin_inset LatexCommand index
name "; (semicolon)"

\end_inset

nextPutAll:
\family default
 
\emph on
alias
\emph default
 
\family typewriter
\series bold
stream\InsetSpace ~
;\InsetSpace ~
sequence
\family default
\series default
 writes all the objects in the 
\family typewriter
Sequence
\family default
 to the stream.
 The 
\family typewriter
;
\family default
 selector allows the user to cascade several sequences into the stream as
 though they were concatenated.
 If the stream fills up (signalling 
\family typewriter
Exhaustion
\family default
) during the write, a 
\family typewriter
PartialWrite
\family default
 condition containing the number of successfully written elements is signalled.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "do: (message)"

\end_inset

do:
\family default
 applies a block to each element of the stream.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "flush (message)"

\end_inset

flush
\family default
 synchronizes the total state of the stream with any pending requests made
 by the user.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "isAtEnd (message)"

\end_inset

isAtEnd
\family default
 answers whether or not the stream has reached some input limit: returns
 true if next or peek would signal Exhaustion at the time 
\family typewriter
isAtEnd
\family default
 was called; returns false otherwise (modulo signalled Conditions).
 Note that, for some streams (notably sockets), even though 
\family typewriter
isAtEnd
\family default
 has returned false, 
\family typewriter
next
\family default
 or 
\family typewriter
peek
\family default
 may still signal Exhaustion because the underlying input-source has changed
 its state asynchronously.
 Use the 
\family typewriter
&onExhaustion:
\family default
 optional argument to 
\family typewriter
next
\family default
 and 
\family typewriter
peek
\family default
 for reliable notifications in these cases.
 
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "hasAnEnd (message)"

\end_inset


\family typewriter
hasAnEnd
\family default
 answers whether the stream has a definable or possible end-point.
 All stream types support this protocol and will often recurses on their
 components to find the answer.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "isWritable (message)"

\end_inset


\family typewriter
isWritable
\family default
 answers whether the stream is prepared to accept further objects via 
\family typewriter
nextPut:
\family default
.
 Returns false if 
\family typewriter
nextPut:
\family default
 would signal 
\family typewriter
Exhaustion
\family default
 at the time 
\family typewriter
isWritable
\family default
 was called; returns true otherwise (modulo signalled 
\family typewriter
Condition
\family default
s).
 See caveat as for 
\family typewriter
isAtEnd
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "upToEnd (message)"

\end_inset

upToEnd
\family default
 collects all the elements of the stream up to its limit into an 
\family typewriter
Extensible\SpecialChar \-
Sequence
\family default
, and returns the sequence.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "contents (message)"

\end_inset

contents
\family default
 answers a collection of the output of the argument 
\family typewriter
WriteStream
\family default
.
\end_layout

\begin_layout Subsubsection
Basic Stream Variants
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Stream (object)"

\end_inset


\begin_inset LatexCommand index
name "PositionableStream (object)"

\end_inset


\begin_inset LatexCommand index
name "FilterStream (object)"

\end_inset


\begin_inset LatexCommand index
name "CollectStream (object)"

\end_inset


\begin_inset LatexCommand index
name "ReadStream (object)"

\end_inset


\begin_inset LatexCommand index
name "WriteStream (object)"

\end_inset


\begin_inset LatexCommand index
name "BufferStream (object)"

\end_inset


\begin_inset LatexCommand index
name "FileStream (object)"

\end_inset


\begin_inset LatexCommand index
name "Socket (object)"

\end_inset


\begin_inset LatexCommand index
name "Pipe (object)"

\end_inset


\begin_inset LatexCommand index
name "Console (object)"

\end_inset


\begin_inset LatexCommand index
name "DummyStream (object)"

\end_inset


\begin_inset LatexCommand index
name "BlockStream (object)"

\end_inset


\begin_inset LatexCommand index
name "ReadWriteStream (object)"

\end_inset


\begin_inset LatexCommand index
name "EchoStream (object)"

\end_inset


\begin_inset LatexCommand index
name "LineNumberedStream (object)"

\end_inset

Figure 
\begin_inset LatexCommand ref
reference "cap:Stream-Inheritance"

\end_inset

 shows the major stream types and their relationships.
\end_layout

\begin_layout Standard
\begin_inset Float figure
wide false
sideways false
status open

\begin_layout Standard
\begin_inset VSpace defskip
\end_inset


\end_layout

\begin_layout Standard
\align center
\begin_inset Graphics
        filename stream-web.eps

\end_inset


\end_layout

\begin_layout Standard
\begin_inset VSpace defskip
\end_inset


\end_layout

\begin_layout Standard
\begin_inset Caption

\begin_layout Standard
\begin_inset LatexCommand label
name "cap:Stream-Inheritance"

\end_inset

Stream Inheritance
\end_layout

\end_inset


\end_layout

\end_inset


\end_layout

\begin_layout Description

\family typewriter
Stream
\family default
 provides the basic protocol for instantiating streams.
\end_layout

\begin_layout Description

\family typewriter
ReadStream
\family default
 provides the basic protocol for input access from a source.
\end_layout

\begin_layout Description

\family typewriter
WriteStream
\family default
 provides the basic protocol for output access to a target.
\end_layout

\begin_layout Description

\family typewriter
ReadWriteStream
\family default
 provides the basic protocol for both read and write access, and caches
 its input as necessary.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "PeekableStream (object)"

\end_inset

PeekableStream
\family default
 extends 
\family typewriter
Stream
\family default
 to provide the ability to look forward on the stream without advancing
 it.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ReadPositionableStream (object)"

\end_inset


\begin_inset LatexCommand index
name "WritePositionableStream (object)"

\end_inset


\begin_inset LatexCommand index
name "ReadWritePositionableStream (object)"

\end_inset

PositionableStream
\family default
 extends 
\family typewriter
PeekableStream
\family default
 to provide a basic protocol to iterate over a sequence of elements from
 a 
\family typewriter
Sequence
\family default
 or a file or other source.
 These streams store their position in the sequence as they iterate, and
 are re-positionable.
 It also has its own variants, -
\family typewriter
Read
\family default
-, -
\family typewriter
Write
\family default
-, and -
\family typewriter
ReadWrite
\family default
-.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "reader (message)"

\end_inset


\begin_inset LatexCommand index
name "writer (message)"

\end_inset


\begin_inset LatexCommand index
name "iterator (message)"

\end_inset

DummyStream
\family default
 is a (singleton) 
\family typewriter
ReadWriteStream
\family default
 that just answers 
\family typewriter
Nil
\family default
 repeatedly (and does nothing on writing).
 It is best created by applying the 
\family typewriter
reader
\family default
, 
\family typewriter
writer
\family default
, or 
\family typewriter
iterator
\family default
 methods to 
\family typewriter
Nil
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "echo (message)"

\end_inset


\begin_inset LatexCommand index
name "echoTo: (message)"

\end_inset

EchoStream
\family default
 is a wrapper for a 
\family typewriter
Stream
\family default
 which copies all stream input/output interactions to another 
\family typewriter
Stream
\family default
 for logging purposes.
 It is best created by applying the 
\family typewriter
echo
\family default
 (goes to the 
\family typewriter
Console
\family default
) or 
\family typewriter
echoTo:\InsetSpace ~
anotherStream
\family default
 methods to any stream.
 It answers the original stream, so that further processing can be chained.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Method ReadStream (object)"

\end_inset

Method\InsetSpace ~
ReadStream
\family default
 is a 
\family typewriter
ReadStream
\family default
 that targets a no-input block and returns its output each time.
 It is best created by applying the 
\family typewriter
reader
\family default
 or 
\family typewriter
iterator
\family default
 method to any block.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Method WriteStream (object)"

\end_inset

Method\InsetSpace ~
WriteStream
\family default
 is a 
\family typewriter
WriteStream
\family default
 that targets a single-input block and applies its input each time.
 It is best created by applying the 
\family typewriter
writer
\family default
 method to any block.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "StreamProcessor (object)"

\end_inset

StreamProcessor
\family default
 is an abstract kind of 
\family typewriter
ReadStream
\family default
 that has a source 
\family typewriter
ReadStream
\family default
 which it processes in some way.
 Derivatives specialize it in various useful ways.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "select: (message)"

\end_inset


\begin_inset LatexCommand index
name "reject: (message)"

\end_inset

FilterStream
\family default
 is a 
\family typewriter
StreamProcessor
\family default
 that returns the elements of a wrapped 
\family typewriter
ReadStream
\family default
 that satisfy the logical test of a single-argument block being applied
 to each element.
 It is created by applying the 
\family typewriter
select:
\family default
 or 
\family typewriter
reject:
\family default
 method to any 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "collect: (message)"

\end_inset

CollectStream
\family default
 is a 
\family typewriter
StreamProcessor
\family default
 that returns the results of applying a single-argument block to each element
 of a 
\family typewriter
ReadStream
\family default
 that it wraps.
 It is created by applying the 
\family typewriter
collect:
\family default
 method to any 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "inject:into: (message)"

\end_inset


\family typewriter
InjectStream
\family default
 is a 
\family typewriter
StreamProcessor
\family default
 that returns the results of successively applying a two-argument block
 to an initial seed and each stream element.
 The result of the block is used as seed for the next block application.
 It is created by applying the 
\family typewriter
inject:into:
\family default
 method to any 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "splitWith: (message)"

\end_inset

Tokenizer
\family default
 is a 
\family typewriter
StreamProcessor
\family default
 that returns the sequences of elements between a given set of separators.
 It is created by applying the 
\family typewriter
split
\family default
 (using whitespace separators) or 
\family typewriter
splitWith:
\family default
 methods to any 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description
\begin_inset LatexCommand index
name "generate:until: (message)"

\end_inset


\family typewriter
GeneratorStream
\family default
 is a 
\family typewriter
ReadStream
\family default
 that returns the results of successively applying a single-argument block
 to an initial seed.
 The result of the block is used as seed for the next block.
 The method 
\family typewriter
generate:until:
\family default
 creates such a stream with a termination block which takes each element
 as the argument to determine where the stream should end.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "readBuffered (message)"

\end_inset

ReadBufferStream
\family default

\begin_inset LatexCommand label
name "des:ReadBufferStream"

\end_inset

 wraps another stream with a special 
\family typewriter
Buffer
\family default
 object for reading large chunks from the stream at a time while handing
 out the elements as requested.
 This also minimizes stress on the memory-allocator by avoiding unnecessary
 allocation of arrays.
 It is created by applying the 
\family typewriter
readBuffered
\family default
 method to any 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "writeBuffered (message)"

\end_inset

WriteBufferStream
\family default

\begin_inset LatexCommand label
name "des:WriteBufferStream"

\end_inset

 wraps another stream with a special 
\family typewriter
Buffer
\family default
 object for writing large chunks to the stream at a time while accepting
 new elements as requested.
 This also minimizes stress on the memory-allocator by avoiding unnecessary
 allocation of arrays.
 It is created by applying the 
\family typewriter
writeBuffered
\family default
 method to any 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Subsubsection
Basic Instantiation
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "creation, streams"

\end_inset


\begin_inset LatexCommand index
name "stream creation"

\end_inset

There are a number of ways to create 
\family typewriter
Stream
\family default
s, and a large number of implementations, so some methods exist to simplify
 the process of making a new one:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newOn: (message)"

\end_inset

newOn:
\family default
 creates a new 
\family typewriter
Stream
\family default
 of the same type as the first argument, targeting it to the second as a
 source.
 This should not be overridden.
 Instead, the re-targeting method 
\family typewriter
on:
\family default
 is overridden.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newTo: (message)"

\end_inset

newTo:
\family default
 creates a new 
\family typewriter
WriteStream
\family default
 of the appropriate type on the specified target.
 This should be overridden for derived types, and the first argument should
 apply to the generic 
\family typewriter
Stream
\family default
 type to allow any instance to know this protocol.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newFrom: (message)"

\end_inset

newFrom:
\family default
 creates a new 
\family typewriter
ReadStream
\family default
 of the appropriate type on the specified target.
 This should be overridden for derived types, and the first argument should
 apply to the generic 
\family typewriter
Stream
\family default
 type to allow any instance to know this protocol.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "buffered (message)"

\end_inset

buffered
\family default
 creates and returns a new 
\family typewriter
BufferStream
\family default
 whose type corresponds to the argument and wraps the argument 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "readBuffered (message)"

\end_inset

readBuffered
\family default
 creates and returns a new 
\family typewriter
ReadBufferStream
\family default
 which wraps the argument 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "writeBuffered (message)"

\end_inset

writeBuffered
\family default
 creates and returns a new 
\family typewriter
WriteBufferStream
\family default
 which wraps the argument 
\family typewriter
Stream
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "echoTo: (message)"

\end_inset

echoTo:
\family default
 creates and returns a new 
\family typewriter
EchoStream
\family default
 which wraps the first argument 
\family typewriter
Stream
\family default
 and echoes to the second.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "echo (message)"

\end_inset

echo
\family default
 creates and returns a new 
\family typewriter
EchoStream
\family default
 to the 
\family typewriter
Console
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name ">> (message)"

\end_inset

>>
\family default
 performs a looping iterative transfer of all elements of the first stream
 to the second.
 The second argument may be any 
\family typewriter
WriteStream
\family default
, or a 
\family typewriter
StreamProcessor
\family default
, or a single-argument 
\family typewriter
Method
\family default
 in which case it has the same semantics as 
\family typewriter
collect:
\family default
.
 For targets to 
\family typewriter
ExternalResource
\family default
s, it will perform a buffered transfer.
 This method always returns the target stream so that the results may be
 further processed.
\end_layout

\begin_layout Subsubsection
Collecting Protocols
\end_layout

\begin_layout Standard
Mirroring the collection protocols, streams support a mirror of that interface
 (
\family typewriter
do:
\family default
, 
\family typewriter
select:
\family default
, 
\family typewriter
collect:
\family default
, 
\family typewriter
reject:
\family default
, 
\family typewriter
inject:into:
\family default
).
 The difference is that where collections would answer other collections,
 streams return corresponding streams.
\end_layout

\begin_layout Subsubsection
\begin_inset LatexCommand label
name "sub:Iterator-Streams"

\end_inset

Iterator Streams
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "iterator streams"

\end_inset


\begin_inset LatexCommand index
name "streams, iterator"

\end_inset


\begin_inset LatexCommand index
name "Set ReadStream (object)"

\end_inset

Many types (typically collections) define their own 
\family typewriter
Stream
\family default
 type which goes over its elements in series, even if the collection is
 not ordered, and only visits each element once.
 This type's prototype is accessed via the slot 
\family typewriter
ReadStream
\family default
 within each collection (located on its traits object).
 So 
\begin_inset Quotes eld
\end_inset


\family typewriter
Set\InsetSpace ~
ReadStream
\family default

\begin_inset Quotes erd
\end_inset

 refers to the prototype suitable for iterating over 
\family typewriter
Set
\family default
s.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "iterator (message)"

\end_inset

In order to create a new iterator for a specific collection, the 
\family typewriter
iterator
\family default
 message is provided, which clones the prototype for that collection's type
 and targets it to the receiver of the message.
 The protocol summary:
\end_layout

\begin_layout Description

\family typewriter
iterator
\family default
 will return a 
\family typewriter
ReadStream
\family default
 or preferably a 
\family typewriter
ReadWriteStream
\family default
 if one is available for the type, targetted to the argument of the message.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "reader (message)"

\end_inset


\begin_inset LatexCommand index
name "writer (message)"

\end_inset

reader
\family default
 and 
\family typewriter
\series bold
writer
\family default
\series default
 get streams with only 
\family typewriter
ReadStream
\family default
 and 
\family typewriter
WriteStream
\family default
 capabilities for the type, when available, targetted to the argument of
 the message.
\end_layout

\begin_layout Standard
The stream capabilities supported for each basic collection type are usually
 limited by the behavior that the type supports.
 The capabilities per basic type are as follows; types not mentioned inherit
 or specialize the capabilities of their ancestors:
\end_layout

\begin_layout Standard
\align center
\begin_inset Tabular
<lyxtabular version="3" rows="6" columns="2">
<features>
<column alignment="center" valignment="top" leftline="true" width="0sp">
<column alignment="center" valignment="top" leftline="true" rightline="true" width="0sp">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Type
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Capabilities
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Collection
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
none
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
ExtensibleCollection
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Write
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Bag
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Read and Write separately
\end_layout

\end_inset
</cell>
</row>
<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Sequence
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Positionables (R, W, RW); copy for extension
\end_layout

\end_inset
</cell>
</row>
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
ExtensibleSequence
\end_layout

\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text

\begin_layout Standard
Positionables (R, W, RW)
\end_layout

\end_inset
</cell>
</row>
</lyxtabular>

\end_inset


\end_layout

\begin_layout Subsection
External Resources
\begin_inset LatexCommand label
name "sub:External-Resources"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "external resources"

\end_inset


\begin_inset LatexCommand index
name "resources, external"

\end_inset

Slate includes an extensible framework for streams that deal with external
 resources, such as files or network connections or other programs.
 This generally relies on having a representative object in the image which
 tracks the underlying primitive identity of the resource, and also provides
 methods for iterator-style streams over what is available through the resources.
 Many of these resources aren't sequences as files are sequences of bytes,
 so they're asynchronous and behave differently from ordinary streams.
\end_layout

\begin_layout Paragraph
Basic Types
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ExternalResource (object)"

\end_inset

ExternalResource
\family default
 provides the basic behavior for external resource types.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ExternalResource Locator (object)"

\end_inset

ExternalResource\InsetSpace ~
Locator
\family default
 provides a core attribute type for structured descriptors of external resources
, as a generalization of file pathnames, port descriptions, URLs, or even
 URIs.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ExternalResource Stream (object)"

\end_inset

ExternalResource\InsetSpace ~
Stream
\family default
 provides an extension of the iterator interface (described on 
\begin_inset LatexCommand vref
reference "sub:Iterator-Streams"

\end_inset

) for 
\family typewriter
ExternalResource
\family default
s.
 All of them provide 
\family typewriter
ReadStream
\family default
, 
\family typewriter
WriteStream
\family default
, and 
\family typewriter
ReadWriteStream
\family default
 variants as appropriate.
\end_layout

\begin_layout Paragraph
Primitives
\end_layout

\begin_layout Standard
Extending the framework to cover new primitive or otherwise connection types
 is fairly simple, since the following methods are the only input/output
 primitives needed for defining an external resource type:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "read:from:startingAt:into: (message)"

\end_inset

resource\InsetSpace ~
read:\InsetSpace ~
n\InsetSpace ~
from:\InsetSpace ~
handle\InsetSpace ~
startingAt:\InsetSpace ~
start\InsetSpace ~
into:\InsetSpace ~
array
\family default
 reads the next n elements from the resource identified by the given low-level
 handle, from the given starting point.
 The contents are placed in the given array, which should be a 
\family typewriter
ByteArray
\family default
 currently.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "write:to:startingAt:from: (message)"

\end_inset

resource\InsetSpace ~
write:\InsetSpace ~
n\InsetSpace ~
to:\InsetSpace ~
handle\InsetSpace ~
startingAt:\InsetSpace ~
start\InsetSpace ~
from:\InsetSpace ~
array
\family default
 writes the next n elements to the resource identified by the given low-level
 handle, from the given starting point.
 The contents are read from the given array, which should be a 
\family typewriter
ByteArray
\family default
 currently.
\end_layout

\begin_layout Paragraph
Standard behavior
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "open (message)"

\end_inset

open
\family default
 Opens the resource for usage within the system.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "close (message)"

\end_inset

close
\family default
 Closes the resource, releasing related administrative data; this happens
 automatically during garbage collection, but it is poor practice to rely
 upon this.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "enable (message)"

\end_inset

enable
\family default
 Creates the external resource represented (used by 
\family typewriter
open
\family default
).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "isOpen (message)"

\end_inset

isOpen
\family default
 answers whether the resource is open or closed.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "isActive (message)"

\end_inset

isActive
\family default
 answers whether the resource is active.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "restart (message)"

\end_inset

restart
\family default
 restarts the resource if it's already active.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "flush (message)"

\end_inset

flush
\family default
 flushes any unwritten elements.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "commit (message)"

\end_inset

commit
\family default
 commits all pending write-out information to the resource.
 Commit performs a flush but also ensures that the data is actually sent
 to the peer.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "read:startingAt:into: (mesage)"

\end_inset

read:startingAt:into:
\family default
 sends 
\family typewriter
read:from:startingAt:into:
\family default
 with the resource's handle.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "write:startingAt:into: (message)"

\end_inset

write:startingAt:from:
\family default
 sends 
\family typewriter
write:to:startingAt:from:
\family default
 with the resource's handle.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "interactor (message)"

\end_inset

interactor
\family default
 returns a 
\family typewriter
ReadWriteStream
\family default
 for accessing the resource.
 Unlike the stream that 
\family typewriter
iterator
\family default
 returns, 
\family typewriter
interactor
\family default
 is expected to return a coupled pair of a 
\family typewriter
ReadStream
\family default
 and 
\family typewriter
WriteStream
\family default
 over the same resource, synchronized to preserve the resource's behavior.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "bufferSize (message)"

\end_inset

bufferSize
\family default
 answers a sensible buffer size for interaction, possibly dynamically determined.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "defaultBufferSize (message)"

\end_inset

defaultBufferSize
\family default
 answers a default sensible buffer size for interaction.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "locator (message)"

\end_inset

locator
\family default
 answers a suitable structured object for dealing with that resource's identity/
location.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "sessionDo: (message)"

\end_inset

sessionDo:
\family default
 executes a code block with the resource as its argument, opening and closing
 the resource transparently to the block, even for abnormal terminations.
 If the resource is already open, then this takes no opening or closing
 actions, so that calls may be nested blindly.
\end_layout

\begin_layout Subsubsection
Consoles
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Console (object)"

\end_inset


\begin_inset LatexCommand index
name "ConsoleInput (object)"

\end_inset


\begin_inset LatexCommand index
name "ConsoleOutput (object)"

\end_inset

The Slate interpreter provides two console 
\family typewriter
Streams
\family default
 primitively, 
\family typewriter
ConsoleInput
\family default
 and 
\family typewriter
ConsoleOutput
\family default
, which are 
\family typewriter
Read
\family default
- and 
\family typewriter
WriteStreams
\family default
 by default, capturing keyboard input and writing out to the console, respective
ly.
 These are also accessible as 
\family typewriter
Console\InsetSpace ~
reader
\family default
 and 
\family typewriter
Console\InsetSpace ~
writer
\family default
.
 
\family typewriter
Console\InsetSpace ~
interactor
\family default
 delegates to these, acting as a 
\family typewriter
ReadWriteStream
\family default
.
\end_layout

\begin_layout Subsubsection
Files
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "files"

\end_inset


\begin_inset LatexCommand index
name "File (object)"

\end_inset

Files are persistent external sequences of bytes.
 The interpreter provides an object type 
\family typewriter
File
\family default
 which provides the corresponding protocol extensions to 
\family typewriter
ExternalResource
\family default
:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newNamed:\\&mode: (message)"

\end_inset

newNamed:&mode:
\family default
 returns a new 
\family typewriter
File
\family default
 with the given name as its locator and also a mode option.
 No attempt to open the file is automatically made.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "sessionDo:\\&mode: (message)"

\end_inset

sessionDo:&mode:
\family default
 extends 
\family typewriter
sessionDo:
\family default
 with a simple temporary mode option (which is reset on return).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "withOpenNamed:Do:\\&mode: (message)"

\end_inset

withOpenNamed:do:&mode:
\family default
 wraps 
\family typewriter
sessionDo:
\family default
 with the ability to create a new 
\family typewriter
File
\family default
 dynamically for the session along with a specified mode.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "position (message)"

\end_inset

position
\family default
 returns the position within the 
\family typewriter
File
\family default
 in byte units.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "position: (message)"

\end_inset

position:
\family default
 sets the position within the 
\family typewriter
File
\family default
 to the given integer number of bytes.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "size (message)"

\end_inset

size
\family default
 returns the 
\family typewriter
File
\family default
 size in bytes.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "name (message)"

\end_inset

name
\family default
 returns the 
\family typewriter
File
\family default
's pathname.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "fullName (message)"

\end_inset

fullName
\family default
 will always return a complete pathname whereas the regular method may not.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "renamedTo: (message)"

\end_inset

renameTo:
\family default
 adjusts the file to have the given name.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "atEnd (message)"

\end_inset

isAtEnd
\family default
 answers whether the file's end has been reached.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "create (message)"

\end_inset

create
\family default
 makes a file with the given name, with empty contents.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "exists (message)"

\end_inset

exists
\family default
 answers whether there is a file with the object's pathname.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "delete (message)"

\end_inset

delete
\family default
 deletes the file.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "load: (message)"

\end_inset

Perhaps the most important utility is to load libraries based on path names.
 
\family typewriter
load: 'filename'
\family default
 will execute a file with the given path name as Slate source.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "File Read (object)"

\end_inset


\begin_inset LatexCommand index
name "File Write (object)"

\end_inset


\begin_inset LatexCommand index
name "File ReadWrite (object)"

\end_inset


\begin_inset LatexCommand index
name "File CreateWrite (object)"

\end_inset

File mode objects specify the interaction capabilities requested of the
 underlying system for the handle.
 The modes consist of 
\family typewriter
File\InsetSpace ~
Read
\family default
, 
\family typewriter
File\InsetSpace ~
Write
\family default
, 
\family typewriter
File\InsetSpace ~
ReadWrite
\family default
, and 
\family typewriter
File\InsetSpace ~
CreateWrite
\family default
.
\end_layout

\begin_layout Subsubsection
Shells and Pipes (Not Currently Implemented)
\begin_inset OptArg
status collapsed

\begin_layout Standard
Shells and Pipes
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "Shell (object)"

\end_inset


\begin_inset LatexCommand index
name "Environment (object)"

\end_inset

The 
\family typewriter
Shell
\family default
 and 
\family typewriter
Environment
\family default
 globals are provided to access the underlying operating system's command
 shell functionality from within the Slate environment.
 
\family typewriter
Shell
\family default
 provides a dispatch hook for shell-related methods, while 
\family typewriter
Environment
\family default
 acts as a 
\family typewriter
Dictionary
\family default
 of the current shell context's defined variables and values.
 They support several primitive methods as follows:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "enter (message)"

\end_inset

Shell\InsetSpace ~
enter
\family default
 enters the host operating system's command-line shell.
 This has no effect on the Slate environment directly except for suspending
 and resuming it.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "runProgram:withArgs: (message)"

\end_inset

Shell\InsetSpace ~
runProgram:\InsetSpace ~
programName\InsetSpace ~
withArgs:\InsetSpace ~
argsArray
\family default
 executes the program with the given name and passes it the arguments which
 must be 
\family typewriter
Strings
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "execute: (message)"

\end_inset

Shell\InsetSpace ~
execute:\InsetSpace ~
scriptFilename
\family default
 passes the contents of the file named along to the shell, returning its
 output.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "at: (message)"

\end_inset

Environment\InsetSpace ~
at:\InsetSpace ~
varName
\family default
 returns the value stored in a given environment variable.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "at:put: (message)"

\end_inset

Environment\InsetSpace ~
at:\InsetSpace ~
varName\InsetSpace ~
put:\InsetSpace ~
newValue
\family default
 stores the new value into the given environment variable named.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "keys (message)"

\end_inset

Environment\InsetSpace ~
keys
\family default
 returns an 
\family typewriter
Array
\family default
 of the environment variable names defined in the context that Slate was
 executed in.
 This result is independent of the actual environment variables.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "values (message)"

\end_inset

Environment\InsetSpace ~
values
\family default
 returns an 
\family typewriter
Array
\family default
 of the environment variable values in the context that Slate was executed
 in, in the same order as the keys are returned.
 This result is independent of the actual environment variables.
\end_layout

\begin_layout Subsubsection
Networking
\end_layout

\begin_layout Standard

\family typewriter
\begin_inset LatexCommand index
name "Socket (object)"

\end_inset

Socket
\family default
s are 
\family typewriter
ExternalResources
\family default
 that provide a connection on an operating system port.
 The behaviors specific to these two types are as follows:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newOnPort: (message)"

\end_inset

newOnPort:
\family default
 creates a new socket of the appropriate type to listen/request on the port
 number.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "listen (message)"

\end_inset

listen\InsetSpace ~
&buffer:
\family default
 sets the port to listening for client connections, with an optional override
 of the system default number of request queue entries.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "accept (message)"

\end_inset

accept
\family default
 creates a new socket connection for the next incoming request.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "shutdown (message)"

\end_inset

shutdown
\family default
 shuts down the socket, called when closing (automatically).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "host (message)"

\end_inset

host
\family default
 answers the hostname of the socket.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "port (message)"

\end_inset

port
\family default
 answers the port number of the socket.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "peerHost (message)"

\end_inset

peerHost
\family default
 answers the hostname of the peer.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "peerPort (message)"

\end_inset

peerPort
\family default
 answers the peer's port number.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "peerIP (message)"

\end_inset

peerIP
\family default
 answers the Internet Protocol address string of the peer, if any.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "status (message)"

\end_inset

status
\family default
 answers a 
\family typewriter
Symbol
\family default
 representing the socket's current status.
\end_layout

\begin_layout Subsection
Paths
\end_layout

\begin_layout Standard
Since the environment is structured into namespaces and many types have
 so-called 
\begin_inset Quotes eld
\end_inset

attribute types
\begin_inset Quotes erd
\end_inset

 (for example, the iterator streams), it is helpful to have more than a
 name by which to refer to an object or its location in the system.
 The path library allows doing this with 
\family typewriter
Path
\begin_inset LatexCommand index
name "Path (object)"

\end_inset


\family default
 objects, which describe the sequence of slot traversals necessary to reach
 a particular object.
 A sub-variant called 
\family typewriter
RootedPath
\begin_inset LatexCommand index
name "RootedPath (object)"

\end_inset


\family default
 remembers the specific origin object used for the path and follows the
 same protocol.
\end_layout

\begin_layout Description

\family typewriter
Path\InsetSpace ~
from:\InsetSpace ~
root\InsetSpace ~
to:\InsetSpace ~
target
\begin_inset LatexCommand index
name "from:to: (message)"

\end_inset


\family default
 creates a new 
\family typewriter
Path
\family default
 object containing the necessary slot traversals to obtain the target object
 (the destination) from the given root (the origin).
 Paths are created by searching breadth-first through slot names; if the
 search completes without an identical match, 
\family typewriter
Nil
\family default
 is returned.
\end_layout

\begin_layout Description

\family typewriter
to:
\begin_inset LatexCommand index
name "to: (message)"

\end_inset


\family default
 works like 
\family typewriter
from:to:
\family default
 except that 
\family typewriter
here
\family default
 is taken as the origin.
\end_layout

\begin_layout Description

\family typewriter
target
\begin_inset LatexCommand index
name "target (message)"

\end_inset


\family default
 answers the target object as computed by following the slot names from
 the origin.
\end_layout

\begin_layout Description

\family typewriter
targetFrom:
\begin_inset LatexCommand index
name "targetFrom: (message)"

\end_inset


\family default
 answers the target object relative to the given one, taking it as the origin.
\end_layout

\begin_layout Description

\family typewriter
reduced
\begin_inset LatexCommand index
name "reduced (message)"

\end_inset


\family default
 answers another equivalent 
\family typewriter
Path
\family default
 object consisting of all non-delegation slots traversed.
 This gives a 
\begin_inset Quotes eld
\end_inset

canonical
\begin_inset Quotes erd
\end_inset

 or shortest path to the object.
\end_layout

\begin_layout Description

\family typewriter
expanded
\begin_inset LatexCommand index
name "expanded (message)"

\end_inset


\family default
 answers another equivalent 
\family typewriter
Path
\family default
 object consisting of all delegation slots required to traverse to reach
 the object directly.
\end_layout

\begin_layout Description

\family typewriter
root\InsetSpace ~
knows:\InsetSpace ~
target
\begin_inset LatexCommand index
name "target (message)"

\end_inset


\family default
 answers whether there is a 
\family typewriter
Path
\family default
 from the given root to the target.
\end_layout

\begin_layout Description

\family typewriter
isWellKnown
\begin_inset LatexCommand index
name "isWellKnown (message)"

\end_inset


\family default
 answers whether there is a 
\family typewriter
Path
\family default
 from the 
\family typewriter
lobby
\family default
 to the given object.
\end_layout

\begin_layout Standard

\family typewriter
Path
\family default
 objects also respond to relevant 
\family typewriter
Sequence
\family default
 protocols such as 
\family typewriter
;
\begin_inset LatexCommand index
name "; (message)"

\end_inset


\family default
 and 
\family typewriter
isPrefixOf:
\begin_inset LatexCommand index
name "isPrefixOf: (message)"

\end_inset


\family default
 among other paths.
\end_layout

\begin_layout Subsection
Exceptional Situations and Errors
\begin_inset OptArg
status open

\begin_layout Standard
Exceptions
\end_layout

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "error handling"

\end_inset


\begin_inset LatexCommand index
name "exceptions"

\end_inset


\begin_inset LatexCommand index
name "Condition (object)"

\end_inset

Slate has a special kind of object representing when an exceptional situation
 has been reached in a program, called a 
\family typewriter
Condition
\family default
.
 Condition objects may have attributes and methods like other ordinary objects,
 but have special methods for dealing with exceptional situations and recovering
 from them in various ways, often automatically.
\end_layout

\begin_layout Subsubsection
Types
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Condition (object)"

\end_inset

Condition
\family default
 An object representing a situation which must be handled.
 This also provides a hook for working with the control-flow of the situation,
 and dynamic unwinding of control.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Restart (object)"

\end_inset

Restart
\family default
 An object representing and controlling how a condition is handled.
 Because they are a kind of 
\family typewriter
Condition
\family default
, they can themselves be handled dynamically.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Warning (object)"

\end_inset


\begin_inset LatexCommand index
name "warn: (message)"

\end_inset

Warning
\family default
 A 
\family typewriter
Condition
\family default
 which should generate notifications, but does not need to be raised for
 handling, i.e.
 no action needs to be taken.
 Raised by 
\family typewriter
warn:
\family default
 with a description.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "StyleWarning (object)"

\end_inset


\begin_inset LatexCommand index
name "note: (message)"

\end_inset

StyleWarning
\family default
 A 
\family typewriter
Warning
\family default
 that certain conventions set up by the library author have not been followed,
 which could lead to problems.
 Raised by 
\family typewriter
note:
\family default
 with a description.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "BreakPoint (object)"

\end_inset


\begin_inset LatexCommand index
name "break (message)"

\end_inset

BreakPoint
\family default
 A 
\family typewriter
Condition
\family default
 that pauses the current computation.
 Raised by 
\family typewriter
break
\family default
 in a context.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Abort (object)"

\end_inset


\begin_inset LatexCommand index
name "abort (message)"

\end_inset

Abort
\family default
 A 
\family typewriter
Restart
\family default
 which unwinds the stack and cleans up contexts after a condition is raised.
 This is raised by the context method 
\family typewriter
abort
\family default
.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "SeriousCondition (object)"

\end_inset

SeriousCondition
\family default
 A 
\family typewriter
Condition
\family default
 that requires handling, but is not a semantic error of the program.
 Rather, it's due to some incidental or pragmatic consideration.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Error (object)"

\end_inset


\begin_inset LatexCommand index
name "error: (message)"

\end_inset

Error
\family default
 A 
\family typewriter
SeriousCondition
\family default
 which involves some misstep in program logic, and raises the need for handlers
 to avoid a program crash.
 Raised by 
\family typewriter
error:
\family default
 with a description.
\end_layout

\begin_layout Subsubsection
Protocol
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "signal (message)"

\end_inset

signal
\family default
 Raises the exception that is the argument.
 This will immediately query for exception handlers in the current context,
 performing dynamic automatic recovery if possible, or starting the debugger
 if not.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "on:do: (message)"

\end_inset

on:do:
\family default
 Executes the block of code with a dynamically bound handler block for the
 given type of condition.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "ensure: (message)"

\end_inset

ensure:
\family default
 This is a block method that ensures that the second block is executed either
 after the first or in 
\emph on
any
\emph default
 case if the original is aborted or control is otherwise handed elsewhere
 in the middle of execution without possibility of returning into that same
 execution.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "handlingCases: (message)"

\end_inset

handlingCases:
\family default
 Executes the block of code with a set of dynamically bound handler blocks,
 give as an 
\family typewriter
Array
\family default
 of 
\family typewriter
Association
\family default
s between 
\family typewriter
Condition
\family default
 objects and the handlers.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "return (message)"

\end_inset


\begin_inset LatexCommand index
name "return: (message)"

\end_inset

return
\family default
/
\family typewriter
return:
\family default
 Returns from the condition with a value (default 
\family typewriter
Nil
\family default
), to the point where the condition was signalled.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "exit (message)"

\end_inset


\begin_inset LatexCommand index
name "exit: (message)"

\end_inset

exit
\family default
/
\family typewriter
exit:
\family default
 Aborts from the condition, or aborts from it with a value, to the point
 where the handler was set up.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "defaultHandler (message)"

\end_inset

defaultHandler
\family default
 This is the condition method that is called if no other handlers are found
 for the context.
\end_layout

\begin_layout Subsection
Concurrency
\begin_inset LatexCommand index
name "concurrency"

\end_inset


\end_layout

\begin_layout Subsubsection
Processes
\end_layout

\begin_layout Standard
Concurrency mostly involves the unit of the 
\family typewriter
Process
\family default
, which is conceptually a manager for a single interpreter.
 Concurrency may be performed within the context of a single process, using
 stack / control-flow interaction, or across processes using messaging.
\end_layout

\begin_layout Standard

\family typewriter
Process
\family default
es in Slate run in turns, each acting as an interpreter with an event loop.
 They also act as object pools, being opaque and having a context with various
 local elements which must be explicitly published to be visible to objects
 in other Processes.
\end_layout

\begin_layout Subsubsection
Promises and Eventual-Sends
\end_layout

\begin_layout Standard
Coupled with event-loop concurrency is Slate's support of deferred execution,
 using the 
\family typewriter
%
\family default
 prefix for selectors (for the message-send) or for entire expressions.
 When a deferral is performed on a message-send, we call it an eventual
 message-send.
 If the return value is in a syntactic position where it might be used,
 the caller may expect an object of type 
\family typewriter
Reference
\family default
 or 
\family typewriter
Promise
\family default
 to be delivered as the answer.
 These objects are resolvable placeholders, which may also communicate errors
 in the requested computation.
\end_layout

\begin_layout Standard
What's significant is that the use of deferred evaluation means that the
 relevant expression costs the caller nothing in the immediate execution
 turn; no matter how expensive side-effecting an expression may be, it will
 not be executed until at least the next turn in the owning process.
 Specifically, when a deferred expression is evaluated, it is turned into
 an event and added to the end of the owner 
\family typewriter
Process
\family default
' queue.
 When a process finishes each turn, it executes one event at a time from
 the other end of the queue.
 Also, if one deferred expression involves the use of the return value from
 another deferred expression, the dependency will be enforced so that such
 events will execute in the data-flow partial order in which they were created.
\end_layout

\begin_layout Subsection
Types
\begin_inset LatexCommand label
name "sub:Types"

\end_inset


\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "types"

\end_inset


\begin_inset LatexCommand index
name "Types (namespace)"

\end_inset

In coordination with the reserved syntax for type-annotation in block headers,
 the standard libraries include a collection of representations of primitive
 
\noun on
types
\noun default
 as well as quantifications over those types.
 The library of types is laid out within the non-delegated namespace 
\family typewriter
Types
\family default
 in the lobby.
\end_layout

\begin_layout Subsubsection
Types
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Any (type)"

\end_inset

Any
\family default
 The type that any object satisfies: the universal type.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "None (type)"

\end_inset

None
\family default
 The type that no object satisfies: the empty type.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Range (type)"

\end_inset


\begin_inset LatexCommand index
name "start (message)"

\end_inset


\begin_inset LatexCommand index
name "finish (message)"

\end_inset

Range
\family default
 A parametrized type over another type with a linear ordering, such as 
\family typewriter
Integer
\family default
.
 This type is bounded, it has a 
\family typewriter
start
\family default
 and a 
\family typewriter
finish
\family default
 (least and greatest possible member).
 In general, any 
\family typewriter
Magnitude
\family default
 can be used as a base of a Range type.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Member (type)"

\end_inset

Member
\family default
 The type associated with membership in a specific set of objects.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Singleton (type)"

\end_inset

Singleton
\family default
 The type of a single object, as distinct from any other object.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Clone (type)"

\end_inset

Clone
\family default
 The type of an object and its 
\noun on
clone family
\noun default
, the set of objects that are direct copies (clones plus changes to slot
 values) of it.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Array (type)"

\end_inset

Array
\family default
 The type representing all arrays, as parametrized by an element type and
 a length.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Block (type)"

\end_inset

Block
\family default
 The type representing code closures of a given (optional) input and output
 signature.
\end_layout

\begin_layout Subsubsection
Operations
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "union: (message)"

\end_inset


\begin_inset LatexCommand index
name "intersection: (message)"

\end_inset


\begin_inset LatexCommand index
name "derive (message)"

\end_inset


\begin_inset LatexCommand index
name "deriveWith: (message)"

\end_inset

Types may be combined in various ways, including 
\family typewriter
union:
\family default
, 
\family typewriter
intersection:
\family default
, and extended via 
\family typewriter
derive
\family default
 which preserve type constraints on the derivations.
\end_layout

\begin_layout Subsubsection
Type Annotations
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "type annotations"

\end_inset


\begin_inset LatexCommand index
name "annotations, type"

\end_inset

Local slot specifiers in a Method header as well as input slot specifiers
 may have types optionally declared within the header.
 Within a method declaration expression, the input slots may be redundantly
 specified in the header as well as in the dispatch expression.
 However, if this is done, the header's specifier needs to be specified
 as an input slot and if multiple input slot types are specified, they should
 be specified in order.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "exclamation mark"

\end_inset


\begin_inset LatexCommand index
name "\\char `\\! (exclamation mark) "

\end_inset

The syntax is similar to that for 
\family typewriter
@
\family default
-based dispatch notation: follow the slot name with the bang character 
\begin_inset Quotes eld
\end_inset


\family typewriter
!
\family default

\begin_inset Quotes erd
\end_inset

 and then a type expression, which may be a primitive or derived type.
 For example,
\end_layout

\begin_layout LyX-Code
[| :foo!Integer bar | bar: (foo raisedTo: 3).
 
\newline
foo + bar] applyWith: 4.3.
\end_layout

\begin_layout Standard
Type annotations don't use primitive expressions: the evaluator doesn't
 have a library of pre-built types at its disposal.
 Instead, Type annotation expressions are evaluated within the namespace
 named 
\family typewriter
Types
\family default
 accessible from the 
\family typewriter
lobby
\family default
.
 For this reason, user-defined named types should be installed in some place
 accessible through the 
\family typewriter
Types
\family default
 path.
\end_layout

\begin_layout Subsubsection
Type Inference
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "type inference"

\end_inset


\begin_inset LatexCommand index
name "inference, type"

\end_inset


\begin_inset LatexCommand index
name "inferTypes (message)"

\end_inset

Type-inference on syntax trees is driven by calling 
\family typewriter
inferTypes
\family default
 on the 
\family typewriter
Syntax\InsetSpace ~
Node
\family default
 in question.
 This will process type information already annotated to produce derived
 annotations on related nodes.
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "rules (slot)"

\end_inset

Also, there is a facility to extend the type-inference capability per method.
 To explain, each Type object comes with a 
\family typewriter
rules
\family default
 object slot that is dual to the traits delegate object; rules delegate
 as the traits do but do not confer to the types their methods.
 Instead, they are used by the inference system transparently to allow for
 more intelligent specialization.
 To wit:
\end_layout

\begin_layout LyX-Code
_@((Member of: {True.
 False}) rules) ifTrue: then@(Block rules)
\newline
   ifFalse: else@(Block rules)
\newline
[
\newline

  then returnType union: else returnType
\newline
].
\end_layout

\begin_layout Standard
is a type-inference extension method for 
\family typewriter
#ifTrue:ifFalse:
\family default
 for any boolean and a pair of blocks, that the return type will be in the
 union of the blocks' return types.
\end_layout

\begin_layout Subsection
Modules
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "modules"

\end_inset


\begin_inset LatexCommand index
name "provides: (message)"

\end_inset


\begin_inset LatexCommand index
name "requires: (message)"

\end_inset


\begin_inset LatexCommand index
name "features (slot)"

\end_inset


\begin_inset LatexCommand index
name "load: (message)"

\end_inset


\begin_inset LatexCommand index
name "currentModule (slot)"

\end_inset

A simple module system is provided, designed to capture the bare essentials
 of a collection of coherent code.
 The current module system is just associated with each library file for
 simplicity's sake.
 The methods 
\family typewriter
provides:
\family default
 and 
\family typewriter
requires:
\family default
 applied to the context will add to and check against a global 
\family typewriter
features
\family default
 sequence respectively, and missing requirements are noted as the code is
 loaded.
 Again for simplicity, 
\family typewriter
features
\family default
 currently contains and expects 
\family typewriter
Symbols
\family default
.
 The 
\family typewriter
load:
\family default
 method also invokes a hook to set the 
\family typewriter
currentModule
\family default
 in its context.
\end_layout

\begin_layout Subsubsection
Types
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "Module (object)"

\end_inset

Module
\family default
 a group of objects and methods, along with some information about their
 definitions.
 Modules can also provide privacy boundaries, restricting certain methods'
 accessibility outside of the module.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "FileModule (object)"

\end_inset

FileModule
\family default
 a module that has been built from source code from a file.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "System (object)"

\end_inset

System
\family default
 a collection of modules that together provide some larger service.
 Systems notably support operations on them to control large-scale libraries.
\end_layout

\begin_layout Subsubsection
Operations
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "new (message)"

\end_inset

Module\InsetSpace ~
new
\family default
 creates a new 
\family typewriter
Module
\family default
 with no contents.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newLocated: (message)"

\end_inset

Module\InsetSpace ~
newLocated:
\family default
 creates a new 
\family typewriter
Module
\family default
 with the given locator (a filename produces a 
\family typewriter
FileModule
\family default
).
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "newForFileNamed: (message)"

\end_inset

Module\InsetSpace ~
newForFileNamed:
\family default
 creates a new 
\family typewriter
FileModule
\family default
 for the given file name.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "load (message)"

\end_inset

load
\family default
 loads the module or system.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "build (message)"

\end_inset

build
\family default
 (re-)builds the module or system.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "provide: (message)"

\end_inset

provide:
\family default
 adds the element to the module's provision collection.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "provides: (message)"

\end_inset

provides:
\family default
 declares a collection's elements to be provided by the current module.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "requires: (message)"

\end_inset

requires:
\family default
 declares a collection's elements to be required by the current context.
 If any are not found, an error is raised.
\begin_inset Foot
status collapsed

\begin_layout Standard
In the future, automatic querying and loading an appropriate module could
 be added.
\end_layout

\end_inset


\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "import:from: (message)"

\end_inset

import:from:
\family default
 adds an element to the import collection of the current module from the
 other one's provisions.
 If it's not provided by the other module, an error is raised.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "importAll:from: (message)"

\end_inset

importAll:from:
\family default
 adds a collection's elements to the import collection of the current module
 from the other one's provisions.
 If it's not provided by the other module, an error is raised.
\end_layout

\begin_layout Subsubsection
Auto-loading
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "AutoLoader (object)"

\end_inset

The 
\family typewriter
AutoLoader
\family default
 object manages unloaded 
\family typewriter
Module
\family default
s and allows them to be transparently loaded when their features are requested
 (via simple message-send).
 This mechanism relies primarily on defining methods which mimick accessors
 for the actual resolved object exactly, except for the fact that their
 action involves loading the file and then re-sending the message once that
 completes successfully.
 It is essential that the match between stub and feature be exact, since
 the feature itself must replace the stub once done.
 However, the standard protocol hides these mechanics and verification successfu
lly, as follows:
\end_layout

\begin_layout Description
AutoLoader
\family typewriter
\InsetSpace ~

\family default
readFromSourceIn: takes a 
\family typewriter
File\InsetSpace ~
Locator
\family default
, reads the source in the file, and fills the database with mappings from
 the features it defines to the module representing it.
\end_layout

\begin_layout Description

\family typewriter
AutoLoader\InsetSpace ~
performScan\InsetSpace ~
&files:
\family default
 takes a list of 
\family typewriter
File\InsetSpace ~
Locator
\family default
s, runnung 
\family typewriter
readFromSourceIn:
\family default
 on each.
 By default it scans a default list.
\end_layout

\begin_layout Description

\family typewriter
AutoLoader\InsetSpace ~
installReadyItems
\family default
 reads definitions in the database, installing stubs for those which only
 take one message to resolve.
\end_layout

\begin_layout Description

\family typewriter
AutoLoader\InsetSpace ~
writeToStorage
\family default
 writes its definitions to a default external database file for quick re-constit
ution.
\end_layout

\begin_layout Description

\family typewriter
AutoLoader\InsetSpace ~
readStorage
\family default
 reads definitions from the default external database file.
 It will automatically calling 
\family typewriter
installReadyItems
\family default
.
\end_layout

\begin_layout Subsection
Persistence
\end_layout

\begin_layout Subsubsection
Slate Heap Images
\end_layout

\begin_layout Standard
Slate's environment is available for saving as a whole via the representative
 object 
\family typewriter

\begin_inset LatexCommand index
name "Image (object)"

\end_inset

Image
\family default
.
 It offers the following methods:
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "save (message)"

\end_inset

save\InsetSpace ~
&name:
\family default
 Writes out a file containing the contents of the heap, after running a
 simple cleaning sweep of memory contents.
 The filename defaults to 
\family typewriter
'slate.image'
\family default
 or to the name of the most recent filename parameter value given.
 Note that execution context state is not disturbed, so saves may occur
 in any context as a snapshot of system-wide state, including debuggers,
 inspectors, and other live running processes.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "handleShutdown (message)"

\end_inset

handleShutdown
\family default
 Performs each action (a block) in the 
\family typewriter
Image
\family default
's 
\family typewriter

\begin_inset LatexCommand index
name "shutdownActions (object)"

\end_inset

shutdownActions
\family default
 attribute, a 
\family typewriter
Dictionary
\family default
 mapping keys to those corresponding actions.
 The keys are not meaningful except for identification by the library which
 installs it, so generally 
\family typewriter
Symbol
\family default
s are used or objects which can be identified and distinguished very easily.
 
\family typewriter
handleShutdown
\family default
 is actually called by the 
\family typewriter
quit
\family default
 method.
 The purpose of shutdown actions is to clean up any state that may affect
 the surrounding environment if not handled properly.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "handleStartup (message)"

\end_inset

handleStartup
\family default
 Performs each action (a block) in the 
\family typewriter
Image
\family default
's 
\family typewriter

\begin_inset LatexCommand index
name "startupActions (object)"

\end_inset

startupActions
\family default
 attribute, a 
\family typewriter
Dictionary
\family default
 mapping keys to those corresponding actions.
 The keys are not meaningful except for identification by the library which
 installs it, so generally 
\family typewriter
Symbol
\family default
s are used or objects which can be identified and distinguished very easily.
 
\family typewriter
handleStartup
\family default
 is actually called by the 
\family typewriter
save
\family default
 method when the image is re-started, because the execution context is preserved
, and the VM sends a signal to indicate a fresh startup.
 The purpose of startup actions is to clean up any state that may be left
 over from a previous session with that Slate environment, and also to re-initia
lize state which must persist to avoid inconsistent execution of various
 services.
 
\family typewriter
ExternalResource
\family default
s (
\begin_inset LatexCommand vref
reference "sub:External-Resources"

\end_inset

) whose connections must be persistent are primary users of these hooks.
\end_layout

\begin_layout Description

\family typewriter
\begin_inset LatexCommand index
name "handleSave (message)"

\end_inset

handleSave
\family default
 Performs each action (a block) in the 
\family typewriter
Image
\family default
's 
\family typewriter

\begin_inset LatexCommand index
name "saveActions (object)"

\end_inset

saveActions
\family default
 attribute, a 
\family typewriter
Dictionary
\family default
 mapping keys to those corresponding actions.
 The keys are not meaningful except for identification by the library which
 installs it, so generally 
\family typewriter
Symbol
\family default
s are used or objects which can be identified and distinguished very easily.
 
\family typewriter
handleSave
\family default
 is actually called by the 
\family typewriter
quit
\family default
 method.
 The purpose of save actions is to clean up any state that should not be
 saved at all; for example, passwords stored for secure access to external
 resources should be purged.
 In general, startup actions should be used for any other save-related activitie
s.
\end_layout

\begin_layout Subsubsection
Heap Image Segments
\end_layout

\begin_layout Standard
We are developing methods for extracting 
\begin_inset Quotes eld
\end_inset

slices
\begin_inset Quotes erd
\end_inset

 of images and saving them on disk along with explicit linking information
 so that groups of arbitrary objects may be transported reliably.
\end_layout

\begin_layout Section
Style Guide
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "style guide"

\end_inset

Slate provides an unusual opportunity to organize programs and environments
 in unique ways, primarily through the unique object-centered combination
 of prototypes and multiple-argument dispatch.
 This section provides a guide to the generally recommended style of developing
 in this environment, to promote a better understanding of the system and
 its usage.
\end_layout

\begin_layout Subsection
Environment organization
\end_layout

\begin_layout Subsubsection
Namespaces
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "namespaces"

\end_inset

New namespaces should be used for separate categories of concepts.
 Occasionally, these are the kind that should automatically included in
 their enclosing namespace (which can be further inherited up to the lobby).
 This is done simply by placing the new namespace object in a delegate slot.
\end_layout

\begin_layout Subsubsection
Exemplars or Value Objects
\end_layout

\begin_layout Standard
These represent objects such as specific colors with well-known names, or
 cloneable objects with useful default values.
 Generally these should have capitalized names if they are cloneable, and
 can be capitalized or lowercase if not.
 For cases with a large group of such value objects, like colors, there
 usually should involve a separate namespace to avoid cluttering up the
 surrounding one.
 This also helps with naming the use of a value if the intuitive interpretation
 of its name is dependent on context.
\end_layout

\begin_layout Subsection
Naming Methods
\end_layout

\begin_layout Standard
One of the primary benefits and peculiarities of the Smalltalk
\begin_inset LatexCommand index
name "Smalltalk"

\end_inset

 family's style of method syntax is that it provides an opportunity to name
 one's protocols using something resembling a phrase.
 Usually, it is recommended to re-use protocols whenever describing similar
 behaviors, as an aid to the user's memory in matching functionality to
 a name to call; in some exceptional situations, different protocols are
 helpful when there is more than one desired algorithm or behavior to provide
 for a kind of object.
 Here are some general practices which have been brought forward from years
 of Smalltalk practice.
\end_layout

\begin_layout Subsubsection
Attributes
\end_layout

\begin_layout Standard
Attributes are perhaps the simplest to name of all, in that they are generally
 nouns or noun phrases of some sort, whether used as direct slots or methods
 which calculate a property dynamically.
\end_layout

\begin_layout Subsubsection
Queries
\end_layout

\begin_layout Standard
Methods which test for some fact or property about a single object are generally
 given a 
\begin_inset Quotes eld
\end_inset

whether
\begin_inset Quotes erd
\end_inset

-style phrase.
 For example, 
\family typewriter
myCar\InsetSpace ~
isRed
\family default
 answers whether one's car is red.
 Slate offers an additional idiom over this particular style, in that 
\family typewriter
myCar\InsetSpace ~
color\InsetSpace ~
is:\InsetSpace ~
Red
\family default
 is also possible, since 
\family typewriter
is:
\family default
 looks at both the subject and the object of the query.
 The only remaining obstacle is whether the conceived subject can stand
 on its own as a named concept; if there are multiple perspectives in normal
 use, the language can support a certain amount of ambiguity using subjective
 overrides, but there are limits to this.
\end_layout

\begin_layout Subsubsection
Creating
\end_layout

\begin_layout Standard
While the method 
\family typewriter
clone
\family default
 is the 
\emph on
core
\emph default
 of building new objects in Slate, rather than instantiating a class, there
 is still the need to provide and use an idiom for delivering optional attribute
s and varying semantics of creation to one's new objects.
 Generally, these methods should start with 
\family typewriter
new
\family default
- as a prefix to help the reader and code user to know that the original
 object will not be modified, and that the result is a new, separate individual.
 These methods are usually methods with keywords, with each of the keywords
 describing each option.
 If the keyword literally names an attribute, the optional-keyword facility
 is ideal, but if providing a grammatical phrase using prepositions, it
 is preferable to create a full keyword method.
\end_layout

\begin_layout Subsubsection
Performing Actions
\end_layout

\begin_layout Standard
The most interesting protocols are akin to commands, where one addresses
 the objects in question with a phrase that suggests performing some action.
 This should usually have one key verb for each major component of the action
 (there is usually just one action per method, but 
\family typewriter
select:thenCollect:
\family default
, for example, performs two), and prepositions or conjunctions to relate
 the verbs and nouns.
\end_layout

\begin_layout Standard
There is a particular idiom of languages without multiple dispatch to add
 the noun (or type) name of an argument to the name of a function involving
 it.
 Slate makes this unnecessary and an obstacle to polymorphism, since the
 type of an argument can be specified in a dispatch as needed.
 Of course, nouns still sometimes have a useful place in a method name,
 when the noun is not a formal type, but an informal role or usage name.
\end_layout

\begin_layout Subsubsection
Binary Operators
\end_layout

\begin_layout Standard
These are perhaps the most controversial of any programming language's protocols.
 In the Smalltalk family of syntax, there are no precedence orderings between
 operators of different names, so the issues with those do not arise.
 However, it is very tempting for the library author to re-use mathematical
 symbols for her own domain, to allow her users to have a convenient abbreviatio
n for common operations.
 While this benefits the writer of code which uses her library, there are
 domains and situations that punish the reader of the code that results.
\end_layout

\begin_layout Standard
For example, mathematical addition and multiplication symbols, 
\begin_inset Quotes eld
\end_inset


\family typewriter
+
\family default

\begin_inset Quotes erd
\end_inset

 and 
\begin_inset Quotes eld
\end_inset


\family typewriter
*
\family default

\begin_inset Quotes erd
\end_inset

, are generally associative and commutative.
 That is, repeated calls to these should be able to re-order their arguments
 arbitrarily and achieve the same result.
 For example, 
\family typewriter

\begin_inset Formula $3+4+5=4+3+5=5+4+3$
\end_inset


\family default
.
 However, string concatenation (as an example) is not commutative; we cannot
 re-order the arguments and expect the same result, i.e\SpecialChar \@.
 
\begin_inset Formula "gold"+"fish"="goldfish"

\end_inset

, whereas 
\begin_inset Formula "fish"+"gold"="fishgold"

\end_inset

\SpecialChar \@.
 Because concatenation is associative, however, we can re-use the punctuation
 style of the semi-colon 
\begin_inset Quotes eld
\end_inset


\family typewriter
;
\family default

\begin_inset Quotes erd
\end_inset

 and achieve intuitive results.
 This general style of reasoning should be applied wherever this type of
 operator name re-use could arise.
\end_layout

\begin_layout Subsection
Instance-specific Dispatch
\end_layout

\begin_layout Standard
\begin_inset LatexCommand index
name "instance-specific dispatch"

\end_inset


\begin_inset LatexCommand index
name "dispatch, instance-specific"

\end_inset

Often there are situations whether the user will want to specialize a method
 in some argument position for a specific object.
 There are various reasons to do this, and various factors to consider when
 deciding to do so.
\end_layout

\begin_layout Subsubsection
Motivations
\end_layout

\begin_layout Standard
Two common patterns where the developer wants to specialize to a single
 object usually emerge after extended usage.
 First, there are domain objects which naturally have special non-sharable
 behavior.
 For example, 
\family typewriter
True
\family default
 is clearly a particular object that helps define the semantics of the whole
 system, by representing mechanical truth abstractly.
 In other situations, the same pattern occurs where one has a 
\emph on
universal
\emph default
 concept, or locally an 
\emph on
absolute
\emph default
 concept within a domain.
\end_layout

\begin_layout Standard
Second, there are situations whether the user is demonstratively modifying
 the behavior of some 
\emph on
thing
\emph default
 in order to achieve some 
\emph on
prototype
\emph default
 that behaves in some situation as they desire.
 Depending on whether the user decides to share this behavior or not, the
 instance-specific behavior may or may not migrate to some shared 
\family typewriter
Traits
\family default
 object.
 In either case, this is an encouraged use of objects and methods within
 Slate.
\end_layout

\begin_layout Subsubsection
Limitations
\end_layout

\begin_layout Standard
There are factors which weigh 
\emph on
against
\emph default
 the use of dispatch on objects with non-shared behaviors.
 Generally, these just amount to a few simple reasons.
 First, the behavior will not be shared, which is obvious, but sometimes
 not clear to the author.
 Second, the author may mistake an object for its value or attributes, such
 as 
\family typewriter
String
\family default
s, which are not unique per their value, and so get unexpected results if
 they dispatch on a 
\family typewriter
String
\family default
 instance.
 The same is true for all literals of that nature, with the exception of
 
\family typewriter
Symbol
\family default
s.
\end_layout

\begin_layout Standard
The general rule for defining a 
\family typewriter
method
\family default
 on an instance which is a lightweight 
\begin_inset Quotes eld
\end_inset

value
\begin_inset Quotes erd
\end_inset

 object, is that the object must be reliably re-identifiable, as 
\family typewriter
Symbol
\family default
s are for the language, or through naming paths from the 
\family typewriter
lobby
\family default
 or some other object that the user is given access to, such as a method
 argument.
 Otherwise, the user must be careful to hang on to the identity of the given
 object, which offsets any polymorphism gains and exposes implementation
 details unnecessarily.
\end_layout

\begin_layout Subsection
Organization of Source
\end_layout

\begin_layout Standard
The nature (and current limitations) of defining objects, relations, and
 the methods that operate over them require a certain ordering at this point
 which is worth mentioning.
 The central point of constraints is the definition of dispatching methods:
 these methods must have their dispatch targets available at the time they
 are evaluated.
 Since there is no late-binding yet of dispatch expressions, generally the
 basic construction of one's traits and prototype definitions must all occur
 before defining methods which dispatch to them.
 The definition needs merely to introduce the actual object that will be
 used later; other features of the objects, such as the slots and methods
 defined upon it, are late-bound and will not hinder a method-definition
 expression.
\end_layout

\begin_layout Standard
In general, however, it is recommended to define methods in a 
\emph on
bottom-up
\emph default
 fashion: that more basic utilities should be introduced before the methods
 that use them.
 This allows the user (and the author) of the code to read the program sequentia
lly as a document and have some understanding of a program's components
 when only the name of the component is seen.
 Of course, this is not always possible, but it helps often enough.
\end_layout

\begin_layout Subsection
Type-Annotating Expressions
\end_layout

\begin_layout Subsection
Writing Test Cases
\end_layout

\begin_layout Standard
Slate includes a port of Smalltalk's SUnit unit-testing framework (implemented
 in 
\family typewriter
src/lib/test.slate
\family default
), as well as a collection of unit tests (in 
\family typewriter
tests/*.slate
\family default
).
 Three namespaces are provided in which users may place their 
\family typewriter
TestCase
\family default
s:
\end_layout

\begin_layout Description
testing\InsetSpace ~
UnitTests should contain unit-test cases;
\end_layout

\begin_layout Description
testing\InsetSpace ~
RegressionTests is for test cases covering bug fixes, for detecting
 regressions; and
\end_layout

\begin_layout Description
testing\InsetSpace ~
BenchmarkTests is to contain test cases for measuring the speed of
 the system.
\end_layout

\begin_layout Standard
There is a method 
\family typewriter
testing runAllTests
\family default
 which runs all 
\family typewriter
TestCase
\family default
s found in a recursive search of the UnitTests and RegressionsTests namespaces.
\end_layout

\begin_layout Standard
To write your own test cases, add a prototype derived from TestCase to the
 namespace you've chosen, within the appropriate container - either UnitTests
 or RegressionTests.
 For example, suppose you are writing test cases covering Ranges; you might
 write
\end_layout

\begin_layout LyX-Code
UnitTests addPrototype: #Range derivedFrom: {TestCase}.
\end_layout

\begin_layout Standard
Once your prototype has been constructed, add tests to it.
 Test methods are unary methods with selectors beginning with 
\family typewriter
test
\family default
.
 For instance,
\end_layout

\begin_layout LyX-Code
tc@(UnitTests Range traits) testInclusion1
\end_layout

\begin_layout LyX-Code
"Verify that all elements of an Range are found in that Range."
\end_layout

\begin_layout LyX-Code
[| range |
\end_layout

\begin_layout LyX-Code
  range: (25 to: 50 by: 1).
\end_layout

\begin_layout LyX-Code
  tc assert: (range allSatisfy: [| :item | range includes: item]).
\end_layout

\begin_layout LyX-Code
].
\end_layout

\begin_layout Standard
The important assertion methods are
\end_layout

\begin_layout LyX-Code
assert: Boolean
\end_layout

\begin_layout LyX-Code
deny: Boolean
\end_layout

\begin_layout LyX-Code
should: Method
\end_layout

\begin_layout LyX-Code
should: Method raise: Condition
\end_layout

\begin_layout LyX-Code
shouldnt: Method
\end_layout

\begin_layout LyX-Code
shouldnt: Method raise: Condition
\end_layout

\begin_layout Standard
and variants with an additional 
\family typewriter
description: String
\family default
 argument.
\end_layout

\begin_layout Standard
Once all your test methods are defined, a 
\family typewriter
suite
\family default
 method should be defined that constructs a 
\family typewriter
TestSuite
\family default
 for exercising the 
\family typewriter
TestCase
\family default
:
\end_layout

\begin_layout LyX-Code
t@(UnitTests Range traits) suite
\end_layout

\begin_layout LyX-Code
[t suiteForSelectors: {
\end_layout

\begin_layout LyX-Code
  #testInclusion1.
\end_layout

\begin_layout LyX-Code
  
\begin_inset Quotes eld
\end_inset

...
 etc.
 ...
\begin_inset Quotes erd
\end_inset


\end_layout

\begin_layout LyX-Code
}].
\end_layout

\begin_layout Standard
See also the method 
\family typewriter
TestCase suiteForSelectors:
\family default
.
 The 
\family typewriter
suite
\family default
 method is called by 
\family typewriter
runSuite
\family default
, which in turn is called by 
\family typewriter
runAllTests
\family default
.
\end_layout

\begin_layout Standard
At this point, invoking 
\family typewriter
testing runAllTests
\family default
 will exercise your new code.
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Bibliography
\begin_inset LatexCommand bibitem
label "Chambers 97"
key "Cecil"

\end_inset


\emph on
The Cecil Language: Specification & Rationale
\emph default
.
 Craig Chambers.
 Cecil/Vortex Project.
 1997.
\newline

\begin_inset LatexCommand htmlurl
name "Available Online"
target "http://www.cs.washington.edu/research/projects/cecil/www/pubs/cecil-spec.html"

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset LatexCommand bibitem
label "Salzman 04"
key "PMD"

\end_inset


\emph on
Multiple Dispatch with Prototypes
\emph default
.
 Lee Salzman, 2004.
\newline

\begin_inset LatexCommand htmlurl
name "Available Online"
target "http://tunes.org/\\~{}eihrul/pmd.pdf"

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset LatexCommand bibitem
label "Ungar et al 95"
key "SelfPR"

\end_inset


\emph on
The Self Programmer's Reference Manual
\emph default
.
 Ole Agesen, Lars Bak, Craig Chambers, Bay-Wei Chang, Urs Holzle, John Maloney,
 Randall B.
 Smith, David Ungar, and Mario Wolczko.
 Sun Microsystems and Stanford University, 4.0 edition, 1995.
 
\newline

\begin_inset LatexCommand htmlurl
name "Available Online"
target "http://research.sun.com/self/language.html"

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset LatexCommand bibitem
label "Graham 94"
key "OnLisp"

\end_inset


\emph on
On Lisp: Advance Techniques for Common Lisp
\emph default
.
 Paul Graham.
 Prentice-Hall, Inc., 1994.
\newline

\begin_inset LatexCommand htmlurl
name "Available Online"
target "http://paulgraham.com/onlisp.html"

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset LatexCommand bibitem
label "The Refactory"
key "RB"

\end_inset

The Smalltalk Refactoring Browser.
 
\begin_inset LatexCommand htmlurl
name "Online Overview"
target "http://www.refactory.com/RefactoringBrowser/Rewrite.html"

\end_inset


\end_layout

\begin_layout Bibliography
\begin_inset LatexCommand bibitem
label "Smith 96"
key "Subjective"

\end_inset


\emph on
The Subjective Prototype
\emph default
.
 Randy Smith.
 Sun Microsystems Laboratories.
 1996.
\newline

\begin_inset LatexCommand htmlurl
name "Available Online"
target "http://www-staff.mcs.uts.edu.au/~cotar/proto/randy.txt"

\end_inset


\end_layout

\begin_layout Standard

\newpage

\begin_inset LatexCommand printindex

\end_inset


\end_layout

\end_body
\end_document