Operators
Raml operators are organized by precedence (highest to lowest). The grammar defines three expression tiers — this page covers the full expr tier.
Overview
Raml supports a C-like operator set with a few additions for bit-level and pointer operations.
Quick Reference
| Category | Operators | Example |
|---|---|---|
| Arithmetic | + - * / % | x + y |
| Bitwise | & | ^ ~ << >> | flags & 0xF |
| Comparison | == != < > <= >= | a > b |
| Logical | && || | x > 0 && x < 10 |
| Pointer | @ # =#= +#= | @var, #ptr, p =#= q |
| Increment | ++ -- (prefix/postfix) | i++, ++i |
| Grouping | ::expr:: | ::a > b:: |
Important Notes
- Comparisons and logical operators in method/function arguments require the
::expr::grouping syntax or a temporary variable. See Design Notes for the rationale. - The
+operator onbstypes performs bitstream concatenation, not addition. - Pointer operations (
@,#,=#=,+#=) are covered in detail on the Memory page. - Compound assignment operators (
+=,-=, etc.) modify a variable and produce no value.
Precedence Table
| Precedence | Operators | Name | Associativity |
|---|---|---|---|
| 1 (highest) | ++ -- (postfix) | Post-increment, post-decrement | Left |
| 2 | * / % | Multiplication, division, modulo | Left |
| 3 | + - | Addition, subtraction | Left |
| 4 | << >> | Left shift, right shift | Left |
| 5 | < > <= >= == != =#= | Comparisons | Left |
| 6 | & | Bitwise AND | Left |
| 7 | ^ | Bitwise XOR | Left |
| 8 | | | Bitwise OR | Left |
| 9 | && | Logical AND | Left |
| 10 | || | Logical OR | Left |
| 11 | ++ -- ~ @ (prefix) | Pre-increment, pre-decrement, bitwise NOT, address-of | Right |
| 12 (lowest) | :: :: | Double-colon grouping | N/A |
Operator Reference (Detailed)
Postfix Operators
expr++ — Post-Increment
Returns the current value, then increments by 1.
x = 5
y = x++ // y = 5, x = 6
C equivalent: x++
expr-- — Post-Decrement
Returns the current value, then decrements by 1.
x = 5
y = x-- // y = 5, x = 4
C equivalent: x--
Multiplicative Operators
* — Multiplication
result = a * b
C equivalent: a * b
/ — Division
quotient = a / b
C equivalent: a / b. Integer division; division by zero triggers a runtime error.
% — Modulo
remainder = a % b
C equivalent: a % b
Additive Operators
+ — Addition / Bitstream Concatenation
For numeric types, performs addition. For bs types, concatenates bitstreams.
sum = 3 + 4 // 7
bs msg = "hi" + "!" // "hi!"
C equivalent (numeric): a + b
- — Subtraction
diff = 10 - 3 // 7
C equivalent: a - b
Shift Operators
<< — Left Shift
shifted = 1 << 3 // 8
C equivalent: a << b
>> — Right Shift
shifted = 8 >> 2 // 2
C equivalent: a >> b. Arithmetic right shift on signed types; logical right shift on unsigned.
Comparison Operators
All comparisons return a boolean value (0 or 1).
| Operator | Meaning | C Equivalent |
|---|---|---|
== | Equal | a == b |
!= | Not equal | a != b |
< | Less than | a < b |
> | Greater than | a > b |
<= | Less than or equal | a <= b |
>= | Greater than or equal | a >= b |
=#= | Address equality (pointers) | a == b (pointer compare) |
Note the :: … :: grouping around comparisons — this is required to prevent the comparison operators from being absorbed by surrounding expressions:
eq = ::a == b::
ne = ::a != b::
lt = ::a < b::
gt = ::a > b::
Bitwise Operators
| Operator | Name | C Equivalent |
|---|---|---|
& | Bitwise AND | a & b |
^ | Bitwise XOR | a ^ b |
| | Bitwise OR | a | b |
~ | Bitwise NOT (prefix) | ~a |
Examples:
masked = value & 0xFF
xored = value ^ 0x55
combined = a | b
inverted = ~value
Logical Operators
&& — Logical AND
if ::x > 0:: && ::x < 10:::
print "in range"
Returns 0 or 1. Short-circuit evaluation.
|| — Logical OR
if ::x == 0:: || ::x == 1:::
print "zero or one"
Returns 0 or 1. Short-circuit evaluation.
Prefix Operators
++expr — Pre-Increment
Increments by 1, then returns the new value.
x = 5
y = ++x // y = 6, x = 6
--expr — Pre-Decrement
Decrements by 1, then returns the new value.
x = 5
y = --x // y = 4, x = 4
@expr — Address-Of
Returns the memory address of a variable.
x = 42
bs# p = @x // p holds the address of x
C equivalent: &x
Double-Colon Grouping
::expr:: — Boolean Grouping
Groups a comparison expression to prevent it from being absorbed into surrounding operators.
in_range = ::low >= 0:: && ::high <= 100::
This is essential when combining multiple comparisons with logical operators. See Design Notes for why this syntax exists.
Compound Assignments
| Operator | Description | Equivalent |
|---|---|---|
+= | Add and assign | x = x + y |
-= | Subtract and assign | x = x - y |
*= | Multiply and assign | x = x * y |
/= | Divide and assign | x = x / y |
%= | Modulo and assign | x = x % y |
&= | Bitwise AND and assign | x = x & y |
|= | Bitwise OR and assign | x = x | y |
^= | Bitwise XOR and assign | x = x ^ y |
<<= | Left shift and assign | x = x << y |
>>= | Right shift and assign | x = x >> y |
+#= | Bit increment (raw bit offset) | x = x + y (element-size agnostic) |
+#= — Bit Increment
Adds a raw bit offset rather than stepping by element size. Useful with bs# pointers.
bs# bp = @target
bp +#= 1 // advance by 1 bit (not by sizeof(element))
Method Calls
->receiver:method — Method Call
Invokes a method on an object instance. The -> prefix distinguishes method calls from field access:
->c:inc 5 // method with arguments
->c:reset // method without arguments
v = ->c:value // method in expression context
Syntax variants:
->recv:method arg1 arg2— method with arguments->recv:method— method without arguments (expression context)->recv:method |— pipe-style multiline arguments
Multi-Field Assignment
:f1 f2 f3: = value
Assigns the same value to multiple fields at once:
:c1 c2 c3: = 0 // sets c1=0, c2=0, c3=0
When used inside an object method, the fields are accessed via self->field in the generated C code.
Dynamic Field Access
object:expr:
Accesses an object field whose name is determined at runtime:
c:idx: // resolves to field c1, c2, etc. based on idx value
The expression idx is evaluated and matched against the object's field names. The generated C code uses a nested ternary chain to select the correct field at runtime.
Can also reference global variables:
g1 g2 g3
:start:
i = 2
print g:i: // prints g2
Range Field Check
c:lo..hi: cmpOp val:
Checks a range of numbered fields against a comparison value. Generates ||-chained conditions for all fields whose numeric suffix falls within the range [lo, hi]:
c:1..9: == 0: // checks if any of c1..c9 equals 0
This generates C code equivalent to:
if (self->c1 == 0 || self->c2 == 0 || ... || self->c9 == 0) { ... }
Supported operators: ==, !=, <, >, <=, >=
Address Assignment
#= — Address Assignment
Assigns an address to a pointer variable.
bs# p = @x
p #= @y // p now points to y
C equivalent: p = &y
Deep Dive
This section covers the technical rationale for operator design, codegen mapping, and edge cases.
Precedence Rationale
Raml's operator precedence closely follows C's with two notable differences:
-
Postfix and prefix
++/--are at opposite ends of the table (levels 1 and 11). This matches C semantics where*x++parses as*(x++), not(*x)++. -
Double-colon
::expr::at the lowest level (12). This is a deliberate design:::expr::always evaluatesexprin its entirety before any surrounding operator sees it. This is essential because the grammar's three-tier expression system restricts comparisons in method arguments —::provides an escape hatch.
Codegen Mapping Table
| Raml Operator | C Output | Notes |
|---|---|---|
a + b (numeric) | (a + b) | Direct C translation |
a + b (bs type) | raml_bs_concat(a, b) | Function call for bitstreams |
a - b | (a - b) | Direct |
a * b | (a * b) | Direct |
a / b | (a / b) | Direct |
a % b | (a % b) | Direct |
a << b | (a << b) | Direct |
a >> b | (a >> b) | Direct |
a & b | (a & b) | Direct |
a | b | (a | b) | Direct |
a ^ b | (a ^ b) | Direct |
~a | (~a) | Direct |
&& | && | Direct; short-circuit preserved |
|| | || | Direct; short-circuit preserved |
@var | (&var) | Address-of |
#ptr | (*ptr) | Dereference |
ptr #= addr | (ptr = addr) | Address assignment |
p =#= q | (p == q) | Pointer comparison |
ptr += n | (ptr += n) | Element-size step |
ptr +#= n | ((void*)((char*)ptr + n)) | Raw byte offset |
Operator Restrictions in Arguments
Method and function call arguments use simpleExprItem, which excludes comparison (==, !=, <, >, <=, >=, =#=) and logical (&&, ||) operators.
Why: Without this restriction, operators following a method call could be absorbed into its argument list. For example, b:get move != 0 could parse as either:
(board_get(&b, move)) != 0— compare the return value (intended)board_get(&b, (move != 0))— pass the comparison result as argument (unintended)
Workaround: Compute the comparison first, or use :: grouping:
is_occupied = b:get move != 0 // comparison applies to return value
if is_occupied:
print "taken"
// Or use double-colon:
if ::b:get move != 0:::
print "taken"
Overflow Semantics
Integer overflow follows the same behavior as the underlying C type:
- Integer values wrap around modulo 2^N (defined behavior in C)
- The compiler does not insert overflow checks
Operator Precedence: Full Example
result = ::a + b:: > ::c + d:: ? print "yes" : print "no"
Parsing order:
::a + b::groups first (lowest precedence: grouping)::c + d::groups next>comparison between the two groups (level 5)- The comparison result feeds the ternary condition