Critiques of Slate Manual

[Brian T Rice]

Hi Jack.

Thanks for the feedback. My comments follow (in a little of a hurry, as I
have a plane flight to catch in the morning). I'm collecting these into
TODO and FIX's which will be applied when I get time in the next few days.

Incidentally, these are the best editorial comments of the 4 or 5 people
who have read it so far at my request for the comments.

-- 
Brian T. Rice
LOGOS Research and Development
mailto:water at tunes.org
http://tunes.org/~water/

On Fri, 25 Oct 2002, Jack Waugh wrote:

> Introduction -> Conventions: three "Finally" sentences.

Yes, that's redundant.

> 2.1.1 Block Closures, last paragraph.
> I suppose what this is getting at is that the closure
> inherits from the context in which the block appeared.
> The paragraph is not clear, I think.  The reader has no
> way to interpret what it means for the code to "remember"
> what objects it depends on.  The paragraph does not explain
> how this dependency comes about or may be defined or
> understood.  This paragraph says a block is "basically" an
> activation frame composed with an environment, but the
> manual does not give any of these terms a very concrete
> explanation.

Okay, I'll work on a more detailed explanation, maybe with a diagram.

> Although I mainly intend here to be writing about just the
> manual and whether it is clear, I will mention one criticism
> of the language.  I think that dropping the use of ; for
> a cascade syntax is a big mistake.  The fact that semantically
> the first argument is not special has nothing to do with
> whether the cascade is useful.  It's useful as syntactic
> sugaring to avoid having to repeat the first argument.  I
> would restore the cascade, and use some other selector
> where you have used the semicolon.  I don't know whether the
> comma is available for those uses.

I see your point. I'll discuss it with my partner. It may happen yet. What
would you think of ++ for concatenation in that case?

> It's interesting that you chose not to keep Self's treatment
> of capitalized keywords.

It makes the syntax a bit more ambiguous, especially as it is
case-sensitive.

> 2.2.4 Expression sequences
>
> I think it's worth making explicit that when Slate executes
> an expression sequence, it evaluates the expressions in
> order, and their side effects occur in that order.  The value
> of the sequence is that of the last expression (except in
> the array syntax).

That's a very good point. I'll add it.

> 2.2.5 Implicit-context sends
>
> I guess the "runtime context" of a block means the context
> in which the block occurs, not that in which someone sends
> it value, value:, or another evaluating message.
> A formula specifying the whole inheritance tree of every
> context of execution would help clarify, I think.

Okay.

> Methods
>
> In the examples that end "[block value]", wouldn't simply
> "block" do as well?

Good point, but it's a bit of a matter of safety for us initially, to
ensure that the method body is a real block. Also, currently the parser
isn't robust/late-bound enough to handle that. I may have to mention that
in the next revision.

> If an @ definition and a | | definition (slot) try to field
> the same selector, which takes precedence?

In some cases, it has to happen, such as when <undocumented>declaring the
type of an input slot, :input!itsType is required and it is an intensional
collision</undocumented>. However, the case of 'overriding' an input slot
with a local declaration is an undefined possibility of the language.
We'll discuss it and try to find something reasonable. Most likely we'll
have a condition thrown (from CL: a condition is a resumable exception,
with methods to handle various continuing options and parameters).
Shadowing the input variable doesn't seem like a good behavior. However,
<hack>the interpreter deals with multiple "_" input arguments that
way</hack>, although that's expedient as opposed to desired.

> Lookup Semantics
>
> Let's say I have invented a class Bumper and have defined
> the following method:
>     _@(Bumper traits) value: anObject [anObject + 1].
>
> Then suppose the system is told to evaluate:
>     Bumper traits value: 1
>
> This will signal an error, right?  The manual says that in
> dispatching on "value:", the system will look in the role
> dictionaries of Bumper traits and 1 and intersect them.
> Presumably 1 will not have a role after value:, so the inter-
> section will be empty.

Not quite, Bumper itself (the argument to the message-send) is where the
lookup begins. But that's besides the point. The fact that a method is
found on Bumper's traits and that 1 _does not have an overriding method_
is what causes / allows the method to be the one used.

You are right that the "intersection" wording is wrong. Lee pointed this
out, but we couldn't find a quick way to fix it. The PMD paper on the
Slate site explains the algorithm adequately. My quest to simplify the
explanation turned out to be incorrect. I'll definitely fix that.

> Anyway, I think examples would help in this section.

They would.

> 2.4 Literal Syntax
>
> The description of the difference between what characters
> would have to be escaped in a character literal and what
> ones would need to be escaped in a string literal suggests
> that the comment quote (double-quote) would have to be
> escaped in a character literal.  But in the table of escape
> codes for character literals, there is no mention of the
> double-quote.

The interpreter evaluates $" as $". :) I'll try to fix the specification
once I've determined what the interpreter's doing, and whether it's a bug.
(A quick experiment tells me that there could be a bug.)

> 2.3.3 Array syntax
>
> It looks as though the expressions in braces without pound
> can be arbitrary expressions rather than only literals.
> If so, I suggest the example should reflect that.

Good idea. They *somewhat* reflect it, but I'll try to make it more clear.

> 3 The Slate World
>
> The Lobby
>
> The manual leaves the reader wondering what it means by
> "the lobby is essentially a threading context".  Maybe an
> explanation of threading is in order.

