tzinfo 1.2.10 → 2.0.6

data/lib/tzinfo/data_sources/country_info.rb

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # Represents a country and references to its time zones as returned by a
+    # {DataSource}.
+    class CountryInfo
+      # @return [String] the ISO 3166-1 alpha-2 country code.
+      attr_reader :code
+
+      # @return [String] the name of the country.
+      attr_reader :name
+
+      # @return [Array<CountryTimezone>] the time zones observed in the country.
+      attr_reader :zones
+
+      # Initializes a new {CountryInfo}. The passed in `code`, `name` and
+      # `zones` instances will be frozen.
+      #
+      # @param code [String] an ISO 3166-1 alpha-2 country code.
+      # @param name [String] the name of the country.
+      # @param zones [Array<CountryTimezone>] the time zones observed in the
+      #   country.
+      # @raise [ArgumentError] if `code`, `name` or `zones` is `nil`.
+      def initialize(code, name, zones)
+        raise ArgumentError, 'code must be specified' unless code
+        raise ArgumentError, 'name must be specified' unless name
+        raise ArgumentError, 'zones must be specified' unless zones
+        @code = code.freeze
+        @name = name.freeze
+        @zones = zones.freeze
+      end
+
+      # @return [String] the internal object state as a programmer-readable
+      #   `String`.
+      def inspect
+        "#<#{self.class}: #@code>"
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/data_timezone_info.rb

@@ -0,0 +1,91 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # The base class for time zones defined as either a series of transitions
+    # ({TransitionsDataTimezoneInfo}) or a constantly observed offset
+    # ({ConstantOffsetDataTimezoneInfo}).
+    #
+    # @abstract Data sources return instances of {DataTimezoneInfo} subclasses.
+    class DataTimezoneInfo < TimezoneInfo
+      # @param timestamp [Timestamp] a {Timestamp} with a specified
+      #   {Timestamp#utc_offset utc_offset}.
+      # @return [TimezonePeriod] the {TimezonePeriod} observed at the time
+      #   specified by `timestamp`.
+      # @raise [ArgumentError] may be raised if `timestamp` is `nil` or does not
+      #   have a specified {Timestamp#utc_offset utc_offset}.
+      def period_for(timestamp)
+        raise_not_implemented('period_for')
+      end
+
+      # Returns an `Array` containing the {TimezonePeriod TimezonePeriods} that
+      # could be observed at the local time specified by `local_timestamp`. The
+      # results are are ordered by increasing UTC start date. An empty `Array`
+      # is returned if no periods are found for the given local time.
+      #
+      # @param local_timestamp [Timestamp] a {Timestamp} representing a local
+      #   time - must have an unspecified {Timestamp#utc_offset utc_offset}.
+      # @return [Array<TimezonePeriod>] an `Array` containing the
+      #   {TimezonePeriod TimezonePeriods} that could be observed at the local
+      #   time specified by `local_timestamp`.
+      # @raise [ArgumentError] may be raised if `local_timestamp` is `nil`, or
+      #   has a specified {Timestamp#utc_offset utc_offset}.
+      def periods_for_local(local_timestamp)
+        raise_not_implemented('periods_for_local')
+      end
+
+      # Returns an `Array` of {TimezoneTransition} instances representing the
+      # times where the UTC offset of the time zone changes.
+      #
+      # Transitions are returned up to a given {Timestamp} (`to_timestamp`).
+      #
+      # A from {Timestamp} may also be supplied using the `from_timestamp`
+      # parameter. If `from_timestamp` is specified, only transitions from that
+      # time onwards will be returned.
+      #
+      # Comparisons with `to_timestamp` are exclusive. Comparisons with
+      # `from_timestamp` are inclusive. If a transition falls precisely on
+      # `to_timestamp`, it will be excluded. If a transition falls on
+      # `from_timestamp`, it will be included.
+      #
+      # Transitions returned are ordered by when they occur, from earliest to
+      # latest.
+      #
+      # @param to_timestamp [Timestamp] a {Timestamp} with a specified
+      #   {Timestamp#utc_offset utc_offset}. Transitions are returned if they
+      #   occur before this time.
+      # @param from_timestamp [Timestamp] an optional {Timestamp} with a
+      #   specified {Timestamp#utc_offset utc_offset}. If specified, transitions
+      #   are returned if they occur at or after this time.
+      # @return [Array<TimezoneTransition>] an `Array` of {TimezoneTransition}
+      #   instances representing the times where the UTC offset of the time zone
+      #   changes.
+      # @raise [ArgumentError] may be raised if `to_timestamp` is `nil` or does
+      #   not have a specified {Timestamp#utc_offset utc_offset}.
+      # @raise [ArgumentError] may be raised if `from_timestamp` is specified
+      #   but does not have a specified {Timestamp#utc_offset utc_offset}.
+      # @raise [ArgumentError] may be raised if `from_timestamp` is specified
+      #   but is not earlier than or at the same time as `to_timestamp`.
+      def transitions_up_to(to_timestamp, from_timestamp = nil)
+        raise_not_implemented('transitions_up_to')
+      end
+
+      # @return [DataTimezone] a new {DataTimezone} instance for the time zone
+      #   represented by this {DataTimezoneInfo}.
+      def create_timezone
+        DataTimezone.new(self)
+      end
+
+      private
+
+      # Raises a {NotImplementedError} to indicate that the base class is
+      # incorrectly being used directly.
+      #
+      # raise [NotImplementedError] always.
+      def raise_not_implemented(method_name)
+        raise NotImplementedError, "Subclasses must override #{method_name}"
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/linked_timezone_info.rb

