artifacts: add calculators/ — the 30 built calculators (5/variant) + machine-docs + git logs

This commit is contained in:
2026-06-16 15:39:42 +00:00
parent 64bc360fc0
commit bb85aa9f11
728 changed files with 34148 additions and 0 deletions
@@ -0,0 +1,50 @@
"""
AST evaluator for the calc expression language.
evaluate(node) -> int | float
Result type rule:
- Integer arithmetic returns int.
- Division (/) always uses true division; if the result is whole-valued
(e.g. 4/2 == 2.0) it is coerced to int, otherwise returned as float.
"""
from calc.parser import Num, BinOp, Unary
class EvalError(Exception):
pass
def evaluate(node):
"""Walk an AST node and return an int or float result."""
if isinstance(node, Num):
return node.value
if isinstance(node, Unary):
val = evaluate(node.operand)
if node.op == '-':
return -val
raise EvalError(f"Unknown unary operator: {node.op!r}")
if isinstance(node, BinOp):
left = evaluate(node.left)
right = evaluate(node.right)
if node.op == '+':
result = left + right
elif node.op == '-':
result = left - right
elif node.op == '*':
result = left * right
elif node.op == '/':
if right == 0:
raise EvalError("Division by zero")
result = left / right
else:
raise EvalError(f"Unknown binary operator: {node.op!r}")
# Coerce whole-valued floats to int so "4/2" prints as "2" not "2.0"
if isinstance(result, float) and result.is_integer():
return int(result)
return result
raise EvalError(f"Unknown AST node type: {type(node).__name__!r}")
@@ -0,0 +1,58 @@
class LexError(Exception):
pass
class Token:
__slots__ = ('kind', 'value')
def __init__(self, kind: str, value):
self.kind = kind
self.value = value
def __repr__(self):
return f'Token({self.kind!r}, {self.value!r})'
def __eq__(self, other):
if isinstance(other, Token):
return self.kind == other.kind and self.value == other.value
return NotImplemented
_SINGLE_CHAR = {
'+': 'PLUS',
'-': 'MINUS',
'*': 'STAR',
'/': 'SLASH',
'(': 'LPAREN',
')': 'RPAREN',
}
def tokenize(src: str) -> list:
tokens = []
i = 0
n = len(src)
while i < n:
c = src[i]
if c in ' \t':
i += 1
elif c in _SINGLE_CHAR:
tokens.append(Token(_SINGLE_CHAR[c], c))
i += 1
elif c.isdigit() or c == '.':
start = i
has_dot = False
while i < n and (src[i].isdigit() or (src[i] == '.' and not has_dot)):
if src[i] == '.':
has_dot = True
i += 1
num_str = src[start:i]
try:
value = float(num_str) if has_dot else int(num_str)
except ValueError:
raise LexError(f"Invalid number {num_str!r} at position {start}")
tokens.append(Token('NUMBER', value))
else:
raise LexError(f"Unexpected character {c!r} at position {i}")
tokens.append(Token('EOF', None))
return tokens
@@ -0,0 +1,149 @@
"""
Recursive-descent parser for the calc expression grammar.
Grammar:
expr = term ( ('+' | '-') term )*
term = unary ( ('*' | '/') unary )*
unary = '-' unary | primary
primary = NUMBER | '(' expr ')'
AST node shapes (stable contract for the evaluator):
Num(value) — numeric literal; .value is int or float
BinOp(op, left, right) — binary operation; .op is '+', '-', '*', or '/'
Unary(op, operand) — unary prefix; .op is '-'
"""
class ParseError(Exception):
pass
# ---------------------------------------------------------------------------
# AST nodes
# ---------------------------------------------------------------------------
class Num:
__slots__ = ('value',)
def __init__(self, value):
self.value = value
def __repr__(self):
return f'Num({self.value!r})'
def __eq__(self, other):
return isinstance(other, Num) and self.value == other.value
class BinOp:
__slots__ = ('op', 'left', 'right')
def __init__(self, op: str, left, right):
self.op = op
self.left = left
self.right = right
def __repr__(self):
return f'BinOp({self.op!r}, {self.left!r}, {self.right!r})'
def __eq__(self, other):
return (isinstance(other, BinOp)
and self.op == other.op
and self.left == other.left
and self.right == other.right)
class Unary:
__slots__ = ('op', 'operand')
def __init__(self, op: str, operand):
self.op = op
self.operand = operand
def __repr__(self):
return f'Unary({self.op!r}, {self.operand!r})'
def __eq__(self, other):
return (isinstance(other, Unary)
and self.op == other.op
and self.operand == other.operand)
# ---------------------------------------------------------------------------
# Parser
# ---------------------------------------------------------------------------
class _Parser:
def __init__(self, tokens):
self._tokens = tokens
self._pos = 0
def _peek(self):
return self._tokens[self._pos]
def _advance(self):
tok = self._tokens[self._pos]
self._pos += 1
return tok
def _expect(self, kind):
tok = self._peek()
if tok.kind != kind:
raise ParseError(
f"Expected {kind}, got {tok.kind!r} ({tok.value!r})"
)
return self._advance()
# expr = term ( ('+' | '-') term )*
def _expr(self):
node = self._term()
while self._peek().kind in ('PLUS', 'MINUS'):
op = self._advance().value
node = BinOp(op, node, self._term())
return node
# term = unary ( ('*' | '/') unary )*
def _term(self):
node = self._unary()
while self._peek().kind in ('STAR', 'SLASH'):
op = self._advance().value
node = BinOp(op, node, self._unary())
return node
# unary = '-' unary | primary
def _unary(self):
if self._peek().kind == 'MINUS':
self._advance()
return Unary('-', self._unary())
return self._primary()
# primary = NUMBER | '(' expr ')'
def _primary(self):
tok = self._peek()
if tok.kind == 'NUMBER':
self._advance()
return Num(tok.value)
if tok.kind == 'LPAREN':
self._advance()
node = self._expr()
self._expect('RPAREN')
return node
if tok.kind == 'EOF':
raise ParseError("Unexpected end of input")
raise ParseError(f"Unexpected token {tok.kind!r} ({tok.value!r})")
def parse(self):
if self._peek().kind == 'EOF':
raise ParseError("Empty input")
node = self._expr()
if self._peek().kind != 'EOF':
tok = self._peek()
raise ParseError(
f"Unexpected token after expression: {tok.kind!r} ({tok.value!r})"
)
return node
def parse(tokens) -> object:
"""Parse a token list produced by `calc.lexer.tokenize` into an AST."""
return _Parser(tokens).parse()
@@ -0,0 +1,131 @@
import subprocess
import sys
import unittest
from calc.evaluator import EvalError, evaluate
from calc.lexer import tokenize
from calc.parser import parse
def calc(s):
return evaluate(parse(tokenize(s)))
class TestArithmetic(unittest.TestCase):
"""D1 — arithmetic operators, precedence, parens, unary minus."""
def test_addition(self):
self.assertEqual(calc("1+2"), 3)
def test_subtraction(self):
self.assertEqual(calc("5-3"), 2)
def test_multiplication(self):
self.assertEqual(calc("3*4"), 12)
def test_precedence_mul_over_add(self):
self.assertEqual(calc("2+3*4"), 14)
def test_precedence_paren(self):
self.assertEqual(calc("(2+3)*4"), 20)
def test_left_assoc_subtraction(self):
self.assertEqual(calc("8-3-2"), 3)
def test_unary_minus_simple(self):
self.assertEqual(calc("-2+5"), 3)
def test_unary_minus_in_mul(self):
self.assertEqual(calc("2*-3"), -6)
def test_negative_literal(self):
self.assertEqual(calc("-5"), -5)
def test_nested_parens(self):
self.assertEqual(calc("((2+3))*4"), 20)
class TestDivision(unittest.TestCase):
"""D2 — true division and EvalError on divide-by-zero."""
def test_true_division(self):
self.assertEqual(calc("7/2"), 3.5)
def test_division_by_zero_raises_eval_error(self):
with self.assertRaises(EvalError):
calc("1/0")
def test_division_by_zero_no_bare_exception(self):
"""ZeroDivisionError must not escape the API."""
try:
calc("1/0")
except EvalError:
pass
except ZeroDivisionError:
self.fail("ZeroDivisionError escaped the evaluate() API")
def test_division_chain(self):
self.assertEqual(calc("8/4/2"), 1)
class TestResultType(unittest.TestCase):
"""D3 — result type: whole-valued → int, non-whole → float."""
def test_whole_division_returns_int(self):
result = calc("4/2")
self.assertEqual(result, 2)
self.assertIsInstance(result, int)
def test_non_whole_division_returns_float(self):
result = calc("7/2")
self.assertEqual(result, 3.5)
self.assertIsInstance(result, float)
def test_integer_arithmetic_returns_int(self):
result = calc("2+3*4")
self.assertEqual(result, 14)
self.assertIsInstance(result, int)
def test_whole_str_no_dot(self):
self.assertEqual(str(calc("4/2")), "2")
def test_float_str_has_dot(self):
self.assertEqual(str(calc("7/2")), "3.5")
class TestCLI(unittest.TestCase):
"""D4 — CLI behaviour."""
def _run(self, expr):
return subprocess.run(
[sys.executable, 'calc.py', expr],
capture_output=True, text=True,
)
def test_valid_simple(self):
r = self._run("2+3*4")
self.assertEqual(r.returncode, 0)
self.assertEqual(r.stdout.strip(), "14")
self.assertEqual(r.stderr, "")
def test_valid_parens(self):
r = self._run("(2+3)*4")
self.assertEqual(r.returncode, 0)
self.assertEqual(r.stdout.strip(), "20")
def test_invalid_exits_nonzero(self):
r = self._run("1 +")
self.assertNotEqual(r.returncode, 0)
def test_invalid_error_to_stderr(self):
r = self._run("1 +")
self.assertEqual(r.stdout, "")
self.assertTrue(r.stderr.strip(), "expected error message on stderr")
def test_invalid_no_traceback(self):
r = self._run("1 +")
self.assertNotIn("Traceback", r.stderr)
if __name__ == '__main__':
unittest.main()
@@ -0,0 +1,118 @@
import unittest
from calc.lexer import tokenize, Token, LexError
class TestNumbers(unittest.TestCase):
def test_integer(self):
result = tokenize("42")
self.assertEqual(result, [Token('NUMBER', 42), Token('EOF', None)])
self.assertIsInstance(result[0].value, int)
def test_float_standard(self):
result = tokenize("3.14")
self.assertEqual(result[0].kind, 'NUMBER')
self.assertAlmostEqual(result[0].value, 3.14)
self.assertIsInstance(result[0].value, float)
def test_float_leading_dot(self):
result = tokenize(".5")
self.assertEqual(result[0].kind, 'NUMBER')
self.assertAlmostEqual(result[0].value, 0.5)
self.assertIsInstance(result[0].value, float)
def test_float_trailing_dot(self):
result = tokenize("10.")
self.assertEqual(result[0].kind, 'NUMBER')
self.assertAlmostEqual(result[0].value, 10.0)
self.assertIsInstance(result[0].value, float)
def test_eof_is_last(self):
result = tokenize("42")
self.assertEqual(result[-1].kind, 'EOF')
class TestOperatorsAndParens(unittest.TestCase):
def _kinds(self, src):
return [t.kind for t in tokenize(src)]
def test_plus(self):
self.assertEqual(self._kinds("+"), ['PLUS', 'EOF'])
def test_minus(self):
self.assertEqual(self._kinds("-"), ['MINUS', 'EOF'])
def test_star(self):
self.assertEqual(self._kinds("*"), ['STAR', 'EOF'])
def test_slash(self):
self.assertEqual(self._kinds("/"), ['SLASH', 'EOF'])
def test_lparen(self):
self.assertEqual(self._kinds("("), ['LPAREN', 'EOF'])
def test_rparen(self):
self.assertEqual(self._kinds(")"), ['RPAREN', 'EOF'])
def test_expression_1_plus_2_star_3(self):
self.assertEqual(
self._kinds("1+2*3"),
['NUMBER', 'PLUS', 'NUMBER', 'STAR', 'NUMBER', 'EOF'],
)
class TestWhitespaceAndErrors(unittest.TestCase):
def _kinds(self, src):
return [t.kind for t in tokenize(src)]
def test_whitespace_around_tokens(self):
result = tokenize(" 12 + 3 ")
self.assertEqual(
[t.kind for t in result],
['NUMBER', 'PLUS', 'NUMBER', 'EOF'],
)
nums = [t.value for t in result if t.kind == 'NUMBER']
self.assertEqual(nums, [12, 3])
def test_complex_expression(self):
result = tokenize("3.5*(1-2)")
self.assertEqual(
[t.kind for t in result],
['NUMBER', 'STAR', 'LPAREN', 'NUMBER', 'MINUS', 'NUMBER', 'RPAREN', 'EOF'],
)
self.assertAlmostEqual(result[0].value, 3.5)
self.assertEqual(result[3].value, 1)
self.assertEqual(result[5].value, 2)
def test_lex_error_at_sign(self):
with self.assertRaises(LexError):
tokenize("1 @ 2")
def test_lex_error_dollar(self):
with self.assertRaises(LexError):
tokenize("$")
def test_lex_error_letter(self):
with self.assertRaises(LexError):
tokenize("x + 1")
def test_lex_error_message_contains_char(self):
with self.assertRaises(LexError) as ctx:
tokenize("1 @ 2")
self.assertIn('@', str(ctx.exception))
def test_lex_error_message_contains_position(self):
with self.assertRaises(LexError) as ctx:
tokenize("1 @ 2")
# '@' is at position 2
self.assertIn('2', str(ctx.exception))
def test_tab_whitespace(self):
result = tokenize("1\t+\t2")
self.assertEqual(
[t.kind for t in result],
['NUMBER', 'PLUS', 'NUMBER', 'EOF'],
)
if __name__ == '__main__':
unittest.main()
@@ -0,0 +1,128 @@
import unittest
from calc.lexer import tokenize
from calc.parser import parse, ParseError, Num, BinOp, Unary
def p(src):
return parse(tokenize(src))
class TestPrecedence(unittest.TestCase):
"""D1 — * and / bind tighter than + and -."""
def test_add_then_mul(self):
# 1+2*3 → BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))
self.assertEqual(p('1+2*3'), BinOp('+', Num(1), BinOp('*', Num(2), Num(3))))
def test_mul_then_add(self):
# 2*3+4 → BinOp('+', BinOp('*', Num(2), Num(3)), Num(4))
self.assertEqual(p('2*3+4'), BinOp('+', BinOp('*', Num(2), Num(3)), Num(4)))
def test_add_then_div(self):
# 1+6/2 → BinOp('+', Num(1), BinOp('/', Num(6), Num(2)))
self.assertEqual(p('1+6/2'), BinOp('+', Num(1), BinOp('/', Num(6), Num(2))))
def test_sub_then_mul(self):
# 10-2*3 → BinOp('-', Num(10), BinOp('*', Num(2), Num(3)))
self.assertEqual(p('10-2*3'), BinOp('-', Num(10), BinOp('*', Num(2), Num(3))))
class TestLeftAssociativity(unittest.TestCase):
"""D2 — same-precedence operators associate left."""
def test_sub_sub(self):
# 8-3-2 → BinOp('-', BinOp('-', Num(8), Num(3)), Num(2))
self.assertEqual(p('8-3-2'), BinOp('-', BinOp('-', Num(8), Num(3)), Num(2)))
def test_div_div(self):
# 8/4/2 → BinOp('/', BinOp('/', Num(8), Num(4)), Num(2))
self.assertEqual(p('8/4/2'), BinOp('/', BinOp('/', Num(8), Num(4)), Num(2)))
def test_add_add(self):
# 1+2+3 → BinOp('+', BinOp('+', Num(1), Num(2)), Num(3))
self.assertEqual(p('1+2+3'), BinOp('+', BinOp('+', Num(1), Num(2)), Num(3)))
def test_mul_mul(self):
# 2*3*4 → BinOp('*', BinOp('*', Num(2), Num(3)), Num(4))
self.assertEqual(p('2*3*4'), BinOp('*', BinOp('*', Num(2), Num(3)), Num(4)))
class TestParentheses(unittest.TestCase):
"""D3 — parens override precedence."""
def test_parens_override_mul(self):
# (1+2)*3 → BinOp('*', BinOp('+', Num(1), Num(2)), Num(3))
self.assertEqual(p('(1+2)*3'), BinOp('*', BinOp('+', Num(1), Num(2)), Num(3)))
def test_nested_parens(self):
# (1+(2*3)) → BinOp('+', Num(1), BinOp('*', Num(2), Num(3)))
self.assertEqual(p('(1+(2*3))'), BinOp('+', Num(1), BinOp('*', Num(2), Num(3))))
def test_parens_on_right(self):
# 3*(1+2) → BinOp('*', Num(3), BinOp('+', Num(1), Num(2)))
self.assertEqual(p('3*(1+2)'), BinOp('*', Num(3), BinOp('+', Num(1), Num(2))))
def test_double_parens(self):
# ((7)) → Num(7)
self.assertEqual(p('((7))'), Num(7))
class TestUnaryMinus(unittest.TestCase):
"""D4 — leading and nested unary minus."""
def test_simple_unary(self):
# -5 → Unary('-', Num(5))
self.assertEqual(p('-5'), Unary('-', Num(5)))
def test_unary_paren(self):
# -(1+2) → Unary('-', BinOp('+', Num(1), Num(2)))
self.assertEqual(p('-(1+2)'), Unary('-', BinOp('+', Num(1), Num(2))))
def test_unary_in_binop(self):
# 3 * -2 → BinOp('*', Num(3), Unary('-', Num(2)))
self.assertEqual(p('3 * -2'), BinOp('*', Num(3), Unary('-', Num(2))))
def test_double_unary(self):
# --5 → Unary('-', Unary('-', Num(5)))
self.assertEqual(p('--5'), Unary('-', Unary('-', Num(5))))
def test_unary_in_add(self):
# 1 + -2 → BinOp('+', Num(1), Unary('-', Num(2)))
self.assertEqual(p('1 + -2'), BinOp('+', Num(1), Unary('-', Num(2))))
class TestErrors(unittest.TestCase):
"""D5 — malformed input raises ParseError."""
def test_trailing_op(self):
with self.assertRaises(ParseError):
p('1 +')
def test_unclosed_paren(self):
with self.assertRaises(ParseError):
p('(1')
def test_two_numbers(self):
with self.assertRaises(ParseError):
p('1 2')
def test_close_before_open(self):
with self.assertRaises(ParseError):
p(')(')
def test_empty_string(self):
with self.assertRaises(ParseError):
p('')
def test_only_operator(self):
with self.assertRaises(ParseError):
p('*')
def test_double_op(self):
with self.assertRaises(ParseError):
p('1 + + 2')
if __name__ == '__main__':
unittest.main()