49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
---
|
|
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)
|