Trie code cleanups.
[cslatevm.git] / doc / progman.lyx
blobb262558614631637f69aefd83db201aacf4f8a9d
1 #LyX 1.5.3 created this file. For more info see http://www.lyx.org/
2 \lyxformat 276
3 \begin_document
4 \begin_header
5 \textclass article
6 \language english
7 \inputencoding auto
8 \font_roman bookman
9 \font_sans default
10 \font_typewriter default
11 \font_default_family default
12 \font_sc false
13 \font_osf false
14 \font_sf_scale 100
15 \font_tt_scale 100
16 \graphics default
17 \float_placement !htp
18 \paperfontsize default
19 \spacing single
20 \papersize default
21 \use_geometry true
22 \use_amsmath 1
23 \use_esint 0
24 \cite_engine basic
25 \use_bibtopic false
26 \paperorientation portrait
27 \leftmargin 1.5in
28 \rightmargin 1.5in
29 \secnumdepth 3
30 \tocdepth 3
31 \paragraph_separation skip
32 \defskip smallskip
33 \quotes_language english
34 \papercolumns 1
35 \papersides 1
36 \paperpagestyle default
37 \tracking_changes false
38 \output_changes false
39 \author "" 
40 \author "" 
41 \end_header
43 \begin_body
45 \begin_layout Title
46 The Slate Programmer's Reference Manual
47 \end_layout
49 \begin_layout Author
50 Brian T.
51  Rice, Lee Salzman, Timmy Douglas
52 \end_layout
54 \begin_layout Standard
55 \begin_inset LatexCommand tableofcontents
57 \end_inset
60 \end_layout
62 \begin_layout Standard
63 \begin_inset FloatList figure
65 \end_inset
68 \end_layout
70 \begin_layout Standard
72 \newpage
74 \end_layout
76 \begin_layout Section
77 Introduction
78 \end_layout
80 \begin_layout Standard
81 Slate is a member of the Smalltalk
82 \begin_inset LatexCommand index
83 name "Smalltalk"
85 \end_inset
87  family of languages which supports an object model in a similar prototype-based
88  style as Self
89 \begin_inset LatexCommand index
90 name "Self"
92 \end_inset
95 \begin_inset LatexCommand cite
96 key "SelfPR"
98 \end_inset
100 , extended and re-shaped to support multiple-dispatch methods.
101  However, unlike Self, Slate does not rely on a literal syntax that combines
102  objects and blocks, using syntax more akin to traditional Smalltalk.
103  Unlike a previous attempt at providing prototype-based languages with multiple
104  dispatch
105 \begin_inset LatexCommand cite
106 key "Cecil"
108 \end_inset
111 \begin_inset LatexCommand index
112 name "Cecil"
114 \end_inset
116 , Slate is dynamic and more free-form in style, supporting the simplicity
117  and flexibility of syntax and environment of the Smalltalk family.
118  It is intended that both Smalltalk and Self styles of programs can be ported
119  to Slate with minimal effort.
120  Finally, Slate contains extensions
121 \begin_inset LatexCommand index
122 name "extensions"
124 \end_inset
126  including optional keywords, optional type-declarations, subjective dispatch
127  and syntactic macros, that can be used to make existing programs and environmen
128 t organizations much more powerful than in traditional object-based programming.
129 \end_layout
131 \begin_layout Subsection
132 Conventions
133 \end_layout
135 \begin_layout Standard
136 Throughout this manual, various terms will be highlighted in different ways
137  to indicate the type of their significance.
138  If some concept is a certain programming utility in Slate with a definite
139  implementation, it will be formatted in a 
140 \family typewriter
141 typewriter-style
142 \family default
144  If a term is technical with a consistent definition in Slate, but cannot
145  have a definite implementation, it will be set in 
146 \noun on
147 small capital letters
148 \noun default
150  Emphasis on its own is denoted by 
151 \emph on
152 italics
153 \emph default
155  When expression/result patterns are entered, typewriter-style text will
156  be used with a 
157 \family typewriter
158 Slate>
159 \family default
160  prompt before the statement and its result will be set in 
161 \family typewriter
162 \emph on
163 italicized typewritten text
164 \family default
165 \emph default
166  below the line.
167 \end_layout
169 \begin_layout Subsection
170 Terms
171 \end_layout
173 \begin_layout Standard
174 Slate is an object-oriented language, and as such works with some terms
175  worth describing initially for clarity.
176  These are primarily inspired by the metaphor of computational entities
177  which communicate via messages, as follows:
178 \end_layout
180 \begin_layout Description
181 Object
182 \begin_inset LatexCommand index
183 name "object (terminology)"
185 \end_inset
187  is some thing in the system that can be identified.
188 \end_layout
190 \begin_layout Description
191 Method
192 \begin_inset LatexCommand index
193 name "method (terminology)"
195 \end_inset
197  is some behavior or procedure that is defined on some objects or class
198  of objects.
199 \end_layout
201 \begin_layout Description
202 Message
203 \begin_inset LatexCommand index
204 name "message (terminology)"
206 \end_inset
208  is the act of requesting a behavior or procedure from some objects, the
209  message's 
210 \emph on
211 arguments
212 \emph default
214  The requestor is known as the 
215 \emph on
216 sender
217 \emph default
219 \end_layout
221 \begin_layout Description
222 Answer
223 \begin_inset LatexCommand index
224 name "answer (terminology)"
226 \end_inset
228  is the response to a message; a value that expressions evaluate into or
229  return to the message's sender.
230 \end_layout
232 \begin_layout Description
233 Selector
234 \begin_inset LatexCommand index
235 name "selector (terminology)"
237 \end_inset
239  is the name of a method or a message-send.
240 \end_layout
242 \begin_layout Description
243 Inheritance
244 \begin_inset LatexCommand index
245 name "inheritance (terminology)"
247 \end_inset
249  is a relationship between objects that confers one object's (the parent)
250  behavior on another (the child).
251 \end_layout
253 \begin_layout Description
254 Dispatch
255 \begin_inset LatexCommand index
256 name "dispatch (terminology)"
258 \end_inset
260  is the process of determining, from a message-send, what method is appropriate
261  to invoke to implement the behavior.
262  This is also referred to as 
263 \emph on
264 lookup
265 \emph default
267 \end_layout
269 \begin_layout Section
270 Language Reference
271 \end_layout
273 \begin_layout Subsection
274 Objects
275 \end_layout
277 \begin_layout Standard
279 \noun on
280 \begin_inset LatexCommand index
281 name "objects"
283 \end_inset
285 Objects
286 \noun default
287  are fundamental in Slate; everything in a running Slate system consists
288  of objects.
289  Slate objects consist of a number of slots and roles: slots
290 \begin_inset LatexCommand index
291 name "slots"
293 \end_inset
295  are mappings from 
296 \family typewriter
297 Symbol
298 \family default
299 s to other objects, and roles
300 \begin_inset LatexCommand index
301 name "roles"
303 \end_inset
305  are a means of organizing code that can act on the object.
306  Slots themselves are accessed and updated by a kind of message-send which
307  is not distinguishable from other message-sends syntactically, but have
308  some important differences.
309 \end_layout
311 \begin_layout Standard
312 Objects in Slate are created by 
313 \emph on
314 cloning
315 \begin_inset LatexCommand index
316 name "cloning"
318 \end_inset
321 \emph default
322  existing objects, rather than instantiating a class.
323  When an object is cloned, the created object has the same slots and values
324  as the original one.
325  The new object will also have the access and update methods for those slots
326  carried over to the new object.
327  Other methods defined on the object will propagate through an analogue
328  of a slot called a role, explained in section 
329 \begin_inset LatexCommand ref
330 reference "sub:Methods"
332 \end_inset
334  on Methods.
335 \end_layout
337 \begin_layout Standard
338 Both control flow and methods are implemented by specialized objects called
339  blocks
340 \begin_inset LatexCommand index
341 name "blocks"
343 \end_inset
345 , which are code closures
346 \begin_inset LatexCommand index
347 name "code closures"
349 \end_inset
352  These code closures contain their own slots and create activation objects
353  to handle run-time context when invoked.
354  They can also be stored in slots and sent their own kinds of messages.
355 \end_layout
357 \begin_layout Subsubsection
358 Code Blocks
359 \end_layout
361 \begin_layout Standard
362 \begin_inset LatexCommand label
363 name "sub:Block-Closures"
365 \end_inset
367 A code block
368 \begin_inset LatexCommand index
369 name "code block"
371 \end_inset
373  is an object representing an encapsulable context of execution, containing
374  local variables, input variables, the capability to execute expressions
375  sequentially, and finally answers a value to its point of invocation.
376  The default return value for a block is the last expression's value; an
377  early return via 
378 \family typewriter
380 \family default
381  (see 
382 \begin_inset LatexCommand vref
383 reference "sub:Early-Returns"
385 \end_inset
388 \begin_inset LatexCommand index
389 name "return, early"
391 \end_inset
393  can override this.
394 \end_layout
396 \begin_layout Standard
397 Blocks have a special syntax for building them up syntactically.
398  Block expressions are delimited by square brackets.
399  The block's optional header can specify input and local slots between vertical
400  bars (
401 \family typewriter
403 \family default
404 ), and then a sequence of expressions which comprises the block's body.
405  The input syntax allows specification of the slot names desired at the
406  beginning.
407  For example,
408 \end_layout
410 \begin_layout LyX-Code
411 Slate> [| :arg num | num: 4.
412  arg + num].
413 \newline
415 \emph on
417 \end_layout
419 \begin_layout Standard
420 creates and returns a new block.
421  Within the header, identifiers that begin with a colon such as 
422 \family typewriter
423 :arg
424 \family default
425  above are parsed as input slots
426 \begin_inset LatexCommand index
427 name "input slots"
429 \end_inset
432  The order in which they are specified is the order that arguments matching
433  them must be passed in later to evaluate the block.
434  If the block is evaluated later, it will return the expression after the
435  final stop (the period) within the brackets, 
436 \family typewriter
437 arg\InsetSpace ~
438 +\InsetSpace ~
440 \family default
442  In this block, 
443 \family typewriter
445 \family default
446  is an input slot, and 
447 \family typewriter
449 \family default
450  is a local slot
451 \begin_inset LatexCommand index
452 name "local slots"
454 \end_inset
456  which is assigned to and then used in a following expression.
457  The order of specifying the mix of input and local slots does not affect
458  the semantics, but the order of the input slots directly determines what
459  order arguments need to be passed to the block to assign them to the correct
460  slots.
461 \end_layout
463 \begin_layout Standard
464 Using the term "slot" for local and input variables is not idle: the block
465  is an actual object with slots for each of these variables, and accessors
466  defined on them which are even callable from outside the block, considering
467  it as an object.
468 \end_layout
470 \begin_layout Standard
471 \begin_inset LatexCommand index
472 name "block invocation"
474 \end_inset
476 In order to invoke a block, the caller must know how many and in what order
477  it takes input arguments.
478  Every block responds to 
479 \family typewriter
480 applyTo:
481 \begin_inset LatexCommand index
482 name "applyTo: (message)"
484 \end_inset
487 \family default
488 , which takes an array of the input values as its other argument.
489  The block is immediately evaluated, and the result of the evaluation is
490  the block's execution result.
491  For example,
492 \end_layout
494 \begin_layout LyX-Code
495 Slate> [| :x :y | x quo: y] applyWith: 17 with: 5.
496 \newline
498 \emph on
500 \newline
502 \emph default
503 Slate> [| :a :b | (a raisedTo: 2) - (4 * b)] 
504 \newline
505  applyTo: {3.
506  4}.
507 \newline
509 \emph on
511 \end_layout
513 \begin_layout Standard
514 Arguments can also be passed in using some easier messages.
515  Blocks that don't expect any inputs respond to 
516 \family typewriter
518 \family default
520 \begin_inset LatexCommand index
521 name "do (message)"
523 \end_inset
525 , as follows:
526 \end_layout
528 \begin_layout LyX-Code
529 Slate> [| a b | a: 4.
530  b: 5.
531  a + b] do.
532 \newline
534 \emph on
536 \end_layout
538 \begin_layout Standard
539 Blocks that take one, two, or three inputs, each have special messages 
540 \family typewriter
541 applyWith:
542 \family default
544 \begin_inset LatexCommand index
545 name "applyWith: (message)"
547 \end_inset
550 \family typewriter
551 applyWith:with:
552 \family default
554 \begin_inset LatexCommand index
555 name "applyWith:with: (message)"
557 \end_inset
559 , and 
560 \family typewriter
561 applyWith:with:with:
562 \begin_inset LatexCommand index
563 name "applyWith:with:with: (message)"
565 \end_inset
568 \family default
569  which pass in the inputs in the order they were declared in the block header.
570 \end_layout
572 \begin_layout Standard
573 If a block is empty
574 \begin_inset LatexCommand index
575 name "block, empty"
577 \end_inset
579 , contains an empty body, or the final expression is terminated with a period
580 \begin_inset LatexCommand index
581 name "block, termination with a period"
583 \end_inset
585 , it returns 
586 \family typewriter
588 \family default
589  when evaluated:
590 \end_layout
592 \begin_layout LyX-Code
593 Slate> [] do.
594 \newline
596 \emph on
598 \emph default
600 \newline
601 Slate> [| :a :b |] applyTo: {0.
602  2}.
603 \newline
605 \emph on
607 \newline
609 \emph default
610 Slate> [3.
611  4.] do.
612 \newline
614 \emph on
616 \end_layout
618 \begin_layout Standard
619 \begin_inset LatexCommand index
620 name "variable arguments"
622 \end_inset
625 \begin_inset LatexCommand index
626 name "rest parameter"
628 \end_inset
630 If more arguments are passed than the block expects as inputs, an error
631  is raised unless the block specifies a single 
632 \begin_inset Quotes eld
633 \end_inset
635 rest
636 \begin_inset Quotes erd
637 \end_inset
639  argument parameter, using an asterisk prefix for the argument identifier
640  in its header (e.g.
642 \family typewriter
643 *rest
644 \family default
645 ), in which case the slot is bound to an array of the inputs not otherwise
646  bound.
647 \end_layout
649 \begin_layout Standard
650 Blocks furthermore have the property that, although they are a piece of
651  code and the values they access may change between defining the closure
652  and invoking it, the code will 
653 \begin_inset Quotes eld
654 \end_inset
656 remember
657 \begin_inset Quotes erd
658 \end_inset
660  what objects it depends on, regardless of what context it may be passed
661  to as a slot value.
662  It is called a lexical closure
663 \begin_inset LatexCommand index
664 name "lexical closure"
666 \end_inset
669 \begin_inset LatexCommand index
670 name "closure, lexical"
672 \end_inset
674  since it 
675 \begin_inset Quotes eld
676 \end_inset
678 closes over
679 \begin_inset Quotes erd
680 \end_inset
682  the environment and variables used in its definition, the lexical context
683  where it was born.
684  This is critical for implementing good control structures in Slate, as
685  is explained later.
686  Basically a block is an activation of its code composed with an environment
687  that can be saved and invoked (perhaps multiple times) long after it is
688  created, and always do so in the way that it reads where it was defined.
689 \end_layout
691 \begin_layout Subsubsection
692 Slots
693 \end_layout
695 \begin_layout Standard
696 \begin_inset LatexCommand index
697 name "slot properties"
699 \end_inset
702 \begin_inset LatexCommand index
703 name "slot mutability"
705 \end_inset
708 \begin_inset LatexCommand index
709 name "slots, delegation"
711 \end_inset
713 Slots may be mutable or immutable, and explicit slots or delegation (inheritance
714 ) slots.
715  These four possibilities are covered by primitive methods defined on all
716  objects.
717 \end_layout
719 \begin_layout Standard
720 Slate provides several primitive messages to manage 
721 \noun on
722 data slots
723 \noun default
724  (or 
725 \emph on
726 non-delegating
727 \emph default
728  slots):
729 \end_layout
731 \begin_layout Description
733 \family typewriter
734 \begin_inset LatexCommand index
735 name "addSlot: (message)"
737 \end_inset
739 obj\InsetSpace ~
740 addSlot:\InsetSpace ~
741 slotSymbol
742 \family default
743  adds a slot using the 
744 \family typewriter
745 Symbol
746 \family default
747  as its name, initialized to 
748 \family typewriter
750 \family default
752 \end_layout
754 \begin_layout Description
756 \family typewriter
757 \begin_inset LatexCommand index
758 name "addSlot:valued: (message)"
760 \end_inset
762 obj\InsetSpace ~
763 addSlot:\InsetSpace ~
764 slotSymbol\InsetSpace ~
765 valued:\InsetSpace ~
767 \family default
768  adds a slot under the given name and initializes its value to the given
769  one.
770 \end_layout
772 \begin_layout Description
773 \begin_inset LatexCommand index
774 name "addImmutableSlot:valued: (message)"
776 \end_inset
779 \family typewriter
780 addImmutableSlot:valued:
781 \family default
782  performs the same as the above method, only without installing a mutator
783  method.
784 \end_layout
786 \begin_layout Description
788 \family typewriter
789 \begin_inset LatexCommand index
790 name "removeSlot: (message)"
792 \end_inset
794 obj\InsetSpace ~
795 removeSlot:\InsetSpace ~
796 slotSymbol
797 \family default
798  removes the slot with the given name on the object directly and returns
799  whatever value it had.
800 \end_layout
802 \begin_layout Standard
803 The effect of all of the slot addition methods when a slot of the same name
804  is present is to update the value and attributes of the slot rather than
805  duplicate or perform nothing.
806 \end_layout
808 \begin_layout Subsubsection
809 Inheritance
810 \end_layout
812 \begin_layout Standard
813 \begin_inset LatexCommand index
814 name "delegation"
816 \end_inset
818 Slate's means of sharing and conferring behavior involves the use of a 
819 \noun on
820 delegation array
821 \noun default
822 , whereby each object can name and access each object it inherits from.
824 \end_layout
826 \begin_layout Standard
827 The delegates' inheritance role involves a precedence order which affects
828  the lookup of messages; from the object's perspective, the delegate slot
829  array goes from least important to most important.
830  Section 
831 \begin_inset LatexCommand vref
832 reference "sub:Lookup-Semantics"
834 \end_inset
836  explains the details of lookup semantics.
837 \end_layout
839 \begin_layout Standard
840 The relevant primitives specific to delegation slots are:
841 \end_layout
843 \begin_layout Description
845 \family typewriter
846 \begin_inset LatexCommand index
847 name "addDelegate: (message)"
849 \end_inset
852 \begin_inset LatexCommand index
853 name "addDelegate:valued: (message)"
855 \end_inset
857 obj\InsetSpace ~
858 addDelegate:\InsetSpace ~
860 \family default
861  and 
862 \family typewriter
863 \series bold
864 obj\InsetSpace ~
865 insertDelegate:\InsetSpace ~
867 \family default
868 \series default
869  add a delegate.
870  The delegates array for an object is stored in the object's map.
871 \end_layout
873 \begin_layout Description
874 \begin_inset LatexCommand index
875 name "delegates (message)"
877 \end_inset
880 \begin_inset LatexCommand index
881 name "delegates: (message)"
883 \end_inset
886 \family typewriter
888 \begin_inset ERT
889 status collapsed
891 \begin_layout Standard
893 \family typewriter
895 \backslash
897 \end_layout
899 \end_inset
901 delegates and
902 \family default
904 \family typewriter
905 \series bold
907 \begin_inset ERT
908 status collapsed
910 \begin_layout Standard
912 \family typewriter
913 \series bold
915 \backslash
917 \end_layout
919 \end_inset
921 delegates:
922 \family default
923 \series default
924  allow for finer control over manipulating delegates, since they explicitly
925  set the delegate array.
926  Use with care.
927 \end_layout
929 \begin_layout Subsection
930 Sending Messages
931 \end_layout
933 \begin_layout Standard
934 \begin_inset LatexCommand index
935 name "expressions"
937 \end_inset
939 Expressions in Slate mainly consist of messages sent to argument objects.
940  The left-most argument is not considered an implicit receiver as it is
941  with most message-passing languages, however.
942  This means that when identifying a variable, it is really a message that
943  is being sent to the context or argument.
944 \end_layout
946 \begin_layout Standard
947 \begin_inset LatexCommand index
948 name "case sensitivity"
950 \end_inset
953 \begin_inset LatexCommand index
954 name "whitespace sensitivity"
956 \end_inset
958 An important issue is that every message selector (and slot name) is 
959 \emph on
960 case-sensitive
961 \emph default
962  in Slate, that is, there is a definite distinction between what 
963 \family typewriter
964 AnObject
965 \family default
967 \family typewriter
968 anobject
969 \family default
970 , and 
971 \family typewriter
972 ANOBJECT
973 \family default
974  denote even in the same context.
975  Furthermore, the current implementation is 
976 \emph on
977 whitespace-sensitive
978 \emph default
979  as well, in the sense that whitespace must be used to separate messages
980  in order for them to be considered separate.
981  For example, 
982 \family typewriter
983 ab+4
984 \family default
985  will be treated as one message, but 
986 \family typewriter
987 ab\InsetSpace ~
988 +\InsetSpace ~
990 \family default
991  is a send of a binary message.
992 \end_layout
994 \begin_layout Standard
995 \begin_inset LatexCommand index
996 name "messages, types"
998 \end_inset
1000 There are three basic types of messages, with different syntaxes and associativi
1001 ties: unary, binary, and keyword messages.
1003 \emph on
1005 \begin_inset LatexCommand index
1006 name "messages, precedence"
1008 \end_inset
1011 \begin_inset LatexCommand index
1012 name "precedence, messages"
1014 \end_inset
1016 Precedence
1017 \emph default
1018  is determine entirely by the syntactic form of the expression, but it can
1019  of course be overridden by enclosing expressions in parentheses.
1020  An implicit left-most argument can be used with all of them.
1021  The default precedence for forms is as follows:
1022 \end_layout
1024 \begin_layout Enumerate
1025 Literal syntax: arrays, blocks, block headers, statement sequences.
1026 \end_layout
1028 \begin_layout Enumerate
1029 Unary messages.
1030 \end_layout
1032 \begin_layout Enumerate
1033 Binary messages.
1034 \end_layout
1036 \begin_layout Enumerate
1037 Keyword messages.
1038 \end_layout
1040 \begin_layout Standard
1041 \begin_inset LatexCommand index
1042 name "selector"
1044 \end_inset
1046 A concept that will be often used about message-sends is that of the name
1047  of a message, its 
1048 \noun on
1049 selector
1050 \noun default
1052  This is the 
1053 \family typewriter
1054 Symbol
1055 \family default
1056  used to refer to the message or the name of a method that matches it.
1057  Slate uses three styles of selectors, each with a unique but simple syntax.
1058 \end_layout
1060 \begin_layout Subsubsection
1061 \begin_inset LatexCommand label
1062 name "sub:Unary-Message-sends"
1064 \end_inset
1066 Unary Messages
1067 \end_layout
1069 \begin_layout Standard
1070 \begin_inset LatexCommand index
1071 name "unary messages"
1073 \end_inset
1076 \begin_inset LatexCommand index
1077 name "messages, unary"
1079 \end_inset
1082 \noun on
1083 unary message
1084 \noun default
1085  does not specify any additional arguments.
1086  It is written as a name following a single argument; it has a post-fix
1087  form.
1088 \end_layout
1090 \begin_layout Standard
1091 Some examples of unary message-sends to explicit arguments include:
1092 \end_layout
1094 \begin_layout LyX-Code
1095 Slate> 42 print.
1096 \newline
1098 \emph on
1099 '42'
1100 \newline
1102 \emph default
1103 Slate> 'Slate' clone.
1104 \newline
1106 \emph on
1107 'Slate'
1108 \end_layout
1110 \begin_layout Standard
1111 Unary sends associate from left to right.
1112  So the following prints the factorial of 5:
1113 \end_layout
1115 \begin_layout LyX-Code
1116 Slate> 5 factorial print.
1117 \newline
1119 \emph on
1120 '120'
1121 \end_layout
1123 \begin_layout Standard
1124 Which works the same as:
1125 \end_layout
1127 \begin_layout LyX-Code
1128 Slate> (5 factorial) print.
1129 \newline
1131 \emph on
1132 '120'
1133 \end_layout
1135 \begin_layout Standard
1136 Unary selectors can be most any alpha-numeric identifier, and are identical
1137  lexically to ordinary identifiers of slot names.
1138  This is no coincidence, since slots are accessed via a type of unary selector.
1139 \end_layout
1141 \begin_layout Subsubsection
1142 Binary Messages
1143 \end_layout
1145 \begin_layout Standard
1146 \begin_inset LatexCommand index
1147 name "messages, binary"
1149 \end_inset
1152 \begin_inset LatexCommand index
1153 name "binary messages"
1155 \end_inset
1158 \noun on
1159 binary message
1160 \noun default
1161  is named by a special non-alphanumeric symbol and 'sits between' its two
1162  arguments; it has an infix form.
1163  Binary messages are also evaluated from left to right; there is no special
1165 \emph on
1166 precedence
1167 \emph default
1168  difference between any two binary message-sends.
1169 \begin_inset Foot
1170 status open
1172 \begin_layout Standard
1173 This removes a source of grammatical complexity in a language where anyone
1174  can add new binary selectors or implementations.
1175  It is our policy that conventional mathematical notation and visual convenience
1176  belong in user interface libraries.
1177 \end_layout
1179 \end_inset
1182 \end_layout
1184 \begin_layout Standard
1185 These examples illustrate the precedence and syntax:
1186 \end_layout
1188 \begin_layout LyX-Code
1189 Slate> 3 + 4.
1190 \newline
1192 \emph on
1194 \emph default
1196 \newline
1197 Slate> 3 + 4 * 5.
1198 \newline
1200 \emph on
1202 \emph default
1204 \newline
1205 Slate> (3 + 4) * 5.
1206 \newline
1208 \emph on
1210 \emph default
1212 \newline
1213 Slate> 3 + (4 * 5).
1214 \newline
1216 \emph on
1218 \end_layout
1220 \begin_layout Standard
1221 Binary messages have lower 
1222 \emph on
1223 precedence
1224 \emph default
1225  than unary messages.
1226  Without any grouping notation, the following expression's unary messages
1227  will be evaluated first and then passed as arguments to the binary message:
1228 \end_layout
1230 \begin_layout LyX-Code
1231 Slate> 7 factorial + 3 negated.
1232 \newline
1234 \emph on
1235 5037
1236 \newline
1238 \emph default
1239 Slate> (7 factorial) + (3 negated).
1240 \newline
1242 \emph on
1243 5037
1244 \newline
1246 \emph default
1247 Slate> (7 factorial + 3) negated.
1248 \newline
1250 \emph on
1251 -5043
1252 \end_layout
1254 \begin_layout Standard
1255 Binary selectors can consist of one or more of the following characters:
1256 \end_layout
1258 \begin_layout LyX-Code
1259 # $ % ^ * - + = 
1260 \begin_inset ERT
1261 status open
1263 \begin_layout Standard
1266 \backslash
1268 \end_layout
1270 \end_inset
1272  / 
1273 \backslash
1274  ? < > , ;
1275 \end_layout
1277 \begin_layout Standard
1278 However, these characters are reserved:
1279 \end_layout
1281 \begin_layout LyX-Code
1282 @ [ ] ( ) { } .
1283  : ! | ` &
1284 \end_layout
1286 \begin_layout Subsubsection
1287 Keyword Messages
1288 \end_layout
1290 \begin_layout Standard
1291 \begin_inset LatexCommand index
1292 name "keyword messages"
1294 \end_inset
1297 \begin_inset LatexCommand index
1298 name "messages, keyword"
1300 \end_inset
1303 \noun on
1304 keyword message
1305 \noun default
1306  is an alternating sequence of keywords and expressions, generally being
1307  a continued infix form.
1308  Keywords are identifiers beginning with a letter and ending with a colon.
1309  Keyword messages start with the left-most argument along with the longest
1310  possible sequence of keyword-value pairs.
1312 \begin_inset LatexCommand index
1313 name "selector, of keyword message"
1315 \end_inset
1317 The 
1318 \noun on
1319 selector
1320 \noun default
1321  of the message is the joining-together of all the keywords into one 
1322 \family typewriter
1323 Symbol
1324 \family default
1325 , which is the 
1326 \emph on
1327 name
1328 \emph default
1329  of the message.
1330  For example,
1331 \end_layout
1333 \begin_layout LyX-Code
1334 Slate> 5 min: 4 max: 7.
1335 \newline
1337 \emph on
1339 \end_layout
1341 \begin_layout Standard
1342 is a keyword message-send named 
1343 \family typewriter
1344 min:max:
1345 \family default
1346  which has 3 arguments: 5, 4, and 7.
1347  However,
1348 \end_layout
1350 \begin_layout LyX-Code
1351 Slate> 5 min: (4 max: 7).
1352 \newline
1354 \emph on
1356 \end_layout
1358 \begin_layout Standard
1359 is a different kind of expression.
1361 \emph on
1363 \emph default
1364  keyword message-sends are made, the first being 
1365 \family typewriter
1366 max:
1367 \family default
1368  sent to 4 and 7, and 
1369 \family typewriter
1370 min:
1371 \family default
1372  sent to 5 and the first result.
1373  Note however, that even though the first expression evaluates to the same
1374  value as:
1375 \end_layout
1377 \begin_layout LyX-Code
1378 Slate> (5 min: 4) max: 7.
1379 \newline
1381 \emph on
1383 \end_layout
1385 \begin_layout Standard
1386 that this is still a distinct expression from the first one, with two message-se
1387 nds of one keyword each instead of one send with two keywords.
1388  Actually, this expresses the definition of 
1389 \family typewriter
1390 min:max:
1391 \family default
1392 , although this is perhaps one of the most trivial uses of method names
1393  with multiple keywords.
1394 \end_layout
1396 \begin_layout Standard
1397 Keywords have the lowest 
1398 \emph on
1399 precedence
1400 \emph default
1401  of message-sends, so arguments may be the results of unary or binary sends
1402  without explicit grouping required.
1403  For example, the first expression here is equivalent to the latter implicitly:
1404 \end_layout
1406 \begin_layout LyX-Code
1407 Slate> 5 + 4 min: 7 factorial max: 8.
1408 \newline
1410 \emph on
1412 \emph default
1414 \newline
1415 Slate> (5 + 4) min: (7 factorial) max: 8.
1416 \newline
1418 \emph on
1420 \end_layout
1422 \begin_layout Subsubsection
1423 Implicit-context Messages
1424 \end_layout
1426 \begin_layout Standard
1427 \begin_inset LatexCommand index
1428 name "sends, implicit-context"
1430 \end_inset
1433 \begin_inset LatexCommand index
1434 name "implicit-context sends"
1436 \end_inset
1439 \begin_inset LatexCommand index
1440 name "lexical scope"
1442 \end_inset
1445 \begin_inset LatexCommand index
1446 name "scope, lexical"
1448 \end_inset
1450 Within methods, blocks, and even at the top-level, some expressions may
1451  take the surrounding context as the first argument.
1452  There is an order for the determination of which object becomes the first
1453  argument, which is entirely based on lexical scoping.
1454  So, within a block, an implicit send will take the block's run-time context
1455  as argument.
1456  The next outer contexts follow in sequence, up to the top-level and what
1457  it inherits from, which generally turns out to be the global object that
1458  roots the current session.
1459 \end_layout
1461 \begin_layout Standard
1462 Specifically, any non-literal expression following a statement-separator
1463  or starting an expression within parentheses or other grouping is an implicit-c
1464 ontext send.
1465 \end_layout
1467 \begin_layout Standard
1468 There are some very common uses of implicit-context sends.
1469  In particular, accessing and modifying local variables of a block or method
1470  is accomplished entirely this way, as well as returns.
1471  For example,
1472 \end_layout
1474 \begin_layout LyX-Code
1475 [| :i j k |
1476 \newline
1477  j: i factorial.
1478 \newline
1479  k: (j raisedTo: 4).
1480 \newline
1481  j < k ifTrue: [| m |
1482 \newline
1483    j:
1484  j - i.
1485  m: j.
1486  ^ (m raisedTo: 3)].
1487 \newline
1488  k: k - 4.
1489 \newline
1491 \newline
1493 \end_layout
1495 \begin_layout Standard
1496 is a block which, when invoked, takes one argument and has another two to
1497  manipulate.
1498  Notice that the local slot 
1499 \family typewriter
1501 \family default
1502  is available within the enclosed block that also has a further slot 
1503 \family typewriter
1505 \family default
1507  Local blocks may also 
1508 \emph on
1509 override
1510 \emph default
1511  the slots of their outer contexts with their input and local slots.
1512  In this case, the identifiers 
1513 \family typewriter
1515 \family default
1516  and 
1517 \family typewriter
1519 \family default
1520 , for example, are automatically-generated accessing and update methods
1521  on the context.
1522  Because 
1523 \family typewriter
1525 \family default
1526  is a keyword message, if the assigned value is a keyword message-send result,
1527  it must be enclosed in parentheses to distinguish the keyword pattern.
1528  The 
1529 \family typewriter
1530 ^\InsetSpace ~
1531 (m\InsetSpace ~
1532 raisedTo:\InsetSpace ~
1534 \family default
1535  message
1536 \begin_inset LatexCommand index
1537 name "early return"
1539 \end_inset
1541  causes the context to exit prematurely, returning as its value the result
1542  of the right-hand argument.
1543  All methods have this method defined on them, and it will return out to
1544  the nearest named block or to the top-level.
1545 \end_layout
1547 \begin_layout Standard
1548 The way this is currently implemented is that the compiler will detect when
1549  a local slot is read or modified and it will turn the command into a 
1550 \family typewriter
1551 loadVariable
1552 \family default
1553  or 
1554 \family typewriter
1555 storeVariable
1556 \family default
1557  bytecode.
1558  If the a read or write is done to a variable in a parent block, it will
1559  be compiled to a 
1560 \family typewriter
1561 loadFreeVariable
1562 \family default
1563  or 
1564 \family typewriter
1565 storeFreeVariable
1566 \family default
1567  which will get the value from the current closure's lexical window array.
1568 \end_layout
1570 \begin_layout Subsection
1571 Sequencing Expressions
1572 \end_layout
1574 \begin_layout Standard
1575 \begin_inset LatexCommand index
1576 name "expression sequences"
1578 \end_inset
1581 \begin_inset LatexCommand index
1582 name ". (period)"
1584 \end_inset
1587 \begin_inset LatexCommand index
1588 name "stop mark"
1590 \end_inset
1592 Statements are the overall expressions between stop-marks, which are periods.
1593  In an interactive evaluation context, expressions aren't evaluated until
1594  a full (top-level) statement is expressed.
1595  The stop mark also means that statement's expression results aren't directly
1596  carried forward as an argument to the following expression; side-effects
1597  must be used to use the results.
1598  More specifically, each expression in the sequence must be evaluated in
1599  order, and one expression's side-effects must effectively occur before
1600  the next expression begins executing and before any of its side-effects
1601  occur.
1602 \end_layout
1604 \begin_layout Standard
1605 \begin_inset LatexCommand index
1606 name "parentheses"
1608 \end_inset
1611 \begin_inset LatexCommand index
1612 name "() (parentheses)"
1614 \end_inset
1616 Slate provides for a bare expression sequence syntax that can be embedded
1617  within any grouping parentheses, as follows:
1618 \end_layout
1620 \begin_layout LyX-Code
1621 Slate> 3 + 4.
1622 \newline
1624 \emph on
1626 \end_layout
1628 \begin_layout LyX-Code
1629 Slate> (7 factorial.
1631 \newline
1632  negated) min: 6.
1633 \newline
1635 \emph on
1637 \end_layout
1639 \begin_layout Standard
1640 The parentheses are used just as normal grouping, and notably, the 
1641 \family typewriter
1642 5\InsetSpace ~
1643 negated
1644 \family default
1645  expression wraps over a line, but still evaluates that way.
1646 \begin_inset Foot
1647 status collapsed
1649 \begin_layout Standard
1650 We do not consider this expression good style, but it illustrates the nature
1651  of the syntax.
1652 \end_layout
1654 \end_inset
1656  If the parentheses are empty, or the last statement in a sequence is followed
1657  by a period before ending the sequence, an 
1658 \begin_inset LatexCommand index
1659 name "empty expression"
1661 \end_inset
1664 \begin_inset Quotes eld
1665 \end_inset
1667 empty expression
1668 \begin_inset Quotes erd
1669 \end_inset
1671  value is returned, which is 
1672 \family typewriter
1674 \begin_inset LatexCommand index
1675 name "Nil (object)"
1677 \end_inset
1680 \family default
1681  by convention.
1682 \end_layout
1684 \begin_layout Subsection
1685 Methods
1686 \end_layout
1688 \begin_layout Standard
1690 \noun on
1691 \begin_inset LatexCommand index
1692 name "methods"
1694 \end_inset
1697 \begin_inset LatexCommand index
1698 name "blocks, code"
1700 \end_inset
1703 \begin_inset LatexCommand index
1704 name "code blocks"
1706 \end_inset
1709 \begin_inset LatexCommand label
1710 name "sub:Methods"
1712 \end_inset
1714 Methods
1715 \noun default
1716  in Slate are basically annotated code blocks (documented in 
1717 \begin_inset LatexCommand ref
1718 reference "sub:Block-Closures"
1720 \end_inset
1722 ), coupled with annotations of the objects' roles that dispatch to them.
1723 \end_layout
1725 \begin_layout Subsubsection
1726 Roles
1727 \end_layout
1729 \begin_layout Standard
1730 A relatively unique concept in the language is that objects relate to their
1731  methods via an 
1732 \emph on
1733 implicit
1734 \emph default
1735  idea called a 
1736 \begin_inset LatexCommand index
1737 name "role"
1739 \end_inset
1742 \noun on
1743 role
1744 \noun default
1746  A role is an association between an object and a method that applies to
1747  it that is similar to a slot, but not directly a slot as it is in 
1748 \begin_inset LatexCommand index
1749 name "Self"
1751 \end_inset
1753 Self.
1754  Instead of simply being a storage reference, a role associates the object
1755  with a 
1756 \emph on
1757 position
1758 \emph default
1759  in the signature of a method.
1760  This is a way of stating that the object 
1761 \begin_inset Quotes eld
1762 \end_inset
1764 plays a role
1765 \begin_inset Quotes erd
1766 \end_inset
1768  in a certain behavior, reinforcing the idea that behavior arrives through
1769  cooperation.
1770  Furthermore, the behavior is shared among the cooperators, so methods are
1771  not 
1772 \begin_inset Quotes eld
1773 \end_inset
1775 owned
1776 \begin_inset Quotes erd
1777 \end_inset
1779  by particular objects; they are not properties.
1780 \end_layout
1782 \begin_layout Standard
1783 However, because dispatch can happen on many combinations of arguments,
1784  a method name plus the object's position is not sufficient to identify
1785  a single method; instead, a group of methods of the same name may be associated
1786  via a role with an object at a certain signature position.
1787  During method lookup, the appropriate method is found through knowing all
1788  of the objects in the signature and knowing which take precedence over
1789  others.
1790  So a specific role consists of a triple-association between an object,
1791  its position in a signature for a method, and the method itself.
1792 \end_layout
1794 \begin_layout Standard
1795 When referring to an object's 
1796 \begin_inset Quotes eld
1797 \end_inset
1799 roles
1800 \begin_inset Quotes erd
1801 \end_inset
1803  in general, it usually means the collection of these associations as a
1804  whole; what relates the object to the behaviors it participates in.
1805 \end_layout
1807 \begin_layout Subsubsection
1808 Method Definitions
1809 \end_layout
1811 \begin_layout Standard
1812 \begin_inset LatexCommand index
1813 name "method definition"
1815 \end_inset
1818 \begin_inset LatexCommand index
1819 name "method template"
1821 \end_inset
1823 Method definition syntax is handled relatively separately from normal precedence
1824  and grammar.
1825  It essentially revolves around the use of the reserved character 
1826 \begin_inset Quotes eld
1827 \end_inset
1830 \family typewriter
1832 \family default
1834 \begin_inset Quotes erd
1835 \end_inset
1838 \begin_inset LatexCommand index
1839 name "\\char `\\@ (at)"
1841 \end_inset
1844  If any identifier in a message-send argument position is found to contain
1845  the character, the rest of the same send is examined for other instances
1846  of the 
1847 \family typewriter
1848 Symbol
1849 \family default
1850 , and the whole send-expression is treated as a template.
1851  The parser treats the expression or identifier to the right of the 
1852 \family typewriter
1854 \family default
1855  characters as dispatch targets
1856 \begin_inset LatexCommand index
1857 name "dispatch targets"
1859 \end_inset
1861  for the method's argument positions; the actual objects returned by the
1862  expressions are annotated with a role for their positions.
1863 \end_layout
1865 \begin_layout Standard
1866 After the message-send template, there is expected a block expression of
1867  some kind, whether a literal or an existing block.
1868  Whichever is specified, the parser creates a new block out of it with adjustmen
1869 ts so that the identifiers in the dispatching message-send become input
1870  slots in the closure.
1871  The block should be the final expression encountered before the next stop
1872  (a period).
1873 \begin_inset LatexCommand index
1874 name "period"
1876 \end_inset
1879 \begin_inset LatexCommand index
1880 name ". (period)"
1882 \end_inset
1885 \begin_inset LatexCommand index
1886 name "stop mark"
1888 \end_inset
1891 \end_layout
1893 \begin_layout Standard
1894 \begin_inset LatexCommand index
1895 name "underscore"
1897 \end_inset
1900 \begin_inset LatexCommand index
1901 name "\\_ (underscore)"
1903 \end_inset
1905 There is a further allowance that an input slot-name specifier may be solely
1906  an underscore (but not an underscore followed by anything else), in which
1907  case the argument to the method at that position is 
1908 \emph on
1910 \emph default
1911  passed in to the block closure.
1912 \end_layout
1914 \begin_layout Standard
1915 This syntax is much simpler to recognize and create than to explain.
1916  For example, the following are a series of message definitions adding to
1917  boolean control of evaluation:
1918 \end_layout
1920 \begin_layout LyX-Code
1921 _@True ifTrue: block ifFalse: _ [block do].
1922 \newline
1923 _@False ifTrue: _ ifFalse: block
1924  [block do].
1925 \newline
1927 \newline
1928 bool@(Boolean traits) ifTrue: block
1929 \newline
1930 "Some sugaring for ifTrue:ifFalse:.
1932 \newline
1934 \newline
1935  bool ifTrue: block ifFalse: []
1936 \newline
1938 \end_layout
1940 \begin_layout Standard
1941 The first two represent good uses of dispatching on a particular individual
1942  object (dispatching the ignored argument named 
1943 \begin_inset Quotes eld
1944 \end_inset
1947 \family typewriter
1949 \family default
1951 \begin_inset Quotes erd
1952 \end_inset
1954  to 
1955 \family typewriter
1956 True
1957 \family default
1958  and 
1959 \family typewriter
1960 False
1961 \family default
1962 , respectively) as well as the syntax for disregarding its value.
1963  Within their blocks, 
1964 \family typewriter
1965 block
1966 \family default
1967  refers to the named argument to the method.
1968  What's hidden is that the block given as the code is re-written to include
1969  those arguments as inputs in the header.
1970  Also, the objects given to the dispatch annotation are configured to install
1971  this method in appropriate roles; because this is hidden, roles are normally
1972  an implicit concept and should not concern the user except as an explanation
1973  for dispatch.
1974 \end_layout
1976 \begin_layout Standard
1977 The latter method appears to have a slightly-different syntax, but this
1978  is an illusion: the parentheses are just surrounding a Slate expression
1979  which evaluates to an object, much as 
1980 \family typewriter
1981 True
1982 \family default
1983  and 
1984 \family typewriter
1985 False
1986 \family default
1987  evaluate to particular objects; really, any Slate expression can be placed
1988  there, assuming that the result of it is what is wanted for dispatch.
1989  As a side note, this last method is defined in terms of the first two and
1990  is shared, since 
1991 \family typewriter
1992 True
1993 \family default
1994  and 
1995 \family typewriter
1996 False
1997 \family default
1998  both delegate to 
1999 \family typewriter
2000 Boolean\InsetSpace ~
2001 traits
2002 \family default
2003  (the object carrying the common behavior of the boolean objects).
2004 \end_layout
2006 \begin_layout Subsubsection
2007 Expression-based Definitions
2008 \end_layout
2010 \begin_layout Standard
2011 \begin_inset LatexCommand index
2012 name "methods, dynamic generation"
2014 \end_inset
2017 \begin_inset LatexCommand index
2018 name "asMethod:on: (message)"
2020 \end_inset
2022 The specialized syntax using the 
2023 \begin_inset Quotes eld
2024 \end_inset
2027 \family typewriter
2029 \family default
2031 \begin_inset Quotes erd
2032 \end_inset
2034  special has an equivalent in regular Slate syntax which is often useful
2035  for generating new methods dynamically in a non-ambiguous way.
2036  This is a reflective call on the evaluator to compile a method using a
2037  certain symbolic name and a sequence of objects that are used for dispatching
2038  targets.
2039  For example:
2040 \end_layout
2042 \begin_layout LyX-Code
2043 [| :x :y | Nil] asMethod: #+ on: {True.
2044  False}.
2045 \end_layout
2047 \begin_layout Standard
2049 \end_layout
2051 \begin_layout LyX-Code
2052 _@True + _@False [Nil].
2053 \end_layout
2055 \begin_layout Standard
2056 are equivalent (while not recommendable) expressions.
2057  This raises the question of a place-filler for an argument position which
2058  is not dispatched.
2059  In that case, Slate provides a unique primitive 
2060 \family typewriter
2061 NoRole
2062 \begin_inset LatexCommand index
2063 name "NoRole (object)"
2065 \end_inset
2068 \family default
2069  for this purpose, which provides an analogous role to 
2070 \family typewriter
2072 \family default
2074 \family typewriter
2075 NoRole
2076 \family default
2077  cannot be dispatched upon.
2078  Essentially, this means that the following method definition:
2079 \end_layout
2081 \begin_layout LyX-Code
2082 c@(Set traits) keyAt: index
2083 \newline
2085 \newline
2086   c array at: index
2087 \newline
2089 \end_layout
2091 \begin_layout Standard
2092 is semantically equivalent to:
2093 \end_layout
2095 \begin_layout LyX-Code
2096 c@(Set traits) keyAt: index@NoRole
2097 \newline
2099 \newline
2100   c array at: index
2101 \newline
2103 \end_layout
2105 \begin_layout Standard
2106 and furthermore to:
2107 \end_layout
2109 \begin_layout LyX-Code
2110 [| :c :index | c array at: index] asMethod: #keyAt:
2111 \newline
2112                    on:
2113  {Set traits.
2114  NoRole}.
2115 \end_layout
2117 \begin_layout Subsubsection
2118 \begin_inset LatexCommand label
2119 name "sub:Lookup-Semantics"
2121 \end_inset
2123 Lookup Semantics
2124 \end_layout
2126 \begin_layout Standard
2127 \begin_inset LatexCommand index
2128 name "dispatch, message"
2130 \end_inset
2133 \begin_inset LatexCommand index
2134 name "message dispatch"
2136 \end_inset
2139 \begin_inset LatexCommand index
2140 name "lookup semantics"
2142 \end_inset
2144 Message dispatch in Slate is achieved by consulting all of the arguments
2145  to that message, and considering what roles they have pertaining to that
2146  message name and their position within the message-send.
2147  Slate's dispatch semantics are termed 
2148 \begin_inset LatexCommand index
2149 name "multiple dispatch"
2151 \end_inset
2154 \begin_inset LatexCommand index
2155 name "dispatch, multiple"
2157 \end_inset
2160 \begin_inset Quotes eld
2161 \end_inset
2163 multiple dispatch
2164 \begin_inset Quotes erd
2165 \end_inset
2167  to distinguish from 
2168 \begin_inset Quotes eld
2169 \end_inset
2171 single dispatch
2172 \begin_inset Quotes erd
2173 \end_inset
2175  which is typical of most languages based on objects and messages.
2176  Whereas most languages designate on object as the receiver of a message,
2177  Slate considers all objects involved cooperating participants.
2178  During the dispatch process, more than one method can be discovered as
2179  a potential candidate.
2180  The most 
2181 \emph on
2182 specific
2183 \emph default
2184  candidate is chosen as soon as its place in the order is determined.
2185 \end_layout
2187 \begin_layout Standard
2188 The algorithm achieves a full ordering of arguments: the specificity of
2189  the first argument counts more than the second, the second more than the
2190  third, and so on.
2191  However, where normal multiple dispatch looks at each argument and uses
2192  the most specific supertype to determine specificity (or rather, the most
2193  specific parameter type of which the argument is a subtype), Slate instead
2194  interprets specificity as 
2195 \noun on
2196 distance
2197 \noun default
2198  in the directed graph of delegations, starting from the particular argument
2199  in question as the root.
2200 \end_layout
2202 \begin_layout Standard
2203 The 
2204 \noun on
2205 distance
2206 \noun default
2207  notion has the following properties:
2208 \end_layout
2210 \begin_layout Itemize
2211 It is determined by a depth-first traversal over the delegate slots, considering
2212  delegates at a higher index in the array before lower ones.
2213 \end_layout
2215 \begin_layout Itemize
2216 Delegations that lead to cycles are not traversed.
2217 \end_layout
2219 \begin_layout Itemize
2220 Repeated finds of a same method do not alter the distance value for it;
2221  the first one found is retained.
2222 \end_layout
2224 \begin_layout Itemize
2225 The closer (smaller) the 
2226 \noun on
2227 distance
2228 \noun default
2229  of the role to the argument, the more specific it is.
2230 \end_layout
2232 \begin_layout Standard
2233 So, Slate's lookup algorithm visits each argument in turn, determining candidate
2234  applicable methods as ordered by the 
2235 \noun on
2236 distance
2237 \noun default
2238  notion, and traverses further to look for other possible candidates, unless
2239  it rules out the possibility of a more applicable method than a singly-identifi
2240 ed one.
2241 \end_layout
2243 \begin_layout Standard
2244 The resulting dispatched method satisfies the property that: for any of
2245  the arguments, we can find the method on some role reachable by traversing
2246  delegations, and that is the closest such method we can find, where former
2247  arguments count as being 
2248 \begin_inset Quotes eld
2249 \end_inset
2251 closer
2252 \begin_inset Quotes erd
2253 \end_inset
2255  than any subsequent arguments, and 
2256 \family typewriter
2257 NoRole
2258 \family default
2259  behaves like an 
2260 \begin_inset Quotes eld
2261 \end_inset
2263 omega distance
2264 \begin_inset Quotes erd
2265 \end_inset
2267 , as far away as possible.
2268 \end_layout
2270 \begin_layout Subsubsection
2271 Optional Keyword Arguments
2272 \end_layout
2274 \begin_layout Standard
2275 \begin_inset LatexCommand index
2276 name "arguments, optional keyword"
2278 \end_inset
2281 \begin_inset LatexCommand index
2282 name "optional keyword arguments"
2284 \end_inset
2287 \begin_inset LatexCommand index
2288 name "keyword arguments, optional"
2290 \end_inset
2292 The mechanism in Slate for specifying optional input arguments uses 
2293 \emph on
2294 optional keywords
2295 \emph default
2296  for a syntax.
2297  They can be added to a method definition, a message-send, or a block header
2298  equally.
2299  Also, optional keywords can apply to unary, binary, and keyword message
2300  syntaxes equally.
2301  However, optional arguments cannot affect dispatch, can be provided in
2302  any order, and when not provided will start with a 
2303 \family typewriter
2305 \family default
2306  value, due to their being incidental to the core semantics of the given
2307  block or method.
2308 \end_layout
2310 \begin_layout Paragraph
2311 In Method Definitions
2312 \begin_inset LatexCommand index
2313 name "optional keywords (in a method definition)"
2315 \end_inset
2318 \end_layout
2320 \begin_layout Standard
2321 \begin_inset LatexCommand index
2322 name "ampersand"
2324 \end_inset
2327 \begin_inset LatexCommand index
2328 name "\\& (ampersand)"
2330 \end_inset
2332 Method definitions may be annotated with optionals that they support by
2333  extending the signature with keyword-localname pairs in arbitrary order
2334  as 
2335 \begin_inset Quotes eld
2336 \end_inset
2339 \family typewriter
2340 &keywordName:\InsetSpace ~
2341 argName
2342 \family default
2344 \begin_inset Quotes erd
2345 \end_inset
2348  This compiles the method to support 
2349 \family typewriter
2350 argName
2351 \family default
2352  as a local, with optional input.
2353 \end_layout
2355 \begin_layout Paragraph
2356 In Message Sends
2357 \begin_inset LatexCommand index
2358 name "optional keywords (in a message send)"
2360 \end_inset
2363 \end_layout
2365 \begin_layout Standard
2366 An optional keyword argument is passed to a method by forming keyword-value
2367  pairs as 
2368 \begin_inset Quotes eld
2369 \end_inset
2372 \family typewriter
2373 &keywordName:\InsetSpace ~
2374 someValue
2375 \family default
2377 \begin_inset Quotes erd
2378 \end_inset
2380  after the main selector and arguments as normal.
2381  Following keywords that have the 
2382 \family typewriter
2384 \family default
2385 -prefix will be collected into the same message-send.
2386  A following non-optional keyword will be treated as beginning a new surrounding
2387  message-send, but in general, optional keywords raise the precedence of
2388  the basis message signature to a keyword level, instead of just unary or
2389  binary.
2390  Again, the order of the keyword-value pairs is ignored.
2391 \end_layout
2393 \begin_layout Paragraph
2394 In Code Blocks
2395 \begin_inset LatexCommand index
2396 name "optional keywords (in a block header)"
2398 \end_inset
2401 \end_layout
2403 \begin_layout Standard
2404 A block can declare optional input keywords in its block header in any order,
2405  using 
2406 \begin_inset Quotes eld
2407 \end_inset
2410 \family typewriter
2411 &argName
2412 \family default
2414 \begin_inset Quotes erd
2415 \end_inset
2417  as an input variable declaration, called with the normal convention (when
2418  using the block with 
2419 \family typewriter
2421 \family default
2423 \family typewriter
2424 applyTo:
2425 \family default
2426 /etc.), whenever the block is invoked with a message-send.
2427 \end_layout
2429 \begin_layout Subsubsection
2430 Resending messages or Dispatch-overriding
2431 \begin_inset OptArg
2432 status collapsed
2434 \begin_layout Standard
2435 Resends
2436 \end_layout
2438 \end_inset
2441 \end_layout
2443 \begin_layout Standard
2444 \begin_inset LatexCommand index
2445 name "messages, resending"
2447 \end_inset
2450 \begin_inset LatexCommand index
2451 name "resending messages"
2453 \end_inset
2456 \begin_inset LatexCommand index
2457 name "overriding, dispatch"
2459 \end_inset
2462 \begin_inset LatexCommand index
2463 name "dispatch-overriding"
2465 \end_inset
2467 Because Slate's methods are not centered around any particular argument,
2468  the resending of messages is formulated in terms of giving the method activatio
2469 n itself a message.
2470  The following are the various primitive protocols involved in resends:
2471 \end_layout
2473 \begin_layout Description
2475 \family typewriter
2476 resend
2477 \begin_inset LatexCommand index
2478 name "resend (message)"
2480 \end_inset
2483 \family default
2484  is the simplest form of resending.
2485  It acts on the context to find the next-most-applicable method and invokes
2486  it with the exact same set of arguments (including optional parameters
2487  passed) as an expression.
2488  The result of the 
2489 \family typewriter
2490 resend
2491 \family default
2492  message is the returned result of that method, just like calling any other
2493  method.
2494 \end_layout
2496 \begin_layout Description
2498 \family typewriter
2499 \begin_inset LatexCommand index
2500 name "findOn: (message)]"
2502 \end_inset
2504 methodName\InsetSpace ~
2505 findOn:\InsetSpace ~
2506 argumentArray
2507 \family default
2508  locates and answers the method for the given 
2509 \family typewriter
2510 Symbol
2511 \family default
2512  name and group of argument objects.
2513 \end_layout
2515 \begin_layout Description
2517 \family typewriter
2518 \begin_inset LatexCommand index
2519 name "findOn:after: (message)"
2521 \end_inset
2523 methodName\InsetSpace ~
2524 findOn:\InsetSpace ~
2525 argumentArray\InsetSpace ~
2526 after:\InsetSpace ~
2527 aMethod
2528 \family default
2529  locates and answers the method following the given one with the same type
2530  of arguments as above.
2531 \end_layout
2533 \begin_layout Description
2535 \family typewriter
2536 \begin_inset LatexCommand index
2537 name "sendTo: (message)"
2539 \end_inset
2541 methodName\InsetSpace ~
2542 sendTo:\InsetSpace ~
2543 argumentArray
2544 \family default
2545  is an explicit application of a method, useful when the 
2546 \family typewriter
2547 Symbol
2548 \family default
2549  name of the method needs to be provided at run-time.
2550  It returns the result of the method.
2551 \end_layout
2553 \begin_layout Description
2555 \family typewriter
2556 \begin_inset LatexCommand index
2557 name "sendWith: (message)"
2559 \end_inset
2562 \begin_inset LatexCommand index
2563 name "sendWith:with: (message)"
2565 \end_inset
2568 \begin_inset LatexCommand index
2569 name "sendWith:with:with: (message)"
2571 \end_inset
2573 sendWith:
2574 \family default
2576 \family typewriter
2577 \series bold
2578 sendWith:with:
2579 \family default
2580 \series default
2581  and 
2582 \family typewriter
2583 \series bold
2584 sendWith:with:with:
2585 \family default
2586 \series default
2587  take one, two, and three arguments respectively as above without creating
2588  an array to pass the arguments in.
2589  It returns the result of the method.
2590 \end_layout
2592 \begin_layout Description
2594 \family typewriter
2595 \begin_inset LatexCommand index
2596 name "sendTo:through: (message)"
2598 \end_inset
2600 methodName\InsetSpace ~
2601 sendTo:\InsetSpace ~
2602 argumentArray\InsetSpace ~
2603 through:\InsetSpace ~
2604 dispatchArray
2605 \family default
2606  is an extra option to specify a different signature (the 
2607 \family typewriter
2608 dispatchArray
2609 \family default
2610 , where the new lookup starts) for the method than that of the actual argument
2611  objects.
2612  It returns the result of the method.
2613 \end_layout
2615 \begin_layout Standard
2616 Also, both 
2617 \family typewriter
2618 sendTo:
2619 \family default
2620  and 
2621 \family typewriter
2622 sendTo:through:
2623 \family default
2624  accept an 
2625 \family typewriter
2626 &optionals:
2627 \family default
2628  optional keyword which is passed an 
2629 \family typewriter
2630 Array
2631 \family default
2632  of the alternating keyword 
2633 \family typewriter
2634 Symbol
2635 \family default
2636 s (not the names of the locals: those are defined per method) and values
2637  to use.
2638 \end_layout
2640 \begin_layout Subsubsection
2641 Subjective Dispatch (currently disabled)
2642 \begin_inset OptArg
2643 status collapsed
2645 \begin_layout Standard
2646 Subjective Dispatch
2647 \end_layout
2649 \end_inset
2652 \end_layout
2654 \begin_layout Standard
2655 \begin_inset LatexCommand index
2656 name "dispatch, subjective"
2658 \end_inset
2661 \begin_inset LatexCommand index
2662 name "subjective dispatch"
2664 \end_inset
2666 The multiple dispatch system has an extended dynamic signature form which
2667  can be used to give a 
2668 \begin_inset Quotes eld
2669 \end_inset
2671 subjective
2672 \begin_inset Quotes erd
2673 \end_inset
2675  or 
2676 \begin_inset Quotes eld
2677 \end_inset
2679 layered
2680 \begin_inset Quotes erd
2681 \end_inset
2683  customization of the Slate environment.
2684  This is an implementation and slight modification of the Us
2685 \begin_inset LatexCommand index
2686 name "Us"
2688 \end_inset
2690  language features conceived of by the Self authors
2691 \begin_inset LatexCommand cite
2692 key "Subjective"
2694 \end_inset
2697 \end_layout
2699 \begin_layout Paragraph
2700 Basic mechanisms
2701 \end_layout
2703 \begin_layout Enumerate
2704 Slate dispatch signatures are 
2705 \begin_inset Quotes eld
2706 \end_inset
2708 enlarged
2709 \begin_inset Quotes erd
2710 \end_inset
2712  to support two implicit endpoints: one before the first argument and one
2713  after the last argument.
2714  We refer to the first role as an 
2715 \begin_inset Quotes eld
2716 \end_inset
2718 adviser
2719 \begin_inset Quotes erd
2720 \end_inset
2722  or 
2723 \family typewriter
2724 Layer
2725 \family default
2727 \begin_inset LatexCommand index
2728 name "Layer (object)"
2730 \end_inset
2732 , and to the second as a 
2733 \family typewriter
2734 Subject
2735 \begin_inset LatexCommand index
2736 name "Subject (object)"
2738 \end_inset
2741 \family default
2742  or 
2743 \begin_inset Quotes eld
2744 \end_inset
2746 interleaver
2747 \begin_inset Quotes erd
2748 \end_inset
2751  The layer role, being 
2752 \begin_inset Quotes eld
2753 \end_inset
2755 to the left
2756 \begin_inset Quotes erd
2757 \end_inset
2759  of the explicit argument positions, has higher precedence than any of them;
2760  the subject role has a correspondingly opposite role: it has the lowest
2761  precedence of all.
2762 \end_layout
2764 \begin_layout Enumerate
2765 \begin_inset LatexCommand index
2766 name "seenFrom: (message)"
2768 \end_inset
2770 Two primitive context-handling methods were added to support invoking code
2771  with a different object used for one of these new roles.
2772  What happens is that you execute a block 
2773 \family typewriter
2774 []\InsetSpace ~
2775 seenFrom:\InsetSpace ~
2776 someSubject
2777 \family default
2778  in order to make all methods defined within dispatched with that object
2779  as the subject, and all methods looked up in that context (or any other
2780  context 
2781 \begin_inset Quotes eld
2782 \end_inset
2784 seen from
2785 \begin_inset Quotes erd
2786 \end_inset
2788  that object) used with that subject in the dispatch.
2789 \end_layout
2791 \begin_layout Standard
2792 The effect of combining these two mechanisms is that there is a means for
2793  the user to dynamically (and transparently) extend existing libraries.
2794  The 
2795 \family typewriter
2796 Layer
2797 \family default
2798  usage has a more 
2799 \begin_inset Quotes eld
2800 \end_inset
2802 absolute
2803 \begin_inset Quotes erd
2804 \end_inset
2806  power to override, since without dispatching on any other arguments, a
2807  method defined in a layer will match a message before any other can.
2808  The 
2809 \family typewriter
2810 Subject
2811 \family default
2812  usage has a more fine-tuned (or weaker, in another sense) ability to override,
2813  since without any other dispatching, a method defined with a certain subject
2814  will never be called.
2815  However, taking an existing method's signature and defining a customized
2816  version with a subject will allow customizing that specific method without
2817  affecting any other method with that selector.
2818 \end_layout
2820 \begin_layout Paragraph
2821 Important features
2822 \end_layout
2824 \begin_layout Itemize
2825 Methods defined with a special subject or layer 
2826 \emph on
2827 persist
2828 \emph default
2829  with those objects, since they are just dispatch participants accessible
2830  via roles.
2831 \end_layout
2833 \begin_layout Itemize
2834 Resending messages works just the same within subjective methods as in normal
2835  methods; the same dispatch mechanism is in effect, so the ability to combine
2836  or extend functionality is available.
2837 \end_layout
2839 \begin_layout Itemize
2840 Nesting subjective scopes has a 
2841 \emph on
2842 dynamic scoping
2843 \emph default
2844  effect: the actions taken within have run-time scope instead of corresponding
2845  exactly to how code is lexically defined.
2846  This gives the compositional effect that should be apparent when viewing
2847  nested subjective scopes.
2848 \end_layout
2850 \begin_layout Itemize
2851 Methods defined in non-subjective contexts have no subject or layer rather
2852  than any 
2853 \begin_inset Quotes eld
2854 \end_inset
2856 default
2857 \begin_inset Quotes erd
2858 \end_inset
2860  subject: they are for most purposes, 
2861 \begin_inset Quotes eld
2862 \end_inset
2864 objective
2865 \begin_inset Quotes erd
2866 \end_inset
2869 \end_layout
2871 \begin_layout Paragraph
2872 The core elements
2873 \end_layout
2875 \begin_layout Description
2877 \family typewriter
2878 Subject
2879 \begin_inset LatexCommand index
2880 name "subject (terminology)"
2882 \end_inset
2885 \family default
2886  the type of object which provides an appropriate handle for subjective
2887  interleaving behavior in dynamically overriding or extending other methods'
2888  behaviors.
2889 \end_layout
2891 \begin_layout Description
2893 \family typewriter
2894 Layer
2895 \begin_inset LatexCommand index
2896 name "layer (terminology)"
2898 \end_inset
2901 \family default
2902  the type of object which provides an appropriate handle for subjective
2903  layering behavior in dynamically overriding or extending other methods'
2904  behaviors.
2905 \end_layout
2907 \begin_layout Description
2909 \family typewriter
2910 \begin_inset LatexCommand index
2911 name "seenFrom: (message)"
2913 \end_inset
2915 []\InsetSpace ~
2916 seenFrom:\InsetSpace ~
2917 aSubject
2918 \family default
2919  executes the contents of the block with the given 
2920 \family typewriter
2921 Subject
2922 \family default
2923  dynamically affecting the execution of the expressions.
2924 \end_layout
2926 \begin_layout Description
2928 \family typewriter
2929 \begin_inset LatexCommand index
2930 name "layering: (message)"
2932 \end_inset
2934 aLayer\InsetSpace ~
2935 layering:\InsetSpace ~
2937 \family default
2938  executes the contents of the block with the given 
2939 \family typewriter
2940 Layer
2941 \family default
2942  dynamically affecting the execution of the expressions.
2943 \end_layout
2945 \begin_layout Description
2947 \family typewriter
2948 \begin_inset LatexCommand index
2949 name "withoutSubject (message)"
2951 \end_inset
2953 []\InsetSpace ~
2954 withoutSubject
2955 \family default
2956  executes the contents of the block without any subject.
2957 \end_layout
2959 \begin_layout Description
2961 \family typewriter
2962 \begin_inset LatexCommand index
2963 name "withoutLayers (message)"
2965 \end_inset
2967 []\InsetSpace ~
2968 withoutLayers
2969 \family default
2970  executes the contents of the block without any layer.
2971 \end_layout
2973 \begin_layout Subsection
2974 Type Annotations
2975 \end_layout
2977 \begin_layout Standard
2978 \begin_inset LatexCommand index
2979 name "type annotations"
2981 \end_inset
2983 Input and local slots' types can be specified statically for performance
2984  or documentation reasons, if desired.
2985  The special character 
2986 \begin_inset LatexCommand index
2987 name "bang character"
2989 \end_inset
2992 \begin_inset LatexCommand index
2993 name "exclamation mark"
2995 \end_inset
2998 \begin_inset LatexCommand index
2999 name "\\char `\\! (exclamation mark)"
3001 \end_inset
3004 \begin_inset Quotes eld
3005 \end_inset
3008 \family typewriter
3010 \family default
3012 \begin_inset Quotes erd
3013 \end_inset
3015  is used in the same manner as the dispatch annotation 
3016 \begin_inset Quotes eld
3017 \end_inset
3020 \family typewriter
3022 \family default
3024 \begin_inset Quotes erd
3025 \end_inset
3027 , but type-annotations can occur anywhere.
3028  The type system and inference system in Slate is part of the standard library,
3029  and so is explained later in 
3030 \begin_inset LatexCommand vref
3031 reference "sub:Types"
3033 \end_inset
3037 \end_layout
3039 \begin_layout Subsection
3040 Macro Message-sends
3041 \end_layout
3043 \begin_layout Standard
3044 \begin_inset LatexCommand index
3045 name "macro message-sends"
3047 \end_inset
3050 \begin_inset LatexCommand index
3051 name "message-sends, macro"
3053 \end_inset
3055 In order to manipulate syntax trees or provide annotations on source code,
3056  Slate provides another form of message-send called a 
3057 \emph on
3058 macro-level
3059 \emph default
3060  message send.
3061  Sends of this sort have as their arguments the objects built for the expression
3062 s' shapes.
3063  Furthermore, the results of evaluation of macro-sends are placed in the
3064  syntax tree in the same location as the macro-send occupied.
3065 \end_layout
3067 \begin_layout Standard
3068 \begin_inset LatexCommand index
3069 name "` (back-tick)"
3071 \end_inset
3074 \begin_inset LatexCommand index
3075 name "back-tick"
3077 \end_inset
3079 Preceding any selector with a back-tick (
3080 \family typewriter
3082 \family default
3083 ) will cause it to be sent as a macro.
3084  This means that the message sent will be dispatched on Slate's 
3085 \family typewriter
3087 \begin_inset LatexCommand index
3088 name "Syntax Node (object)"
3090 \end_inset
3092 Syntax\InsetSpace ~
3093 Node
3094 \family default
3095  objects, which are produced by the parser and consumed by the compiler.
3096  Macros fit into the process of compiling in this order: the text is processed
3097  by the 
3098 \family typewriter
3099 Lexer
3100 \begin_inset LatexCommand index
3101 name "Lexer (object)"
3103 \end_inset
3106 \family default
3107  into a stream of tokens, which are consumed by the 
3108 \family typewriter
3109 Parser
3110 \begin_inset LatexCommand index
3111 name "Parser (object)"
3113 \end_inset
3116 \family default
3117  to produce a (tree-)stream of 
3118 \family typewriter
3119 Syntax\InsetSpace ~
3120 Node
3121 \family default
3123  Before being passed to the compiler, the 
3124 \family typewriter
3125 macroexpand
3126 \begin_inset LatexCommand index
3127 name "macroexpand (message)"
3129 \end_inset
3132 \family default
3133  method is recursively called on these syntax trees, which invokes every
3134  macro-level message-send and performs the mechanics of replacing the macro-send
3135  with the result of the method invoked.
3136  With this in mind, the Slate macro system is offered as a flexible communicatio
3137 n system between the code-writer and the compiler or other tools or even
3138  other users, using parse trees as the medium.
3139 \end_layout
3141 \begin_layout Standard
3142 As an example of the expressiveness of this system, we can express the type
3143  annotation and comment features of the Slate language in terms of macros:
3144 \end_layout
3146 \begin_layout Itemize
3147 Type-annotation via 
3148 \begin_inset Quotes eld
3149 \end_inset
3152 \family typewriter
3153 expression!type
3154 \family default
3156 \begin_inset Quotes erd
3157 \end_inset
3159  could be replaced by 
3160 \begin_inset Quotes eld
3161 \end_inset
3164 \family typewriter
3165 someExpression `type: assertedTypeExpression
3166 \family default
3168 \begin_inset Quotes erd
3169 \end_inset
3171  where the 
3172 \family typewriter
3173 `type:
3174 \family default
3175  macro simply sets the 
3176 \family typewriter
3177 type
3178 \family default
3179  slot for the expression object.
3180 \end_layout
3182 \begin_layout Itemize
3183 Comments could be applied specifically to particular expressions.
3184  For example, following a syntax element with a comment could be implemented
3185  by 
3186 \begin_inset Quotes eld
3187 \end_inset
3190 \family typewriter
3191 theExpression `comment: commentString
3192 \family default
3194 \begin_inset Quotes erd
3195 \end_inset
3197 , wrapping the syntax node with a comment annotation.
3198 \end_layout
3200 \begin_layout Itemize
3201 Compile-time evaluation of any expression can be accomplished by calling
3203 \family typewriter
3204 `evaluate
3205 \family default
3206  on it.
3207  This also subsumes the 
3208 \family typewriter
3210 \family default
3211 -prefix for array literals and expression sequences which accomplishes that
3212  for those syntax forms.
3213 \end_layout
3215 \begin_layout Subsubsection
3216 Defining new Macro-methods
3217 \end_layout
3219 \begin_layout Standard
3220 Macros must be dispatched (if at all) upon the traits of expressions' syntactic
3221  representation.
3222  This introduces a few difficulties, in that some familiarity is needed
3223  with the parse node types in order to name them.
3224  However, only two things need to be remembered:
3225 \end_layout
3227 \begin_layout Enumerate
3228 The generic syntax node type is 
3229 \family typewriter
3230 Syntax\InsetSpace ~
3231 Node\InsetSpace ~
3232 traits
3233 \family default
3234 , and this is usually all that is necessary for basic macro-methods.
3235 \end_layout
3237 \begin_layout Enumerate
3238 Syntax node types of various objects and specific expression types can be
3239  had by simply quoting them and asking for their traits, although this might
3240  be too specific in some cases.
3241  For example, 
3242 \family typewriter
3243 4\InsetSpace ~
3244 `quote\InsetSpace ~
3245 traits
3246 \family default
3247  is suitable for dispatching on Integers, but not Numbers in general, or
3249 \family typewriter
3250 (3\InsetSpace ~
3251 +\InsetSpace ~
3252 4)\InsetSpace ~
3253 `quote\InsetSpace ~
3254 traits
3255 \family default
3256  will help dispatch on binary message-sends, but not all message-sends.
3257  Luckily, 
3258 \family typewriter
3259 []\InsetSpace ~
3260 `quote\InsetSpace ~
3261 traits
3262 \family default
3263  works for blocks as well as methods.
3264 \end_layout
3266 \begin_layout Subsubsection
3267 Quoting and Unquoting
3268 \end_layout
3270 \begin_layout Standard
3271 \begin_inset LatexCommand index
3272 name "quoting"
3274 \end_inset
3277 \begin_inset LatexCommand index
3278 name "unquoting"
3280 \end_inset
3283 \begin_inset LatexCommand index
3284 name "`quote (message)"
3286 \end_inset
3289 \begin_inset LatexCommand index
3290 name "`unquote (message)"
3292 \end_inset
3294 A fundamental application of the macro message-send system is the ability
3295  to obtain syntax trees for any expression at run-time.
3296  The most basic methods for this are 
3297 \family typewriter
3298 `quote
3299 \family default
3300 , which causes the surrounding expression to use its quoted value as the
3301  input for even normal methods, and 
3302 \family typewriter
3303 `unquote
3304 \family default
3305  results in an inversion of the action of 
3306 \family typewriter
3307 `quote
3308 \family default
3309 , so it can only be provided within quoted expressions.
3310 \end_layout
3312 \begin_layout Standard
3313 An abbreviated form of quotation may be used by surrounding an expression
3314  with 
3315 \family typewriter
3317 \family default
3318  which has the same effect as sending 
3319 \family typewriter
3320 `quote
3321 \family default
3323  The parentheses may be omitted if the inner expression cannot be interpreted
3324  as a message-send (applicable to literal blocks, arrays, numbers, and so
3325  on).
3326 \begin_inset Foot
3327 status collapsed
3329 \begin_layout Standard
3330 Lisp macro system users will note that this effectively makes 
3331 \family typewriter
3332 `quote
3333 \family default
3334  the same as quasi-quotation.
3335 \end_layout
3337 \end_inset
3340 \end_layout
3342 \begin_layout Paragraph
3343 Labelled Quotation
3344 \end_layout
3346 \begin_layout Standard
3347 \begin_inset LatexCommand index
3348 name "quotation, labelled"
3350 \end_inset
3353 \begin_inset LatexCommand index
3354 name "labelled quotation"
3356 \end_inset
3358 In experience with Lisp macros, nested quotation is often found necessary.
3359  In order to adequately control this, often the quotation prefix symbols
3360  have to be combined in non-intuitive ways to produce the correct code.
3361  Slate includes, as an alternative, two operations which set a label on
3362  a quotation and can unquote within that to the original quotation by means
3363  of referencing the label.
3364 \end_layout
3366 \begin_layout Standard
3367 Most users need time to develop the understanding of the need for higher-order
3368  macros, and this relates to users who employ them.
3369  For reference, a Lisp book which covers the subject of higher-order macros
3370  better than any other is 
3371 \emph on
3372 On Lisp
3373 \emph default
3375 \begin_inset LatexCommand cite
3376 key "OnLisp"
3378 \end_inset
3381  However, it's also been said that Lisp's notation and the conceptual overhead
3382  required to manage the notation in higher-order macros keeps programmers
3383  from entering the field, so perhaps this new notation will help.
3384 \end_layout
3386 \begin_layout Standard
3387 \begin_inset LatexCommand index
3388 name "`quote: (message)"
3390 \end_inset
3393 \begin_inset LatexCommand index
3394 name "`unquote: (message)"
3396 \end_inset
3398 The operators are 
3399 \family typewriter
3400 expr1\InsetSpace ~
3401 `quote:\InsetSpace ~
3402 aLiteral
3403 \family default
3404  and 
3405 \family typewriter
3406 expr2\SpecialChar \-
3407 \InsetSpace ~
3408 `unquote:\SpecialChar \-
3409 \InsetSpace ~
3410 aLiteral
3411 \family default
3412 , and in order for this to work syntactically, the labels must be equal
3413  in value and must be literals.
3414  As well, the unquoting expression has to be a sub-expression of the quotation.
3415  The effect is that nesting an expression more deeply does not require altering
3416  the quotation operators to compensate, and it does indicate better what
3417  the unquoting is intended to do\SpecialChar \@.
3419 \end_layout
3421 \begin_layout Subsubsection
3422 Message Cascading
3423 \end_layout
3425 \begin_layout Standard
3426 \begin_inset LatexCommand index
3427 name "cascade, message"
3429 \end_inset
3432 \begin_inset LatexCommand index
3433 name "message cascading"
3435 \end_inset
3438 \begin_inset LatexCommand index
3439 name "`>> (macro)"
3441 \end_inset
3443 Many object-oriented code idioms involve repeated message-sends to the same
3444  object.
3445  This is common in creating and setting up a new object, or activating many
3446  behaviors in sequence on the same thing (used in a lot of UI code - or
3447  more generally with objects that have many variables or are "facade" objects).
3448  Take notice of the period after the last message in the block.
3449  If you forget, you'll return the last result instead of the original object
3450  your cascading into.
3451 \end_layout
3453 \begin_layout Standard
3454 Smalltalk-80 included a syntax feature to elide the first argument when
3455  repeating message-sends.
3456  In Slate, the first argument of a message send is not a special "receiver",
3457  so support in the basic syntax does not make sense.
3458  The solution is a macro-method which takes an expression (well, its result)
3459  and a block, and enhances the block so that the result of the expression
3460  becomes the implicit context for statement-level (top-level) message expression
3462  For example:
3463 \end_layout
3465 \begin_layout LyX-Code
3466 Slate> (addPrototype: #Something derivedFrom: {Cloneable})
3467 \newline
3468   `>> [addSlot:
3469  #foo.
3470  addSlot: #bar.
3471  ].
3472 \end_layout
3474 \begin_layout LyX-Code
3476 \end_layout
3478 \begin_layout LyX-Code
3479 ("Something traitsWindow" bar: Nil.
3480  foo: Nil)
3481 \end_layout
3483 \begin_layout Standard
3484 In this expression, a prototype is created and returned by the first expression,
3485  and the block is evaluated with that object substituted for the context,
3486  so that the 
3487 \family typewriter
3488 addSlot:
3489 \family default
3490  calls apply to it directly.
3491  We recommend you don't define things this way.
3492  Instead use 
3493 \family typewriter
3494 namespace define: #Something &parents: {Cloneable} &slots: {#foo -> Nil.
3495  #bar -> Nil }.
3496 \end_layout
3498 \begin_layout Standard
3499 There is an additional possibility that it takes care of by allowing the
3500  user to specify an input variable to the block, which will also allow the
3501  code within to refer to the object explicitly.
3502  Also, the default return value for empty-last-statements is modified to
3503  be this object instead of the usual 
3504 \family typewriter
3506 \family default
3508  Without such features, a method which returns its only argument is needed;
3509  in Smalltalk-80, the 
3510 \family typewriter
3511 yourself
3512 \family default
3513  method performs this role at the end of a cascade.
3514  To see the effect this would have on Slate library code, take a collection
3515  creation method as an example:
3516 \end_layout
3518 \begin_layout LyX-Code
3519 set@(Set traits) new &capacity: n
3520 \newline
3521 [| newSet |
3522 \newline
3523   newSet: set clone.
3524 \newline
3525   newSet
3526  contents: (set contents new &capacity: ((n ifNil: [0]) max: 1)).
3527 \newline
3528   newSet
3529  tally: 0.
3530 \newline
3531   newSet
3532 \newline
3534 \end_layout
3536 \begin_layout Standard
3537 could become:
3538 \end_layout
3540 \begin_layout LyX-Code
3541 set@(Set traits) new &capacity: n
3542 \newline
3543 [set clone `>>
3544 \newline
3545   [contents: (set contents
3546  new &capacity: ((n ifNil: [0]) max: 1)).
3547 \newline
3548   tally: 0.
3550 \newline
3552 \end_layout
3554 \begin_layout Standard
3555 So in this new method, an object is made by cloning the argument 
3556 \family typewriter
3558 \family default
3559 , and then the contents and tally are assigned as before, but not needing
3560  to refer to the object explicitly, and then returning the object (if the
3561  ending period is left off, it'll return the value of the last explicit
3562  expression, just as normal blocks).
3563  However, the message-sends which are not leading a statement do not (and
3564  cannot) use the object as implicit context.
3565  This is intentional, as the results of this kind of pervasive change are
3566  more drastic and would be an entirely different kind of idiom.
3567  If a reference to the implicit context argument is needed in the block,
3568  an input argument may be specified in the block header, and the macro method
3569  will bind it to that object.
3570  A notable property of the 
3571 \family typewriter
3573 \family default
3574  method, since it returns resulting values and has a binary selector, is
3575  composability in a data-flow manner.
3576 \end_layout
3578 \begin_layout Subsubsection
3579 Slots as Block Variables
3580 \end_layout
3582 \begin_layout Standard
3583 \begin_inset LatexCommand index
3584 name "`withSlotsDo: (macro)"
3586 \end_inset
3588 Another macro allows for the slots of an object to appear as local variables
3589  in a method, responding both to accessors and mutators in the appropriate
3590  way (by modifying the object's slots).
3591 \end_layout
3593 \begin_layout Standard
3594 So, the following expression names some slots in the first argument which
3595  should be available as inputs to the second argument, a block.
3596  This is analogous to having Smalltalk's direct slot reference syntax (or
3597  Self's, for that matter), or to Lisp's with-slots macro.
3598  (Again, you shouldn't generally shouldn't create objects this way.)
3599 \end_layout
3601 \begin_layout LyX-Code
3602 Slate> Cloneable clone 
3603 \newline
3604   `>> [addSlot: #x valued: 2.
3605  addSlot: #y valued: 2]
3606 \newline
3607   `withSlotsDo: [| :x :y | x + y].
3609 \newline
3611 \end_layout
3613 \begin_layout Subsubsection
3614 Expression Substitution (Not Yet Implemented)
3615 \begin_inset OptArg
3616 status open
3618 \begin_layout Standard
3619 Expression Substitution
3620 \end_layout
3622 \end_inset
3625 \end_layout
3627 \begin_layout Standard
3629 \family typewriter
3630 \begin_inset LatexCommand index
3631 name "`with:as: (message)"
3633 \end_inset
3635 `with:as:
3636 \family default
3637  is a proposed protocol for transparent substitution of temporary or locally-pro
3638 vided proxies for environment values and other system elements.
3639  This should provide an effective correspondent of the functionality of
3640  Lisp's "
3641 \family typewriter
3642 with-
3643 \family default
3644 " style macros.
3645 \end_layout
3647 \begin_layout Subsubsection
3648 Source Pattern-matching (Not Yet Implemented)
3649 \begin_inset OptArg
3650 status collapsed
3652 \begin_layout Standard
3653 Source Pattern Matching
3654 \end_layout
3656 \end_inset
3659 \end_layout
3661 \begin_layout Standard
3662 \begin_inset LatexCommand index
3663 name "pattern-matching"
3665 \end_inset
3667 A future framework for expansion will involve accommodating the types of
3668  source-level pattern-matching used in tools for manipulating code for developme
3669 nt, as in the Smalltalk Refactoring Browser.
3670 \end_layout
3672 \begin_layout Subsection
3673 Literal Syntax
3674 \begin_inset OptArg
3675 status collapsed
3677 \begin_layout Standard
3678 Literals
3679 \end_layout
3681 \end_inset
3684 \begin_inset LatexCommand index
3685 name "literal syntax"
3687 \end_inset
3690 \begin_inset LatexCommand index
3691 name "syntax, literal"
3693 \end_inset
3696 \end_layout
3698 \begin_layout Subsubsection
3699 Numbers
3700 \end_layout
3702 \begin_layout Paragraph
3703 Integers
3704 \end_layout
3706 \begin_layout Standard
3707 Integers are read in as an arbitrary-precision sequence of digits, without
3708  separators.
3709 \end_layout
3711 \begin_layout Paragraph
3712 Floats
3713 \end_layout
3715 \begin_layout Standard
3716 Floats are read in as an arbitrary-precision sequence of digits, with a
3717  period noting the decimal position.
3718 \end_layout
3720 \begin_layout Paragraph
3721 Radix Prefixes
3722 \end_layout
3724 \begin_layout Standard
3725 Integers or Floats may be entered with radix up to 36, using the digits
3726  0 to 9 and then A to Z in order, by prefixing the literal with the radix
3727  (numeric base) and '
3728 \family typewriter
3730 \family default
3732  So 
3733 \family typewriter
3734 3r100
3735 \family default
3736  evaluates to 9, and 
3737 \family typewriter
3738 2r0.1
3739 \family default
3740  evaluates to 
3741 \family typewriter
3743 \family default
3745  Case is disregarded for the extra-decimal digits.
3746  The Float radix notation is always read in as a Float, and not an infinite-prec
3747 ision Fraction.
3748 \end_layout
3750 \begin_layout Subsubsection
3751 Characters
3752 \end_layout
3754 \begin_layout Standard
3755 \begin_inset LatexCommand index
3756 name "characters"
3758 \end_inset
3761 \begin_inset LatexCommand index
3762 name "dollar sign"
3764 \end_inset
3767 \begin_inset LatexCommand index
3768 name "\\$ (dollar sign)"
3770 \end_inset
3772 Slate's default support for character literals uses the 
3773 \family typewriter
3775 \family default
3776  symbol as a prefix.
3777  For example, 
3778 \family typewriter
3780 \family default
3782 \family typewriter
3784 \family default
3786 \family typewriter
3788 \family default
3789 , and 
3790 \family typewriter
3792 \family default
3793  are all Character object literals for 
3794 \family typewriter
3796 \family default
3798 \family typewriter
3800 \family default
3802 \family typewriter
3804 \family default
3805 , and 
3806 \family typewriter
3808 \family default
3809 , respectively.
3810  Printable and non-printable characters require backslash escapes as shown
3811  and listed in Table 
3812 \begin_inset LatexCommand vref
3813 reference "cap:Character-Literal-Escapes"
3815 \end_inset
3818 \end_layout
3820 \begin_layout Standard
3821 \align center
3822 \begin_inset LatexCommand index
3823 name "characters, special"
3825 \end_inset
3828 \begin_inset LatexCommand index
3829 name "special characters"
3831 \end_inset
3834 \begin_inset LatexCommand index
3835 name "escape (character literal)"
3837 \end_inset
3840 \begin_inset LatexCommand index
3841 name "newline (character literal)"
3843 \end_inset
3846 \begin_inset LatexCommand index
3847 name "carriage return (character literal)"
3849 \end_inset
3852 \begin_inset LatexCommand index
3853 name "tab (character literal)"
3855 \end_inset
3858 \begin_inset LatexCommand index
3859 name "backspace (character literal)"
3861 \end_inset
3864 \begin_inset LatexCommand index
3865 name "null (character literal)"
3867 \end_inset
3870 \begin_inset LatexCommand index
3871 name "bell (character literal)"
3873 \end_inset
3876 \begin_inset LatexCommand index
3877 name "form feed (character literal)"
3879 \end_inset
3882 \begin_inset LatexCommand index
3883 name "vertical feed (character literal)"
3885 \end_inset
3888 \begin_inset LatexCommand index
3889 name "space (character literal)"
3891 \end_inset
3894 \begin_inset LatexCommand index
3895 name "backslash (character literal)"
3897 \end_inset
3900 \begin_inset Float table
3901 placement h
3902 wide false
3903 sideways false
3904 status open
3906 \begin_layout Standard
3907 \align center
3908 \begin_inset Tabular
3909 <lyxtabular version="3" rows="12" columns="2">
3910 <features>
3911 <column alignment="center" valignment="top" leftline="true" width="0pt">
3912 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
3913 <row topline="true" bottomline="true">
3914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3915 \begin_inset Text
3917 \begin_layout Standard
3918 Character name
3919 \end_layout
3921 \end_inset
3922 </cell>
3923 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3924 \begin_inset Text
3926 \begin_layout Standard
3927 Literal
3928 \end_layout
3930 \end_inset
3931 </cell>
3932 </row>
3933 <row topline="true">
3934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3935 \begin_inset Text
3937 \begin_layout Standard
3938 Escape
3939 \end_layout
3941 \end_inset
3942 </cell>
3943 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3944 \begin_inset Text
3946 \begin_layout Standard
3948 \family typewriter
3950 \backslash
3952 \end_layout
3954 \end_inset
3955 </cell>
3956 </row>
3957 <row topline="true">
3958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3959 \begin_inset Text
3961 \begin_layout Standard
3962 Newline
3963 \end_layout
3965 \end_inset
3966 </cell>
3967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3968 \begin_inset Text
3970 \begin_layout Standard
3972 \family typewriter
3974 \backslash
3976 \end_layout
3978 \end_inset
3979 </cell>
3980 </row>
3981 <row topline="true">
3982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
3983 \begin_inset Text
3985 \begin_layout Standard
3986 Carriage Return
3987 \end_layout
3989 \end_inset
3990 </cell>
3991 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
3992 \begin_inset Text
3994 \begin_layout Standard
3996 \family typewriter
3998 \backslash
4000 \end_layout
4002 \end_inset
4003 </cell>
4004 </row>
4005 <row topline="true">
4006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4007 \begin_inset Text
4009 \begin_layout Standard
4011 \end_layout
4013 \end_inset
4014 </cell>
4015 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4016 \begin_inset Text
4018 \begin_layout Standard
4020 \family typewriter
4022 \backslash
4024 \end_layout
4026 \end_inset
4027 </cell>
4028 </row>
4029 <row topline="true">
4030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4031 \begin_inset Text
4033 \begin_layout Standard
4034 Backspace
4035 \end_layout
4037 \end_inset
4038 </cell>
4039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4040 \begin_inset Text
4042 \begin_layout Standard
4044 \family typewriter
4046 \backslash
4048 \end_layout
4050 \end_inset
4051 </cell>
4052 </row>
4053 <row topline="true">
4054 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4055 \begin_inset Text
4057 \begin_layout Standard
4058 Null
4059 \end_layout
4061 \end_inset
4062 </cell>
4063 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4064 \begin_inset Text
4066 \begin_layout Standard
4068 \family typewriter
4070 \backslash
4072 \end_layout
4074 \end_inset
4075 </cell>
4076 </row>
4077 <row topline="true">
4078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4079 \begin_inset Text
4081 \begin_layout Standard
4082 Bell
4083 \end_layout
4085 \end_inset
4086 </cell>
4087 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4088 \begin_inset Text
4090 \begin_layout Standard
4092 \family typewriter
4094 \backslash
4096 \end_layout
4098 \end_inset
4099 </cell>
4100 </row>
4101 <row topline="true">
4102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4103 \begin_inset Text
4105 \begin_layout Standard
4106 Form Feed
4107 \end_layout
4109 \end_inset
4110 </cell>
4111 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4112 \begin_inset Text
4114 \begin_layout Standard
4116 \family typewriter
4118 \backslash
4120 \end_layout
4122 \end_inset
4123 </cell>
4124 </row>
4125 <row topline="true">
4126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4127 \begin_inset Text
4129 \begin_layout Standard
4130 Vertical Feed
4131 \end_layout
4133 \end_inset
4134 </cell>
4135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4136 \begin_inset Text
4138 \begin_layout Standard
4140 \family typewriter
4142 \backslash
4144 \end_layout
4146 \end_inset
4147 </cell>
4148 </row>
4149 <row topline="true">
4150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4151 \begin_inset Text
4153 \begin_layout Standard
4154 Space
4155 \end_layout
4157 \end_inset
4158 </cell>
4159 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4160 \begin_inset Text
4162 \begin_layout Standard
4164 \family typewriter
4166 \backslash
4168 \end_layout
4170 \end_inset
4171 </cell>
4172 </row>
4173 <row topline="true" bottomline="true">
4174 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4175 \begin_inset Text
4177 \begin_layout Standard
4178 Backslash
4179 \end_layout
4181 \end_inset
4182 </cell>
4183 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
4184 \begin_inset Text
4186 \begin_layout Standard
4188 \family typewriter
4190 \backslash
4192 \backslash
4194 \end_layout
4196 \end_inset
4197 </cell>
4198 </row>
4199 </lyxtabular>
4201 \end_inset
4204 \end_layout
4206 \begin_layout Standard
4207 \begin_inset Caption
4209 \begin_layout Standard
4210 \begin_inset LatexCommand label
4211 name "cap:Character-Literal-Escapes"
4213 \end_inset
4215 Character Literal Escapes
4216 \end_layout
4218 \end_inset
4221 \end_layout
4223 \end_inset
4226 \end_layout
4228 \begin_layout Subsubsection
4229 Strings
4230 \end_layout
4232 \begin_layout Standard
4233 \begin_inset LatexCommand index
4234 name "strings"
4236 \end_inset
4239 \begin_inset LatexCommand index
4240 name "quotes, single"
4242 \end_inset
4245 \begin_inset LatexCommand index
4246 name "single quotes"
4248 \end_inset
4251 \begin_inset LatexCommand index
4252 name "' (single quote)"
4254 \end_inset
4256 Strings are comprised of any sequence of characters surrounded by single-quote
4257  characters.
4258  Strings can include the commenting character (double-quotes) without an
4259  escape.
4260  Embedded single-quotes can be provided by using the backslash character
4261  to escape them (
4262 \family typewriter
4264 \backslash
4266 \family default
4268  Slate's character literal syntax also embeds into string literals, omitting
4269  the 
4270 \family typewriter
4272 \family default
4273  prefix.
4274  All characters that require escapes in character literal syntax also require
4275  escapes when used within string literals, with the exception of double-quote
4276  marks and the addition of single-quote marks.
4277 \end_layout
4279 \begin_layout Standard
4280 The following are all illustrative examples of Strings in Slate:
4281 \end_layout
4283 \begin_layout LyX-Code
4284 'a string comprises any sequence of characters, surrounded by single quotes'
4285 \end_layout
4287 \begin_layout LyX-Code
4288 'strings can include the "comment delimiting" character'
4289 \end_layout
4291 \begin_layout LyX-Code
4292 'and strings can include embedded single quote characters by escaping
4293 \backslash
4294 ' them'
4295 \end_layout
4297 \begin_layout LyX-Code
4298 'strings can contain embedded
4299 \end_layout
4301 \begin_layout LyX-Code
4302 newline characters'
4303 \end_layout
4305 \begin_layout LyX-Code
4306 'and escaped 
4307 \backslash
4308 ncharacters'
4309 \end_layout
4311 \begin_layout LyX-Code
4313 \begin_inset ERT
4314 status inlined
4316 \begin_layout Standard
4319 \end_layout
4321 \end_inset
4323 ' "and don't forget the empty string"
4324 \end_layout
4326 \begin_layout Subsubsection
4327 Symbols
4328 \end_layout
4330 \begin_layout Standard
4331 \begin_inset LatexCommand index
4332 name "symbols"
4334 \end_inset
4337 \begin_inset LatexCommand index
4338 name "pound sign"
4340 \end_inset
4343 \begin_inset LatexCommand index
4344 name "\\# (pound sign)"
4346 \end_inset
4349 \family typewriter
4350 Symbol
4351 \family default
4352  literal syntax starts with the pound sign character (
4353 \family typewriter
4355 \family default
4356 ) and consists of all following characters up to the next non-escaped whitespace
4357  or reserved character (whichever comes first), unless the pound sign is
4358  followed exactly by a string literal (in single quotes), in which case
4359  the string's contents become the identifier for the 
4360 \family typewriter
4361 Symbol
4362 \family default
4364  So, for example, the following are all valid 
4365 \family typewriter
4366 Symbol
4367 \family default
4368 s and 
4369 \family typewriter
4370 Symbol
4371 \family default
4372  literals:
4373 \end_layout
4375 \begin_layout LyX-Code
4377 \end_layout
4379 \begin_layout LyX-Code
4381 \end_layout
4383 \begin_layout LyX-Code
4385 \end_layout
4387 \begin_layout LyX-Code
4388 #key:word:expression:
4389 \end_layout
4391 \begin_layout LyX-Code
4392 #something_with_underscores
4393 \end_layout
4395 \begin_layout LyX-Code
4396 #'A full string with a 
4397 \backslash
4398 nnewline in it.'
4399 \end_layout
4401 \begin_layout LyX-Code
4402 #'@'
4403 \end_layout
4405 \begin_layout Standard
4406 A property of 
4407 \family typewriter
4408 Symbols
4409 \family default
4410  and their literals is that any literal with the same value as another also
4411  refers to the 
4412 \emph on
4413 same instance
4414 \emph default
4415  as any other 
4416 \family typewriter
4417 Symbol
4418 \family default
4419  literal with that value in a Slate system.
4420  This allows fast hashes and comparisons by identity rather than value hashes.
4421  In particular, as with Slate identifiers, a 
4422 \family typewriter
4423 Symbol
4424 \family default
4425 's value is case-sensitive, so 
4426 \family typewriter
4428 \family default
4429  and 
4430 \family typewriter
4432 \family default
4433  are distinct.
4434 \end_layout
4436 \begin_layout Standard
4437 Internally, Slate currently keeps one global table for 
4438 \family typewriter
4439 Symbol
4440 \family default
4441 s, and uses individual context objects to hold local bindings.
4442 \begin_inset Foot
4443 status open
4445 \begin_layout Standard
4446 Future, bootstrapped releases may provide for partitioning of the global
4447  table.
4448 \end_layout
4450 \end_inset
4453 \end_layout
4455 \begin_layout Subsubsection
4456 Arrays
4457 \end_layout
4459 \begin_layout Standard
4460 \begin_inset LatexCommand index
4461 name "arrays"
4463 \end_inset
4466 \begin_inset LatexCommand index
4467 name "literal arrays"
4469 \end_inset
4472 \begin_inset LatexCommand index
4473 name "curly braces"
4475 \end_inset
4478 \begin_inset LatexCommand index
4479 name "\\{\\} (curly braces)"
4481 \end_inset
4483 Arrays can be literally and recursively specified by curly-brace notation
4484  using stops as separators.
4486 \begin_inset LatexCommand index
4487 name "array indices"
4489 \end_inset
4492 \begin_inset LatexCommand index
4493 name "indices, array"
4495 \end_inset
4497 Array indices in Slate are 0-based.
4498  So:
4499 \end_layout
4501 \begin_layout LyX-Code
4503  5.
4504  {foo.
4505  bar}}.
4506 \end_layout
4508 \begin_layout Standard
4509 returns an array with 4 in position 0, 5 at 1, and an array with objects
4511 \family typewriter
4513 \family default
4514  and 
4515 \family typewriter
4517 \family default
4518  inserted into it at position 2.
4519 \end_layout
4521 \begin_layout Standard
4522 \begin_inset LatexCommand index
4523 name "array syntax, immediate"
4525 \end_inset
4528 \begin_inset LatexCommand index
4529 name "immediate array syntax"
4531 \end_inset
4534 \begin_inset LatexCommand index
4535 name "pound sign"
4537 \end_inset
4540 \begin_inset LatexCommand index
4541 name "\\# (pound sign)"
4543 \end_inset
4545 Immediate array syntax - 
4546 \family typewriter
4547 #{4.\InsetSpace ~
4548 5.\InsetSpace ~
4549 {foo.\InsetSpace ~
4550 bar}}
4551 \family default
4552  - is provided as an alternative to create the array when the method is
4553  compiled, instead of creating a new array on each method invocation.
4554  The syntax is identical except that the first opening brace is preceded
4555  by the pound sign.
4556  The disadvantage is that no run-time values will be usable.
4557 \end_layout
4559 \begin_layout Standard
4560 \begin_inset LatexCommand index
4561 name "array syntax, literal"
4563 \end_inset
4566 \begin_inset LatexCommand index
4567 name "literal array syntax"
4569 \end_inset
4572 \begin_inset LatexCommand index
4573 name "() (parentheses)"
4575 \end_inset
4578 \begin_inset LatexCommand index
4579 name "parentheses"
4581 \end_inset
4583 A special 
4584 \begin_inset Quotes eld
4585 \end_inset
4587 literal array
4588 \begin_inset Quotes erd
4589 \end_inset
4591  syntax is also provided, in the manner of Smalltalk-80,
4592 \begin_inset LatexCommand index
4593 name "Smalltalk"
4595 \end_inset
4597  in which all tokens within are treated symbolically, evaluating to an array
4598  of literals as read (but not evaluated) by Slate.
4599  Naturally, these are all evaluated when the surrounding context is compiled.
4600  For example:
4601 \end_layout
4603 \begin_layout LyX-Code
4604 Slate> #(1 2 3).
4605 \newline
4607 \emph on
4609  2.
4610  3}
4611 \emph default
4613 \newline
4614 Slate> #(3 + 4).
4615 \newline
4617 \emph on
4619  #'+'.
4620  4}
4621 \emph default
4623 \newline
4624 Slate> #(quux: a :bar).
4625 \newline
4627 \emph on
4628 {#quux:.
4629  #a.
4630  #:bar}
4631 \emph default
4633 \newline
4634 Slate> #(1 .
4635  _ 2e3).
4636 \newline
4638 \emph on
4640  #'.'.
4641  #_.
4642  2000.0}
4643 \end_layout
4645 \begin_layout Subsubsection
4646 Blocks
4647 \end_layout
4649 \begin_layout Standard
4650 \begin_inset LatexCommand index
4651 name "blocks"
4653 \end_inset
4656 \begin_inset LatexCommand index
4657 name "square brackets"
4659 \end_inset
4662 \begin_inset LatexCommand index
4663 name "[] (square brackets)"
4665 \end_inset
4667 Block syntax basics were covered in 
4668 \begin_inset LatexCommand ref
4669 reference "sub:Block-Closures"
4671 \end_inset
4673 ; the precise, full specification includes more features and outlines some
4674  necessary logical rules.
4675  Primarily, blocks are square-bracket-delimited statement sequences with
4676  an optional header that specifies input and local slots (input slots being
4678 \emph on
4679 arguments
4680 \emph default
4682 \end_layout
4684 \begin_layout Standard
4685 \begin_inset LatexCommand index
4686 name "colon character"
4688 \end_inset
4691 \begin_inset LatexCommand index
4692 name ": (colon)"
4694 \end_inset
4696 Slot names must be valid unary message selectors (see 
4697 \begin_inset LatexCommand ref
4698 reference "sub:Unary-Message-sends"
4700 \end_inset
4703  Inputs are distinguished by a prefix colon character (
4704 \family typewriter
4706 \family default
4707 ), and must occur in the same positional order that the invocation will
4708  use or expect, although they can be interspersed among other slot declarations
4709  at will.
4710 \end_layout
4712 \begin_layout Standard
4713 \begin_inset LatexCommand index
4714 name "optional keyword arguments"
4716 \end_inset
4719 \begin_inset LatexCommand index
4720 name "arguments, optional keyword"
4722 \end_inset
4725 \begin_inset LatexCommand index
4726 name "keyword arguments, optional"
4728 \end_inset
4731 \begin_inset LatexCommand index
4732 name "\\& (ampersand)"
4734 \end_inset
4737 \begin_inset LatexCommand index
4738 name "ampersand"
4740 \end_inset
4742 Optional keyword arguments are specified with an ampersand prefix character
4744 \family typewriter
4746 \family default
4747 ), and may occur in any order.
4748 \end_layout
4750 \begin_layout Standard
4751 For example,
4752 \end_layout
4754 \begin_layout LyX-Code
4755 [| x :y &z :w | ]
4756 \end_layout
4758 \begin_layout Standard
4759 evaluates to a block which takes inputs 
4760 \family typewriter
4762 \family default
4763  and 
4764 \family typewriter
4766 \family default
4767  in that order, has locals 
4768 \family typewriter
4770 \family default
4771  (and 
4772 \family typewriter
4774 \family default
4775 ), and takes an optional parameter to specify 
4776 \family typewriter
4778 \family default
4779 's value when called.
4780 \end_layout
4782 \begin_layout Standard
4783 \begin_inset LatexCommand index
4784 name "rest arguments"
4786 \end_inset
4789 \begin_inset LatexCommand index
4790 name "arguments, rest"
4792 \end_inset
4795 \begin_inset LatexCommand index
4796 name "\\* (asterisk)"
4798 \end_inset
4801 \begin_inset LatexCommand index
4802 name "asterisk"
4804 \end_inset
4806 A single 
4807 \begin_inset Quotes eld
4808 \end_inset
4810 rest
4811 \begin_inset Quotes erd
4812 \end_inset
4814  parameter which becomes an array containing all extra positional (non-keyword)
4815  arguments passed may be specified once in the header in any position relative
4816  to the other parameters, prefixed with an asterisk (e.g.
4818 \family typewriter
4819 *rest
4820 \family default
4822 \end_layout
4824 \begin_layout Standard
4825 \begin_inset LatexCommand index
4826 name "compile-time blocks"
4828 \end_inset
4831 \begin_inset LatexCommand index
4832 name "blocks, compile-time"
4834 \end_inset
4837 \begin_inset LatexCommand index
4838 name "\\#[] (pound-square brackets)"
4840 \end_inset
4842 Blocks may be used to perform arbitrary compile-time calculations, using
4843  the 
4844 \family typewriter
4846 \family default
4847 -prefix as used for literal arrays and strings.
4848  So 
4849 \family typewriter
4850 #[3\InsetSpace ~
4851 +\InsetSpace ~
4853 \family default
4854  will result in 
4855 \family typewriter
4857 \family default
4858  in the resulting code for the surrounding context (perhaps a method or
4859  top-level expression), as though the block were never there.
4860 \end_layout
4862 \begin_layout Section
4863 The Slate World
4864 \end_layout
4866 \begin_layout Subsection
4867 Overall Organization
4868 \end_layout
4870 \begin_layout Subsubsection
4871 The lobby
4872 \end_layout
4874 \begin_layout Standard
4875 \begin_inset LatexCommand index
4876 name "lobby (object)"
4878 \end_inset
4881 \begin_inset LatexCommand index
4882 name "objects, global"
4884 \end_inset
4887 \begin_inset LatexCommand index
4888 name "global objects"
4890 \end_inset
4892 The 
4893 \family typewriter
4894 lobby
4895 \family default
4896  is the root namespace object for the Slate object system; it is the 
4897 \begin_inset Quotes eld
4898 \end_inset
4900 room
4901 \begin_inset Quotes erd
4902 \end_inset
4904  by which objects enter the Slate world.
4905  All 
4906 \begin_inset Quotes eld
4907 \end_inset
4909 global
4910 \begin_inset Quotes erd
4911 \end_inset
4913  objects are really only globally accessible because the lobby is delegated
4914  to by lexical contexts, directly or indirectly.
4915  The lobby in turn may (and often does) delegate to other namespaces which
4916  contain different categorized objects of interest to the applications programme
4917 r, and this can be altered at run-time.
4918 \end_layout
4920 \begin_layout Standard
4921 Every object reference which is not local to a block closure is sent to
4922  the enclosing namespace for resolution, which by default is the root namespace,
4923  the 
4924 \family typewriter
4925 lobby
4926 \family default
4927  (nested closures refer first to their surrounding closure).
4929 \begin_inset LatexCommand index
4930 name "lobby (slot)"
4932 \end_inset
4934 The 
4935 \family typewriter
4936 lobby
4937 \family default
4938  contains a loopback slot referring to itself by that name.
4939  To add or arrange globals, either implicit sends or explicit references
4940  to the lobby can be made.
4941  (Consider it good style to directly reference it.)
4942 \end_layout
4944 \begin_layout Standard
4945 The lobby is essentially a threading context, and in the future bootstrap
4946  will be instantiable in that sense.
4947 \end_layout
4949 \begin_layout Subsubsection
4950 Naming and Paths
4951 \end_layout
4953 \begin_layout Standard
4954 The 
4955 \family typewriter
4956 lobby
4957 \family default
4958  provides access to the major 
4959 \family typewriter
4960 Namespaces
4961 \family default
4963 \begin_inset LatexCommand index
4964 name "Namespace (object)"
4966 \end_inset
4968 , which are objects suitable for organizing things (for now, they are essentiall
4969 y just 
4970 \family typewriter
4971 Cloneable
4972 \family default
4973  objects).
4974  The most important one is 
4975 \family typewriter
4976 prototypes
4977 \family default
4979 \begin_inset LatexCommand index
4980 name "prototypes (object)"
4982 \end_inset
4984 , which contains the major kinds of shared behavior used by the system.
4985  Objects there may be cloned and used directly, but they should not themselves
4986  be manipulated without some design effort, since these are global resources,
4987  having a name-path identifier which can be freely shared.
4989 \family typewriter
4990 prototypes
4991 \family default
4992  is inherited by the lobby, so it is not necessary to use the namespace
4993  path to identify, for example, 
4994 \family typewriter
4995 Collection
4996 \family default
4997  or 
4998 \family typewriter
4999 Boolean
5000 \family default
5002  However, without explicitly mentioning the path, adding slots will use
5003  the lobby or the local context by default.
5004  To use the current namespace, an implicit-context message 
5005 \family typewriter
5006 here
5007 \begin_inset LatexCommand index
5008 name "here (message)"
5010 \end_inset
5013 \family default
5014  is provided which will answer the nearest surrounding namespace object
5015  in the context, which is the 
5016 \family typewriter
5017 lobby
5018 \family default
5019  by default, but is polymorphic to namespace shifts.
5020 \end_layout
5022 \begin_layout Standard
5023 The 
5024 \family typewriter
5025 prototypes
5026 \family default
5027  namespace further contains inherited namespaces for, by example, collections,
5028  and can be otherwise enhanced to divide up the system into manageable pieces.
5029 \end_layout
5031 \begin_layout Subsection
5032 Core Behaviors
5033 \end_layout
5035 \begin_layout Standard
5036 \begin_inset Float figure
5037 placement htbp
5038 wide true
5039 sideways false
5040 status open
5042 \begin_layout Standard
5043 \begin_inset VSpace defskip
5044 \end_inset
5047 \end_layout
5049 \begin_layout Standard
5050 \align center
5051 \begin_inset Graphics
5052         filename core-web.eps
5054 \end_inset
5057 \end_layout
5059 \begin_layout Standard
5060 \begin_inset VSpace defskip
5061 \end_inset
5064 \end_layout
5066 \begin_layout Standard
5067 \begin_inset Caption
5069 \begin_layout Standard
5070 \begin_inset LatexCommand label
5071 name "cap:Core-delegation"
5073 \end_inset
5075 Core Object Inheritance
5076 \end_layout
5078 \end_inset
5081 \end_layout
5083 \end_inset
5086 \end_layout
5088 \begin_layout Standard
5089 Slate defines several subtle variations on the core behavior of objects:
5090 \end_layout
5092 \begin_layout Description
5094 \family typewriter
5095 Root
5096 \begin_inset LatexCommand index
5097 name "Root (object)"
5099 \end_inset
5102 \family default
5103  The "root" object, upon which all the very basic methods of slot manipulation
5104  are defined.
5105 \end_layout
5107 \begin_layout Description
5109 \family typewriter
5110 Oddball
5111 \begin_inset LatexCommand index
5112 name "Oddball (object)"
5114 \end_inset
5117 \family default
5118  The branch of 
5119 \family typewriter
5120 Root
5121 \family default
5122  representing non-cloneable objects.
5123  These include built-in 'constants' such as the 
5124 \family typewriter
5125 Boolean
5126 \family default
5127 s, as well as literals (value-objects) such as 
5128 \family typewriter
5129 Character
5130 \family default
5131 s and 
5132 \family typewriter
5133 Symbol
5134 \family default
5136  Note that 
5137 \family typewriter
5138 Oddball
5139 \family default
5140  itself defines a 
5141 \family typewriter
5142 clone
5143 \begin_inset LatexCommand index
5144 name "clone (message)"
5146 \end_inset
5149 \family default
5150  method, but that method will only work once, in that you can clone 
5151 \family typewriter
5152 Oddball
5153 \family default
5154  but not objects made by cloning 
5155 \family typewriter
5156 Oddball
5157 \family default
5159 \end_layout
5161 \begin_layout Description
5163 \family typewriter
5165 \begin_inset LatexCommand index
5166 name "Nil (object)"
5168 \end_inset
5171 \family default
5173 \family typewriter
5175 \family default
5176  is an 
5177 \family typewriter
5178 Oddball
5179 \family default
5180  representing "no-object".
5181 \end_layout
5183 \begin_layout Description
5185 \family typewriter
5186 NoRole
5187 \begin_inset LatexCommand index
5188 name "NoRole (object)"
5190 \end_inset
5193 \family default
5195 \family typewriter
5196 NoRole
5197 \family default
5198  is an 
5199 \family typewriter
5200 Oddball
5201 \family default
5202  representing a non-dispatching participant in a method definition.
5203  Methods cannot be defined directly on 
5204 \family typewriter
5205 NoRole
5206 \family default
5208 \end_layout
5210 \begin_layout Description
5212 \family typewriter
5213 Derivable
5214 \begin_inset LatexCommand index
5215 name "Derivable (object)"
5217 \end_inset
5220 \family default
5222 \family typewriter
5223 Derivable
5224 \family default
5225  objects respond to 
5226 \family typewriter
5227 derive
5228 \begin_inset LatexCommand index
5229 name "derive (message)"
5231 \end_inset
5234 \family default
5235 , which means they can be readily used for extension.
5236 \end_layout
5238 \begin_layout Description
5240 \family typewriter
5241 Cloneable
5242 \begin_inset LatexCommand index
5243 name "Cloneable (object)"
5245 \end_inset
5248 \family default
5249  A 
5250 \family typewriter
5251 Derivable
5252 \family default
5253  that can be 
5254 \family typewriter
5255 clone
5256 \family default
5258 \end_layout
5260 \begin_layout Description
5262 \family typewriter
5263 Method
5264 \begin_inset LatexCommand index
5265 name "Method (object)"
5267 \end_inset
5270 \family default
5271  A 
5272 \family typewriter
5273 Cloneable
5274 \family default
5275  object with attributes for supporting execution of blocks (with closure
5276  semantics, notably) and holding compiled code and its attributes.
5277 \end_layout
5279 \begin_layout Subsubsection
5280 Default Object Features
5281 \end_layout
5283 \begin_layout Description
5284 Identity
5285 \begin_inset LatexCommand index
5286 name "identity (terminology)"
5288 \end_inset
5291 \begin_inset LatexCommand index
5292 name "== (message)"
5294 \end_inset
5297 \begin_inset LatexCommand index
5298 name "\\~{}== (message)"
5300 \end_inset
5303 \family typewriter
5305 \family default
5306  returns whether the two arguments are identical, i.e.
5307  the same object, and 
5308 \family typewriter
5310 \begin_inset ERT
5311 status collapsed
5313 \begin_layout Standard
5316 \backslash
5318 \end_layout
5320 \end_inset
5323 \family default
5324  is its negation.
5325  Value-equality (
5326 \family typewriter
5328 \family default
5329  and its negation 
5330 \family typewriter
5332 \begin_inset ERT
5333 status collapsed
5335 \begin_layout Standard
5338 \backslash
5340 \end_layout
5342 \end_inset
5345 \family default
5346 ) defaults to this.
5347 \end_layout
5349 \begin_layout Description
5350 Printing
5351 \begin_inset LatexCommand index
5352 name "printing"
5354 \end_inset
5357 \family typewriter
5358 printString
5359 \begin_inset LatexCommand index
5360 name "printString (message)"
5362 \end_inset
5365 \family default
5366  returns a printed (string) representation of the object.
5368 \family typewriter
5369 printOn:
5370 \begin_inset LatexCommand index
5371 name "printOn: (message)"
5373 \end_inset
5376 \family default
5377  places the result of printing onto a designated 
5378 \family typewriter
5379 Stream
5380 \family default
5382 \begin_inset LatexCommand index
5383 name "Stream (object)"
5385 \end_inset
5388 \family typewriter
5389 print
5390 \begin_inset LatexCommand index
5391 name "print (message)"
5393 \end_inset
5396 \family default
5397  will invoke 
5398 \family typewriter
5399 printOn:
5400 \family default
5401  on the 
5402 \family typewriter
5403 Console
5404 \family default
5406  This should be overridden for clarity.
5407 \end_layout
5409 \begin_layout Description
5410 Delegation-testing
5411 \begin_inset LatexCommand index
5412 name "delegation testing"
5414 \end_inset
5417 \begin_inset LatexCommand index
5418 name "testing, delegation"
5420 \end_inset
5423 \family typewriter
5424 isReally:
5425 \begin_inset LatexCommand index
5426 name "isReally: message"
5428 \end_inset
5431 \family default
5432  returns whether the first object has the second (or its traits object if
5433  it is not a 
5434 \family typewriter
5435 Trait
5436 \family default
5437 ) as one of its delegated objects, directly or indirectly.
5438 \end_layout
5440 \begin_layout Description
5441 Kind-testing
5442 \begin_inset LatexCommand index
5443 name "testing, kind"
5445 \end_inset
5448 \begin_inset LatexCommand index
5449 name "kind testing"
5451 \end_inset
5454 \family typewriter
5456 \begin_inset LatexCommand index
5457 name "is: (message)"
5459 \end_inset
5462 \family default
5463  returns whether the first object has the same kind as the second object,
5464  or some derived kind from the second object's kind.
5465  By default, 
5466 \family typewriter
5468 \family default
5469  is 
5470 \family typewriter
5471 isReally:
5472 \family default
5473 ; overrides can allow the user to adapt or abuse this notion where delegation
5474  isn't appropriate but kind-similarity still should hold.
5476 \family typewriter
5477 isSameAs:
5478 \begin_inset LatexCommand index
5479 name "isSameAs: (message)"
5481 \end_inset
5484 \family default
5485  answers whether the arguments have the same traits object.
5486 \end_layout
5488 \begin_layout Description
5489 Hashing
5490 \begin_inset LatexCommand index
5491 name "hashing"
5493 \end_inset
5495  A quick way to sort by object value that makes searching collections faster
5496  is the 
5497 \family typewriter
5498 hash
5499 \begin_inset LatexCommand index
5500 name "hash (message)"
5502 \end_inset
5505 \family default
5506  method, which by default hashes on the object's identity (available separately
5507  as 
5508 \family typewriter
5509 identityHash
5510 \family default
5512 \begin_inset LatexCommand index
5513 name "identityHash (message)"
5515 \end_inset
5517 ), essentially by its birth address in memory.
5518  More importantly, this is how value-equality
5519 \begin_inset LatexCommand index
5520 name "equality, value"
5522 \end_inset
5525 \begin_inset LatexCommand index
5526 name "value equality"
5528 \end_inset
5530  is established for collections; if an object type overrides =
5531 \begin_inset LatexCommand index
5532 name "= (equal sign)"
5534 \end_inset
5537 \begin_inset LatexCommand index
5538 name "equal sign"
5540 \end_inset
5542 , it must also override the 
5543 \family typewriter
5544 hash
5545 \family default
5546  method's algorithm so that 
5547 \family typewriter
5548 a\InsetSpace ~
5549 =\InsetSpace ~
5551 \family default
5553 \begin_inset Formula $\Rightarrow$
5554 \end_inset
5557 \family typewriter
5558 a\InsetSpace ~
5559 hash\InsetSpace ~
5560 =\InsetSpace ~
5561 b\InsetSpace ~
5562 hash
5563 \family default
5565 \end_layout
5567 \begin_layout Description
5568 Cloning
5569 \begin_inset LatexCommand index
5570 name "cloning"
5572 \end_inset
5574  The 
5575 \family typewriter
5576 clone
5577 \begin_inset LatexCommand index
5578 name "clone (message)"
5580 \end_inset
5583 \family default
5584  method is fundamental for Slate objects.
5585  It creates and returns a new object identical in slot names and values
5586  to the argument object, but with a new unique identity.
5587  As such, it has a very specific meaning and should only be used that way.
5588 \end_layout
5590 \begin_layout Description
5591 Copying
5592 \begin_inset LatexCommand index
5593 name "copying"
5595 \end_inset
5597  The 
5598 \family typewriter
5599 copy
5600 \begin_inset LatexCommand index
5601 name "copy (message)"
5603 \end_inset
5606 \family default
5607  method makes a value-equal (
5608 \family typewriter
5610 \family default
5611 ) object from the argument and returns the new object.
5612  This should be overridden as necessary where 
5613 \family typewriter
5615 \family default
5616  is overridden.
5617  The default case is to clone the original object.
5618 \end_layout
5620 \begin_layout Description
5621 Conversion/coercion
5622 \begin_inset LatexCommand index
5623 name "coercion"
5625 \end_inset
5628 \begin_inset LatexCommand index
5629 name "conversion"
5631 \end_inset
5633  the 
5634 \family typewriter
5636 \begin_inset LatexCommand index
5637 name "as: (message)"
5639 \end_inset
5642 \family default
5643  protocol provides default conversion methods between types of objects in
5644  Slate.
5645  Some primitive types, such as 
5646 \family typewriter
5647 Number
5648 \family default
5649 , override this.
5650  The 
5651 \family typewriter
5653 \family default
5654  method has a default implementation on root objects: if no converter is
5655  found or if the objects are not of the same type, the failure will raise
5656  a condition.
5657  Precisely, the behavior of 
5658 \family typewriter
5659 a\InsetSpace ~
5660 as:\InsetSpace ~
5662 \family default
5663  is to produce an object based on 
5664 \family typewriter
5666 \family default
5667  which is as much like 
5668 \family typewriter
5670 \family default
5671  as possible.
5672 \end_layout
5674 \begin_layout Subsubsection
5675 Oddballs
5676 \end_layout
5678 \begin_layout Standard
5679 \begin_inset LatexCommand index
5680 name "oddballs"
5682 \end_inset
5684 There are various 
5685 \family typewriter
5686 Oddball
5687 \family default
5688 s in the system, and they are non-cloneable in general.
5689  However, 
5690 \family typewriter
5691 Oddball
5692 \family default
5693  itself may be cloned, for extension purposes.
5694 \end_layout
5696 \begin_layout Subsection
5697 Introspection
5698 \end_layout
5700 \begin_layout Subsubsection
5701 Slot Queries
5702 \end_layout
5704 \begin_layout Standard
5705 Objects may be queried directly for various attributes that they have.
5706  These should not be used in ordinary 
5707 \begin_inset Quotes eld
5708 \end_inset
5710 non-private
5711 \begin_inset Quotes erd
5712 \end_inset
5714  code, only in specific uses which need to operate on arbitrary object-slot
5715  structures or inside of accessor methods.
5716 \end_layout
5718 \begin_layout Description
5720 \family typewriter
5721 \begin_inset LatexCommand index
5722 name "atSlotNamed: (message)"
5724 \end_inset
5726 atSlotNamed:
5727 \family default
5728  answers the value of the slot with the given name.
5729 \end_layout
5731 \begin_layout Description
5733 \family typewriter
5734 \begin_inset LatexCommand index
5735 name "atSlotNamed:put: (message)"
5737 \end_inset
5739 atSlotNamed:put:
5740 \family default
5741  fills the delegate slot with the given name.
5742  It answers the object modified.
5743 \end_layout
5745 \begin_layout Description
5747 \family typewriter
5748 \begin_inset LatexCommand index
5749 name "slotNames (message)"
5751 \end_inset
5753 slotNames
5754 \family default
5755  answers an 
5756 \family typewriter
5757 Array
5758 \family default
5759  of the names of the object's direct slots.
5760 \end_layout
5762 \begin_layout Description
5764 \family typewriter
5765 \begin_inset LatexCommand index
5766 name "delegates (message)"
5768 \end_inset
5771 \begin_inset ERT
5772 status collapsed
5774 \begin_layout Standard
5776 \family typewriter
5778 \backslash
5780 \end_layout
5782 \end_inset
5784 delegates
5785 \family default
5786  answers an 
5787 \family typewriter
5788 Array
5789 \family default
5790  of the names of the object's direct delegate slots.
5791 \end_layout
5793 \begin_layout Description
5795 \family typewriter
5796 \begin_inset LatexCommand index
5797 name "slotsDo: (message)"
5799 \end_inset
5801 slotsDo:
5802 \family default
5803  applies a block to each slot's value.
5804 \end_layout
5806 \begin_layout Description
5808 \family typewriter
5809 \begin_inset LatexCommand index
5810 name "delegatesDo: (message)"
5812 \end_inset
5814 delegatesDo:
5815 \family default
5816  applies a block to each delegate slot's value.
5817 \end_layout
5819 \begin_layout Description
5821 \family typewriter
5822 \begin_inset LatexCommand index
5823 name "addAccessorFor: (message)"
5825 \end_inset
5827 addAccessorFor:
5828 \family default
5829  defines a default accessor (aka 
5830 \begin_inset Quotes eld
5831 \end_inset
5833 getter
5834 \begin_inset Quotes erd
5835 \end_inset
5837 ) method for the slot with the given name.
5838 \end_layout
5840 \begin_layout Description
5842 \family typewriter
5843 \begin_inset LatexCommand index
5844 name "addMutatorFor: (message)"
5846 \end_inset
5848 addMutatorFor:
5849 \family default
5850  defines a default mutator (aka 
5851 \begin_inset Quotes eld
5852 \end_inset
5854 setter
5855 \begin_inset Quotes erd
5856 \end_inset
5858 ) method for the slot with the given name.
5859 \end_layout
5861 \begin_layout Description
5863 \family typewriter
5864 \begin_inset LatexCommand index
5865 name "addAccessor:for: (message)"
5867 \end_inset
5869 addAccessor:for:
5870 \family default
5871  installs the given method as accessor for the slot with the given name.
5872 \end_layout
5874 \begin_layout Description
5876 \family typewriter
5877 \begin_inset LatexCommand index
5878 name "addMutator:for: (message)"
5880 \end_inset
5882 addMutator:for:
5883 \family default
5884  installs the given method as mutator for the slot with the given name.
5885 \end_layout
5887 \begin_layout Subsubsection
5888 Method Queries
5889 \end_layout
5891 \begin_layout Standard
5892 Slate includes a protocol for common query operations on 
5893 \family typewriter
5894 Method
5895 \family default
5896  objects:
5897 \end_layout
5899 \begin_layout Description
5901 \family typewriter
5902 \begin_inset LatexCommand index
5903 name "selector (message)"
5905 \end_inset
5907 selector
5908 \family default
5909  answers the 
5910 \family typewriter
5911 Symbol
5912 \family default
5913  naming the 
5914 \family typewriter
5915 Method
5916 \family default
5917  if it has been defined and installed under some objects' roles, or 
5918 \family typewriter
5920 \family default
5921  if it is unnamed (an ordinary block).
5922 \end_layout
5924 \begin_layout Description
5926 \family typewriter
5927 \begin_inset LatexCommand index
5928 name "isNamed (method)"
5930 \end_inset
5932 isNamed
5933 \family default
5934  answers whether the 
5935 \family typewriter
5936 Method
5937 \family default
5938  is a named method; that is, whether it is installed with a dispatch signature
5939  and selector.
5940 \end_layout
5942 \begin_layout Description
5944 \family typewriter
5945 \begin_inset LatexCommand index
5946 name "arity (message)"
5948 \end_inset
5950 arity
5951 \family default
5952  answers the number of arguments expected as input to the 
5953 \family typewriter
5954 Method
5955 \family default
5957  This excludes any optional keyword arguments or rest arguments that it
5958  may accept.
5959  This also applies to the quoted form of a literal method.
5960 \end_layout
5962 \begin_layout Description
5964 \family typewriter
5965 \begin_inset LatexCommand index
5966 name "acceptsAdditionalArguments (message)"
5968 \end_inset
5970 acceptsAdditionalArguments
5971 \family default
5972  answers whether the 
5973 \family typewriter
5974 Method
5975 \family default
5976  takes a rest parameter.
5977 \end_layout
5979 \begin_layout Description
5981 \family typewriter
5982 \begin_inset LatexCommand index
5983 name "allSelectorsSent (message)"
5985 \end_inset
5987 allSelectorsSent
5988 \family default
5989  answers an 
5990 \family typewriter
5991 Array
5992 \family default
5993  of all 
5994 \family typewriter
5995 Symbol
5996 \family default
5997 s that the block directly (in its defining source) sends.
5998  This also applies to the quoted form of a literal method.
5999 \end_layout
6001 \begin_layout Description
6003 \family typewriter
6004 \begin_inset LatexCommand index
6005 name "methodsNamed: (message)"
6007 \end_inset
6009 methodsNamed:
6010 \family default
6011  answers all distinct 
6012 \family typewriter
6013 Method
6014 \family default
6015  objects with the given name stored in roles on the given object.
6016 \end_layout
6018 \begin_layout Description
6020 \family typewriter
6021 \begin_inset LatexCommand index
6022 name "methodsAt: (message)"
6024 \end_inset
6026 methodsAt:
6027 \family default
6028  answers all distinct 
6029 \family typewriter
6030 Method
6031 \family default
6032  objects stored in the role position given on the given object.
6033 \end_layout
6035 \begin_layout Description
6037 \family typewriter
6038 \begin_inset LatexCommand index
6039 name "methodsNamed:at: (message)"
6041 \end_inset
6043 methodsNamed:at:
6044 \family default
6045  answers all distinct 
6046 \family typewriter
6047 Method
6048 \family default
6049  objects stored in roles on the given object with the given name and at
6050  the given role position.
6051 \end_layout
6053 \begin_layout Description
6055 \family typewriter
6056 \begin_inset LatexCommand index
6057 name "methodsCalling: (message)"
6059 \end_inset
6061 methodsSending:
6062 \family default
6063  answers all distinct 
6064 \family typewriter
6065 Method
6066 \family default
6067  objects stored in roles on the given object which send the given selector.
6068 \end_layout
6070 \begin_layout Description
6072 \family typewriter
6073 \begin_inset LatexCommand index
6074 name "signature (message)"
6076 \end_inset
6078 signature\InsetSpace ~
6079 &in:
6080 \family default
6081  answers a 
6082 \family typewriter
6083 Signature
6084 \family default
6085  object (roles plus selector) corresponding to the given (named) 
6086 \family typewriter
6087 Method
6088 \family default
6089 's definition.
6090  This currently involves a search and takes a variable amount of time.
6091 \end_layout
6093 \begin_layout Description
6095 \family typewriter
6096 \begin_inset LatexCommand index
6097 name "implementations (message)"
6099 \end_inset
6101 Symbol\InsetSpace ~
6102 implementations
6103 \family default
6104  answers a 
6105 \family typewriter
6107 \family default
6108  of all 
6109 \family typewriter
6110 Method
6111 \family default
6112 s whose 
6113 \family typewriter
6114 selector
6115 \family default
6116  is the argument.
6117  An 
6118 \family typewriter
6119 &in:
6120 \family default
6121  optional parameter restricts the search to one object (as namespace).
6122 \end_layout
6124 \begin_layout Description
6126 \family typewriter
6127 \begin_inset LatexCommand index
6128 name "callers (message)"
6130 \end_inset
6132 Symbol\InsetSpace ~
6133 senders
6134 \family default
6135  answers a 
6136 \family typewriter
6138 \family default
6139  of all 
6140 \family typewriter
6141 Method
6142 \family default
6143 s which send the argument selector.
6144  An 
6145 \family typewriter
6146 &in:
6147 \family default
6148  optional parameter restricts the search to one object (as namespace).
6149 \end_layout
6151 \begin_layout Description
6153 \family typewriter
6154 \begin_inset LatexCommand index
6155 name "macroCallers (message)"
6157 \end_inset
6159 Symbol\InsetSpace ~
6160 macroSenders
6161 \family default
6162  answers a 
6163 \family typewriter
6165 \family default
6166  of all 
6167 \family typewriter
6168 Method
6169 \family default
6170 s which send the argument selector.
6171  An 
6172 \family typewriter
6173 &in:
6174 \family default
6175  optional parameter restricts the search to one object (as namespace).
6176 \end_layout
6178 \begin_layout Subsection
6179 Traits
6180 \end_layout
6182 \begin_layout Standard
6183 \begin_inset LatexCommand index
6184 name "traits"
6186 \end_inset
6188 Slate objects, from the root objects down, all respond to the message 
6189 \family typewriter
6190 traits
6191 \family default
6193 \begin_inset LatexCommand index
6194 name "traits (message)"
6196 \end_inset
6198 , which is conceptually shared behavior but is not as binding as a class
6199  is.
6200  It returns an object which is, by convention, the location to place shared
6201  behavior.
6202  Most Slate method definitions are defined upon some object's 
6203 \family typewriter
6204 traits
6205 \family default
6206  object.
6207  This is significant because cloning an object with a traits delegation
6208  slot will result in a new object with the same object delegated-to, so
6209  all methods defined on that traits object apply to the new clone.
6210  There is one core method which drives derivation:
6211 \end_layout
6213 \begin_layout Description
6215 \family typewriter
6216 \begin_inset LatexCommand index
6217 name "derive (message)"
6219 \end_inset
6221 myObject\InsetSpace ~
6222 derive\InsetSpace ~
6223 &mixins:\InsetSpace ~
6224 &rejects:
6225 \family default
6226  will return a new clone of the 
6227 \family typewriter
6228 Derivable
6229 \family default
6230  object with a traits object which is cloned from the original's traits
6231  object, and an immutable delegation slot set between the traits objects.
6232  If mixins are given, it will include more immutable delegation links between
6233  the new traits and the traits of the array's objects, in the given order,
6234  which achieves a structured, shared behavior of static multiple delegation.
6235  Note that the delegation link addition order makes the right-most delegation
6236  target override the former ones in that order.
6237  One interesting property of this method is that the elements of the mixins
6238  do not have to be 
6239 \family typewriter
6240 Derivable
6241 \family default
6243 \end_layout
6245 \begin_layout Standard
6246 In practice, the following wrapper is the appropriate method to use in common
6247  situations, since it handles the installation of the prototype in a cleaner
6248  manner:
6249 \end_layout
6251 \begin_layout Description
6253 \family typewriter
6254 \begin_inset LatexCommand index
6255 name "addPrototype:derivedFrom:"
6257 \end_inset
6259 obj\InsetSpace ~
6260 addPrototype:\InsetSpace ~
6261 name\InsetSpace ~
6262 derivedFrom:\InsetSpace ~
6263 parentsArray
6264 \family default
6265  will perform the effects of 
6266 \family typewriter
6267 derive
6268 \family default
6269  using all the elements of the 
6270 \family typewriter
6271 Sequence
6272 \family default
6273  in the same order as 
6274 \family typewriter
6275 derive
6276 \family default
6278  It also assigns the name to the traits object's name attribute (which should
6279  be a 
6280 \family typewriter
6281 Symbol
6282 \family default
6283 ) as well as using the name for the attribute between the surrounding object
6284  and the new prototype.
6285  Finally, it will compare the delegation pattern of the new object with
6286  the old, and only replace the old if they differ.
6287  In either case, the installed object is what is returned, and the existing
6288  traits object will be re-used if there is one.
6289 \end_layout
6291 \begin_layout Description
6293 \family typewriter
6294 \begin_inset LatexCommand index
6295 name "define: (message)"
6297 \end_inset
6299 obj\InsetSpace ~
6300 define:\InsetSpace ~
6301 name\InsetSpace ~
6302 &parents:\InsetSpace ~
6303 parentsArray\InsetSpace ~
6304 &slots:\InsetSpace ~
6305 slotSpecs
6306 \family default
6307  performs the effects of 
6308 \family typewriter
6309 derive
6310 \family default
6311  using all the elements of the 
6312 \family typewriter
6313 Sequence
6314 \family default
6315  in the same order as 
6316 \family typewriter
6317 derive
6318 \family default
6320  The default parent is just 
6321 \family typewriter
6322 Cloneable
6323 \family default
6325  It also assigns the name to the traits object's name attribute (which should
6326  be a 
6327 \family typewriter
6328 Symbol
6329 \family default
6330 ) as well as using the name for the attribute between the surrounding object
6331  and the new prototype.
6332  The 
6333 \family typewriter
6334 slotSpecs
6335 \family default
6336  needs to be an array with either 
6337 \family typewriter
6338 Symbol
6339 \family default
6340 s or 
6341 \family typewriter
6342 Association
6343 \family default
6344 s from 
6345 \family typewriter
6346 Symbol
6347 \family default
6348 s to values, to specify (mutable) state-slots and their attributes.
6349  Finally, it will compare the delegation pattern of the new object with
6350  the old, and only replace the old if they differ.
6351  In either case, the installed object is what is returned, and the existing
6352  traits object will be re-used if there is one.
6353  A 
6354 \family typewriter
6355 define:&builder:
6356 \family default
6357  form is also provided which takes a block and uses its resulting value
6358  for the object; 
6359 \family typewriter
6360 &builder:
6361 \family default
6362  can be used in conjuction with 
6363 \family typewriter
6364 &slots:
6365 \family default
6366 , but not with 
6367 \family typewriter
6368 &parents:
6369 \family default
6370 , as no derivation is relevant.
6371 \end_layout
6373 \begin_layout Standard
6374 As with any method in Slate, these may be overridden to provide additional
6375  automation and safety in line with their semantics.
6376 \end_layout
6378 \begin_layout Paragraph
6379 Traits Windows
6380 \end_layout
6382 \begin_layout Standard
6383 Beneath this simple system is a level of indirection which allows for greater
6384  control 
6385 \emph on
6386 when necessary
6387 \emph default
6388  over the combination of parent behaviors; for most purposes, they may be
6389  ignored.
6390  What is actually the case is that each object points to an object in a
6392 \family typewriter
6393 traitsWindow
6394 \family default
6395  delegation slot.
6397 \family typewriter
6398 traitsWindow
6399 \family default
6400  is defined to be the first delegate in an object's delegates array and
6402 \family typewriter
6403 traits
6404 \family default
6405  is defined to be the last delegate in an object's 
6406 \family typewriter
6407 traitsWindow
6408 \family default
6410 \end_layout
6412 \begin_layout Standard
6413 Because the delegates of an object are easily changed, there is a great
6414  deal of control over the order of precedence This means that nearly all
6415  of the problems of precedence in a multiple inheritance graph may be resolved
6416  flexibly.
6417 \begin_inset Foot
6418 status collapsed
6420 \begin_layout Standard
6421 The classical illustration of multiple inheritance issues is the 
6422 \begin_inset Quotes eld
6423 \end_inset
6425 diamond
6426 \begin_inset Quotes erd
6427 \end_inset
6429  problem where one parent is inherited via two different paths indirectly.
6430  Solutions that involve choosing inheritance graph traversal orders for
6431  the whole language are insufficiently flexible in dealing with multiple
6432  inheritance confusion, since various protocols need to interact independently.
6433 \end_layout
6435 \end_inset
6437  There is also a hint to the lookup procedure in the 
6438 \family typewriter
6439 traitsWindow
6440 \family default
6441  objects that a meta-level has been reached.
6442  Once one meta-transition has occurred during lookup, the algorithm will
6443  not traverse such a transition again; thus Slate avoids a lookup confusion
6444  between methods meant for regular objects and those meant for the traits
6445  themselves.
6446 \end_layout
6448 \begin_layout Subsection
6449 Blocks, Booleans, and Control-Flow
6450 \begin_inset OptArg
6451 status collapsed
6453 \begin_layout Standard
6454 Control-flow
6455 \end_layout
6457 \end_inset
6460 \end_layout
6462 \begin_layout Subsubsection
6463 Boolean Logic
6464 \end_layout
6466 \begin_layout Standard
6467 \begin_inset LatexCommand index
6468 name "boolean logic"
6470 \end_inset
6472 Slate's evaluator primitively provides the objects 
6473 \family typewriter
6474 True
6475 \begin_inset LatexCommand index
6476 name "True (object)"
6478 \end_inset
6481 \family default
6482  and 
6483 \family typewriter
6484 False
6485 \family default
6487 \begin_inset LatexCommand index
6488 name "False (object)"
6490 \end_inset
6492 , which are clones of 
6493 \family typewriter
6494 Boolean
6495 \family default
6497 \begin_inset LatexCommand index
6498 name "Boolean (object)"
6500 \end_inset
6502 , and delegate to 
6503 \family typewriter
6504 Boolean\InsetSpace ~
6505 traits
6506 \family default
6508  Logical methods are defined on these in a very minimalistic way.
6509  Table 
6510 \begin_inset LatexCommand vref
6511 reference "cap:Basic-Logical-Operators"
6513 \end_inset
6515  shows the non-lazy logical methods and their meanings.
6516 \end_layout
6518 \begin_layout Standard
6519 \begin_inset LatexCommand index
6520 name "boolean messages"
6522 \end_inset
6525 \begin_inset LatexCommand index
6526 name "and"
6528 \end_inset
6531 \begin_inset LatexCommand index
6532 name "\\char `\\/\\char `\\\\ (message)"
6534 \end_inset
6537 \begin_inset LatexCommand index
6538 name "or"
6540 \end_inset
6543 \begin_inset LatexCommand index
6544 name "\\char `\\\\\\char `\\/ (message)"
6546 \end_inset
6549 \begin_inset LatexCommand index
6550 name "not (message)"
6552 \end_inset
6555 \begin_inset LatexCommand index
6556 name "eqv: (message)"
6558 \end_inset
6561 \begin_inset LatexCommand index
6562 name "xor: (message)"
6564 \end_inset
6567 \begin_inset Float table
6568 wide false
6569 sideways false
6570 status open
6572 \begin_layout Standard
6573 \align center
6574 \begin_inset Tabular
6575 <lyxtabular version="3" rows="6" columns="2">
6576 <features>
6577 <column alignment="center" valignment="top" leftline="true" width="0pt">
6578 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
6579 <row topline="true" bottomline="true">
6580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6581 \begin_inset Text
6583 \begin_layout Standard
6584 Description
6585 \end_layout
6587 \end_inset
6588 </cell>
6589 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6590 \begin_inset Text
6592 \begin_layout Standard
6593 Selector
6594 \end_layout
6596 \end_inset
6597 </cell>
6598 </row>
6599 <row bottomline="true">
6600 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6601 \begin_inset Text
6603 \begin_layout Standard
6604 AND/Conjunction
6605 \end_layout
6607 \end_inset
6608 </cell>
6609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6610 \begin_inset Text
6612 \begin_layout Standard
6614 \family typewriter
6616 \backslash
6618 \end_layout
6620 \end_inset
6621 </cell>
6622 </row>
6623 <row>
6624 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6625 \begin_inset Text
6627 \begin_layout Standard
6629 \noun on
6631 \noun default
6632 /Disjunction
6633 \end_layout
6635 \end_inset
6636 </cell>
6637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6638 \begin_inset Text
6640 \begin_layout Standard
6642 \family typewriter
6644 \backslash
6646 \end_layout
6648 \end_inset
6649 </cell>
6650 </row>
6651 <row topline="true">
6652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6653 \begin_inset Text
6655 \begin_layout Standard
6656 NOT/Negation
6657 \end_layout
6659 \end_inset
6660 </cell>
6661 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6662 \begin_inset Text
6664 \begin_layout Standard
6666 \family typewriter
6668 \end_layout
6670 \end_inset
6671 </cell>
6672 </row>
6673 <row topline="true">
6674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6675 \begin_inset Text
6677 \begin_layout Standard
6678 EQV/Equivalence
6679 \end_layout
6681 \end_inset
6682 </cell>
6683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6684 \begin_inset Text
6686 \begin_layout Standard
6688 \family typewriter
6689 eqv:
6690 \end_layout
6692 \end_inset
6693 </cell>
6694 </row>
6695 <row topline="true" bottomline="true">
6696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6697 \begin_inset Text
6699 \begin_layout Standard
6700 XOR/Exclusive-OR
6701 \end_layout
6703 \end_inset
6704 </cell>
6705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
6706 \begin_inset Text
6708 \begin_layout Standard
6710 \family typewriter
6711 xor:
6712 \end_layout
6714 \end_inset
6715 </cell>
6716 </row>
6717 </lyxtabular>
6719 \end_inset
6722 \end_layout
6724 \begin_layout Standard
6725 \begin_inset Caption
6727 \begin_layout Standard
6728 \begin_inset LatexCommand label
6729 name "cap:Basic-Logical-Operators"
6731 \end_inset
6733 Basic Logical Operators
6734 \end_layout
6736 \end_inset
6739 \end_layout
6741 \end_inset
6744 \end_layout
6746 \begin_layout Subsubsection
6747 Basic Conditional Evaluation
6748 \end_layout
6750 \begin_layout Standard
6751 \begin_inset LatexCommand index
6752 name "conditional evaluation"
6754 \end_inset
6757 \begin_inset LatexCommand index
6758 name "evaluation, conditional"
6760 \end_inset
6762 Logical methods are provided which take a block as their second argument
6764 \family typewriter
6766 \backslash
6768 \family default
6770 \family typewriter
6772 \backslash
6774 \family default
6776 \family typewriter
6777 and:
6778 \family default
6780 \family typewriter
6782 \family default
6784 \family typewriter
6785 xor:
6786 \family default
6788 \family typewriter
6789 eqv:
6790 \family default
6792  By accepting a block as the second argument, they can and do provide conditiona
6793 l evaluation of the second argument only in the case that the first does
6794  not decide the total result automatically
6795 \begin_inset Foot
6796 status collapsed
6798 \begin_layout Standard
6799 However, support for blocks in the second argument position may be incorporated
6800  into the non-lazy selectors as different methods in the future, making
6801  some of these obsolete.
6802 \end_layout
6804 \end_inset
6808 \begin_inset LatexCommand index
6809 name "evaluation, lazy"
6811 \end_inset
6814 \begin_inset LatexCommand index
6815 name "lazy evaluation"
6817 \end_inset
6819 Blocks that evaluate logical expressions can be used lazily in these logical
6820  expressions.
6821  For example,
6822 \end_layout
6824 \begin_layout LyX-Code
6825 (x < 3) /
6826 \backslash
6827  [y > 7].
6828 \end_layout
6830 \begin_layout Standard
6831 only evaluates the right-hand block argument if the first argument turns
6832  out to be 
6833 \family typewriter
6834 True
6835 \family default
6837 \end_layout
6839 \begin_layout LyX-Code
6840 (x < 3) 
6841 \backslash
6842 / [y > 7].
6843 \end_layout
6845 \begin_layout Standard
6846 only evaluates the right-hand block argument if the first argument turns
6847  out to be 
6848 \family typewriter
6849 False
6850 \family default
6852 \end_layout
6854 \begin_layout Standard
6855 In general, the basic of booleans to switch between code alternatives is
6856  to use 
6857 \family typewriter
6858 ifTrue:
6859 \family default
6861 \begin_inset LatexCommand index
6862 name "ifTrue: (message)"
6864 \end_inset
6867 \family typewriter
6868 ifFalse:
6869 \family default
6871 \begin_inset LatexCommand index
6872 name "ifFalse: (message)"
6874 \end_inset
6876 , and 
6877 \family typewriter
6878 ifTrue:ifFalse:
6879 \begin_inset LatexCommand index
6880 name "ifTrue:ifFalse: (message)"
6882 \end_inset
6885 \family default
6886  for the various combinations of binary branches.
6887  For example,
6888 \end_layout
6890 \begin_layout LyX-Code
6891 x isNegative ifTrue: [x: x negated].
6892 \end_layout
6894 \begin_layout Standard
6895 ensures that 
6896 \family typewriter
6898 \family default
6899  is positive by optionally executing code to assign a positive form if it's
6900  not.
6901  Of course if only the result is desired, instead of just the side-effect,
6902  the entire expression's result will be the result of the executed block,
6903  so that it can be embedded in further expressions.
6904 \end_layout
6906 \begin_layout Standard
6907 Conditional evaluation can also be driven by whether or not a slot has been
6908  initialized, or whether a method returns 
6909 \family typewriter
6911 \family default
6913  There are a few options for conditionalizing on 
6914 \family typewriter
6916 \family default
6918 \end_layout
6920 \begin_layout Description
6922 \family typewriter
6923 \begin_inset LatexCommand index
6924 name "ifNil: (message)"
6926 \end_inset
6929 \begin_inset LatexCommand index
6930 name "ifNotNil: (message)'"
6932 \end_inset
6934 expr\InsetSpace ~
6935 ifNil:\InsetSpace ~
6936 block
6937 \family default
6938  and 
6939 \family typewriter
6940 \series bold
6941 expr\InsetSpace ~
6942 ifNotNil:\InsetSpace ~
6943 block
6944 \family default
6945 \series default
6946  execute their blocks based on whether the expression evaluates to Nil,
6947  and returns the result.
6948 \end_layout
6950 \begin_layout Description
6952 \family typewriter
6953 \begin_inset LatexCommand index
6954 name "ifNil:ifNotNil: (message)"
6956 \end_inset
6958 expr\InsetSpace ~
6959 ifNil:\InsetSpace ~
6960 nilBlock\InsetSpace ~
6961 ifNotNil:\InsetSpace ~
6962 otherBlock
6963 \family default
6964  provides both options in one expression.
6965 \end_layout
6967 \begin_layout Description
6969 \family typewriter
6970 \begin_inset LatexCommand index
6971 name "ifNotNilDo: (message)"
6973 \end_inset
6976 \begin_inset LatexCommand index
6977 name "ifNil:ifNotNilDo: (message)"
6979 \end_inset
6981 expr\InsetSpace ~
6982 ifNotNilDo:\InsetSpace ~
6983 block
6984 \family default
6985  applies the block to the expression's result if it turns out to be non-
6986 \family typewriter
6988 \family default
6989 , so the block given must accept one argument.
6991 \family typewriter
6992 \series bold
6993 ifNil:ifNotNilDo:
6994 \family default
6995 \series default
6996  is also provided for completeness.
6997 \end_layout
6999 \begin_layout Standard
7000 There is also a 
7001 \begin_inset Quotes eld
7002 \end_inset
7004 case-switch
7005 \begin_inset Quotes erd
7006 \end_inset
7008  style idiom:
7009 \end_layout
7011 \begin_layout Description
7013 \family typewriter
7014 \begin_inset LatexCommand index
7015 name "caseOf: (message)"
7017 \end_inset
7020 \begin_inset LatexCommand index
7021 name "caseOf:otherwise: (message)"
7023 \end_inset
7025 expr\InsetSpace ~
7026 caseOf:\InsetSpace ~
7027 cases\InsetSpace ~
7028 otherwise:\InsetSpace ~
7029 defaultBlock
7030 \family default
7031  takes the result of the first argument and the 
7032 \family typewriter
7033 cases
7034 \family default
7035  array of 
7036 \family typewriter
7037 Association
7038 \family default
7039 s (made with 
7040 \family typewriter
7042 \family default
7043 ) from objects to blocks and executes the first block associated with a
7044  value equal to the expression.
7045  If none match, the last argument is executed; the otherwise: clause may
7046  be omitted, to just do / return nothing.
7047 \end_layout
7049 \begin_layout Subsubsection
7050 \begin_inset LatexCommand label
7051 name "sub:Early-Returns"
7053 \end_inset
7055 Early Returns
7056 \end_layout
7058 \begin_layout Standard
7059 \begin_inset LatexCommand index
7060 name "early return"
7062 \end_inset
7065 \begin_inset LatexCommand index
7066 name "return, early"
7068 \end_inset
7070 Control-flow within methods can be skipped with a return value using the
7072 \family typewriter
7074 \family default
7075  message to the context.
7077 \family typewriter
7079 \family default
7080  takes its second argument and exits the nearest surrounding lexical scope
7081  that is a named method (and not an anonymous code block) with that value.
7082  This message is a real binary message with no special precedence, so disambigua
7083 tion is often needed.
7084  For example,
7085 \end_layout
7087 \begin_layout LyX-Code
7088 ^ 4
7089 \end_layout
7091 \begin_layout LyX-Code
7092 ^ n factorial
7093 \end_layout
7095 \begin_layout Standard
7096 return the expressions on the left as a whole, but
7097 \end_layout
7099 \begin_layout LyX-Code
7100 ^ 3 + 4
7101 \end_layout
7103 \begin_layout LyX-Code
7104 ^ (3 + 4)
7105 \end_layout
7107 \begin_layout LyX-Code
7108 ^ set collect: [| :each | each name]
7109 \end_layout
7111 \begin_layout LyX-Code
7112 ^ (set collect: [| :each | each name])
7113 \end_layout
7115 \begin_layout Standard
7116 represent expression variations where a lack of disambiguation results in
7117  returning an unintended answer.
7118 \end_layout
7120 \begin_layout Subsubsection
7121 Looping
7122 \begin_inset LatexCommand label
7123 name "sub:Looping"
7125 \end_inset
7128 \end_layout
7130 \begin_layout Standard
7131 \begin_inset LatexCommand index
7132 name "looping"
7134 \end_inset
7136 Slate includes various idioms for constructing basic loops.
7137  These are all built from ordinary methods which work with code blocks,
7138  and any ordinary code may define similar idioms rather quickly.
7139 \end_layout
7141 \begin_layout Description
7143 \family typewriter
7144 \begin_inset LatexCommand index
7145 name "loop (message)"
7147 \end_inset
7149 loop
7150 \family default
7151  executes the block repeatedly, indefinitely
7152 \begin_inset Foot
7153 status collapsed
7155 \begin_layout Standard
7156 This is currently implemented through a compiler rule.
7157 \end_layout
7159 \end_inset
7162 \end_layout
7164 \begin_layout Description
7166 \family typewriter
7167 \begin_inset LatexCommand index
7168 name "timesRepeat: (message)"
7170 \end_inset
7172 n\InsetSpace ~
7173 timesRepeat:\InsetSpace ~
7174 block
7175 \family default
7176  executes the block 
7177 \family typewriter
7179 \family default
7180  times.
7181 \end_layout
7183 \begin_layout Description
7185 \family typewriter
7186 \begin_inset LatexCommand index
7187 name "whileTrue: (message)"
7189 \end_inset
7192 \begin_inset LatexCommand index
7193 name "whileFalse: (message)"
7195 \end_inset
7197 condition\InsetSpace ~
7198 whileTrue:\InsetSpace ~
7199 block
7200 \family default
7201  and 
7202 \family typewriter
7203 \series bold
7204 condition\InsetSpace ~
7205 whileFalse:\InsetSpace ~
7206 block
7207 \family default
7208 \series default
7209  execute their blocks repeatedly, checking the condition before each iteration
7210  (implying that the body block will not be executed if the condition is
7211  initially false).
7212 \end_layout
7214 \begin_layout Description
7216 \family typewriter
7217 \begin_inset LatexCommand index
7218 name "whileTrue (message)"
7220 \end_inset
7223 \begin_inset LatexCommand index
7224 name "whileFalse (message)"
7226 \end_inset
7228 whileTrue
7229 \family default
7230  and 
7231 \family typewriter
7232 \series bold
7233 whileFalse
7234 \family default
7235 \series default
7236  execute their blocks repeatedly, checking the return value before repeating
7237  iterations (so that they will always execute at least one time).
7238 \end_layout
7240 \begin_layout Description
7242 \family typewriter
7243 \begin_inset LatexCommand index
7244 name "upTo:do: (message)"
7246 \end_inset
7249 \begin_inset LatexCommand index
7250 name "downTo:do: (message)"
7252 \end_inset
7254 a\InsetSpace ~
7255 upTo:\InsetSpace ~
7256 b\InsetSpace ~
7257 do:\InsetSpace ~
7258 block
7259 \family default
7260  and 
7261 \family typewriter
7262 \series bold
7263 b\InsetSpace ~
7264 downTo:\InsetSpace ~
7265 a\InsetSpace ~
7266 do:\InsetSpace ~
7267 block
7268 \family default
7269 \series default
7270  executes the block with each number in turn from 
7271 \family typewriter
7273 \family default
7274  to 
7275 \family typewriter
7277 \family default
7278 , inclusive.
7279 \end_layout
7281 \begin_layout Description
7283 \family typewriter
7284 \begin_inset LatexCommand index
7285 name "upTo:by:do: (message)"
7287 \end_inset
7290 \begin_inset LatexCommand index
7291 name "downTo:by:do: (message)"
7293 \end_inset
7295 upTo:by:do:
7296 \family default
7297  and 
7298 \family typewriter
7299 \series bold
7300 downTo:by:do:
7301 \family default
7302 \series default
7303  executes the block with each number in turn in the inclusive range, with
7304  the given stepping increment.
7305 \end_layout
7307 \begin_layout Description
7309 \family typewriter
7310 \begin_inset LatexCommand index
7311 name "below:do: (message)"
7313 \end_inset
7316 \begin_inset LatexCommand index
7317 name "above:do: (message)"
7319 \end_inset
7321 a\InsetSpace ~
7322 below:\InsetSpace ~
7323 b\InsetSpace ~
7324 do:\InsetSpace ~
7325 block
7326 \family default
7327  and 
7328 \family typewriter
7329 \series bold
7330 b\InsetSpace ~
7331 above:\InsetSpace ~
7332 a\InsetSpace ~
7333 do:\InsetSpace ~
7334 block
7335 \family default
7336 \series default
7337  act identically to the previous method except that they stop just before
7338  the last value.
7339  This assists in iterating over array ranges, where the 0-based indexing
7340  makes a difference in range addresses by one, avoiding excessive use of
7342 \family typewriter
7343 size\InsetSpace ~
7344 -\InsetSpace ~
7346 \family default
7347  calls.
7348 \end_layout
7350 \begin_layout Description
7352 \family typewriter
7353 \begin_inset LatexCommand index
7354 name "below:by:do: (message)"
7356 \end_inset
7359 \begin_inset LatexCommand index
7360 name "above:by:do: (message)"
7362 \end_inset
7364 below:by:do:
7365 \family default
7366  and 
7367 \family typewriter
7368 \series bold
7369 above:by:do:
7370 \family default
7371 \series default
7372  vary on the previous methods with the given stepping increment.
7373 \end_layout
7375 \begin_layout Standard
7376 \begin_inset Note Note
7377 status collapsed
7379 \begin_layout Standard
7380 Slate's looping control structures can easily be extended without concern
7381  due to the fact that the evaluator 
7382 \emph on
7384 \emph default
7385  at one point unroll properly tail-recursive blocks into low-level loop
7386  code that re-uses the same activation frame.
7387  So basically structuring custom looping code so that it calls itself last
7388  within its own body and returns that value will avoid the need for increasing
7389  stack space per iteration.
7390  (Turn this back into a paragraph if it is implemented again.)
7391 \end_layout
7393 \end_inset
7396 \end_layout
7398 \begin_layout Subsubsection
7399 Method Operations
7400 \end_layout
7402 \begin_layout Standard
7403 Slate provides some powerful methods for operating on 
7404 \family typewriter
7405 Method
7406 \family default
7407  (block) objects themselves.
7408  The answers of these operations are also fully-fledged 
7409 \family typewriter
7410 Method
7411 \family default
7412  objects which respond to all of the normal queries and are useful anywhere
7413  that a 
7414 \family typewriter
7415 Method
7416 \family default
7417  is accepted.
7418 \end_layout
7420 \begin_layout Description
7422 \family typewriter
7423 \begin_inset LatexCommand index
7424 name "** (message)"
7426 \end_inset
7429 \begin_inset LatexCommand index
7430 name "method composition"
7432 \end_inset
7435 \family default
7436  composes two 
7437 \family typewriter
7438 Method
7439 \family default
7440 s in a functional manner, so that 
7441 \begin_inset Formula $(F\circ G)(x)=F(G(x))$
7442 \end_inset
7444 ; basically the result of applying the first to the result of the second
7445  (which in turn consumes the input).
7446  This operation is associative, so grouping of continued applications should
7447  not be a concern.
7448  This semantics assumes that the inner/right function 
7449 \begin_inset Formula $G$
7450 \end_inset
7452  may take any number of arguments, and that 
7453 \begin_inset Formula $F$
7454 \end_inset
7456  takes 1.
7457  If both of these are false, then there is an extended form of the semantics
7458  where the arity of 
7459 \begin_inset Formula $F$
7460 \end_inset
7462  is used to group the results of applying 
7463 \begin_inset Formula $G$
7464 \end_inset
7466  to each element in the argument array.
7467  The groups are then passed as a whole to one invocation of 
7468 \begin_inset Formula $F$
7469 \end_inset
7472 \end_layout
7474 \begin_layout Description
7476 \family typewriter
7477 \begin_inset LatexCommand index
7478 name "`er (macro)"
7480 \end_inset
7483 \family default
7484  takes a literal 
7485 \family typewriter
7486 Symbol
7487 \family default
7488  taken as a message selector and expands into an appropriate 
7489 \family typewriter
7490 Method
7491 \family default
7492  which takes an appropriate number of arguments for the selector and sends
7493  the selector to those arguments, answering the result.
7494  E.g.
7496 \family typewriter
7497 #+`er
7498 \family default
7499  expands into 
7500 \family typewriter
7501 [| :x :y | x + y]
7502 \family default
7503  and 
7504 \family typewriter
7505 #name`er
7506 \family default
7507  expands into 
7508 \family typewriter
7509 [| :x | x name]
7510 \family default
7512 \end_layout
7514 \begin_layout Description
7516 \family typewriter
7517 \begin_inset LatexCommand index
7518 name "converse (message)"
7520 \end_inset
7522 converse
7523 \family default
7524  takes a 
7525 \family typewriter
7526 Method
7527 \family default
7528  and answers a new 
7529 \family typewriter
7530 Method
7531 \family default
7532  with the same body but with input argument order reversed.
7533 \end_layout
7535 \begin_layout Description
7536 \begin_inset LatexCommand index
7537 name "<- (message)"
7539 \end_inset
7542 \begin_inset LatexCommand index
7543 name "currying"
7545 \end_inset
7548 \family typewriter
7550 \family default
7551  takes a 
7552 \family typewriter
7553 Method
7554 \family default
7555  and an object and returns a new 
7556 \family typewriter
7557 Method
7558 \family default
7559  with the same body but with the object substituted for the first argument,
7560  so it takes one less argument.
7561  This is also known as 
7562 \emph on
7563 currying
7564 \emph default
7567 \family typewriter
7569 \family default
7571 \family typewriter
7573 \family default
7575 \family typewriter
7577 \family default
7578 , and 
7579 \family typewriter
7581 \family default
7582  curry the next three argument positions and the last argument, respectively.
7584 \family typewriter
7585 fill:with:
7586 \family default
7587  fills the N'th argument.
7588 \end_layout
7590 \begin_layout Description
7592 \family typewriter
7593 \begin_inset LatexCommand index
7594 name "`commutatively (macro)"
7596 \end_inset
7598 `commutatively
7599 \family default
7600  takes a literal 
7601 \family typewriter
7602 MethodDefinition
7603 \family default
7604  and defines it with two signatures, one reversed from the original definition,
7605  with the same body.
7606 \end_layout
7608 \begin_layout Subsection
7609 Symbols
7610 \end_layout
7612 \begin_layout Standard
7613 \begin_inset LatexCommand index
7614 name "Symbol (object)"
7616 \end_inset
7619 \begin_inset LatexCommand index
7620 name "symbol table"
7622 \end_inset
7625 \begin_inset LatexCommand index
7626 name "intern (message)"
7628 \end_inset
7631 \begin_inset LatexCommand index
7632 name "intern: (message)"
7634 \end_inset
7637 \begin_inset LatexCommand index
7638 name "name (message)"
7640 \end_inset
7643 \family typewriter
7644 Symbol
7645 \family default
7646 s in Slate are basically a large group of 
7647 \family typewriter
7648 String
7649 \family default
7650 s sorted by identity into a global table 
7651 \family typewriter
7652 Symbols
7653 \family default
7655  A new 
7656 \family typewriter
7657 Symbol
7658 \family default
7659  is created or identified by taking a 
7660 \family typewriter
7661 String
7662 \family default
7663  and calling the 
7664 \family typewriter
7665 intern
7666 \family default
7667  method on it (or alternately, the context message 
7668 \family typewriter
7669 intern:
7670 \family default
7672  Repeatedly 
7673 \family typewriter
7674 intern
7675 \family default
7676 'ing a same 
7677 \family typewriter
7678 String
7679 \family default
7680  value or 
7681 \family typewriter
7682 Symbol
7683 \family default
7684  object will return the exact same 
7685 \family typewriter
7686 Symbol
7687 \family default
7688  object.
7689  In order to perform 
7690 \family typewriter
7691 String
7692 \family default
7693  operations (see the 
7694 \family typewriter
7695 Sequence
7696 \family default
7697  and 
7698 \family typewriter
7699 String
7700 \family default
7701  sections
7702 \begin_inset LatexCommand ref
7703 reference "sub:Sequences"
7705 \end_inset
7707 ), the 
7708 \family typewriter
7709 Symbol
7710 \family default
7711  must be asked for its 
7712 \family typewriter
7713 name
7714 \family default
7715  which gives a separate 
7716 \family typewriter
7717 String
7718 \family default
7719  with its value; the results of these operations will still be 
7720 \family typewriter
7721 String
7722 \family default
7723 s and again must be 
7724 \family typewriter
7725 intern
7726 \family default
7727 'ed to create a new 
7728 \family typewriter
7729 Symbol
7730 \family default
7732 \end_layout
7734 \begin_layout Subsection
7735 Magnitudes and Numbers
7736 \end_layout
7738 \begin_layout Subsubsection
7739 Basic Types
7740 \begin_inset LatexCommand index
7741 name "basic types"
7743 \end_inset
7746 \begin_inset LatexCommand index
7747 name "types, basic"
7749 \end_inset
7752 \end_layout
7754 \begin_layout Description
7756 \family typewriter
7757 Magnitude
7758 \begin_inset LatexCommand index
7759 name "Magnitude (object)"
7761 \end_inset
7764 \family default
7765  the abstract protocol for linearly-comparable objects, following 
7766 \family typewriter
7768 \family default
7770 \family typewriter
7772 \family default
7774 \family typewriter
7776 \family default
7778 \family typewriter
7780 \family default
7781 , and 
7782 \family typewriter
7784 \family default
7786 \end_layout
7788 \begin_layout Description
7790 \family typewriter
7791 Number
7792 \begin_inset LatexCommand index
7793 name "Number (object)"
7795 \end_inset
7798 \family default
7799  the abstract type of dimensionless quantities.
7800 \end_layout
7802 \begin_layout Description
7804 \family typewriter
7805 Integer
7806 \begin_inset LatexCommand index
7807 name "Integer (object)"
7809 \end_inset
7812 \family default
7813  integral quantities, generally.
7814 \end_layout
7816 \begin_layout Description
7818 \family typewriter
7819 SmallInteger
7820 \begin_inset LatexCommand index
7821 name "SmallInteger (object)"
7823 \end_inset
7826 \family default
7827  machine-word-limited integer values (minus 1 bit for the immediate-value
7828  flag).
7829  Their normal protocol will not produce errors inconsistent with mathematic
7830  behavior of 
7831 \family typewriter
7832 Integer
7833 \family default
7834 s, however: instead of overflows, 
7835 \family typewriter
7836 BigInteger
7837 \family default
7838  objects of the appropriate value are returned.
7839 \end_layout
7841 \begin_layout Description
7843 \family typewriter
7844 BigInteger
7845 \begin_inset LatexCommand index
7846 name "BigInteger (object)"
7848 \end_inset
7851 \family default
7852  larger 
7853 \family typewriter
7854 Integer
7855 \family default
7856 s, implemented by wrapping 
7857 \family typewriter
7858 ByteArray
7859 \family default
7861 \begin_inset LatexCommand index
7862 name "ByteArray (object)"
7864 \end_inset
7866 s with the appropriate behavior.
7867 \end_layout
7869 \begin_layout Description
7871 \family typewriter
7872 Fraction
7873 \begin_inset LatexCommand index
7874 name "Fraction (object)"
7876 \end_inset
7879 \family default
7880  An exact representation of a quotient, or rational number.
7881 \end_layout
7883 \begin_layout Description
7885 \family typewriter
7886 Float
7887 \begin_inset LatexCommand index
7888 name "Float (object)"
7890 \end_inset
7893 \family default
7894  A low-level floating-point numeric representation, being inexact.
7895  Floats are currently only implemented as 
7896 \family typewriter
7897 SingleFloat
7898 \begin_inset LatexCommand index
7899 name "SingleFloat (object)"
7901 \end_inset
7904 \family default
7905 , a single-precision floating-point number representation.
7906 \end_layout
7908 \begin_layout Description
7910 \family typewriter
7911 Complex
7912 \begin_inset LatexCommand index
7913 name "Complex (object)"
7915 \end_inset
7918 \family default
7919  A complex number, similar to a pair of real numbers.
7920 \end_layout
7922 \begin_layout Subsubsection
7923 Basic Operations
7924 \end_layout
7926 \begin_layout Standard
7927 \begin_inset LatexCommand index
7928 name "operations, basic"
7930 \end_inset
7933 \begin_inset LatexCommand index
7934 name "basic operations"
7936 \end_inset
7939 \begin_inset LatexCommand index
7940 name "plus"
7942 \end_inset
7945 \begin_inset LatexCommand index
7946 name "+ (plus)"
7948 \end_inset
7951 \begin_inset LatexCommand index
7952 name "addition"
7954 \end_inset
7957 \begin_inset LatexCommand index
7958 name "operations, arithmetic"
7960 \end_inset
7963 \begin_inset LatexCommand index
7964 name "arithmetic operations"
7966 \end_inset
7969 \begin_inset LatexCommand index
7970 name "minus"
7972 \end_inset
7975 \begin_inset LatexCommand index
7976 name "subtraction"
7978 \end_inset
7981 \begin_inset LatexCommand index
7982 name "- (minus)"
7984 \end_inset
7987 \begin_inset LatexCommand index
7988 name "multiplication"
7990 \end_inset
7993 \begin_inset LatexCommand index
7994 name "times"
7996 \end_inset
7999 \begin_inset LatexCommand index
8000 name "asterisk"
8002 \end_inset
8005 \begin_inset LatexCommand index
8006 name "* (asterisk)"
8008 \end_inset
8011 \begin_inset LatexCommand index
8012 name "division"
8014 \end_inset
8017 \begin_inset LatexCommand index
8018 name "slash, forward"
8020 \end_inset
8023 \begin_inset LatexCommand index
8024 name "forward slash"
8026 \end_inset
8029 \begin_inset LatexCommand index
8030 name "\\char `\\/ (forward slash)"
8032 \end_inset
8034 All of the normal arithmetic operations (i.e.
8036 \family typewriter
8038 \family default
8040 \family typewriter
8042 \family default
8044 \family typewriter
8046 \family default
8048 \family typewriter
8050 \family default
8051 ) are supported primitively between elements of the same type.
8052  Type coercion has to be done entirely in code; no implicit coercions are
8053  performed by the virtual machine.
8054  However, the standard library includes methods which perform this coercion.
8055  The interpreter also transparently provides unlimited-size integers, although
8056  the bootstrapped system may not do so implicitly.
8057 \end_layout
8059 \begin_layout Standard
8060 The following are the rest of the primitive operations, given with an indication
8061  of their "signatures":
8062 \end_layout
8064 \begin_layout Description
8066 \family typewriter
8067 \begin_inset LatexCommand index
8068 name "raisedTo: (message)"
8070 \end_inset
8073 \begin_inset LatexCommand index
8074 name "exponentiation"
8076 \end_inset
8079 \begin_inset LatexCommand index
8080 name "power, raising to a"
8082 \end_inset
8084 Float\InsetSpace ~
8085 raisedTo:\InsetSpace ~
8086 Float
8087 \family default
8088  is simple floating-point exponentiation.
8089 \end_layout
8091 \begin_layout Description
8093 \family typewriter
8094 \begin_inset LatexCommand index
8095 name "as: (message)"
8097 \end_inset
8100 \begin_inset LatexCommand index
8101 name "conversion, number"
8103 \end_inset
8106 \begin_inset LatexCommand index
8107 name "number conversion"
8109 \end_inset
8111 Integer\InsetSpace ~
8112 as:\InsetSpace ~
8113 Float
8114 \family default
8115  extends an integer into a float.
8116 \end_layout
8118 \begin_layout Description
8120 \family typewriter
8121 Float\InsetSpace ~
8122 as:\InsetSpace ~
8123 Integer
8124 \family default
8125  truncates a float.
8126 \end_layout
8128 \begin_layout Description
8130 \family typewriter
8131 \begin_inset LatexCommand index
8132 name "bitOr: (message)"
8134 \end_inset
8137 \begin_inset LatexCommand index
8138 name "bit operations"
8140 \end_inset
8143 \begin_inset LatexCommand index
8144 name "operations, bit"
8146 \end_inset
8148 Integer\InsetSpace ~
8149 bitOr:\InsetSpace ~
8150 Integer
8151 \family default
8152  performs bitwise logical 
8153 \shape smallcaps
8155 \shape default
8157 \end_layout
8159 \begin_layout Description
8161 \family typewriter
8162 \begin_inset LatexCommand index
8163 name "bitXor: (message)"
8165 \end_inset
8167 Integer\InsetSpace ~
8168 bitXor:\InsetSpace ~
8169 Integer
8170 \family default
8171  performs bitwise logical 
8172 \shape smallcaps
8174 \shape default
8176 \end_layout
8178 \begin_layout Description
8180 \family typewriter
8181 \begin_inset LatexCommand index
8182 name "bitAnd: (message)"
8184 \end_inset
8186 Integer\InsetSpace ~
8187 bitAnd:\InsetSpace ~
8188 Integer
8189 \family default
8190  performs bitwise logical 
8191 \shape smallcaps
8193 \shape default
8195 \end_layout
8197 \begin_layout Description
8199 \family typewriter
8200 \begin_inset LatexCommand index
8201 name "bitShift: (message)"
8203 \end_inset
8205 Integer\InsetSpace ~
8206 bitShift:\InsetSpace ~
8207 Integer
8208 \family default
8209  performs bitwise logical right-shift (left-shift if negative).
8210 \end_layout
8212 \begin_layout Description
8214 \family typewriter
8215 \begin_inset LatexCommand index
8216 name "bitNot (message)"
8218 \end_inset
8220 Integer\InsetSpace ~
8221 bitNot
8222 \family default
8223  performs bitwise logical 
8224 \shape smallcaps
8226 \shape default
8228 \end_layout
8230 \begin_layout Description
8232 \family typewriter
8233 \begin_inset LatexCommand index
8234 name ">> (message)"
8236 \end_inset
8238 Integer\InsetSpace ~
8239 >>\InsetSpace ~
8240 Integer
8241 \family default
8242  performs logical right-shift.
8243 \end_layout
8245 \begin_layout Description
8247 \family typewriter
8248 \begin_inset LatexCommand index
8249 name "<< (message)"
8251 \end_inset
8253 Integer\InsetSpace ~
8254 <<\InsetSpace ~
8255 Integer
8256 \family default
8257  performs logical left-shift.
8258 \end_layout
8260 \begin_layout Description
8262 \family typewriter
8263 \begin_inset LatexCommand index
8264 name "quo: (message)"
8266 \end_inset
8269 \begin_inset LatexCommand index
8270 name "quotient"
8272 \end_inset
8275 \begin_inset LatexCommand index
8276 name "division, integer"
8278 \end_inset
8281 \begin_inset LatexCommand index
8282 name "integer division"
8284 \end_inset
8286 Integer\InsetSpace ~
8287 quo:\InsetSpace ~
8288 Integer
8289 \family default
8290  returns a quotient (integer division).
8291 \end_layout
8293 \begin_layout Standard
8294 \begin_inset LatexCommand index
8295 name "mod: (mesage)"
8297 \end_inset
8300 \begin_inset LatexCommand index
8301 name "reciprocal: (message)"
8303 \end_inset
8306 \begin_inset LatexCommand index
8307 name "min: (message)"
8309 \end_inset
8312 \begin_inset LatexCommand index
8313 name "max: (message)"
8315 \end_inset
8318 \begin_inset LatexCommand index
8319 name "between:and: (message)"
8321 \end_inset
8324 \begin_inset LatexCommand index
8325 name "lcm: (message)"
8327 \end_inset
8330 \begin_inset LatexCommand index
8331 name "gcd: (message)"
8333 \end_inset
8336 \begin_inset LatexCommand index
8337 name "Fraction (object)"
8339 \end_inset
8341 Many more useful methods are defined, such as 
8342 \family typewriter
8343 mod:
8344 \family default
8346 \family typewriter
8347 reciprocal
8348 \family default
8350 \family typewriter
8351 min:
8352 \family default
8354 \family typewriter
8355 max:
8356 \family default
8358 \family typewriter
8359 between:and:
8360 \family default
8362 \family typewriter
8363 lcm:
8364 \family default
8365 , and 
8366 \family typewriter
8367 gcd:
8368 \family default
8370  Slate also works with 
8371 \family typewriter
8372 Fractions
8373 \family default
8374  when dividing Integers, keeping them lazily reduced.
8375 \end_layout
8377 \begin_layout Subsubsection
8378 Non-core Operations
8379 \end_layout
8381 \begin_layout Description
8383 \family typewriter
8384 \begin_inset LatexCommand index
8385 name "zero (message)"
8387 \end_inset
8389 zero
8390 \family default
8391  The zero element for the type of number.
8392 \end_layout
8394 \begin_layout Description
8396 \family typewriter
8397 \begin_inset LatexCommand index
8398 name "isZero (message)"
8400 \end_inset
8402 isZero
8403 \family default
8404  Whether the number is the zero element for its type.
8405 \end_layout
8407 \begin_layout Description
8409 \family typewriter
8410 \begin_inset LatexCommand index
8411 name "isPositive (message)"
8413 \end_inset
8416 \begin_inset LatexCommand index
8417 name "isNegative (message)"
8419 \end_inset
8421 isPositive
8422 \family default
8424 \family typewriter
8425 isNegative
8426 \family default
8427  Whether it's positive or negative.
8428 \end_layout
8430 \begin_layout Description
8432 \family typewriter
8433 \begin_inset LatexCommand index
8434 name "abs (message)"
8436 \end_inset
8439 \family default
8440  The absolute value of the number.
8441 \end_layout
8443 \begin_layout Description
8445 \family typewriter
8446 \begin_inset LatexCommand index
8447 name "sign (message)"
8449 \end_inset
8451 sign
8452 \family default
8453  The sign of the number.
8454 \end_layout
8456 \begin_layout Description
8458 \family typewriter
8459 \begin_inset LatexCommand index
8460 name "negated (message)"
8462 \end_inset
8464 negated
8465 \family default
8466  Returns 
8467 \emph on
8469 \emph default
8470  for 
8471 \emph on
8473 \emph default
8475 \end_layout
8477 \begin_layout Description
8479 \family typewriter
8480 \begin_inset LatexCommand index
8481 name "gcd: (message)"
8483 \end_inset
8485 gcd:
8486 \family default
8487  Greatest common divisor.
8488 \end_layout
8490 \begin_layout Description
8492 \family typewriter
8493 \begin_inset LatexCommand index
8494 name "lcm: (message)"
8496 \end_inset
8498 lcm:
8499 \family default
8500  Least common multiple.
8501 \end_layout
8503 \begin_layout Description
8505 \family typewriter
8506 \begin_inset LatexCommand index
8507 name "factorial (message)"
8509 \end_inset
8511 factorial
8512 \family default
8513  Factorial.
8514 \end_layout
8516 \begin_layout Description
8518 \family typewriter
8519 \begin_inset LatexCommand index
8520 name "mod: (message)"
8522 \end_inset
8525 \begin_inset LatexCommand index
8526 name "rem: (message)"
8528 \end_inset
8531 \begin_inset LatexCommand index
8532 name "quo: (message)"
8534 \end_inset
8536 mod:
8537 \family default
8539 \family typewriter
8540 rem:
8541 \family default
8543 \family typewriter
8544 quo:
8545 \family default
8546  Modulo division, remainder, and quotient.
8547 \end_layout
8549 \begin_layout Description
8551 \family typewriter
8552 \begin_inset LatexCommand index
8553 name "reciprocal (message)"
8555 \end_inset
8557 reciprocal
8558 \family default
8559  Constructs a new fraction reciprocal.
8560 \end_layout
8562 \begin_layout Description
8564 \family typewriter
8565 \begin_inset LatexCommand index
8566 name "min: (message)"
8568 \end_inset
8570 min:
8571 \family default
8572  The lesser of the arguments.
8573  The least in cases of 
8574 \family typewriter
8575 min:min:
8576 \family default
8578 \end_layout
8580 \begin_layout Description
8582 \family typewriter
8583 \begin_inset LatexCommand index
8584 name "max: (message)"
8586 \end_inset
8588 max:
8589 \family default
8590  The greater of the arguments.
8591  The greatest in cases of 
8592 \family typewriter
8593 max:max:
8594 \family default
8596 \end_layout
8598 \begin_layout Description
8600 \family typewriter
8601 \begin_inset LatexCommand index
8602 name "between:and: (message)"
8604 \end_inset
8606 a\InsetSpace ~
8607 between:\InsetSpace ~
8608 b\InsetSpace ~
8609 and:\InsetSpace ~
8611 \family default
8612  Whether 
8613 \family typewriter
8615 \family default
8616  is between 
8617 \family typewriter
8619 \family default
8620  and 
8621 \family typewriter
8623 \family default
8625 \end_layout
8627 \begin_layout Description
8629 \family typewriter
8630 \begin_inset LatexCommand index
8631 name "truncated (message)"
8633 \end_inset
8636 \begin_inset LatexCommand index
8637 name "fractionPart (message)"
8639 \end_inset
8641 truncated
8642 \family default
8644 \family typewriter
8645 fractionPart
8646 \family default
8647  answers the greatest integer less than the number, and the corresponding
8648  difference as a fraction (or a float for 
8649 \family typewriter
8650 Float
8651 \family default
8653 \end_layout
8655 \begin_layout Description
8657 \family typewriter
8658 \begin_inset LatexCommand index
8659 name "reduced (message)"
8661 \end_inset
8663 reduced
8664 \family default
8665  Only defined on 
8666 \family typewriter
8667 Fraction
8668 \family default
8669 , this is the lazily-applied reducer; it will be invoked automatically for
8670  arithmetic operations as necessary, but is useful when only the reduced
8671  form is needed.
8672 \end_layout
8674 \begin_layout Description
8676 \family typewriter
8677 \begin_inset LatexCommand index
8678 name "readFrom: (message)"
8680 \end_inset
8682 readFrom:
8683 \family default
8684  This takes a 
8685 \family typewriter
8686 String
8687 \family default
8688  or a 
8689 \family typewriter
8690 Stream
8691 \family default
8692  with compatible contents and parses the first available data as the type
8693  of the argument.
8694  If the return value is not the same as the argument type, an error is signalled
8695  (beyond any normal parsing errors).
8696  If the value is valid, it is returned; otherwise only 
8697 \family typewriter
8699 \family default
8700  will be available.
8701 \end_layout
8703 \begin_layout Subsubsection
8704 Limit Numerics
8705 \end_layout
8707 \begin_layout Description
8709 \family typewriter
8710 \begin_inset LatexCommand index
8711 name "limits, numeric"
8713 \end_inset
8716 \begin_inset LatexCommand index
8717 name "numeric limits"
8719 \end_inset
8722 \begin_inset LatexCommand index
8723 name "PositiveInfinity (object)"
8725 \end_inset
8727 PositiveInfinity
8728 \family default
8729  is greater than any other 
8730 \family typewriter
8731 Magnitude
8732 \family default
8734 \end_layout
8736 \begin_layout Description
8738 \family typewriter
8739 \begin_inset LatexCommand index
8740 name "NegativeInfinity (object)"
8742 \end_inset
8744 NegativeInfinity
8745 \family default
8746  is lesser than any other 
8747 \family typewriter
8748 Magnitude
8749 \family default
8751 \end_layout
8753 \begin_layout Description
8755 \family typewriter
8756 \begin_inset LatexCommand index
8757 name "LargeUnbound (object)"
8759 \end_inset
8761 LargeUnbounded
8762 \family default
8763  A 
8764 \family typewriter
8765 Magnitude
8766 \family default
8767  designed to represent non-infinite, but non-bounded (
8768 \begin_inset Quotes eld
8769 \end_inset
8771 as large as you like
8772 \begin_inset Quotes erd
8773 \end_inset
8775 ) quantities.
8776 \end_layout
8778 \begin_layout Description
8780 \family typewriter
8781 \begin_inset LatexCommand index
8782 name "PositiveEpsilon (object)"
8784 \end_inset
8786 PositiveEpsilon
8787 \family default
8788  is as small as you like, but positive and greater than zero.
8789 \end_layout
8791 \begin_layout Description
8793 \family typewriter
8794 \begin_inset LatexCommand index
8795 name "NegativeEpsilon (message)"
8797 \end_inset
8799 NegativeEpsilon
8800 \family default
8801  is as small as you like, but negative and lesser than zero.
8802 \end_layout
8804 \begin_layout Subsubsection
8805 Dimensioned Units
8806 \end_layout
8808 \begin_layout Standard
8809 \begin_inset LatexCommand index
8810 name "SI units"
8812 \end_inset
8815 \begin_inset LatexCommand index
8816 name "dimensioned units"
8818 \end_inset
8821 \begin_inset LatexCommand index
8822 name "units, dimensioned"
8824 \end_inset
8827 \begin_inset LatexCommand index
8828 name "units, SI"
8830 \end_inset
8833 \begin_inset LatexCommand index
8834 name "English units"
8836 \end_inset
8839 \begin_inset LatexCommand index
8840 name "units, English"
8842 \end_inset
8844 There is an entire system for handling dimensioned units and their various
8845  combinations and mathematical operations.
8846  There is included support for SI units, and common English units; furthermore,
8847  any object may conceivably be used as a base unit.
8848  See the '
8849 \family typewriter
8850 src/lib/dimensioned.slate
8851 \family default
8852 ' file for an overview.
8853 \end_layout
8855 \begin_layout Subsection
8856 Collections
8857 \end_layout
8859 \begin_layout Standard
8860 \begin_inset LatexCommand index
8861 name "collections"
8863 \end_inset
8866 \begin_inset LatexCommand index
8867 name "Collection (object)"
8869 \end_inset
8872 \begin_inset LatexCommand index
8873 name "Mapping (object)"
8875 \end_inset
8878 \begin_inset LatexCommand index
8879 name "ExtensibleCollection (object)"
8881 \end_inset
8884 \begin_inset LatexCommand index
8885 name "Sequence (object)"
8887 \end_inset
8890 \begin_inset LatexCommand index
8891 name "LinkedCollection (object)"
8893 \end_inset
8896 \begin_inset LatexCommand index
8897 name "Bag (object)"
8899 \end_inset
8902 \begin_inset LatexCommand index
8903 name "NoDuplicatesCollection (object)"
8905 \end_inset
8908 \begin_inset LatexCommand index
8909 name "ExtensibleSequence (object)"
8911 \end_inset
8914 \begin_inset LatexCommand index
8915 name "LinkedList (object)"
8917 \end_inset
8920 \begin_inset LatexCommand index
8921 name "Tree (object)"
8923 \end_inset
8926 \begin_inset LatexCommand index
8927 name "Graph (object)"
8929 \end_inset
8932 \begin_inset LatexCommand index
8933 name "Tuple (object)"
8935 \end_inset
8938 \begin_inset LatexCommand index
8939 name "Cord (object)"
8941 \end_inset
8944 \begin_inset LatexCommand index
8945 name "Set (object)"
8947 \end_inset
8950 \begin_inset LatexCommand index
8951 name "SortedSequence (object)"
8953 \end_inset
8956 \begin_inset LatexCommand index
8957 name "Array (object)"
8959 \end_inset
8962 \begin_inset LatexCommand index
8963 name "ByteArray (object)"
8965 \end_inset
8968 \begin_inset LatexCommand index
8969 name "String (object)"
8971 \end_inset
8974 \begin_inset LatexCommand index
8975 name "Range (object)"
8977 \end_inset
8980 \begin_inset LatexCommand index
8981 name "Buffer (object)"
8983 \end_inset
8986 \begin_inset LatexCommand index
8987 name "Dictionary (object)"
8989 \end_inset
8992 \begin_inset LatexCommand index
8993 name "SortedSet (object)"
8995 \end_inset
8998 \begin_inset LatexCommand index
8999 name "InsertionSequence (object)"
9001 \end_inset
9003 Slate's collection hierarchy makes use of composing multiple behaviors (via
9004  inheritance) to provide a collection system that can be reasoned about
9005  with greater certainty, and that can be extended more easily than other
9006  object-oriented languages' collection types.
9007  Primarily Slate collections are mutable, which means that basic modifications
9008  occur destructively on the collection object.
9009 \end_layout
9011 \begin_layout Standard
9012 Figure 
9013 \begin_inset LatexCommand ref
9014 reference "cap:Collections-delegation"
9016 \end_inset
9018  shows the overview of the collection types, and how their inheritance is
9019  patterned.
9020 \end_layout
9022 \begin_layout Standard
9023 \begin_inset Float figure
9024 placement htbp
9025 wide true
9026 sideways false
9027 status open
9029 \begin_layout Standard
9030 \begin_inset VSpace defskip
9031 \end_inset
9034 \end_layout
9036 \begin_layout Standard
9037 \align center
9038 \begin_inset Graphics
9039         filename collection-web.eps
9041 \end_inset
9044 \end_layout
9046 \begin_layout Standard
9047 \begin_inset VSpace defskip
9048 \end_inset
9051 \end_layout
9053 \begin_layout Standard
9054 \begin_inset Caption
9056 \begin_layout Standard
9057 \begin_inset LatexCommand label
9058 name "cap:Collections-delegation"
9060 \end_inset
9062 Core Collections Inheritance
9063 \end_layout
9065 \end_inset
9068 \end_layout
9070 \end_inset
9073 \end_layout
9075 \begin_layout Standard
9076 All collections support a minimal set of methods, including support for
9077  basic internal iteration and testing.
9078  The following are representative core methods, and are by no means the
9079  limit of collection features:
9080 \end_layout
9082 \begin_layout Paragraph
9083 \begin_inset LatexCommand index
9084 name "testing, collections"
9086 \end_inset
9089 \begin_inset LatexCommand index
9090 name "collection testing"
9092 \end_inset
9094 Testing Methods
9095 \end_layout
9097 \begin_layout Description
9099 \family typewriter
9100 \begin_inset LatexCommand index
9101 name "isEmpty (message)"
9103 \end_inset
9105 isEmpty
9106 \family default
9107  answers whether or not the collection has any elements in it.
9108 \end_layout
9110 \begin_layout Description
9112 \family typewriter
9113 \begin_inset LatexCommand index
9114 name "includes: (message)"
9116 \end_inset
9118 includes:
9119 \family default
9120  answers whether the collection contains the object.
9121 \end_layout
9123 \begin_layout Paragraph
9124 \begin_inset LatexCommand index
9125 name "properties, collections"
9127 \end_inset
9130 \begin_inset LatexCommand index
9131 name "collection properties"
9133 \end_inset
9135 Properties
9136 \end_layout
9138 \begin_layout Description
9140 \family typewriter
9141 \begin_inset LatexCommand index
9142 name "size (message)"
9144 \end_inset
9146 size
9147 \family default
9148  answers the number of elements in it.
9149  This is often calculated dynamically for extensible collections, so it's
9150  often useful to cache it in a calling method.
9151 \end_layout
9153 \begin_layout Description
9155 \family typewriter
9156 \begin_inset LatexCommand index
9157 name "capacity (message)"
9159 \end_inset
9161 capacity
9162 \family default
9163  answers the size that the collection's implementation is currently ready
9164  for.
9165 \end_layout
9167 \begin_layout Paragraph
9168 \begin_inset LatexCommand index
9169 name "creation, collections"
9171 \end_inset
9174 \begin_inset LatexCommand index
9175 name "collection creation"
9177 \end_inset
9179 Making new collections
9180 \end_layout
9182 \begin_layout Description
9184 \family typewriter
9185 \begin_inset LatexCommand index
9186 name "newSize: (message)"
9188 \end_inset
9190 new\InsetSpace ~
9191 &capacity:
9192 \family default
9193  answers a new (empty) collection of the same type that is sized to the
9194  optional argument or a sensible default per type.
9195 \end_layout
9197 \begin_layout Description
9199 \family typewriter
9200 \begin_inset LatexCommand index
9201 name "newSizeOf: (message)"
9203 \end_inset
9205 newSizeOf:
9206 \family default
9207  answers a new collection of the same type that is sized to same size that
9208  the argument has.
9209 \end_layout
9211 \begin_layout Description
9213 \family typewriter
9214 \begin_inset LatexCommand index
9215 name "as:newWithAll: (message)"
9217 \end_inset
9220 \begin_inset LatexCommand index
9221 name "newWithAll: (message)"
9223 \end_inset
9226 \family default
9227 \emph on
9228 \InsetSpace ~
9230 \family typewriter
9231 \emph default
9232 \InsetSpace ~
9234 \series bold
9235 newWithAll:
9236 \family default
9237 \series default
9238  has extensive support in the collection types to produce collections of
9239  the type of the second with the contents of the first collection (
9240 \emph on
9241 vice versa
9242 \emph default
9243  for 
9244 \family typewriter
9245 newWithAll:
9246 \family default
9247  arguments).
9248 \end_layout
9250 \begin_layout Paragraph
9251 \begin_inset LatexCommand index
9252 name "collection iteration"
9254 \end_inset
9257 \begin_inset LatexCommand index
9258 name "iteration, collections"
9260 \end_inset
9262 Iterating
9263 \end_layout
9265 \begin_layout Description
9267 \family typewriter
9268 \begin_inset LatexCommand index
9269 name "do: (message)"
9271 \end_inset
9274 \begin_inset LatexCommand index
9275 name "each: (message)"
9277 \end_inset
9280 \family default
9281  executes a block with 
9282 \family typewriter
9283 :each
9284 \family default
9285  (the idiomatic input slot for iterating) of the collection's elements in
9286  turn.
9287  It answers the original collection.
9288 \end_layout
9290 \begin_layout Description
9292 \family typewriter
9293 \begin_inset LatexCommand index
9294 name "collect: (message)"
9296 \end_inset
9298 collect:
9299 \family default
9300  also takes a block, but answers a collection with all the results of those
9301  block-applications put into a new collection of the appropriate type.
9302 \end_layout
9304 \begin_layout Description
9306 \family typewriter
9307 \begin_inset LatexCommand index
9308 name "select: (message)"
9310 \end_inset
9312 select:
9313 \family default
9314  takes a block that answers a 
9315 \family typewriter
9316 Boolean
9317 \family default
9318  and answers a new collection of the elements that the block filters (answers
9320 \family typewriter
9321 True
9322 \family default
9324 \end_layout
9326 \begin_layout Description
9328 \family typewriter
9329 \begin_inset LatexCommand index
9330 name "reject: (message)"
9332 \end_inset
9334 reject:
9335 \family default
9336  performs the logical opposite of 
9337 \family typewriter
9338 select:
9339 \family default
9340 , answering elements for which the block answers 
9341 \family typewriter
9342 False
9343 \family default
9345 \end_layout
9347 \begin_layout Description
9349 \family typewriter
9350 \begin_inset LatexCommand index
9351 name "inject:into: (message)"
9353 \end_inset
9355 inject:\InsetSpace ~
9356 init\InsetSpace ~
9357 into:\InsetSpace ~
9358 accumulator
9359 \family default
9360  takes a two-argument accumulation block and applies it across the collection's
9361  elements.
9362  The initial value given becomes the first argument, and is replaced through
9363  the iterations with the result of the block.
9364 \end_layout
9366 \begin_layout Description
9368 \family typewriter
9369 \begin_inset LatexCommand index
9370 name "reduce: (message)"
9372 \end_inset
9374 reduce:
9375 \family default
9376  takes a two-argument block and performs the same action as 
9377 \family typewriter
9378 inject:into:
9379 \family default
9380  only using one of the collection's elements as an initial value.
9381 \end_layout
9383 \begin_layout Description
9384 \begin_inset LatexCommand index
9385 name "project: (message)"
9387 \end_inset
9390 \family typewriter
9391 project:
9392 \family default
9393  takes a block, answering a 
9394 \family typewriter
9395 Dictionary
9396 \family default
9397  or 
9398 \family typewriter
9399 Mapping
9400 \family default
9401  in general with each argument (member of the original collection) mapped
9402  to the result of applying the block to it.
9403 \end_layout
9405 \begin_layout Subsubsection
9406 Extensible Collections
9407 \end_layout
9409 \begin_layout Standard
9410 \begin_inset LatexCommand index
9411 name "extensible collections"
9413 \end_inset
9416 \begin_inset LatexCommand index
9417 name "collections, extensible"
9419 \end_inset
9422 \begin_inset LatexCommand index
9423 name "ExtensibleCollection (object)"
9425 \end_inset
9427 Collections derived from 
9428 \family typewriter
9429 ExtensibleCollection
9430 \family default
9431  can be modified by adding or removing elements in various ways.
9432  The core protocol is:
9433 \end_layout
9435 \begin_layout Description
9437 \family typewriter
9438 \begin_inset LatexCommand index
9439 name "add: (message)"
9441 \end_inset
9443 add:
9444 \family default
9445  inserts the given object into the collection.
9446 \end_layout
9448 \begin_layout Description
9450 \family typewriter
9451 \begin_inset LatexCommand index
9452 name "remove: (message)"
9454 \end_inset
9456 remove:
9457 \family default
9458  removes an object equal to the given one from the collection.
9459 \end_layout
9461 \begin_layout Description
9463 \family typewriter
9464 \begin_inset LatexCommand index
9465 name "addAll: (message)"
9467 \end_inset
9469 addAll:
9470 \family default
9471  inserts all elements from the first collection contained in the second.
9472 \end_layout
9474 \begin_layout Description
9476 \family typewriter
9477 \begin_inset LatexCommand index
9478 name "removeAll: (message)"
9480 \end_inset
9482 removeAll:
9483 \family default
9484  removes all elements from the first collection contained in the second.
9485 \end_layout
9487 \begin_layout Description
9489 \family typewriter
9490 \begin_inset LatexCommand index
9491 name "clear (message)"
9493 \end_inset
9495 clear
9496 \family default
9497  removes all the elements from the collection.
9498 \end_layout
9500 \begin_layout Subsubsection
9501 Sequences
9502 \begin_inset LatexCommand label
9503 name "sub:Sequences"
9505 \end_inset
9508 \end_layout
9510 \begin_layout Standard
9512 \family typewriter
9513 \begin_inset LatexCommand index
9514 name "Sequence (object)"
9516 \end_inset
9519 \begin_inset LatexCommand index
9520 name "Mapping (object)"
9522 \end_inset
9524 Sequences
9525 \family default
9526  are 
9527 \family typewriter
9528 Mappings
9529 \family default
9530  from a range of natural numbers to some objects, sometimes restricted to
9531  a given type.
9532  Slate sequences are all addressed from a base of 0.
9533 \end_layout
9535 \begin_layout Description
9537 \family typewriter
9538 \begin_inset LatexCommand index
9539 name "at: (message)"
9541 \end_inset
9544 \family default
9545  answers the element at the index given.
9546 \end_layout
9548 \begin_layout Description
9550 \family typewriter
9551 \begin_inset LatexCommand index
9552 name "at:put: (message)"
9554 \end_inset
9556 at:put:
9557 \family default
9558  replaces the element at the index given with the object that is the last
9559  argument.
9560 \end_layout
9562 \begin_layout Description
9564 \family typewriter
9565 \begin_inset LatexCommand index
9566 name "doWithIndex: (message)"
9568 \end_inset
9570 doWithIndex:
9571 \family default
9572  operates as do:, but applying the block with both the element as first
9573  argument and the index of the element in the Sequence as the second argument.
9574 \end_layout
9576 \begin_layout Paragraph
9577 Arrays
9578 \end_layout
9580 \begin_layout Standard
9582 \family typewriter
9583 \begin_inset LatexCommand index
9584 name "Array (object)"
9586 \end_inset
9589 \begin_inset LatexCommand index
9590 name "WordArray (object)"
9592 \end_inset
9595 \begin_inset LatexCommand index
9596 name "ByteArray (object)"
9598 \end_inset
9601 \begin_inset LatexCommand index
9602 name "String (object)"
9604 \end_inset
9606 Arrays
9607 \family default
9608  are fixed-length sequences of any kind of object and are supported primitively.
9609  Various parameter types of 
9610 \family typewriter
9611 Array
9612 \family default
9613  are supported primitively, such as 
9614 \family typewriter
9615 WordArray
9616 \family default
9618 \family typewriter
9619 ByteArray
9620 \family default
9621 , and 
9622 \family typewriter
9623 String
9624 \family default
9626 \end_layout
9628 \begin_layout Paragraph
9629 Vectors
9630 \end_layout
9632 \begin_layout Standard
9634 \family typewriter
9635 \begin_inset LatexCommand index
9636 name "Vector (object)"
9638 \end_inset
9641 \begin_inset LatexCommand index
9642 name "Tuple (object)"
9644 \end_inset
9647 \begin_inset LatexCommand index
9648 name "Point (object)"
9650 \end_inset
9653 \begin_inset LatexCommand index
9654 name "comma"
9656 \end_inset
9659 \begin_inset LatexCommand index
9660 name ", (comma)"
9662 \end_inset
9664 Vectors
9665 \family default
9666  and 
9667 \family typewriter
9668 Tuples
9669 \family default
9670  are fixed-length sequences constructed for geometrical purposes.
9672 \family typewriter
9673 Points
9674 \family default
9675  happen to be 
9676 \family typewriter
9677 Tuples
9678 \family default
9680  The constructor message for these types is 
9681 \begin_inset Quotes eld
9682 \end_inset
9685 \family typewriter
9687 \family default
9689 \begin_inset Quotes erd
9690 \end_inset
9693 \end_layout
9695 \begin_layout Paragraph
9696 Subsequences / Slices
9697 \end_layout
9699 \begin_layout Standard
9701 \family typewriter
9702 \begin_inset LatexCommand index
9703 name "Subsequence (object)"
9705 \end_inset
9707 Subsequences
9708 \family default
9709  allow one to treat a segment of a sequence as a separate sequence with
9710  its own addressing scheme; however, modifying the subsequence will cause
9711  the original to be modified.
9712 \end_layout
9714 \begin_layout Paragraph
9715 Cords
9716 \end_layout
9718 \begin_layout Standard
9720 \family typewriter
9721 \begin_inset LatexCommand index
9722 name "Cord (object)"
9724 \end_inset
9727 \begin_inset LatexCommand index
9728 name "semicolon"
9730 \end_inset
9733 \begin_inset LatexCommand index
9734 name "; (semicolon)"
9736 \end_inset
9739 \begin_inset LatexCommand index
9740 name ";; (message)"
9742 \end_inset
9744 Cords
9745 \family default
9746  are a non-copying representation of a concatenation of 
9747 \family typewriter
9748 Sequence
9749 \family default
9751  Normal concatenation of Sequences is performed with the 
9752 \family typewriter
9754 \family default
9755  method, and results in copying both of the arguments into a new 
9756 \family typewriter
9757 Sequence
9758 \family default
9759  of the appropriate type; the 
9760 \family typewriter
9762 \family default
9763  method will construct a 
9764 \family typewriter
9765 Cord
9766 \family default
9767  instead.
9768  They efficiently implement accessing via 
9769 \family typewriter
9771 \family default
9772  and iteration via 
9773 \family typewriter
9775 \family default
9776 , and 
9777 \family typewriter
9778 Cord\InsetSpace ~
9779 as:\InsetSpace ~
9780 Sequence
9781 \family default
9782  will 
9783 \begin_inset Quotes eld
9784 \end_inset
9786 flatten
9787 \begin_inset Quotes erd
9788 \end_inset
9790  the 
9791 \family typewriter
9792 Cord
9793 \family default
9794  into a 
9795 \family typewriter
9796 Sequence
9797 \family default
9799 \end_layout
9801 \begin_layout Paragraph
9802 Extensible and Sorted Sequences
9803 \end_layout
9805 \begin_layout Standard
9806 \begin_inset LatexCommand index
9807 name "ExtensibleSequence (object)"
9809 \end_inset
9811 An 
9812 \family typewriter
9813 ExtensibleSequence
9814 \family default
9815  is an extensible 
9816 \family typewriter
9817 Sequence
9818 \family default
9819  with some special methods to treat both ends as queues.
9820  It provides the following additional protocol:
9821 \end_layout
9823 \begin_layout Description
9825 \family typewriter
9826 \begin_inset LatexCommand index
9827 name "addFirst: (message)"
9829 \end_inset
9831 addFirst:
9832 \family default
9833  inserts the given object at the beginning of the sequence.
9834 \end_layout
9836 \begin_layout Description
9838 \family typewriter
9839 \begin_inset LatexCommand index
9840 name "addLast: (message)"
9842 \end_inset
9844 addLast:
9845 \family default
9846  inserts the given object at the end of the sequence.
9847 \end_layout
9849 \begin_layout Description
9851 \family typewriter
9852 \begin_inset LatexCommand index
9853 name "add: (message)"
9855 \end_inset
9857 add:
9858 \family default
9859  inserts the given object at the end of the sequence (it's addLast:).
9860 \end_layout
9862 \begin_layout Description
9864 \family typewriter
9865 \begin_inset LatexCommand index
9866 name "first: (message)"
9868 \end_inset
9870 first:
9871 \family default
9872  answers a sequence of the first N elements.
9873 \end_layout
9875 \begin_layout Description
9877 \family typewriter
9878 \begin_inset LatexCommand index
9879 name "last: (message)"
9881 \end_inset
9883 last:
9884 \family default
9885  answers a sequence of the final N elements.
9886 \end_layout
9888 \begin_layout Description
9890 \family typewriter
9891 \begin_inset LatexCommand index
9892 name "removeFirst (message)"
9894 \end_inset
9896 removeFirst
9897 \family default
9898  removes the first element from the sequence.
9899 \end_layout
9901 \begin_layout Description
9903 \family typewriter
9904 \begin_inset LatexCommand index
9905 name "removeLast (message)"
9907 \end_inset
9909 removeLast
9910 \family default
9911  removes the final element from the sequence.
9912 \end_layout
9914 \begin_layout Standard
9915 \begin_inset LatexCommand index
9916 name "SortedSequence (object)"
9918 \end_inset
9921 \begin_inset LatexCommand index
9922 name "remove: (message)"
9924 \end_inset
9927 \begin_inset LatexCommand index
9928 name "Heap (object)"
9930 \end_inset
9933 \family typewriter
9934 SortedSequence
9935 \family default
9936  behaves similarly except that it will arrange for its members to remain
9937  sorted according to a block closure that compares two individual elements;
9938  as a result, it should not be manipulated except via 
9939 \family typewriter
9940 add:
9941 \family default
9942  and 
9943 \family typewriter
9944 remove:
9945 \family default
9946  since it maintains its own ordering.
9947  A 
9948 \family typewriter
9949 Heap
9950 \family default
9951  is a 
9952 \family typewriter
9953 SortedSequence
9954 \family default
9955  designed for collecting elements in arbitrary order, and removing the first
9956  elements.
9957 \end_layout
9959 \begin_layout Paragraph
9960 Stacks
9961 \end_layout
9963 \begin_layout Standard
9964 \begin_inset LatexCommand index
9965 name "Stack (object)"
9967 \end_inset
9970 \begin_inset LatexCommand index
9971 name "push: (message)"
9973 \end_inset
9976 \begin_inset LatexCommand index
9977 name "pop (message)"
9979 \end_inset
9982 \begin_inset LatexCommand index
9983 name "top (message)"
9985 \end_inset
9988 \family typewriter
9989 Stack
9990 \family default
9991  is an 
9992 \family typewriter
9993 ExtensibleSequence
9994 \family default
9995  augmented with methods to honor the stack abstraction: 
9996 \family typewriter
9997 push:
9998 \family default
10000 \family typewriter
10002 \family default
10004 \family typewriter
10006 \family default
10007 , etc.
10008 \end_layout
10010 \begin_layout Paragraph
10011 Ranges
10012 \end_layout
10014 \begin_layout Standard
10015 \begin_inset LatexCommand index
10016 name "Range (object)"
10018 \end_inset
10021 \family typewriter
10022 Range
10023 \family default
10024  is a 
10025 \family typewriter
10026 Sequence
10027 \family default
10028  of 
10029 \family typewriter
10030 Number
10031 \family default
10032 s between two values, that is ordered consecutively and has some stepping
10033  value; they include the 
10034 \family typewriter
10035 start
10036 \family default
10037  value and also the 
10038 \family typewriter
10040 \family default
10041  value unless the stepping doesn't lead to the 
10042 \family typewriter
10044 \family default
10045  value exactly, in which case the last value is the greatest value in the
10046  sequence that is still before the end marker value.
10047  Creating ranges is identical to the numeric iteration protocol in 
10048 \begin_inset LatexCommand ref
10049 reference "sub:Looping"
10051 \end_inset
10053 , without the final 
10054 \family typewriter
10056 \family default
10057  keyword, and sending the 
10058 \family typewriter
10060 \family default
10061  message to a 
10062 \family typewriter
10063 Range
10064 \family default
10065  performs the identical function.
10066 \end_layout
10068 \begin_layout Paragraph
10069 Buffers
10070 \end_layout
10072 \begin_layout Standard
10073 \begin_inset LatexCommand index
10074 name "Buffer (object)"
10076 \end_inset
10079 \begin_inset LatexCommand index
10080 name "RingBuffer (object)"
10082 \end_inset
10085 \begin_inset LatexCommand index
10086 name "ReadBufferStream (object)"
10088 \end_inset
10091 \begin_inset LatexCommand index
10092 name "WriteBufferStream (object)"
10094 \end_inset
10097 \family typewriter
10098 RingBuffer
10099 \family default
10100  is a special 
10101 \family typewriter
10102 ExtensibleSequence
10103 \family default
10104  that takes extra care to only use one underlying array object, and also
10105  stores its elements in a 
10106 \begin_inset Quotes eld
10107 \end_inset
10109 wrap-around
10110 \begin_inset Quotes erd
10111 \end_inset
10113  fashion, to make for an efficient queue for Streams (see 
10114 \family typewriter
10115 ReadBufferStream
10116 \family default
10117  and 
10118 \family typewriter
10119 WriteBufferStream
10120 \family default
10122 \begin_inset LatexCommand vref
10123 reference "des:ReadBufferStream"
10125 \end_inset
10128  One consequence of this is that a 
10129 \family typewriter
10130 RingBuffer
10131 \family default
10132  has a limited upper bound in size which the client must handle, although
10133  the capacity can be grown explicitly.
10134 \end_layout
10136 \begin_layout Subsubsection
10137 Strings and Characters
10138 \end_layout
10140 \begin_layout Standard
10142 \family typewriter
10143 \begin_inset LatexCommand index
10144 name "String (object)"
10146 \end_inset
10148 Strings
10149 \family default
10150  in Slate are non-extensible, mutable 
10151 \family typewriter
10152 Sequence
10153 \family default
10154 s of 
10155 \family typewriter
10156 Character
10157 \family default
10158 s (although 
10159 \family typewriter
10160 ExtensibleSequence
10161 \family default
10162 s can easily be made for them via, say, 
10163 \family typewriter
10165 \family default
10168 \family typewriter
10169 String
10170 \family default
10171 s and 
10172 \family typewriter
10173 Character
10174 \family default
10175 s have a special literal syntax, and methods specific to dealing with text;
10176  most of the useful generic methods for strings are lifted to the 
10177 \family typewriter
10178 Sequence
10179 \family default
10180  type.
10181  Strings provide the following specific protocol:
10182 \end_layout
10184 \begin_layout Description
10185 \begin_inset LatexCommand index
10186 name "lexicographicallyCompare: (message)"
10188 \end_inset
10191 \family typewriter
10192 lexicographicallyCompare:
10193 \family default
10194  performs an in-order comparison of the codes of the constituent 
10195 \family typewriter
10196 Character
10197 \family default
10198 s of the 
10199 \family typewriter
10200 String
10201 \family default
10202  arguments, returning the sign of comparison, 
10203 \family typewriter
10205 \family default
10206  if the first argument is greater, 
10207 \family typewriter
10209 \family default
10210  if equal, and 
10211 \family typewriter
10213 \family default
10214  if lesser.
10215 \end_layout
10217 \begin_layout Description
10219 \family typewriter
10220 \begin_inset LatexCommand index
10221 name "capitalize (message)"
10223 \end_inset
10225 capitalize
10226 \family default
10227  uppercases in-place the first 
10228 \family typewriter
10229 Character
10230 \family default
10231  in the 
10232 \family typewriter
10233 String
10234 \family default
10236 \end_layout
10238 \begin_layout Description
10240 \family typewriter
10241 \begin_inset LatexCommand index
10242 name "toUppercase (message)"
10244 \end_inset
10246 toUppercase
10247 \family default
10248  uppercases in-place all 
10249 \family typewriter
10250 Character
10251 \family default
10252 s in the 
10253 \family typewriter
10254 String
10255 \family default
10257 \end_layout
10259 \begin_layout Description
10261 \family typewriter
10262 \begin_inset LatexCommand index
10263 name "toLowerCase (message)"
10265 \end_inset
10267 toLowercase
10268 \family default
10269  lowercases in-place all 
10270 \family typewriter
10271 Character
10272 \family default
10273 s in the 
10274 \family typewriter
10275 String
10276 \family default
10278 \end_layout
10280 \begin_layout Description
10282 \family typewriter
10283 \begin_inset LatexCommand index
10284 name "toSwapCase (message)"
10286 \end_inset
10288 toSwapCase
10289 \family default
10290  toggles in-place the case of all 
10291 \family typewriter
10292 Character
10293 \family default
10294 s in the 
10295 \family typewriter
10296 String
10297 \family default
10299 \end_layout
10301 \begin_layout Description
10303 \family typewriter
10304 \begin_inset LatexCommand index
10305 name "toCamelCase (message)"
10307 \end_inset
10309 toCamelCase\InsetSpace ~
10310 &separators:
10311 \family default
10312  splits the 
10313 \family typewriter
10314 String
10315 \family default
10316  up according to the given separators (defaulting to whitespace), joining
10318 \family typewriter
10319 capitalize
10320 \family default
10321 'd versions of each element.
10322 \end_layout
10324 \begin_layout Description
10326 \family typewriter
10327 \begin_inset LatexCommand index
10328 name "fromCamelCase (message)"
10330 \end_inset
10332 fromCamelCase\InsetSpace ~
10333 &separator:
10334 \family default
10335  splits the 
10336 \family typewriter
10337 String
10338 \family default
10339  up according to capitalization transition boundaries and joins the elements
10340  together with the given separator.
10341 \end_layout
10343 \begin_layout Description
10345 \family typewriter
10346 \begin_inset LatexCommand index
10347 name "escaped (message)"
10349 \end_inset
10351 escaped
10352 \family default
10353  answers a new 
10354 \family typewriter
10355 String
10356 \family default
10357  based on adding slash-escapes for literal printing so it can be read in
10358  as the same value.
10359 \end_layout
10361 \begin_layout Description
10363 \family typewriter
10364 \begin_inset LatexCommand index
10365 name "unescaped (message)"
10367 \end_inset
10369 unescaped
10370 \family default
10371  answers a new 
10372 \family typewriter
10373 String
10374 \family default
10375  based on removing slash-escapes, the same way that parsing is done.
10376 \end_layout
10378 \begin_layout Description
10380 \family typewriter
10381 \begin_inset LatexCommand index
10382 name "readFrom: (message)"
10384 \end_inset
10386 readFrom:
10387 \family default
10388  takes a 
10389 \family typewriter
10390 String
10391 \family default
10392  or a 
10393 \family typewriter
10394 Stream
10395 \family default
10396  with compatible contents and parses the first available data as a 
10397 \family typewriter
10398 String
10399 \family default
10400  with the relevant escape interpretation.
10401 \end_layout
10403 \begin_layout Description
10404 \begin_inset LatexCommand index
10405 name "plural (message)"
10407 \end_inset
10410 \family typewriter
10411 plural
10412 \family default
10413  uses English rules to answer a new regular plural form of the argument
10415 \family typewriter
10416 String
10417 \family default
10419 \end_layout
10421 \begin_layout Description
10422 \begin_inset LatexCommand index
10423 name "asAn (message)"
10425 \end_inset
10428 \family typewriter
10429 asAn
10430 \family default
10431  uses English rules to answer a new String with 
10432 \family typewriter
10433 'a\InsetSpace ~
10435 \family default
10436  or 
10437 \family typewriter
10438 'an\InsetSpace ~
10440 \family default
10441  prepended.
10442 \end_layout
10444 \begin_layout Subsubsection
10445 Collections without Duplicates
10446 \end_layout
10448 \begin_layout Standard
10450 \family typewriter
10451 \begin_inset LatexCommand index
10452 name "NoDuplicationCollection (object)"
10454 \end_inset
10457 \begin_inset LatexCommand index
10458 name "include: (message)"
10460 \end_inset
10462 NoDuplicatesCollection
10463 \family default
10464  forms a special protocol that allows for extension in a well-mannered way.
10465  Instead of an 
10466 \family typewriter
10467 add:
10468 \family default
10469  protocol for extension, these collections provide 
10470 \family typewriter
10471 include:
10472 \family default
10473 , which ensures that at least one element of the collection is the target
10474  object, but doesn't do anything otherwise.
10475  Using 
10476 \family typewriter
10477 include:
10478 \family default
10479  will never add an object if it is already present.
10480  These collection types still respond to 
10481 \family typewriter
10482 add:
10483 \family default
10484  and its variants, but they will behave in terms of the 
10485 \family typewriter
10486 include:
10487 \family default
10488  semantics.
10489 \end_layout
10491 \begin_layout Standard
10492 \begin_inset LatexCommand index
10493 name "Set (object)"
10495 \end_inset
10497 The default implementation of this protocol is 
10498 \family typewriter
10500 \family default
10501 , which stores its elements in a (somewhat sparse) hashed array.
10502 \end_layout
10504 \begin_layout Subsubsection
10505 Mappings and Dictionaries
10506 \end_layout
10508 \begin_layout Standard
10510 \family typewriter
10511 \begin_inset LatexCommand index
10512 name "Mapping (object)"
10514 \end_inset
10517 \begin_inset LatexCommand index
10518 name "Association (object)"
10520 \end_inset
10523 \begin_inset LatexCommand index
10524 name "keysDo: (message)"
10526 \end_inset
10529 \begin_inset LatexCommand index
10530 name "valuesDo: (message)"
10532 \end_inset
10535 \begin_inset LatexCommand index
10536 name "keysAndValuedDo: (message)"
10538 \end_inset
10541 \begin_inset LatexCommand index
10542 name "Dictionary (object)"
10544 \end_inset
10546 Mapping
10547 \family default
10548 s provide a general protocol for associating the elements of a set of keys
10549  each to a value object.
10550  A 
10551 \family typewriter
10552 Dictionary
10553 \family default
10554  is essentially a 
10555 \family typewriter
10557 \family default
10558  of these 
10559 \family typewriter
10560 Association
10561 \family default
10562 s, but they are generally used with 
10563 \family typewriter
10564 Symbol
10565 \family default
10566 s as keys.
10567 \end_layout
10569 \begin_layout Standard
10571 \family typewriter
10572 Mapping
10573 \family default
10574  defines the general protocol 
10575 \family typewriter
10577 \family default
10578  and 
10579 \family typewriter
10580 at:put:
10581 \family default
10582  that 
10583 \family typewriter
10584 Sequence
10585 \family default
10586 s use, which also happen to be Mappings.
10587  Mappings also support iteration protocols such as 
10588 \family typewriter
10589 keysDo:
10590 \family default
10592 \family typewriter
10593 valuesDo:
10594 \family default
10595 , and 
10596 \family typewriter
10597 keysAndValuesDo:
10598 \family default
10600 \end_layout
10602 \begin_layout Subsubsection
10603 Linked Collections
10604 \end_layout
10606 \begin_layout Standard
10607 \begin_inset LatexCommand index
10608 name "LinkedCollection (object)"
10610 \end_inset
10613 \family typewriter
10614 LinkedCollection
10615 \family default
10616  provides a type of collection where the elements themselves are central
10617  to defining what is in the collection and what is not.
10618 \end_layout
10620 \begin_layout Paragraph
10621 Linked Lists
10622 \end_layout
10624 \begin_layout Standard
10625 \begin_inset LatexCommand index
10626 name "LinkedList (object)"
10628 \end_inset
10631 \begin_inset LatexCommand index
10632 name "Link (object)"
10634 \end_inset
10636 The usual 
10637 \family typewriter
10638 LinkedList
10639 \family default
10640  type, comprised of individual 
10641 \family typewriter
10642 Link
10643 \family default
10644 s with forward and backward directional access, is provided as a flexible
10645  but basic data structure.
10646  This type does require that its elements follow the 
10647 \family typewriter
10648 Link
10649 \family default
10650  protocol, however, so it does require some advanced preparation to use
10651  it.
10652 \end_layout
10654 \begin_layout Paragraph
10655 Trees
10656 \end_layout
10658 \begin_layout Standard
10659 \begin_inset LatexCommand index
10660 name "trees"
10662 \end_inset
10665 \begin_inset LatexCommand index
10666 name "trees, binary"
10668 \end_inset
10671 \begin_inset LatexCommand index
10672 name "binary trees"
10674 \end_inset
10677 \begin_inset LatexCommand index
10678 name "trees, red-black"
10680 \end_inset
10683 \begin_inset LatexCommand index
10684 name "red-black trees"
10686 \end_inset
10689 \begin_inset LatexCommand index
10690 name "trees with ordered elements"
10692 \end_inset
10695 \begin_inset LatexCommand index
10696 name "ordered elements, trees"
10698 \end_inset
10701 \begin_inset LatexCommand index
10702 name "tries"
10704 \end_inset
10706 Slate includes libraries for binary trees, red-black trees, trees with ordered
10707  elements, and tries.
10708 \end_layout
10710 \begin_layout Paragraph
10711 Graphs
10712 \end_layout
10714 \begin_layout Standard
10715 \begin_inset LatexCommand index
10716 name "graphs"
10718 \end_inset
10721 \begin_inset LatexCommand index
10722 name "Digraph (object)"
10724 \end_inset
10727 \begin_inset LatexCommand index
10728 name "Node (object)"
10730 \end_inset
10733 \begin_inset LatexCommand index
10734 name "Edge (object)"
10736 \end_inset
10739 \begin_inset LatexCommand index
10740 name "KeyedDigraph (object)"
10742 \end_inset
10744 A directed graph, or 
10745 \family typewriter
10746 Digraph
10747 \family default
10748  (directed graph) type, is provided with associated 
10749 \family typewriter
10750 Node
10751 \family default
10752  and 
10753 \family typewriter
10754 Edge
10755 \family default
10756  types.
10757  A 
10758 \family typewriter
10759 KeyedDigraph
10760 \family default
10761  provides the same behavior with a keyed access, similar to that in a 
10762 \family typewriter
10763 Mapping
10764 \family default
10765 , although there is an allowance for various kinds of non-determinism, which
10766  makes this useful for creating Non-deterministic Finite Automata.
10767 \end_layout
10769 \begin_layout Subsubsection
10770 Vectors and Matrices
10771 \end_layout
10773 \begin_layout Standard
10774 \begin_inset LatexCommand index
10775 name "vectors"
10777 \end_inset
10780 \begin_inset LatexCommand index
10781 name "matrices"
10783 \end_inset
10785 Slate includes the beginnings of a mathematical vector and matrix library.
10786  See the '
10787 \family typewriter
10788 src/lib/matrix.slate
10789 \family default
10790 ' file for an overview.
10791 \end_layout
10793 \begin_layout Subsection
10794 Streams and Iterators
10795 \end_layout
10797 \begin_layout Standard
10798 \begin_inset LatexCommand index
10799 name "streams"
10801 \end_inset
10804 \begin_inset LatexCommand index
10805 name "iterators"
10807 \end_inset
10809 Streams are objects that act as a sequential channel of elements from (or
10810  even 
10811 \emph on
10813 \emph default
10814 ) some source.
10815 \end_layout
10817 \begin_layout Subsubsection
10818 Basic Protocol
10819 \end_layout
10821 \begin_layout Standard
10822 Streams respond to a number of common messages.
10823  However, many of these only work on some of the stream types, usually according
10824  to good sense:
10825 \end_layout
10827 \begin_layout Description
10829 \family typewriter
10830 \begin_inset LatexCommand index
10831 name "next (message)"
10833 \end_inset
10835 next\InsetSpace ~
10836 &onExhaustion:
10837 \family default
10838  reads and answers the next element in the stream.
10839  This causes the stream reader to advance one element.
10840  If no further elements are available to return, then the block supplied
10841  to 
10842 \family typewriter
10843 &onExhaustion:
10844 \family default
10845  is invoked (with no arguments), or if the optional argument was not supplied,
10846  an 
10847 \family typewriter
10848 Exhaustion
10849 \family default
10850  condition is signalled.
10851 \end_layout
10853 \begin_layout Description
10855 \family typewriter
10856 \begin_inset LatexCommand index
10857 name "peek (message)"
10859 \end_inset
10861 peek\InsetSpace ~
10862 &onExhaustion:
10863 \family default
10864  reads and answers the next element in the stream.
10865  This does 
10866 \emph on
10868 \emph default
10869  advance the stream reader.
10870  If no further elements are available to return, the 
10871 \family typewriter
10872 &onExhaustion:
10873 \family default
10874  argument is processed as for 
10875 \family typewriter
10876 next
10877 \family default
10879 \end_layout
10881 \begin_layout Description
10883 \family typewriter
10884 \begin_inset LatexCommand index
10885 name "next: (message)"
10887 \end_inset
10889 next:
10890 \family default
10891  draws the next 
10892 \family typewriter
10894 \family default
10895  number of elements from the stream and delivers them in a 
10896 \family typewriter
10897 Sequence
10898 \family default
10899  of the appropriate type.
10900  If fewer than n elements are available before the end of stream (when 
10901 \family typewriter
10902 next
10903 \family default
10904  would have signalled 
10905 \family typewriter
10906 Exhaustion
10907 \family default
10908 ), then a shorter 
10909 \family typewriter
10910 Sequence
10911 \family default
10912  than asked for, possibly even empty, is returned.
10913 \end_layout
10915 \begin_layout Description
10917 \family typewriter
10918 \begin_inset LatexCommand index
10919 name "next:putInto: (message)"
10921 \end_inset
10923 next:putInto:
10924 \family default
10925  reads the next N elements into the given 
10926 \family typewriter
10927 Sequence
10928 \family default
10929  starting from index 0.
10930  Returns the number of elements actually read and inserted.
10931  As for 
10932 \family typewriter
10933 next:
10934 \family default
10935 , the returned number may be smaller than actually asked for.
10936 \end_layout
10938 \begin_layout Description
10940 \family typewriter
10941 \begin_inset LatexCommand index
10942 name "next:putInto:startingAt: (message)"
10944 \end_inset
10946 next:putInto:startingAt:
10947 \family default
10948  reads the N elements into the given 
10949 \family typewriter
10950 Sequence
10951 \family default
10952  starting from the given index.
10953  Returns the number of elements read and inserted, exactly as for 
10954 \family typewriter
10955 next:putInto:
10956 \family default
10958 \end_layout
10960 \begin_layout Description
10962 \family typewriter
10963 \begin_inset LatexCommand index
10964 name "nextPutInto: (message)"
10966 \end_inset
10968 nextPutInto:
10969 \family default
10970  reads into the given 
10971 \family typewriter
10972 Sequence
10973 \family default
10974  the number of elements which will fit into it.
10975  Returns a result exactly as for 
10976 \family typewriter
10977 next:putInto:
10978 \family default
10980 \end_layout
10982 \begin_layout Description
10984 \family typewriter
10985 \begin_inset LatexCommand index
10986 name "nextPut: (message)"
10988 \end_inset
10990 nextPut:\InsetSpace ~
10991 &onExhaustion:
10992 \family default
10993  writes the object to the stream.
10994  If the stream is full, and will not accept the object, the 
10995 \family typewriter
10996 &onExhaustion:
10997 \family default
10998  optional argument is processed as for 
10999 \family typewriter
11000 next
11001 \family default
11003 \end_layout
11005 \begin_layout Description
11007 \family typewriter
11008 \begin_inset LatexCommand index
11009 name "nextPutAll: (message)"
11011 \end_inset
11014 \begin_inset LatexCommand index
11015 name "; (semicolon)"
11017 \end_inset
11019 nextPutAll:
11020 \family default
11022 \emph on
11023 alias
11024 \emph default
11026 \family typewriter
11027 \series bold
11028 stream\InsetSpace ~
11029 ;\InsetSpace ~
11030 sequence
11031 \family default
11032 \series default
11033  writes all the objects in the 
11034 \family typewriter
11035 Sequence
11036 \family default
11037  to the stream.
11038  The 
11039 \family typewriter
11041 \family default
11042  selector allows the user to cascade several sequences into the stream as
11043  though they were concatenated.
11044  If the stream fills up (signalling 
11045 \family typewriter
11046 Exhaustion
11047 \family default
11048 ) during the write, a 
11049 \family typewriter
11050 PartialWrite
11051 \family default
11052  condition containing the number of successfully written elements is signalled.
11053 \end_layout
11055 \begin_layout Description
11057 \family typewriter
11058 \begin_inset LatexCommand index
11059 name "do: (message)"
11061 \end_inset
11064 \family default
11065  applies a block to each element of the stream.
11066 \end_layout
11068 \begin_layout Description
11070 \family typewriter
11071 \begin_inset LatexCommand index
11072 name "flush (message)"
11074 \end_inset
11076 flush
11077 \family default
11078  synchronizes the total state of the stream with any pending requests made
11079  by the user.
11080 \end_layout
11082 \begin_layout Description
11084 \family typewriter
11085 \begin_inset LatexCommand index
11086 name "isAtEnd (message)"
11088 \end_inset
11090 isAtEnd
11091 \family default
11092  answers whether or not the stream has reached some input limit: returns
11093  true if next or peek would signal Exhaustion at the time 
11094 \family typewriter
11095 isAtEnd
11096 \family default
11097  was called; returns false otherwise (modulo signalled Conditions).
11098  Note that, for some streams (notably sockets), even though 
11099 \family typewriter
11100 isAtEnd
11101 \family default
11102  has returned false, 
11103 \family typewriter
11104 next
11105 \family default
11106  or 
11107 \family typewriter
11108 peek
11109 \family default
11110  may still signal Exhaustion because the underlying input-source has changed
11111  its state asynchronously.
11112  Use the 
11113 \family typewriter
11114 &onExhaustion:
11115 \family default
11116  optional argument to 
11117 \family typewriter
11118 next
11119 \family default
11120  and 
11121 \family typewriter
11122 peek
11123 \family default
11124  for reliable notifications in these cases.
11126 \end_layout
11128 \begin_layout Description
11129 \begin_inset LatexCommand index
11130 name "hasAnEnd (message)"
11132 \end_inset
11135 \family typewriter
11136 hasAnEnd
11137 \family default
11138  answers whether the stream has a definable or possible end-point.
11139  All stream types support this protocol and will often recurses on their
11140  components to find the answer.
11141 \end_layout
11143 \begin_layout Description
11144 \begin_inset LatexCommand index
11145 name "isWritable (message)"
11147 \end_inset
11150 \family typewriter
11151 isWritable
11152 \family default
11153  answers whether the stream is prepared to accept further objects via 
11154 \family typewriter
11155 nextPut:
11156 \family default
11158  Returns false if 
11159 \family typewriter
11160 nextPut:
11161 \family default
11162  would signal 
11163 \family typewriter
11164 Exhaustion
11165 \family default
11166  at the time 
11167 \family typewriter
11168 isWritable
11169 \family default
11170  was called; returns true otherwise (modulo signalled 
11171 \family typewriter
11172 Condition
11173 \family default
11175  See caveat as for 
11176 \family typewriter
11177 isAtEnd
11178 \family default
11180 \end_layout
11182 \begin_layout Description
11184 \family typewriter
11185 \begin_inset LatexCommand index
11186 name "upToEnd (message)"
11188 \end_inset
11190 upToEnd
11191 \family default
11192  collects all the elements of the stream up to its limit into an 
11193 \family typewriter
11194 Extensible\SpecialChar \-
11195 Sequence
11196 \family default
11197 , and returns the sequence.
11198 \end_layout
11200 \begin_layout Description
11202 \family typewriter
11203 \begin_inset LatexCommand index
11204 name "contents (message)"
11206 \end_inset
11208 contents
11209 \family default
11210  answers a collection of the output of the argument 
11211 \family typewriter
11212 WriteStream
11213 \family default
11215 \end_layout
11217 \begin_layout Subsubsection
11218 Basic Stream Variants
11219 \end_layout
11221 \begin_layout Standard
11222 \begin_inset LatexCommand index
11223 name "Stream (object)"
11225 \end_inset
11228 \begin_inset LatexCommand index
11229 name "PositionableStream (object)"
11231 \end_inset
11234 \begin_inset LatexCommand index
11235 name "FilterStream (object)"
11237 \end_inset
11240 \begin_inset LatexCommand index
11241 name "CollectStream (object)"
11243 \end_inset
11246 \begin_inset LatexCommand index
11247 name "ReadStream (object)"
11249 \end_inset
11252 \begin_inset LatexCommand index
11253 name "WriteStream (object)"
11255 \end_inset
11258 \begin_inset LatexCommand index
11259 name "BufferStream (object)"
11261 \end_inset
11264 \begin_inset LatexCommand index
11265 name "FileStream (object)"
11267 \end_inset
11270 \begin_inset LatexCommand index
11271 name "Socket (object)"
11273 \end_inset
11276 \begin_inset LatexCommand index
11277 name "Pipe (object)"
11279 \end_inset
11282 \begin_inset LatexCommand index
11283 name "Console (object)"
11285 \end_inset
11288 \begin_inset LatexCommand index
11289 name "DummyStream (object)"
11291 \end_inset
11294 \begin_inset LatexCommand index
11295 name "BlockStream (object)"
11297 \end_inset
11300 \begin_inset LatexCommand index
11301 name "ReadWriteStream (object)"
11303 \end_inset
11306 \begin_inset LatexCommand index
11307 name "EchoStream (object)"
11309 \end_inset
11312 \begin_inset LatexCommand index
11313 name "LineNumberedStream (object)"
11315 \end_inset
11317 Figure 
11318 \begin_inset LatexCommand ref
11319 reference "cap:Stream-Inheritance"
11321 \end_inset
11323  shows the major stream types and their relationships.
11324 \end_layout
11326 \begin_layout Standard
11327 \begin_inset Float figure
11328 wide false
11329 sideways false
11330 status open
11332 \begin_layout Standard
11333 \begin_inset VSpace defskip
11334 \end_inset
11337 \end_layout
11339 \begin_layout Standard
11340 \align center
11341 \begin_inset Graphics
11342         filename stream-web.eps
11344 \end_inset
11347 \end_layout
11349 \begin_layout Standard
11350 \begin_inset VSpace defskip
11351 \end_inset
11354 \end_layout
11356 \begin_layout Standard
11357 \begin_inset Caption
11359 \begin_layout Standard
11360 \begin_inset LatexCommand label
11361 name "cap:Stream-Inheritance"
11363 \end_inset
11365 Stream Inheritance
11366 \end_layout
11368 \end_inset
11371 \end_layout
11373 \end_inset
11376 \end_layout
11378 \begin_layout Description
11380 \family typewriter
11381 Stream
11382 \family default
11383  provides the basic protocol for instantiating streams.
11384 \end_layout
11386 \begin_layout Description
11388 \family typewriter
11389 ReadStream
11390 \family default
11391  provides the basic protocol for input access from a source.
11392 \end_layout
11394 \begin_layout Description
11396 \family typewriter
11397 WriteStream
11398 \family default
11399  provides the basic protocol for output access to a target.
11400 \end_layout
11402 \begin_layout Description
11404 \family typewriter
11405 ReadWriteStream
11406 \family default
11407  provides the basic protocol for both read and write access, and caches
11408  its input as necessary.
11409 \end_layout
11411 \begin_layout Description
11413 \family typewriter
11414 \begin_inset LatexCommand index
11415 name "PeekableStream (object)"
11417 \end_inset
11419 PeekableStream
11420 \family default
11421  extends 
11422 \family typewriter
11423 Stream
11424 \family default
11425  to provide the ability to look forward on the stream without advancing
11426  it.
11427 \end_layout
11429 \begin_layout Description
11431 \family typewriter
11432 \begin_inset LatexCommand index
11433 name "ReadPositionableStream (object)"
11435 \end_inset
11438 \begin_inset LatexCommand index
11439 name "WritePositionableStream (object)"
11441 \end_inset
11444 \begin_inset LatexCommand index
11445 name "ReadWritePositionableStream (object)"
11447 \end_inset
11449 PositionableStream
11450 \family default
11451  extends 
11452 \family typewriter
11453 PeekableStream
11454 \family default
11455  to provide a basic protocol to iterate over a sequence of elements from
11456  a 
11457 \family typewriter
11458 Sequence
11459 \family default
11460  or a file or other source.
11461  These streams store their position in the sequence as they iterate, and
11462  are re-positionable.
11463  It also has its own variants, -
11464 \family typewriter
11465 Read
11466 \family default
11467 -, -
11468 \family typewriter
11469 Write
11470 \family default
11471 -, and -
11472 \family typewriter
11473 ReadWrite
11474 \family default
11476 \end_layout
11478 \begin_layout Description
11480 \family typewriter
11481 \begin_inset LatexCommand index
11482 name "reader (message)"
11484 \end_inset
11487 \begin_inset LatexCommand index
11488 name "writer (message)"
11490 \end_inset
11493 \begin_inset LatexCommand index
11494 name "iterator (message)"
11496 \end_inset
11498 DummyStream
11499 \family default
11500  is a (singleton) 
11501 \family typewriter
11502 ReadWriteStream
11503 \family default
11504  that just answers 
11505 \family typewriter
11507 \family default
11508  repeatedly (and does nothing on writing).
11509  It is best created by applying the 
11510 \family typewriter
11511 reader
11512 \family default
11514 \family typewriter
11515 writer
11516 \family default
11517 , or 
11518 \family typewriter
11519 iterator
11520 \family default
11521  methods to 
11522 \family typewriter
11524 \family default
11526 \end_layout
11528 \begin_layout Description
11530 \family typewriter
11531 \begin_inset LatexCommand index
11532 name "echo (message)"
11534 \end_inset
11537 \begin_inset LatexCommand index
11538 name "echoTo: (message)"
11540 \end_inset
11542 EchoStream
11543 \family default
11544  is a wrapper for a 
11545 \family typewriter
11546 Stream
11547 \family default
11548  which copies all stream input/output interactions to another 
11549 \family typewriter
11550 Stream
11551 \family default
11552  for logging purposes.
11553  It is best created by applying the 
11554 \family typewriter
11555 echo
11556 \family default
11557  (goes to the 
11558 \family typewriter
11559 Console
11560 \family default
11561 ) or 
11562 \family typewriter
11563 echoTo:\InsetSpace ~
11564 anotherStream
11565 \family default
11566  methods to any stream.
11567  It answers the original stream, so that further processing can be chained.
11568 \end_layout
11570 \begin_layout Description
11572 \family typewriter
11573 \begin_inset LatexCommand index
11574 name "Method ReadStream (object)"
11576 \end_inset
11578 Method\InsetSpace ~
11579 ReadStream
11580 \family default
11581  is a 
11582 \family typewriter
11583 ReadStream
11584 \family default
11585  that targets a no-input block and returns its output each time.
11586  It is best created by applying the 
11587 \family typewriter
11588 reader
11589 \family default
11590  or 
11591 \family typewriter
11592 iterator
11593 \family default
11594  method to any block.
11595 \end_layout
11597 \begin_layout Description
11599 \family typewriter
11600 \begin_inset LatexCommand index
11601 name "Method WriteStream (object)"
11603 \end_inset
11605 Method\InsetSpace ~
11606 WriteStream
11607 \family default
11608  is a 
11609 \family typewriter
11610 WriteStream
11611 \family default
11612  that targets a single-input block and applies its input each time.
11613  It is best created by applying the 
11614 \family typewriter
11615 writer
11616 \family default
11617  method to any block.
11618 \end_layout
11620 \begin_layout Description
11622 \family typewriter
11623 \begin_inset LatexCommand index
11624 name "StreamProcessor (object)"
11626 \end_inset
11628 StreamProcessor
11629 \family default
11630  is an abstract kind of 
11631 \family typewriter
11632 ReadStream
11633 \family default
11634  that has a source 
11635 \family typewriter
11636 ReadStream
11637 \family default
11638  which it processes in some way.
11639  Derivatives specialize it in various useful ways.
11640 \end_layout
11642 \begin_layout Description
11644 \family typewriter
11645 \begin_inset LatexCommand index
11646 name "select: (message)"
11648 \end_inset
11651 \begin_inset LatexCommand index
11652 name "reject: (message)"
11654 \end_inset
11656 FilterStream
11657 \family default
11658  is a 
11659 \family typewriter
11660 StreamProcessor
11661 \family default
11662  that returns the elements of a wrapped 
11663 \family typewriter
11664 ReadStream
11665 \family default
11666  that satisfy the logical test of a single-argument block being applied
11667  to each element.
11668  It is created by applying the 
11669 \family typewriter
11670 select:
11671 \family default
11672  or 
11673 \family typewriter
11674 reject:
11675 \family default
11676  method to any 
11677 \family typewriter
11678 Stream
11679 \family default
11681 \end_layout
11683 \begin_layout Description
11685 \family typewriter
11686 \begin_inset LatexCommand index
11687 name "collect: (message)"
11689 \end_inset
11691 CollectStream
11692 \family default
11693  is a 
11694 \family typewriter
11695 StreamProcessor
11696 \family default
11697  that returns the results of applying a single-argument block to each element
11698  of a 
11699 \family typewriter
11700 ReadStream
11701 \family default
11702  that it wraps.
11703  It is created by applying the 
11704 \family typewriter
11705 collect:
11706 \family default
11707  method to any 
11708 \family typewriter
11709 Stream
11710 \family default
11712 \end_layout
11714 \begin_layout Description
11715 \begin_inset LatexCommand index
11716 name "inject:into: (message)"
11718 \end_inset
11721 \family typewriter
11722 InjectStream
11723 \family default
11724  is a 
11725 \family typewriter
11726 StreamProcessor
11727 \family default
11728  that returns the results of successively applying a two-argument block
11729  to an initial seed and each stream element.
11730  The result of the block is used as seed for the next block application.
11731  It is created by applying the 
11732 \family typewriter
11733 inject:into:
11734 \family default
11735  method to any 
11736 \family typewriter
11737 Stream
11738 \family default
11740 \end_layout
11742 \begin_layout Description
11744 \family typewriter
11745 \begin_inset LatexCommand index
11746 name "splitWith: (message)"
11748 \end_inset
11750 Tokenizer
11751 \family default
11752  is a 
11753 \family typewriter
11754 StreamProcessor
11755 \family default
11756  that returns the sequences of elements between a given set of separators.
11757  It is created by applying the 
11758 \family typewriter
11759 split
11760 \family default
11761  (using whitespace separators) or 
11762 \family typewriter
11763 splitWith:
11764 \family default
11765  methods to any 
11766 \family typewriter
11767 Stream
11768 \family default
11770 \end_layout
11772 \begin_layout Description
11773 \begin_inset LatexCommand index
11774 name "generate:until: (message)"
11776 \end_inset
11779 \family typewriter
11780 GeneratorStream
11781 \family default
11782  is a 
11783 \family typewriter
11784 ReadStream
11785 \family default
11786  that returns the results of successively applying a single-argument block
11787  to an initial seed.
11788  The result of the block is used as seed for the next block.
11789  The method 
11790 \family typewriter
11791 generate:until:
11792 \family default
11793  creates such a stream with a termination block which takes each element
11794  as the argument to determine where the stream should end.
11795 \end_layout
11797 \begin_layout Description
11799 \family typewriter
11800 \begin_inset LatexCommand index
11801 name "readBuffered (message)"
11803 \end_inset
11805 ReadBufferStream
11806 \family default
11808 \begin_inset LatexCommand label
11809 name "des:ReadBufferStream"
11811 \end_inset
11813  wraps another stream with a special 
11814 \family typewriter
11815 Buffer
11816 \family default
11817  object for reading large chunks from the stream at a time while handing
11818  out the elements as requested.
11819  This also minimizes stress on the memory-allocator by avoiding unnecessary
11820  allocation of arrays.
11821  It is created by applying the 
11822 \family typewriter
11823 readBuffered
11824 \family default
11825  method to any 
11826 \family typewriter
11827 Stream
11828 \family default
11830 \end_layout
11832 \begin_layout Description
11834 \family typewriter
11835 \begin_inset LatexCommand index
11836 name "writeBuffered (message)"
11838 \end_inset
11840 WriteBufferStream
11841 \family default
11843 \begin_inset LatexCommand label
11844 name "des:WriteBufferStream"
11846 \end_inset
11848  wraps another stream with a special 
11849 \family typewriter
11850 Buffer
11851 \family default
11852  object for writing large chunks to the stream at a time while accepting
11853  new elements as requested.
11854  This also minimizes stress on the memory-allocator by avoiding unnecessary
11855  allocation of arrays.
11856  It is created by applying the 
11857 \family typewriter
11858 writeBuffered
11859 \family default
11860  method to any 
11861 \family typewriter
11862 Stream
11863 \family default
11865 \end_layout
11867 \begin_layout Subsubsection
11868 Basic Instantiation
11869 \end_layout
11871 \begin_layout Standard
11872 \begin_inset LatexCommand index
11873 name "creation, streams"
11875 \end_inset
11878 \begin_inset LatexCommand index
11879 name "stream creation"
11881 \end_inset
11883 There are a number of ways to create 
11884 \family typewriter
11885 Stream
11886 \family default
11887 s, and a large number of implementations, so some methods exist to simplify
11888  the process of making a new one:
11889 \end_layout
11891 \begin_layout Description
11893 \family typewriter
11894 \begin_inset LatexCommand index
11895 name "newOn: (message)"
11897 \end_inset
11899 newOn:
11900 \family default
11901  creates a new 
11902 \family typewriter
11903 Stream
11904 \family default
11905  of the same type as the first argument, targeting it to the second as a
11906  source.
11907  This should not be overridden.
11908  Instead, the re-targeting method 
11909 \family typewriter
11911 \family default
11912  is overridden.
11913 \end_layout
11915 \begin_layout Description
11917 \family typewriter
11918 \begin_inset LatexCommand index
11919 name "newTo: (message)"
11921 \end_inset
11923 newTo:
11924 \family default
11925  creates a new 
11926 \family typewriter
11927 WriteStream
11928 \family default
11929  of the appropriate type on the specified target.
11930  This should be overridden for derived types, and the first argument should
11931  apply to the generic 
11932 \family typewriter
11933 Stream
11934 \family default
11935  type to allow any instance to know this protocol.
11936 \end_layout
11938 \begin_layout Description
11940 \family typewriter
11941 \begin_inset LatexCommand index
11942 name "newFrom: (message)"
11944 \end_inset
11946 newFrom:
11947 \family default
11948  creates a new 
11949 \family typewriter
11950 ReadStream
11951 \family default
11952  of the appropriate type on the specified target.
11953  This should be overridden for derived types, and the first argument should
11954  apply to the generic 
11955 \family typewriter
11956 Stream
11957 \family default
11958  type to allow any instance to know this protocol.
11959 \end_layout
11961 \begin_layout Description
11963 \family typewriter
11964 \begin_inset LatexCommand index
11965 name "buffered (message)"
11967 \end_inset
11969 buffered
11970 \family default
11971  creates and returns a new 
11972 \family typewriter
11973 BufferStream
11974 \family default
11975  whose type corresponds to the argument and wraps the argument 
11976 \family typewriter
11977 Stream
11978 \family default
11980 \end_layout
11982 \begin_layout Description
11984 \family typewriter
11985 \begin_inset LatexCommand index
11986 name "readBuffered (message)"
11988 \end_inset
11990 readBuffered
11991 \family default
11992  creates and returns a new 
11993 \family typewriter
11994 ReadBufferStream
11995 \family default
11996  which wraps the argument 
11997 \family typewriter
11998 Stream
11999 \family default
12001 \end_layout
12003 \begin_layout Description
12005 \family typewriter
12006 \begin_inset LatexCommand index
12007 name "writeBuffered (message)"
12009 \end_inset
12011 writeBuffered
12012 \family default
12013  creates and returns a new 
12014 \family typewriter
12015 WriteBufferStream
12016 \family default
12017  which wraps the argument 
12018 \family typewriter
12019 Stream
12020 \family default
12022 \end_layout
12024 \begin_layout Description
12026 \family typewriter
12027 \begin_inset LatexCommand index
12028 name "echoTo: (message)"
12030 \end_inset
12032 echoTo:
12033 \family default
12034  creates and returns a new 
12035 \family typewriter
12036 EchoStream
12037 \family default
12038  which wraps the first argument 
12039 \family typewriter
12040 Stream
12041 \family default
12042  and echoes to the second.
12043 \end_layout
12045 \begin_layout Description
12047 \family typewriter
12048 \begin_inset LatexCommand index
12049 name "echo (message)"
12051 \end_inset
12053 echo
12054 \family default
12055  creates and returns a new 
12056 \family typewriter
12057 EchoStream
12058 \family default
12059  to the 
12060 \family typewriter
12061 Console
12062 \family default
12064 \end_layout
12066 \begin_layout Description
12068 \family typewriter
12069 \begin_inset LatexCommand index
12070 name ">> (message)"
12072 \end_inset
12075 \family default
12076  performs a looping iterative transfer of all elements of the first stream
12077  to the second.
12078  The second argument may be any 
12079 \family typewriter
12080 WriteStream
12081 \family default
12082 , or a 
12083 \family typewriter
12084 StreamProcessor
12085 \family default
12086 , or a single-argument 
12087 \family typewriter
12088 Method
12089 \family default
12090  in which case it has the same semantics as 
12091 \family typewriter
12092 collect:
12093 \family default
12095  For targets to 
12096 \family typewriter
12097 ExternalResource
12098 \family default
12099 s, it will perform a buffered transfer.
12100  This method always returns the target stream so that the results may be
12101  further processed.
12102 \end_layout
12104 \begin_layout Subsubsection
12105 Collecting Protocols
12106 \end_layout
12108 \begin_layout Standard
12109 Mirroring the collection protocols, streams support a mirror of that interface
12111 \family typewriter
12113 \family default
12115 \family typewriter
12116 select:
12117 \family default
12119 \family typewriter
12120 collect:
12121 \family default
12123 \family typewriter
12124 reject:
12125 \family default
12127 \family typewriter
12128 inject:into:
12129 \family default
12131  The difference is that where collections would answer other collections,
12132  streams return corresponding streams.
12133 \end_layout
12135 \begin_layout Subsubsection
12136 \begin_inset LatexCommand label
12137 name "sub:Iterator-Streams"
12139 \end_inset
12141 Iterator Streams
12142 \end_layout
12144 \begin_layout Standard
12145 \begin_inset LatexCommand index
12146 name "iterator streams"
12148 \end_inset
12151 \begin_inset LatexCommand index
12152 name "streams, iterator"
12154 \end_inset
12157 \begin_inset LatexCommand index
12158 name "Set ReadStream (object)"
12160 \end_inset
12162 Many types (typically collections) define their own 
12163 \family typewriter
12164 Stream
12165 \family default
12166  type which goes over its elements in series, even if the collection is
12167  not ordered, and only visits each element once.
12168  This type's prototype is accessed via the slot 
12169 \family typewriter
12170 ReadStream
12171 \family default
12172  within each collection (located on its traits object).
12173  So 
12174 \begin_inset Quotes eld
12175 \end_inset
12178 \family typewriter
12179 Set\InsetSpace ~
12180 ReadStream
12181 \family default
12183 \begin_inset Quotes erd
12184 \end_inset
12186  refers to the prototype suitable for iterating over 
12187 \family typewriter
12189 \family default
12191 \end_layout
12193 \begin_layout Standard
12194 \begin_inset LatexCommand index
12195 name "iterator (message)"
12197 \end_inset
12199 In order to create a new iterator for a specific collection, the 
12200 \family typewriter
12201 iterator
12202 \family default
12203  message is provided, which clones the prototype for that collection's type
12204  and targets it to the receiver of the message.
12205  The protocol summary:
12206 \end_layout
12208 \begin_layout Description
12210 \family typewriter
12211 iterator
12212 \family default
12213  will return a 
12214 \family typewriter
12215 ReadStream
12216 \family default
12217  or preferably a 
12218 \family typewriter
12219 ReadWriteStream
12220 \family default
12221  if one is available for the type, targetted to the argument of the message.
12222 \end_layout
12224 \begin_layout Description
12226 \family typewriter
12227 \begin_inset LatexCommand index
12228 name "reader (message)"
12230 \end_inset
12233 \begin_inset LatexCommand index
12234 name "writer (message)"
12236 \end_inset
12238 reader
12239 \family default
12240  and 
12241 \family typewriter
12242 \series bold
12243 writer
12244 \family default
12245 \series default
12246  get streams with only 
12247 \family typewriter
12248 ReadStream
12249 \family default
12250  and 
12251 \family typewriter
12252 WriteStream
12253 \family default
12254  capabilities for the type, when available, targetted to the argument of
12255  the message.
12256 \end_layout
12258 \begin_layout Standard
12259 The stream capabilities supported for each basic collection type are usually
12260  limited by the behavior that the type supports.
12261  The capabilities per basic type are as follows; types not mentioned inherit
12262  or specialize the capabilities of their ancestors:
12263 \end_layout
12265 \begin_layout Standard
12266 \align center
12267 \begin_inset Tabular
12268 <lyxtabular version="3" rows="6" columns="2">
12269 <features>
12270 <column alignment="center" valignment="top" leftline="true" width="0sp">
12271 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0sp">
12272 <row topline="true" bottomline="true">
12273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12274 \begin_inset Text
12276 \begin_layout Standard
12277 Type
12278 \end_layout
12280 \end_inset
12281 </cell>
12282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12283 \begin_inset Text
12285 \begin_layout Standard
12286 Capabilities
12287 \end_layout
12289 \end_inset
12290 </cell>
12291 </row>
12292 <row topline="true">
12293 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12294 \begin_inset Text
12296 \begin_layout Standard
12297 Collection
12298 \end_layout
12300 \end_inset
12301 </cell>
12302 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12303 \begin_inset Text
12305 \begin_layout Standard
12306 none
12307 \end_layout
12309 \end_inset
12310 </cell>
12311 </row>
12312 <row topline="true">
12313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12314 \begin_inset Text
12316 \begin_layout Standard
12317 ExtensibleCollection
12318 \end_layout
12320 \end_inset
12321 </cell>
12322 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12323 \begin_inset Text
12325 \begin_layout Standard
12326 Write
12327 \end_layout
12329 \end_inset
12330 </cell>
12331 </row>
12332 <row topline="true">
12333 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12334 \begin_inset Text
12336 \begin_layout Standard
12338 \end_layout
12340 \end_inset
12341 </cell>
12342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12343 \begin_inset Text
12345 \begin_layout Standard
12346 Read and Write separately
12347 \end_layout
12349 \end_inset
12350 </cell>
12351 </row>
12352 <row topline="true">
12353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12354 \begin_inset Text
12356 \begin_layout Standard
12357 Sequence
12358 \end_layout
12360 \end_inset
12361 </cell>
12362 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12363 \begin_inset Text
12365 \begin_layout Standard
12366 Positionables (R, W, RW); copy for extension
12367 \end_layout
12369 \end_inset
12370 </cell>
12371 </row>
12372 <row topline="true" bottomline="true">
12373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12374 \begin_inset Text
12376 \begin_layout Standard
12377 ExtensibleSequence
12378 \end_layout
12380 \end_inset
12381 </cell>
12382 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12383 \begin_inset Text
12385 \begin_layout Standard
12386 Positionables (R, W, RW)
12387 \end_layout
12389 \end_inset
12390 </cell>
12391 </row>
12392 </lyxtabular>
12394 \end_inset
12397 \end_layout
12399 \begin_layout Subsection
12400 External Resources
12401 \begin_inset LatexCommand label
12402 name "sub:External-Resources"
12404 \end_inset
12407 \end_layout
12409 \begin_layout Standard
12410 \begin_inset LatexCommand index
12411 name "external resources"
12413 \end_inset
12416 \begin_inset LatexCommand index
12417 name "resources, external"
12419 \end_inset
12421 Slate includes an extensible framework for streams that deal with external
12422  resources, such as files or network connections or other programs.
12423  This generally relies on having a representative object in the image which
12424  tracks the underlying primitive identity of the resource, and also provides
12425  methods for iterator-style streams over what is available through the resources.
12426  Many of these resources aren't sequences as files are sequences of bytes,
12427  so they're asynchronous and behave differently from ordinary streams.
12428 \end_layout
12430 \begin_layout Paragraph
12431 Basic Types
12432 \end_layout
12434 \begin_layout Description
12436 \family typewriter
12437 \begin_inset LatexCommand index
12438 name "ExternalResource (object)"
12440 \end_inset
12442 ExternalResource
12443 \family default
12444  provides the basic behavior for external resource types.
12445 \end_layout
12447 \begin_layout Description
12449 \family typewriter
12450 \begin_inset LatexCommand index
12451 name "ExternalResource Locator (object)"
12453 \end_inset
12455 ExternalResource\InsetSpace ~
12456 Locator
12457 \family default
12458  provides a core attribute type for structured descriptors of external resources
12459 , as a generalization of file pathnames, port descriptions, URLs, or even
12460  URIs.
12461 \end_layout
12463 \begin_layout Description
12465 \family typewriter
12466 \begin_inset LatexCommand index
12467 name "ExternalResource Stream (object)"
12469 \end_inset
12471 ExternalResource\InsetSpace ~
12472 Stream
12473 \family default
12474  provides an extension of the iterator interface (described on 
12475 \begin_inset LatexCommand vref
12476 reference "sub:Iterator-Streams"
12478 \end_inset
12480 ) for 
12481 \family typewriter
12482 ExternalResource
12483 \family default
12485  All of them provide 
12486 \family typewriter
12487 ReadStream
12488 \family default
12490 \family typewriter
12491 WriteStream
12492 \family default
12493 , and 
12494 \family typewriter
12495 ReadWriteStream
12496 \family default
12497  variants as appropriate.
12498 \end_layout
12500 \begin_layout Paragraph
12501 Primitives
12502 \end_layout
12504 \begin_layout Standard
12505 Extending the framework to cover new primitive or otherwise connection types
12506  is fairly simple, since the following methods are the only input/output
12507  primitives needed for defining an external resource type:
12508 \end_layout
12510 \begin_layout Description
12512 \family typewriter
12513 \begin_inset LatexCommand index
12514 name "read:from:startingAt:into: (message)"
12516 \end_inset
12518 resource\InsetSpace ~
12519 read:\InsetSpace ~
12520 n\InsetSpace ~
12521 from:\InsetSpace ~
12522 handle\InsetSpace ~
12523 startingAt:\InsetSpace ~
12524 start\InsetSpace ~
12525 into:\InsetSpace ~
12526 array
12527 \family default
12528  reads the next n elements from the resource identified by the given low-level
12529  handle, from the given starting point.
12530  The contents are placed in the given array, which should be a 
12531 \family typewriter
12532 ByteArray
12533 \family default
12534  currently.
12535 \end_layout
12537 \begin_layout Description
12539 \family typewriter
12540 \begin_inset LatexCommand index
12541 name "write:to:startingAt:from: (message)"
12543 \end_inset
12545 resource\InsetSpace ~
12546 write:\InsetSpace ~
12547 n\InsetSpace ~
12548 to:\InsetSpace ~
12549 handle\InsetSpace ~
12550 startingAt:\InsetSpace ~
12551 start\InsetSpace ~
12552 from:\InsetSpace ~
12553 array
12554 \family default
12555  writes the next n elements to the resource identified by the given low-level
12556  handle, from the given starting point.
12557  The contents are read from the given array, which should be a 
12558 \family typewriter
12559 ByteArray
12560 \family default
12561  currently.
12562 \end_layout
12564 \begin_layout Paragraph
12565 Standard behavior
12566 \end_layout
12568 \begin_layout Description
12570 \family typewriter
12571 \begin_inset LatexCommand index
12572 name "open (message)"
12574 \end_inset
12576 open
12577 \family default
12578  Opens the resource for usage within the system.
12579 \end_layout
12581 \begin_layout Description
12583 \family typewriter
12584 \begin_inset LatexCommand index
12585 name "close (message)"
12587 \end_inset
12589 close
12590 \family default
12591  Closes the resource, releasing related administrative data; this happens
12592  automatically during garbage collection, but it is poor practice to rely
12593  upon this.
12594 \end_layout
12596 \begin_layout Description
12598 \family typewriter
12599 \begin_inset LatexCommand index
12600 name "enable (message)"
12602 \end_inset
12604 enable
12605 \family default
12606  Creates the external resource represented (used by 
12607 \family typewriter
12608 open
12609 \family default
12611 \end_layout
12613 \begin_layout Description
12615 \family typewriter
12616 \begin_inset LatexCommand index
12617 name "isOpen (message)"
12619 \end_inset
12621 isOpen
12622 \family default
12623  answers whether the resource is open or closed.
12624 \end_layout
12626 \begin_layout Description
12628 \family typewriter
12629 \begin_inset LatexCommand index
12630 name "isActive (message)"
12632 \end_inset
12634 isActive
12635 \family default
12636  answers whether the resource is active.
12637 \end_layout
12639 \begin_layout Description
12641 \family typewriter
12642 \begin_inset LatexCommand index
12643 name "restart (message)"
12645 \end_inset
12647 restart
12648 \family default
12649  restarts the resource if it's already active.
12650 \end_layout
12652 \begin_layout Description
12654 \family typewriter
12655 \begin_inset LatexCommand index
12656 name "flush (message)"
12658 \end_inset
12660 flush
12661 \family default
12662  flushes any unwritten elements.
12663 \end_layout
12665 \begin_layout Description
12667 \family typewriter
12668 \begin_inset LatexCommand index
12669 name "commit (message)"
12671 \end_inset
12673 commit
12674 \family default
12675  commits all pending write-out information to the resource.
12676  Commit performs a flush but also ensures that the data is actually sent
12677  to the peer.
12678 \end_layout
12680 \begin_layout Description
12682 \family typewriter
12683 \begin_inset LatexCommand index
12684 name "read:startingAt:into: (mesage)"
12686 \end_inset
12688 read:startingAt:into:
12689 \family default
12690  sends 
12691 \family typewriter
12692 read:from:startingAt:into:
12693 \family default
12694  with the resource's handle.
12695 \end_layout
12697 \begin_layout Description
12699 \family typewriter
12700 \begin_inset LatexCommand index
12701 name "write:startingAt:into: (message)"
12703 \end_inset
12705 write:startingAt:from:
12706 \family default
12707  sends 
12708 \family typewriter
12709 write:to:startingAt:from:
12710 \family default
12711  with the resource's handle.
12712 \end_layout
12714 \begin_layout Description
12716 \family typewriter
12717 \begin_inset LatexCommand index
12718 name "interactor (message)"
12720 \end_inset
12722 interactor
12723 \family default
12724  returns a 
12725 \family typewriter
12726 ReadWriteStream
12727 \family default
12728  for accessing the resource.
12729  Unlike the stream that 
12730 \family typewriter
12731 iterator
12732 \family default
12733  returns, 
12734 \family typewriter
12735 interactor
12736 \family default
12737  is expected to return a coupled pair of a 
12738 \family typewriter
12739 ReadStream
12740 \family default
12741  and 
12742 \family typewriter
12743 WriteStream
12744 \family default
12745  over the same resource, synchronized to preserve the resource's behavior.
12746 \end_layout
12748 \begin_layout Description
12750 \family typewriter
12751 \begin_inset LatexCommand index
12752 name "bufferSize (message)"
12754 \end_inset
12756 bufferSize
12757 \family default
12758  answers a sensible buffer size for interaction, possibly dynamically determined.
12759 \end_layout
12761 \begin_layout Description
12763 \family typewriter
12764 \begin_inset LatexCommand index
12765 name "defaultBufferSize (message)"
12767 \end_inset
12769 defaultBufferSize
12770 \family default
12771  answers a default sensible buffer size for interaction.
12772 \end_layout
12774 \begin_layout Description
12776 \family typewriter
12777 \begin_inset LatexCommand index
12778 name "locator (message)"
12780 \end_inset
12782 locator
12783 \family default
12784  answers a suitable structured object for dealing with that resource's identity/
12785 location.
12786 \end_layout
12788 \begin_layout Description
12790 \family typewriter
12791 \begin_inset LatexCommand index
12792 name "sessionDo: (message)"
12794 \end_inset
12796 sessionDo:
12797 \family default
12798  executes a code block with the resource as its argument, opening and closing
12799  the resource transparently to the block, even for abnormal terminations.
12800  If the resource is already open, then this takes no opening or closing
12801  actions, so that calls may be nested blindly.
12802 \end_layout
12804 \begin_layout Subsubsection
12805 Consoles
12806 \end_layout
12808 \begin_layout Standard
12809 \begin_inset LatexCommand index
12810 name "Console (object)"
12812 \end_inset
12815 \begin_inset LatexCommand index
12816 name "ConsoleInput (object)"
12818 \end_inset
12821 \begin_inset LatexCommand index
12822 name "ConsoleOutput (object)"
12824 \end_inset
12826 The Slate interpreter provides two console 
12827 \family typewriter
12828 Streams
12829 \family default
12830  primitively, 
12831 \family typewriter
12832 ConsoleInput
12833 \family default
12834  and 
12835 \family typewriter
12836 ConsoleOutput
12837 \family default
12838 , which are 
12839 \family typewriter
12840 Read
12841 \family default
12842 - and 
12843 \family typewriter
12844 WriteStreams
12845 \family default
12846  by default, capturing keyboard input and writing out to the console, respective
12848  These are also accessible as 
12849 \family typewriter
12850 Console\InsetSpace ~
12851 reader
12852 \family default
12853  and 
12854 \family typewriter
12855 Console\InsetSpace ~
12856 writer
12857 \family default
12860 \family typewriter
12861 Console\InsetSpace ~
12862 interactor
12863 \family default
12864  delegates to these, acting as a 
12865 \family typewriter
12866 ReadWriteStream
12867 \family default
12869 \end_layout
12871 \begin_layout Subsubsection
12872 Files
12873 \end_layout
12875 \begin_layout Standard
12876 \begin_inset LatexCommand index
12877 name "files"
12879 \end_inset
12882 \begin_inset LatexCommand index
12883 name "File (object)"
12885 \end_inset
12887 Files are persistent external sequences of bytes.
12888  The interpreter provides an object type 
12889 \family typewriter
12890 File
12891 \family default
12892  which provides the corresponding protocol extensions to 
12893 \family typewriter
12894 ExternalResource
12895 \family default
12897 \end_layout
12899 \begin_layout Description
12901 \family typewriter
12902 \begin_inset LatexCommand index
12903 name "newNamed:\\&mode: (message)"
12905 \end_inset
12907 newNamed:&mode:
12908 \family default
12909  returns a new 
12910 \family typewriter
12911 File
12912 \family default
12913  with the given name as its locator and also a mode option.
12914  No attempt to open the file is automatically made.
12915 \end_layout
12917 \begin_layout Description
12919 \family typewriter
12920 \begin_inset LatexCommand index
12921 name "sessionDo:\\&mode: (message)"
12923 \end_inset
12925 sessionDo:&mode:
12926 \family default
12927  extends 
12928 \family typewriter
12929 sessionDo:
12930 \family default
12931  with a simple temporary mode option (which is reset on return).
12932 \end_layout
12934 \begin_layout Description
12936 \family typewriter
12937 \begin_inset LatexCommand index
12938 name "withOpenNamed:Do:\\&mode: (message)"
12940 \end_inset
12942 withOpenNamed:do:&mode:
12943 \family default
12944  wraps 
12945 \family typewriter
12946 sessionDo:
12947 \family default
12948  with the ability to create a new 
12949 \family typewriter
12950 File
12951 \family default
12952  dynamically for the session along with a specified mode.
12953 \end_layout
12955 \begin_layout Description
12957 \family typewriter
12958 \begin_inset LatexCommand index
12959 name "position (message)"
12961 \end_inset
12963 position
12964 \family default
12965  returns the position within the 
12966 \family typewriter
12967 File
12968 \family default
12969  in byte units.
12970 \end_layout
12972 \begin_layout Description
12974 \family typewriter
12975 \begin_inset LatexCommand index
12976 name "position: (message)"
12978 \end_inset
12980 position:
12981 \family default
12982  sets the position within the 
12983 \family typewriter
12984 File
12985 \family default
12986  to the given integer number of bytes.
12987 \end_layout
12989 \begin_layout Description
12991 \family typewriter
12992 \begin_inset LatexCommand index
12993 name "size (message)"
12995 \end_inset
12997 size
12998 \family default
12999  returns the 
13000 \family typewriter
13001 File
13002 \family default
13003  size in bytes.
13004 \end_layout
13006 \begin_layout Description
13008 \family typewriter
13009 \begin_inset LatexCommand index
13010 name "name (message)"
13012 \end_inset
13014 name
13015 \family default
13016  returns the 
13017 \family typewriter
13018 File
13019 \family default
13020 's pathname.
13021 \end_layout
13023 \begin_layout Description
13025 \family typewriter
13026 \begin_inset LatexCommand index
13027 name "fullName (message)"
13029 \end_inset
13031 fullName
13032 \family default
13033  will always return a complete pathname whereas the regular method may not.
13034 \end_layout
13036 \begin_layout Description
13038 \family typewriter
13039 \begin_inset LatexCommand index
13040 name "renamedTo: (message)"
13042 \end_inset
13044 renameTo:
13045 \family default
13046  adjusts the file to have the given name.
13047 \end_layout
13049 \begin_layout Description
13051 \family typewriter
13052 \begin_inset LatexCommand index
13053 name "atEnd (message)"
13055 \end_inset
13057 isAtEnd
13058 \family default
13059  answers whether the file's end has been reached.
13060 \end_layout
13062 \begin_layout Description
13064 \family typewriter
13065 \begin_inset LatexCommand index
13066 name "create (message)"
13068 \end_inset
13070 create
13071 \family default
13072  makes a file with the given name, with empty contents.
13073 \end_layout
13075 \begin_layout Description
13077 \family typewriter
13078 \begin_inset LatexCommand index
13079 name "exists (message)"
13081 \end_inset
13083 exists
13084 \family default
13085  answers whether there is a file with the object's pathname.
13086 \end_layout
13088 \begin_layout Description
13090 \family typewriter
13091 \begin_inset LatexCommand index
13092 name "delete (message)"
13094 \end_inset
13096 delete
13097 \family default
13098  deletes the file.
13099 \end_layout
13101 \begin_layout Standard
13102 \begin_inset LatexCommand index
13103 name "load: (message)"
13105 \end_inset
13107 Perhaps the most important utility is to load libraries based on path names.
13109 \family typewriter
13110 load: 'filename'
13111 \family default
13112  will execute a file with the given path name as Slate source.
13113 \end_layout
13115 \begin_layout Standard
13116 \begin_inset LatexCommand index
13117 name "File Read (object)"
13119 \end_inset
13122 \begin_inset LatexCommand index
13123 name "File Write (object)"
13125 \end_inset
13128 \begin_inset LatexCommand index
13129 name "File ReadWrite (object)"
13131 \end_inset
13134 \begin_inset LatexCommand index
13135 name "File CreateWrite (object)"
13137 \end_inset
13139 File mode objects specify the interaction capabilities requested of the
13140  underlying system for the handle.
13141  The modes consist of 
13142 \family typewriter
13143 File\InsetSpace ~
13144 Read
13145 \family default
13147 \family typewriter
13148 File\InsetSpace ~
13149 Write
13150 \family default
13152 \family typewriter
13153 File\InsetSpace ~
13154 ReadWrite
13155 \family default
13156 , and 
13157 \family typewriter
13158 File\InsetSpace ~
13159 CreateWrite
13160 \family default
13162 \end_layout
13164 \begin_layout Subsubsection
13165 Shells and Pipes (Not Currently Implemented)
13166 \begin_inset OptArg
13167 status collapsed
13169 \begin_layout Standard
13170 Shells and Pipes
13171 \end_layout
13173 \end_inset
13176 \end_layout
13178 \begin_layout Standard
13179 \begin_inset LatexCommand index
13180 name "Shell (object)"
13182 \end_inset
13185 \begin_inset LatexCommand index
13186 name "Environment (object)"
13188 \end_inset
13190 The 
13191 \family typewriter
13192 Shell
13193 \family default
13194  and 
13195 \family typewriter
13196 Environment
13197 \family default
13198  globals are provided to access the underlying operating system's command
13199  shell functionality from within the Slate environment.
13201 \family typewriter
13202 Shell
13203 \family default
13204  provides a dispatch hook for shell-related methods, while 
13205 \family typewriter
13206 Environment
13207 \family default
13208  acts as a 
13209 \family typewriter
13210 Dictionary
13211 \family default
13212  of the current shell context's defined variables and values.
13213  They support several primitive methods as follows:
13214 \end_layout
13216 \begin_layout Description
13218 \family typewriter
13219 \begin_inset LatexCommand index
13220 name "enter (message)"
13222 \end_inset
13224 Shell\InsetSpace ~
13225 enter
13226 \family default
13227  enters the host operating system's command-line shell.
13228  This has no effect on the Slate environment directly except for suspending
13229  and resuming it.
13230 \end_layout
13232 \begin_layout Description
13234 \family typewriter
13235 \begin_inset LatexCommand index
13236 name "runProgram:withArgs: (message)"
13238 \end_inset
13240 Shell\InsetSpace ~
13241 runProgram:\InsetSpace ~
13242 programName\InsetSpace ~
13243 withArgs:\InsetSpace ~
13244 argsArray
13245 \family default
13246  executes the program with the given name and passes it the arguments which
13247  must be 
13248 \family typewriter
13249 Strings
13250 \family default
13252 \end_layout
13254 \begin_layout Description
13256 \family typewriter
13257 \begin_inset LatexCommand index
13258 name "execute: (message)"
13260 \end_inset
13262 Shell\InsetSpace ~
13263 execute:\InsetSpace ~
13264 scriptFilename
13265 \family default
13266  passes the contents of the file named along to the shell, returning its
13267  output.
13268 \end_layout
13270 \begin_layout Description
13272 \family typewriter
13273 \begin_inset LatexCommand index
13274 name "at: (message)"
13276 \end_inset
13278 Environment\InsetSpace ~
13279 at:\InsetSpace ~
13280 varName
13281 \family default
13282  returns the value stored in a given environment variable.
13283 \end_layout
13285 \begin_layout Description
13287 \family typewriter
13288 \begin_inset LatexCommand index
13289 name "at:put: (message)"
13291 \end_inset
13293 Environment\InsetSpace ~
13294 at:\InsetSpace ~
13295 varName\InsetSpace ~
13296 put:\InsetSpace ~
13297 newValue
13298 \family default
13299  stores the new value into the given environment variable named.
13300 \end_layout
13302 \begin_layout Description
13304 \family typewriter
13305 \begin_inset LatexCommand index
13306 name "keys (message)"
13308 \end_inset
13310 Environment\InsetSpace ~
13311 keys
13312 \family default
13313  returns an 
13314 \family typewriter
13315 Array
13316 \family default
13317  of the environment variable names defined in the context that Slate was
13318  executed in.
13319  This result is independent of the actual environment variables.
13320 \end_layout
13322 \begin_layout Description
13324 \family typewriter
13325 \begin_inset LatexCommand index
13326 name "values (message)"
13328 \end_inset
13330 Environment\InsetSpace ~
13331 values
13332 \family default
13333  returns an 
13334 \family typewriter
13335 Array
13336 \family default
13337  of the environment variable values in the context that Slate was executed
13338  in, in the same order as the keys are returned.
13339  This result is independent of the actual environment variables.
13340 \end_layout
13342 \begin_layout Subsubsection
13343 Networking
13344 \end_layout
13346 \begin_layout Standard
13348 \family typewriter
13349 \begin_inset LatexCommand index
13350 name "Socket (object)"
13352 \end_inset
13354 Socket
13355 \family default
13356 s are 
13357 \family typewriter
13358 ExternalResources
13359 \family default
13360  that provide a connection on an operating system port.
13361  The behaviors specific to these two types are as follows:
13362 \end_layout
13364 \begin_layout Description
13366 \family typewriter
13367 \begin_inset LatexCommand index
13368 name "newOnPort: (message)"
13370 \end_inset
13372 newOnPort:
13373 \family default
13374  creates a new socket of the appropriate type to listen/request on the port
13375  number.
13376 \end_layout
13378 \begin_layout Description
13380 \family typewriter
13381 \begin_inset LatexCommand index
13382 name "listen (message)"
13384 \end_inset
13386 listen\InsetSpace ~
13387 &buffer:
13388 \family default
13389  sets the port to listening for client connections, with an optional override
13390  of the system default number of request queue entries.
13391 \end_layout
13393 \begin_layout Description
13395 \family typewriter
13396 \begin_inset LatexCommand index
13397 name "accept (message)"
13399 \end_inset
13401 accept
13402 \family default
13403  creates a new socket connection for the next incoming request.
13404 \end_layout
13406 \begin_layout Description
13408 \family typewriter
13409 \begin_inset LatexCommand index
13410 name "shutdown (message)"
13412 \end_inset
13414 shutdown
13415 \family default
13416  shuts down the socket, called when closing (automatically).
13417 \end_layout
13419 \begin_layout Description
13421 \family typewriter
13422 \begin_inset LatexCommand index
13423 name "host (message)"
13425 \end_inset
13427 host
13428 \family default
13429  answers the hostname of the socket.
13430 \end_layout
13432 \begin_layout Description
13434 \family typewriter
13435 \begin_inset LatexCommand index
13436 name "port (message)"
13438 \end_inset
13440 port
13441 \family default
13442  answers the port number of the socket.
13443 \end_layout
13445 \begin_layout Description
13447 \family typewriter
13448 \begin_inset LatexCommand index
13449 name "peerHost (message)"
13451 \end_inset
13453 peerHost
13454 \family default
13455  answers the hostname of the peer.
13456 \end_layout
13458 \begin_layout Description
13460 \family typewriter
13461 \begin_inset LatexCommand index
13462 name "peerPort (message)"
13464 \end_inset
13466 peerPort
13467 \family default
13468  answers the peer's port number.
13469 \end_layout
13471 \begin_layout Description
13473 \family typewriter
13474 \begin_inset LatexCommand index
13475 name "peerIP (message)"
13477 \end_inset
13479 peerIP
13480 \family default
13481  answers the Internet Protocol address string of the peer, if any.
13482 \end_layout
13484 \begin_layout Description
13486 \family typewriter
13487 \begin_inset LatexCommand index
13488 name "status (message)"
13490 \end_inset
13492 status
13493 \family default
13494  answers a 
13495 \family typewriter
13496 Symbol
13497 \family default
13498  representing the socket's current status.
13499 \end_layout
13501 \begin_layout Subsection
13502 Paths
13503 \end_layout
13505 \begin_layout Standard
13506 Since the environment is structured into namespaces and many types have
13507  so-called 
13508 \begin_inset Quotes eld
13509 \end_inset
13511 attribute types
13512 \begin_inset Quotes erd
13513 \end_inset
13515  (for example, the iterator streams), it is helpful to have more than a
13516  name by which to refer to an object or its location in the system.
13517  The path library allows doing this with 
13518 \family typewriter
13519 Path
13520 \begin_inset LatexCommand index
13521 name "Path (object)"
13523 \end_inset
13526 \family default
13527  objects, which describe the sequence of slot traversals necessary to reach
13528  a particular object.
13529  A sub-variant called 
13530 \family typewriter
13531 RootedPath
13532 \begin_inset LatexCommand index
13533 name "RootedPath (object)"
13535 \end_inset
13538 \family default
13539  remembers the specific origin object used for the path and follows the
13540  same protocol.
13541 \end_layout
13543 \begin_layout Description
13545 \family typewriter
13546 Path\InsetSpace ~
13547 from:\InsetSpace ~
13548 root\InsetSpace ~
13549 to:\InsetSpace ~
13550 target
13551 \begin_inset LatexCommand index
13552 name "from:to: (message)"
13554 \end_inset
13557 \family default
13558  creates a new 
13559 \family typewriter
13560 Path
13561 \family default
13562  object containing the necessary slot traversals to obtain the target object
13563  (the destination) from the given root (the origin).
13564  Paths are created by searching breadth-first through slot names; if the
13565  search completes without an identical match, 
13566 \family typewriter
13568 \family default
13569  is returned.
13570 \end_layout
13572 \begin_layout Description
13574 \family typewriter
13576 \begin_inset LatexCommand index
13577 name "to: (message)"
13579 \end_inset
13582 \family default
13583  works like 
13584 \family typewriter
13585 from:to:
13586 \family default
13587  except that 
13588 \family typewriter
13589 here
13590 \family default
13591  is taken as the origin.
13592 \end_layout
13594 \begin_layout Description
13596 \family typewriter
13597 target
13598 \begin_inset LatexCommand index
13599 name "target (message)"
13601 \end_inset
13604 \family default
13605  answers the target object as computed by following the slot names from
13606  the origin.
13607 \end_layout
13609 \begin_layout Description
13611 \family typewriter
13612 targetFrom:
13613 \begin_inset LatexCommand index
13614 name "targetFrom: (message)"
13616 \end_inset
13619 \family default
13620  answers the target object relative to the given one, taking it as the origin.
13621 \end_layout
13623 \begin_layout Description
13625 \family typewriter
13626 reduced
13627 \begin_inset LatexCommand index
13628 name "reduced (message)"
13630 \end_inset
13633 \family default
13634  answers another equivalent 
13635 \family typewriter
13636 Path
13637 \family default
13638  object consisting of all non-delegation slots traversed.
13639  This gives a 
13640 \begin_inset Quotes eld
13641 \end_inset
13643 canonical
13644 \begin_inset Quotes erd
13645 \end_inset
13647  or shortest path to the object.
13648 \end_layout
13650 \begin_layout Description
13652 \family typewriter
13653 expanded
13654 \begin_inset LatexCommand index
13655 name "expanded (message)"
13657 \end_inset
13660 \family default
13661  answers another equivalent 
13662 \family typewriter
13663 Path
13664 \family default
13665  object consisting of all delegation slots required to traverse to reach
13666  the object directly.
13667 \end_layout
13669 \begin_layout Description
13671 \family typewriter
13672 root\InsetSpace ~
13673 knows:\InsetSpace ~
13674 target
13675 \begin_inset LatexCommand index
13676 name "target (message)"
13678 \end_inset
13681 \family default
13682  answers whether there is a 
13683 \family typewriter
13684 Path
13685 \family default
13686  from the given root to the target.
13687 \end_layout
13689 \begin_layout Description
13691 \family typewriter
13692 isWellKnown
13693 \begin_inset LatexCommand index
13694 name "isWellKnown (message)"
13696 \end_inset
13699 \family default
13700  answers whether there is a 
13701 \family typewriter
13702 Path
13703 \family default
13704  from the 
13705 \family typewriter
13706 lobby
13707 \family default
13708  to the given object.
13709 \end_layout
13711 \begin_layout Standard
13713 \family typewriter
13714 Path
13715 \family default
13716  objects also respond to relevant 
13717 \family typewriter
13718 Sequence
13719 \family default
13720  protocols such as 
13721 \family typewriter
13723 \begin_inset LatexCommand index
13724 name "; (message)"
13726 \end_inset
13729 \family default
13730  and 
13731 \family typewriter
13732 isPrefixOf:
13733 \begin_inset LatexCommand index
13734 name "isPrefixOf: (message)"
13736 \end_inset
13739 \family default
13740  among other paths.
13741 \end_layout
13743 \begin_layout Subsection
13744 Exceptional Situations and Errors
13745 \begin_inset OptArg
13746 status open
13748 \begin_layout Standard
13749 Exceptions
13750 \end_layout
13752 \end_inset
13755 \end_layout
13757 \begin_layout Standard
13758 \begin_inset LatexCommand index
13759 name "error handling"
13761 \end_inset
13764 \begin_inset LatexCommand index
13765 name "exceptions"
13767 \end_inset
13770 \begin_inset LatexCommand index
13771 name "Condition (object)"
13773 \end_inset
13775 Slate has a special kind of object representing when an exceptional situation
13776  has been reached in a program, called a 
13777 \family typewriter
13778 Condition
13779 \family default
13781  Condition objects may have attributes and methods like other ordinary objects,
13782  but have special methods for dealing with exceptional situations and recovering
13783  from them in various ways, often automatically.
13784 \end_layout
13786 \begin_layout Subsubsection
13787 Types
13788 \end_layout
13790 \begin_layout Description
13792 \family typewriter
13793 \begin_inset LatexCommand index
13794 name "Condition (object)"
13796 \end_inset
13798 Condition
13799 \family default
13800  An object representing a situation which must be handled.
13801  This also provides a hook for working with the control-flow of the situation,
13802  and dynamic unwinding of control.
13803 \end_layout
13805 \begin_layout Description
13807 \family typewriter
13808 \begin_inset LatexCommand index
13809 name "Restart (object)"
13811 \end_inset
13813 Restart
13814 \family default
13815  An object representing and controlling how a condition is handled.
13816  Because they are a kind of 
13817 \family typewriter
13818 Condition
13819 \family default
13820 , they can themselves be handled dynamically.
13821 \end_layout
13823 \begin_layout Description
13825 \family typewriter
13826 \begin_inset LatexCommand index
13827 name "Warning (object)"
13829 \end_inset
13832 \begin_inset LatexCommand index
13833 name "warn: (message)"
13835 \end_inset
13837 Warning
13838 \family default
13839  A 
13840 \family typewriter
13841 Condition
13842 \family default
13843  which should generate notifications, but does not need to be raised for
13844  handling, i.e.
13845  no action needs to be taken.
13846  Raised by 
13847 \family typewriter
13848 warn:
13849 \family default
13850  with a description.
13851 \end_layout
13853 \begin_layout Description
13855 \family typewriter
13856 \begin_inset LatexCommand index
13857 name "StyleWarning (object)"
13859 \end_inset
13862 \begin_inset LatexCommand index
13863 name "note: (message)"
13865 \end_inset
13867 StyleWarning
13868 \family default
13869  A 
13870 \family typewriter
13871 Warning
13872 \family default
13873  that certain conventions set up by the library author have not been followed,
13874  which could lead to problems.
13875  Raised by 
13876 \family typewriter
13877 note:
13878 \family default
13879  with a description.
13880 \end_layout
13882 \begin_layout Description
13884 \family typewriter
13885 \begin_inset LatexCommand index
13886 name "BreakPoint (object)"
13888 \end_inset
13891 \begin_inset LatexCommand index
13892 name "break (message)"
13894 \end_inset
13896 BreakPoint
13897 \family default
13898  A 
13899 \family typewriter
13900 Condition
13901 \family default
13902  that pauses the current computation.
13903  Raised by 
13904 \family typewriter
13905 break
13906 \family default
13907  in a context.
13908 \end_layout
13910 \begin_layout Description
13912 \family typewriter
13913 \begin_inset LatexCommand index
13914 name "Abort (object)"
13916 \end_inset
13919 \begin_inset LatexCommand index
13920 name "abort (message)"
13922 \end_inset
13924 Abort
13925 \family default
13926  A 
13927 \family typewriter
13928 Restart
13929 \family default
13930  which unwinds the stack and cleans up contexts after a condition is raised.
13931  This is raised by the context method 
13932 \family typewriter
13933 abort
13934 \family default
13936 \end_layout
13938 \begin_layout Description
13940 \family typewriter
13941 \begin_inset LatexCommand index
13942 name "SeriousCondition (object)"
13944 \end_inset
13946 SeriousCondition
13947 \family default
13948  A 
13949 \family typewriter
13950 Condition
13951 \family default
13952  that requires handling, but is not a semantic error of the program.
13953  Rather, it's due to some incidental or pragmatic consideration.
13954 \end_layout
13956 \begin_layout Description
13958 \family typewriter
13959 \begin_inset LatexCommand index
13960 name "Error (object)"
13962 \end_inset
13965 \begin_inset LatexCommand index
13966 name "error: (message)"
13968 \end_inset
13970 Error
13971 \family default
13972  A 
13973 \family typewriter
13974 SeriousCondition
13975 \family default
13976  which involves some misstep in program logic, and raises the need for handlers
13977  to avoid a program crash.
13978  Raised by 
13979 \family typewriter
13980 error:
13981 \family default
13982  with a description.
13983 \end_layout
13985 \begin_layout Subsubsection
13986 Protocol
13987 \end_layout
13989 \begin_layout Description
13991 \family typewriter
13992 \begin_inset LatexCommand index
13993 name "signal (message)"
13995 \end_inset
13997 signal
13998 \family default
13999  Raises the exception that is the argument.
14000  This will immediately query for exception handlers in the current context,
14001  performing dynamic automatic recovery if possible, or starting the debugger
14002  if not.
14003 \end_layout
14005 \begin_layout Description
14007 \family typewriter
14008 \begin_inset LatexCommand index
14009 name "on:do: (message)"
14011 \end_inset
14013 on:do:
14014 \family default
14015  Executes the block of code with a dynamically bound handler block for the
14016  given type of condition.
14017 \end_layout
14019 \begin_layout Description
14021 \family typewriter
14022 \begin_inset LatexCommand index
14023 name "ensure: (message)"
14025 \end_inset
14027 ensure:
14028 \family default
14029  This is a block method that ensures that the second block is executed either
14030  after the first or in 
14031 \emph on
14033 \emph default
14034  case if the original is aborted or control is otherwise handed elsewhere
14035  in the middle of execution without possibility of returning into that same
14036  execution.
14037 \end_layout
14039 \begin_layout Description
14041 \family typewriter
14042 \begin_inset LatexCommand index
14043 name "handlingCases: (message)"
14045 \end_inset
14047 handlingCases:
14048 \family default
14049  Executes the block of code with a set of dynamically bound handler blocks,
14050  give as an 
14051 \family typewriter
14052 Array
14053 \family default
14054  of 
14055 \family typewriter
14056 Association
14057 \family default
14058 s between 
14059 \family typewriter
14060 Condition
14061 \family default
14062  objects and the handlers.
14063 \end_layout
14065 \begin_layout Description
14067 \family typewriter
14068 \begin_inset LatexCommand index
14069 name "return (message)"
14071 \end_inset
14074 \begin_inset LatexCommand index
14075 name "return: (message)"
14077 \end_inset
14079 return
14080 \family default
14082 \family typewriter
14083 return:
14084 \family default
14085  Returns from the condition with a value (default 
14086 \family typewriter
14088 \family default
14089 ), to the point where the condition was signalled.
14090 \end_layout
14092 \begin_layout Description
14094 \family typewriter
14095 \begin_inset LatexCommand index
14096 name "exit (message)"
14098 \end_inset
14101 \begin_inset LatexCommand index
14102 name "exit: (message)"
14104 \end_inset
14106 exit
14107 \family default
14109 \family typewriter
14110 exit:
14111 \family default
14112  Aborts from the condition, or aborts from it with a value, to the point
14113  where the handler was set up.
14114 \end_layout
14116 \begin_layout Description
14118 \family typewriter
14119 \begin_inset LatexCommand index
14120 name "defaultHandler (message)"
14122 \end_inset
14124 defaultHandler
14125 \family default
14126  This is the condition method that is called if no other handlers are found
14127  for the context.
14128 \end_layout
14130 \begin_layout Subsection
14131 Concurrency
14132 \begin_inset LatexCommand index
14133 name "concurrency"
14135 \end_inset
14138 \end_layout
14140 \begin_layout Subsubsection
14141 Processes
14142 \end_layout
14144 \begin_layout Standard
14145 Concurrency mostly involves the unit of the 
14146 \family typewriter
14147 Process
14148 \family default
14149 , which is conceptually a manager for a single interpreter.
14150  Concurrency may be performed within the context of a single process, using
14151  stack / control-flow interaction, or across processes using messaging.
14152 \end_layout
14154 \begin_layout Standard
14156 \family typewriter
14157 Process
14158 \family default
14159 es in Slate run in turns, each acting as an interpreter with an event loop.
14160  They also act as object pools, being opaque and having a context with various
14161  local elements which must be explicitly published to be visible to objects
14162  in other Processes.
14163 \end_layout
14165 \begin_layout Subsubsection
14166 Promises and Eventual-Sends
14167 \end_layout
14169 \begin_layout Standard
14170 Coupled with event-loop concurrency is Slate's support of deferred execution,
14171  using the 
14172 \family typewriter
14174 \family default
14175  prefix for selectors (for the message-send) or for entire expressions.
14176  When a deferral is performed on a message-send, we call it an eventual
14177  message-send.
14178  If the return value is in a syntactic position where it might be used,
14179  the caller may expect an object of type 
14180 \family typewriter
14181 Reference
14182 \family default
14183  or 
14184 \family typewriter
14185 Promise
14186 \family default
14187  to be delivered as the answer.
14188  These objects are resolvable placeholders, which may also communicate errors
14189  in the requested computation.
14190 \end_layout
14192 \begin_layout Standard
14193 What's significant is that the use of deferred evaluation means that the
14194  relevant expression costs the caller nothing in the immediate execution
14195  turn; no matter how expensive side-effecting an expression may be, it will
14196  not be executed until at least the next turn in the owning process.
14197  Specifically, when a deferred expression is evaluated, it is turned into
14198  an event and added to the end of the owner 
14199 \family typewriter
14200 Process
14201 \family default
14202 ' queue.
14203  When a process finishes each turn, it executes one event at a time from
14204  the other end of the queue.
14205  Also, if one deferred expression involves the use of the return value from
14206  another deferred expression, the dependency will be enforced so that such
14207  events will execute in the data-flow partial order in which they were created.
14208 \end_layout
14210 \begin_layout Subsection
14211 Types
14212 \begin_inset LatexCommand label
14213 name "sub:Types"
14215 \end_inset
14218 \end_layout
14220 \begin_layout Standard
14221 \begin_inset LatexCommand index
14222 name "types"
14224 \end_inset
14227 \begin_inset LatexCommand index
14228 name "Types (namespace)"
14230 \end_inset
14232 In coordination with the reserved syntax for type-annotation in block headers,
14233  the standard libraries include a collection of representations of primitive
14235 \noun on
14236 types
14237 \noun default
14238  as well as quantifications over those types.
14239  The library of types is laid out within the non-delegated namespace 
14240 \family typewriter
14241 Types
14242 \family default
14243  in the lobby.
14244 \end_layout
14246 \begin_layout Subsubsection
14247 Types
14248 \end_layout
14250 \begin_layout Description
14252 \family typewriter
14253 \begin_inset LatexCommand index
14254 name "Any (type)"
14256 \end_inset
14259 \family default
14260  The type that any object satisfies: the universal type.
14261 \end_layout
14263 \begin_layout Description
14265 \family typewriter
14266 \begin_inset LatexCommand index
14267 name "None (type)"
14269 \end_inset
14271 None
14272 \family default
14273  The type that no object satisfies: the empty type.
14274 \end_layout
14276 \begin_layout Description
14278 \family typewriter
14279 \begin_inset LatexCommand index
14280 name "Range (type)"
14282 \end_inset
14285 \begin_inset LatexCommand index
14286 name "start (message)"
14288 \end_inset
14291 \begin_inset LatexCommand index
14292 name "finish (message)"
14294 \end_inset
14296 Range
14297 \family default
14298  A parametrized type over another type with a linear ordering, such as 
14299 \family typewriter
14300 Integer
14301 \family default
14303  This type is bounded, it has a 
14304 \family typewriter
14305 start
14306 \family default
14307  and a 
14308 \family typewriter
14309 finish
14310 \family default
14311  (least and greatest possible member).
14312  In general, any 
14313 \family typewriter
14314 Magnitude
14315 \family default
14316  can be used as a base of a Range type.
14317 \end_layout
14319 \begin_layout Description
14321 \family typewriter
14322 \begin_inset LatexCommand index
14323 name "Member (type)"
14325 \end_inset
14327 Member
14328 \family default
14329  The type associated with membership in a specific set of objects.
14330 \end_layout
14332 \begin_layout Description
14334 \family typewriter
14335 \begin_inset LatexCommand index
14336 name "Singleton (type)"
14338 \end_inset
14340 Singleton
14341 \family default
14342  The type of a single object, as distinct from any other object.
14343 \end_layout
14345 \begin_layout Description
14347 \family typewriter
14348 \begin_inset LatexCommand index
14349 name "Clone (type)"
14351 \end_inset
14353 Clone
14354 \family default
14355  The type of an object and its 
14356 \noun on
14357 clone family
14358 \noun default
14359 , the set of objects that are direct copies (clones plus changes to slot
14360  values) of it.
14361 \end_layout
14363 \begin_layout Description
14365 \family typewriter
14366 \begin_inset LatexCommand index
14367 name "Array (type)"
14369 \end_inset
14371 Array
14372 \family default
14373  The type representing all arrays, as parametrized by an element type and
14374  a length.
14375 \end_layout
14377 \begin_layout Description
14379 \family typewriter
14380 \begin_inset LatexCommand index
14381 name "Block (type)"
14383 \end_inset
14385 Block
14386 \family default
14387  The type representing code closures of a given (optional) input and output
14388  signature.
14389 \end_layout
14391 \begin_layout Subsubsection
14392 Operations
14393 \end_layout
14395 \begin_layout Standard
14396 \begin_inset LatexCommand index
14397 name "union: (message)"
14399 \end_inset
14402 \begin_inset LatexCommand index
14403 name "intersection: (message)"
14405 \end_inset
14408 \begin_inset LatexCommand index
14409 name "derive (message)"
14411 \end_inset
14414 \begin_inset LatexCommand index
14415 name "deriveWith: (message)"
14417 \end_inset
14419 Types may be combined in various ways, including 
14420 \family typewriter
14421 union:
14422 \family default
14424 \family typewriter
14425 intersection:
14426 \family default
14427 , and extended via 
14428 \family typewriter
14429 derive
14430 \family default
14431  which preserve type constraints on the derivations.
14432 \end_layout
14434 \begin_layout Subsubsection
14435 Type Annotations
14436 \end_layout
14438 \begin_layout Standard
14439 \begin_inset LatexCommand index
14440 name "type annotations"
14442 \end_inset
14445 \begin_inset LatexCommand index
14446 name "annotations, type"
14448 \end_inset
14450 Local slot specifiers in a Method header as well as input slot specifiers
14451  may have types optionally declared within the header.
14452  Within a method declaration expression, the input slots may be redundantly
14453  specified in the header as well as in the dispatch expression.
14454  However, if this is done, the header's specifier needs to be specified
14455  as an input slot and if multiple input slot types are specified, they should
14456  be specified in order.
14457 \end_layout
14459 \begin_layout Standard
14460 \begin_inset LatexCommand index
14461 name "exclamation mark"
14463 \end_inset
14466 \begin_inset LatexCommand index
14467 name "\\char `\\! (exclamation mark) "
14469 \end_inset
14471 The syntax is similar to that for 
14472 \family typewriter
14474 \family default
14475 -based dispatch notation: follow the slot name with the bang character 
14476 \begin_inset Quotes eld
14477 \end_inset
14480 \family typewriter
14482 \family default
14484 \begin_inset Quotes erd
14485 \end_inset
14487  and then a type expression, which may be a primitive or derived type.
14488  For example,
14489 \end_layout
14491 \begin_layout LyX-Code
14492 [| :foo!Integer bar | bar: (foo raisedTo: 3).
14494 \newline
14495 foo + bar] applyWith: 4.3.
14496 \end_layout
14498 \begin_layout Standard
14499 Type annotations don't use primitive expressions: the evaluator doesn't
14500  have a library of pre-built types at its disposal.
14501  Instead, Type annotation expressions are evaluated within the namespace
14502  named 
14503 \family typewriter
14504 Types
14505 \family default
14506  accessible from the 
14507 \family typewriter
14508 lobby
14509 \family default
14511  For this reason, user-defined named types should be installed in some place
14512  accessible through the 
14513 \family typewriter
14514 Types
14515 \family default
14516  path.
14517 \end_layout
14519 \begin_layout Subsubsection
14520 Type Inference
14521 \end_layout
14523 \begin_layout Standard
14524 \begin_inset LatexCommand index
14525 name "type inference"
14527 \end_inset
14530 \begin_inset LatexCommand index
14531 name "inference, type"
14533 \end_inset
14536 \begin_inset LatexCommand index
14537 name "inferTypes (message)"
14539 \end_inset
14541 Type-inference on syntax trees is driven by calling 
14542 \family typewriter
14543 inferTypes
14544 \family default
14545  on the 
14546 \family typewriter
14547 Syntax\InsetSpace ~
14548 Node
14549 \family default
14550  in question.
14551  This will process type information already annotated to produce derived
14552  annotations on related nodes.
14553 \end_layout
14555 \begin_layout Standard
14556 \begin_inset LatexCommand index
14557 name "rules (slot)"
14559 \end_inset
14561 Also, there is a facility to extend the type-inference capability per method.
14562  To explain, each Type object comes with a 
14563 \family typewriter
14564 rules
14565 \family default
14566  object slot that is dual to the traits delegate object; rules delegate
14567  as the traits do but do not confer to the types their methods.
14568  Instead, they are used by the inference system transparently to allow for
14569  more intelligent specialization.
14570  To wit:
14571 \end_layout
14573 \begin_layout LyX-Code
14574 _@((Member of: {True.
14575  False}) rules) ifTrue: then@(Block rules)
14576 \newline
14577    ifFalse: else@(Block rules)
14578 \newline
14580 \newline
14582   then returnType union: else returnType
14583 \newline
14585 \end_layout
14587 \begin_layout Standard
14588 is a type-inference extension method for 
14589 \family typewriter
14590 #ifTrue:ifFalse:
14591 \family default
14592  for any boolean and a pair of blocks, that the return type will be in the
14593  union of the blocks' return types.
14594 \end_layout
14596 \begin_layout Subsection
14597 Modules
14598 \end_layout
14600 \begin_layout Standard
14601 \begin_inset LatexCommand index
14602 name "modules"
14604 \end_inset
14607 \begin_inset LatexCommand index
14608 name "provides: (message)"
14610 \end_inset
14613 \begin_inset LatexCommand index
14614 name "requires: (message)"
14616 \end_inset
14619 \begin_inset LatexCommand index
14620 name "features (slot)"
14622 \end_inset
14625 \begin_inset LatexCommand index
14626 name "load: (message)"
14628 \end_inset
14631 \begin_inset LatexCommand index
14632 name "currentModule (slot)"
14634 \end_inset
14636 A simple module system is provided, designed to capture the bare essentials
14637  of a collection of coherent code.
14638  The current module system is just associated with each library file for
14639  simplicity's sake.
14640  The methods 
14641 \family typewriter
14642 provides:
14643 \family default
14644  and 
14645 \family typewriter
14646 requires:
14647 \family default
14648  applied to the context will add to and check against a global 
14649 \family typewriter
14650 features
14651 \family default
14652  sequence respectively, and missing requirements are noted as the code is
14653  loaded.
14654  Again for simplicity, 
14655 \family typewriter
14656 features
14657 \family default
14658  currently contains and expects 
14659 \family typewriter
14660 Symbols
14661 \family default
14663  The 
14664 \family typewriter
14665 load:
14666 \family default
14667  method also invokes a hook to set the 
14668 \family typewriter
14669 currentModule
14670 \family default
14671  in its context.
14672 \end_layout
14674 \begin_layout Subsubsection
14675 Types
14676 \end_layout
14678 \begin_layout Description
14680 \family typewriter
14681 \begin_inset LatexCommand index
14682 name "Module (object)"
14684 \end_inset
14686 Module
14687 \family default
14688  a group of objects and methods, along with some information about their
14689  definitions.
14690  Modules can also provide privacy boundaries, restricting certain methods'
14691  accessibility outside of the module.
14692 \end_layout
14694 \begin_layout Description
14696 \family typewriter
14697 \begin_inset LatexCommand index
14698 name "FileModule (object)"
14700 \end_inset
14702 FileModule
14703 \family default
14704  a module that has been built from source code from a file.
14705 \end_layout
14707 \begin_layout Description
14709 \family typewriter
14710 \begin_inset LatexCommand index
14711 name "System (object)"
14713 \end_inset
14715 System
14716 \family default
14717  a collection of modules that together provide some larger service.
14718  Systems notably support operations on them to control large-scale libraries.
14719 \end_layout
14721 \begin_layout Subsubsection
14722 Operations
14723 \end_layout
14725 \begin_layout Description
14727 \family typewriter
14728 \begin_inset LatexCommand index
14729 name "new (message)"
14731 \end_inset
14733 Module\InsetSpace ~
14735 \family default
14736  creates a new 
14737 \family typewriter
14738 Module
14739 \family default
14740  with no contents.
14741 \end_layout
14743 \begin_layout Description
14745 \family typewriter
14746 \begin_inset LatexCommand index
14747 name "newLocated: (message)"
14749 \end_inset
14751 Module\InsetSpace ~
14752 newLocated:
14753 \family default
14754  creates a new 
14755 \family typewriter
14756 Module
14757 \family default
14758  with the given locator (a filename produces a 
14759 \family typewriter
14760 FileModule
14761 \family default
14763 \end_layout
14765 \begin_layout Description
14767 \family typewriter
14768 \begin_inset LatexCommand index
14769 name "newForFileNamed: (message)"
14771 \end_inset
14773 Module\InsetSpace ~
14774 newForFileNamed:
14775 \family default
14776  creates a new 
14777 \family typewriter
14778 FileModule
14779 \family default
14780  for the given file name.
14781 \end_layout
14783 \begin_layout Description
14785 \family typewriter
14786 \begin_inset LatexCommand index
14787 name "load (message)"
14789 \end_inset
14791 load
14792 \family default
14793  loads the module or system.
14794 \end_layout
14796 \begin_layout Description
14798 \family typewriter
14799 \begin_inset LatexCommand index
14800 name "build (message)"
14802 \end_inset
14804 build
14805 \family default
14806  (re-)builds the module or system.
14807 \end_layout
14809 \begin_layout Description
14811 \family typewriter
14812 \begin_inset LatexCommand index
14813 name "provide: (message)"
14815 \end_inset
14817 provide:
14818 \family default
14819  adds the element to the module's provision collection.
14820 \end_layout
14822 \begin_layout Description
14824 \family typewriter
14825 \begin_inset LatexCommand index
14826 name "provides: (message)"
14828 \end_inset
14830 provides:
14831 \family default
14832  declares a collection's elements to be provided by the current module.
14833 \end_layout
14835 \begin_layout Description
14837 \family typewriter
14838 \begin_inset LatexCommand index
14839 name "requires: (message)"
14841 \end_inset
14843 requires:
14844 \family default
14845  declares a collection's elements to be required by the current context.
14846  If any are not found, an error is raised.
14847 \begin_inset Foot
14848 status collapsed
14850 \begin_layout Standard
14851 In the future, automatic querying and loading an appropriate module could
14852  be added.
14853 \end_layout
14855 \end_inset
14858 \end_layout
14860 \begin_layout Description
14862 \family typewriter
14863 \begin_inset LatexCommand index
14864 name "import:from: (message)"
14866 \end_inset
14868 import:from:
14869 \family default
14870  adds an element to the import collection of the current module from the
14871  other one's provisions.
14872  If it's not provided by the other module, an error is raised.
14873 \end_layout
14875 \begin_layout Description
14877 \family typewriter
14878 \begin_inset LatexCommand index
14879 name "importAll:from: (message)"
14881 \end_inset
14883 importAll:from:
14884 \family default
14885  adds a collection's elements to the import collection of the current module
14886  from the other one's provisions.
14887  If it's not provided by the other module, an error is raised.
14888 \end_layout
14890 \begin_layout Subsubsection
14891 Auto-loading
14892 \end_layout
14894 \begin_layout Standard
14895 \begin_inset LatexCommand index
14896 name "AutoLoader (object)"
14898 \end_inset
14900 The 
14901 \family typewriter
14902 AutoLoader
14903 \family default
14904  object manages unloaded 
14905 \family typewriter
14906 Module
14907 \family default
14908 s and allows them to be transparently loaded when their features are requested
14909  (via simple message-send).
14910  This mechanism relies primarily on defining methods which mimick accessors
14911  for the actual resolved object exactly, except for the fact that their
14912  action involves loading the file and then re-sending the message once that
14913  completes successfully.
14914  It is essential that the match between stub and feature be exact, since
14915  the feature itself must replace the stub once done.
14916  However, the standard protocol hides these mechanics and verification successfu
14917 lly, as follows:
14918 \end_layout
14920 \begin_layout Description
14921 AutoLoader
14922 \family typewriter
14923 \InsetSpace ~
14925 \family default
14926 readFromSourceIn: takes a 
14927 \family typewriter
14928 File\InsetSpace ~
14929 Locator
14930 \family default
14931 , reads the source in the file, and fills the database with mappings from
14932  the features it defines to the module representing it.
14933 \end_layout
14935 \begin_layout Description
14937 \family typewriter
14938 AutoLoader\InsetSpace ~
14939 performScan\InsetSpace ~
14940 &files:
14941 \family default
14942  takes a list of 
14943 \family typewriter
14944 File\InsetSpace ~
14945 Locator
14946 \family default
14947 s, runnung 
14948 \family typewriter
14949 readFromSourceIn:
14950 \family default
14951  on each.
14952  By default it scans a default list.
14953 \end_layout
14955 \begin_layout Description
14957 \family typewriter
14958 AutoLoader\InsetSpace ~
14959 installReadyItems
14960 \family default
14961  reads definitions in the database, installing stubs for those which only
14962  take one message to resolve.
14963 \end_layout
14965 \begin_layout Description
14967 \family typewriter
14968 AutoLoader\InsetSpace ~
14969 writeToStorage
14970 \family default
14971  writes its definitions to a default external database file for quick re-constit
14972 ution.
14973 \end_layout
14975 \begin_layout Description
14977 \family typewriter
14978 AutoLoader\InsetSpace ~
14979 readStorage
14980 \family default
14981  reads definitions from the default external database file.
14982  It will automatically calling 
14983 \family typewriter
14984 installReadyItems
14985 \family default
14987 \end_layout
14989 \begin_layout Subsection
14990 Persistence
14991 \end_layout
14993 \begin_layout Subsubsection
14994 Slate Heap Images
14995 \end_layout
14997 \begin_layout Standard
14998 Slate's environment is available for saving as a whole via the representative
14999  object 
15000 \family typewriter
15002 \begin_inset LatexCommand index
15003 name "Image (object)"
15005 \end_inset
15007 Image
15008 \family default
15010  It offers the following methods:
15011 \end_layout
15013 \begin_layout Description
15015 \family typewriter
15016 \begin_inset LatexCommand index
15017 name "save (message)"
15019 \end_inset
15021 save\InsetSpace ~
15022 &name:
15023 \family default
15024  Writes out a file containing the contents of the heap, after running a
15025  simple cleaning sweep of memory contents.
15026  The filename defaults to 
15027 \family typewriter
15028 'slate.image'
15029 \family default
15030  or to the name of the most recent filename parameter value given.
15031  Note that execution context state is not disturbed, so saves may occur
15032  in any context as a snapshot of system-wide state, including debuggers,
15033  inspectors, and other live running processes.
15034 \end_layout
15036 \begin_layout Description
15038 \family typewriter
15039 \begin_inset LatexCommand index
15040 name "handleShutdown (message)"
15042 \end_inset
15044 handleShutdown
15045 \family default
15046  Performs each action (a block) in the 
15047 \family typewriter
15048 Image
15049 \family default
15050 's 
15051 \family typewriter
15053 \begin_inset LatexCommand index
15054 name "shutdownActions (object)"
15056 \end_inset
15058 shutdownActions
15059 \family default
15060  attribute, a 
15061 \family typewriter
15062 Dictionary
15063 \family default
15064  mapping keys to those corresponding actions.
15065  The keys are not meaningful except for identification by the library which
15066  installs it, so generally 
15067 \family typewriter
15068 Symbol
15069 \family default
15070 s are used or objects which can be identified and distinguished very easily.
15072 \family typewriter
15073 handleShutdown
15074 \family default
15075  is actually called by the 
15076 \family typewriter
15077 quit
15078 \family default
15079  method.
15080  The purpose of shutdown actions is to clean up any state that may affect
15081  the surrounding environment if not handled properly.
15082 \end_layout
15084 \begin_layout Description
15086 \family typewriter
15087 \begin_inset LatexCommand index
15088 name "handleStartup (message)"
15090 \end_inset
15092 handleStartup
15093 \family default
15094  Performs each action (a block) in the 
15095 \family typewriter
15096 Image
15097 \family default
15098 's 
15099 \family typewriter
15101 \begin_inset LatexCommand index
15102 name "startupActions (object)"
15104 \end_inset
15106 startupActions
15107 \family default
15108  attribute, a 
15109 \family typewriter
15110 Dictionary
15111 \family default
15112  mapping keys to those corresponding actions.
15113  The keys are not meaningful except for identification by the library which
15114  installs it, so generally 
15115 \family typewriter
15116 Symbol
15117 \family default
15118 s are used or objects which can be identified and distinguished very easily.
15120 \family typewriter
15121 handleStartup
15122 \family default
15123  is actually called by the 
15124 \family typewriter
15125 save
15126 \family default
15127  method when the image is re-started, because the execution context is preserved
15128 , and the VM sends a signal to indicate a fresh startup.
15129  The purpose of startup actions is to clean up any state that may be left
15130  over from a previous session with that Slate environment, and also to re-initia
15131 lize state which must persist to avoid inconsistent execution of various
15132  services.
15134 \family typewriter
15135 ExternalResource
15136 \family default
15137 s (
15138 \begin_inset LatexCommand vref
15139 reference "sub:External-Resources"
15141 \end_inset
15143 ) whose connections must be persistent are primary users of these hooks.
15144 \end_layout
15146 \begin_layout Description
15148 \family typewriter
15149 \begin_inset LatexCommand index
15150 name "handleSave (message)"
15152 \end_inset
15154 handleSave
15155 \family default
15156  Performs each action (a block) in the 
15157 \family typewriter
15158 Image
15159 \family default
15160 's 
15161 \family typewriter
15163 \begin_inset LatexCommand index
15164 name "saveActions (object)"
15166 \end_inset
15168 saveActions
15169 \family default
15170  attribute, a 
15171 \family typewriter
15172 Dictionary
15173 \family default
15174  mapping keys to those corresponding actions.
15175  The keys are not meaningful except for identification by the library which
15176  installs it, so generally 
15177 \family typewriter
15178 Symbol
15179 \family default
15180 s are used or objects which can be identified and distinguished very easily.
15182 \family typewriter
15183 handleSave
15184 \family default
15185  is actually called by the 
15186 \family typewriter
15187 quit
15188 \family default
15189  method.
15190  The purpose of save actions is to clean up any state that should not be
15191  saved at all; for example, passwords stored for secure access to external
15192  resources should be purged.
15193  In general, startup actions should be used for any other save-related activitie
15195 \end_layout
15197 \begin_layout Subsubsection
15198 Heap Image Segments
15199 \end_layout
15201 \begin_layout Standard
15202 We are developing methods for extracting 
15203 \begin_inset Quotes eld
15204 \end_inset
15206 slices
15207 \begin_inset Quotes erd
15208 \end_inset
15210  of images and saving them on disk along with explicit linking information
15211  so that groups of arbitrary objects may be transported reliably.
15212 \end_layout
15214 \begin_layout Section
15215 Style Guide
15216 \end_layout
15218 \begin_layout Standard
15219 \begin_inset LatexCommand index
15220 name "style guide"
15222 \end_inset
15224 Slate provides an unusual opportunity to organize programs and environments
15225  in unique ways, primarily through the unique object-centered combination
15226  of prototypes and multiple-argument dispatch.
15227  This section provides a guide to the generally recommended style of developing
15228  in this environment, to promote a better understanding of the system and
15229  its usage.
15230 \end_layout
15232 \begin_layout Subsection
15233 Environment organization
15234 \end_layout
15236 \begin_layout Subsubsection
15237 Namespaces
15238 \end_layout
15240 \begin_layout Standard
15241 \begin_inset LatexCommand index
15242 name "namespaces"
15244 \end_inset
15246 New namespaces should be used for separate categories of concepts.
15247  Occasionally, these are the kind that should automatically included in
15248  their enclosing namespace (which can be further inherited up to the lobby).
15249  This is done simply by placing the new namespace object in a delegate slot.
15250 \end_layout
15252 \begin_layout Subsubsection
15253 Exemplars or Value Objects
15254 \end_layout
15256 \begin_layout Standard
15257 These represent objects such as specific colors with well-known names, or
15258  cloneable objects with useful default values.
15259  Generally these should have capitalized names if they are cloneable, and
15260  can be capitalized or lowercase if not.
15261  For cases with a large group of such value objects, like colors, there
15262  usually should involve a separate namespace to avoid cluttering up the
15263  surrounding one.
15264  This also helps with naming the use of a value if the intuitive interpretation
15265  of its name is dependent on context.
15266 \end_layout
15268 \begin_layout Subsection
15269 Naming Methods
15270 \end_layout
15272 \begin_layout Standard
15273 One of the primary benefits and peculiarities of the Smalltalk
15274 \begin_inset LatexCommand index
15275 name "Smalltalk"
15277 \end_inset
15279  family's style of method syntax is that it provides an opportunity to name
15280  one's protocols using something resembling a phrase.
15281  Usually, it is recommended to re-use protocols whenever describing similar
15282  behaviors, as an aid to the user's memory in matching functionality to
15283  a name to call; in some exceptional situations, different protocols are
15284  helpful when there is more than one desired algorithm or behavior to provide
15285  for a kind of object.
15286  Here are some general practices which have been brought forward from years
15287  of Smalltalk practice.
15288 \end_layout
15290 \begin_layout Subsubsection
15291 Attributes
15292 \end_layout
15294 \begin_layout Standard
15295 Attributes are perhaps the simplest to name of all, in that they are generally
15296  nouns or noun phrases of some sort, whether used as direct slots or methods
15297  which calculate a property dynamically.
15298 \end_layout
15300 \begin_layout Subsubsection
15301 Queries
15302 \end_layout
15304 \begin_layout Standard
15305 Methods which test for some fact or property about a single object are generally
15306  given a 
15307 \begin_inset Quotes eld
15308 \end_inset
15310 whether
15311 \begin_inset Quotes erd
15312 \end_inset
15314 -style phrase.
15315  For example, 
15316 \family typewriter
15317 myCar\InsetSpace ~
15318 isRed
15319 \family default
15320  answers whether one's car is red.
15321  Slate offers an additional idiom over this particular style, in that 
15322 \family typewriter
15323 myCar\InsetSpace ~
15324 color\InsetSpace ~
15325 is:\InsetSpace ~
15327 \family default
15328  is also possible, since 
15329 \family typewriter
15331 \family default
15332  looks at both the subject and the object of the query.
15333  The only remaining obstacle is whether the conceived subject can stand
15334  on its own as a named concept; if there are multiple perspectives in normal
15335  use, the language can support a certain amount of ambiguity using subjective
15336  overrides, but there are limits to this.
15337 \end_layout
15339 \begin_layout Subsubsection
15340 Creating
15341 \end_layout
15343 \begin_layout Standard
15344 While the method 
15345 \family typewriter
15346 clone
15347 \family default
15348  is the 
15349 \emph on
15350 core
15351 \emph default
15352  of building new objects in Slate, rather than instantiating a class, there
15353  is still the need to provide and use an idiom for delivering optional attribute
15354 s and varying semantics of creation to one's new objects.
15355  Generally, these methods should start with 
15356 \family typewriter
15358 \family default
15359 - as a prefix to help the reader and code user to know that the original
15360  object will not be modified, and that the result is a new, separate individual.
15361  These methods are usually methods with keywords, with each of the keywords
15362  describing each option.
15363  If the keyword literally names an attribute, the optional-keyword facility
15364  is ideal, but if providing a grammatical phrase using prepositions, it
15365  is preferable to create a full keyword method.
15366 \end_layout
15368 \begin_layout Subsubsection
15369 Performing Actions
15370 \end_layout
15372 \begin_layout Standard
15373 The most interesting protocols are akin to commands, where one addresses
15374  the objects in question with a phrase that suggests performing some action.
15375  This should usually have one key verb for each major component of the action
15376  (there is usually just one action per method, but 
15377 \family typewriter
15378 select:thenCollect:
15379 \family default
15380 , for example, performs two), and prepositions or conjunctions to relate
15381  the verbs and nouns.
15382 \end_layout
15384 \begin_layout Standard
15385 There is a particular idiom of languages without multiple dispatch to add
15386  the noun (or type) name of an argument to the name of a function involving
15387  it.
15388  Slate makes this unnecessary and an obstacle to polymorphism, since the
15389  type of an argument can be specified in a dispatch as needed.
15390  Of course, nouns still sometimes have a useful place in a method name,
15391  when the noun is not a formal type, but an informal role or usage name.
15392 \end_layout
15394 \begin_layout Subsubsection
15395 Binary Operators
15396 \end_layout
15398 \begin_layout Standard
15399 These are perhaps the most controversial of any programming language's protocols.
15400  In the Smalltalk family of syntax, there are no precedence orderings between
15401  operators of different names, so the issues with those do not arise.
15402  However, it is very tempting for the library author to re-use mathematical
15403  symbols for her own domain, to allow her users to have a convenient abbreviatio
15404 n for common operations.
15405  While this benefits the writer of code which uses her library, there are
15406  domains and situations that punish the reader of the code that results.
15407 \end_layout
15409 \begin_layout Standard
15410 For example, mathematical addition and multiplication symbols, 
15411 \begin_inset Quotes eld
15412 \end_inset
15415 \family typewriter
15417 \family default
15419 \begin_inset Quotes erd
15420 \end_inset
15422  and 
15423 \begin_inset Quotes eld
15424 \end_inset
15427 \family typewriter
15429 \family default
15431 \begin_inset Quotes erd
15432 \end_inset
15434 , are generally associative and commutative.
15435  That is, repeated calls to these should be able to re-order their arguments
15436  arbitrarily and achieve the same result.
15437  For example, 
15438 \family typewriter
15440 \begin_inset Formula $3+4+5=4+3+5=5+4+3$
15441 \end_inset
15444 \family default
15446  However, string concatenation (as an example) is not commutative; we cannot
15447  re-order the arguments and expect the same result, i.e\SpecialChar \@.
15449 \begin_inset Formula "gold"+"fish"="goldfish"
15451 \end_inset
15453 , whereas 
15454 \begin_inset Formula "fish"+"gold"="fishgold"
15456 \end_inset
15458 \SpecialChar \@.
15459  Because concatenation is associative, however, we can re-use the punctuation
15460  style of the semi-colon 
15461 \begin_inset Quotes eld
15462 \end_inset
15465 \family typewriter
15467 \family default
15469 \begin_inset Quotes erd
15470 \end_inset
15472  and achieve intuitive results.
15473  This general style of reasoning should be applied wherever this type of
15474  operator name re-use could arise.
15475 \end_layout
15477 \begin_layout Subsection
15478 Instance-specific Dispatch
15479 \end_layout
15481 \begin_layout Standard
15482 \begin_inset LatexCommand index
15483 name "instance-specific dispatch"
15485 \end_inset
15488 \begin_inset LatexCommand index
15489 name "dispatch, instance-specific"
15491 \end_inset
15493 Often there are situations whether the user will want to specialize a method
15494  in some argument position for a specific object.
15495  There are various reasons to do this, and various factors to consider when
15496  deciding to do so.
15497 \end_layout
15499 \begin_layout Subsubsection
15500 Motivations
15501 \end_layout
15503 \begin_layout Standard
15504 Two common patterns where the developer wants to specialize to a single
15505  object usually emerge after extended usage.
15506  First, there are domain objects which naturally have special non-sharable
15507  behavior.
15508  For example, 
15509 \family typewriter
15510 True
15511 \family default
15512  is clearly a particular object that helps define the semantics of the whole
15513  system, by representing mechanical truth abstractly.
15514  In other situations, the same pattern occurs where one has a 
15515 \emph on
15516 universal
15517 \emph default
15518  concept, or locally an 
15519 \emph on
15520 absolute
15521 \emph default
15522  concept within a domain.
15523 \end_layout
15525 \begin_layout Standard
15526 Second, there are situations whether the user is demonstratively modifying
15527  the behavior of some 
15528 \emph on
15529 thing
15530 \emph default
15531  in order to achieve some 
15532 \emph on
15533 prototype
15534 \emph default
15535  that behaves in some situation as they desire.
15536  Depending on whether the user decides to share this behavior or not, the
15537  instance-specific behavior may or may not migrate to some shared 
15538 \family typewriter
15539 Traits
15540 \family default
15541  object.
15542  In either case, this is an encouraged use of objects and methods within
15543  Slate.
15544 \end_layout
15546 \begin_layout Subsubsection
15547 Limitations
15548 \end_layout
15550 \begin_layout Standard
15551 There are factors which weigh 
15552 \emph on
15553 against
15554 \emph default
15555  the use of dispatch on objects with non-shared behaviors.
15556  Generally, these just amount to a few simple reasons.
15557  First, the behavior will not be shared, which is obvious, but sometimes
15558  not clear to the author.
15559  Second, the author may mistake an object for its value or attributes, such
15560  as 
15561 \family typewriter
15562 String
15563 \family default
15564 s, which are not unique per their value, and so get unexpected results if
15565  they dispatch on a 
15566 \family typewriter
15567 String
15568 \family default
15569  instance.
15570  The same is true for all literals of that nature, with the exception of
15572 \family typewriter
15573 Symbol
15574 \family default
15576 \end_layout
15578 \begin_layout Standard
15579 The general rule for defining a 
15580 \family typewriter
15581 method
15582 \family default
15583  on an instance which is a lightweight 
15584 \begin_inset Quotes eld
15585 \end_inset
15587 value
15588 \begin_inset Quotes erd
15589 \end_inset
15591  object, is that the object must be reliably re-identifiable, as 
15592 \family typewriter
15593 Symbol
15594 \family default
15595 s are for the language, or through naming paths from the 
15596 \family typewriter
15597 lobby
15598 \family default
15599  or some other object that the user is given access to, such as a method
15600  argument.
15601  Otherwise, the user must be careful to hang on to the identity of the given
15602  object, which offsets any polymorphism gains and exposes implementation
15603  details unnecessarily.
15604 \end_layout
15606 \begin_layout Subsection
15607 Organization of Source
15608 \end_layout
15610 \begin_layout Standard
15611 The nature (and current limitations) of defining objects, relations, and
15612  the methods that operate over them require a certain ordering at this point
15613  which is worth mentioning.
15614  The central point of constraints is the definition of dispatching methods:
15615  these methods must have their dispatch targets available at the time they
15616  are evaluated.
15617  Since there is no late-binding yet of dispatch expressions, generally the
15618  basic construction of one's traits and prototype definitions must all occur
15619  before defining methods which dispatch to them.
15620  The definition needs merely to introduce the actual object that will be
15621  used later; other features of the objects, such as the slots and methods
15622  defined upon it, are late-bound and will not hinder a method-definition
15623  expression.
15624 \end_layout
15626 \begin_layout Standard
15627 In general, however, it is recommended to define methods in a 
15628 \emph on
15629 bottom-up
15630 \emph default
15631  fashion: that more basic utilities should be introduced before the methods
15632  that use them.
15633  This allows the user (and the author) of the code to read the program sequentia
15634 lly as a document and have some understanding of a program's components
15635  when only the name of the component is seen.
15636  Of course, this is not always possible, but it helps often enough.
15637 \end_layout
15639 \begin_layout Subsection
15640 Type-Annotating Expressions
15641 \end_layout
15643 \begin_layout Subsection
15644 Writing Test Cases
15645 \end_layout
15647 \begin_layout Standard
15648 Slate includes a port of Smalltalk's SUnit unit-testing framework (implemented
15649  in 
15650 \family typewriter
15651 src/lib/test.slate
15652 \family default
15653 ), as well as a collection of unit tests (in 
15654 \family typewriter
15655 tests/*.slate
15656 \family default
15658  Three namespaces are provided in which users may place their 
15659 \family typewriter
15660 TestCase
15661 \family default
15663 \end_layout
15665 \begin_layout Description
15666 testing\InsetSpace ~
15667 UnitTests should contain unit-test cases;
15668 \end_layout
15670 \begin_layout Description
15671 testing\InsetSpace ~
15672 RegressionTests is for test cases covering bug fixes, for detecting
15673  regressions; and
15674 \end_layout
15676 \begin_layout Description
15677 testing\InsetSpace ~
15678 BenchmarkTests is to contain test cases for measuring the speed of
15679  the system.
15680 \end_layout
15682 \begin_layout Standard
15683 There is a method 
15684 \family typewriter
15685 testing runAllTests
15686 \family default
15687  which runs all 
15688 \family typewriter
15689 TestCase
15690 \family default
15691 s found in a recursive search of the UnitTests and RegressionsTests namespaces.
15692 \end_layout
15694 \begin_layout Standard
15695 To write your own test cases, add a prototype derived from TestCase to the
15696  namespace you've chosen, within the appropriate container - either UnitTests
15697  or RegressionTests.
15698  For example, suppose you are writing test cases covering Ranges; you might
15699  write
15700 \end_layout
15702 \begin_layout LyX-Code
15703 UnitTests addPrototype: #Range derivedFrom: {TestCase}.
15704 \end_layout
15706 \begin_layout Standard
15707 Once your prototype has been constructed, add tests to it.
15708  Test methods are unary methods with selectors beginning with 
15709 \family typewriter
15710 test
15711 \family default
15713  For instance,
15714 \end_layout
15716 \begin_layout LyX-Code
15717 tc@(UnitTests Range traits) testInclusion1
15718 \end_layout
15720 \begin_layout LyX-Code
15721 "Verify that all elements of an Range are found in that Range."
15722 \end_layout
15724 \begin_layout LyX-Code
15725 [| range |
15726 \end_layout
15728 \begin_layout LyX-Code
15729   range: (25 to: 50 by: 1).
15730 \end_layout
15732 \begin_layout LyX-Code
15733   tc assert: (range allSatisfy: [| :item | range includes: item]).
15734 \end_layout
15736 \begin_layout LyX-Code
15738 \end_layout
15740 \begin_layout Standard
15741 The important assertion methods are
15742 \end_layout
15744 \begin_layout LyX-Code
15745 assert: Boolean
15746 \end_layout
15748 \begin_layout LyX-Code
15749 deny: Boolean
15750 \end_layout
15752 \begin_layout LyX-Code
15753 should: Method
15754 \end_layout
15756 \begin_layout LyX-Code
15757 should: Method raise: Condition
15758 \end_layout
15760 \begin_layout LyX-Code
15761 shouldnt: Method
15762 \end_layout
15764 \begin_layout LyX-Code
15765 shouldnt: Method raise: Condition
15766 \end_layout
15768 \begin_layout Standard
15769 and variants with an additional 
15770 \family typewriter
15771 description: String
15772 \family default
15773  argument.
15774 \end_layout
15776 \begin_layout Standard
15777 Once all your test methods are defined, a 
15778 \family typewriter
15779 suite
15780 \family default
15781  method should be defined that constructs a 
15782 \family typewriter
15783 TestSuite
15784 \family default
15785  for exercising the 
15786 \family typewriter
15787 TestCase
15788 \family default
15790 \end_layout
15792 \begin_layout LyX-Code
15793 t@(UnitTests Range traits) suite
15794 \end_layout
15796 \begin_layout LyX-Code
15797 [t suiteForSelectors: {
15798 \end_layout
15800 \begin_layout LyX-Code
15801   #testInclusion1.
15802 \end_layout
15804 \begin_layout LyX-Code
15805   
15806 \begin_inset Quotes eld
15807 \end_inset
15810  etc.
15811  ...
15812 \begin_inset Quotes erd
15813 \end_inset
15816 \end_layout
15818 \begin_layout LyX-Code
15820 \end_layout
15822 \begin_layout Standard
15823 See also the method 
15824 \family typewriter
15825 TestCase suiteForSelectors:
15826 \family default
15828  The 
15829 \family typewriter
15830 suite
15831 \family default
15832  method is called by 
15833 \family typewriter
15834 runSuite
15835 \family default
15836 , which in turn is called by 
15837 \family typewriter
15838 runAllTests
15839 \family default
15841 \end_layout
15843 \begin_layout Standard
15844 At this point, invoking 
15845 \family typewriter
15846 testing runAllTests
15847 \family default
15848  will exercise your new code.
15849 \end_layout
15851 \begin_layout Standard
15853 \newpage
15855 \end_layout
15857 \begin_layout Bibliography
15858 \begin_inset LatexCommand bibitem
15859 label "Chambers 97"
15860 key "Cecil"
15862 \end_inset
15865 \emph on
15866 The Cecil Language: Specification & Rationale
15867 \emph default
15869  Craig Chambers.
15870  Cecil/Vortex Project.
15871  1997.
15872 \newline
15874 \begin_inset LatexCommand htmlurl
15875 name "Available Online"
15876 target "http://www.cs.washington.edu/research/projects/cecil/www/pubs/cecil-spec.html"
15878 \end_inset
15881 \end_layout
15883 \begin_layout Bibliography
15884 \begin_inset LatexCommand bibitem
15885 label "Salzman 04"
15886 key "PMD"
15888 \end_inset
15891 \emph on
15892 Multiple Dispatch with Prototypes
15893 \emph default
15895  Lee Salzman, 2004.
15896 \newline
15898 \begin_inset LatexCommand htmlurl
15899 name "Available Online"
15900 target "http://tunes.org/\\~{}eihrul/pmd.pdf"
15902 \end_inset
15905 \end_layout
15907 \begin_layout Bibliography
15908 \begin_inset LatexCommand bibitem
15909 label "Ungar et al 95"
15910 key "SelfPR"
15912 \end_inset
15915 \emph on
15916 The Self Programmer's Reference Manual
15917 \emph default
15919  Ole Agesen, Lars Bak, Craig Chambers, Bay-Wei Chang, Urs Holzle, John Maloney,
15920  Randall B.
15921  Smith, David Ungar, and Mario Wolczko.
15922  Sun Microsystems and Stanford University, 4.0 edition, 1995.
15924 \newline
15926 \begin_inset LatexCommand htmlurl
15927 name "Available Online"
15928 target "http://research.sun.com/self/language.html"
15930 \end_inset
15933 \end_layout
15935 \begin_layout Bibliography
15936 \begin_inset LatexCommand bibitem
15937 label "Graham 94"
15938 key "OnLisp"
15940 \end_inset
15943 \emph on
15944 On Lisp: Advance Techniques for Common Lisp
15945 \emph default
15947  Paul Graham.
15948  Prentice-Hall, Inc., 1994.
15949 \newline
15951 \begin_inset LatexCommand htmlurl
15952 name "Available Online"
15953 target "http://paulgraham.com/onlisp.html"
15955 \end_inset
15958 \end_layout
15960 \begin_layout Bibliography
15961 \begin_inset LatexCommand bibitem
15962 label "The Refactory"
15963 key "RB"
15965 \end_inset
15967 The Smalltalk Refactoring Browser.
15969 \begin_inset LatexCommand htmlurl
15970 name "Online Overview"
15971 target "http://www.refactory.com/RefactoringBrowser/Rewrite.html"
15973 \end_inset
15976 \end_layout
15978 \begin_layout Bibliography
15979 \begin_inset LatexCommand bibitem
15980 label "Smith 96"
15981 key "Subjective"
15983 \end_inset
15986 \emph on
15987 The Subjective Prototype
15988 \emph default
15990  Randy Smith.
15991  Sun Microsystems Laboratories.
15992  1996.
15993 \newline
15995 \begin_inset LatexCommand htmlurl
15996 name "Available Online"
15997 target "http://www-staff.mcs.uts.edu.au/~cotar/proto/randy.txt"
15999 \end_inset
16002 \end_layout
16004 \begin_layout Standard
16006 \newpage
16008 \begin_inset LatexCommand printindex
16010 \end_inset
16013 \end_layout
16015 \end_body
16016 \end_document