[[ Bug 14993 ]] Updated LCB language reference.

runrevmark · runrevmark · commit a1b2ddb1ec67 · 2015-03-31T13:07:19.000+01:00
diff --git a/docs/specs/livecode_builder_language_reference.md b/docs/specs/livecode_builder_language_reference.md
@@ -60,11 +60,11 @@ By following this convention, there will not be any ambiguity between identifier
 
 # Typing
 
-Modular LiveCode is a typed language, although typing is completely optional in most places (the only exception being in foreign handler declarations). If a type annotation is not specified it is simply taken to be the most general type *optional any* (meaning any value, including undefined).
+Modular LiveCode is a typed language, although typing is completely optional in most places (the only exception being in foreign handler declarations). If a type annotation is not specified it is simply taken to be the most general type *optional any* (meaning any value, including nothing).
 
 The range of core types is relatively small, comprising the following:
 
- - **undefined**: the single value *undefined*
+ - **nothing**: the single value *nothing*
  - **Boolean**: one of *true* or *false*
  - **Integer**: any integral numeric value (size limitations apply)
  - **Real**: any numeric value (size and accuracy limitations apply)
@@ -75,7 +75,7 @@ The range of core types is relatively small, comprising the following:
  - **Array**: a mapping from strings to values
  - **any**: a value of any type
 
-Additionally, all types can be annotated with **optional**. An optional annotation means the value may be the original type or the undefined value.
+Additionally, all types can be annotated with **optional**. An optional annotation means the value may be the original type or nothing.
 
 > **Note:** The current compiler does not do type-checking; all type-checking happens at runtime. However, this is being worked on so there will soon be a compiler which will give you type errors at compile-time.
 
@@ -164,36 +164,36 @@ A type definition defines an alias, it names the given type with the given Name,
       : <Name: Identifier>
       | 'optional' <Target: Type>
       | 'any'
-      | 'boolean'
-      | 'integer'
-      | 'real'
-      | 'number'
-      | 'string'
-      | 'data'
-      | 'array'
-      | 'list'
-      | 'undefined'
-      | 'pointer'
+      | 'nothing'
+      | 'Boolean'
+      | 'Integer'
+      | 'Real'
+      | 'Number'
+      | 'String'
+      | 'Data'
+      | 'Array'
+      | 'List'
+      | 'Pointer'
 
 A type clause describes the kind of value which can be used in a variable or parameter.
 
 If a type is an identifier, then this is taken to be a named type defined in a type definition clause.
 
-An optional type means the value can be either the specified type or undefined.
+An optional type means the value can be either the specified type or nothing. Variables which are of optional type are automatically initial zed to nothing.
 
 The remaining types are as follows:
 
  - **any**: any value
