zone 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48ffc5f23c1380e609e45c5f5a934b73663f697ca2a42326db020abafe1b73d4
-  data.tar.gz: d0c55e0563de05b15b01ca129476f59fe2c61129c997dc3c505bf7f9c40d8b5c
+  metadata.gz: 8be1f2c6eebecd142bfd5ef95bd1fefbe02a4cc2e873caa61f7ddeb837b28eff
+  data.tar.gz: a318b8c2d32fd77f89aa2aacdf39eb01ee04218c4a5bd3e68312dcf24bbe2a67
 SHA512:
-  metadata.gz: a9dd64f6fe00be2fd8999e6dbc20310c266ef2089ce81e367c34cc7f39e38fc9cf1d70471eff3f70f18d2ad0e37d4b68d3fc57019cd1ee289135bb7751864a10
-  data.tar.gz: 6c99b5f7ca51350827e6bea1c7dee0b0226069679f79c1f16685517ad0b7565b1cea9ecc89a7c556ae0121ec20998ff71126328c905e13357aa6f14832050156
+  metadata.gz: 5ed2ddc6514b9b5de43eafb0ebdde0b4b841d0ef94446dd2b1a794abe858dd443755699ac92ee070856f461e9e7c8fd72e018822989faf246cbe0b30eba84d15
+  data.tar.gz: 91b2edc5636d550b133de5d78372ae3b2e5103a9fd56cce8a28c719ef4e655d54a52f4db1eee278be6a61bccd22ac35aa12e521df1258dc7d7c6ab317c473f18

data/CHANGELOG.md

@@ -1,5 +1,82 @@
 ## [Unreleased]
 
+### Added
+
+#### --color Flag
+Added `--color` flag with three modes for controlling ANSI color output:
+- `auto` (default): Colors when stdout is a TTY device
+- `always`: Always show colors (useful for piping to `less -R`)
+- `never`: Never show colors (useful for scripting and CI)
+
+Both pattern mode and field mode now respect this setting and colorize converted timestamps in cyan.
+
+#### Pretty Format Variants
+Implemented `-p [STYLE]` / `--pretty [STYLE]` with three preset formats:
+- `-p 1`: `Jan 15, 2025 - 10:30 AM EST` (12-hour with AM/PM) - default
+- `-p 2`: `Jan 15, 2025 - 22:30 EST` (24-hour for international users)
+- `-p 3`: `2025-01-15 22:30 EST` (ISO-style compact, sortable)
+
+All three formats include the year and timezone abbreviation, emphasizing zone's core conversion feature over simple formatting.
+
+### Changed
+
+#### New Defaults for Better UX
+- **Default format**: Changed from ISO8601 to pretty format 1 (12-hour with AM/PM)
+- **Default timezone**: Changed from UTC to local timezone
+
+These changes give new users immediate visual feedback, showing the tool's value on first use. Users running `zone "2025-01-15T10:30:00Z"` now see their local time in a readable format instead of unchanged ISO8601.
+
+#### Updated Pattern Matching
+- Added patterns for all three pretty output formats (P03-P05)
+- Renumbered unix timestamp pattern to P06
+- Renumbered relative time pattern to P07
+- Zone maintains full idempotency: can parse all its own output formats
+
+### Technical Details
+
+**Files Modified:**
+- `lib/zone/timestamp.rb`: Updated `to_pretty(style)` to accept style parameter (1/2/3)
+- `lib/zone/timestamp_patterns.rb`: Added P03-P05 patterns for pretty formats, updated validation
+- `lib/zone/cli.rb`:
+  - Added `--color` option with auto/always/never modes
+  - Added `colorize(stream)` helper method
+  - Changed default timezone from UTC to local
+  - Changed default format from ISO8601 to pretty1
+  - Updated `determine_format_method` to handle pretty style variants
+  - Added color support to field mode output via `sub()` replacement
+- `README.md`: Updated all examples, options, and documentation
+
+**Backward Compatibility:**
+- This is a **breaking change** for scripts that relied on default ISO8601/UTC output
+- Users who want the old behavior should explicitly specify `--iso8601 --utc`
+- The `--pretty` flag behavior changed from a boolean to accepting an optional integer style
+
+**Testing Verified:**
+- ✓ All three pretty formats produce correct output
+- ✓ Default behavior shows pretty1 with local timezone
+- ✓ Color modes work correctly (auto/always/never)
+- ✓ Field mode colorizes transformed timestamps
+- ✓ Idempotency maintained: zone can parse its own output
+- ✓ Pattern matching recognizes all zone output formats
+
+### Rationale
+
+**Why these three formats?**
+
+1. **Format 1 (12hr)**: Most readable for North American users, matches human conversation style
+2. **Format 2 (24hr)**: International standard, technical contexts, no AM/PM ambiguity
+3. **Format 3 (ISO-compact)**: Sortable, structured, good for logs and data processing
+
+All formats prioritize **conversion** (showing timezone) over pure **formatting** (date-only output), aligning with the tool's name and purpose.
+
+**Why default to local timezone?**
+
+The principle of least surprise: users running timezone conversion tools expect to see their local time. UTC is correct for APIs and storage, but humans think in local time. Power users who need UTC will specify `--utc` explicitly.
+
+**Why default to pretty format?**
+
+Immediate visual feedback shows the tool working. Seeing "Jan 15, 2025 - 10:30 AM EST" is instantly recognizable as a timestamp conversion. ISO8601 output looks identical to input for many timestamps, giving no feedback that anything happened.
+
 ## [0.1.0] - 2025-11-04
 
 - Initial release

