Syntax, Operators & Precedence

Kalc allows you to write calculations using both classical mathematical symbols and conversational English phrases. Its parser is backed by a top-down Pratt Parser (operator precedence from level 10 to 100), ensuring intuitive factor binding and natural expression evaluation.

---

Operators & Natural Language Synonyms

Mathematical symbols and their English counterparts can be used interchangeably:

Operation	Symbolic	Conversational Synonyms	Example
Addition	+	plus, and	10 + 20 or 10 plus 20
Subtraction	-	minus, subtract, without	50 - 15 or 50 minus 15
Multiplication	*, ×, ·	times, multiplied by, mul	12 * 8 or 12 times 8
Division	/, ÷	divided by, divide, over	100 / 4 or 100 divided by 4
Exponentiation	^, **	pow, to the power of	2^8 or 2 to the power of 8
Conversion	->	in, to, as, into	50 cm in inches or 100 EUR to USD
Percentages	%	percent	15% of $80

---

Pratt Operator Precedence Table

When multiple operations appear on a single line, Kalc resolves them using top-down operator precedence:

Precedence Level	Operators / Tokens	Associativity	Description
10 (Lowest)	->, in, to, as, into	Left	Unit, currency, and radix conversions
20	as a % of, as a % on, as a % off, to ... as %	Left	Relative and proportional percentages
30	+, -, plus, minus, subtract	Left	Binary addition and subtraction
40	Adjacent multi-part units (1 m 20 cm, $5 50 c)	Left	Dimensional combination addition
50	*, /, times, mul, divide, over	Left	Multiplication and division
60	of, on, off (in percentage context)	Left	Percentage scaling and offsets
70	Implicit multiplication (2(3+4), 5x, 10USD)	Left	Adjacent factors and scalar prefixes
80	^, pow, to the power of	Right	Exponentiation
90	Prefix +, -, sqrt, sin, cos, not	Right (Prefix)	Unary signs, bitwise NOT, and function calls
100 (Highest)	Parentheses (...), Literals, Variables, Tab@var	Atom	Grouping, primary identifiers, cross-tab refs

Precedence Example

4 + 5 * 2                                       // 14 (Multiplication binds tighter than addition)
(4 + 5) * 2                                     // 18 (Parentheses take highest precedence)
100 + 10% in EUR                                // 101.45 EUR (Percentage offset binds before conversion)

---

Implicit Multiplication

Kalc understands common mathematical shorthand without requiring explicit * or times operators:

1. Number Adjacent to Parentheses:

   2(3 + 4)                                     // 14

2. Adjacent Grouped Parentheses:

   (4)(5)                                       // 20

3. Scalar Adjacent to Variable or Unit:

   x = 25
   4x                                           // 100
   10USD + 20USD                                // $30.00
   200m in feet                                 // 656.17 ft

---

Unicode Normalization & Casing Rules

1. Unicode Normalization Form C (NFC)

All source text is normalized to Unicode NFC before lexing. Mathematical operators like × (U+00D7), ÷ (U+00F7), non-breaking spaces, and typographic minus signs (−, —, –) are recognized cleanly as their standard ASCII counterparts.

2. Case Sensitivity

• Case-Insensitive: Keywords, operator synonyms, built-in functions, and date keywords:
  • sqrt, SQRT, Sqrt
  • in, IN
  • plus, PLUS
  • today, TODAY
• Case-Sensitive: Identifiers and unit symbols where case conveys dimensional meaning:
  • m (meter) vs. M (mega prefix)
  • k (kilo prefix) vs. K (Kelvin temperature)
  • b (bits) vs. B (bytes)
  • User variable identifiers (taxRate vs. TaxRate)

---

Formula Formatting (⌥ ⇧ ⌘ F)

Kalc includes a built-in AST FormulaFormatter:

• Normalizes binary operator spacing (2+3*4 $\rightarrow$ 2 + 3 * 4).
• Standardizes keyword casing (SQRT $\rightarrow$ sqrt, IN $\rightarrow$ in).
• Balances nested parentheses.
• Cleans trailing whitespace while preserving comments and headings.

---

Conditionals & Guard Clauses

Kalc supports inline branching using either explicit if...then...else or trailing unless guard clauses:

if <condition> then <thenBranch> else <elseBranch>

score = 85
status = if score >= 80 then "Distinction" else "Pass"  // Distinction

tax_bracket = if income > $100k then 32% else 22%

<expression> unless <condition>

discounted_price = price - 15% unless member == false
fee = $25 unless balance > $1000

---

Compound Assignment (+=, -=, *=, /=)

Update previously declared variables in-place:

balance = $1,000                                // $1,000.00
balance += $250                                 // $1,250.00
balance -= 15%                                  // $1,062.50
balance *= 1.05                                 // $1,115.63
balance /= 2                                    // $557.81

---

Comparison & Equality Operators

Evaluate numeric, currency, date, or dimensional comparisons returning boolean results (true or false):

Operator	Meaning	Example	Result
==	Exactly equal	100 cm == 1 m	true
!=	Not equal	$50 != 50 EUR	true
<	Less than	45 mins < 1 hour	true
<=	Less than or equal to	1000 MB <= 1 GB	true
>	Greater than	5 kg > 10 lbs	true
>=	Greater than or equal to	120 km/h >= 75 mph	false

---

Bitwise Operators & Shifts

For embedded engineering, systems programming, and flag masking:

Operator	Natural Synonym	Description	Example
&	and	Bitwise AND	0xFF00 & 0x00FF $\to$ 0
|	or	Bitwise OR	0x0F00 | 0x000F $\to$ 3855 (0x0F0F)
^	xor	Bitwise XOR	0xAAAA ^ 0xFFFF $\to$ 21845 (0x5555)
~	not	Bitwise NOT	not 0 in hex
<<	shl	Bitwise Shift Left	1 << 8 in hex $\to$ 0x100
>>	shr	Bitwise Shift Right	0x1000 >> 4 in hex $\to$ 0x100