- - **boolean**: a boolean value, either the value *true* or *false*.
- - **integer**: any integer number value
- - **real**: any real number value
- - **number**: any number value
- - **string**: a sequence of UTF-16 code units
- - **data**: a sequence of bytes
- - **array**: a map from string to any value (i.e. an associative array, just like in LiveCode Script)
- - **list**: a sequence of any value
- - **undefined**: a single value *undefined* (this is used to describe handlers with no return value - i.e. void)
- - **pointer**: a low-level pointer (this is used with foreign code interconnect and shouldn't be generally used).
+ - **Boolean**: a boolean value, either the value *true* or *false*.
+ - **Integer**: any integer number value
+ - **Real**: any real number value
+ - **Number**: any number value
+ - **String**: a sequence of UTF-16 code units
+ - **Data**: a sequence of bytes
+ - **Array**: a map from string to any value (i.e. an associative array, just like in LiveCode Script)
+ - **List**: a sequence of any value
+ - **nothing**: a single value *nothing* (this is used to describe handlers with no return value - i.e. void)
+ - **Pointer**: a low-level pointer (this is used with foreign code interconnect and shouldn't be generally used).
 
 > **Note:** *integer* and *real* are currently the same as *number*.
 
@@ -208,18 +208,18 @@ The remaining types are as follows:
 
 A variable definition defines a module-scope variable. In a widget module, such variables are per-widget (i.e. instance variables). In a library module, there is only a single instance (i.e. a private global variable).
 
-The type specification for the variable is optional, if it is not specified the type of the variable is *optional any* meaning that it can hold any value, including being undefined.
+The type specification for the variable is optional, if it is not specified the type of the variable is *optional any* meaning that it can hold any value, including being nothing.
 
 ## Handlers
 
     HandlerDefinition
-      : 'handler' <Name: Identifier> '(' [ ParameterList ] ')' [ 'returns' ( <ReturnType: Type> | 'nothing' ) ] SEPARATOR
+      : 'handler' <Name: Identifier> '(' [ ParameterList ] ')' [ 'returns' <ReturnType: Type> ] SEPARATOR
           { Statement }
         'end' 'handler'
 
 Handler definitions are used to define functions which can be called from LiveCode Builder code, invoked as a result of events triggering in a widget module, or called from LiveCode Script if public and inside a library module.
 
-There is no distinction between handlers which return a value and ones which do not, apart from the return type. Handlers can be called either in expression context, or in statement context. If a handler which returns no value (it is specified as *returns nothing*) is called in expression context then its value is *undefined*.
+There is no distinction between handlers which return a value and ones which do not, apart from the return type. Handlers can be called either in expression context, or in statement context. If a handler which returns no value (it is specified as *returns nothing*) is called in expression context then its value is *nothing*.
 
 	ParameterList
 	  : { Parameter , ',' }
@@ -231,7 +231,7 @@ The parameter list describes the parameters which can be passed to the handler.
 
 An in parameter means that the value from the caller is copied to the parameter variable in the callee handler.
 
-An out parameter means that no value is copied from the caller (the parameter variable in the callee handler starts as *undefined*), and the value on exit of the callee handler is copied back to the caller on return.
+An out parameter means that no value is copied from the caller, and the value on exit of the callee handler is copied back to the caller on return.
 
 > **Note:** It is a checked runtime error to return from a handler without ensuring all non-optional 'out' parameters have been assigned a value.
 
@@ -244,15 +244,15 @@ The type of parameter is optional, if no type is specified it is taken to be *op
 ## Foreign Handlers
 
     ForeignHandlerDefinition
-      : 'foreign' 'handler' <Name: Identifier> '(' [ ParameterList ] ')' [ 'returns' ( <ReturnType: Type> | 'nothing' ) ] 'binds' 'to' <Binding: String>
+      : 'foreign' 'handler' <Name: Identifier> '(' [ ParameterList ] ')' [ 'returns' <ReturnType: Type> ) ] 'binds' 'to' <Binding: String>
 
     ForeignType
       : Type
-      | 'bool'
-      | 'int'
-      | 'uint'
-      | 'float'
-      | 'double'
+      | 'CBool'
+      | 'CInt'
+      | 'CUInt'
+      | 'CFloat'
+      | 'CDouble'
 
 A foreign handler definition binds an identifier to a handler defined in foreign code.
 
@@ -269,21 +269,21 @@ This mapping means that a foreign handler with a bool parameter say, will accept
 At present, only C binding is allowed and follow these rules:
 
  - any type passes an MCValueRef
- - boolean type passes an MCBooleanRef
- - integer type passes an MCNumberRef
- - real type passes an MCNumberRef
- - number type passes an MCNumberRef
- - string type passes an MCStringRef
- - data type passes an MCDataRef
- - array type passes an MCArrayRef
- - list type passes an MCProperListRef
- - undefined type passes an MCNullRef
- - pointer type passes a void *
- - bool type passes a bool (i.e. an int - pre-C99).
- - int type passes an int
- - uint type passes an unsigned int
- - float type passes a float
- - double type passes a double
+ - nothing type passes as the null pointer
+ - Boolean type passes an MCBooleanRef
+ - Integer type passes an MCNumberRef
+ - Real type passes an MCNumberRef
+ - Number type passes an MCNumberRef
+ - String type passes an MCStringRef
+ - Data type passes an MCDataRef
+ - Array type passes an MCArrayRef
+ - List type passes an MCProperListRef
+ - Pointer type passes a void *
+ - CBool type passes a bool (i.e. an int - pre-C99).
+ - CInt type passes an int
+ - CUInt type passes an unsigned int
+ - CFloat type passes a float
+ - CDouble type passes a double
 
 Modes map as follows:
 
@@ -371,11 +371,11 @@ A variable statement defines a handler-scope variable. Such variables can be use
 
 > **Note:** Variables are currently not block-scoped, they are defined from the point of declaration to the end of the handler - this might change in a subsequent revision.
 
-Variables are initially undefined, and if of non-optional type, must be assigned a value before they can be used.
+Variables are initially undefined and thus cannot be fetched without a runtime error occurring until a value is placed into them. If a variable has been annotated with an optional type, its initial value will be nothing.
 
 > **Note:** It is a checked runtime error to attempt to use a non-optionally typed variable before it has a value.
 
-The type specification for the variable is optional, if it is not specified the type of the variable is *optional any* meaning that it can hold any value, including being undefined.
+The type specification for the variable is optional, if it is not specified the type of the variable is *optional any* meaning that it can hold any value, including being nothing.
 
 ## If Statements
 
@@ -501,7 +501,7 @@ Any parameters of 'inout' type are evaluated on entry, and assigned on exit.
 
 The return value of a handler is subsequently available by using **the result** expression.
 
-> **Note:** All handlers return a value, even if it is undefined. This means that calling a handler will always change **the result**.
+> **Note:** All handlers return a value, even if it is nothing. This means that calling a handler will always change **the result**.
 
 # Expressions
 
@@ -517,7 +517,7 @@ There are a number of expressions which are built-in and allow constant values,
 ## Constant Value Expressions
 
       ConstantValueExpression
-        : 'undefined'
+        : 'nothing'
         | 'true'
         | 'false'
         | INTEGER
@@ -526,7 +526,7 @@ There are a number of expressions which are built-in and allow constant values,
 
 Constant value expressions evaluate to the specified constant value.
 
-The **undefined** expression evaluates to the undefined value and can be assigned to any optional typed variable.
+The **nothing** expression evaluates to the nothing value and can be assigned to any optional typed variable.
 
 The **true** and **false** expressions evaluate to boolean values.
 
@@ -574,4 +574,4 @@ A call expression executes a handler.
 
 Its use is identical to a call statement, except that the return value of the handler is the value of the expression, rather than being available as **the result**.
 
-> **Note:** Handlers which return no value (i.e. have undefined as their result type) can still be used in call expressions. In this case the value of the call is **undefined**.
+> **Note:** Handlers which return no value (i.e. have nothing as their result type) can still be used in call expressions. In this case the value of the call is **nothing**.
