libtad 0.1.0

data/lib/types/onthisday/event.rb

@@ -0,0 +1,51 @@
+module LibTAD
+  module OnThisDay
+    # A historical event.
+    class Event
+      # @return [Integer]
+      # Identifier for the event.
+      attr_reader :id
+
+      # @return [Hash<String, String>]
+      # Hash of languages with corresponding event name.
+      attr_reader :name
+
+      # @return [::LibTAD::TADTime::TADTime]
+      # Date of the event.
+      attr_reader :date
+
+      # @return [String]
+      # Location of the event.
+      attr_reader :location
+
+      # @return [Array<String>]
+      # Event categories.
+      attr_reader :categories
+
+      # @return [Array<::LibTAD::Places::Country>]
+      # Related countries.
+      attr_reader :countries
+
+      # @return [Hash<String, String>]
+      # Languages with corresponding event description.
+      attr_reader :description
+
+      def initialize(hash)
+        @id = hash.fetch('id', nil)
+        @name = hash.fetch('name', nil)
+          &.map { |e| [ e['lang'], e['text'] ] }
+          .to_h
+
+        @date = ::LibTAD::TADTime::TADTime.new hash.fetch('date', nil)
+        @location = hash.fetch('location', nil)
+        @categories = hash.fetch('categories', nil)
+        @countries = hash.fetch('countries', nil)
+          &.map { |e| ::LibTAD::Places::Country.new(e) }
+
+        @description = hash.fetch('description', nil)
+          &.map { |e| [ e['lang'], e['text'] ] }
+          .to_h
+      end
+    end
+  end
+end

data/lib/types/onthisday/event_type.rb

@@ -0,0 +1,15 @@
+module LibTAD
+  module OnThisDay
+    # All valid event types.
+    EVENT_TYPE = [
+      # A historical event.
+      :events,
+
+      # Birth of a historical person.
+      :births,
+
+      # Death of a historical person.
+      :deaths
+    ].freeze
+  end
+end

data/lib/types/onthisday/name.rb

@@ -0,0 +1,24 @@
+module LibTAD
+  module OnThisDay
+    # A full name.
+    class Name
+      # @return [String]
+      # First name.
+      attr_reader :first
+
+      # @return [String]
+      # Middle name.
+      attr_reader :middle
+
+      # @return [String]
+      # Last name.
+      attr_reader :last
+
+      def initialize(hash)
+        @first = hash.fetch('first', nil)
+        @middle = hash.fetch('middle', nil)
+        @last = hash.fetch('last', nil)
+      end
+    end
+  end
+end

data/lib/types/onthisday/person.rb

@@ -0,0 +1,39 @@
+module LibTAD
+  module OnThisDay
+    # A historical person.
+    class Person
+      # @return [Integer]
+      # Identifier for the person.
+      attr_reader :id
+
+      # @return [::LibTAD::OnThisDay::Name]
+      # Full name.
+      attr_reader :name
+
+      # @return [::LibTAD::TADTime::TADTime]
+      # Date of birth.
+      attr_reader :birthdate
+
+      # @return [::LibTAD::TADTime::TADTime]
+      # Date of death, if applicable.
+      attr_reader :deathdate
+
+      # @return [Array<String>]
+      # Person categories.
+      attr_reader :categories
+
+      # @return [Array<String>]
+      # The nationalities of the person
+      attr_reader :nationalities
+
+      def initialize(hash)
+        @id = hash.fetch('id', nil)
+        @name = ::LibTAD::OnThisDay::Name.new hash.fetch('name', nil)
+        @birthdate = ::LibTAD::TADTime::TADTime.new hash['birthdate'] unless !hash.key?('birthdate')
+        @deathdate = ::LibTAD::TADTime::TADTime.new hash['deathdate'] unless !hash.key?('deathdate')
+        @categories = hash.fetch('categories', nil)
+        @nationalities = hash.fetch('nationalities', nil)
+      end
+    end
+  end
+end

data/lib/types/places/country.rb

@@ -0,0 +1,20 @@
+module LibTAD
+  module Places
+    # Information about a country.
+    class Country
+      # @return [String]
+      # The ISO 3166-1-alpha-2 country code.
+      # @see https://dev-test.timeanddate.com/docs/external-references#ISO3166 ISO3166
+      attr_reader :id
+
+      # @return [String]
+      # Full name of the country.
+      attr_reader :name
+
+      def initialize(hash)
+        @id = hash.fetch('id', nil)
+        @name = hash.fetch('name', nil)
+      end
+    end
+  end
+end

data/lib/types/places/geo.rb

