Metadata-Version: 2.4
Name: calced
Version: 0.5.0
Summary: A notepad calculator that evaluates expressions in text files
Project-URL: Homepage, https://calced.karl.berlin
Project-URL: Repository, https://github.com/karlb/calced
Project-URL: Issues, https://github.com/karlb/calced/issues
Author-email: Karl Bartel <karl@karl.berlin>
License-Expression: MIT
License-File: LICENSE
Keywords: calculator,cli,math,notepad
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

  calced logo

# calced

A notepad calculator that evaluates math expressions in plain text files. Available as a **CLI tool** and a **web app**.

## Why calced?

Spreadsheets are overkill for quick calculations. REPLs lose context once you close them. calced keeps your math in plain text files where results stay next to the expressions, files can be versioned and diffed, and you use whatever editor you want.

Compared to other notepad calculators:

- **Tiny, no dependencies** — the CLI is a single 47KB Python file (stdlib only), the web app is a single 52KB HTML file. No build step, no node_modules, no Electron.
- **Works offline** — both versions run entirely locally. Save the HTML file or install the CLI and you're set.
- **Both CLI and web** — same syntax, same test suite, but well adapted to each environment.
- **Stable results** — shared web URLs include the major version, so they won't break on updates. Files store results inline. All configuration is inside the documents.

## Web

