Polish UnitMath v1.18.0

Author: LJrobinson

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "unitmath"
-version = "1.4.0"
+version = "1.18.0"
 edition = "2021"
 description = "A small Rust library and CLI for unit conversions, parsing, and package math."
 license = "MIT"

Cargo.toml

@@ -1,22 +1,20 @@
 # UnitMath
 
-UnitMath is a small Rust library and dependency-free CLI for unit conversions, parsing, and package math.
+UnitMath is a small Rust library and dependency-free CLI for unit conversions, parsing, and package math. The library focuses on core typed conversions and parsers; the CLI adds convenient one-shot commands, package math commands, and batch processing for CSV and JSON Lines data.
 
-Version 1.4.0 is focused on:
+## Current Scope
 
-- Weight conversions
-- US liquid volume conversions
-- Potency conversions
+UnitMath currently supports:
+
+- Weight conversions and parsing
+- US liquid volume conversions and parsing
+- Potency conversions and parsing
 - Simple package math helpers
-- Basic string parsing for weight, volume, and potency quantities
-- Parsed conversion helpers
-- A minimal CLI
-- Optional JSON CLI output
-- Optional CSV CLI output
-- Universal CLI conversion with category inference
-- Batch CSV input mode with CSV or JSON Lines output
+- One-shot CLI conversion commands
+- Batch CLI processing from CSV, JSON Lines, files, and stdin
+- Machine-readable CLI output as JSON, CSV-style rows, JSON Lines, or JSON arrays
 
-UnitMath intentionally does not include universal library conversion, package parsing, or trait-based quantity abstractions yet.
+UnitMath intentionally keeps the public library API focused and lightweight. Higher-level features such as universal conversion, package expression parsing, batch processing, CSV/JSON formatting, and input-format handling are currently CLI-layer features, while trait-based quantity abstractions are intentionally deferred.
 
 ## Supported Units
 
@@ -72,8 +70,8 @@ assert_eq!(milligrams_per_gram, 224.0);
 let units = calculate_total_units(2.0, 12.0);
 assert_eq!(units, 24.0);
 
-let total_grams = calculate_total_quantity(10.0, 3.5);
-assert_eq!(total_grams, 35.0);
+let total_milligrams = calculate_total_quantity(24.0, 100.0);
+assert_eq!(total_milligrams, 2400.0);
 
 let parsed_weight = parse_weight("  3.5G  ")?;
 assert_eq!(parsed_weight.value, 3.5);
@@ -85,59 +83,20 @@ assert_eq!(parsed_volume.unit, VolumeUnit::FluidOunce);
 let parsed_potency = parse_potency("22.4%")?;
 assert_eq!(parsed_potency.unit, PotencyUnit::Percent);
 
-let grams = convert_parsed_weight("1000mg", WeightUnit::Gram)?;
-assert_eq!(grams, 1.0);
-
+let ounces = convert_parsed_weight("3.5g", WeightUnit::Ounce)?;
 let cups = convert_parsed_volume("8 fl oz", VolumeUnit::Cup)?;
-assert_eq!(cups, 1.0);
+let percent = convert_parsed_potency("224mg/g", PotencyUnit::Percent)?;
 
