reality 0.0.3 → 0.0.4

data/lib/reality/entity/coercion.rb

@@ -71,6 +71,26 @@ module Reality
         end
       end
 
+      def to_simple_type(val)
+        case val
+        when Rational
+          val.to_f
+        when nil, Numeric, String, Symbol
+          val
+        when Array
+          val.map{|v| to_simple_type(v)}
+        #when Hash
+          #val.map{|k, v| [to_simple_type(k), to_simple_type(v)]}.to_h
+        when Entity
+          val.loaded? ? val.to_h : val.to_s
+
+        when ->(v){v.respond_to?(:to_h)}
+          val.to_h
+        else
+          val.to_s
+        end
+      end
+
     end
   end
 end

data/lib/reality/entity/wikidata_predicates.rb

@@ -1,5 +1,6 @@
 module Reality
   class Entity
+    # @private
     module WikidataPredicates
       module_function
       

data/lib/reality/entity/wikipedia_type.rb

@@ -1,5 +1,6 @@
 module Reality
   class Entity
+    # @private
     module WikipediaType
       def infobox_name(*infobox_names)
         infobox_names.each do |n|

data/lib/reality/extras/geonames.rb

@@ -12,10 +12,12 @@ module Reality
         private
         
         def guess_timezone
-          Timezone::Configure.username = Reality.config.fetch('keys', 'geonames')
+          Timezone::Lookup.config(:geonames) do |c|
+            c.username = Reality.config.fetch('keys', 'geonames')
+          end
           
-          gnzone = Timezone::Zone.new(latlon: [lat.to_f, lng.to_f])
-          gnzone && TZInfo::Timezone.new(gnzone.zone)
+          gnzone = Timezone.lookup(lat.to_f, lng.to_f)
+          gnzone && TZInfo::Timezone.new(gnzone.name)
         end
       end
 

data/lib/reality/extras/quandl.rb

@@ -0,0 +1,57 @@
+require 'quandl'
+
+module Reality
+  module Extras
+    module Quandl
+      class Economy
+        def initialize(country)
+          @country = country
+        end
+
+        def gdp
+          gdp = fetch("ODA/#{@country.iso3_code}_NGDPD")
+          gdp = gdp.to_i * 1_000_000_000
+          Reality::Measure(gdp, '$')
+        end
+
+        def inflation
+          inflation = fetch("ODA/#{@country.iso3_code}_PCPIPCH")
+          Reality::Measure(inflation, '%')
+        end
+
+        def unemployment
+          unemployment = fetch("ODA/#{@country.iso3_code}_LUR")
+          Reality::Measure(unemployment, '%')
+        end
+
+        def inspect
+          "#<Reality::Quandl::Economy (%s)>" % [@country.name]
+        end
+
+        private
+
+        def fetch(code)
+          ::Quandl::ApiConfig.api_key ||= Reality.config.fetch('keys', 'quandl')
+          database, dataset = code.split('/')
+          data = ::Quandl::Data.all({ params: { database_code: database, dataset_code: dataset }})
+          data.values.select { |v| v['date'] <= Date.today }.sort_by { |d| d['date'] }.last.value
+        rescue ::Quandl::NotFoundError
+          nil
+        end
+      end
+
+      module CountryEconomics
+        def economy
+          @economy ||= Extras::Quandl::Economy.new(self)
+        end
+      end
+
+      def self.included(reality)
+        reality.config.register('keys', 'quandl',
+                                desc: 'Quandl API key. Can be obtained here: http://quandl.com')
+
+        reality::Country.include CountryEconomics
+      end
+    end
+  end
+end

data/lib/reality/geo.rb

@@ -4,11 +4,30 @@ Geokit::default_units = :kms # TODO: use global settings
 
 module Reality
   module Geo
