Amber update

amber/bin/amberc

@@ -1,7 +1,7 @@
 #!/bin/bash
 #
 # This is a "compiler" for Amber code. Run without arguments for help.
-
+#
 # Get Amber root directory from the location of this script so that
 # we can find the st and js directories etc.
 

amber/css/documentation.css

@@ -30,6 +30,12 @@
     padding: 5px;
 }
 
+.documentation code {
+    background: #eee;
+    padding: 0 5px;
+}
+
+
 .documentation .menu {
     position: fixed;
     left: 0;

amber/js/Documentation.deploy.js

@@ -128,7 +128,7 @@ smalltalk.method({
 selector: 'ch6KernelObjects',
 fn: function (){
 var self=this;
-return (function($rec){smalltalk.send($rec, "_title_", [unescape("Kernel-Objects")]);return smalltalk.send($rec, "_yourself", []);})(smalltalk.send((smalltalk.PackageDocChapter || PackageDocChapter), "_on_", [smalltalk.send((smalltalk.Package || Package), "_named_", [unescape("Kernel-Objects")])]));
+return smalltalk.send((smalltalk.PackageDocChapter || PackageDocChapter), "_on_", [smalltalk.send((smalltalk.Package || Package), "_named_", [unescape("Kernel-Objects")])]);
 return self;}
 }),
 smalltalk.DocumentationBuilder);
@@ -158,6 +158,43 @@ return self;}
 }),
 smalltalk.DocumentationBuilder);
 
+smalltalk.addMethod(
+'_ch7KernelClasses',
+smalltalk.method({
+selector: 'ch7KernelClasses',
+fn: function (){
+var self=this;
+return smalltalk.send((smalltalk.PackageDocChapter || PackageDocChapter), "_on_", [smalltalk.send((smalltalk.Package || Package), "_named_", [unescape("Kernel-Classes")])]);
+return self;}
+}),
+smalltalk.DocumentationBuilder);
+
+smalltalk.addMethod(
+'_update',
+smalltalk.method({
+selector: 'update',
+fn: function (){
+var self=this;
+self['@chapters']=nil;
+self['@announcer']=nil;
+self['@widget']=nil;
+smalltalk.send(smalltalk.send((typeof window == 'undefined' ? nil : window), "_jQuery_", [".documentation"]), "_remove", []);
+smalltalk.send(self, "_build", []);
+return self;}
+}),
+smalltalk.DocumentationBuilder);
+
+smalltalk.addMethod(
+'_build',
+smalltalk.method({
+selector: 'build',
+fn: function (){
+var self=this;
+smalltalk.send(self, "_buildOnJQuery_", [smalltalk.send("body", "_asJQuery", [])]);
+return self;}
+}),
+smalltalk.DocumentationBuilder);
+
 
 smalltalk.DocumentationBuilder.klass.iVarNames = ['current'];
 smalltalk.addMethod(
@@ -166,7 +203,7 @@ smalltalk.method({
 selector: 'initialize',
 fn: function (){
 var self=this;
-smalltalk.send(smalltalk.send(self, "_current", []), "_buildOnJQuery_", [smalltalk.send((typeof window == 'undefined' ? nil : window), "_jQuery_", ["body"])]);
+smalltalk.send(smalltalk.send(self, "_current", []), "_build", []);
 return self;}
 }),
 smalltalk.DocumentationBuilder.klass);

amber/js/Documentation.js

@@ -184,11 +184,11 @@ selector: unescape('ch6KernelObjects'),
 category: 'chapters',
 fn: function (){
 var self=this;
-return (function($rec){smalltalk.send($rec, "_title_", [unescape("Kernel-Objects")]);return smalltalk.send($rec, "_yourself", []);})(smalltalk.send((smalltalk.PackageDocChapter || PackageDocChapter), "_on_", [smalltalk.send((smalltalk.Package || Package), "_named_", [unescape("Kernel-Objects")])]));
+return smalltalk.send((smalltalk.PackageDocChapter || PackageDocChapter), "_on_", [smalltalk.send((smalltalk.Package || Package), "_named_", [unescape("Kernel-Objects")])]);
 return self;},
 args: [],
