Merge pull request #2031 from sanjiva/master

Clean up iterators and moved exceptions to its own section

docs/specification/connectors.md

@@ -47,6 +47,8 @@ Connectors are instantiated using the `create` keyword as follows:
 [ConnectorPackageName:]ConnectorName ConnectorVarName = create [ConnectorPackageName:]ConnectorName (ValueList);
 ```
 
+## Invoking Actions
+
 Actions are invoked as follows:
 ```
 [ConnectorPackageName:]ConnectorName.ActionName (ConnectorVarName, ValueList);

docs/specification/docsandcomments.md

@@ -0,0 +1,17 @@
+# Documentation and Comments
+
+Many programming languages treat documentation as an after thought with some languages using the approach of introducing structure to comments to insert structured documentation into the language.
+
+Ballerina has a structured approach for both documentation and random comments which are not related to documenting per se but simply commenting about the logic of the program.
+
+## Documenting with annotations
+
+> NOTE: To be written to explain docerina architecture.
+
+## Commenting Code
+
+Any statement that starts with the characters `//` is a comment.
+
+
+Comments are quite different in Ballerina in comparison to other languages. Comments are only allowed as a statement - i.e., only inside a resource, action, or function.
+Ballerina has designed structured mechanisms via annotations to document all Ballerina outer level constructs (services, resources, etc.), and comments only play the role of providing a comment about the logic of a resource, action, or function.

docs/specification/exceptions.md

@@ -0,0 +1,46 @@
+# Exception Handling
+
+Ballerina supports throwing and catching exceptions using a simple exception handling model. This is supported by the `exception` type and the constructs `try-catch` and `throw`.
+
+## Behavior
+
+An exception may be thrown by a native Ballerina function or any Ballerina construct using the `throw` statement. When thrown, the runtime searches for the nearest enclosing block containing a `try-catch` statement. If none is found in the current stack frame then execution of the function (or resource or action or type mapper) stops and the frame is popped and the search continues until a `try-catch` statement is found. If none is found at the outermost level of the worker, then that worker thread dies in an abnormal state.
+
+If the exception goes through the default worker of a `main` function without being caught then the entire program will stop executing. If the exception goes through a `resource` without being caught then that particular invocation of the service & resource will fail and the server connector will choose the appropriate behavior in that situation.
+
+# The `exception` Type
+
+Exceptions are instances of a built-in, opaque reference type named `exception`.
+
+A collection of library functions can be used to set and get properties of exceptions, including stack traces. Note that unlike other languages, Ballerina does not allow developers to define subtypes of the exception type and custom exceptions must be thrown by using custom category strings. As such exception category strings starting with "Ballerina:" are reserved for system use only.
+
+Variables of type `exception` are defined and initialized to a new exception as follows:
+```
+exception VariableName = {};
+```
+Library functions for accessing information from this type are in the package `ballerina.lang.exceptions`. These functions can be used to set the category of the exception, the descriptive messsage and any additional properties.
+
+# The `try-catch` Statement
+
+The syntax of a `try-catch` is as follows:
+```
+try {
+    Statement;+
+} catch (exception e) {
+    Statement;+
+}
+```
+If any exception occurs while execution the first block of statements then the exception will be handled by the block after the `catch`.
+
+> NOTE: Ballerina currently does not have a `finally` concept but we will likely add it.
+
+# The `throw` Statement
+
+The syntax of a `throw` statement is as follows:
+```
+throw ExceptionVariableName;
+```
+
+The `throw` statement is used to throw an exception from the current location. An execution stack trace pointing to the current location will be automatically inserted into the exception before the runtime starts the exception handling process.
+
+> NOTE: There will be more capabilities brought to exceptions in future.

docs/specification/statements.md

@@ -7,18 +7,16 @@ A Statement can be one of the following:
 - while statement
 - break statement
 - fork/join statement
-- try/catch statement
-- throw statement
+- try/catch statement (see [Exception Handling](exceptions.md))
+- throw statement (see [Exception Handling](exceptions.md))
 - return statement
 - reply statement
-- worker initiation statement
-- worker join statement
-- action invocation statement
-- comment statement
+- worker initiation/invocation/join statements (see [Workers](workers.md))
+- action invocation statement (see [Connectors & Actions](connectors.md))
 
-#### Assignment Statement
+## Assignment Statement
 
-Assignment statements are encoded as follows:
+Assignment statements are written as follows:
 ```
 VariableAccessor = Expression;
 ```
