Changes on the language reference page

[matifreyre]

A list of changes I'd do in the language reference page. So far, this is complete up to "Advanced Features" (not included). I'll probably add some more later on.

1. At Wollok Programs
   • A Wollok program is an executable piece of code that consists of a set of statements (actually expressions) that will be executed one after the other. This can be thought as a "main" entry point to a program in other languages. This program just prints "Hello World!" to the console. Further sections will explain all parts of the "console.println(...)" expression. For now, you can think of it as if it was an out-of-the-box function available to programs. Or as another instruction.
2. At References: Variables and Values
   • ... A Value is a reference that points to an object and cannot be redirected (changed) to point to another object. It's kind of a "constant". ...
3. At Basic objects
   • Here we will introduce the basic objects that come out-of-the-box with Wollok
4. At Numbers
   • Numbers are immutable objects. They understand several messages that can return other numbers. These messages include mathematical operations to add, substract, etc. ...
   • In addition wollok also supports postfix operators, as well as the plus-equals operations (among other variants). These are all just shortcuts for other expressions (shown here as comments to the right of their respective equivalents)...
5. At Booleans
   • There are two boolean objects which are available as literals: "true", and "false". Again, these are immutable objects, but they understand some operations that are evaluated to new boolean values, for example the "and" and "or" operations:
   • Furthermore, all equality and comparative operations are evaluated to boolean objects (see further sections)
6. At Equality Expressions
   • == tells us whether the two objects are equal
   • != tells us whether the two objects are NOT equal
7. At User Objects
   • Besides the predefined objects that we have seen, being an OOP language means that programmers should be able to create their own objects.
8. Change title Named Objects for **Named Objects (a.k.a. "Well-Known Objects" or "WKO")
9. At Object Literals
   • Another option is to use object literals...
10. At Methods
    • Within the object's braces we can define methods. For example, we will represent a Bird
    • ... As you can see here, methods are defined with the method keyword. They can receive parameters, and return a value. Parameters type are not explicit. In this case, "meters" is the name of the parameter.
    • Also, in case the method returns a value, you MUST explicitly write a return statement. The only possible exception is the "simple return method" explained in the next section.
11. At Instance Variables
    • Our bird doesn't do much so far. We will add "state" to it, in the form of instance variables.
    • Instead, if you want to access the bird's energy, the object must "publish" that information via a new method.
12. At Messages
    • OOP means objects, but most important, it means messages! So, in Wollok (almost) everything you do is sending messages to objects.
    • We saw that those objects could have methods within them that will get executed if someone sends them messages.
    • You CANNOT write any of these variants:
13. At Polymorphism - Part I (just objects)
    • Polymorphism, the most important concept in OOP, is the ability that allows an object to be interchangeable with another, without affecting a third that uses them.
    • ... This means that if two objects understand the same messages, then nothing else is needed, they can be used polymorphically by a third that sends those messages.
14. At Closures
    • For a detailed explanation see wikipedia. Here we'll just say that a closure is an object that represents a "piece of code" that can be manipulated. Specifically, it can be executed at any time. As many times as you want. But they can also be assigned to references, be passed as parameters, as well as be returned.
    • ... Here is one that receives a parameter
    • ... There's a special fact about closures: they have access to their own parameters, but also to any other reference that was available at the place where it was defined.
    • ... If we change this reference, then executing the closure will have another effect (as shown in the second call).
15. At Closures and Collections
    • Change: "As many other languages wollok provides rich collection messages to operate with them. Instead of writting code that indexes or iterates elements everytime, it already has methods for common tasks. All of which usually receive closures as parameters."
    • Change for: "As many other languages, Wollok provides rich collection messages to operate with them. Instead of writting code that indexes or iterates elements everytime, a series of methods for common tasks is delivered out-of-the-box. Many of those predefined messages receive closures as parameters."
16. At Inheritance
    • ... Instance variables are visible from the subclass. Think of them like if they were "protected" in java.
    • Methods in Wollok are always "public".
    • Subclasses can add new methods and instance variables, and override existing methods (check on section "Overriding and super").
17. At Overriding and super
    • Subclasses might override already defined methods in any superclass. For this you will need to explicitly use the "override" keyword before the method definition.
    • Notice that you don't need to specify the method name. In Wollok, you can only invoke the overrided method using super.
    • You cannot use super to call any other method in the superclass.
    • Also notice that super can only be used within an overriding method. (<--remove "Then")
18. At Polymorphism - Part II
    • Wollok combines objects and classes in a single language, and therefore in programs. Polymorphism with classes work in the same way as with objects. Two objects of different classes are polymorphic if they understand the same messages sent from a third object.
    • ... There's no need to have a common base class for objects to be polymorphic.
19. At Modularization
    • Wollok provides a set of rules and language constructions in order to promote modularization.