-source: unescape('ch6KernelObjects%0A%09%5E%28PackageDocChapter%20on%3A%20%28Package%20named%3A%20%27Kernel-Objects%27%29%29%0A%09%09title%3A%20%27Kernel-Objects%27%3B%0A%09%09yourself'),
-messageSends: ["title:", "yourself", "on:", "named:"],
+source: unescape('ch6KernelObjects%0A%09%5EPackageDocChapter%20on%3A%20%28Package%20named%3A%20%27Kernel-Objects%27%29'),
+messageSends: ["on:", "named:"],
 referencedClasses: ["PackageDocChapter", "Package"]
 }),
 smalltalk.DocumentationBuilder);
@@ -228,6 +228,58 @@ referencedClasses: ["ChapterSelectionAnnouncement"]
 }),
 smalltalk.DocumentationBuilder);
 
+smalltalk.addMethod(
+unescape('_ch7KernelClasses'),
+smalltalk.method({
+selector: unescape('ch7KernelClasses'),
+category: 'chapters',
+fn: function (){
+var self=this;
+return smalltalk.send((smalltalk.PackageDocChapter || PackageDocChapter), "_on_", [smalltalk.send((smalltalk.Package || Package), "_named_", [unescape("Kernel-Classes")])]);
+return self;},
+args: [],
+source: unescape('ch7KernelClasses%0A%09%5EPackageDocChapter%20on%3A%20%28Package%20named%3A%20%27Kernel-Classes%27%29'),
+messageSends: ["on:", "named:"],
+referencedClasses: ["PackageDocChapter", "Package"]
+}),
+smalltalk.DocumentationBuilder);
+
+smalltalk.addMethod(
+unescape('_update'),
+smalltalk.method({
+selector: unescape('update'),
+category: 'updating',
+fn: function (){
+var self=this;
+self['@chapters']=nil;
+self['@announcer']=nil;
+self['@widget']=nil;
+smalltalk.send(smalltalk.send((typeof window == 'undefined' ? nil : window), "_jQuery_", [".documentation"]), "_remove", []);
+smalltalk.send(self, "_build", []);
+return self;},
+args: [],
+source: unescape('update%0A%09chapters%20%3A%3D%20nil.%0A%09announcer%20%3A%3D%20nil.%0A%09widget%20%3A%3D%20nil.%0A%09%28window%20jQuery%3A%20%27.documentation%27%29%20remove.%0A%09self%20build'),
+messageSends: ["remove", "jQuery:", "build"],
+referencedClasses: []
+}),
+smalltalk.DocumentationBuilder);
+
+smalltalk.addMethod(
+unescape('_build'),
+smalltalk.method({
+selector: unescape('build'),
+category: 'building',
+fn: function (){
+var self=this;
+smalltalk.send(self, "_buildOnJQuery_", [smalltalk.send("body", "_asJQuery", [])]);
+return self;},
+args: [],
+source: unescape('build%0A%09self%20buildOnJQuery%3A%20%28%27body%27%20asJQuery%29'),
+messageSends: ["buildOnJQuery:", "asJQuery"],
+referencedClasses: []
+}),
+smalltalk.DocumentationBuilder);
+
 
 smalltalk.DocumentationBuilder.klass.iVarNames = ['current'];
 smalltalk.addMethod(
@@ -237,11 +289,11 @@ selector: unescape('initialize'),
 category: 'initialization',
 fn: function (){
 var self=this;
-smalltalk.send(smalltalk.send(self, "_current", []), "_buildOnJQuery_", [smalltalk.send((typeof window == 'undefined' ? nil : window), "_jQuery_", ["body"])]);
+smalltalk.send(smalltalk.send(self, "_current", []), "_build", []);
 return self;},
 args: [],
-source: unescape('initialize%0A%09self%20current%20buildOnJQuery%3A%20%28window%20jQuery%3A%20%27body%27%29'),
-messageSends: ["buildOnJQuery:", "current", "jQuery:"],
+source: unescape('initialize%0A%09self%20current%20build'),
+messageSends: ["build", "current"],
 referencedClasses: []
 }),
 smalltalk.DocumentationBuilder.klass);

