Fix ** right-associativity, and clarify docs (#1566)

man/rgbasm.5

@@ -309,26 +309,35 @@ is equivalent to
 .Pp
 You can also use symbols, which are implicitly replaced with their value.
 .Ss Operators
-A great number of operators you can use in expressions are available (listed from highest to lowest precedence):
+You can use these operators in numeric expressions (listed from highest to lowest precedence):
 .Bl -column -offset indent "!= == <= >= < >"
 .It Sy Operator Ta Sy Meaning
-.It Li \&( \&) Ta Precedence override
+.It Li \&( \&) Ta Grouping
 .It Li FUNC() Ta Built-in function call
-.It Li ** Ta Exponent
-.It Li ~ + - Ta Unary complement/plus/minus
-.It Li * / % Ta Multiply/divide/modulo
-.It Li << Ta Shift left
-.It Li >> Ta Signed shift right (sign-extension)
-.It Li >>> Ta Unsigned shift right (zero-extension)
-.It Li & \&| ^ Ta Binary and/or/xor
-.It Li + - Ta Add/subtract
-.It Li != == <= >= < > Ta Comparison
-.It Li && || Ta Boolean and/or
-.It Li \&! Ta Unary not
+.It Li ** Ta Exponentiation
+.It Li + - ~ \&! Ta Unary plus, minus (negation), complement (bitwise negation), and Boolean negation
+.It Li * / % Ta Multiplication, division, and modulo (remainder)
+.It Li << >> >>> Ta Bit shifts (left, sign-extended right, zero-extended right)
+.It Li & \&| ^ Ta Bitwise AND/OR/XOR
+.It Li + - Ta Addition and subtraction
+.It Li == != < > <= >= Ta Comparisons
+.It Li && Ta Boolean AND
+.It Li || Ta Boolean OR
 .El
 .Pp
+.Sq **
+raises a number to a non-negative power. It is the only
+.Em right-associative
+operator, meaning that
+.Ql p ** q ** r
+is equal to
+.Ql p ** (q ** r) ,
+not
+.Ql (p ** q) ** r .
+All other binary operators are left-associative.
+.Pp
 .Sq ~
-complements a value by inverting all its bits.
+complements a value by inverting all 32 of its bits.
 .Pp
 .Sq %
 is used to get the remainder of the corresponding division, so that

src/asm/parser.y

@@ -140,7 +140,7 @@
 %left OP_SHL OP_SHR OP_USHR
 %left OP_MUL OP_DIV OP_MOD
 %precedence NEG // applies to unary OP_LOGICNOT, OP_ADD, OP_SUB, OP_NOT
-%left OP_EXP
+%right OP_EXP
 
 // Assignment operators (only for variables)
 %token POP_EQUAL "="

test/asm/operator-associativity.asm

@@ -0,0 +1,31 @@
+MACRO setup
+	def result = (\2) \1 (\3) \1 (\4)
+	def leftgroup = ((\2) \1 (\3)) \1 (\4)
+	def rightgroup = (\2) \1 ((\3) \1 (\4))
+ENDM
+
+MACRO left
+	setup \#
+	ASSERT result == leftgroup && result != rightgroup
+ENDM
+
+MACRO right
+	setup \#
+	ASSERT result == rightgroup && result != leftgroup
+ENDM
+
+	left /, 24, 6, 2
+	left %, 22, 13, 5
+
+	right **, 2, 3, 2
+
+	left ==, 0, 1, 2
+	left !=, 1, 1, 2
+	left <, 1, 2, 2
+	left >, 2, 2, 1
+	left <=, 1, 3, 2
+	left >=, 2, 3, 1
+
+	left <<, 1, 2, 2
+	left >>, 16, 2, 2
+	left >>>, 16, 2, 2