20. At "Packages"
    • A package is logical unit that groups together several classes and/or WKOs.
    • The package has a name (here "birds", "trainers", etc). Every class defined within it will inherit the package name as a prefix.
    • While coding within this package, you can refer classes with their shortname (here SwimmingBird). This is valid as long as they are also defined within the same package.
    • To refer to a class from outside the package you MUST use the FQN.

[matifreyre]

I left the constructors section out of this review because of the discussion at #559.

[npasserini]

Mati, I tried to implement your changes but I get into some kind of a mess. Would you like to edit the page yourself? I already gave you the required permissions.

On Tue, Jan 19, 2016 at 6:09 PM, Nicolas Passerini npasserini@gmail.com wrote:

On Mon, Jan 11, 2016 at 4:15 PM, Matías Freyre notifications@github.com wrote:

• A Wollok program is an executable piece of code that consists of a set of statements (actually expressions) that will be executed one after the other This can be thought as a "main" entry point to a program in other languages This program just prints "Hello World!" to the console Further sections will explain all parts of the "consoleprintln()" expression For now, you can think of it as if it was an out-of-the-box function available to programs Or as another instruction 1 At References: Variables and Values

I think that not every statement is an expression, am I wrong?

[matifreyre]

Ok! El ene. 19, 2016 18:28, "Nico Passerini" notifications@github.com escribió:

Mati, I tried to implement your changes but I get into some kind of a mess. Would you like to edit the page yourself? I already gave you the required permissions.

On Tue, Jan 19, 2016 at 6:09 PM, Nicolas Passerini npasserini@gmail.com wrote:

On Mon, Jan 11, 2016 at 4:15 PM, Matías Freyre <notifications@github.com

wrote:

• A Wollok program is an executable piece of code that consists of a set of statements (actually expressions) that will be executed one after the other This can be thought as a "main" entry point to a program in other languages This program just prints "Hello World!" to the console Further sections will explain all parts of the "consoleprintln()" expression For now, you can think of it as if it was an out-of-the-box function available to programs Or as another instruction 1 At References: Variables and Values

I think that not every statement is an expression, am I wrong?

— Reply to this email directly or view it on GitHub https://github.com/uqbar-project/wollok/issues/584#issuecomment-172992495 .

[npasserini]

My comments to the proposals:

On Mon, Jan 11, 2016 at 4:15 PM, Matías Freyre notifications@github.com wrote:

A list of changes I'd do in the language reference page https://githubcom/uqbar-project/wollok/wiki/LanguageReference So far, this is complete up to "Advanced Features" (not included) I'll probably add some more later on

1 At Wollok Program (<-- remove "s")