@@ -0,0 +1,33 @@
+# encoding: UTF-8
+
+module TZInfo
+  module DataSources
+    # Represents a time zone that is defined as a link to or alias of another
+    # zone.
+    class LinkedTimezoneInfo < TimezoneInfo
+      # @return [String] the identifier of the time zone that provides the data
+      # (that this zone links to or is an alias for).
+      attr_reader :link_to_identifier
+
+      # Initializes a new {LinkedTimezoneInfo}. The passed in `identifier` and
+      # `link_to_identifier` instances will be frozen.
+      #
+      # @param identifier [String] the identifier of the time zone.
+      # @param link_to_identifier [String] the identifier of the time zone that
+      #   this zone link to.
+      # @raise [ArgumentError] if `identifier` or `link_to_identifier` are
+      # `nil`.
+      def initialize(identifier, link_to_identifier)
+        super(identifier)
+        raise ArgumentError, 'link_to_identifier must be specified' unless link_to_identifier
+        @link_to_identifier = link_to_identifier.freeze
+      end
+
+      # @return [LinkedTimezone] a new {LinkedTimezone} instance for the time
+      #   zone represented by this {LinkedTimezoneInfo}.
+      def create_timezone
+        LinkedTimezone.new(self)
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/posix_time_zone_parser.rb

