tztr 0.1.0 → 0.2.1

data/bin/tztr

@@ -2,11 +2,52 @@
 # frozen_string_literal: true
 
 require 'optparse'
+require 'json'
+require 'date'
+require 'stringio'
 
 $LOAD_PATH.unshift File.expand_path('../lib', __dir__)
 require 'tztr'
 
+# Structured description of the CLI, emitted by `-h -j` / `-h -J` so agents can
+# read the option schema instead of scraping the text help.
+HELP_DOC = {
+  name: 'tztr',
+  version: Tztr::VERSION,
+  usage: 'tztr [options] [file | now]',
+  summary: 'Timezone Translator - convert timestamps between timezones. Reads from stdin, files, or the clock (now).',
+  options: [
+    { short: '-f', long: '--from', arg: 'TZ', description: 'Input timezone for timestamps that name none (default: $TZ, else the system zone)' },
+    { short: '-t', long: '--to', arg: 'TZ', description: 'Output timezone (default: $TZ, else UTC)' },
+    { short: '-l', long: '--list', arg: nil, description: 'List timezone aliases' },
+    { short: '-i', long: '--in-place', arg: nil, description: 'Edit files in place' },
+    { short: '-F', long: '--format', arg: 'FMT', description: 'Output format: iso, short, time (default: preserve input)' },
+    { short: '-d', long: '--date', arg: 'DATE', description: 'Reference date for time-only inputs (resolves DST)' },
+    { short: '-j', long: '--json', arg: nil, description: 'Emit a JSON array of matches' },
+    { short: '-J', long: '--ndjson', arg: nil, description: 'Emit newline-delimited JSON (one object per match)' },
+    { short: nil, long: '--detect', arg: nil, description: 'Report detected format/zone without converting' },
+    { short: '-v', long: '--verbose', arg: nil, description: 'Print diagnostics to stderr' },
+    { short: '-V', long: '--version', arg: nil, description: 'Show version' },
+    { short: '-h', long: '--help', arg: nil, description: 'Show this help' },
+  ],
+  environment: [
+    { name: 'TZ', description: 'Default timezone for input and output (overridden by -f / -t)' },
+  ],
+  examples: [
+    "echo '2026-04-03T12:00:00Z' | tztr -t sf",
+    "echo '15:30 UTC' | tztr -t pst",
+    "echo '12:00 EST' | tztr -t -8",
+    "tail -f app.log | tztr -t nyc",
+    "echo '15:30 UTC' | tztr -t pst -j",
+    "tail -f app.log | tztr -t nyc -J",
+    "echo '2026-04-03T12:00:00Z' | tztr --detect -j",
+    "echo '15:30' | tztr -f pacific -t utc -d 2026-01-15",
+    "tztr now -t tokyo",
+  ],
+}.freeze
+
 local_tz = ENV['TZ']