I would keep the 's' (see other titles, like "Wollok files"

• * A Value is a reference that points to an object and* cannot be redirected (changed) to point to another object It's kind of a "constant"

I would loose the: It's kind of a "constant", as it is not very clear. Maybe we could replace it for something like: (It is not exactly a constant as the referenced object can change itself. The reference is constant but the referenced object might not be.)

• Numbers are immutable objects They understand several messages that can return other numbers**

What do you think about "Can return references to other numbers"

• At Closures

I don't like the word Closure. For example, here is named "code block" / "anonymous function": https://en.wikipedia.org/wiki/Smalltalk#Code_blocks

Against my opinion (but still better than closure): BlockClosure: https://www.gnu.org/software/smalltalk/manual-base/html_node/BlockClosure.html

To my interpretation the term closure could also be applied to anonymous objects. So I would prefer code block or even block closure.

• Instance variables are visible from the subclass Think of them like if they were "protected" in java

Is this true?

• Notice that you don't need to specify the method name In Wollok, you can only invoke the overrided method using super

It should be "overridden"

• Wollok combines objects and classes in a single language, and therefore in programs Polymorphism with classes work in the same way as with objects Two objects of different classes are polymorphic if they understand the same messages sent from a third object

I think we should avoid talking about classes here, because not every object in wollok has a class. I would reduce this to only say "to objects can be use polymorphically if they understand a common set of messages".

-

• There's no need to have a common base class for objects to be polymorphic**\ 1 At Modularization
• Wollok provides a set of rules and language constructions in order to promote modularization 1 At "Packages"
• A package is logical unit that groups together several classes and/or WKOs
• The package has a name (here "birds", "trainers", etc)\ Every** class defined within it will inherit the package name as a prefix
• While coding within this package, you can refer classes with their shortname (here SwimmingBird) This is valid as long as they are also defined within the same package
• To refer to a class from outside the package you MUST use the FQN

— Reply to this email directly or view it on GitHub https://github.com/uqbar-project/wollok/issues/584.

[matifreyre]

1 At Wollok Program (<-- remove "s")

I would keep the 's' (see other titles, like "Wollok files"

Sure... I edited and removed that afterwards from my original comment.

• * A Value is a reference that points to an object and* cannot be redirected (changed) to point to another object It's kind of a "constant"

I would loose the: It's kind of a "constant", as it is not very clear. Maybe we could replace it for something like: (It is not exactly a constant as the referenced object can change itself. The reference is constant but the referenced object might not be.)

I changed it for: It's kind of a "constant reference", always pointing to the same object, but it's not a "constant" as meant in some other languages due to the fact that the referenced object might change its own state.

I don't like the word Closure.

I think we should open a new issue for this discussion, but so far I will say I like block closure.

• Wollok combines objects and classes in a single language, and therefore in programs Polymorphism with classes work in the same way as with objects Two objects of different classes are polymorphic if they understand the same messages sent from a third object.

I think we should avoid talking about classes here, because not every object in wollok has a class. I would reduce this to only say "to objects can be use polymorphically if they understand a common set of messages".

I wouldn't completely get rid of the term "class". I'd like to explicitly mention that it doesn't matter if the object is an instance of a class or a WKO or an anonymous one, they can potentially be used polymorphically.

[npasserini]

I changed it for: It's kind of a "constant reference", always pointing to the same object, but it's not a "constant" as meant in some other languages due to the fact that the referenced object might change its own state.

I don't like the word Closure.

I think we should open a new issue for this discussion, but so far I will say I like block closure.

Agreed on both.

• Wollok combines objects and classes in a single language, and therefore in programs Polymorphism with classes work in the same way as with objects Two objects of different classes are polymorphic if they understand the same messages sent from a third object.

I think we should avoid talking about classes here, because not every object in wollok has a class. I would reduce this to only say "to objects can be use polymorphically if they understand a common set of messages".

I wouldn't completely get rid of the term "class". I'd like to explicitly mention that it doesn't matter if the object is an instance of a class or a WKO or an anonymous one, they can potentially be used polymorphically.

Ok, and how would it be then?

[matifreyre]

Updates are already on the page. I wrote it like this:

Wollok combines objects and classes in a single language, and therefore in programs. Polymorphism with classes work in the same way as with objects. It doesn't matter if the object is an instance of a class or a WKO or an anonymous one, they can potentially be used polymorphically.

Two objects can be used polymorphically if they understand a common set of messages.

On Wed, Jan 20, 2016 at 3:07 PM, Nico Passerini notifications@github.com wrote:

I changed it for: It's kind of a "constant reference", always pointing to the same object, but it's not a "constant" as meant in some other languages due to the fact that the referenced object might change its own state.

I don't like the word Closure.

I think we should open a new issue for this discussion, but so far I will say I like block closure.

Agreed on both.

• Wollok combines objects and classes in a single language, and therefore in programs Polymorphism with classes work in the same way as with objects Two objects of different classes are polymorphic if they understand the same messages sent from a third object.

I think we should avoid talking about classes here, because not every object in wollok has a class. I would reduce this to only say "to objects can be use polymorphically if they understand a common set of messages".

I wouldn't completely get rid of the term "class". I'd like to explicitly mention that it doesn't matter if the object is an instance of a class or a WKO or an anonymous one, they can potentially be used polymorphically.

Ok, and how would it be then?

— Reply to this email directly or view it on GitHub https://github.com/uqbar-project/wollok/issues/584#issuecomment-173308954 .

[npasserini]

Great!

On Wed, Jan 20, 2016 at 3:16 PM, Matías Freyre notifications@github.com wrote:

Updates are already on the page. I wrote it like this:

Wollok combines objects and classes in a single language, and therefore in programs. Polymorphism with classes work in the same way as with objects. It doesn't matter if the object is an instance of a class or a WKO or an anonymous one, they can potentially be used polymorphically.

Two objects can be used polymorphically if they understand a common set of messages.

On Wed, Jan 20, 2016 at 3:07 PM, Nico Passerini notifications@github.com wrote:

I changed it for: It's kind of a "constant reference", always pointing to the same object, but it's not a "constant" as meant in some other languages due to the fact that the referenced object might change its own state.

I don't like the word Closure.

I think we should open a new issue for this discussion, but so far I will say I like block closure.

Agreed on both.

• Wollok combines objects and classes in a single language, and therefore in programs Polymorphism with classes work in the same way as with objects Two objects of different classes are polymorphic if they understand the same messages sent from a third object.

I think we should avoid talking about classes here, because not every object in wollok has a class. I would reduce this to only say "to objects can be use polymorphically if they understand a common set of messages".

I wouldn't completely get rid of the term "class". I'd like to explicitly mention that it doesn't matter if the object is an instance of a class or a WKO or an anonymous one, they can potentially be used polymorphically.

Ok, and how would it be then?

— Reply to this email directly or view it on GitHub < https://github.com/uqbar-project/wollok/issues/584#issuecomment-173308954> .

— Reply to this email directly or view it on GitHub https://github.com/uqbar-project/wollok/issues/584#issuecomment-173312754 .

[matifreyre]

All the proposed changes have been added a month ago. I'm closing the issue. Open a new one if needed.