@@ -0,0 +1,34 @@
+module LibTAD
+  module Places
+    # Geographical information about a location.
+    class Geo
+      # @return [String]
+      # The name of the location.
+      attr_reader :name
+
+      # @return [String]
+      # The state of the location within the country (only if applicable).
+      attr_reader :state
+      
+      # @return [Country]
+      # Country of the location.
+      attr_reader :country
+
+      # @return [Float]
+      # Geographical latitude of the location.
+      attr_reader :latitude
+
+      # @return [Float]
+      # Geographical longitude of the location.
+      attr_reader :longitude
+
+      def initialize(hash)
+        @name = hash.fetch('name', nil)
+        @state = hash.fetch('state', nil)
+        @country = Country.new hash['country'] unless !hash.key?('country')
+        @latitude = hash.fetch('latitude', nil)
+        @longitude = hash.fetch('longitude', nil)
+      end
+    end
+  end
+end

data/lib/types/places/location.rb

@@ -0,0 +1,43 @@
+module LibTAD
+  module Places
+    # Information about a location.
+    class Location
+      # @return [String]
+      # The id of the location.
+      attr_reader :id
+
+      # @return [String]
+      # The part of the queried placeid that this location matches.
+      attr_reader :matchparam
+
+      # @return [Geo]
+      # Geographical information about the location.
+      attr_reader :geo
+
+      # @return [::LibTAD::TADTime::TADTime]
+      # Time information. Only present if requested.
+      attr_reader :time
+
+      # @return [Array<::LibTAD::TADTime::TimeChange>]
+      # Time changes (daylight savings time). Only present if requested and information is available.
+      attr_reader :timechanges
+
+      # @return [Array<::LibTAD::Astronomy::AstronomyObject>]
+      # Astronomical information – sunrise and sunset times. Only for the timeservice and if requested.
+      attr_reader :objects
+
+      def initialize(hash)
+        @id = hash.fetch('id', nil)
+        @matchparam = hash.fetch('matchparam', nil)
+        @geo = Geo.new hash['geo'] unless !hash.key?('geo')
+        @time = ::LibTAD::TADTime::TADTime.new hash['time'] unless !hash.key?('time')
+        @timechanges = hash.fetch('timechanges', nil)
+          &.map { |e| ::LibTAD::TADTime::TimeChange.new(e) }
+
+        @objects = hash.fetch('astronomy', nil)
+          &.fetch('objects', nil)
+          &.map { |e| ::LibTAD::Astronomy::AstronomyObject.new(e) }
+      end
+    end
+  end
+end

data/lib/types/places/location_ref.rb

@@ -0,0 +1,24 @@
+module LibTAD
+  module Places
+    # Information about a location referenced by a region.
+    class LocationRef
+      # @return [String]
+      # The ID of the location.
+      attr_reader :id
+
+      # @return [String]
+      # The name of the location.
+      attr_reader :name
+      
+      # @return [State]
+      # The state of the location within the country (only if applicable).
+      attr_reader :state
+
+      def initialize(hash)
+        @id = hash.fetch('id', nil)
+        @name = hash.fetch('name', nil)
+        @state = hash.fetch('state', nil)
+      end
+    end
+  end
+end

data/lib/types/places/place.rb

@@ -0,0 +1,24 @@
+module LibTAD
+  module Places
+    # Information about a place.
+    class Place
+      # @return [String]
+      # Numerical ID of the referenced place.
+      attr_reader :id
+
+      # @return [String]
+      # Textual ID of the referenced place.
+      attr_reader :urlid
+
+      # @return [Geo]
+      # Geographical information about the location.
+      attr_reader :geo
+
+      def initialize(hash)
+        @id = hash.fetch('id', nil)
+        @urlid = hash.fetch('urlid', nil)
+        @geo = Geo.new hash['geo'] unless !hash.key?('geo')
+      end
+    end
+  end
+end

data/lib/types/places/region.rb

@@ -0,0 +1,35 @@
+module LibTAD
+  module Places
+    # The geographical region. Contains country, a textual description of
+    # the region and the name of the biggest place.
+    class Region
+      # @return [Country]
+      # Country which the region belongs to.
+      attr_reader :country
+
+      # @return [String]
+      # Textual description of a region.
+      #
+      # Example: All locations
+      # Example: most of Newfoundland and Labrador
+      # Example: some regions of Nunavut Territory; small region of Ontario
+      attr_reader :desc
+
+      # @return [String]
+      # Name of the biggest city within the region.
+      attr_reader :biggestplace
+
+      # @return [Array<LocationRef>]
+      # A list of all locations referenced by this region. Only returned if requested by specifying the parameter listplaces.
+      attr_reader :locations
+
+      def initialize(hash)
+        @country = Country.new hash['country'] unless !hash.key?('country')
+        @desc = hash.fetch('desc', nil)
+        @biggestplace = hash.fetch('biggestplace', nil)
+        @locations = hash.fetch('locations', nil)
+          &.map { |e| LocationRef.new(e) }
+      end
+    end
+  end
+end