-    # GeoKit, RGeo, GeoRuby -- I know, ok?
-    # It's just incredibly simple class to hold two values
-    # and show them prettily.
+    # Keeps information about coordinates point.
+    # All services that are based on particular point in space (Weather, Time) depend on it.
+    # Many Entity types can have coordinates, they can be accessed as #coord  method which returns this class.
+    #
+    # Example:
+    #
+    # ```ruby
+    # Reality::Entity('Mississippi').coord
+    # # => #<Reality::Geo::Coord(33°0′0″N,90°0′0″W)>
+    # ```
+    #
+    # Usage examples:
+    #
+    # ```ruby
+    # coord = Reality::Geo::Coord.new(50.45, 30.52)
+    # # => #<Reality::Geo::Coord(50°27′0″N,30°31′24″E)>
+    # coord.sunrise
+    # #  => 2016-03-31 03:35:22 UTC
+    # coord.distance_to(Reality::Entity('London'))
+    # #  => #<Reality::Measure(2,135 km)>
+    # ```
+    #
+    # Uses Geokit for some operations like #distance_to, #close_to? etc.
     #
-    # GeoKit will be used at its time.
     class Coord
       attr_reader :lat, :lng
 
@@ -44,33 +63,52 @@ module Reality
           sign * (d.abs.to_i + Rational(m.to_i) / 60 + Rational(s.to_f) / 3600)
         end
       end
-      
+
+      # @param latitude
+      # @param longitude
       def initialize(lat, lng)
         @lat, @lng = Rational(lat), Rational(lng)
       end
 
+      # @param point - Coordinates, e.g "50.45,30.52", [50.45, 30.52], Coord or Entity instance
+      #
+      # @return [Reality::Measure]
       def distance_to(point)
         destination_coords = normalize_point(point).to_s
         res = Geokit::LatLng.distance_between(to_s, destination_coords, formula: :sphere)
         Reality::Measure(res, 'km')
       end
 
+      # @param point - Coordinates, e.g "50.45,30.52", [50.45, 30.52], Coord or Entity instance
+      #
+      # @return [Reality::Measure]
       def direction_to(point)
         destination_coords = normalize_point(point).to_s
         res = Geokit::LatLng.heading_between(to_s, destination_coords)
         Reality::Measure(res, '°')
       end
 
+      # @param direction - angle from the North by clock, e.g. '90' means 'to the east'
+      # @param distance - km, e.g. 100
+      #
+      # @return [Reality::Geo::Coord]
       def endpoint(direction, distance)
         res = Geokit::LatLng.endpoint(to_s, direction.to_f, distance.to_f)
         Coord.new res.lat, res.lng
       end
 
+      # @param point - Coordinates, e.g "50.45,30.52", [50.45, 30.52], Coord or Entity instance
+      # @param radius - km, e.g. 10
+      #
+      # @return [true, false]
       def close_to?(point, radius)
         area = Geokit::Bounds.from_point_and_radius(to_s, radius.to_f)
         area.contains?(normalize_point(point).to_s)
       end
 
+      # Latitude in "degrees minutes seconds" format
+      #
+      # @return [Array]
       def lat_dms(direction = true)
         seconds = (lat.abs % 1.0) * 3600.0
         d, m, s = lat.to_i, (seconds / 60).to_i, (seconds % 60)
@@ -81,6 +119,9 @@ module Reality
         end
       end
 
+      # Longitude in "degrees minutes seconds" format
+      #
+      # @return [Array]
       def lng_dms(direction = true)
         seconds = (lng.abs % 1.0) * 3600.0
         d, m, s = lng.to_i, (seconds / 60).to_i, (seconds % 60)
@@ -94,13 +135,18 @@ module Reality
       def to_s
         "#{lat.to_f},#{lng.to_f}"
       end
+      alias_method :latlng, :to_s
+
+      def to_h
+        {lat: lat.to_f, lng: lng.to_f}
+      end
 
       def ==(other)
         other.is_a?(self.class) && lat == other.lat && lng == self.lng
       end
 
       def inspect