[Open the web app](https://calced.karl.berlin) in a browser.

## CLI

```
calced <file>           # evaluate and update file in place
calced -s <file>        # print result to stdout (don't modify file)
calced -w <file>        # watch for changes and auto-update
calced -w -s <file>     # watch and print (clears screen on change)
calced -u <file>        # print shareable web URL
```

### Installation

Requires Python 3.9+. Any typical Python install method works (`pip install calced`, etc.).

```sh
# Install as a CLI tool
uv tool install calced

# Or run without installing
uvx calced <file>

# Or just grab the single-file script and run it directly
python calced.py <file>
```

## How it works

Write math anywhere in a plain text file. Results are appended inline as `# => result` comments. Non-math lines are left untouched.


```
rent 1500                               # => 1_500 │
groceries 200 + 150                     # =>   350 │
utilities 80 + 45 + 30                  # =>   155 │
total                                   # => 2_005 ┘
```
[Try in web app](https://calced.karl.berlin/0/#K0rNK1EwNDUw4Eovyk9OLcpMLVYwMjBQ0AYJcpWWZOZkloDELEBCJqZAwtiAqyS_JDGHCwA)

Results are aligned and updated in place each time you run the CLI (or automatically in watch mode), or live as you type in the web app.

## Features

### Basic arithmetic

```
2 + 3                                   # =>     5
10 * (4 + 6)                            # =>   100
2 ^ 10                                  # => 1_024
17 % 5                                  # =>     2
```
[Try in web app](https://calced.karl.berlin/0/#M1LQVjDmMjRQ0FLQMAGyzTS5jBTiFAwNuAzNFVQVTLkA)

### Variables

```
income = 5000                           # => 5_000
tax_rate = 22%                          # =>     0.22
tax = income * tax_rate                 # => 1_100
after_tax = income - tax                # => 3_900
```
[Try in web app](https://calced.karl.berlin/0/#y8xLzs9NVbBVMDUwMOAqSayIL0osAfGNjFRBXCArE6JESwEmy5WYVpJaFI8iqwuS5QIA)

### Percentages

```
50% of 300                              # => 150
200 + 15%                               # => 230
200 - 10%                               # => 180
10 as % of 50                           # =>  20
```
[Try in web app](https://calced.karl.berlin/0/#MzVQVchPUzA2MOAyMjBQ0FYwNFUFs3QVDA1UuQwNFBKLFcBKTA24AA)

### SI prefixes

```
1k                                      # =>         1_000
1M                                      # =>     1_000_000
1.5G                                    # => 1_500_000_000
500n * 2                                # =>             0.000001
```
[Try in web app](https://calced.karl.berlin/0/#M8zmMvTlMtQzdecyNTDIU9BSMOICAA)

Supported: `k`/`K` (kilo), `M` (mega), `G` (giga), `T` (tera), `P` (peta), `E` (exa), `m` (milli), `u`/`μ` (micro), `n` (nano), `p` (pico), `f` (femto), and more.

### Unit conversions


```
5 km in miles                           # =>     3.106855961
100 C in F                              # =>   212
1 gib in mib                            # => 1_024
60 min in hr                            # =>     1
1 gal in l                              # =>     3.78541
```
[Try in web app](https://calced.karl.berlin/0/#M1XIzlXIzFPIzcxJLeYyNDBQcAZx3bgMFdIzkyAySVxmBkAqD8TLKALJJOaA2DlcAA)

Supported dimensions: length, mass, temperature, data, time, volume. Use `in` or `to`.

### Rate conversions

Define exchange rates (or any conversion rate) with `@rate`, then convert using `in`.


```
@rate USD/EUR = 0.92
100 USD in EUR                          # => 92
50 EUR in USD                           # => 54.34782609
```
[Try in web app](https://calced.karl.berlin/0/#cyhKLElVCA120XcNDVKwVTDQszTiMjQwAAkpZOYpAEW5TA1AFIgHFOQCAA)

### Functions

```
sqrt(16)                                # => 4
round(3.14159, 2)                       # => 3.14
min(5, 2, 8)                            # => 2
max(1, 9, 3)                            # => 9
log10(1000)                             # => 3
sin(0)                                  # => 0
```
[Try in web app](https://calced.karl.berlin/0/#Ky4sKtEwNNPkKsovzUvRMNYzNDE0tdRRMNLkys3M0zAFsnQULICcxAoNQx0FoIyxJldOfrqhgYahgYGBJlcxUBWQAgA)

Available: `sqrt`, `abs`, `floor`, `ceil`, `round`, `log`, `log2`, `log10`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `exp`, `min`, `max`

### Constants


```
pi * 2                                  # => 6.283185307
e ^ 1                                   # => 2.718281828
```
[Try in web app](https://calced.karl.berlin/0/#K8hU0FIw4kpViFMw5AIA)

### Date arithmetic

```
2025-01-15 + 3 days                     # => 2025-01-18
2025-01-31 + 1 month                    # => 2025-02-28
2025-03-01 - 2025-01-01                 # => 59
```
[Try in web app](https://calced.karl.berlin/0/#MzIwMtU1MNQ1NFXQVjBWSEmsLOYygooZGwLFDBVy8_NKMqCCxkBxBV0FmAoDQy4A)

Supports `days`, `weeks`, `months`, `years`. Subtracting two dates returns the difference in days. `today`, `tomorrow`, and `yesterday` work as keywords.

### Totals

The `total` (or `sum`) keyword sums all numeric results since the last `#` heading or start of file.


```
rent 1500                               # => 1_500 │
groceries 350                           # =>   350 │
utilities 155                           # =>   155 │
total                                   # => 2_005 ┘
```
[Try in web app](https://calced.karl.berlin/0/#K0rNK1EwNDUw4Eovyk9OLcpMLVYwNjXgKi3JzMksAfEMTU25SvJLEnO4AA)

Blank lines are ignored in the total; headings reset it.

### Number formats

Numbers can be written with commas or underscores as separators (`1,000` or `1_000`), in hex/binary/octal (`0xFF`, `0b1010`, `0o77`), or in scientific notation (`1.5e3`).

### Trailing annotations

Parenthetical notes after an expression are ignored:


```
celo_price = 0.08 (see http://coinmarketcap.com)  # => 0.08
```
[Try in web app](https://calced.karl.berlin/0/#S07NyY8vKMpMTlWwVTDQM7BQ0ChOTVXIKCkpsNLXT87PzMtNLMpOLUlOLNBLzs_V5AIA)

### Format directives

Control output formatting with `@format` and `@separator` directives. These apply to all subsequent lines until changed.


```
1000000                                 # => 1_000_000
@format = fixed(2)
1000000                                 # => 1_000_000.00
@format = scientific
1000000                                 # => 1.00e+06
@separator = comma
@format = minSig(3)
1000000                                 # => 1,000,000
```
[Try in web app](https://calced.karl.berlin/0/#MzQAAy6HtPyi3MQSBVuFtMyK1BQNI00uQwyp4uTM1LySzLTMZIRkcWpBYlFiSX4RUD45Pzc3EUl9bmZecGa6hjHCLAA)