-let milligrams_per_gram =
-    convert_parsed_potency("22.4%", PotencyUnit::MilligramsPerGram)?;
-assert_eq!(milligrams_per_gram, 224.0);
-
-# Ok::<(), unitmath::UnitMathError>(())
-```
-
-## Parsing Examples
-
-```rust
-use unitmath::{parse_potency, parse_volume, parse_weight, PotencyUnit, VolumeUnit, WeightUnit};
-
-assert_eq!(parse_weight("1000 mg")?.unit, WeightUnit::Milligram);
-assert_eq!(parse_weight("1000mg")?.unit, WeightUnit::Milligram);
-assert_eq!(parse_weight(".5 g")?.value, 0.5);
-
-assert_eq!(parse_volume("1000 ml")?.unit, VolumeUnit::Milliliter);
-assert_eq!(parse_volume("8floz")?.unit, VolumeUnit::FluidOunce);
-assert_eq!(parse_volume("2 gallons")?.unit, VolumeUnit::Gallon);
-
-assert_eq!(parse_potency("22.4 %")?.unit, PotencyUnit::Percent);
-assert_eq!(parse_potency("224mg/g")?.unit, PotencyUnit::MilligramsPerGram);
-assert_eq!(
-    parse_potency("224 milligrams per gram")?.unit,
-    PotencyUnit::MilligramsPerGram
-);
+assert!(ounces > 0.0);
+assert_eq!(cups, 1.0);
+assert_eq!(percent, 22.4);
 
 # Ok::<(), unitmath::UnitMathError>(())
 ```
 
 Parsing trims whitespace, is case-insensitive, and returns `UnitMathError` for empty input, missing numbers, invalid numbers, missing units, and unknown units.
 
-## Package Helpers
-
-```rust
-use unitmath::{calculate_total_quantity, calculate_total_units};
-
-let units = calculate_total_units(5.0, 24.0);
-assert_eq!(units, 120.0);
-
-let total_milligrams = calculate_total_quantity(24.0, 100.0);
-assert_eq!(total_milligrams, 2400.0);
-```
-
-Package helpers only multiply counts by per-unit quantities. They do not parse package strings or perform unit conversion.
-
-## CLI Usage
+## CLI Examples
 
 Default CLI output is numeric-only:
 
@@ -153,90 +112,199 @@ unitmath convert "1 gallon" ml
 unitmath convert "22.4%" mg/g
 ```
 
-Add `--json` at the end to emit structured output:
+Package CLI commands perform simple multiplication without unit conversion:
 
 ```sh
-unitmath weight "3.5g" oz --json
-unitmath volume "8 fl oz" cup --json
-unitmath potency "22.4%" mg/g --json
-unitmath convert "3.5g" oz --json
+unitmath package total-units "2 x 12"
+unitmath package total-units "2,12"
+unitmath package total-quantity "10 x 3.5"
+unitmath package total-quantity "24 * 100" mg
 ```
 
-Example JSON output:
+Add `--precision <digits>` to format output values with exactly that many digits after the decimal point. Precision supports values from `0` through `12` and affects output formatting only:
 
-```json
-{"category":"weight","input":"3.5g","target_unit":"oz","value":0.12345886682353144}
+```sh
+unitmath convert "3.5g" oz --precision 4
+unitmath convert "3.5g" oz --json --precision 4
+unitmath convert "3.5g" oz --csv --precision 4
+unitmath package total-units "2 x 12" --precision 2
 ```
 
-Add `--csv` at the end to emit a header row and one data row:
+## Machine-Readable Output
+
+One-shot commands support JSON and CSV-style output:
 
 ```sh
-unitmath weight "3.5g" oz --csv
-unitmath volume "8 fl oz" cup --csv
-unitmath potency "22.4%" mg/g --csv
+unitmath convert "3.5g" oz --json
 unitmath convert "3.5g" oz --csv
