Thinking in CalcMark

Transition from calculator thinking to idiomatic CalcMark — sum of, percentage operators, rates, and growth functions.

You’re moving from Austin to Denver. New job, new apartment, new cost of living. Time to crunch some numbers.

You could open a spreadsheet. Or you could write it down the way you think about it.

Key Idioms Covered #

Simple Arithmetic Already Works #

Start with the basics. How much more is rent in Denver?

rent_austin = $1450
rent_denver = $1750
difference = rent_denver - rent_austin

rent_austin = $1450                  $1,450.00
rent_denver = $1750                  $1,750.00
difference = rent_denver - ...       $300.00

{
  "source": "difference = rent_denver - rent_austin",
  "value": "$300.00",
  "type": "currency",
  "numeric_value": 300,
  "unit": "USD",
  "variable": "difference"
}

No special syntax needed. CalcMark understands currency, does the arithmetic, and formats the result. If you can type it into a calculator, it works here too.

The difference is what comes next.

Adding Things Up #

Your instinct from a calculator:

total = rent + groceries + transport + utilities

That works! But when the list grows to eight items, it gets unwieldy. CalcMark has a better way:

rent = $1750
groceries = $400
transport = $165
utilities = $120
total = sum of rent, groceries, transport, utilities

rent = $1750                         $1,750.00
groceries = $400                     $400.00
transport = $165                     $165.00
utilities = $120                     $120.00
total = sum of rent, ...             $2,435.00

{
  "source": "total = sum of rent, groceries, transport, utilities",
  "value": "$2,435.00",
  "type": "currency",
  "numeric_value": 2435,
  "unit": "USD",
  "variable": "total"
}

sum of reads like English and scales to any number of items. You could also write sum(rent, groceries, transport, utilities) — both produce identical results. But the NL form is what makes CalcMark feel like writing, not programming.

Percentages Without the Math #

The Denver job pays 8% more. Your calculator instinct:

adjusted = salary * 1.08

Or worse:

adjusted = salary + salary * 0.08

In CalcMark, percentages are operators:

salary = $85000
adjusted = salary + 8%
after_tax = adjusted - 24%

salary = $85000                      $85K
adjusted = salary + 8%               $91.8K
after_tax = adjusted - 24%           $69.77K

{
  "source": "adjusted = salary + 8%",
  "value": "$91.8K",
  "type": "currency",
  "numeric_value": 91800,
  "unit": "USD",
  "variable": "adjusted"
}

salary + 8% means “salary plus 8% of salary.” adjusted - 24% means “adjusted minus 24% of adjusted.” No manual conversion to decimals. No remembering whether to multiply by 1.08 or 0.08.

Rates and Accumulation #

Denver has great public transit. How much will your commute cost per month?

Your calculator instinct: count the rides, multiply everything out:

cost_per_ride = $2.75
rides_per_day = 2
days_per_month = 22
monthly_commute = 2.75 * 2 * 22

That works, but you’re doing the work the computer should do. CalcMark understands rates:

fare = $5.50/day
monthly_commute = fare over 1 month

fare = $5.50/day                     5.5 $/day
monthly_commute = fare over 1 ...    $165.00

[
  {
    "source": "fare = $5.50/day",
    "value": "5.5 $/day",
    "type": "rate",
    "numeric_value": 5.5,
    "unit": "$/day",
    "variable": "fare"
  },
  {
    "source": "monthly_commute = fare over 1 month",
    "value": "$165.00",
    "type": "currency",
    "numeric_value": 165,
    "unit": "USD",
    "variable": "monthly_commute"
  }
]

$5.50/day creates a Rate — a first-class type in CalcMark. over accumulates it across a time period. You write what you mean ("$5.50 per day, over one month") and CalcMark handles the multiplication.

Putting It Together #

Here’s your full Denver budget. First, the way you’d write it on a calculator:

salary = $85000
take_home = salary + salary * 0.08
take_home = take_home - take_home * 0.24
monthly_income = take_home / 12

rent = $1750
groceries = $400
commute = 2.75 * 2 * 22
utilities = $120
total_expenses = rent + groceries + commute + utilities

remaining = monthly_income - total_expenses

salary = $85000
take_home = salary + 8% - 24%
monthly_income = take_home / 12

rent = $1750
groceries = $400
commute = $5.50/day over 1 month
utilities = $120
total_expenses = sum of rent, groceries, commute, utilities

remaining = monthly_income - total_expenses

Same result. But the CalcMark version is shorter, reads more naturally, and doesn’t require you to remember percentage formulas or count multiplication operands.

Saving for a House #

You’re settled in Denver. Time to start saving for a down payment.

Your calculator instinct — the compound interest formula:

future = 500 * (1 + 0.045 / 12) ^ (12 * 5)

Quick — what does that compute? You’d have to stare at it to decode it. In CalcMark:

compound $500 by 4.5% monthly over 5 years

compound $500 by 4.5% monthly ...   $625.90

{
  "source": "compound $500 by 4.5% monthly over 5 years",
  "value": "$625.90",
  "type": "currency",
  "numeric_value": 625.9,
  "unit": "USD"
}

compound $500 by 4.5% monthly over 5 years reads like a sentence. No formula memorization. No getting the parentheses wrong.

The same pattern works for things losing value. Your car:

depreciate $35000 by 15% over 5 years

depreciate $35000 by 15% over ...    $15.53K

{
  "source": "depreciate $35000 by 15% over 5 years",
  "value": "$15.53K",
  "type": "currency",
  "numeric_value": 15529.69,
  "unit": "USD"
}

Beyond the Calculator #

CalcMark also has domain-specific functions for engineering and infrastructure:

read 100 MB from ssd

That computes how long it takes to read 100 MB from an SSD (0.18 seconds). It reads like English and produces real results. See the System Sizing guide for the full story on capacity planning, transfer times, and compression estimates.

NL Syntax with Variables #

NL functions work with both literal values and variable references. Define values once and refer to them by name:

yearly_storage = 796 GB
compress yearly_storage using gzip    -- variable reference
compress 796 GB using gzip            -- literal value (equivalent)

Both forms produce identical results. Use whichever reads most naturally for your document.

Quick Reference #

What to Read Next #

• Units and conversions: Understanding Measurements — quantities, fractions, napkin math, and JSON output semantics
• Engineering functions: System Sizing & Capacity Planning — rates, capacity planning, and at...per syntax
• All functions: Functions & NL Syntax — complete reference with both NL and functional forms
• Full language spec: Language Reference — percentages, rates, growth functions, and everything else