data/README.md

@@ -3,18 +3,22 @@
 Timezone conversion and datetime formatting for the command line
 
 ```bash
+# Convert to your local timezone (default behavior)
+zone 2025-11-05T02:40:32+00:00
+# => Nov 05, 2025 - 9:40 PM EST
+
 # Fuzzy timezone matching
 zone --zone tokyo 2025-11-05T02:40:32+00:00
-# => 2025-11-05T11:40:32+09:00
+# => Nov 05, 2025 - 11:40 AM JST
 
-# Process CSV timestamps
-cat data.csv | zone --index 3 --zone pacific --pretty
+# Process CSV timestamps (field mode)
+cat data.csv | zone --field 3 --delimiter ',' --zone pacific
 # => customer,purchase_date,amount
-# => alice,42.00,Nov 04 - 06:40 PM PST
+# => alice,42.00,Nov 04, 2025 - 6:40 PM PST
 
-# Make logs readable
-tail -f app.log | zone --pretty --zone local
-# => Nov 04 - 09:15 PM EST [ERROR] Database connection timeout
+# Make logs readable (pattern mode - default)
+tail -f app.log | zone
+# => Nov 04, 2025 - 9:15 PM EST [ERROR] Database connection timeout
 ```
 
 ## Installation
@@ -29,21 +33,62 @@ Or with Bundler:
 bundle add zone
 ```
 
+## How It Works
+
+Zone operates in two modes:
+
+**Pattern Mode (Default)**: Finds and converts timestamps in arbitrary text. Zone automatically detects timestamps using smart regex patterns and updates them in place. This is like `bat` for timestamps - text goes in, formatted timestamps come out.
+
+```bash
+echo "Event at 2025-01-15T10:30:00Z completed" | zone --pretty
+# => Event at Jan 15, 2025 - 10:30 AM UTC completed
+```
+
+**Field Mode (Explicit)**: Splits lines by delimiter, converts a specific field, then rejoins. Use this for structured data like CSV or TSV files.
+
+```bash
+echo "alice,1736937000,active" | zone --field 2 --delimiter ',' --pretty
+# => alice,Jan 15, 2025 - 10:30 AM UTC,active
+```
+
+Field mode requires both `--field` and `--delimiter` flags.
+
+**Idempotency**: Zone can parse its own output formats, so you can pipe zone output back through zone:
+
+```bash
+zone "2025-01-15T10:30:00Z" --pretty | zone --unix
+# => 1736937000
+```
+
 ## Usage
 
 Convert timezones:
 
 ```bash
 zone --zone 'New York' '2025-11-05T02:40:32+00:00'
-# => 2025-11-04T21:40:32-05:00
+# => Nov 04, 2025 - 9:40 PM EST
 ```
 
 Change formats:
 
 ```bash
-zone --unix 'Nov 04 - 06:42 PM PST'
-# => 1730775720
+# Pretty format 1: 12-hour with AM/PM (default)
+zone -p 1 '2025-01-15T10:30:00Z'
+# => Jan 15, 2025 - 10:30 AM UTC
+
+# Pretty format 2: 24-hour
+zone -p 2 '2025-01-15T10:30:00Z'
+# => Jan 15, 2025 - 10:30 UTC
+
+# Pretty format 3: ISO-compact
+zone -p 3 '2025-01-15T10:30:00Z'
+# => 2025-01-15 10:30 UTC
 
+# Unix timestamp
+zone --unix '2025-01-15T10:30:00Z'
+# => 1736937000
+
+# Custom format
 zone --strftime '%Y-%m-%d %H:%M' '2025-11-05T02:40:32+00:00'
 # => 2025-11-05 02:40
 ```
@@ -51,11 +96,15 @@ zone --strftime '%Y-%m-%d %H:%M' '2025-11-05T02:40:32+00:00'
 Process structured data:
 
 ```bash
