diff --git a/classes.html b/classes.html index 6e9b3a2d..e38c1522 100644 --- a/classes.html +++ b/classes.html @@ -91,11 +91,11 @@ add a parenthesized parameter list after the method's name:

-

Arity #

+

Signature #

Unlike most other dynamically-typed languages, in Wren you can have multiple -methods in a class with the same name, as long as they take a different number -of parameters. In technical terms, you can overload by arity. So this class -is fine:

+methods in a class with the same name, as long as they have a different +parameter signature. In technical terms, you can overload by arity. So this +class is fine:

class Unicorn {
   prance {
     IO.print("The unicorn prances in a fancy manner!")
@@ -126,6 +126,43 @@ chosen.

 sets of arguments. In other languages, you'd define a single method for the
 operation and have to check for "undefined" or missing arguments. Wren just
 treats them as different methods that you can implement separately.

+
Signature is a bit more than just arity. It also lets you distinguish between a
+method that takes an empty argument list (()) and no argument list at all:

+
class Confusing {
+  method { "no argument list" }
+  method() { "empty argument list" }
+}
+
+var confusing = new Confusing
+confusing.method // "no argument list".
+confusing.method() // "empty argument list".
+

+
+
+
Like the example says, having two methods that differ just by an empty set of
+parentheses is pretty confusing. That's not what this is for. It's mainly so
+you can define methods that don't take any arguments but look "method-like".

+
Methods that don't need arguments and don't modify the underlying object tend
+to omit the parentheses. These are "getters" and usually access a property of
+an object, or produce a new object from it:

+
"string".count
+(1..3).min
+0.123.sin
+

+
+
+
Other methods do change the object, and it's helpful to draw attention to that:

+
list.clear()
+

+
+
+
Since the parentheses are part of the method's signature, the callsite and
+definition have to agree. These don't work:

+
"string".count()
+list.clear
+

+
+
 
Operators #

 
Operators are just special syntax for a method call on the left hand operand
 (or only operand in the case of unary operators like ! and ~). In other
@@ -194,7 +231,7 @@ constructor by adding a parenthesized parameter list after new:
-

Like other methods, you can overload constructors by arity.

+

Like other methods, you can overload constructors by arity.

Fields #

All state stored in instances is stored in fields. Each field has a named that starts with an underscore.

@@ -251,7 +288,46 @@ to or even should define getters or setters for most of your object's fields.

A name that starts with two underscores is a static field. They work similar to fields except the data is stored on the class itself, and not the instance. They can be used in both instance and static methods.

-

TODO: Example.

+
class Foo {
+  // Set the static field.
+  static set(a) {
+    __a = a
+  }
+
+  setFromInstance(a) {
+    __a = a
+  }
+
+  // Can use __a in both static methods...
+  static bar { __a }
+
+  // ...and instance ones.
+  baz { __a }
+}
+
+ + +

Just like instance fields, static fields are initially null:

+
IO.print(Foo.bar) // null.
+
+ + +

They can be used from static methods:

+
Foo.set("foo")
+IO.print(Foo.bar) // foo.
+
+ + +

And also instance methods. When you do so, there is still only one static field +shared among all instances of the class:

+
var foo1 = new Foo
+var foo2 = new Foo
+
+foo1.setFromInstance("updated")
+IO.print(foo2.baz) // updated.
+
+ +

Inheritance #

A class can inherit from a "parent" or superclass. When you invoke a method on an object of some class, if it can't be found, it walks up the chain of diff --git a/core/fiber.html b/core/fiber.html index c4ffb310..efec7db2 100644 --- a/core/fiber.html +++ b/core/fiber.html @@ -53,40 +53,42 @@ fiber is run. Does not immediately start running the fiber.

-

Fiber.yield #

+

Fiber.current #

+

The currently executing fiber.

+

Fiber.yield() #

Pauses the current fiber and transfers control to the parent fiber. "Parent" here means the last fiber that was started using call and not run.

var fiber = new Fiber {
   IO.print("Before yield")
-  Fiber.yield
+  Fiber.yield()
   IO.print("After yield")
 }
 
-fiber.call              // "Before yield"
+fiber.call()            // "Before yield"
 IO.print("After call")  // "After call"
-fiber.call              // "After yield"
+fiber.call()            // "After yield"
-

When resumed, the parent fiber's call method returns null.

+

When resumed, the parent fiber's call() method returns null.

If a yielded fiber is resumed by calling call() or run() with an argument, -yield returns that value.

+yield() returns that value.

var fiber = new Fiber {
-  IO.print(Fiber.yield) // "value"
+  IO.print(Fiber.yield()) // "value"
 }
 
-fiber.call          // Run until the first yield.
+fiber.call()        // Run until the first yield.
 fiber.call("value") // Resume the fiber.
-

If it was resumed by calling call or run with no argument, returns null.

-

It is a runtime error to call this when there is no parent fiber to return to.

-
Fiber.yield // ERROR
-
-new Fiber {
-  Fiber.yield // ERROR
-}.run
+
If it was resumed by calling call() or run() with no argument, it returns
+null.

+
If there is no parent fiber to return to, this exits the interpreter. This can
+be useful to pause execution until the host application wants to resume it
+later.

+
Fiber.yield()
+IO.print("this does not get reached")
 

 
 
@@ -97,18 +99,18 @@ here means the last fiber that was started using call and not Fiber.yield("value")
 }
 
-IO.print(fiber.call) // "value"
+IO.print(fiber.call()) // "value"
-

call #

+

call() #

TODO

call(value) #

TODO

isDone #

Whether the fiber's main function has completed and the fiber can no longer be run. This returns false if the fiber is currently running or has yielded.

-

run #

+

run() #

TODO

run(value) #

TODO

diff --git a/core/fn.html b/core/fn.html index 21bfaf65..1a2f0322 100644 --- a/core/fn.html +++ b/core/fn.html @@ -46,17 +46,17 @@

A first class function—an object that wraps an executable chunk of code. Here is a friendly introduction.

new Fn(function) #

-

Creates a new function from... function. Of course, function is already be -a function, so this really just returns the argument. It exists mainly to let -you create a "bare" function when you don't want to immediately pass it as a -block argument to some other method.

+

Creates a new function from... function. Of course, function is already a +function, so this really just returns the argument. It exists mainly to let you +create a "bare" function when you don't want to immediately pass it as a block +argument to some other method.

var fn = new Fn {
   IO.print("The body")
 }
-

It is a runtime error if block is not a function.

+

It is a runtime error if function is not a function.

arity #

The number of arguments the function requires.

IO.print(new Fn {}.arity)             // 0.
diff --git a/core/list.html b/core/list.html
index e64f6b6b..3a3bc80c 100644
--- a/core/list.html
+++ b/core/list.html
@@ -47,7 +47,7 @@
 
An indexable contiguous collection of elements. More details here.

 
add(item) #

 
Appends item to the end of the list.

-
clear #

+
clear() #

 
Removes all items from the list.

 
count #

 
The number of items in the list.

@@ -67,7 +67,7 @@ are shifted up to fill in where the removed element was.

 
 
 
Returns the removed item.

-
IO.print(["a", "b", "c"].removeAt(1) // "b".
+
IO.print(["a", "b", "c"].removeAt(1)) // "b".
 

 
 
diff --git a/core/map.html b/core/map.html
index 1d56e1f0..cac5b98f 100644
--- a/core/map.html
+++ b/core/map.html
@@ -44,7 +44,7 @@
   

     
Map Class

     
An associative collection that maps keys to values. More details here.

-
clear #

+
clear() #

 
Removes all entries from the map.

 
containsKey(key) #

 
Returns true if the map contains key or false otherwise.

diff --git a/core/num.html b/core/num.html
index b507e0b9..2597d8d8 100644
--- a/core/num.html
+++ b/core/num.html
@@ -43,19 +43,28 @@
   
   

     
Num Class

-    
TODO

-
abs #

+    
abs #

 
The absolute value of the number.

 
-123.abs // 123
 

 
 
 
ceil #

-
TODO

+
Rounds the number up to the nearest integer.

+
1.5.ceil // 2
+(-3.2).ceil // -3
+

+
+
 
cos #

 
The cosine of the number.

 
floor #

-
TODO

+
Rounds the number down to the nearest integer.

+
1.5.floor    // 1
+(-3.2).floor // -4
+

+
+
 
isNan #

 
Whether the number is not a number. This is
 false for normal number values and infinities, and true for the result of
@@ -96,9 +105,29 @@ unsigned values. The result is then a 32-bit unsigned number where each bit is
 true only where the corresponding bits of both inputs were true.

 
It is a runtime error if other is not a number.

 
..(other) operator #

-
TODO

+
Creates a Range representing a consecutive range of numbers
+from the beginning number to the ending number.

+
var range = 1.2..3.4
+IO.print(range.min)         // 1.2
+IO.print(range.max)         // 3.4
+IO.print(range.isInclusive) // true
+

+
+
 
...(other) operator #

-
TODO

+
Creates a Range representing a consecutive range of numbers
+from the beginning number to the ending number not including the ending number.

+
var range = 1.2...3.4
+IO.print(range.min)         // 1.2
+IO.print(range.max)         // 3.4
+IO.print(range.isInclusive) // false
+

+
+
+
Num.fromString(value) #

+
Attempts to parse value as a decimal literal and return it as an instance of
+Num. If the number cannot be parsed null will be returned.

+
It is a runtime error if value is not a string.

   

 

 

diff --git a/core/sequence.html b/core/sequence.html
index a62362cf..9fbe1d75 100644
--- a/core/sequence.html
+++ b/core/sequence.html
@@ -48,13 +48,23 @@ core iterator protocol
 
all(predicate) #

 
Tests whether all the elements in the sequence pass the predicate.

 
Iterates over the sequence, passing each element to the function predicate.
-If it returns false, stops iterating and returns false. Otherwise, returns
-true.

+If its return value evaluates to false, stops iterating and returns false.
+Otherwise, returns true.

 
[1, 2, 3].all {|n| n > 2} // False.
 [1, 2, 3].all {|n| n < 4} // True.
 

 
 
+
any(predicate) #

+
Tests whether any element in the sequence passes the predicate.

+
Iterates over the sequence, passing each element to the function predicate.
+If its return value evaluates to true, stops iterating and returns true.
+Otherwise, returns false.

+
[1, 2, 3].any {|n| n < 1} // False.
+[1, 2, 3].any {|n| n > 2} // True.
+

+
+
 
join(sep) #

 
Returns a string representation of the list. The string representations of the
 elements in the list is concatenated with intervening occurrences of sep.

diff --git a/error-handling.html b/error-handling.html
index 525ce036..c70aa70f 100644
--- a/error-handling.html
+++ b/error-handling.html
@@ -150,7 +150,7 @@ error message as a string.

   123.badMethod
 }
 
-var error = fiber.try
+var error = fiber.try()
 IO.print("Caught error: ", error)
@@ -195,8 +195,9 @@ only way the program could prevent that failure is by validating the string before its parsed, but validating that a string is a number is pretty much the same thing as parsing it.

For cases like this where failure can occur and the program will want to -handle it, fibers and try are too coarse-grained to work with. Instead, these -operations will indicate failure by returning some sort of error indication.

+handle it, fibers and try() are too coarse-grained to work with. Instead, +these operations will indicate failure by returning some sort of error +indication.

For example, a method for parsing a number could return a number on success and null to indicate parsing failed. Since Wren is dynamically typed, it's easy and natural for a method to return different types of values.

diff --git a/expressions.html b/expressions.html index 771e611a..798fb16e 100644 --- a/expressions.html +++ b/expressions.html @@ -85,13 +85,24 @@ look like so:

You have a receiver expression followed by a ., then a name and an argument list in parentheses. Arguments are separated by commas. Methods that do not -take any arguments omit the ():

+take any arguments can omit the ():

text.length

These are special "getters" or "accessors" in other languages. In Wren, they're -just method calls.

+just method calls. You can also define methods that take an empty argument list:

+
list.clear()
+
+ + +

An empty argument list is not the same as omitting the parentheses +completely. Wren lets you overload methods by their call signature. This mainly +means arity—number of parameters—but +also distinguishes between "empty parentheses" and "no parentheses at all".

+

You can have a class that defines both foo and foo() as separate methods. +Think of it like the parentheses and commas between arguments are part of the +method's name.

If the last (or only) argument to a method call is a function, it may be passed as a block argument:

@@ -273,21 +284,122 @@ class (or one of its subclasses).

Precedence #

When you mix these all together, you need to worry about -precedence—which operators bind more tightly than others. Wren mostly +precedence—which operators bind more tightly than others—and +associativity—how a series of the same operator is ordered. Wren mostly follows C, except that it fixes the bitwise operator mistake. The full -precedence table, from lowest to highest, is:

-
=           // Assignment.
-&& || ?:    // Logic.
-is          // Type test.
-== !=       // Equality.
-< > <= >=   // Comparison.
-.. ...      // Range.
-| &         // Bitwise.
-+ -         // Terms.
-* / %       // Factors.
-- ~ !       // Unary.
-. []        // Call.
-
+precedence table, from highest to lowest, is:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PrecOperatorDescriptionAssoc
1() [] .Grouping, Subscript, Method callLeft
2- ! ~Negate, Not, ComplementRight
3* / %Multiply, Divide, ModuloLeft
4+ -Add, SubtractLeft
5.. ...Inclusive range, Exclusive rangeLeft
6<< >>Left shift, Right shiftLeft
7< <= > >=ComparisonLeft
8==EqualsLeft
8!=Not equalLeft
9&Bitwise andLeft
10^Bitwise xorLeft
11|Bitwise orLeft
12isType testLeft
13&&Logical andLeft
14||Logical orLeft
15?:ConditionalRight
16=AssignRight