Merge remote-tracking branch 'origin/feature/f0049' into feature/f0049

docs/books/crexx_language_reference/crexx_language_reference.tex

@@ -44,7 +44,10 @@ \part{Overview}
 \input{data_types}
 \input{literals}
 \input{variables}
+\input{namespace}
 \input{classes_and_interfaces}
+\input{operators}
+\input{statements}
 
 
 \part{Reference}

docs/books/crexx_language_reference/namespace.md

@@ -0,0 +1,11 @@
+# Namespace {#namespace}
+
+In Rexx programming, the "namespace" instruction plays a crucial role in organizing and structuring modules within a program. It allows you to define a unique identifier for a module, enabling multiple modules to coexist within the same program while maintaining their own identity and scope.
+
+The namespace instruction is used after the "options" instruction in a Rexx program. By specifying a namespace, you define the logical group or category to which a particular module belongs. This helps in organizing related modules together and facilitates their identification and usage from other modules within the program.
+
+One of the key benefits of using namespaces is that it allows you to control the exposure of procedures, members, and globals from one module to another. When you define a namespace, you can specify which elements of that module will be visible and accessible to other modules. This enhances modularity and encapsulation by limiting the scope of variables and procedures to specific namespaces, preventing potential conflicts and promoting code reusability.
+
+If a module does not explicitly include a namespace instruction, Rexx automatically assigns it to a default namespace based on the file name. The default namespace is derived from the file name without the ".rexx" file type. 
+
+By leveraging namespaces, Rexx programmers can create modular and well-organized programs, enhancing code readability, maintainability, and reusability. Namespaces promote a structured approach to program design, allowing developers to group related functionality together and control the visibility of elements across different modules.

docs/books/crexx_language_reference/operators.md

@@ -0,0 +1,63 @@
+# Operators
+
+## Expression Operators {#expression-operators}
+
+Level B incorporates the Classic REXX operators. These operators function similarly to their counterparts in other programming languages. However, it's worth mentioning that Classic REXX, being untyped, allows for flexible use of these operators with different data types, which might lead to implicit conversions or unexpected behaviours. In Level B, this flexibility is supported by implicit promotions which may lead to errors at compile or runtime. 
+
+## **Arithmetic operators** {#arithmetic-operators}
+
+* \+ Add  
+* \- Subtract  
+* \* Multiply  
+* / Divide  
+* % Divide and return only the integer part of the quotient  
+* // Divide and return only the remainder (not modulo because the result can be negative)  
+* \*\* Raise the number to a whole-number power (exponentiation)  
+* Prefix \- Negate the next term  
+* Prefix \+ Take the next term as-is
+
+## **Comparative operators** {#comparative-operators}
+
+* \== Exactly equal (identical)  
+* \= Equal (numerically or when padded)  
+* ¬==, /== Not exactly equal (inverse of \==)  
+* ¬=, /= Not equal (inverse of \=)  
+* \> Greater than  
+* \< Less than  
+* \< \> Not equal  
+* \>= Greater than or equal  
+* ¬\< Not less than  
+* \<= Less than or equal  
+* ¬\> Not greater than
+
+## **String Concatenation** {#string-concatenation}
+
+* || Concatenate terms (you can use no blanks or one blank)  
+* {space} Concatenate with a space added between terms  
+* {abuttal} (i.e. no space between a literal and variable) Concatenate without a space added between terms
+
+## **Logical operators** {#logical-operators}
+
+* & AND (returns 1 if both terms are true)  
+* | Inclusive OR (returns 1 if either term is true)  
+* && Exclusive OR (returns 1 if either term is true, but not both)  
+* Prefix ¬ Logical NOT (negates; 1 becomes 0 and vice-versa)
+
+## **Term Operators** {#term-operators}
+
+* () Parenthetical grouping  
+* \[\] or . Array index
+
+## **Operator priorities** {#operator-priorities}
+
+The order of priority of the operators (from highest to lowest) is:
+
+1. () \[\] . Term operators  
+2. \+ \- ¬ Prefix operators  
+3. \*\* Exponentiation  
+4. \* / % // Multiply and divide  
+5. \+ \- Add and subtract  
+6. || Concatenation (with or without blank)  
+7. \=, \>, … All comparison operators  
+8. & And  
+9. |, && Or, exclusive or

docs/books/crexx_language_reference/statements.md