@@ -28,7 +26,7 @@ A `VariableAccessor` is one of:
 - VariableAccessor'['MapIndex']'
 - VariableAccessor.FieldName
 
-#### If Statement
+## If Statement
 
 An `if` statement provides a way to perform conditional execution.
 ```
@@ -42,7 +40,9 @@ if (BooleanExpression) {
 }]
 ```
 
-#### Iterate Statement
+## Iterate Statement
+
+> NOTE: Iterators are still not fully conceived and as such this is not implemented in v0.8.0.
 
 An `iterate` statement provides a way to iterate through an iterator.
 ```
@@ -51,7 +51,7 @@ iterate (VariableType VariableName : Iterator) {
 }
 ```
 
-#### While Statement
+## While Statement
 
 A `while` statement provides a way to execute a series of statements as long as a Boolean expression is met.
 ```
@@ -60,15 +60,15 @@ while (BooleanExpression) {
 }
 ```
 
-#### Break Statement
+## Break Statement
 
 A `break` statement allows one to terminate the immediately enclosing loop.
 This is only allowed within the `iterate` or `while` constructs.
 ```
 break;
 ```
 
-#### Fork/Join Statement
+## Fork/Join Statement
 
 A `fork` statement allows one to replicate a message to any number of parallel
 workers and have them independently operate on the copies of the message. The `join`
@@ -78,7 +78,6 @@ will wait for the parallel workers to complete.
 ```
 fork (MessageName) {
   worker WorkerName (message VariableName) {
-    VariableDeclaration;*
     Statement;+
     [reply MessageName;]
   }+       
@@ -88,67 +87,35 @@ fork (MessageName) {
   Statement;*  
 }]
 ```
-Note that if the `join` clause is missing, it is equivalent to waiting for all workers to complete and ignorning the results.
+Note that if the `join` clause is missing, it is equivalent to waiting for all workers to complete and ignoring the results.
 
 The `JoinCondition` is one of the following:
 - `any IntegerValue [(WorkerNameList)]`: wait for any k (i.e., the IntegerValue) of the given workers or any of the workers
 - `all [(WorkerNameList)]`: wait for all given workers or all of the workers
 
 where `WorkerNameList` is a list of comma-separated names of workers.
 
+> NOTE: In v0.8.0 the join condition "any k" where k != 1 is not yet implemented.
+
 When the `JoinCondition` has been satisfied, the corresponding slots of the message array will be filled with the returned messages from the workers in the workers' lexical order. If the condition asks for up to some number of results to be available to satisfy the condition, it may be the case that more than that number are available by the time the statements within the join condition are executed. If a particular worker has completed but not sent a response message, or not yet completed, the corresponding message slot will be null.
 
 The `timeout` clause allows one to specify a maximum time (in milliseconds) within which the join condition must be satisfied.
 
+> NOTE: The Ballerina Composer does not yet support fork/join as of v0.8.0.
 
-#### Exception Handling
-
-Ballerina supports exception handling as a way to address unexpected scenarios in a Ballerina program. This is provided by the built-in `exception` type, the `try/catch` statement, and the `throw` statement. Furthermore, any function can indicate that it may throw an exception by saying `throws exception`.
-
-The built-in `exception` type has three properties: its category (a string), its message (a string), and its properties (a map). These properties are manipulated using the functions defined in the `ballerina.lang.exception` package.
-
-Note that there is only one built-in exception type, and all exceptions use this type with different values for the category property. All standard exception "types" are defined by category string constants in the `ballerina.lang.exception` package.
-
-The syntax of a `try/catch` is as follows:
-```
-try {
-    Statement;+
-} catch (exception e) {
-    Statement;+
-}
-```
-
-The syntax of a `throw` statement is as follows:
-```
-throw Expression;
-```
-
-#### Return Statement
+## Return Statement
 
 The syntax of a `return` statement is as follows:
 ```
 return Expression*;
 ```
+Return is used to return immediately from a function, resource or action.
+
+## Reply Statement
 
-#### Reply Statement
+Reply is used to signal the message that a parallel worker will return to its initiator. If present, it must be the last statement of the worker's statment block. See [Workers](workers.md) for more information.
 
 The syntax of a `reply` statement is as follows:
 ```
 reply Message?;
 ```