amber/st/Documentation.st

@@ -34,6 +34,10 @@ buildOn: aCanvas
 
 buildOnJQuery: aJQuery
 	self buildOn: (HTMLCanvas onJQuery: aJQuery)
+!
+
+build
+	self buildOnJQuery: ('body' asJQuery)
 ! !
 
 !DocumentationBuilder methodsFor: 'chapters'!
@@ -232,9 +236,11 @@ ch5Index
 !
 
 ch6KernelObjects
-	^(PackageDocChapter on: (Package named: 'Kernel-Objects'))
-		title: 'Kernel-Objects';
-		yourself
+	^PackageDocChapter on: (Package named: 'Kernel-Objects')
+!
+
+ch7KernelClasses
+	^PackageDocChapter on: (Package named: 'Kernel-Classes')
 ! !
 
 !DocumentationBuilder methodsFor: 'routing'!
@@ -251,6 +257,16 @@ checkHash
 		yourself)
 ! !
 
+!DocumentationBuilder methodsFor: 'updating'!
+
+update
+	chapters := nil.
+	announcer := nil.
+	widget := nil.
+	(window jQuery: '.documentation') remove.
+	self build
+! !
+
 DocumentationBuilder class instanceVariableNames: 'current'!
 
 !DocumentationBuilder class methodsFor: 'accessing'!
@@ -262,7 +278,7 @@ current
 !DocumentationBuilder class methodsFor: 'initialization'!
 
 initialize
-	self current buildOnJQuery: (window jQuery: 'body')
+	self current build
 ! !
 
 Widget subclass: #DocChapter

amber/st/Kernel-Objects.st

@@ -2,6 +2,42 @@ Smalltalk current createPackage: 'Kernel-Objects' properties: #{}!
 nil subclass: #Object
 	instanceVariableNames: ''
 	category: 'Kernel-Objects'!
+!Object commentStamp!
+*Object is the root of the Smalltalk class system*. All classes in the system are subclasses of Object.
+
+Object provides default behavior common to all normal objects, such as: 
+
+- access
+- copying
+- comparison
+- error handling
+- message sending
+- reflection
+
+Also utility messages that all objects should respond to are defined here.
+
+Object has no instance variable.
+
+##Access
+
+Instance variables can be accessed with `#instVarAt:` and `#instVarAt:put:`. `Object >> instanceVariableNames` answers a collection of all instance variable names.
+Accessing JavaScript properties of an object is done through `#basicAt:`, `#basicAt:put:` and `basicDelete:`.
+
+##Copying
+
+Copying an object is handled by `#copy` and `#deepCopy`. The first one performs a shallow copy of the receiver, while the second one performs a deep copy.
+The hook method `#postCopy` can be overriden in subclasses to copy fields as necessary to complete the full copy. It will be sent by the copy of the receiver.
+
+##Comparison
+
+Objects understand equality  `#=` and identity `#==` comparison.
+
+##Error handling
+
+- `#halt` is the typical message to use for inserting breakpoints during debugging.
+- `#error:` throws a generic error exception
+- `#doesNotUnderstand:` handles the fact that there was an attempt to send the given message to the receiver but the receiver does not understand this message.
+  Overriding this message can be useful to implement proxies for example.!
 
 !Object methodsFor: 'accessing'!
 
@@ -824,6 +860,11 @@ pi
 Object subclass: #Boolean
 	instanceVariableNames: ''
 	category: 'Kernel-Objects'!
+!Boolean commentStamp!
+Boolean wraps the JavaScript `Boolean()` constructor. The `true` and `false` objects are the JavaScript boolean objects.
+
+Boolean defines the protocol for logic testing operations and conditional control structures for the logical values.
+Boolean instances are weither `true` or `false`.!
 
 !Boolean methodsFor: 'comparing'!
 