+local_tz = nil if local_tz&.empty? # TZ="" means unset, not "a zone named ''"
 
 options = {
   from: nil,
@@ -14,58 +55,213 @@ options = {
   format: nil
 }
 
+FORMATS = %w[iso short time].freeze
+
+# Validated as the flag is parsed, not afterwards, so `-h -F bogus` still
+# fails -- the order the Rust port parses in.
+parse_format = lambda do |value|
+  unless FORMATS.include?(value)
+    abort "tztr: invalid format: #{value} (expected #{FORMATS.join(', ')})"
+  end
+
+  value.to_sym
+end
+
 parser = OptionParser.new do |opts|
-  opts.banner = "Usage: tztr [options] [file]"
+  opts.banner = "Usage: tztr [options] [file | now]"
   opts.separator ""
-  opts.separator "Timezone Translator - convert timestamps timezone. Reads from stdin or file."
+  opts.separator "Timezone Translator - convert timestamps between timezones. Reads from stdin, files, or the clock (now)."
   opts.separator ""
 
-  opts.on("-f", "--from TZ", "Input timezone (default: auto-detect)") { |v| options[:from] = v }
-  opts.on("-t", "--to TZ", "Output timezone (default: UTC)") { |v| options[:to] = v }
+  opts.on("-f", "--from TZ", "Input timezone for timestamps that name none (default: $TZ, else the system zone)") { |v| options[:from] = v }
+  opts.on("-t", "--to TZ", "Output timezone (default: $TZ, else UTC)") { |v| options[:to] = v }
   opts.on("-l", "--list", "List timezone aliases") { Tztr::TIMEZONE_ALIASES.sort.each { |k, v| puts "%-12s %s" % [k, v] }; exit }
-  opts.on("-i", "--in-place", "Edit file in place") { options[:inplace] = true }
-  opts.on("-F", "--format FMT", %i[iso short time], "Output format: iso, short, time (default: preserve input)") { |v| options[:format] = v }
-  opts.on("-v", "--version", "Show version") { puts Tztr::VERSION; exit }
-  opts.on("-h", "--help", "Show this help") { puts opts; exit }
+  opts.on("-i", "--in-place", "Edit files in place") { options[:inplace] = true }
+  opts.on("-F", "--format FMT", "Output format: iso, short, time (default: preserve input)") { |v| options[:format] = parse_format.call(v) }
+  opts.on("-d", "--date DATE", "Reference date for time-only inputs (resolves DST)") { |v| options[:date] = v }
+  opts.on("-j", "--json", "Emit a JSON array of matches") { options[:json] = true }
+  opts.on("-J", "--ndjson", "Emit newline-delimited JSON (one object per match)") { options[:ndjson] = true }
+  opts.on("--detect", "Report detected format/zone without converting") { options[:detect] = true }
+  opts.on("-v", "--verbose", "Print diagnostics to stderr") { options[:verbose] = true }
+  opts.on("-V", "--version", "Show version") { puts Tztr::VERSION; exit }
+  opts.on("-h", "--help", "Show this help") { options[:help] = true }
 
   opts.separator ""
   opts.separator "Environment:"
-  opts.separator "  TZ    Sets default output timezone (overridden by -t)"
+  opts.separator "  TZ    Default timezone for input and output (overridden by -f / -t)"
   opts.separator ""
   opts.separator "Examples:"
   opts.separator "  echo '2026-04-03T12:00:00Z' | tztr -t sf"
   opts.separator "  echo '15:30 UTC' | tztr -t pst"
   opts.separator "  echo '12:00 EST' | tztr -t -8"
   opts.separator "  tail -f app.log | tztr -t nyc"
+  opts.separator "  echo '15:30 UTC' | tztr -t pst -j"
+  opts.separator "  tail -f app.log | tztr -t nyc -J"
+  opts.separator "  echo '2026-04-03T12:00:00Z' | tztr --detect -j"
+  opts.separator "  echo '15:30' | tztr -f pacific -t utc -d 2026-01-15"
+  opts.separator "  tztr now -t tokyo"
+end
+begin
+  # No prefix abbreviation: --jso must not quietly mean --json, because the
+  # Rust binary most users install rejects it.
+  parser.require_exact = true
+  parser.parse!
+rescue OptionParser::MissingArgument => e
+  abort "#{parser.program_name}: missing argument for #{e.args.first}"
+rescue OptionParser::NeedlessArgument => e
+  # args carries the "=value" tail; the user only needs the flag named.
+  abort "#{parser.program_name}: #{e.args.first.split('=').first} takes no argument"
+rescue OptionParser::InvalidOption, OptionParser::AmbiguousOption => e
+  # Built from args rather than e.message, which appends a "Did you mean?" line.
+  abort "#{parser.program_name}: invalid option: #{e.args.first}"
+rescue OptionParser::ParseError => e
+  abort "#{parser.program_name}: #{e.message}"
+end
+
+json_mode = options[:json] || options[:ndjson]
+
+if options[:help]
+  if json_mode
+    puts(options[:ndjson] ? JSON.generate(HELP_DOC) : JSON.pretty_generate(HELP_DOC))
+  else
+    puts parser
+  end
+  exit
 end
-parser.parse!
 
-options[:to] = Tztr.resolve_tz(options[:to])
-options[:from] = Tztr.resolve_tz(options[:from]) || Tztr.resolve_tz(local_tz)
+# A timestamp with no zone is read in -f, else $TZ, else the machine's own
+# zone; only when none of those is known is it taken to be in -t already.
+system_tz = Tztr.system_zone unless local_tz
+implicit_source =
+  if options[:from] then nil
+  elsif local_tz then '$TZ'
+  elsif system_tz then 'the system zone'
+  end
+implicit_from = !implicit_source.nil?
+
+begin
+  options[:to] = Tztr.resolve_tz(options[:to])
+  options[:from] = Tztr.resolve_tz(options[:from]) || Tztr.resolve_tz(local_tz) || system_tz
+  options[:date] = Tztr.normalize_date(options[:date]) if options[:date]
+rescue Tztr::Error => e
+  abort "#{parser.program_name}: #{e.message}"
+end
 ENV['TZ'] = options[:to]
 
+if options[:inplace] && (json_mode || options[:detect])
+  abort "#{parser.program_name}: -i cannot be combined with --json/--ndjson/--detect"
+end
+
+# An implicit from is announced by `disclose` below instead, and only if some
+# timestamp actually uses it -- naming it here would claim a source zone that a
+# timestamp carrying its own never consults.
+if options[:verbose] && !implicit_from
+  warn "#{parser.program_name}: from=#{options[:from] || 'auto'} to=#{options[:to]}"
+end
+
+# A bare time silently borrows its source zone from $TZ and resolves DST
+# against today. Say so, once, the first time it actually happens.
+disclosed = []
+disclose = lambda do |line|
+  # A date(1) zone we don't know (EEST): the reason its line was left alone.
+  (Tztr.unknown_zones(line, from: options[:from]) - disclosed).each do |token|
+    disclosed << token
+    warn %(#{parser.program_name}: ignored "#{token}": not a zone tztr knows)
+  end
+
+  # A zone the user wrote but we didn't read, because of its case (Pst).
+  (Tztr.ignored_zones(line) - disclosed).each do |token|
+    disclosed << token
+    warn %(#{parser.program_name}: ignored "#{token}": a zone abbreviation is matched in all uppercase or all lowercase)
+  end
+
+  assumed = Tztr.assumptions(line, from: options[:from]) - disclosed
+  return if assumed.empty?
+
+  disclosed.concat(assumed)
+  warn "#{parser.program_name}: from=#{options[:from]} (implicit, from #{implicit_source}) to=#{options[:to]}" if assumed.include?(:zone) && implicit_from
+  return unless assumed.include?(:date) && !options[:date]
+
+  warn "#{parser.program_name}: no -d given, assuming #{Tztr.assumed_date(line, from: options[:from], to: options[:to])} for DST resolution"
+end
+
+# An error about one of our inputs names it, and the run carries on with the
+# rest, as cat and sed -i do -- stopping would leave -i half-applied. A broken
+# pipe is about stdout and stdin has no name, so neither is about an input
+# file: both fall through to the bare form below.
+failed = false
+file_error = lambda do |path, error|
+  raise error if path.nil? || error.is_a?(Errno::EPIPE)
+
+  warn "#{parser.program_name}: #{path}: #{SystemCallError.new(error.errno).message} (os error #{error.errno})"
+  failed = true
+end
+
 $stdout.sync = true
 
+# `tztr now`: the current time, read as though piped in, so every flag applies.
+if ARGV == ['now']
+  abort "#{parser.program_name}: -i cannot be combined with now" if options[:inplace]
+
+  ARGV.clear
+  $stdin = StringIO.new(Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ\n"))
+end
+
 if ARGV.empty? && $stdin.tty?
   puts parser
   exit
 end
 
-if options[:inplace]
-  abort "#{parser.program_name}: -i requires a file argument" if ARGV.empty?
+begin
+  if options[:inplace]
+    abort "#{parser.program_name}: -i requires a file argument" if ARGV.empty?
 
-  ARGV.each do |file|
-    content = File.read(file)
-    translated = content.each_line.map do |line|
-      Tztr.translate(line, to: options[:to], from: options[:from], format: options[:format])
-    end.join
-    File.write(file, translated) if translated != content
-  end
-else
-  inputs = ARGV.empty? ? [$stdin] : ARGV.map { |f| File.open(f) }
-  inputs.each do |input|
-    input.each_line do |line|
-      print Tztr.translate(line, to: options[:to], from: options[:from], format: options[:format])
+    ARGV.each do |file|
+      content = File.read(file)
+      translated = content.each_line.map do |line|
+        disclose.call(line) if options[:verbose] && !options[:detect]
+        Tztr.translate(line, to: options[:to], from: options[:from], format: options[:format], date: options[:date])
+      end.join
+      File.write(file, translated) if translated != content
+    rescue SystemCallError => e
+      file_error.call(file, e)
     end
+  else
+    collected = [] if options[:json]
+
+    # Opened one at a time: a filter should start emitting as soon as it has
+    # something, rather than stat-ing every argument first. nil is stdin.
+    paths = ARGV.empty? ? [nil] : ARGV
+    paths.each do |path|
+      input = path ? File.open(path) : $stdin
+
+      input.each_line do |line|
+        disclose.call(line) if options[:verbose] && !options[:detect]
+
+        if json_mode
+          ms = Tztr.matches(line, to: options[:to], from: options[:from], format: options[:format], detect: options[:detect], date: options[:date])
+          if options[:ndjson]
+            ms.each { |m| puts JSON.generate(m) }
+          else
+            collected.concat(ms)
+          end
+        elsif options[:detect]
+          Tztr.matches(line, to: options[:to], from: options[:from], detect: true).each do |m|
+            puts [m[:original], m[:detected_format], m[:detected_tz]].join("\t")
+          end
+        else
+          print Tztr.translate(line, to: options[:to], from: options[:from], format: options[:format], date: options[:date])
+        end
+      end
+    rescue SystemCallError => e
+      file_error.call(path, e)
+    end
+
+    puts JSON.pretty_generate(collected) if options[:json]
   end
+  exit 1 if failed
+rescue SystemCallError => e
+  # Ruby's own message carries the syscall and path; the Rust port prints the
+  # bare strerror, and the two must read the same.
+  abort "#{parser.program_name}: #{SystemCallError.new(e.errno).message} (os error #{e.errno})"
 end

data/lib/tztr/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tztr
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end