diff options
Diffstat (limited to 'docs/cli-usage.md')
| -rw-r--r-- | docs/cli-usage.md | 76 |
1 files changed, 10 insertions, 66 deletions
diff --git a/docs/cli-usage.md b/docs/cli-usage.md index b551083..0bbb938 100644 --- a/docs/cli-usage.md +++ b/docs/cli-usage.md @@ -1,6 +1,6 @@ # CLI Usage -gt supports several invocation modes for different use cases: single-expression evaluation, interactive REPL, piping, and stdin redirection. +gt supports several invocation modes: single-expression evaluation, interactive REPL, piping, and stdin redirection. ## Invocation Modes @@ -14,7 +14,7 @@ gt '20% of 150' # → 30 gt '100Mbps @Gbps convert' # → 1 ``` -This is the primary mode for scripts, one-off calculations, and CI pipelines. Each invocation starts with a fresh state — no variables, no history, no persistent settings. +This is the primary mode for scripts, one-off calculations, and CI pipelines. Each invocation starts fresh — no variables, no history. ### REPL Mode @@ -26,7 +26,7 @@ gt This starts the interactive Read-Eval-Print Loop with command history, tab completion, and persistent variable storage. See [repl-mode.md](repl-mode.md) for full details. -When stdin is not a terminal (e.g., piped input), gt falls back to single-command mode instead of starting the REPL. +When stdin is not a terminal (e.g., piped input), gt falls back to single-command mode. ### Pipe Mode @@ -38,18 +38,15 @@ echo '20% of 150' | gt # → 30 echo '100kmh @mph convert' | gt # → 62.13711922 ``` -gt reads from stdin, trims whitespace, tries RPN parsing first, then falls back to percentage calculation. This makes it easy to integrate gt into shell pipelines. +gt reads from stdin, trims whitespace, tries RPN parsing first, then falls back to percentage calculation. ### Stdin Redirection -Redirect a file or use `/dev/stdin`: - ```bash gt < input.txt -gt /dev/stdin < input.txt ``` -The `readStdin()` function in `cmd/gt/main.go` uses `os.ReadFile("/dev/stdin")` for full reads, with a 4096-byte buffer fallback if `/dev/stdin` is unavailable on the platform. +gt uses `os.ReadFile("/dev/stdin")` for full reads, with a 4096-byte buffer fallback if `/dev/stdin` is unavailable. ### Empty Input @@ -71,8 +68,6 @@ Error: no input provided ### Version -Print the current version: - ```bash $ gt version v0.4.2 @@ -89,14 +84,7 @@ $ gt -h Error: rpn fallback failed for input "-h": perc: unable to parse input "-h": unknown error ``` -To see usage information, provide empty input or just run `gt` with no stdin: - -```bash -$ echo '' | gt -Usage: gt <calculation> - gt version -... -``` +To see usage information, provide empty input or just run `gt` with no stdin. ### `--log` Flag @@ -110,7 +98,7 @@ See [repl-mode.md](repl-mode.md) for details on session logging. ## Boolean Coercion -gt treats `true` and `false` as first-class literals on the RPN stack. Comparison operators (`==`, `!=`, `>`, `<`, `>=`, `<=`) produce boolean values. Booleans coerce to numbers when used in arithmetic: `true` is `1`, `false` is `0`. +gt treats `true` and `false` as first-class literals on the RPN stack. Comparison operators produce boolean values. Booleans coerce to numbers in arithmetic: `true` is `1`, `false` is `0`. ### Boolean Literals @@ -125,27 +113,19 @@ gt 'false' # → false gt '5 5 ==' # → true gt '5 6 ==' # → false gt '5 3 >' # → true -gt '3 5 <' # → true -gt '5 5 >' # → false ``` ### Boolean-Arithmetic Coercion -When a boolean is used with an arithmetic operator, it is coerced to `1` (true) or `0` (false): - ```bash gt 'true true +' # → 2 (1 + 1) gt 'true false +' # → 1 (1 + 0) gt 'false false +' # → 0 (0 + 0) gt 'true 2 *' # → 2 (1 * 2) -gt 'false 1 +' # → 1 (0 + 1) -gt 'false 0 +' # → 0 (0 + 0) ``` ### Mixed Boolean-Arithmetic Expressions -Use comparison results directly in arithmetic without explicit conversion: - ```bash gt '5 3 == 1 +' # → 1 (false + 1 = 0 + 1) gt '5 5 == 10 *' # → 10 (true * 10 = 1 * 10) @@ -153,20 +133,12 @@ gt '5 5 == 10 *' # → 10 (true * 10 = 1 * 10) ### Comparing Booleans to Numbers -Equality comparisons work between booleans and their numeric equivalents: - ```bash gt 'true 1 ==' # → true (1 == 1) gt 'false 0 ==' # → true (0 == 0) gt 'true 0 ==' # → false (1 != 0) ``` -### Implementation Details - -Boolean values are stored as a special `Float` variant (or `Rat` in rational mode) with an `isBool` flag. The `Float64()` method coerces `true` to `1` and `false` to `0` automatically. The `String()` method returns `"true"` or `"false"` instead of a numeric representation, preserving readability on the stack. - -See `internal/rpn/number.go` for the `Float` and `Rat` boolean implementations, and `internal/rpn/rpn_parse.go` for the `pushLiteral()` function that recognizes `true` and `false` tokens. - ## Exit Codes | Condition | Exit Code | @@ -175,14 +147,12 @@ See `internal/rpn/number.go` for the `Float` and `Rat` boolean implementations, | Error (parse failure, invalid expression, etc.) | 1 | | Empty input (no TTY) | 1 | -Error messages are printed to stdout with the prefix `Error:` followed by a newline and the result. +Error messages are printed to stdout with the prefix `Error:`. -## Practical Use Cases +## Examples ### In Shell Scripts -Embed calculations directly in scripts: - ```bash THRESHOLD=$(gt '100Mbps 50 /') if [ "$THRESHOLD" -gt 1000 ]; then @@ -192,8 +162,6 @@ fi ### In CI Pipelines -Validate calculations in build steps: - ```yaml - name: Check bandwidth math run: | @@ -203,40 +171,16 @@ Validate calculations in build steps: ### In Pipes -Combine with other tools: - ```bash cat sizes.txt | xargs -I{} gt '{} @GB convert' -find . -type f -exec wc -c {} + | awk '{print $1}' | xargs -I{} gt '{} @MiB convert' ``` ### Quick Conversions at the Prompt ```bash -# Travel planning gt '500mi @km convert' # → 804.672 - -# Data transfer -gt '10GB 2hr /' # → transfer rate - -# Weight -gt '150lb @kg convert' # → 68.04 - -# Percentage gt '15% of 899' # → discount amount -``` - -### Conditional Logic - -Use boolean coercion for inline conditionals: - -```bash -# Check if a value meets a threshold gt '75 80 >' # → false (75 < 80) -gt '85 80 >' # → true (85 > 80) - -# Combine with arithmetic -gt '75 80 > 1 -' # → 1 (not greater, so 1 - false = 1 - 0 = 1) ``` ## Summary of Modes @@ -245,6 +189,6 @@ gt '75 80 > 1 -' # → 1 (not greater, so 1 - false = 1 - 0 = 1) |------|---------|-------|----------| | Single-expression | `gt '3 4 +'` | Fresh per invocation | Scripts, CI, one-off math | | REPL | `gt` (with TTY) | Persistent (saved to disk) | Interactive exploration | -| Pipe | `echo '3 4 +' \| gt` | Fresh per invocation | Pipelines, xargs | +| Pipe | `echo '3 4 +' | gt` | Fresh per invocation | Pipelines, xargs | | Stdin redirect | `gt < file.txt` | Fresh per invocation | Batch processing | | Version | `gt version` | N/A | Checking installed version | |