zone 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec4bf54c71190831471974566598f5f99d1398588eb781d6bf05d5b09e8d208b
-  data.tar.gz: b2984b02b1e3b384bfc2593e3f24e9fb79507eec7bd7b4fa33981023b2daeda7
+  metadata.gz: 8be1f2c6eebecd142bfd5ef95bd1fefbe02a4cc2e873caa61f7ddeb837b28eff
+  data.tar.gz: a318b8c2d32fd77f89aa2aacdf39eb01ee04218c4a5bd3e68312dcf24bbe2a67
 SHA512:
-  metadata.gz: 1ab5600b1439b2ff8692eaa08baf9c8687978f5c8c9e3639d1031c509fb45db59379f77359d76274c8030ca02bb7589c57ebf3692867a55188567a3c39b8c6a6
-  data.tar.gz: 2223d049e9c21f2805c0ab411c9623a11fd5da50a05d742e48d9dfc0edff90a2fe8481db551d3f46a19f09103a35156a0b91d89419fc553ac18b1d18ddb824e9
+  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

@@ -1,39 +1,234 @@
 # Zone
 
-TODO: Delete this and the text below, and describe your gem
+Timezone conversion and datetime formatting for the command line
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/zone`. To experiment with that code, run `bin/console` for an interactive prompt.
+```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
+# => Nov 05, 2025 - 11:40 AM JST
+
+# Process CSV timestamps (field mode)
+cat data.csv | zone --field 3 --delimiter ',' --zone pacific
+# => customer,purchase_date,amount
+# => alice,42.00,Nov 04, 2025 - 6:40 PM PST
+
+# Make logs readable (pattern mode - default)
+tail -f app.log | zone
+# => Nov 04, 2025 - 9:15 PM EST [ERROR] Database connection timeout
+```
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```bash
+gem install zone
+```
+
+Or with Bundler:
+
+```bash
+bundle add zone
+```
+
+## How It Works
+
+Zone operates in two modes:
 
-Install the gem and add to the application's Gemfile by executing:
+**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
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+echo "Event at 2025-01-15T10:30:00Z completed" | zone --pretty
+# => Event at Jan 15, 2025 - 10:30 AM UTC completed
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+**Field Mode (Explicit)**: Splits lines by delimiter, converts a specific field, then rejoins. Use this for structured data like CSV or TSV files.
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+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
 
-TODO: Write usage instructions here
+Convert timezones:
+
+```bash
+zone --zone 'New York' '2025-11-05T02:40:32+00:00'
+# => Nov 04, 2025 - 9:40 PM EST
+```
+
+Change formats:
+
+```bash
+# 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
+```
+
+Process structured data:
+
+```bash
+# 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
+
+# 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:
+
+```bash
+zone 1730772120 1730858520 1730944920 --zone tokyo --pretty
+# => Nov 05 - 11:42 AM JST
+# => Nov 06 - 11:42 AM JST
+# => Nov 07 - 11:42 AM JST
+```
+
+## Options
+
+**Output Formats**
+
+- `-p, --pretty [STYLE]` - Pretty format (1=12hr, 2=24hr, 3=ISO-compact, default: 1)
+- `--iso8601` - ISO 8601 format
+- `--unix` - Unix timestamp
+- `--strftime FORMAT` - Custom strftime format
 
-## Development
+**Timezones**
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+- `--zone TZ` - Convert to timezone (fuzzy matching, default: local)
+- `--utc` - Convert to UTC
+- `--local` - Convert to local time (default)
+
+**Data Processing**
+
+- `--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
+
+**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
+# 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
+```
+
+**Idempotent Conversions**: Chain zone commands together:
+
+```bash
+# 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**:
+
+```bash
+zone --zone berlin "3pm PST"
+# => 2025-11-05T00:00:00+01:00
+
+zone --zone pacific now
+# => 2025-11-04T16:42:15-08:00
+```
+
+## Timezone Matching
+
+Zone uses fuzzy matching for timezone names:
+
+```bash
+zone --zone pacific     # => US/Pacific
+zone --zone tokyo       # => Asia/Tokyo  
+zone --zone europe      # => Europe/London (first match)
+zone --zone 'US/Eastern' # => US/Eastern (exact match)
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Use `--verbose` to see which timezone was matched.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/gillisd/zone.
+Bug reports and pull requests are welcome on [GitHub](https://github.com/gillisd/zone).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+[MIT License](https://opensource.org/licenses/MIT)