-        "#<%s(%i°%i′%i″%s,%i°%i′%i″%s)>" % [self.class, *lat_dms, *lng_dms]
+        "#<%s(%i°%i′%.0f″%s,%i°%i′%.0f″%s)>" % [self.class, *lat_dms, *lng_dms]
       end
 
       def sunrise(date = Date.today)
@@ -111,8 +157,23 @@ module Reality
         SunTimes.new.set(date, lat.to_f, lng.to_f)
       end
 
+      # Links to popular maps sites with this point marked
+      # Maps: openstreetmap, google maps, wikimapia
+      #
+      # @return [Hash]
+      def links
+        param = {lat: lat.to_f, lng: lng.to_f, latlng: latlng}
+        Hashie::Mash.new(EXTERNAL_LINKS.map{|key, pattern| [key, pattern % param]}.to_h)
+      end
+
       private
 
+      EXTERNAL_LINKS = {
+        osm: "https://www.openstreetmap.org/?mlat=%{lat}&mlon=%{lng}&zoom=12&layers=M",
+        google: "https://maps.google.com/maps?ll=%{latlng}&q=%{latlng}&hl=en&t=m&z=12",
+        wikimapia: "http://wikimapia.org/#lang=en&lat=%{lat}&lon=%{lng}&z=12&m=w"
+      }
+
       def normalize_point(point)
         return point if point.is_a?(Coord)
         point.coord if point.respond_to?(:coord)

data/lib/reality/list.rb

@@ -1,16 +1,59 @@
 module Reality
+  # List is subclass of Array, which allows effective entities storing
+  # and loading.
+  #
+  # You can create list from entities or just their names:
+  #
+  # ```ruby
+  # Reality::List.new('Argentina', 'Ukraine')
+  # # => #<Reality::List[Argentina?, Ukraine?]>
+  # ```
+  #
+  # ...or from existing entities:
+  #
+  # ```ruby
+  # Reality::List.new(Reality::Entity.new('Argentina'), Reality::Entity.new('Ukraine'))
+  # # => #<Reality::List[Argentina?, Ukraine?]>
+  # ```
+  #
+  # List is useful for compact inspect (see above), and for effective
+  # batch loading (see {#load!}).
+  #
+  # Also, List is smart enough to remain List on multiple enumerable
+  # methods like `#select`, `#reject`, `#map` and so on:
+  #
+  # ```ruby
+  # Reality::List.new('Argentina', 'Bolivia', 'Chile').sample(2)
+  # # => #<Reality::List[Chile?, Argentina?]>
+  #
+  # Reality::List.new('Argentina', 'Bolivia', 'Chile').load!.map(&:capital)
+  # # => #<Reality::List[Buenos Aires?, La Paz?, Santiago?]>
+  # ```
+  #
   class List < Array
     using Refinements
-    
+
+    # Creates List from a set of entity names or entity objects.
+    # Also aliased as `Reality::List()` method.
+    #
     def initialize(*names)
       super names.map(&method(:coerce))
     end
 
+    # Loads all entities in batch. Optimized to make as few requests
+    # as possible. Typically, when you want to load several entities
+    #
+    # @return [self]
     def load!
-      partition(&:wikidata_id).tap{|wd, wp|
+      compact.partition(&:wikidata_id).tap{|wd, wp|
           load_by_wikipedia(wp)
           load_by_wikidata(wd)
         }
+      # try to fallback to labels:
+      compact.reject(&:loaded?).tap{|entities|
+        load_by_wikidata_labels(entities)
+      }
+      
       self
     end
 
@@ -21,10 +64,24 @@ module Reality
       }
     end
 
+    # @return [String]
     def inspect
-      "#<#{self.class.name}[#{map(&:to_s?).join(', ')}]>"
+      "#<#{self.class.name}[#{map{|e| e ? e.to_s? : e.inspect}.join(', ')}]>"
     end
 