-
-#### Comment Statement
-
-Comments are quite different in Ballerina in comparison to other languages. Comments are only allowed as a statement - i.e., only inside a resource, action, or function.
-Ballerina has designed structured mechanisms via annotations to document all Ballerina outer level constructs (services, resources, etc.), and comments only play the role of providing a comment about the logic of a resource, action, or function.
-
-Any statement that starts with the characters `//` is a comment.
-
-### Expressions
-Similar to languages such as Java, Go, etc, Ballerina supports the following expressions:
-* mathamtical expressions `(x + y, x/y, etc.)`
-* function calls `(foo(a,b))`
-* action calls `(tweet(twitterActor, "hello"))`
-* complex expressions `(foo(a,bar(c,d)))`
-
-Please see the grammar file for more details.

docs/specification/typesandvar.md

@@ -1,6 +1,6 @@
 # Types, Variables & Constants
 
-The Ballerina type system has value types and reference types. Ballerina comes with a set of built-in reference types and array, struct or iterator type constructors to create new reference types.
+The Ballerina type system has value types and reference types. Ballerina comes with a set of built-in value types, a set of built-in reference types, array & struct type constructors to create new reference types and an iterator type constructor to create new iterators.
 
 The type system is illustrated in the following:
 
@@ -20,6 +20,8 @@ TypeName VariableName [ = Expression];
 
 Variables can be initialized using the standard literal value syntax for that type of variable or using expressions consisting of literal values and any other variables that are in-scope and already initialized. See the 'Literal Values' subsection below for the syntax for literal values for value types, built-in reference types and user defined reference types.
 
+Note that variable declarations are considered to be statements of the language and can be done any place where a statement is allowed. See [Statements](statements.md).
+
 ## Allocating & Deallocating Variables
 
 All value typed variables are allocated on the stack, while all reference typed variables are allocated on the heap. Value typed variables are deallocated when they go out of scope and all reference typed variables are garbage collected when they are no longer in use.
@@ -40,6 +42,8 @@ Ballerina includes the following value types:
 
 The types `int` and `float` both support 64-bit IEEE754 arithmetic. The `boolean` type has only two values: `true` and `false`. The `string` type operates similar to value types in that assignment and comparison involve the full value and not the pointer.
 
+> NOTE: Earlier versions of the language (while it was under development) we had additional types such as long and double. Those have been removed but there are some remnants in the implementation. The only valid value types are those listed above and the implementation will be cleaned up shortly.
+
 Value types can be initialized at declaration by assigning a value of that type. If they are not initialized they have the following default values: int: 0, float: 0.0, string: "" (empty string, not null) and boolean: false.
 
 > NOTE: We are considering making the default value of a string to be null.
@@ -85,6 +89,8 @@ VariableName = [ Expression, Expression, ... ];
 ```
 If there are no expressions given (i.e., the right hand side is `[]`), then the variable will be initialized to an array of length 0. Else it will be array of the same length as the number of expressions with each value being stored in the corresponding index of the array.
 
+> NOTE: We are considering adding support for arrays of arrays (of arrays ...).
+
 ## Built-In Reference Types
 
 Ballerina comes with a pre-defined set of reference types which are key to supporting the types of programs that Ballerina developers are expected to write. These are supported by a set of standard library functions found in the packages `ballerina.lang.*`. This section defines each of these types and defines their usage.
@@ -102,11 +108,9 @@ message VarName = {};
 
 ### Type: `exception`
 
-The `exception` type, like `message`, is an opaque type used to hold an exception. A collection of library functions can use to set and get properties of exceptions, including stack traces. Note that unlike other languages, Ballerina does not allow developers to define subtypes of the exception type and custom exceptions must be thrown by using customer type strings. As such exception type strings starting with "Ballerina:" are reserved for system use only.
-
-Library functions for accessing information from this type are in the package `ballerina.lang.exceptions`.
+The `exception` type, like `message`, is an opaque type used to hold an exception.
 
-> NOTE: There will be more capabilities brought to exceptions in future.
+See [Exception Handling](exceptions.md) for more information on exception handling and the `exception` type.
 
 ### Type: `map`
 
@@ -199,7 +203,7 @@ TypeName~
 ```
 Iterator typed values are navigated through using an `iterate` statement.
 
-> NOTE: Iterators are still not fully consumated. Iterators are currently only available for the built-in types xml and json. In the future we will allow developers to define their own iterators for their types.
+> NOTE: Iterators are still under development and not fully implemented.
 
 ## Type Conversion and Mapping