================================================================================
BambooBasic Operator Precedence and Symbols
================================================================================

This document lists all operators and symbols available in BambooBasic and
their order of precedence (evaluation order).

NOTE: BambooBasic transpiles to C++, so the actual precedence follows C++
operator precedence rules. The operators are listed here in order from
highest to lowest precedence.

All operators are CASE-INSENSITIVE (And, AND, and all work the same).

================================================================================
OPERATOR PRECEDENCE (Highest to Lowest)
================================================================================

1. PRIMARY OPERATORS (Highest Precedence)
   ---------------------------------------
   ( )          Parentheses/Grouping - forces evaluation order
   [ ]          Array subscript/indexing
   .            Member access (object.member)
   \            Field/Method access (object\field or object\method)
   ::           Scope resolution (namespace::member)

2. UNARY OPERATORS
   ---------------
   Not          Logical NOT (!)
   BitNot       Bitwise NOT (~)
   -            Unary minus (negation)
   +            Unary plus

3. MULTIPLICATIVE OPERATORS
   -------------------------
   *            Multiplication
   /            Division
   Mod          Modulo (remainder) (%)

4. ADDITIVE OPERATORS
   ------------------
   +            Addition
   -            Subtraction
   &            String concatenation (when used with strings)

5. BITWISE SHIFT OPERATORS
   ------------------------
   Shl          Shift left (<<)
   Shr          Shift right (>>)

6. RELATIONAL/COMPARISON OPERATORS
   --------------------------------
   <            Less than
   >            Greater than
   <=           Less than or equal
   >=           Greater than or equal

7. EQUALITY OPERATORS
   ------------------
   =            Equality (converts to == in comparisons)
   <>           Not equal (!=)
   ==           Equality (explicit)
   !=           Not equal (explicit)

8. BITWISE AND
   -----------
   BitAnd       Bitwise AND (&)
   &&           Bitwise AND (explicit)

9. BITWISE XOR
   -----------
   BitXor       Bitwise XOR (^)

10. BITWISE OR
    ----------
    BitOr       Bitwise OR (|)
    |           Bitwise OR (single pipe, when not string concat)

11. LOGICAL AND
    -----------
    And         Logical AND (&&)

12. LOGICAL OR
    ----------
    Or          Logical OR (||)
    ||          Logical OR (explicit)

13. ASSIGNMENT (Lowest Precedence)
    ------------------------------
    =           Assignment

================================================================================
COMPLETE OPERATOR REFERENCE
================================================================================

ARITHMETIC OPERATORS:
---------------------
+               Addition
-               Subtraction (binary) or negation (unary)
*               Multiplication
/               Division
Mod / %         Modulo (remainder after division)

COMPARISON OPERATORS:
---------------------
=               Equality (in comparison contexts, converts to ==)
<>              Not equal
<               Less than
>               Greater than
<=              Less than or equal
>=              Greater than or equal
==              Equality (explicit)
!=              Not equal (explicit)

LOGICAL OPERATORS:
------------------
And / &&        Logical AND (both operands must be true)
Or  / ||        Logical OR (at least one operand must be true)
Not / !         Logical NOT (inverts boolean value)

BITWISE OPERATORS:
------------------
BitAnd / &      Bitwise AND
BitOr  / |      Bitwise OR
BitXor / ^      Bitwise XOR (exclusive OR)
BitNot / ~      Bitwise NOT (one's complement)
Shl    / <<     Shift left
Shr    / >>     Shift right

STRING OPERATORS:
-----------------
&               String concatenation (joins strings)
+               Can also be used for string concatenation

OBJECT/TYPE OPERATORS:
----------------------
\               Field/method access (object\field)
.               Member access (alternative to \)
::              Scope resolution
New / Create    Object instantiation

ARRAY OPERATORS:
----------------
[ ]             Array indexing/subscript

OTHER SYMBOLS:
--------------
( )             Parentheses (grouping, function calls)
,               Separator (parameters, array elements)
:               Type annotation (variable:Type)
;               Comment (rest of line is comment)
//              Comment (alternative, rest of line is comment)

================================================================================
SPECIAL NOTES
================================================================================

1. PARENTHESES OVERRIDE PRECEDENCE:
   Use parentheses ( ) to force evaluation order when needed.
   Example: (a + b) * c  vs  a + b * c

2. STRING CONCATENATION (&):
   The & operator is used for string concatenation.
   When used with numbers, they are automatically converted to strings.
   Example: "Value: " & 42  produces  "Value: 42"

3. EQUALITY OPERATOR (=):
   Single = is used for both assignment AND equality comparison.
   In comparison contexts (If, While, etc.), it becomes ==
   In other contexts, it remains assignment.

4. NOT EQUAL (<>):
   BambooBasic uses <> for "not equal" (like BASIC/Pascal)
   This transpiles to != in C++

5. THE AMPERSAND (&) - DUAL PURPOSE:
   The & symbol serves TWO different purposes depending on context:

   a) STRING CONCATENATION (when either operand is a string):
      "Hello " & "World"     produces "Hello World"
      "Score: " & 100        produces "Score: 100" (number auto-converted)

   b) BITWISE OR (when both operands are integers):
      10 & 13                produces 15 (1010 | 1101 = 1111 in binary)
      flags & 2              sets bit 1 in flags

   The transpiler automatically detects which operation to use based on the
   operand types. If either operand is a string literal, it's concatenation.
   Otherwise, it's bitwise OR.

6. OTHER BITWISE/LOGICAL OPERATORS:
   - Logical operators (And, Or, Not) work with boolean values
   - Bitwise operators (BitAnd, BitOr, BitXor, etc.) work with integer bits
   - && is always bitwise AND
   - | is always bitwise OR
   - || is always logical OR
   - BitOr is the keyword equivalent of & when used for bitwise OR

7. CASE INSENSITIVITY:
   All operators are case-insensitive:
   - And, AND, and all work
   - Mod, MOD, mod all work
   - Not, NOT, not all work
   etc.

8. FIELD ACCESS OPERATOR (\):
   BambooBasic uses backslash \ for field/method access
   Example: player\health, enemy\TakeDamage()
   This is different from C++'s dot (.) operator

9. TYPE ANNOTATION (:):
   The colon is used to specify variable types
   Example: Local count:Int = 0
   This transpiles to C++ type declarations

================================================================================
EXAMPLES
================================================================================

PRECEDENCE EXAMPLES:
--------------------
2 + 3 * 4           = 14     (multiplication before addition)
(2 + 3) * 4         = 20     (parentheses first)
10 Mod 3 + 1        = 4      (modulo before addition)
5 > 3 And 10 < 20   = True   (comparisons before logical And)
Not 0 Or 1          = True   (Not before Or)

COMPARISON EXAMPLES:
--------------------
If x = 10 Then              (equality test)
If x <> y Then              (not equal test)
If a < b And b < c Then     (chained comparisons)

BITWISE EXAMPLES:
-----------------
flags = flags BitOr 2       (set bit 1)
value = value BitAnd $FF    (mask lower 8 bits)
result = x Shl 2            (shift left 2 positions, multiply by 4)

STRING CONCATENATION:
---------------------
name = "Player" & "1"           (produces "Player1")
message = "Score: " & score     (auto-converts score to string)

OBJECT ACCESS:
--------------
player\health = 100             (set field)
enemy\TakeDamage(10)            (call method)

================================================================================
END OF OPERATOR PRECEDENCE REFERENCE
================================================================================