+unitmath convert "3.5g" oz --csv --no-header
+unitmath convert "3.5g" oz --csv --include-header
+unitmath convert "3.5g" oz --csv --delimiter tab
+```
+
+One-shot JSON output is a single object:
+
+```json
+{"category":"weight","input":"3.5g","target_unit":"oz","value":0.12345886682353144}
 ```
 
-Example CSV output:
+One-shot CSV output includes headers by default:
 
 ```csv
 category,input,target_unit,value
 weight,3.5g,oz,0.12345886682353144
 ```
 
-Errors are written to stderr with usage guidance.
+Batch commands support CSV-style rows, JSON Lines, and JSON arrays:
 
-The `convert` command infers the category from the input and target unit. It succeeds only when exactly one category matches.
+```sh
+unitmath batch examples/conversions.csv --csv
+unitmath batch examples/conversions.csv --json
+unitmath batch examples/conversions.csv --json --json-array
+unitmath batch examples/conversions.csv --csv --delimiter tab
+unitmath batch examples/conversions.csv --csv --delimiter pipe
+```
 
-## Batch Mode
+Batch JSON output is JSON Lines by default:
 
-Batch mode reads a CSV file with these headers:
+```jsonl
+{"category":"weight","input":"1000mg","target_unit":"g","value":1,"status":"ok","error":null}
+{"category":"volume","input":"1 gallon","target_unit":"ml","value":3785.411784,"status":"ok","error":null}
+```
+
+Add `--json-array` with batch `--json` to emit one JSON array instead of JSON Lines:
+
+```json
+[{"category":"weight","input":"1000mg","target_unit":"g","value":1,"status":"ok","error":null},{"category":"volume","input":"1 gallon","target_unit":"ml","value":3785.411784,"status":"ok","error":null}]
+```
+
+CSV-style output uses commas by default. Use `--delimiter comma`, `--delimiter tab`, or `--delimiter pipe` with `--csv` to choose the output separator. Delimiter control affects output only; batch CSV input remains comma-separated.
+
+## Batch Examples
+
+Batch CSV input uses these headers:
 
 ```csv
 category,input,target_unit
 weight,1000mg,g
 volume,1 gallon,ml
 potency,22.4%,mg/g
 convert,8 fl oz,cup
+total_units,2 x 12,units
+total_quantity,24 * 100,mg
 ```
 
-Supported batch categories are `weight`, `volume`, `potency`, and `convert`. Surrounding whitespace in header names and category values is ignored.
+Supported batch categories are `weight`, `volume`, `potency`, `convert`, `total_units`, and `total_quantity`. Surrounding whitespace in header names and category values is ignored. Package rows do simple multiplication without unit conversion; `target_unit` is preserved as an output label.
 
-Batch mode requires an explicit output format:
+JSON Lines batch input uses one flat object per non-empty line with string fields for `category`, `input`, and `target_unit`:
+
+```jsonl
+{"category":"weight","input":"1000mg","target_unit":"g"}
+{"category":"volume","input":"1 gallon","target_unit":"ml"}
+{"category":"potency","input":"22.4%","target_unit":"mg/g"}
+{"category":"convert","input":"8 fl oz","target_unit":"cup"}
+{"category":"total_units","input":"2 x 12","target_unit":"units"}
+{"category":"total_quantity","input":"24 * 100","target_unit":"mg"}
+```
+
+Copy-paste batch commands:
 
 ```sh
-unitmath batch conversions.csv --csv
-unitmath batch conversions.csv --json
+unitmath batch examples/conversions.csv --csv
+unitmath batch examples/conversions.csv --json
+unitmath batch examples/conversions.csv --json --json-array
+unitmath batch examples/conversions.jsonl --json
+unitmath batch examples/conversions.jsonl --csv
+unitmath batch examples/conversions.csv --csv --precision 2
 ```
 
-CSV batch output includes one result row per input row:
+Omit the file path to read from stdin. Stdin defaults to CSV unless `--input-format jsonl` or `--input-json` is provided:
 
-```csv
-category,input,target_unit,value,status,error
-weight,1000mg,g,1,ok,
-volume,1 gallon,ml,3785.411784,ok,
+```sh
+cat examples/conversions.csv | unitmath batch --csv
+cat examples/conversions.csv | unitmath batch --json
+cat examples/conversions.jsonl | unitmath batch --input-format jsonl --csv
+cat examples/conversions.jsonl | unitmath batch --input-format jsonl --json
 ```
 
-JSON batch output is JSON Lines:
+Batch file input is auto-detected from the file extension:
 