@@ -0,0 +1,177 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require 'strscan'
+
+module TZInfo
+  module DataSources
+    # An {InvalidPosixTimeZone} exception is raised if an invalid POSIX-style
+    # time zone string is encountered.
+    #
+    # @private
+    class InvalidPosixTimeZone < StandardError #:nodoc:
+    end
+    private_constant :InvalidPosixTimeZone
+
+    # A parser for POSIX-style TZ strings used in zoneinfo files and specified
+    # by tzfile.5 and tzset.3.
+    #
+    # @private
+    class PosixTimeZoneParser #:nodoc:
+      # Initializes a new {PosixTimeZoneParser}.
+      #
+      # @param string_deduper [StringDeduper] a {StringDeduper} instance to use
+      #   to dedupe abbreviations.
+      def initialize(string_deduper)
+        @string_deduper = string_deduper
+      end
+
+      # Parses a POSIX-style TZ string.
+      #
+      # @param tz_string [String] the string to parse.
+      # @return [Object] either a {TimezoneOffset} for a constantly applied
+      #   offset or an {AnnualRules} instance representing the rules.
+      # @raise [InvalidPosixTimeZone] if `tz_string` is not a `String`.
+      # @raise [InvalidPosixTimeZone] if `tz_string` is is not valid.
+      def parse(tz_string)
+        raise InvalidPosixTimeZone unless tz_string.kind_of?(String)
+        return nil if tz_string.empty?
+
+        s = StringScanner.new(tz_string)
+        check_scan(s, /([^-+,\d<][^-+,\d]*) | <([^>]+)>/x)
+        std_abbrev = @string_deduper.dedupe(RubyCoreSupport.untaint(s[1] || s[2]))
+        check_scan(s, /([-+]?\d+)(?::(\d+)(?::(\d+))?)?/)
+        std_offset = get_offset_from_hms(s[1], s[2], s[3])
+
+        if s.scan(/([^-+,\d<][^-+,\d]*) | <([^>]+)>/x)
+          dst_abbrev = @string_deduper.dedupe(RubyCoreSupport.untaint(s[1] || s[2]))
+
+          if s.scan(/([-+]?\d+)(?::(\d+)(?::(\d+))?)?/)
+            dst_offset = get_offset_from_hms(s[1], s[2], s[3])
+          else
+            # POSIX is negative for ahead of UTC.
+            dst_offset = std_offset - 3600
+          end
+
+          dst_difference = std_offset - dst_offset
+
+          start_rule = parse_rule(s, 'start')
+          end_rule = parse_rule(s, 'end')
+
+          raise InvalidPosixTimeZone, "Expected the end of a POSIX-style time zone string but found '#{s.rest}'." if s.rest?
+
+          if start_rule.is_always_first_day_of_year? && start_rule.transition_at == 0 &&
+               end_rule.is_always_last_day_of_year? && end_rule.transition_at == 86400 + dst_difference
+            # Constant daylight savings time.
+            # POSIX is negative for ahead of UTC.
+            TimezoneOffset.new(-std_offset, dst_difference, dst_abbrev)
+          else
+            AnnualRules.new(
+              TimezoneOffset.new(-std_offset, 0, std_abbrev),
+              TimezoneOffset.new(-std_offset, dst_difference, dst_abbrev),
+              start_rule,
+              end_rule)
+          end
+        elsif !s.rest?
+          # Constant standard time.
+          # POSIX is negative for ahead of UTC.
+          TimezoneOffset.new(-std_offset, 0, std_abbrev)
+        else
+          raise InvalidPosixTimeZone, "Expected the end of a POSIX-style time zone string but found '#{s.rest}'."
+        end
+      end
+
+      private
+
+      # Parses a rule.
+      #
+      # @param s [StringScanner] the `StringScanner` to read the rule from.
+      # @param type [String] the type of rule (either `'start'` or `'end'`).
+      # @raise [InvalidPosixTimeZone] if the rule is not valid.
+      # @return [TransitionRule] the parsed rule.
+      def parse_rule(s, type)
+        check_scan(s, /,(?: (?: J(\d+) ) | (\d+) | (?: M(\d+)\.(\d)\.(\d) ) )/x)
+        julian_day_of_year = s[1]
+        absolute_day_of_year = s[2]
+        month = s[3]
+        week = s[4]
+        day_of_week = s[5]
+
+        if s.scan(/\//)
+          check_scan(s, /([-+]?\d+)(?::(\d+)(?::(\d+))?)?/)
+          transition_at = get_seconds_after_midnight_from_hms(s[1], s[2], s[3])
+        else
+          transition_at = 7200
+        end
+
+        begin
+          if julian_day_of_year
+            JulianDayOfYearTransitionRule.new(julian_day_of_year.to_i, transition_at)
+          elsif absolute_day_of_year
+            AbsoluteDayOfYearTransitionRule.new(absolute_day_of_year.to_i, transition_at)
+          elsif week == '5'
+            LastDayOfMonthTransitionRule.new(month.to_i, day_of_week.to_i, transition_at)
+          else
+            DayOfMonthTransitionRule.new(month.to_i, week.to_i, day_of_week.to_i, transition_at)
+          end
+        rescue ArgumentError => e
+          raise InvalidPosixTimeZone, "Invalid #{type} rule in POSIX-style time zone string: #{e}"
+        end
+      end
+
+      # Returns an offset in seconds from hh:mm:ss values. The value can be
+      # negative. -02:33:12 would represent 2 hours, 33 minutes and 12 seconds
+      # ahead of UTC.
+      #
+      # @param h [String] the hours.
+      # @param m [String] the minutes.
+      # @param s [String] the seconds.
+      # @return [Integer] the offset.
+      # @raise [InvalidPosixTimeZone] if the mm and ss values are greater than
+      #   59.
+      def get_offset_from_hms(h, m, s)
+        h = h.to_i
+        m = m.to_i
+        s = s.to_i
+        raise InvalidPosixTimeZone, "Invalid minute #{m} in offset for POSIX-style time zone string." if m > 59
+        raise InvalidPosixTimeZone, "Invalid second #{s} in offset for POSIX-style time zone string." if s > 59
+        magnitude = (h.abs * 60 + m) * 60 + s
+        h < 0 ? -magnitude : magnitude
+      end
+
+      # Returns the seconds from midnight from hh:mm:ss values. Hours can exceed
+      # 24 for a time on the following day. Hours can be negative to subtract
+      # hours from midnight on the given day. -02:33:12 represents 22:33:12 on
+      # the prior day.
+      #
+      # @param h [String] the hour.
+      # @param m [String] the minutes past the hour.
+      # @param s [String] the seconds past the minute.
+      # @return [Integer] the number of seconds after midnight.
+      # @raise [InvalidPosixTimeZone] if the mm and ss values are greater than
+      #   59.
+      def get_seconds_after_midnight_from_hms(h, m, s)
+        h = h.to_i
+        m = m.to_i
+        s = s.to_i
+        raise InvalidPosixTimeZone, "Invalid minute #{m} in time for POSIX-style time zone string." if m > 59
+        raise InvalidPosixTimeZone, "Invalid second #{s} in time for POSIX-style time zone string." if s > 59
+        (h * 3600) + m * 60 + s
+      end
+
+      # Scans for a pattern and raises an exception if the pattern does not
+      # match the input.
+      #
+      # @param s [StringScanner] the `StringScanner` to scan.
+      # @param pattern [Regexp] the pattern to match.
+      # @return [String] the result of the scan.
+      # @raise [InvalidPosixTimeZone] if the pattern does not match the input.
+      def check_scan(s, pattern)
+        result = s.scan(pattern)
+        raise InvalidPosixTimeZone, "Expected '#{s.rest}' to match #{pattern} in POSIX-style time zone string." unless result
+        result
+      end
+    end
+    private_constant :PosixTimeZoneParser
+  end
+end

data/lib/tzinfo/data_sources/ruby_data_source.rb

@@ -0,0 +1,141 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # A {TZInfoDataNotFound} exception is raised if the tzinfo-data gem could
+    # not be found (i.e. `require 'tzinfo/data'` failed) when selecting the Ruby
+    # data source.
+    class TZInfoDataNotFound < StandardError
+    end
+
+    # A DataSource implementation that loads data from the set of Ruby modules
+    # included in the tzinfo-data gem.
+    #
+    # TZInfo will use {RubyDataSource} by default if the tzinfo-data gem
+    # is available on the load path. It can also be selected by calling
+    # {DataSource.set} as follows:
+    #
+    #     TZInfo::DataSource.set(:ruby)
+    class RubyDataSource < DataSource
+      # (see DataSource#data_timezone_identifiers)
+      attr_reader :data_timezone_identifiers
+
+      # (see DataSource#linked_timezone_identifiers)
+      attr_reader :linked_timezone_identifiers
+
+      # (see DataSource#country_codes)
+      attr_reader :country_codes
+
+      # Initializes a new {RubyDataSource} instance.
+      #
+      # @raise [TZInfoDataNotFound] if the tzinfo-data gem could not be found
+      #   (i.e. `require 'tzinfo/data'` failed).
+      def initialize
+        super
+
+        begin
+          require('tzinfo/data')
+        rescue LoadError
+          raise TZInfoDataNotFound, "The tzinfo-data gem could not be found (require 'tzinfo/data' failed)."
+        end
+
+        if TZInfo::Data.const_defined?(:LOCATION)
+          # Format 2
+          @base_path = File.join(TZInfo::Data::LOCATION, 'tzinfo', 'data')
+        else
+          # Format 1
+          data_file = File.join('', 'tzinfo', 'data.rb')
+          path = $".reverse_each.detect {|p| p.end_with?(data_file) }
+          if path
+            @base_path = RubyCoreSupport.untaint(File.join(File.dirname(path), 'data'))
+          else
+            @base_path = 'tzinfo/data'
+          end
+        end
+
+        require_index('timezones')
+        require_index('countries')
+
+        @data_timezone_identifiers = Data::Indexes::Timezones.data_timezones
+        @linked_timezone_identifiers = Data::Indexes::Timezones.linked_timezones
+        @countries = Data::Indexes::Countries.countries
+        @country_codes = @countries.keys.sort!.freeze
+      end
+
+      # (see DataSource#to_s)
+      def to_s
+        "Ruby DataSource: #{version_info}"
+      end
+
+      # (see DataSource#inspect)
+      def inspect
+        "#<TZInfo::DataSources::RubyDataSource: #{version_info}>"
+      end
+
+      protected
+
+      # Returns a {TimezoneInfo} instance for the given time zone identifier.
+      # The result will either be a {ConstantOffsetDataTimezoneInfo}, a
+      # {TransitionsDataTimezoneInfo} or a {LinkedTimezoneInfo} depending on the
+      # type of time zone.
+      #
+      # @param identifier [String] A time zone identifier.
+      # @return [TimezoneInfo] a {TimezoneInfo} instance for the given time zone
+      #   identifier.
+      # @raise [InvalidTimezoneIdentifier] if the time zone is not found or the
+      #   identifier is invalid.
+      def load_timezone_info(identifier)
+        valid_identifier = validate_timezone_identifier(identifier)
+        split_identifier = valid_identifier.gsub(/-/, '__m__').gsub(/\+/, '__p__').split('/')
+
+        begin
+          require_definition(split_identifier)
+
+          m = Data::Definitions
+          split_identifier.each {|part| m = m.const_get(part) }
+          m.get
+        rescue LoadError, NameError => e
+          raise InvalidTimezoneIdentifier, "#{e.message.encode(Encoding::UTF_8)} (loading #{valid_identifier})"
+        end
+      end
+
+      # (see DataSource#load_country_info)
+      def load_country_info(code)
+        lookup_country_info(@countries, code)
+      end
+
+      private
+
+      # Requires a zone definition by its identifier (split on /).
+      #
+      # @param identifier [Array<string>] the component parts of a time zone
+      #   identifier (split on /). This must have already been validated.
+      def require_definition(identifier)
+        require_data('definitions', *identifier)
+      end
+
+      # Requires an index by its name.
+      #
+      # @param name [String] an index name.
+      def require_index(name)
+        require_data('indexes', name)
+      end
+
+      # Requires a file from tzinfo/data.
+      #
+      # @param file [Array<String>] a relative path to a file to be required.
+      def require_data(*file)
+        require(File.join(@base_path, *file))
+      end
+
+      # @return [String] a `String` containing TZInfo::Data version infomation
+      #   for inclusion in the #to_s and #inspect output.
+      def version_info
+        # The TZInfo::Data::VERSION constant is only available from v1.2014.8
+        # onwards.
+        "tzdb v#{TZInfo::Data::Version::TZDATA}#{TZInfo::Data.const_defined?(:VERSION) ? ", tzinfo-data v#{TZInfo::Data::VERSION}" : ''}"
+      end
+    end
+  end
+end

data/lib/tzinfo/data_sources/timezone_info.rb

@@ -0,0 +1,47 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module TZInfo
+  module DataSources
+    # Represents a time zone defined by a data source.
+    #
+    # @abstract Data sources return instances of {TimezoneInfo} subclasses.
+    class TimezoneInfo
+      # @return [String] the identifier of the time zone.
+      attr_reader :identifier
+
+      # Initializes a new TimezoneInfo. The passed in `identifier` instance will
+      # be frozen.
+      #
+      # @param identifier [String] the identifier of the time zone.
+      # @raise [ArgumentError] if `identifier` is `nil`.
+      def initialize(identifier)
+        raise ArgumentError, 'identifier must be specified' unless identifier
+        @identifier = identifier.freeze
+      end
+
+      # @return [String] the internal object state as a programmer-readable
+      #   `String`.
+      def inspect
+        "#<#{self.class}: #@identifier>"
+      end
+
+      # @return [Timezone] a new {Timezone} instance for the time zone
+      #   represented by this {TimezoneInfo}.
+      def create_timezone
+        raise_not_implemented('create_timezone')
+      end
+
+      private
+
+      # Raises a {NotImplementedError}.
+      #
+      # @param method_name [String] the name of the method that must be
+      #   overridden.
+      # @raise NotImplementedError always.
+      def raise_not_implemented(method_name)
+        raise NotImplementedError, "Subclasses must override #{method_name}"
+      end
+    end
+  end
+end