reality 0.0.3 → 0.0.4

data/lib/reality/methods.rb

@@ -2,12 +2,16 @@ require 'forwardable'
 
 module Reality
   module Methods
-    def Entity(name, entity_class = nil)
-      Entity.load(name, entity_class)
+    def Entity(name)
+      Entity.load(name)
     end
 
     def List(*names)
-      Entity::List.new(*names)
+      List.new(*names)
+    end
+
+    def Measure(*arg)
+      Measure.new(*arg)
     end
 
     extend Forwardable

data/lib/reality/names.rb

@@ -0,0 +1,46 @@
+module Reality
+  # This optional and higly experimental module allows treat ALL objects
+  # available with Reality, as Ruby constants (via redefined `const_missing`).
+  # This practice may seem questionable, so use it wisely!
+  #
+  # You can just use this module on its own:
+  #
+  # ```ruby
+  # Reality::Names::Argentina
+  # # => #<Reality::Entity(Argentina):country>
+  # ```
+  #
+  # ...Or just include it elsewhere:
+  #
+  # ```ruby
+  # include Reality::Names
+  #
+  # Argentina
+  # # => #<Reality::Entity(Argentina):country>
+  # ```
+  #
+  # Multi-word entities can also be called:
+  #
+  # ```ruby
+  # BuenosAires
+  # # => #<Reality::Entity(Buenos Aires):city>
+  # ```
+  #
+  # Though, more complicated entity names (with punctuations) can't be
+  # accessed this way.
+  #
+  module Names
+    def Names.const_missing(symbol)
+      name = symbol.to_s.
+        gsub('_', ' ').
+        gsub(/([a-z])([A-Z])/, '\1 \2')
+      Reality::Entity(name) or super
+    end
+
+    def Names.included(other)
+      other.define_singleton_method(:const_missing){|name|
+        Reality::Names.const_missing(name)
+      }
+    end
+  end
+end

data/lib/reality/refinements.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module Refinements
     refine Object do
       def derp

data/lib/reality/tz_offset.rb

@@ -1,11 +1,46 @@
 module Reality
+  # Simple class representing timezone offset (in minutes). Knows nothing
+  # about timezone name, DST or other complications, but useful when ONLY
+  # offset is known for some {Entity}.
+  #
+  # Usage:
+  #
+  # ```ruby
+  # # As entity property:
+  # Reality::Entity('Beijing').tz_offset
+  # # => #<Reality::TZOffset(UTC+08:00)>
+  #
+  # # On itself:
+  # o = Reality::TZOffset.parse('UTC+3')
+  # # => #<Reality::TZOffset(UTC+03:00)>
+  #
+  # o.now
+  # # => 2016-04-16 19:01:40 +0300
+  # o.local(2016, 4, 1, 20, 30)
+  # # => 2016-04-01 20:30:00 +0300
+  # o.convert(Time.now)
+  # # => 2016-04-16 19:02:22 +0300
+  # ```
+  #
   class TZOffset
     using Refinements
-    
+
+    # Number of minutes in offset.
+    #
+    # @return [Fixnum]
     attr_reader :minutes
 
+    # @private
     MINUSES = /[−—–]/
 
+    # Parses TZOffset from string. Understands several options like:
+    #
+    # * `GMT` (not all TZ names, only those Ruby itself knows about);
+    # * `UTC+3` (or `GMT+3`);
+    # * `+03:30`;
+    # * ..and several combinations.
+    #
+    # @return [TZOffset]
     def self.parse(text)
       text = text.gsub(MINUSES, '-')
       
@@ -13,24 +48,32 @@ module Reality
       when /^[A-Z]{3}$/
         Time.zone_offset(text)
       when /^(?:UTC|GMT)?([+-]\d{1,2}:?\d{2})$/
-        Time.zone_offset($1)
+        offset = $1
+        Time.zone_offset(offset.sub(/^([+-])(\d):/, '\10\2:'))
       when /^(?:UTC|GMT)?([+-]\d{1,2})/
         $1.to_i * 3600
       end.derp{|sec| sec && new(sec / 60)}
     end
-    
+
+    # Constructs offset from number of minutes. In most cases, you don't
+    # want to use it, but rather {TZOffset.parse}.
+    #
+    # @param minutes [Fixnum] Number of minutes in offset.
     def initialize(minutes)
       @minutes = minutes
     end
 
+    # @return [String]
     def inspect
       '#<%s(UTC%+03i:%02i)>' % [self.class.name, *minutes.divmod(60)]
     end
 
+    # @return [String]
     def to_s
       '%+03i:%02i' % minutes.divmod(60)
     end
 
+    # @return [Boolean]
     def <=>(other)
       other.is_a?(TZOffset) or fail ArgumentError, "Can't compare TZOffset with #{other.class}"
       minutes <=> other.minutes