-```jsonl
-{"category":"weight","input":"1000mg","target_unit":"g","value":1,"status":"ok","error":null}
-{"category":"volume","input":"1 gallon","target_unit":"ml","value":3785.411784,"status":"ok","error":null}
+- `.csv` reads CSV input
+- `.jsonl` reads JSON Lines input
+- `.ndjson` reads JSON Lines input
+
+Extension matching is case-insensitive. Files with unknown or missing extensions require `--input-format csv` or `--input-format jsonl`:
+
+```sh
+unitmath batch examples/conversions.csv --input-format csv --csv
+unitmath batch examples/conversions.jsonl --input-format jsonl --json
+unitmath batch examples/conversions.jsonl --input-format jsonl --json --json-array
 ```
 
-Rows with errors are included in the output with `status` set to `error`; batch processing continues after row-level failures.
+The older `--input-json` flag remains available as a compatibility alias for `--input-format jsonl`:
+
+```sh
+unitmath batch examples/conversions.jsonl --input-json --json
+cat examples/conversions.jsonl | unitmath batch --input-json --json
+```
+
+Use `--out <path>` to write batch results to a file instead of stdout:
+
+```sh
+unitmath batch examples/conversions.csv --csv --out results.csv
+unitmath batch examples/conversions.csv --json --out results.jsonl
+unitmath batch examples/conversions.csv --json --json-array --out results.json
+unitmath batch examples/conversions.csv --csv --delimiter tab --out results.tsv
+cat examples/conversions.csv | unitmath batch --csv --out results.csv
+```
+
+## Dirty Data Workflows
+
+Rows with conversion errors are included in batch output with `status` set to `error`; batch processing continues after row-level failures. Use filters and summaries to triage mixed-quality files:
+
+```sh
+unitmath batch examples/conversions.csv --csv --errors-only
+unitmath batch examples/conversions.csv --json --errors-only
+unitmath batch examples/conversions.csv --csv --ok-only
+unitmath batch examples/conversions.csv --csv --summary
+unitmath batch examples/conversions.csv --csv --errors-only --summary
+unitmath batch examples/conversions.csv --csv --errors-only --out errors.csv
+unitmath batch examples/conversions.csv --json --ok-only --out clean.jsonl
+```
+
+`--summary` writes counts to stderr and never changes stdout or output file schemas:
+
+```text
+summary: processed=6 ok=6 errors=0 emitted=6
+summary: processed=6 ok=5 errors=1 emitted=1 output=errors.csv
+```
+
+Summary counts are:
+
+- `processed`: all parsed batch result rows before filtering
+- `ok`: successful rows before filtering
+- `errors`: error rows before filtering
+- `emitted`: rows emitted after `--errors-only` or `--ok-only`
 
 ## Examples
 
+Library examples:
+
 ```sh
 cargo run --example basic_weight
 cargo run --example basic_volume
 cargo run --example basic_potency
 ```
 
-## Roadmap After v1.0.0
+Batch sample files:
+
+- `examples/conversions.csv`
+- `examples/conversions.jsonl`
+
+## Roadmap
 
 - Additional parsers
-- Package parsing
 - More unit families
+- Richer package parsing as a library API
 - Broader CLI ergonomics
+- Trait-based quantity abstractions when the core API shape is clear

README.md

@@ -0,0 +1,7 @@
+category,input,target_unit
+weight,1000mg,g
+volume,1 gallon,ml
+potency,22.4%,mg/g
+convert,8 fl oz,cup
+total_units,2 x 12,units
+total_quantity,24 * 100,mg

examples/conversions.csv

@@ -0,0 +1,6 @@
+{"category":"weight","input":"1000mg","target_unit":"g"}
+{"category":"volume","input":"1 gallon","target_unit":"ml"}
+{"category":"potency","input":"22.4%","target_unit":"mg/g"}
+{"category":"convert","input":"8 fl oz","target_unit":"cup"}
+{"category":"total_units","input":"2 x 12","target_unit":"units"}
+{"category":"total_quantity","input":"24 * 100","target_unit":"mg"}