@@ -0,0 +1,165 @@
+# Statements {#statements}
+
+## **ADDRESS** {#address}
+
+ADDRESS … 
+
+The ADDRESS instruction is a directive that enables the transmission of commands to an external environment.
+
+## 
+
+## **ARG**  {#arg}
+
+See Procedures and Arguments Section
+
+## 
+
+## **CALL** {#call}
+
+CALL routine \[ parameter \] \[, \[ parameter \] ... \] 
+
+## 
+
+## **DO/END** {#do/end}
+
+DO \[ repetitor \] \[ conditional \] ; \[ clauses \]
+
+END \[ symbol \] ;
+
+repetitor : \= symbol \= expri \[ TO exprt \] \[ BY exprb \] \[ FOR exprf \]
+
+conditional : \= WHILE exprw UNTIL expru
+
+The DO/END statement is the command employed to iterate and group multiple statements into a singular block. This instruction consists of multiple clauses.
+
+## 
+
+## **EXIT**  {#exit}
+
+EXIT \[ expr \] ;
+
+Causes the Rexx program to cease execution and, optionally, returns the expression expr to the calling program.
+
+## 
+
+## **IF/THEN/ELSE** {#if/then/else}
+
+IF expr \[;\] THEN \[;\] statement
+
+\[ ELSE \[;\] statement \]
+
+This provides the standard conditional statement structure.
+
+## 
+
+## **ITERATE** {#iterate}
+
+ITERATE \[ symbol \] ;
+
+The ITERATE instruction will execute the innermost, active loop in which the ITERATE instruction is situated repeatedly. If a symbol is specified, it will execute the innermost, active loop having the symbol as the control variable repeatedly.
+
+## 
+
+## **LEAVE** {#leave}
+
+LEAVE \[ symbol \] ;
+
+This statement terminates the innermost, active loop. If symbol is specified, it terminates the innermost, active loop having symbol as control variable. 
+
+## 
+
+## **NOP** {#nop}
+
+NOP ;
+
+The NOP instruction is the "null operation" directive; it executes without performing any operation.
+
+## 
+
+## **OPTIONS** {#options}
+
+OPTIONS expr ;
+
+The OPTIONS instruction is used to set various interpreter-specific options. See Language Level and Options Section
+
+## 
+
+## **PARSE** {#parse}
+
+PARSE \[ option \] \[ CASELESS \] type \[ template \] ;
+
+*CURRENT STATUS: not implemented*
+
+## 
+
+## **PROCEDURE** {#procedure}
+
+See Procedures and Arguments Section.
+
+## 
+
+## **SAY** {#say}
+
+SAY \[ expr \] ;
+
+Evaluates the expression expr and prints the resulting string onto the standard output stream.
+
+## 
+
+## **SELECT/WHEN/OTHERWISE** {#select/when/otherwise}
+
+*CURRENT STATUS: not implemented*
+
+## 
+
+## **TRACE** {#trace}
+
+CURRENT STATUS: not implemented (Debugging Approach TBC)
+
+# Procedures and Arguments {#procedures-and-arguments}
+
+## **Function Arguments** {#function-arguments}
+
+Arguments can be passed to a procedure by reference or by value. When an argument is passed by reference, the procedure can modify the original variable that was passed to it. When an argument is passed by value, a copy of the variable is passed to the procedure, and any changes made to the copy do not affect the original variable.
+
+By example:
+
+ARG a1 \= 0, a2 \= .int, expose a3 \= .aclass, ?a4 \= .aclass, a5 \= .string\[\]
+
+* Arg a1 is an optional integer (and 0 if not specified in the call)  
+* Arg a2 is a mandatory integer (pass by value)  
+* Arg a3 is a mandatory class aclass pass by reference  
+* Arg a4 is a optional class aclass pass by value, value from the default factory if not specified in the call  
+* Arg a5 is an array of strings and is one way to allow an arbitrary number of strings to be passed to the procedure (see also Ellipsis later)
+
+## **Ellipsis (...)** {#ellipsis-(...)}
+
+The last arguments declaration can be an ellipsis ('...'), this is used to show that 0 or more arguments can be provided. For example:
+
+ARG a1 \= 0, a2 \= .int, ... \= .string
+
+* The '...' shows that an arbitrary number of .string arguments can be added to the end of the call.  
+* The ? operator exist to access & query arguments:  
+* ?a1 returns true if the optional arg a1 was specified.  
+* ?a2 will always be true as a2 is not optional.
+
+Pseudo Array arg allows access to the '...' arguments. Also see the Arrays section.
+
+* arg\[1\] or arg.1 gives the first '...' argument. These can signal OUTOFRANGE  
+* arg\[0\], arg\[\], arg.0 or arg. return the number of '...' arguments
+
+The type of this Pseudo is the type of the '...' argument
+
+## **arg() Operator** {#arg()-operator}
+
+The compatibility arg() operator is designed to provide some compatibility with classic REXX; by example:
+
+* arg() is equivalent to arg.0 etc. Type Integer.  
+* arg(1) is equivalent to arg.1 etc. The type of this operator is the same as the '...' argument and like arg.1 can signal OUTOFRANGE  
+* arg(4,E), arg(4,"E"), arg(4,Exxx), arg(4,"Exxx") etc. all return 1 (true) if there were 4 or more '...' arguments given or 0 (false) otherwise. E is Exists.  
+* Likewise arg(4,'O') etc. (O is Omitted) is equivalent to \~arg(4,'E').
+
+## **Implicit Main Procedure** {#implicit-main-procedure}
+
+In the event that a module file contains instructions preceding a PROCEDURE instruction, an implicit procedure named main() is automatically generated within the namespace of the module file. The arguments for this procedure can be accessed through the pseudo array arg or arg() operator. The return type of the implicitly defined main() procedure is automatically set to either int or void.
+

docs/books/crexx_language_reference/variables.md

@@ -24,6 +24,3 @@ Variables can also be declared and initialized by class name.
 * Class Instance \= .ACLASS(ARG1,ARG2) via a factory function with 2 arguments
 
 Once a variable has been assigned a type, then the type cannot be changed.
-
-# 
-