diff options
| -rw-r--r-- | docs/metrics.md | 205 |
1 files changed, 205 insertions, 0 deletions
diff --git a/docs/metrics.md b/docs/metrics.md new file mode 100644 index 0000000..4ae2732 --- /dev/null +++ b/docs/metrics.md @@ -0,0 +1,205 @@ +# Metrics System + +gt attaches units of measurement (metrics) to numbers. Every number on the stack carries a metric — the default is `Cool` (unitless). Metrics enable automatic unit conversion, metric-aware arithmetic, and cross-category inference. + +## Suffix Notation + +Attach a unit directly to a number with no space: + +```bash +gt '100Mbps' # 100 megabits per second +gt '5GB' # 5 gigabytes +gt '1hr' # 1 hour +gt '100kmh' # 100 kilometers per hour +``` + +## Available Metric Categories + +### DataRate + +| Unit | Description | +|------|-------------| +| `bps` | Bits per second (base) | +| `Kbps` | Kilobits per second | +| `Mbps` | Megabits per second | +| `Gbps` | Gigabits per second | +| `Tbps` | Terabits per second | + +### DataSize + +| Unit | Description | +|------|-------------| +| `bits` / `bytes` | Base units | +| `KB` / `MB` / `GB` / `TB` / `PB` | SI (1000-based) | +| `KiB` / `MiB` / `GiB` / `TiB` / `PiB` | IEC (1024-based) | + +### Time + +| Unit | Description | +|------|-------------| +| `ms` | Milliseconds | +| `s` | Seconds (base) | +| `min` | Minutes | +| `hr` | Hours | +| `day` | Days | + +### Weight + +| Unit | Description | +|------|-------------| +| `mg` | Milligrams | +| `g` | Grams (base) | +| `kg` | Kilograms | +| `lb` | Pounds | +| `oz` | Ounces | +| `ton` | Tons | + +### Speed + +| Unit | Description | +|------|-------------| +| `mps` | Meters per second (base) | +| `kmh` | Kilometers per hour | +| `mph` | Miles per hour | +| `knots` | Knots | + +### Distance + +| Unit | Description | +|------|-------------| +| `m` | Meters (base) | +| `km` | Kilometers | +| `mi` | Miles | +| `ft` | Feet | +| `in` | Inches | +| `nm` | Nautical miles | + +### Universal + +| Unit | Description | +|------|-------------| +| `Cool` | Default unitless metric | + +## Unit Conversion + +Convert between units using `@` prefix and `convert`: + +```bash +gt '1000Mbps @Gbps convert' # → 1 +gt '1hr @min convert' # → 60 +gt '1km @mi convert' # → 0.6213711922 +gt '1TB @GB convert' # → 1000 +gt '1KiB @bytes convert' # → 1024 +``` + +## Metric-Aware Arithmetic + +### Addition and Subtraction + +Require compatible categories. Mixed units are automatically converted: + +```bash +gt '100Mbps 50Mbps +' # → 150 (same category) +gt '1km 500m +' # → 1.5 (auto-convert to km) +gt '5 100Mbps +' # → 105 (Cool absorbs into Mbps) +gt '100Mbps 2hr +' # ERROR: incompatible categories +``` + +### Multiplication + +Supports cross-category inference: + +```bash +gt '100Mbps 1hr *' # → 3.6e+11 (rate × time = data size) +gt '100kmh 1hr *' # → 100000 (speed × time = distance) +``` + +### Division + +Also supports cross-category inference: + +```bash +gt '10GB 2hr /' # → 11111111.11 (data / time = rate) +gt '1km 1s /' # → 1000 (distance / time = speed) +``` + +### Power + +Always returns `Cool` (unitless): + +```bash +gt '2hr 3 ^' # → 8 (not 8hr³) +``` + +## SI vs IEC Prefix Modes + +Data size prefixes use SI (1000-based) by default. Switch to IEC (1024-based) in REPL mode: + +``` +> metric decimal set # SI mode +prefix mode: SI +> 1GB @MB convert +1000 +> metric binary set # IEC mode +prefix mode: IEC +> 1GB @MB convert +1024 +``` + +In single-command mode, SI is always used. + +## Practical Use Cases + +### Bandwidth Planning + +```bash +gt '1Gbps 1000 /' # Gbps to Mbps: 1000 +gt '100Mbps 1hr *' # Bits transferred in 1 hour: 3.6e+11 +gt '500GB 1hr /' # Required throughput: large bps value +``` + +### Travel Calculations + +```bash +gt '60mph @kmh convert' # mph to km/h: 96.56 +gt '500mi @km convert' # miles to km: 804.67 +gt '1000km 60mph /' # Travel time: hours (after conversion) +``` + +### Weight Conversions + +```bash +gt '70kg @lb convert' # kg to lbs: 154.32 +gt '250lb @kg convert' # lbs to kg: 113.4 +``` + +## Metric Commands + +```bash +gt 'metric show' # Show metric info for top of stack +gt 'metric list' # List all categories +gt 'metric DataRate' # List metrics in a category +gt '100Mbps 1Gbps metric compatible' # Check compatibility +``` + +## Custom Metrics + +Define your own units: + +```bash +gt 'custom define foobar 42 Custom' +# → defined custom metric "foobar" (factor: 42, category: Custom) + +gt 'custom define foobar 42 Custom 10foobar 5foobar +' +# → 15 + +gt 'custom define foobar 42 Custom custom undefine foobar' +# → removed custom metric "foobar" +``` + +## Notes + +- Numbers without suffixes default to `Cool` (unitless) +- Metric names are case-insensitive (`100mbps` = `100Mbps`) +- Metric-aware comparison operators work with compatible categories +- Incompatible category operations produce clear error messages |