@@ -38,18 +81,28 @@ module Reality
 
     include Comparable
 
+    # Like Ruby's `Time.now`, but in desired offset.
+    #
+    # @return [Time] Current time in that offset.
     def now
       convert(Time.now)
     end
 
+    # Like Ruby's `Time.local`, but in desired offset.
+    #
+    # @return [Time] Constructed time in that offset.
     def local(*values)
       values << 0 until values.count == 6
       Time.new(*values, to_s)
     end
 
-    # FIXME: usec are lost
+    # Converts `tm` into correct offset.
+    #
+    # @param tm [Time] Time object to convert (with any offset);
+    # @return [Time] Converted object.
     def convert(tm)
       pattern = tm.utc + minutes * 60
+      # FIXME: usec are lost
       Time.new(
         pattern.year,
         pattern.month,

data/lib/reality/util/formatters.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module Util
     module Format
       module_function

data/lib/reality/util/parsers.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module Util
     module Parse
       module_function

data/lib/reality/version.rb

@@ -1,6 +1,6 @@
 module Reality
   MAJOR = 0
   MINOR = 0
-  PATCH = 3
+  PATCH = 4
   VERSION = [MINOR, MAJOR, PATCH].join('.')
 end

data/lib/reality/wikidata.rb

@@ -1,6 +1,9 @@
+require_relative 'wikidata/query'
+
 module Reality
   using Reality::Refinements
-  
+
+  # @private
   module Wikidata
     class Link
       attr_reader :id, :label
@@ -18,198 +21,38 @@ module Reality
       end
     end
 
-    # FIXME: I should be burn in hell for this mess. But it works. Somehow.
     class Entity
-      PREFIX = %Q{
-        PREFIX wikibase: <http://wikiba.se/ontology#>
-        PREFIX wd: <http://www.wikidata.org/entity/> 
-        PREFIX wdt: <http://www.wikidata.org/prop/direct/>
-        PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
-        PREFIX p: <http://www.wikidata.org/prop/>
-        PREFIX v: <http://www.wikidata.org/prop/statement/>
-        PREFIX schema: <http://schema.org/>
-      }
-      
-      SINGLE_QUERY = %Q{
-        #{PREFIX}
-        
-        SELECT ?id ?p ?o ?oLabel  WHERE {
-          <https://en.wikipedia.org/wiki/%{title}> schema:about ?id .
-          {
-            ?id ?p ?o .
-            FILTER(STRSTARTS(STR(?p), "http://www.wikidata.org/prop/direct/"))
-          } union {
-            ?id ?p ?o .
-            filter(langMatches(lang(?o), "EN")).
-            filter(?p = rdfs:label)
-          }
-          SERVICE wikibase:label {
-            bd:serviceParam wikibase:language "en" .
-          }
-         }
-      }
-
-      ID_QUERY = %Q{
-        #{PREFIX}
-        
-        SELECT ?id ?p ?o ?oLabel  WHERE {
-          bind(wd:%{id} as ?id)
-          {
-            ?id ?p ?o .
-            FILTER(
-              STRSTARTS(STR(?p), "http://www.wikidata.org/prop/direct/") ||
-              (?p = rdfs:label && langMatches(lang(?o), "EN"))
-            )
-          } union {
-            bind(schema:about as ?p) .
-            ?o schema:about ?id .
-            filter(strstarts(str(?o), "https://en.wikipedia.org/wiki/"))
-          }
-          SERVICE wikibase:label {
-            bd:serviceParam wikibase:language "en" .
-          }
-         }
-      }
-
-      MULTIPLE_QUERY = %Q{
-        #{PREFIX}
-
-        SELECT ?id ?p ?o ?oLabel  WHERE {
-          %{selectors} .
-          {
-            ?id ?p ?o .
-            FILTER(
-              STRSTARTS(STR(?p), "http://www.wikidata.org/prop/direct/") ||
-              (?p = rdfs:label && langMatches(lang(?o), "EN"))
-            )
-          } union {
-            bind(schema:about as ?p) .
-            ?o schema:about ?id .
-            filter(strstarts(str(?o), "https://en.wikipedia.org/wiki/"))
-          }
-          SERVICE wikibase:label {
-            bd:serviceParam wikibase:language "en" .
-          }
-         }
-      }
-      MULTIPLE_IDS_QUERY = %Q{
-        #{PREFIX}
-
-        SELECT ?id ?p ?o ?oLabel  WHERE {
-          %{selectors} .
-          {
-            ?id ?p ?o .
-            FILTER(
-              STRSTARTS(STR(?p), "http://www.wikidata.org/prop/direct/") ||
-              (?p = rdfs:label && langMatches(lang(?o), "EN"))
-            )
-          } union {
-            bind(schema:about as ?p) .
-            ?o schema:about ?id .
-            filter(strstarts(str(?o), "https://en.wikipedia.org/wiki/"))
-          }
-          SERVICE wikibase:label {
-            bd:serviceParam wikibase:language "en" .
-          }
-         }
-      }
-      SELECTOR = %Q{
-        {
-          <https://en.wikipedia.org/wiki/%{title}> schema:about ?id
-        }
-      }
-      IDSELECTOR = %Q{
-        {
-          BIND(wd:%{id} as ?id)
-        }
-      }
-
-      UNSAFE = Regexp.union(URI::UNSAFE, /[,()']/)
-      
       class << self
-        def faraday
-          @faraday ||= Faraday.new(url: 'https://query.wikidata.org/sparql'){|f|
-            f.adapter Faraday.default_adapter
-          }
+        def by_wikititle(*titles)
+          Query.by_wikititle(*titles)
         end
 
-        def fetch(title)
-          title = URI.escape(title, UNSAFE)
-          faraday.get('', query: SINGLE_QUERY % {title: title}, format: :json).
-            derp{|res| from_sparql(res.body, subject: 'id', predicate: 'p', object: 'o', object_label: 'oLabel')}
+        def by_id(*ids)
+          Query.by_id(*ids)
         end
 
-        def fetch_by_id(id)
-          faraday.get('', query: ID_QUERY % {id: id}, format: :json).
-            derp{|res| from_sparql(res.body, subject: 'id', predicate: 'p', object: 'o', object_label: 'oLabel')}.
-            first
+        def by_label(*labels)
+          Query.by_label(*labels)
         end
 
-        WIKIURL = 'https://en.wikipedia.org/wiki/%{title}'
-
-        MAX_SLICE = 20
-
-        def fetch_list(*titles)
-          titles.each_slice(MAX_SLICE).map{|titles_chunk|
-            fetch_small_list(*titles_chunk)
-          }.inject(:merge)
+        def one_by_wikititle(title)
+          by_wikititle(title).values.first
         end
 
-        def fetch_list_by_id(*ids)
-          ids.each_slice(MAX_SLICE).map{|ids_chunk|
-            fetch_small_idlist(*ids_chunk)
-          }.inject(:merge)
+        def one_by_id(id)
+          by_id(id).values.first
         end
 
-        def fetch_small_list(*titles)
-          titles.
-            map{|t| SELECTOR % {title: URI.escape(t, UNSAFE)}}.
-            join(' UNION ').
-            derp{|selectors| MULTIPLE_QUERY % {selectors: selectors}}.
-            derp{|query|
-              faraday.get('', query: query, format: :json)
-            }.
-            derp{|res|
-              from_sparql(
-                res.body,
-                subject: 'id',
-                predicate: 'p',
-                object: 'o',
-                object_label: 'oLabel')
-            }.
-            map{|e|
-              [e.en_wikipage, e]
-            }.to_h
+        def one_by_label(label)
+          by_label(label).values.first
         end
 
-
-        def fetch_small_idlist(*ids)
-          ids.
-            map{|i| IDSELECTOR % {id: i}}.
-            join(' UNION ').
-            derp{|selectors| MULTIPLE_IDS_QUERY % {selectors: selectors}}.
-            derp{|query|
-              faraday.get('', query: query, format: :json)
-            }.
-            derp{|res|
-              from_sparql(
-                res.body,
-                subject: 'id',
-                predicate: 'p',
-                object: 'o',
-                object_label: 'oLabel')
-            }.
-            map{|e|
-              [e.id, e]
-            }.to_h
-        end
-        
-        def from_sparql(sparql_json, subject: 'subject', predicate: 'predicate', object: 'object', object_label: 'object_label')
+        def from_sparql(sparql_json)
           JSON.parse(sparql_json)['results']['bindings'].map{|row|
             [
-              row[subject]['value'].sub('http://www.wikidata.org/entity/', ''),
-              row[predicate]['value'].sub('http://www.wikidata.org/prop/direct/', ''),
-              row[object].merge('label' => row[object_label]['value'])
+              row['s']['value'].sub('http://www.wikidata.org/entity/', ''),
+              row['p']['value'].sub('http://www.wikidata.org/prop/direct/', ''),
+              row['o'].merge('label' => row['oLabel']['value'])
             ]
           }.group_by(&:first).
           map{|id, rows|
@@ -223,6 +66,7 @@ module Reality
             to_h
         end
 
+        # FIXME: move all parse_* to util/parsers or wikidata/parsers
         def parse_value(hash)
           case hash['type']
           when 'literal'
@@ -278,6 +122,10 @@ module Reality
         @predicates[pred]
       end
 
+      def id_i
+        id.sub('Q', '').to_i
+      end
+
       def label
         self['http://www.w3.org/2000/01/rdf-schema#label'].first
       end