---
epic: 5
story: 5.1
title: "Variable Declaration & Usage"
status: draft
---

## Epic 5 — Variables, Line References & Aggregators
**Goal:** Transform the notepad into a lightweight computational document.

### Story 5.1: Variable Declaration & Usage

As a **CalcPad user**,
I want to declare named variables and use them in subsequent expressions,
So that I can build readable, self-documenting calculations that update automatically when I change an input.

**Acceptance Criteria:**

**Given** a line containing an assignment expression like `monthly_rent = $1250`
**When** the engine evaluates that line
**Then** the variable `monthly_rent` is stored with the value `1250` (with currency context preserved)
**And** the answer column displays `$1,250` for that line

**Given** a variable `monthly_rent` has been declared on a previous line
**When** the user writes `monthly_rent * 12` on a subsequent line
**Then** the engine resolves `monthly_rent` to its current value and displays `$15,000`

**Given** a variable `monthly_rent` is used on lines 3, 5, and 7
**When** the user changes the declaration on line 1 from `monthly_rent = $1250` to `monthly_rent = $1400`
**Then** every dependent line (3, 5, 7) re-evaluates automatically using the new value
**And** the results update within the same evaluation cycle (no stale values visible)

**Given** a variable `x = 10` declared on line 1 and `y = x * 2` on line 2
**When** the user changes line 1 to `x = 20`
**Then** line 2 re-evaluates to `40` via the dependency graph (transitive update)

**Given** a variable name that conflicts with a built-in function or unit name (e.g., `min = 5`)
**When** the engine evaluates the assignment
**Then** the engine either rejects the assignment with an error or clearly shadows the built-in with a warning indicator

**Given** the user writes a variable name using valid identifier characters (letters, digits, underscores, starting with a letter or underscore)
**When** the engine parses the line
**Then** the variable is accepted
**And** names like `tax_rate`, `_temp`, `item1` are all valid

**Given** the user writes a variable name with invalid characters (e.g., `my-var = 5` or `3x = 10`)
**When** the engine parses the line
**Then** the line is treated as an error or as a non-assignment expression (not silently misinterpreted)