-# Convert column 2, auto-detect delimiter
-cat events.csv | zone --index 2 --zone UTC
+# Convert column 2 with explicit delimiter
+cat events.csv | zone --field 2 --delimiter ',' --zone UTC
+
+# Skip header row, use tab delimiter
+zone --field 2 --delimiter '\t' --headers < data.tsv
 
-# Skip header row
-zone --headers --delimiter '\t' < data.tsv
+# Regex delimiter (outputs as tabs)
+echo "alice    1736937000    active" | zone --field 2 --delimiter '/\s+/' --pretty
+# => alice	Jan 15, 2025 - 10:30 AM UTC	active
 ```
 
 Multiple timestamps:
@@ -71,43 +120,89 @@ zone 1730772120 1730858520 1730944920 --zone tokyo --pretty
 
 **Output Formats**
 
-- `--iso8601` - ISO 8601 format (default)
+- `-p, --pretty [STYLE]` - Pretty format (1=12hr, 2=24hr, 3=ISO-compact, default: 1)
+- `--iso8601` - ISO 8601 format
 - `--unix` - Unix timestamp
-- `--pretty` - Human-readable (e.g., "Nov 04 - 06:40 PM PST")
-- `--strftime FORMAT` - Custom format
+- `--strftime FORMAT` - Custom strftime format
 
 **Timezones**
 
-- `--zone TZ` - Convert to timezone (fuzzy matching)
+- `--zone TZ` - Convert to timezone (fuzzy matching, default: local)
 - `--utc` - Convert to UTC
-- `--local` - Convert to local time
+- `--local` - Convert to local time (default)
 
 **Data Processing**
 
-- `--index N` - Column to convert (default: 1)
-- `--delimiter PATTERN` - Field separator (auto-detected)
-- `--headers` - Skip first line
+- `--field N` - Field index or name to convert (requires --delimiter)
+- `--delimiter PATTERN` - Field separator (string or /regex/)
+- `--headers` - Skip first line as headers (requires --field)
 
 **Other**
 
+- `--color MODE` - Colorize output (auto, always, never, default: auto)
 - `--verbose` - Show debug output
 - `--help` - Show help
 
 ## Examples
 
-Analyze logs across timezones:
+**Pattern Mode**: Find and convert timestamps in arbitrary text:
+
+```bash
+# Logs with embedded timestamps (converts to local time by default)
+grep "ERROR" app.log | zone
+
+# Multiple timestamps per line
+echo "Start: 1736937000, End: 1736940600" | zone
+# => Start: Jan 15, 2025 - 5:30 AM EST, End: Jan 15, 2025 - 6:30 AM EST
+
+# Use different pretty formats
+echo "Event: 2025-01-15T10:30:00Z" | zone -p 2
+# => Event: Jan 15, 2025 - 10:30 UTC
+
+echo "Event: 2025-01-15T10:30:00Z" | zone -p 3
+# => Event: 2025-01-15 10:30 UTC
+
+# Mixed formats in same line
+echo "Logged in at 2025-01-15T10:30:00Z (1736937000)" | zone --unix
+# => Logged in at 1736937000 (1736937000)
+```
+
+**Field Mode**: Convert specific columns in structured data:
 
 ```bash
-grep "ERROR" app.log | zone --zone local --pretty
+# CSV with explicit delimiter
+cat trades.csv | zone --field 3 --delimiter ',' --zone 'New York' -p 2
+
+# Tab-separated with headers
+zone --field timestamp --delimiter '\t' --headers < data.tsv
+
+# Regex delimiter
+echo "alice    1736937000    active" | zone --field 2 --delimiter '/\s+/'
+# => alice	Jan 15, 2025 - 5:30 AM EST	active
 ```
 
-Convert trading data:
+**Idempotent Conversions**: Chain zone commands together:
 
 ```bash
-zone --zone 'New York' --strftime '%H:%M:%S' < trades.csv
+# Convert format multiple times
+zone "2025-01-15T10:30:00Z" -p 2 | zone --unix | zone --zone tokyo
+# => Jan 15, 2025 - 19:30 JST
+
+# Process zone's own output
+zone "now" | zone --zone berlin -p 3
+```
+
+**Color Control**:
+
+```bash
+# Force colors even when piping
+zone "2025-01-15T10:30:00Z" --color always | less -R
+
+# Disable colors for scripting
+zone "2025-01-15T10:30:00Z" --color never
 ```
 
-Quick conversions:
+**Quick Conversions**:
 
 ```bash
 zone --zone berlin "3pm PST"