It will be. I'm not sure when, since the interpreter has no chance of
multi-threading right now.

> 3.1.2 Naming and Paths
>
> This section should give an example of the name of an
> object that might be cloned.  I see many examples that
> mention "traits" after a name that looks to a Smalltalker
> like a class name, e. g., Integer traits.  I think I see
> that the traits object would usually be the target of
> method definitions for shared behavior.  But what services
> would an object named Integer or Set or something like
> that provide, other than access to the traits object?  I think
> this section should give examples of the uses of the
> objects accessed through the namespaces.  The examples
> should include creating an array of a given size, a
> clone of some simple object such as an employee record,
> and also the inheritance tree of immutable objects.

That's a good idea. I should note that the prototypes for 'value objects'
such as Integers are eventually going to be a place where variables
quantified over that type would be instantiated, probably by collaborating
with a Type object itself (documented later). But that's not ready to be
added; maybe it never will be.

> 3.2.1 Default Object Features
>
> Printing
>
> In Smalltalk it makes more sense to override printOn: than
> print.  Object>>print invokes printOn:, so usually print
> doesn't need to be overridden.  Is it the other way around
> in Slate?  Why?

It is the other way around, for the reason that the interpreter defined
print methods primitively, because we didn't have any primitive Streams
and we needed to see some verification in the REPL. Regrettable, and I'll
try to invert the relationship, but true for now.

> Hashing
>
> Where you say a = b iff a hash = b hash, I think you mean
> to say a = b only if a hash = b hash.

Oops. I got careless with the symbol.

> Language criticism about as::  I should think that by
> default, a as: b should return a rather than Nil.  a is
> closer to an object based on a which is as much like b
> as possible than Nil is.

Good point. We hadn't thought of that. I think our reasoning was that we
didn't want "a as: b" to return "a" unless they had the same type and it
was a value object. We also wanted ifNil: switching on failure. Maybe
we'll do it; at least we'll re-consider it.

> Language suggestion:  Have a way to derive from an object
> another object that exhibits the same behavior so far as
> programmer-defined methods are concerned as the orignial
> object, but that does not support metaprogramming such
> as creating new slots and adding roles.  Metaprogramming
> the original object would program the derived object, but
> a holder of a reference to only the derived object could
> not monkey with the object's behavior (except as permitted
> via its public methods).  I think this would be useful for
> security in transactions where one party does not trust
> the other.  Examples of untrusting objects are operating
> systems and bank accounts.

Proxies? We'll definitely get around to it, and this sounds like a good
use of a MOP (which we do intend to build).

> 3.4.1 Boolean Logic
>
> Comment on and: vs. /\ :  the need to make that distinction
> is one of the nasty traits of imperative languages.

Bleh, I had a discussion about this with my partner a few months ago.
You've convinced me to bring it up again at some point, because /\ doesn't
require extra grouping of arguments when nested as and: does.

> 3.4.3  Looping
>
> Hooray for proper tail recursion.  I have always wondered why
> Smalltalk didn't guarantee that (and I guess Self doesn't
> either).

Actually you have to uncomment some lines in the interpreter to enable it.
They are marked as such. We did this because our (albeit crude) current
debugging facilities "get lost" in iteration. :)

> For absolute clarity, instead of writing in the manual "from
> a to b", I would write "from a through b, inclusive".

Good suggestion.

> Language criticism:  Instead of upTo: and downTo:, I would
> use upThrough: and downThrough:.

Hm. I'll take a poll at OOPSLA as well to see what makes more sense.

> Collections
>
> Comment: I guess NoDuplicatesCollection is what a Smalltalker
> would name AbstractSet.  I'm not suggesting that either
> convention is better than the other.  In fact, I think I would
> name AbstractSet as Set and name Set with some term that
> suggests the implementation, e. g. HashedSet,
> or SetViaPaddedArray.  I do like the include: selector.  In
> fact any extensible collection class could implement it.

I would like Set to be the abstract case, but it would confuse
Smalltalkers. :P Also, ExtensibleCollection does define "c include: obj"
as "c add: obj ifPresent: []".

> The manual should make clear whether the internal comparisons
> occasioned by include: and perhaps other operations on
> collections are = or ==.  This applies to keys in at:put:,
> etc.

Yeah, that's an important detail.

> Somewhere in here (I can't find it now) I came across a
> mention of a selector for testing something (i. e., returning
> a Boolean) that didn't conform to the conventional English
> parts of speech that Smalltalkers use for tests.  Examples
> of selectors that do conform to that convention are isEmpty
> and includes:.  The latter is a good example of not needing
> the "is" beginning to still fall in the English part of
> speech that fits to testing semantics.  OK, I think I found
> the bad example: atEnd.  Should be isAtEnd.

We're intending that the bootstrapped system will infer the types of
methods as you compile them, so that methods returning Boolean will
annotate themselves that way, or as boolean-or-nil. How that will make
code more readable could then be a matter of highlighting in some
appropriate way. The long-term direction is towards independence of text
syntax, and that impacts the decision we made there. Also, we wanted "is"
to be restricted to "is:".

> Despite all my nitpicks, which I hope you find to be of
> some use, I find the manual overall to be a very good
> document.

Thanks. I'm not sure when I'll republish the .ps and .pdf, but I'll enter
the changes straight into CVS into via .lyx source file.

> Jack Waugh <waugh at acm.org>