blob: ebadaec21da3650d8609ace84285087c94a26b1e (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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.
## Examples
### 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
|
