Skip to main content

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​

CategoryOperatorsExample
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 on bs types 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​

PrecedenceOperatorsNameAssociativity
1 (highest)++ -- (postfix)Post-increment, post-decrementLeft
2* / %Multiplication, division, moduloLeft
3+ -Addition, subtractionLeft
4<< >>Left shift, right shiftLeft
5< > <= >= == != =#=ComparisonsLeft
6&Bitwise ANDLeft
7^Bitwise XORLeft
8|Bitwise ORLeft
9&&Logical ANDLeft
10||Logical ORLeft
11++ -- ~ @ (prefix)Pre-increment, pre-decrement, bitwise NOT, address-ofRight
12 (lowest):: ::Double-colon groupingN/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).

OperatorMeaningC Equivalent
==Equala == b
!=Not equala != b
<Less thana < b
>Greater thana > b
<=Less than or equala <= b
>=Greater than or equala >= 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​

OperatorNameC Equivalent
&Bitwise ANDa & b
^Bitwise XORa ^ b
|Bitwise ORa | 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​

OperatorDescriptionEquivalent
+=Add and assignx = x + y
-=Subtract and assignx = x - y
*=Multiply and assignx = x * y
/=Divide and assignx = x / y
%=Modulo and assignx = x % y
&=Bitwise AND and assignx = x & y
|=Bitwise OR and assignx = x | y
^=Bitwise XOR and assignx = x ^ y
<<=Left shift and assignx = x << y
>>=Right shift and assignx = 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:

  1. 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)++.

  2. Double-colon ::expr:: at the lowest level (12). This is a deliberate design: ::expr:: always evaluates expr in 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 OperatorC OutputNotes
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:

  1. ::a + b:: groups first (lowest precedence: grouping)
  2. ::c + d:: groups next
  3. > comparison between the two groups (level 5)
  4. The comparison result feeds the ternary condition