+    # Prints compact description of the list. Implicitly loads all list
+    # if not loaded.
+    #
+    # ```ruby
+    # Reality::List.new('Argentina', 'Bolivia', 'Chile').describe
+    # # -------------------------
+    # # #<Reality::List(3 items)>
+    # # -------------------------
+    # #   keys: adm_divisions (3), area (3), calling_code (3), capital (3), continent (3), coord (3), country (3), created_at (3), currency (3), gdp_nominal (3), gdp_ppp (3), head_of_government (2), head_of_state (3), highest_point (3), iso2_code (3), iso3_code (3), long_name (3), neighbours (3), official_website (1), organizations (3), part_of (3), population (3), tld (3), tz_offset (3)
+    # #  types: country (3)
+    # ```
+    #
+    # @return [nil]
     def describe
       load! unless all?(&:loaded?)
       
@@ -50,7 +107,7 @@ module Reality
       
       pages = Infoboxer.wp.get_h(*entities.map(&:name))
       datum = Wikidata::Entity.
-        fetch_list(*pages.values.compact.map(&:title))
+        by_wikititle(*pages.values.compact.map(&:title))
 
       entities.each do |entity|
         page = pages[entity.name]
@@ -63,7 +120,7 @@ module Reality
       return if entities.empty?
       
       datum = Wikidata::Entity.
-        fetch_list_by_id(*entities.map(&:wikidata_id))
+        by_id(*entities.map(&:wikidata_id))
       pages = Infoboxer.wp.
         get_h(*datum.values.compact.map(&:en_wikipage).compact)
       entities.each do |entity|
@@ -73,8 +130,19 @@ module Reality
       end
     end
 
+    def load_by_wikidata_labels(entities)
+      return if entities.empty?
+      
+      datum = Wikidata::Entity.
+        by_label(*entities.map(&:name))
+      entities.each do |entity|
+        data = datum[entity.name]
+        entity.setup!(wikidata: data)
+      end
+    end
+
     def ensure_type(arr)
-      if arr.kind_of?(Array) && arr.all?{|e| e.is_a?(Entity)}
+      if arr.kind_of?(Array) && arr.all?{|e| e.nil? || e.is_a?(Entity)}
         List[*arr]
       else
         arr
@@ -83,6 +151,8 @@ module Reality
 
     def coerce(val)
       case val
+      when nil
+        val
       when String
         Entity.new(val)
       when Entity

data/lib/reality/measure.rb

@@ -1,4 +1,10 @@
 module Reality
+  # Wrapper for numeric values.
+  # Example:
+  #   Reality::Entity.new('Ukraine', load: true).area
+  #    => #<Reality::Measure(603,500 km²)>
+  # Keeps information about value unit
+  # Allows coercion and general Numeric operations
   class Measure
     %w[unit].each{|mod| require_relative "measure/#{mod}"}
     
@@ -7,7 +13,9 @@ module Reality
     def Measure.coerce(amount, unit)
       amount && unit && new(amount, unit)
     end
-    
+
+    # @param amount - numeric value, e.g. 100.5
+    # @param unit - can be any string, e.g. 'km', '$'
     def initialize(amount, unit)
       @amount, @unit = Rational(amount), Unit.parse(unit)
     end
@@ -18,10 +26,6 @@ module Reality
       amount <=> other.amount
     end
 
-    def ==(other)
-      amount == other.amount && unit == other.unit
-    end
-
     def -@
       self.class.new(-amount, unit)
     end
@@ -65,12 +69,20 @@ module Reality
       (num-1).times.inject(self){|res| res*self}
     end
 
+    def abs
+      self.class.new(amount.abs, unit)
+    end
+
     include Comparable
 
     def to_s
       '%s%s' % [Util::Format.number(amount), unit]
     end
 
+    def to_h
+      {amount: amount.to_f, unit: unit.to_s}
+    end
+
     def to_f
       amount.to_f
     end
@@ -91,8 +103,4 @@ module Reality
       end
     end
   end
-
-  def Reality.Measure(*arg)
-    Measure.new(*arg)
-  end
 end