#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass article
\language english
\inputencoding auto
\fontscheme bookman
\graphics default
\float_placement !htp
\paperfontsize default
\spacing single
\papersize Default
\paperpackage a4
\use_geometry 1
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\leftmargin 1.5in
\rightmargin 1.5in
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default
\layout Title
The Slate Programmer's Reference Manual
\layout Author
Brian Rice and Lee Salzman
\layout Standard
\begin_inset LatexCommand \tableofcontents{}
\end_inset
\layout Section
\pagebreak_top
Introduction
\layout Standard
Slate is a member of the Smalltalk family of languages which supports an
object model in a similar prototype-based style as Self
\begin_inset LatexCommand \cite{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, Slate is dynamic and more free-form.
It is intended that both Smalltalk and Self styles of programs can be ported
to Slate with minimal effort.
Finally, Slate contains extensions including syntactic macros, optional
keywords, optional type-declarations and subjective dispatch, that can
be used to make existing programs and environment organizations more powerful.
\layout Standard
Slate is currently implemented as an interpreter written in Common Lisp,
which loads source files to build a full environment.
A complete bootstrap is under development, which will involve many of the
optimizations of the Self system.
\layout Subsection*
Conventions
\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.
\layout Standard
Finally, many of the examples assume that the full standard library set
has been loaded, or at least the fundamental set.
To perform this, execute:
\newline
\family typewriter
'src/init.slate'\SpecialChar ~
fileIn.
\newline
\family default
when the interpreter is running.
Additional libraries can be loaded with a similar syntax.
\layout Subsection*
Terms
\layout Standard
Slate is an object-oriented language, and as such works with some terms
worth describing initially for clarity:
\layout Description
Object some thing in the system that can be identified.
\layout Description
Method some behavior or procedure that is defined on some objects or class
of objects.
\layout Description
Message the act of requesting a behavior or procedure from some objects,
the message's arguments.
\layout Description
Selector the name of a method or a message-send.
\layout Description
Inheritance a relationship between objects that confers the parent's behavior
on the child.
\layout Description
Dispatch the process of determining, from a message-send, what method is
appropriate to invoke to implement the behavior.
\layout Section
Language Reference
\layout Subsection
Objects
\layout Standard
\noun on
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 are mappings
from symbols to other objects, and roles 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.
\layout Standard
Objects in Slate are created by
\emph on
cloning
\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{sub:Methods}
\end_inset
on Methods.
\layout Standard
Both control flow and methods are implemented by specialized objects called
blocks, which are code closures.
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.
\layout Subsubsection
Block Closures
\layout Standard
\begin_inset LatexCommand \label{sub:Block-Closures}
\end_inset
A block closure represents an encapsulable context of execution, containing
local variables, input variables, the capability to execute expressions
sequentially, and finally returns a value to its point of invocation.
The default return value for a block is the last expression's value; an
early return can override this.
\layout Standard
Block closures have a special syntax for building them up syntactically.
Blocks can specify input slots and local slots in a header between vertical
bars (
\family typewriter
||
\family default
), and then a sequence of expressions which comprises the block's body.
Block expressions are delimited by square brackets.
The input syntax allows specification of the slot names desired at the
beginning.
For example,
\layout LyX-Code
Slate> [| :i j k | j: 4.
k: 5.
j + k - i].
\newline
\emph on
[]
\layout Standard
creates and returns a new block.
Within the header, identifiers that begin with a colon such as
\family typewriter
:i
\family default
above are parsed as input slots.
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
j\SpecialChar ~
+\SpecialChar ~
k\SpecialChar ~
-\SpecialChar ~
i
\family default
.
In this block,
\family typewriter
i
\family default
is an input slot, and
\family typewriter
j
\family default
and
\family typewriter
k
\family default
are local slots which are 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.
\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.
\layout Standard
In order to invoke a block, the client must know how many and in what order
it takes input arguments.
Arguments are passed in using one of several messages.
By evaluating these messages, the block is immediately evaluated, and the
result of the evaluation is the block's execution result.
\layout Standard
Blocks that don't expect any inputs respond to
\family typewriter
value
\family default
, as follows:
\layout LyX-Code
Slate> [| a b | a: 4.
b: 5.
a + b] value.
\newline
\emph on
9
\layout Standard
Blocks that take one, two, or three inputs, each have special messages
\family typewriter
value:
\family default
,
\family typewriter
value:value:
\family default
, and
\family typewriter
value:value:value:
\family default
which pass in the inputs in the order they were declared in the block header.
Every block responds properly to
\family typewriter
values:
\family default
however, which takes an array of the input values as its other argument.
\layout LyX-Code
Slate> [| :x :y | x quo: y] value: 17 value: 5.
\newline
\emph on
3
\newline
\emph default
Slate> [| :a :b :c | (b raisedTo: 2) - (4 * a * c)]
\newline
values: {3.
4.
5}.
\newline
\emph on
-44
\layout Standard
If a block is empty, contains an empty body, or the final expression is
terminated with a period, it returns
\family typewriter
Nil
\family default
when evaluated:
\layout LyX-Code
Slate> [] value.
\newline
\emph on
Nil
\emph default
\newline
Slate> [| :a :b |] values: {0.
2}.
\newline
\emph on
Nil
\layout LyX-Code
Slate> [3.
4.] value.
\newline
\emph on
Nil
\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 closure since it
\begin_inset Quotes eld
\end_inset
closes over
\begin_inset Quotes erd
\end_inset
the environment and variables used in its definition.
This is critical for implementing good control structures in Slate, as
is explained later.
Basically a block is an activation frame composed with an environment that
can be saved and invoked (perhaps multiple times) long after it is created.
\layout Subsubsection
Slot Properties
\layout Standard
Slots may be mutable or immutable, and explicit slots or delegation (inheritance
) slots.
These four possibilities are covered by four primitive methods defined
on all objects.
\layout Standard
Slate provides several primitive messages to manage slots:
\layout Description
\family typewriter
object\SpecialChar ~
addSlot:\SpecialChar ~
slotSymbol
\family default
adds a slot using the symbol as its name, initialized to
\family typewriter
Nil
\family default
.
\layout Description
\family typewriter
object\SpecialChar ~
addSlot:\SpecialChar ~
slotSymbol\SpecialChar ~
valued:\SpecialChar ~
val
\family default
adds a slot under the given name and initializes its value to the given
one.
\layout Description
\family typewriter
object\SpecialChar ~
addDelegate:\SpecialChar ~
slotSymbol
\family default
and
\family typewriter
\series bold
object\SpecialChar ~
addDelegate:\SpecialChar ~
slotSymbol valued:\SpecialChar ~
val
\family default
\series default
add a delegation slot, and initialize it, respectively.
It is recommended to use the latter since delegation to
\family typewriter
Nil
\family default
is unsafe.
\layout Standard
Each of the these has a variant which does not create a mutator method for
its slot:
\family typewriter
addImmutableSlot:valued:
\family default
and
\family typewriter
addImmutableDelegate:valued:
\family default
.
\layout Subsection
Expressions
\layout Standard
Expressions in Slate mostly consist of message-sends to argument objects.
The left-most argument is not considered an implicit receiver as it is
with most message-passing languages, however.
\layout Standard
An important issue is that every identifier 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 identifiers
in order for them to be considered separate.
For example,
\family typewriter
ab+4
\family default
will be treated as one identifier, but
\family typewriter
ab\SpecialChar ~
+\SpecialChar ~
4
\family default
is a message-send expression.
\layout Standard
There are three basic types of messages, with different syntaxes and associativi
ties: unary, binary, and keyword messages.
\emph on
Precedence
\emph default
is determine entirely by the syntactic form of the expreesion, 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:
\layout Enumerate
Literal syntax: arrays, blocks, block headers, statement sequences.
\layout Enumerate
Unary message-sends.
\layout Enumerate
Binary message-sends.
\layout Enumerate
Keyword message-sends.
\layout Standard
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 symbol 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.
\layout Subsubsection
Unary Message-sends
\layout Standard
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.
\layout Standard
Some examples of unary message-sends to explicit arguments include:
\layout LyX-Code
Slate> 42 print.
\newline
\emph on
42
\newline
\emph default
Slate> 'Slate' clone.
\newline
\emph on
'Slate'
\layout Standard
Unary sends associate from left to right.
So the following prints the factorial of 5:
\layout LyX-Code
Slate> 5 factorial print.
\newline
\emph on
120
\layout Standard
Which works the same as:
\layout LyX-Code
Slate> (5 factorial) print.
\newline
\emph on
120
\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.
\layout Subsubsection
Binary Message-sends
\layout Standard
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.
\layout Standard
These examples illustrate the precedence and syntax:
\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
\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:
\layout LyX-Code
Slate> 7 factorial + 3 negated.
\newline
\emph on
5037
\newline
\emph default
Slate> (7 factorial) + (3 negated).
\newline
\emph on
5037
\layout Standard
Binary selectors can consist of one or more of the following characters:
\layout LyX-Code
# $ % ^ & * - + = ~ /
\backslash
? < > , ;
\layout Standard
However, these characters are reserved:
\layout LyX-Code
@ [ ] ( ) { } .
: ! | `
\layout Subsubsection
Keyword Message-sends
\layout Standard
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.
The
\noun on
selector
\noun default
of the message is the joining-together of all the keywords into one symbol,
which is the
\emph on
name
\emph default
of the message.
For example,
\layout LyX-Code
Slate> 5 min: 4 max: 7.
\newline
\emph on
7
\layout Standard
is a keyword message-send named
\family typewriter
min:max:
\family default
which has 3 arguments: 5, 4, and 7.
However,
\layout LyX-Code
Slate> 5 min: (4 max: 7).
\newline
\emph on
5
\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:
\layout LyX-Code
Slate> (5 min: 4) max: 7.
\newline
\emph on
7
\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.
\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:
\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
\layout Subsubsection
Expression Sequences
\layout Standard
Expressions occur between stop-marks, which are periods.
At the top-level, expressions aren't evaluated until a full stop is entered.
The stop mark also means that expression results aren't directly carried
forward as an argument to the following expression; side-effects must be
used to keep 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.
\layout Standard
Slate provides for a bare expression sequence syntax that can be embedded
within any grouping parentheses, as follows:
\layout LyX-Code
Slate> 3 + 4.
\newline
\emph on
7
\layout LyX-Code
Slate> (7 factorial.
5
\newline
negated) min: 6.
\newline
\emph on
-5
\layout Standard
The parentheses are used just as normal grouping, and notably, the
\family typewriter
5 negated
\family default
expression wraps over a line, but still evaluates that way.
(We do not consider this expression good style, but it illustrates the
nature of the language.)
\layout Subsubsection
Implicit-context Sends
\layout Standard
Within methods, blocks, and even at the top-level, some expressions may
take the surrounding context as the first argument.
There is a precedence 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, and then at lesser precedences will be the next outer contexts
in sequence, up to the top-level and what it inherits from.
\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.
\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,
\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
].
\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
^\SpecialChar ~
(m\SpecialChar ~
raisedTo:\SpecialChar ~
3)
\family default
message 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.
\layout Standard
In some cases, it may be necessary to manipulate the context in particular
ways.
In that case, it can be directly addressed with a loopback slot named
\family typewriter
thisContext
\family default
, which refers to the current activation.
The essence of this concept is that within a block,
\family typewriter
x:\SpecialChar ~
4.
\family default
is equivalent to
\family typewriter
\SpecialChar ~
thisContext\SpecialChar ~
x:\SpecialChar ~
4.
\family default
\begin_inset Foot
collapsed true
\layout Standard
The current named method as distinct from the context is available as
\family typewriter
currentMethod
\family default
, and its name is available as
\family typewriter
selector
\family default
.
However, these are dependent on the current implementation of Slate, and
so may not be available in the future.
\end_inset
\layout Subsection
Methods
\layout Standard
\noun on
\begin_inset LatexCommand \label{sub:Methods}
\end_inset
Methods
\noun default
in Slate are basically annotated block closures (documented in
\begin_inset LatexCommand \ref{sub:Block-Closures}
\end_inset
), coupled with annotations of the objects' roles that dispatch to them.
\layout Subsubsection
Method Definitions
\layout Standard
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
.
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 symbol, 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 for their argument positions; the actual
objects returned by the expressions are annotated with a role for their
positions.
\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).
\layout Standard
There is a further allowance that an input slotname 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.
\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:
\layout LyX-Code
_@True ifTrue: block ifFalse: _ [block value].
\newline
_@False ifTrue: _ ifFalse: block [block value].
\newline
\newline
bool@(Boolean traits) ifTrue: block
\newline
"Some sugaring for ifTrue:ifFalse:."
\newline
[
\newline
bool ifTrue: block ifFalse: []
\newline
].
\layout Standard
The first two represent good uses of dispatching on a particular individual
object (dispatching the ignored symbol
\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.
The latter method is defined in terms of the first two, since
\family typewriter
True
\family default
and
\family typewriter
False
\family default
both delegate to
\family typewriter
Boolean\SpecialChar ~
traits
\family default
.
\layout Subsubsection
Expression-based Definitions
\layout Standard
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 interpreter to compile a method using
a certain symbolic name and a sequence of objects that are used for dispatching
targets.
For example:
\layout LyX-Code
[| :x :y | 5] asMethod: #+ on: {2.
2}.
\layout Standard
and
\layout LyX-Code
_@2 + _@2 [5].
\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
\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:
\layout LyX-Code
c@(Set traits) keyAt: index
\newline
[
\newline
c array at: index
\newline
].
\layout Standard
is semantically equivalent to:
\layout LyX-Code
c@(Set traits) keyAt: index@NoRole
\newline
[
\newline
c array at: index
\newline
].
\layout Standard
and furthermore to:
\layout LyX-Code
[| :c :index | c array at: index] asMethod: #keyAt:
\newline
on: {Set traits.
NoRole}.
\layout Subsubsection
Lookup Semantics
\layout Standard
Message dispatch in Slate is acheived 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.
During the dispatch process, more than one method is often 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.
\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 uses the most specific supertype
to determine specificity (or rather, the most specific parameter type of
which the argument is a subtype), specificity is instead interpreted as
\noun on
distance
\noun default
in the directed graph of delegations, starting from the argument as the
root.
\layout Standard
The
\noun on
distance
\noun default
notion has the following properties:
\layout Itemize
It is determined by a depth-first traversal over the delegate slots, considering
most-recently-added delegates before previously-added ones.
\layout Itemize
Delegations that lead to cycles are not traversed.
\layout Itemize
Repeated finds of a same method do not alter the distance value for it;
the first one found is retained.
\layout Itemize
The closer the
\noun on
distance
\noun default
of the role to the argument, the more specific it is.
\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), where
\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.
\layout Subsubsection
Resending messages or Dispatch-overriding
\begin_inset OptArg
collapsed true
\layout Standard
Resends
\end_inset
\layout Standard
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 simplest type of resend is
\family typewriter
resend
\family default
, which finds the next most-applicable method and invokes it with the exact
same set of arguments.
The result of
\family typewriter
resend
\family default
is the returned result of that method.
\layout Description
\family typewriter
methodName\SpecialChar ~
findOn:\SpecialChar ~
argumentArray
\family default
locates the method for the given symbol name and group of argument objects.
\layout Description
\family typewriter
methodName\SpecialChar ~
findOn:\SpecialChar ~
argumentArray\SpecialChar ~
after:\SpecialChar ~
aMethod
\family default
locates the method following the given one with the same type of arguments
as above.
\layout Description
\family typewriter
methodName\SpecialChar ~
sendTo:\SpecialChar ~
argumentArray
\family default
is an explicit application of a method, useful when the symbol name of
the method needs to be provided at run-time.
\layout Description
\family typewriter
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.
\layout Description
\family typewriter
methodName\SpecialChar ~
sendTo:\SpecialChar ~
argumentArray\SpecialChar ~
through:\SpecialChar ~
dispatchArray
\family default
is an extra option to specify a different signature for the method than
that of the actual argument objects.
\layout Subsubsection
Type Annotations
\layout Standard
Input and local slots' types can be specified statically for performance
or documentation reasons, if desired.
The special character
\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 only occur within a block closure's header.
The type system and inference system in Slate is part of the standard library,
and so is explained later.
\layout Subsubsection
Macro-level Methods
\layout Paragraph
The ` special character
\layout Standard
Preceding any selector with a back-tick (
\family typewriter
`
\family default
) will cause it to be applied to the parsed pre-evaluated form of its arguments.
This provides access to syntax-level methods at run-time and compile-time.
\layout Standard
Slate's parser produces syntax trees which are trees of objects with various
attributes, so there is some difference from the Lisp family of languages
in that simple lists are not the limit of the expression's parsed format.
\layout Paragraph
Quoting and Unquoting
\layout Standard
A few of the macro-methods we have found appropriate already are
\family typewriter
`quote
\family default
and
\family typewriter
`unquote
\family default
, which pass as their run-time result the syntax-level shifted versions
of their expressions.
\layout Standard
\family typewriter
`quote
\family default
causes the surrounding expression to use its quoted value as the input
for even normal methods\SpecialChar \@.
\layout Standard
\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.
Lisp macro system users will note that this effectively makes
\family typewriter
`quote
\family default
the same as quasi-quotation.
\layout Standard
\begin_inset Foot
collapsed true
\layout Standard
We may also provide these as
\family typewriter
`up
\family default
and
\family typewriter
`down
\family default
, respectively, if there is enough demand for it, and it is not too confusing.
\end_inset
\layout Paragraph
Labelled Quotation
\layout Standard
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.
\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{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.
\layout Standard
The operators are
\family typewriter
expr1\SpecialChar ~
`quote:\SpecialChar ~
aLiteral
\family default
and
\family typewriter
expr2\SpecialChar \-
\SpecialChar ~
`unquote:\SpecialChar \-
\SpecialChar ~
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 \@.
\layout Paragraph
Evaluation at Compile-time
\layout Standard
\family typewriter
`evaluate
\family default
provides compile-time evaluation of arbitrary expressions.
\layout Paragraph
Expression Substitution
\emph on
(Not Yet Implemented)
\layout Standard
\family typewriter
`with:as:
\family default
is a protocol for transparent substitution of temporary or locally-provided
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.
\layout Paragraph
Defining new Macro-methods
\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:
\layout Enumerate
The generic syntax node type is
\family typewriter
Compiler\SpecialChar ~
SyntaxNode\SpecialChar ~
traits
\family default
, and this is usually all that is necessary for basic macro-methods.
\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\SpecialChar ~
`quote\SpecialChar ~
traits
\family default
is suitable for dispatching on Integers, but not Numbers in general, or
\family typewriter
(3\SpecialChar ~
+\SpecialChar ~
4)\SpecialChar ~
`quote\SpecialChar ~
traits
\family default
will help dispatch on binary message-sends, but not all message-sends.
Luckily,
\family typewriter
[]\SpecialChar ~
`quote\SpecialChar ~
traits
\family default
works for blocks as well as methods.
\layout Subsection
Literal Syntax
\begin_inset OptArg
collapsed true
\layout Standard
Literals
\end_inset
\layout Subsubsection
Characters
\layout Standard
Slate's default support for character literals uses the
\family typewriter
$
\family default
symbol as a prefix.
The following printable and non-printable characters require backslash
escapes as follows:
\layout Standard
\added_space_top smallskip \added_space_bottom smallskip \align center
\begin_inset Tabular
\begin_inset Text
\layout Standard
Character name
\end_inset
|
\begin_inset Text
\layout Standard
Literal
\end_inset
|
\begin_inset Text
\layout Standard
Escape
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
e
\end_inset
|
\begin_inset Text
\layout Standard
Newline
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
n
\end_inset
|
\begin_inset Text
\layout Standard
Carriage return
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
r
\end_inset
|
\begin_inset Text
\layout Standard
Tab
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
t
\end_inset
|
\begin_inset Text
\layout Standard
Backspace
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
b
\end_inset
|
\begin_inset Text
\layout Standard
Null
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
0
\end_inset
|
\begin_inset Text
\layout Standard
Space
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
s
\end_inset
|
\begin_inset Text
\layout Standard
Backslash
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
$
\backslash
\backslash
\end_inset
|
\end_inset
\layout Standard
All other symbols can be immediately be preceded by
\family typewriter
$
\family default
in order to construct the Character object for them, for example,
\layout Standard
\family typewriter
$a
\family default
,
\family typewriter
$3
\family default
,
\family typewriter
$>
\family default
, and
\family typewriter
$$
\layout Standard
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.
\layout Subsubsection
Strings
\layout Standard
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.
\layout Standard
The following are all illustrative examples of Strings in Slate:
\layout LyX-Code
'a string comprises any sequence of characters, surrounded by single quotes'
\newline
'strings can include the "comment delimiting" character'
\newline
'and strings can include embedded single quote characters by escaping
\backslash
' them'
\newline
'strings can contain embedded
\newline
newline characters'
\newline
'and escaped
\backslash
ncharacters'
\newline
'' "and don't forget the empty string"
\layout Subsubsection
Symbols
\layout Standard
Symbols start with the pound sign character (
\family typewriter
#
\family default
) and consist of all following characters up to the next non-escaped whitespace,
unless the pound sign is followed exactly by a string literal, in which
case the string's contents become the identifier for the symbol.
So, for example,
\family typewriter
#@
\family default
,
\family typewriter
#key:word:expression:
\family default
,
\family typewriter
#something_with_underscores
\family default
, and
\family typewriter
#'A\SpecialChar ~
full\SpecialChar ~
string\SpecialChar ~
with\SpecialChar ~
a
\backslash
nnewline\SpecialChar ~
in\SpecialChar ~
it.'
\family default
are all valid symbols and symbol literals.
\layout Standard
A property of Symbols 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 symbol 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 Symbol's value is case-sensitive,
so #a and #A are distinct.
\layout Standard
Internally, Slate currently keeps one global table for symbols, and uses
individual context objects to hold local bindings.
\begin_inset Foot
collapsed true
\layout Standard
Future, bootstrapped releases may provide for partitioning of the global
table.
\end_inset
\layout Subsubsection
Arrays
\layout Standard
Arrays can be literally and recursively specified by curly-brace notation
using stops as separators.
Array indices in Slate are 0-based.
So:
\layout LyX-Code
{4.
5.
{foo.
bar}}.
\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.
\layout Standard
Immediate array syntax 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.
\layout Section
The Slate World
\layout Subsection
Overall Organization
\layout Subsubsection
The lobby
\layout Standard
The lobby is the root namespace object for the Slate object system.
All 'global' objects are really only globally accessible because the lobby
is delegated to by lexical contexts, directly or indirectly.
The lobby in turn may delegate to other namespaces which contain different
categorized objects of interest to the applications programmer, and this
can be altered at run-time.
\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 lobby (nested closures refer first to their surrounding closure).
The lobby 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.)
\layout Standard
The lobby is essentially a threading context, and in the future bootstrap
will be instantiable in that sense.
\layout Subsubsection
Naming and Paths
\layout Standard
The lobby provides access to the major
\family typewriter
Namespaces
\family default
, which are objects suitable for organizing things (for now, they are essentiall
y just
\family typewriter
Oddball
\family default
objects).
The most important one is
\family typewriter
prototypes
\family default
, 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.
\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.
\layout Standard
The
\family typewriter
prototypes
\family default
namespace further contains inherited namespaces for collections, and can
be otherwise enhanced to divide up the system into manageable pieces.
\layout Subsection
Core Behaviors
\layout Standard
Slate defines several subtle variations on the core behavior of objects:
\layout Description
\noun on
Root
\noun default
The "root" object, upon which all the very basic methods of slot manipulation
are defined.
\layout Description
\noun on
Oddball
\noun 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
\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
.
\layout Description
\noun on
Nil
\noun default
\family typewriter
Nil
\family default
is an
\family typewriter
Oddball
\family default
representing "no-object".
\layout Description
\noun on
Derivable
\noun default
\family typewriter
Derivable
\family default
objects respond to
\family typewriter
derive
\family default
and
\family typewriter
deriveWith:
\family default
, which means they can be readily extended.
\layout Description
\noun on
Cloneable
\noun default
\family typewriter
Cloneable
\family default
objects are derivables that can be cloned.
\layout Description
\noun on
Method
\noun default
A
\family typewriter
Cloneable
\family default
object with attributes for supporting execution of blocks and holding compiled
code and its attributes.
\layout Subsubsection
Default Object Features
\layout Description
Identity
\family typewriter
==
\family default
returns whether the two arguments are identical, i.e.
the same object, and
\family typewriter
~==
\family default
is its negation.
Value-equality (
\family typewriter
=
\family default
and its negation
\family typewriter
~=
\family default
) defaults to this.
\layout Description
Printing
\family typewriter
print
\family default
returns a printed representation of the object.
\family typewriter
printOn:
\family default
places the result of printing onto a designated Stream.
This should be overridden.
\layout Description
Delegation-testing
\family typewriter
is:
\family default
returns whether the first object has the second as one of its delegated
objects, directly or indirectly.
\layout Description
Hashing A quick way to sort by object value that makes searching collections
faster is the
\family typewriter
hash
\family default
method, which by default hashes on the object's identity (available separately
as
\family typewriter
identityHash
\family default
), essentially by its address in memory.
What's more important about hashing is that this is how value-equality
is established for collections; if an object type overrides =, it must
also override the
\family typewriter
hash
\family default
method's algorithm so that
\family typewriter
a\SpecialChar ~
=\SpecialChar ~
b
\family default
\begin_inset Formula $\Rightarrow$
\end_inset
\family typewriter
a\SpecialChar ~
hash\SpecialChar ~
=\SpecialChar ~
b\SpecialChar ~
hash
\family default
.
\layout Description
Conversion/coercion The
\family typewriter
as:
\family default
method has a default implementation on root objects.
Essentially the purpose of the
\family typewriter
as:
\family default
protocol is to provide default conversion methods between types of objects
in Slate.
Some primitive types, such as
\family typewriter
Number
\family default
, override this.
For now, if no converter is found or if the objects are not of the same
type, the failure answer is
\family typewriter
Nil
\family default
.
Precisely, the behavior of
\family typewriter
a\SpecialChar ~
as:\SpecialChar ~
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.
\layout Description
Slot-enumeration For each object, the Symbols naming its slot and delegate
slots can be accessed and iterated over, using the accessors
\family typewriter
slotNames
\family default
and
\family typewriter
delegateNames
\family default
, which work with the symbol names of the slots, or the iterators
\family typewriter
slotsDo:
\family default
and
\family typewriter
delegatesDo:
\family default
, which iterate over the stored values themselves.
\layout Subsubsection
Oddballs
\layout Standard
There are various Oddballs in the system, and they are non-cloneable in
general.
However, Oddball itself may be cloned, for extension purposes.
\layout Subsection
Traits
\layout Standard
Slate objects, from the root objects down, all respond to the message
\family typewriter
traits
\family default
, 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 Traits 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.
\layout Standard
Traits objects also have their own traits object, which is
\family typewriter
Traits\SpecialChar ~
traits
\family default
.
This has the important methods defined on it for deriving new prototypes
with new traits objects:
\layout Description
\family typewriter
myObject\SpecialChar ~
derive
\family default
will return a new clone of the object with a traits object which is cloned
from the original's traits object, and a delegation slot set between the
traits objects.
\layout Description
\family typewriter
myObject\SpecialChar ~
deriveWith:\SpecialChar ~
mixinsArray
\family default
will perform the same operation, adding more delegation links to the traits
of the array's objects, in the given order, which achieves a structured,
shared behavior of 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
\family typewriter
mixinsArray
\family default
do not have to be
\family typewriter
Derivable
\family default
.
\layout Standard
As with any method in Slate, these may be overridden to provide additional
automation and safety in line with their semantics.
\layout Subsection
Closures, Booleans, and Control Structures
\begin_inset OptArg
collapsed true
\layout Standard
Control-flow
\end_inset
\layout Subsubsection
Boolean Logic
\layout Standard
Slate's interpreter primitively provides the objects
\family typewriter
True
\family default
and
\family typewriter
False
\family default
, which are clones of
\family typewriter
Boolean
\family default
, and delegate to
\family typewriter
Boolean\SpecialChar ~
traits
\family default
.
Logical methods are defined on these in a very minimalistic way.
\layout Standard
Here are the logical methods and their meanings:
\layout Standard
\added_space_top smallskip \added_space_bottom smallskip \align center
\begin_inset Tabular
\begin_inset Text
\layout Standard
Description
\end_inset
|
\begin_inset Text
\layout Standard
Selector
\end_inset
|
\begin_inset Text
\layout Standard
AND/Conjunction
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
/
\backslash
\end_inset
|
\begin_inset Text
\layout Standard
OR/Disjunction
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
\backslash
/
\end_inset
|
\begin_inset Text
\layout Standard
NOT/Negation
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
not
\end_inset
|
\begin_inset Text
\layout Standard
EQV/Equivalence
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
equiv:
\end_inset
|
\begin_inset Text
\layout Standard
XOR/Exclusive-OR
\end_inset
|
\begin_inset Text
\layout Standard
\family typewriter
xor:
\end_inset
|
\end_inset
\layout Subsubsection
Basic Conditional Evaluation
\layout Standard
Blocks that evaluate logical expressions can be used lazily in other logical
expressions.
For example,
\layout LyX-Code
(x < 3) and: [y > 7].
\layout Standard
only evaluates the right-hand block argument if the first argument turns
out to be True.
\layout LyX-Code
(x < 3) or: [y > 7].
\layout Standard
only evaluates the right-hand block argument if the first argument turns
out to be False.
\layout Standard
In general, the basic of booleans to switch between code alternatives is
to use
\family typewriter
ifTrue:
\family default
,
\family typewriter
ifFalse:
\family default
, and
\family typewriter
ifTrue:ifFalse:
\family default
for the various combinations of binary branches.
For example,
\layout LyX-Code
x isNegative ifTrue: [x: x negated].
\layout Standard
ensures that
\family typewriter
x
\family default
is positive by optionally executing code to make it positive 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.
\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
:
\layout Description
\family typewriter
expr\SpecialChar ~
ifNil:\SpecialChar ~
block
\family default
and
\family typewriter
\series bold
expr\SpecialChar ~
ifNotNil:\SpecialChar ~
block
\family default
\series default
execute their blocks based on whether the expression evaluates to Nil,
and returns the result.
\layout Description
\family typewriter
expr\SpecialChar ~
ifNil:\SpecialChar ~
nilBlock\SpecialChar ~
ifNotNil:\SpecialChar ~
otherBlock
\family default
provides both options in one expression.
\layout Description
\family typewriter
expr\SpecialChar ~
ifNotNilDo:\SpecialChar ~
block
\family default
applies the block to the expression's result if it turns out to be non-Nil,
so the block given must accept one argument.
\layout Subsubsection
Looping
\layout Standard
Slate includes various idioms for constructing basic loops.
\layout Description
\family typewriter
n\SpecialChar ~
timesRepeat:\SpecialChar ~
block
\family default
executes the block
\family typewriter
n
\family default
times.
\layout Description
\family typewriter
condition\SpecialChar ~
whileTrue:\SpecialChar ~
block
\family default
and
\family typewriter
\series bold
condition\SpecialChar ~
whileFalse:\SpecialChar ~
block
\family default
\series default
execute their blocks repeatedly, checking the condition before each iteration.
\layout Description
\family typewriter
a\SpecialChar ~
upTo:\SpecialChar ~
b\SpecialChar ~
do:\SpecialChar ~
block
\family default
and
\family typewriter
\series bold
b\SpecialChar ~
downTo:\SpecialChar ~
a\SpecialChar ~
do:\SpecialChar ~
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.
\layout Description
\family typewriter
a\SpecialChar ~
below:\SpecialChar ~
b\SpecialChar ~
do:\SpecialChar ~
block
\family default
and
\family typewriter
\series bold
b\SpecialChar ~
above:\SpecialChar ~
a\SpecialChar ~
do:\SpecialChar ~
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\SpecialChar ~
-\SpecialChar ~
1
\family default
calls.
\layout Standard
Slate's looping control structures can easily be extended without concern
due to the fact that the interpreter unrolls 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.
\layout Subsection
Magnitudes and Numbers
\layout Subsubsection
Basic Types
\layout Description
Magnitude 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
.
\layout Description
Number the abstract type of dimensionless quantities.
\layout Description
Integer integral quantities, generally.
\layout Description
SmallInteger machine-word-limited literals.
Their normal protocol will not produce errors inconsistent with mathematic
behavior of
\family typewriter
Integer
\family default
s, however.
\layout Description
BigInteger larger
\family typewriter
Integer
\family default
s, implemented as
\family typewriter
WordArray
\family default
s.
\layout Description
Fraction An exact representation of a quotient, or rational number.
\layout Description
Float A low-level floating-point numeric representation, being inexact.
\layout Description
Complex A complex number, similar to a pair of real numbers.
\layout Subsubsection
Basic Operations
\layout Standard
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.
\layout Standard
The following are the rest of the primitive operations, given with an indication
of their "signatures":
\layout Description
\family typewriter
Float\SpecialChar ~
raisedTo:\SpecialChar ~
Float
\family default
is simple floating-point exponentiation.
\layout Description
\family typewriter
Integer\SpecialChar ~
as:\SpecialChar ~
Float
\family default
extends an integer into a float.
\layout Description
\family typewriter
Float\SpecialChar ~
as:\SpecialChar ~
Integer
\family default
truncates a float.
\layout Description
\family typewriter
Integer\SpecialChar ~
bitOr:\SpecialChar ~
Integer
\family default
performs bitwise logical
\shape smallcaps
OR
\shape default
.
\layout Description
\family typewriter
Integer\SpecialChar ~
bitXor:\SpecialChar ~
Integer
\family default
performs bitwise logical
\shape smallcaps
XOR
\shape default
.
\layout Description
\family typewriter
Integer\SpecialChar ~
bitAnd:\SpecialChar ~
Integer
\family default
performs bitwise logical
\shape smallcaps
AND
\shape default
.
\layout Description
\family typewriter
Integer\SpecialChar ~
bitShift:\SpecialChar ~
Integer
\family default
performs bitwise logical right-shift (left-shift if negative).
\layout Description
\family typewriter
Integer\SpecialChar ~
bitNot
\family default
performs bitwise logical
\shape smallcaps
NOT
\shape default
.
\layout Description
\family typewriter
Integer\SpecialChar ~
>>\SpecialChar ~
Integer
\family default
performs logical right-shift.
\layout Description
\family typewriter
Integer\SpecialChar ~
<<\SpecialChar ~
Integer
\family default
performs logical left-shift.
\layout Description
\family typewriter
Integer\SpecialChar ~
quo:\SpecialChar ~
Integer
\family default
returns a quotient (integer division).
\layout Standard
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.
\layout Subsubsection
Non-core Operations
\layout Description
\family typewriter
zero
\family default
The zero element for the type of number.
\layout Description
\family typewriter
isZero
\family default
Whether the number is the zero element for its type.
\layout Description
\family typewriter
isPositive
\family default
/
\family typewriter
isNegative
\family default
Whether its positive or negative.
\layout Description
\family typewriter
abs
\family default
The absolute value of the number.
\layout Description
\family typewriter
sign
\family default
The sign of the number.
\layout Description
\family typewriter
negated
\family default
Returns
\emph on
-x
\emph default
for
\emph on
x
\emph default
.
\layout Description
\family typewriter
gcd:
\family default
Greatest common divisor.
\layout Description
\family typewriter
lcm:
\family default
Least common multiple.
\layout Description
\family typewriter
factorial
\family default
Factorial.
\layout Description
\family typewriter
mod:
\family default
/
\family typewriter
rem:
\family default
/
\family typewriter
quo:
\family default
Modulo division, remainder, and quotient.
\layout Description
\family typewriter
reciprocal
\family default
Constructs a new fraction reciprocal.
\layout Description
\family typewriter
min:
\family default
The lesser of the arguments.
The least in cases of
\family typewriter
min:min:
\family default
.
\layout Description
\family typewriter
max:
\family default
The greater of the arguments.
The greatest in cases of
\family typewriter
max:max:
\family default
.
\layout Description
\family typewriter
a\SpecialChar ~
between:\SpecialChar ~
b\SpecialChar ~
and:\SpecialChar ~
c
\family default
Whether
\family typewriter
a
\family default
is between
\family typewriter
b
\family default
and
\family typewriter
c
\family default
.
\layout Description
\family typewriter
truncated
\family default
/
\family typewriter
fractionPart
\family default
Returns the greatest integer less than the number, and the corresponding
difference as a fraction (or a float for
\family typewriter
Float
\family default
).
\layout Description
\family typewriter
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.
\layout Subsubsection
Limit Numerics
\layout Description
PositiveInfinity is greater than any other
\family typewriter
Magnitude
\family default
.
\layout Description
NegativeInfinity is lesser than any other
\family typewriter
Magnitude
\family default
.
\layout Description
LargeUnbounded 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.
\layout Description
PositiveEpsilon is as small as you like, but positive and greater than zero.
\layout Description
NegativeEpsilon is as small as you like, but negative and lesser than zero.
\layout Subsubsection
Dimensioned Units
\layout Standard
There is an entire system for handling dimensioned units and their various
combinations and mathematical operations.
See the '
\family typewriter
src/dimensioned.slate
\family default
' file for an overview.
\layout Subsection
Collections
\layout Standard
Slate's collection hierarchy makes use of multiple delegation 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.
\layout Standard
Figure
\begin_inset LatexCommand \ref{cap:Collections-delegation}
\end_inset
shows the overview of the collection types, and how their delegation is
patterned.
\layout Standard
\begin_inset Float figure
placement htbp
wide true
collapsed false
\layout Standard
\added_space_top defskip \added_space_bottom defskip
\begin_inset Graphics
filename /home/water/slate/doc/collection-web.fig
\end_inset
\layout Caption
\begin_inset LatexCommand \label{cap:Collections-delegation}
\end_inset
Core Collections Inheritance
\end_inset
\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:
\layout Paragraph
Testing Methods
\layout Description
\family typewriter
isEmpty
\family default
answers whether or not the collection has any elements in it.
\layout Description
\family typewriter
includes:
\family default
answers whether the collection contains the object.
\layout Paragraph
Properties
\layout Description
\family typewriter
size
\family default
returns 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.
\layout Description
\family typewriter
capacity
\family default
returns the size that the collection's implementation is currently ready
for.
\layout Paragraph
Making new collections
\layout Description
\family typewriter
newSize:
\family default
returns a new collection of the same type that is sized to the argument.
\layout Description
\family typewriter
newEmpty
\family default
returns a new collection of the same type that is sized to some small default
value.
\layout Description
\family typewriter
as:
\family default
\emph on
alias
\emph default
\family typewriter
\series bold
newWithAll:
\family default
\series default
has extensive support in the collection types to produce copies of the
first collection with the type of the second.
\layout Paragraph
Iterating
\layout Description
\family typewriter
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 returns the original collection.
\layout Description
\family typewriter
collect:
\family default
also takes a block, but returns a collection with all the results of those
block-applications put into a new collection of the appropriate type.
\layout Description
\family typewriter
select:
\family default
takes a block that returns a
\family typewriter
Boolean
\family default
and returns a new collection of the elements that the block filters (returns
\family typewriter
True
\family default
).
\layout Subsubsection
Extensible Collections
\layout Standard
Collections delegating to
\family typewriter
ExtensibleCollection
\family default
respond to
\family typewriter
add:
\family default
,
\family typewriter
remove:
\family default
, and other protocol messages based upon them, such as the batch operations
\family typewriter
addAll:
\family default
and
\family typewriter
removeAll:
\family default
.
\layout Subsubsection
Sequences
\layout Standard
\family typewriter
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.
\layout Standard
To access and modify sequences, the basic methods
\family typewriter
seq\SpecialChar ~
at:\SpecialChar ~
index
\family default
and
\newline
\family typewriter
seq\SpecialChar ~
at:\SpecialChar ~
index\SpecialChar ~
put:\SpecialChar ~
object
\family default
are provided.
\layout Paragraph
Arrays
\layout Standard
\family typewriter
Arrays
\family default
are fixed-length sequences 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
.
\layout Paragraph
Vectors
\layout Standard
\family typewriter
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
.
\layout Paragraph
Subsequences / Slices
\layout Standard
\family typewriter
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.
\layout Paragraph
Cords
\layout Standard
\family typewriter
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\SpecialChar ~
as:\SpecialChar ~
Sequence
\family default
will
\begin_inset Quotes eld
\end_inset
flatten
\begin_inset Quotes erd
\end_inset
the Cord into a Sequence.
\layout Paragraph
Extensible and Sorted Sequences
\layout Standard
An
\family typewriter
ExtensibleSequence
\family default
is an extensible
\family typewriter
Sequence
\family default
with some special methods to treat both ends as queues.
Adding to an
\family typewriter
ExtensibleSequence
\family default
will add at the last index, at the
\begin_inset Quotes eld
\end_inset
end
\begin_inset Quotes erd
\end_inset
.
\layout Standard
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.
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.
\layout Paragraph
Stacks
\layout Standard
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.
\layout Paragraph
Ranges
\layout Standard
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.
\layout Paragraph
Buffers
\layout Standard
A
\family typewriter
Buffer
\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 BufferReadStream
and BufferWriteStream (
\begin_inset LatexCommand \vref{des:BufferReadStream}
\end_inset
)).
One consequence of this is that a Buffer has a limited upper bound in size
which the client must handle, although the capacity can be grown explicitly.
\layout Subsubsection
Strings and Characters
\layout Standard
\family typewriter
Strings
\family default
in Slate are
\family typewriter
Array
\family default
s of
\family typewriter
Character
\family default
s.
Strings and characters have a special literal syntax, and methods specific
to dealing with text.
\layout Subsubsection
Collections without Duplicates
\layout Standard
\family typewriter
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.
\layout Standard
The default implementation of this protocol is
\family typewriter
Set
\family default
, which stores its elements in a (somewhat sparse) hashed array.
\layout Subsubsection
Mappings and Dictionaries
\layout Standard
\family typewriter
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 symbols as keys.
\layout Standard
Mapping 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
.
\layout Subsubsection
Linked Collections
\layout Standard
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.
\layout Paragraph
Linked Lists
\layout Standard
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.
\layout Paragraph
Trees
\layout Standard
Slate includes libraries for binary trees, red-black trees, trees with ordered
elements, and tries.
\layout Paragraph
Graphs
\layout Standard
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.
\layout Subsubsection
Vectors and Matrices
\layout Standard
Slate includes the beginnings of a mathematical vector and matrix library.
See the '
\family typewriter
src/matrix.slate
\family default
' file for an overview.
\layout Subsection
Streams and External Iterators
\layout Standard
Streams are objects that act as a sequential channel of elements from (or
even
\emph on
to
\emph default
) some source.
\layout Subsubsection
Basic Protocol
\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:
\layout Description
\family typewriter
next
\family default
reads and returns the next element in the stream.
This causes the stream reader to advance one element.
\layout Description
\family typewriter
peek
\family default
reads and returns the next element in the stream.
This does
\emph on
not
\emph default
advance the stream reader.
\layout Description
\family typewriter
next:
\family default
draws the next
\family typewriter
n
\family default
number of elements from the stream and returns them in a
\family typewriter
Sequence
\family default
of the appropriate type.
\layout Description
\family typewriter
next:putInto:
\family default
reads the next N bytes into the given
\family typewriter
Sequence
\family default
starting from index 0.
\layout Description
\family typewriter
next:putInto:startingAt:
\family default
reads the N elements into the given
\family typewriter
Sequence
\family default
starting from the given index.
\layout Description
\family typewriter
nextPutInto:
\family default
reads into the given
\family typewriter
Sequence
\family default
the number of elements which will fit into it.
\layout Description
\family typewriter
nextPut:
\family default
writes the object to the stream.
\layout Description
\family typewriter
nextPutAll:
\family default
\emph on
alias
\emph default
\family typewriter
\series bold
stream\SpecialChar ~
;\SpecialChar ~
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.
\layout Description
\family typewriter
do:
\family default
applies a Block to each element of the stream.
\layout Description
\family typewriter
flush
\family default
synchronizes the total state of the stream with any pending requests made
by the user.
\layout Description
\family typewriter
atEnd
\family default
answers whether or not the stream has reached some limit.
\layout Description
\family typewriter
upToEnd
\family default
collects all the elements of the stream up to its limit into an
\family typewriter
ExtensibleSequence
\family default
.
\layout Subsubsection
Basic Stream Variants
\layout Standard
Figure
\begin_inset LatexCommand \ref{cap:Stream-Inheritance}
\end_inset
shows the major stream types and their relationships.
\layout Standard
\begin_inset Float figure
wide false
collapsed false
\layout Standard
\align center
\begin_inset Graphics
filename /home/water/slate/doc/stream-web.fig
\end_inset
\layout Caption
\begin_inset LatexCommand \label{cap:Stream-Inheritance}
\end_inset
Stream Inheritance
\end_inset
\layout Description
Stream provides the basic protocol for instantiating streams.
\layout Description
Stream provides the basic protocol for instantiating streams.
\layout Description
PositionableStream extends
\family typewriter
Stream
\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
-.
\layout Description
ReadStream provides the basic protocol for input access to a source.
\layout Description
WriteStream provides the basic protocol for output access to a target.
\layout Description
ReadWriteStream provides the basic protocol for both read and write access,
and caches its input as necessary.
\layout Description
FileStream targets a file, for reading or writing.
\layout Description
DummyStream is a
\family typewriter
ReadStream
\family default
that just returns
\family typewriter
Nil
\family default
repeatedly.
\layout Description
EchoStream 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.
\layout Description
BlockStream is a
\family typewriter
ReadStream
\family default
that targets a no-input block and returns its output each time.
\layout Description
BufferReadStream
\begin_inset LatexCommand \label{des:BufferReadStream}
\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.
\layout Description
BufferWriteStream
\begin_inset LatexCommand \label{des:BufferWriteStream}
\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.
\layout Subsubsection
Basic Instantiation
\layout Standard
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:
\layout Description
\family typewriter
newOn:
\family default
creates a new
\family typewriter
Stream
\family default
of the same type as the first argument, targetting it to the second as
a source.
This should not be overridden.
Instead, the retargetting method
\family typewriter
on:
\family default
is overridden.
\layout Description
\family typewriter
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.
\layout Description
\family typewriter
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.
\layout Description
\family typewriter
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
.
\layout Description
\family typewriter
readBuffered
\family default
creates and returns a new
\family typewriter
ReadBufferStream
\family default
which wraps the argument
\family typewriter
Stream
\family default
.
\layout Description
\family typewriter
writeBuffered
\family default
creates and returns a new
\family typewriter
WriteBufferStream
\family default
which wraps the argument
\family typewriter
Stream
\family default
.
\layout Description
\family typewriter
echoTo:
\family default
\family typewriter
creates
\family default
and returns a new
\family typewriter
EchoStream
\family default
which wraps the first argument
\family typewriter
Stream
\family default
and echoes to the second.
\layout Subsubsection
Standard Input/Output
\layout Standard
The Slate interpreter provides two Streams 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.
\layout Subsubsection
Collection Iterator Streams
\layout Standard
Each collection type may define its 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.
So
\begin_inset Quotes eld
\end_inset
\family typewriter
Set\SpecialChar ~
ReadStream
\family default
\begin_inset Quotes erd
\end_inset
refers to the prototype suitable for iterating over
\family typewriter
Sets
\family default
.
\layout Standard
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:
\layout Description
\family typewriter
iterator
\family default
will return a
\family typewriter
ReadStream
\family default
or preferrably a
\family typewriter
ReadWriteStream
\family default
if one is available for the type.
\layout Description
\family typewriter
reader
\family default
and
\family typewriter
\series bold
writer
\family default
\series default
get only ReadStream and
\family typewriter
WriteStream
\family default
objects for the type, when available.
\layout Subsection
Files
\layout Standard
File access in Slate is currently rudimentary.
The interpreter provides an object type
\family typewriter
FileStream
\family default
which follows the corresponding protocol:
\layout Description
FileStream\SpecialChar ~
newNamed:\SpecialChar ~
filename returns a stream for a
\family typewriter
String
\family default
that names a path to a file, for read/write access.
\layout Description
FileStream\SpecialChar ~
newForInputNamed:\SpecialChar ~
filename returns a stream for reading an existing
file of the given name, or
\family typewriter
Nil
\family default
if it doesn't exist.
\layout Description
FileStream\SpecialChar ~
newForOutputNamed:\SpecialChar ~
filename returns a stream for writing (appending)
to a file with the given name.
\layout Description
FileStream\SpecialChar ~
newForNewNamed:\SpecialChar ~
filename returns a stream for writing (appending)
to a new file with the given name.
It will create a new file, but if the file exists,
\family typewriter
Nil
\family default
will be returned.
\layout Description
\family typewriter
open
\family default
opens the file.
\layout Description
\family typewriter
exists
\family default
answers whether there is a file with the stream's pathname.
\layout Description
\family typewriter
close
\family default
closes the file.
\layout Description
\family typewriter
next
\family default
reads the next byte from the file.
\layout Description
\family typewriter
next:
\family default
reads the next N bytes from the file.
\layout Description
\family typewriter
next:putInto:
\family default
reads the next N bytes into the given
\family typewriter
Sequence
\family default
starting from index 0.
\layout Description
\family typewriter
next:putInto:startingAt:
\family default
reads the N bytes into the given
\family typewriter
Sequence
\family default
starting from the given index.
\layout Description
\family typewriter
nextPutInto:
\family default
reads into the given
\family typewriter
Sequence
\family default
the number of bytes which will fit into it.
\layout Description
\family typewriter
position
\family default
returns the position within the file in byte units.
\layout Description
\family typewriter
position:
\family default
sets the position within the file to the given integer number of bytes.
\layout Description
\family typewriter
size
\family default
returns the file size in bytes.
\layout Description
\family typewriter
nextPut:\SpecialChar ~
char
\family default
writes one byte to the file.
\layout Description
\family typewriter
nextPut:\SpecialChar ~
seq
\family default
writes a sequence of bytes to the file.
\layout Description
\family typewriter
name
\family default
returns the file's pathname.
\layout Description
\family typewriter
fullName
\family default
will always return a complete pathname whereas the regular method may not.
\layout Description
\family typewriter
renameTo:
\family default
adjusts the file to have the given name.
\layout Description
\family typewriter
atEnd
\family default
answers whether the file's end has been reached.
\layout Description
\family typewriter
delete
\family default
deletes the file.
\layout Standard
Perhaps the most important utility is to load libraries based on path names.
\family typewriter
'filename'\SpecialChar ~
fileIn
\family default
will execute a file with the given path name as Slate source.
\layout Subsection
Types
\layout Standard
In coordination with the reserved syntax for type-annotation in block headers,
Slate's standard libraries include a collection of representations of primitive
\noun on
types
\noun default
as well as quantifications over those types.
\layout Standard
The library of types is laid out within the non-delegated namespace
\family typewriter
Types
\family default
in the lobby.
\layout Description
Any The type that any object satisfies: the universal type.
\layout Description
None The type that no object satisfies: the empty type.
\layout Description
Range 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.
\layout Description
Member The type associated with membership in a specific set of objects.
\layout Description
Singleton The type of a single object, as distinct from any other object.
\layout Description
Clone The type of an object and its
\noun on
clone family
\noun default
, the set of objects that are direct copies of it.
\layout Description
Array The Array type is parametrized by an element type and represents arrays
of all length of that type.
\layout Description
Block The Block type represents code closures of a given (optional) input
and output signature.
\layout Standard
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
and
\family typewriter
deriveWith:
\family default
which preserve type constraints on the derivations.
\layout Subsubsection*
Type Annotations
\layout Standard
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.
\layout Standard
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,
\layout LyX-Code
[| :foo!Integer bar | bar: (foo raisedTo: 3).
\newline
foo + bar] value: 4.3.
\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.
\layout Subsection
Modules
\layout Standard
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 primitive
\family typewriter
fileIn
\family default
method also invokes a hook to set the
\family typewriter
currentModule
\family default
in its context.
\layout Section
Style Guide
\layout Standard
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.
\layout Subsection
Environment organization
\layout Subsubsection
Namespaces
\layout Standard
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.
\layout Subsubsection
Exemplars or Value Objects
\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.
\layout Subsection
Naming Methods
\layout Standard
One of the primary benefits and peculiarities of Smalltalk'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.
Here are some general practices that Slate uses which have been common
in Smalltalk practice for years.
\layout Subsubsection
Attributes
\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.
\layout Subsubsection
Queries
\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\SpecialChar ~
isRed
\family default
answers whether one's car is red.
Slate offers an additional idiom over this particular style, in that
\family typewriter
myCar\SpecialChar ~
color\SpecialChar ~
is:\SpecialChar ~
Red
\family default
is also possible, since
\family typewriter
is:
\family default
looks at both the subject and the object of the query.
\layout Subsubsection
Creating
\layout Standard
While the method
\family typewriter
clone
\family default
is the core of building new objects in Slate, rather than instantiating
a class, there is still the need to provide an idiom for delivering optional
attributes 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 keyword methods, with each of the keywords describing
each option, whether literally naming an attribute, or simulating a grammatical
phrase using prepositions.
\layout Subsubsection
Performing Actions
\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.
\layout Subsubsection
Binary Operators
\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.
\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 acheive 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.
\layout Subsection
Instance-specific Dispatch
\layout Standard
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.
\layout Subsubsection
Motivations
\layout Standard
Two common patterns where the developer wants to specialize to a single
object emerge from using Slate.
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.
\layout Standard
Second, there are situations whether the user is demonstratively modifying
the behavior of some
\emph on
thing
\emph default
in order to acheive 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.
\layout Subsubsection
Limitations
\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 most literals of that nature, with the exception of
\family typewriter
Symbol
\family default
s.
\layout Subsection
Organization of Source
\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 what other methods are
defined upon it, are late-bound and will not hinder a method-dispatch expressio
n.
\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.
\layout Subsection
Code Templates Using Macros
\layout Bibliography
\bibitem {PMD}
\emph on
Multiple Dispatch with Prototypes
\emph default
.
Lee Salzman, 2002.
\layout Bibliography
\bibitem {SelfPR}
\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.
\layout Bibliography
\bibitem {OnLisp}
\emph on
On Lisp: Advance Techniques for Common Lisp
\emph default
.
Paul Graham.
Prentice-Hall, Inc., 1994.
\the_end