data/lib/types/time/datetime.rb

@@ -0,0 +1,93 @@
+require 'date'
+
+module LibTAD
+  module TADTime
+    # Date and time, split up into components.
+    class TADDateTime
+      # @return [Integer]
+      # The year component of the timestamp.
+      attr_reader :year
+
+      # @return [Integer]
+      # The month component of the timestamp.
+      attr_reader :month
+
+      # @return [Integer]
+      # The day component of the timestamp.
+      attr_reader :day
+
+      # @return [Integer]
+      # The hour component of the timestamp.
+      attr_reader :hour
+
+      # @return [Integer]
+      # The minute component of the timestamp.
+      attr_reader :minute
+
+      # @return [Integer]
+      # The second component of the timestamp.
+      attr_reader :second
+
+      def initialize(year: nil, month: nil, day: nil, hour: nil, minute: nil, second: nil)
+        @year = year
+        @month = month
+        @day = day
+        @hour = hour
+        @minute = minute
+        @second = second
+      end
+
+      # @return [Boolean]
+      # Compare equality to another instance.
+      def ==(other)
+        other.year == @year &&
+        other.month == @month &&
+        other.day == @day &&
+        other.minute == @minute &&
+        other.second == @second
+      end
+
+      # @return [::LibTAD::TADTime::TADDateTime]
+      # Helper function for initializing from json.
+      def from_json(hash)
+        @year = hash&.fetch('year', nil)
+        @month = hash&.fetch('month', nil)
+        @day = hash&.fetch('day', nil)
+        @hour = hash&.fetch('hour', nil)
+        @minute = hash&.fetch('minute', nil)
+        @second = hash&.fetch('second', nil)
+        
+        self
+      end
+
+      # @return [String]
+      # Helper function for formatting as ISO 8601.
+      def to_iso8601
+        year = @year.to_s.rjust(4, '0')
+        month = @month.to_s.rjust(2, '0')
+        day = @day.to_s.rjust(2, '0')
+        "#{year}-#{month}-#{day}"
+      end
+
+      # @return [::LibTAD::TADTime::TADDateTime]
+      # Get the current time.
+      def now
+        dt = ::Time.now
+        @year = dt.year
+        @month = dt.month
+        @day = dt.day
+        @hour = dt.hour
+        @minute = dt.min
+        @second = dt.sec
+
+        self
+      end
+
+      # @return [::DateTime]
+      # Try converting to Time from the standard library.
+      def to_std!
+        ::Time.new(@year, @month, @day, @hour, @minute, @second)
+      end
+    end
+  end
+end

data/lib/types/time/dst_entry.rb

@@ -0,0 +1,48 @@
+module LibTAD
+  module TADTime
+    # DST information about a region.
+    class DSTEntry
+      # @return [::LibTAD::Places::Region]
+      # The geographical region where this information is valid.
+      # Contains country, a textual description of the region and the name of the biggest place.
+      attr_reader :region
+
+      # @return [::LibTAD::TADTime::TADTimeZone]
+      # Information about the standard time zone. This element is always returned.
+      attr_reader :stdtimezone
+
+      # @return [::LibTAD::TADTime::TADTimeZone]
+      # Information about the daylight savings time zone. Suppressed, if there are no DST changes in the
+      # queried year. Please note that if the region is on daylight savings time for the whole year, this information will be returned
+      # the stdtimezone element. Additionally, the special element will be set to allyear.
+      attr_reader :dsttimezone
+
+      # @return [DstEntrySpecial]
+      # Indicates if the region does not observe DST at all, or is on DST all year long.
+      attr_reader :special
+
+      # @return [String]
+      # Starting date of daylight savings time. Suppressed, if there are no DST changes in the queried year.
+      attr_reader :dststart
+
+      # @return [String]
+      # Ending date of daylight savings time. Suppressed, if there are no DST changes in the queried year.
+      attr_reader :dstend
+
+      # @return [Array<::LibTAD::TADTime::TimeChange]
+      # Time changes (daylight savings time). Only present if requested and information is available.
+      attr_reader :timechanges
+
+      def initialize(hash)
+        @region = ::LibTAD::Places::Region.new hash['region'] unless !hash.key?('region')
+        @stdtimezone = ::LibTAD::TADTime::TADTimeZone.new hash['stdtimezone'] unless !hash.key?('stdtimezone')
+        @dsttimezone = ::LibTAD::TADTime::TADTimeZone.new hash['dsttimezone'] unless !hash.key?('dsttimezone')
+        @special = hash.dig('special', 'type')
+        @dststart = hash.fetch('dststart', nil)
+        @dstend = hash.fetch('dstend', nil)
+        @timechanges = hash.fetch('timechanges', nil)
+          &.map { |e| ::LibTAD::TADTime::TimeChange.new(e) }
+      end
+    end
+  end
+end