Hi Nicolai,

On Mon, Sep 7, 2015 at 1:21 PM, Nicolai Hess <nicolaihess@web.de> wrote:


2015-09-07 20:10 GMT+02:00 Eliot Miranda <eliot.miranda@gmail.com>:


On Sun, Sep 6, 2015 at 12:56 PM, Nicolai Hess <nicolaihess@web.de> wrote:
Do we have a documentation about the format of
- class definitions
- methods
- class comments
for the changes file ?


Google "specification of smalltalk chunk format" and you will see:


and more.


Thank you eliot
(should have google that myself !)
��
��

I am asking because some entries are using two separator
"! !"
and some only one
"!"

Indeed.�� It's in the spec. ��! ! ends a run of methods in the same protocol. ��! ends a method or a doit, etc.�� Read the spec.

ah! grouping multiple methods for one protocol.

Forgive me, I don't mean to complain, but...�� It's rather sad now I look at it that the specification misses a very cool thing about the format.�� Glenn Krasner invented it and he's no dummy.�� What the specs miss out is that the syntax for a protocol is actually a general escape mechanism.�� For example in

!Object methodsFor: 'testing'!
isUnderstood
�� �� ^false! !

the fileIn parser evaluates

�� �� Object methodsFor: 'testing'

and then asks that object to scanFrom: the stream.�� And the above answers a ClassCategoryReader that reads chunks, compiling them and adding them to the relevant category, until it finds an empty chunk (hence ! ! is not special syntax, but actually a chunk followed by an empty chunk).

So one /could/, if one wanted, add another kind of reader, for example

!Preferences loadSavedPreferences!
beCool true!
beKnowledgeable true!
rememberOnersHistorytLestOneWishesToRepeatIt true! !

and have this not file in, but store preferences. I think that's neat, and it's very sad that the ANSI standard did;t define this but reduced the mechanism to support only protocols, and thence cause people to wonder why the syntax was so weird, when in fact it was very simple and wonderfully extensible.

Now I'm not blaming the standards process; the real problem here is that the scheme wasn't documented other than by its implementation and so the flexibility was never made apparent to the standardizers, and anyway they wanted an interchange format, which is not what Squeak and Pharo chunk readers provide; they provide an extensible format.�� The ANSI standard /could/ however have specified that the syntax is indeed extensible as described, but that conforming implementations are only expected to provide ClassCategoryReaders, and are expected to raise an error if given expressions they don't recognize, or some such.

Also, given this history you can see why a single ! following a method definition isn't seen anymore; we've put the stamp information in the ClassCategoryreader so it can only parse a single method.�� If we'd done something like this (and I'm not suggesting that's a good idea)

!Object methodsFor: 'testing'!
[stamp: 'mad 01/04/2015 12:00']
isUnderstood
�� �� ^#barely!

[stamp: 'mad 01/04/2015 12:01']
isMisunderstood
�� �� ^#almostCertainly! !

we'd still see the single !'s after methods.

Two key points for me are
- specify carefully and visibly
- extensible standards are better than fixed standards

And we have a problem with the "Recover lost changes" browser
(https://pharo.fogbugz.com/f/cases/16498/unrecoverable-changes)
and I am not sure if this is a bug on the code importer
or if it is a bug on how we write changes to the changes file.

_,,,^..^,,,_
best,��Eliot