@@ -916,7 +957,10 @@ Object subclass: #Date
 	instanceVariableNames: ''
 	category: 'Kernel-Objects'!
 !Date commentStamp!
-The Date class is used to work with dates and times.!
+The Date class is used to work with dates and times. Therefore `Date today` and `Date now` are both valid in
+Amber and answer the same date object.
+
+Date wraps the `Date()` JavaScript constructor, and Smalltalk date objects are JavaScript date objects.!
 
 !Date methodsFor: 'accessing'!
 
@@ -1170,6 +1214,18 @@ new
 Object subclass: #Random
 	instanceVariableNames: ''
 	category: 'Kernel-Objects'!
+!Random commentStamp!
+Random is just a wrapper around javascript Math.random() and is trivially used like this:
+
+	Random new next
+
+This will return a float x where x < 1 and x > 0. If you want a random integer between 1 and 10 you can use #atRandom
+
+	10 atRandom
+
+...which is also implemented in SequencableCollection so you can easy pick an element at random:
+
+	#('a' 'b' 'c') atRandom!
 
 !Random methodsFor: 'accessing'!
 
@@ -1244,6 +1300,28 @@ x: aNumber y: anotherNumber
 Object subclass: #JSObjectProxy
 	instanceVariableNames: 'jsObject'
 	category: 'Kernel-Objects'!
+!JSObjectProxy commentStamp!
+JSObjectProxy handles sending messages to JavaScript object, therefore accessing JavaScript objects from Amber is transparent.
+JSOjbectProxy makes intensive use of `#doesNotUnderstand:`.
+
+## Examples
+
+JSObjectProxy objects are instanciated by Amber when a Smalltalk message is sent to a JavaScript object.
+
+    window alert: 'hello world'.
+    window inspect.
+    (window jQuery: 'body') append: 'hello world'
+
+Smalltalk messages sends are converted to JavaScript function calls or object property access _(in this order)_. If n one of them match, a `MessageNotUnderstood` error will be thrown. 
+
+## Message conversion rules
+
+- `someUser name` becomes  `someUser.name`
+- `someUser name: 'John'` becomes `someUser name = "John"`
+- `console log: 'hello world'` becomes `console.log('hello world')`
+- `(window jQuery: 'foo') css: 'background' color: 'red'` becomes `window.jQuery('foo').css('background', 'red')`
+
+__Note:__ For keyword-based messages, only the first keyword is kept: `window foo: 1 bar: 2` is equivalent to `window foo: 1 baz: 2`.!
 
 !JSObjectProxy methodsFor: 'accessing'!
 

amber/st/Makefile

@@ -56,7 +56,6 @@ Compiler.js: Compiler.st Kernel-Objects.js Kernel-Classes.js Kernel-Methods.js K
 # to compile the rest of st files presuming that they only depend on Kernel, like
 # for example Canvas.js and Benchfib.js.
 %.js: %.st Compiler.js
-	echo $(OBJECTS)
 	$(AMBERC) $(FLAGS) $<
 
 # But for some libraries there are more dependencies to care for. Then
@@ -77,11 +76,11 @@ TrySmalltalk.js: TrySmalltalk.st IDE.js
 
 # Some Examples use SUnit and also IDE
 Examples.js: Examples.st SUnit.js IDE.js
-	$(AMBERC) $(FLAGS) -l SUnit,Canvas,IDE $<;
+	$(AMBERC) $(FLAGS) -l SUnit,Canvas,IDE $<
 
 # Tests typically also use SUnit
 Kernel-Tests.js: Kernel-Tests.st SUnit.js
-	$(AMBERC) $(FLAGS) -l SUnit $<;
+	$(AMBERC) $(FLAGS) -l SUnit $<
 
 # Documentation
 Documentation.js: Documentation.st Canvas.js
@@ -93,7 +92,7 @@ install: all
 
 # And cleaning is trivial also
 clean:
-	rm -f *.js; 
+	rm -f *.js
 
 # These three are phony
 .PHONY: all install clean