reality 0.0.3 → 0.0.4

data/bin/reality

@@ -1,16 +1,13 @@
 #!/usr/bin/env ruby
+
 require 'rubygems'
 require 'reality'
-require 'reality/pretty_inspect'
-require 'reality/shortcuts'
+require 'reality/command_line'
 
-Reality.configure :demo
+reality_runner = Reality::CommandLine.new
 
-class << self
-  # including it ONLY into the main object, not Kernel
-  include Reality::Methods
+if reality_runner.interactive?
+  reality_runner.run_interactive_shell
+else
+  puts reality_runner.results
 end
-
-require 'irb'
-ARGV.shift until ARGV.empty?
-IRB.start

data/config/demo.yml

@@ -1,3 +1,4 @@
 keys:
   open_weather_map: '90d73c1188829195d023b5a5fc6399e1'
   geonames: 'realitygeo'
+  quandl: JU6KEPEkqqqfVkcpa9MU

data/lib/reality.rb

@@ -1,7 +1,14 @@
 require 'infoboxer'
 require 'yaml'
 
+# Reality is library for accessing all world data, starting from Wikipedia.
+#
+# Look at {Entity} for good starting point.
+#
+# You also may want to navigate [Getting started](https://github.com/molybdenum-99/reality/wiki/Getting-started)
+# page in our wiki.
 module Reality
+  # @private
   def self.require_(*modules)
     modules.flatten.flat_map{|pattern|
       Dir[File.expand_path("../reality/#{pattern}.rb", __FILE__)]
@@ -19,16 +26,14 @@ module Reality
   # entities
   require_ %w[entity list]
   require_ %w[definitions/*]
-  require_ %w[methods]
+  require_ %w[methods names]
 
+  include Methods
   extend Methods
 
-  def self.reload!
-    require_ %w[definitions/*]
-  end
-
   # extras
-  require_ %w[extras/open_weather_map extras/geonames]
+  require_ %w[extras/open_weather_map extras/geonames extras/quandl]
   include Extras::OpenWeatherMap
   include Extras::Geonames
+  include Extras::Quandl
 end

data/lib/reality/command_line.rb

@@ -0,0 +1,124 @@
+require 'optparse'
+require 'reality/pretty_inspect'
+
+module Reality
+  # This module contains services used from `bin/reality`, you typically
+  # don't need to think of it.
+  class CommandLine
+    attr_accessor :search_term, :article, :commands, :options, :errors
+
+    def initialize
+      parse_arguments
+    end
+
+    def self.display_usage
+      puts "usage: reality \"[search-string]\" [entity-command] [chained-command(s) ...]"
+    end
+
+    def interactive?
+      !!self.options[:interactive]
+    end
+
+    def article_found?
+      !self.article.nil?
+    end
+
+    def subcommand_for(object, subcommand)
+      if object.respond_to?(subcommand.to_sym)
+        puts "Calling #{subcommand} on #{object.inspect}" if ENV['DEBUG']
+        object.send(subcommand.to_sym)
+      else
+        self.errors << "#{object} doesn't respond to #{subcommand}"
+        nil
+      end
+    end
+
+    def results
+      return "Nothing found for: #{self.search_term}" unless self.article_found?
+      puts "Attempting entity chain: #{self.commands} on #{self.article.inspect}" if ENV['DEBUG']
+
+      result = subcommand_for(self.article, self.commands.shift)
+
+      while subcommand = self.commands.shift
+        result = subcommand_for(result, subcommand)
+      end
+
+      if self.errors.any?
+        "Error: #{ self.errors.join("\n") }"
+      else
+        result
+      end
+    end
+
+    def run_interactive_shell
+      require 'irb'
+      require 'reality/shortcuts'
+      ::ARGV.clear
+
+      # FIXME: can't see better means to have everything accessible & included
+      #IRB::ExtendCommandBundle.include(Reality)
+      TOPLEVEL_BINDING.receiver.send(:include, Reality)
+
+      IRB.setup nil
+
+      IRB.conf[:IRB_NAME] = 'reality'
+
+      IRB.conf[:PROMPT] = {}
+      IRB.conf[:PROMPT][:REALITY] = {
+        :PROMPT_I => '%N:%03n:%i> ',
+        :PROMPT_S => '%N:%03n:%i%l ',
+        :PROMPT_C => '%N:%03n:%i* ',
+        :RETURN => "# => %s\n"
+      }
+      IRB.conf[:PROMPT_MODE] = :REALITY
+      IRB.conf[:RC] = false
+
+      IRB.conf[:MAIN_CONTEXT] = IRB::Irb.new.context
+
+      require 'irb/ext/multi-irb'
+      IRB.irb nil, TOPLEVEL_BINDING
+    end
+
+    private
+
+    def parse_options
+      self.options = {}
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: reality [options] [search-string] [entity-command] [chained-command(s) ...]"
+
+        opts.on_tail("-i", "--interactive", "Run an interactive IRB session with Reality pre-configured for querying.") do
+          self.options[:interactive] = true
+        end
+
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+      end.parse!
+    end
+
+    def parse_arguments
+      parse_options
+      self.search_term = "#{::ARGV.shift}"
+
+      if self.options[:interactive]
+        Reality.configure :demo
+      elsif self.search_term.length > 0
+        self.article = Reality::Entity(self.search_term)
+        self.errors  = []
+
+        if ::ARGV.count > 0
+          self.commands = ::ARGV.map(&:to_sym)
+        else
+          self.commands = [:describe]
+        end
+
+        Reality.configure :demo
+      else
+        self.class.display_usage
+        exit
+      end
+    end
+  end
+end

data/lib/reality/config.rb

@@ -32,15 +32,22 @@ module Reality
     end
   end
 
+  # @private
   def Reality.config
     @config ||= Config.new
   end
 
-  def Reality.configure(cfg)
-    if cfg == :demo
+  # Allows to configure Reality.
+  #
+  # @param path [String] Path to config. See `config/demo.yml` for config
+  #   sample. Also, you can use `:demo` value for config Reality with
+  #   demo keys.
+  #
+  def Reality.configure(path)
+    if path == :demo
       config.load(File.expand_path('../../../config/demo.yml', __FILE__))
     else
-      config.load(cfg)
+      config.load(path)
     end
   end
 end

data/lib/reality/definitions/helpers.rb

@@ -1,6 +1,7 @@
 require 'time_boots'
 
 module Reality
+  # @private
   # Just assorted "cool things", included into all entities
   # Subject to change/refactor
   module Helpers

data/lib/reality/definitions/wikidata.rb

@@ -9,6 +9,7 @@ module Reality
     predicate 'P571', :created_at, :date # TODO: aliases: :founded_at, :incepted_at
 
     predicate 'P740', :location, :entity
+    predicate 'P585', :date    , :date # TODO: maybe :datetime?
 
     predicate 'P737', :influenced_by, [:entity]
 
@@ -30,13 +31,17 @@ module Reality
     predicate 'P2046', :area, :measure, unit: 'km²'
     predicate 'P2044', :elevation, :measure, unit: 'm'
 
-    # Economy and socilogy ---------------------------------------------
+    predicate 'P969', :street_address, :string
+    predicate 'P131', :located_in, :entity
+
+    # Economy and sociology ---------------------------------------------
     predicate 'P38', :currency, :entity
     predicate 'P463', :organizations, [:entity]
     predicate 'P2131', :gdp_nominal, :measure, unit: '$'
     predicate 'P1082',:population, :measure, unit: 'person'
 
     predicate 'P35', :head_of_state, :entity
+    predicate 'P6', :head_of_government, :entity
 
     # References -------------------------------------------------------
     predicate 'P297', :iso2_code, :string
@@ -101,5 +106,9 @@ module Reality
     # Fictional entities -----------------------------------------------
     predicate 'P1080', :fictional_universe, :string
     predicate 'P1441', :present_in_works, [:entity]
+
+    # Internet ---------------------------------------------------------
+    predicate 'P856', :official_website, :string
+    predicate 'P2002', :twitter_username, :string
   end
 end

data/lib/reality/definitions/wikipedia_character.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module Character
     extend Entity::WikipediaType
 

data/lib/reality/definitions/wikipedia_city.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module City
     extend Entity::WikipediaType
 

data/lib/reality/definitions/wikipedia_continent.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module Continent
     extend Entity::WikipediaType
 

data/lib/reality/definitions/wikipedia_country.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module Country
     extend Entity::WikipediaType
 

data/lib/reality/definitions/wikipedia_musical_artist.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module MusicalArtist
     extend Entity::WikipediaType
 

data/lib/reality/definitions/wikipedia_person.rb

@@ -1,4 +1,5 @@
 module Reality
+  # @private
   module Person
     extend Entity::WikipediaType
 

data/lib/reality/entity.rb

@@ -1,25 +1,120 @@
 module Reality
   require_ %w[entity/coercion entity/wikidata_predicates entity/wikipedia_type]
-  
+
+  # Reality::Entity is a main concept of the library. It represents errr
+  # well, some entity from real world. You can think of it as of rough
+  # equivalent of Wikipedia article.
+  #
+  # Wiki has more details about entity [concept](https://github.com/molybdenum-99/reality/wiki/Entity)
+  # and [internals](https://github.com/molybdenum-99/reality/wiki/Entity%20internals).
+  #
+  # The easiest way to have an entity is to instantiate is as {Entity.load}
+  # (also aliased as `Reality.Entity()` method): you'll just have your
+  # entity already _loaded_ from all possible data sources (or `nil` if
+  # neither of them knows about it):
+  #
+  # ```ruby
+  # argentina = Reality::Entity('Argentina')
+  # # => #<Reality::Entity(Argentina):country>
+  # ```
+  # Then, you can use {#describe} to see what properties entity has, and
+  # call any of them by name, like `argentina.capital`.
+  #
+  # Or you can create not loaded entities with just {#initialize} (it
+  # may be useful when you want to further batch-load several of them 
+  # through {List#load!}).
+  #
   class Entity
     using Refinements
-    
-    attr_reader :wikipage, :wikidata, :wikidata_id
-    attr_reader :values, :wikipedia_type
-    
-    def initialize(name, wikipage: nil, wikidata: nil, wikidata_id: nil, load: false)
+
+    # Instance of Infoboxer's [page](http://www.rubydoc.info/gems/infoboxer/Infoboxer/MediaWiki/Page).
+    #
+    # Pretty useful on its own:
+    #
+    # ```ruby
+    # puts Reality::Entity('Argentina').wikipage.intro
+    # # Argentina (ˌɑrdʒənˈtiːnə; aɾxenˈtina), officially the Argentine Republic (República Argentina), is a federal republic....
+    # ```
+    #
+    # Refer to [Infoboxer's documentation](http://www.rubydoc.info/gems/infoboxer/Infoboxer/MediaWiki/Page)
+    # for details.
+    #
+    # @return [Infoboxer::MediaWiki::Page]
+    attr_reader :wikipage
+
+    # All values extracted from data sources, in structured form.
+    # You can pretty-previes them via {#describe}, as well as work with
+    # separate values with method call (see {#method_missing}).
+    #
+    # @return [Hash<Symbol, Object>]
+    attr_reader :values
+
+    # @private
+    attr_reader :wikipedia_type, :wikidata, :wikidata_id
+
+    # Creates new entity. Initially, entity is _not_ loaded from datasources,
+    # it's just a name. If you want to receive a loaded entity with one
+    # statement, take a look at {Entity.load}, which does `new` + `load!`
+    # under the hoods.
+    #
+    # ```
+    # e = Reality::Entity.new('Mississippi')
+    # # => #<Reality::Entity?(Mississippi)>
+    # e.loaded?
+    # # => false
+    # e.values
+    # # => {}
+    # ```
+    #
+    # @param name [String] Name of the entity you want. Basically, it's
+    #   Wikipedia page name for some concept. Not-so-basically, please
+    #   refer to [names explanation](https://github.com/molybdenum-99/reality/wiki/Entity#entity-names)
+    #   in our wiki.
+    # @param wikidata_id [String] Used mostly internally (when not only
+    #   entity name, but also wikidata id is known; this happens on loading
+    #   entities by references from other entities).
+    def initialize(name, wikidata_id: nil)
       @name = name
-      @wikipage, @wikidata, @wikidata_id = wikipage, wikidata, wikidata_id
+      @wikidata_id = wikidata_id
       @values = {}
-      
-      load! if load
-      after_load if @wikipage
     end
 
+    # Entity name string. For not loaded entity returns the name by which it
+    # was created. For loaded, it's correct name of Wikipedia page:
+    #
+    # ```ruby
+    # e = Reality::Entity.new('Einstein')
+    # # => #<Reality::Entity?(Einstein)>
+    # e.name
+    # # => "Einstein"
+    # e.load!
+    # # => #<Reality::Entity(Albert Einstein)>
+    # e.name
+    # # => "Albert Einstein"
+    # ```
+    #
+    # @return [String]
     def name
       @wikipage ? @wikipage.title : @name
     end
 
+    # Returns entity brief representation. Things to note:
+    #
+    # ```
+    # #<Reality::Entity?(Argentina)>
+    #                  ^    ^
+    #                  |  Entity name
+    #             Sign of not
+    #             loaded entity
+    #
+    # #<Reality::Entity(Argentina):country>
+    #                  ^             ^
+    #                  |           Name of "additional type" (to be documented...)
+    #            No question mark:
+    #            entity is loaded
+    # ```
+    #
+    # @return [String]
     def inspect
       if @wikipedia_type && @wikipedia_type.symbol
         "#<#{self.class}#{loaded? ? '' : '?'}(#{name}):#{@wikipedia_type.symbol}>"
@@ -28,11 +123,27 @@ module Reality
       end
     end
 
-    def _describe
-      load! unless loaded?
-      Util::Format.describe(inspect, values.map{|k,v| [k, v.inspect]})
-    end
-
+    # Prints general object state and all properties with values
+    #
+    # Example:
+    #
+    # ```
+    # $> Reality::Entity.new('Mississippi').describe
+    #   Output:
+    #   -------------------------------
+    #   <Reality::Entity(Mississippi)>
+    #   -------------------------------
+    #          capital: #<Reality::Entity?(Jackson)>
+    #            coord: #<Reality::Geo::Coord(33°0′0″N,90°0′0″W)>
+    #          country: #<Reality::Entity?(United States of America)>
+    #       created_at: Wed, 10 Dec 1817
+    #       located_in: #<Reality::Entity?(United States of America)>
+    #       neighbours: #<Reality::List[Alabama?, Tennessee?, Louisiana?, Arkansas?]>
+    # official_website: "http://www.mississippi.gov"
+    #        tz_offset: #<Reality::TZOffset(UTC-06:00)>
+    # ```
+    #
+    # @return [nil]
     def describe
       puts _describe
       nil
@@ -42,39 +153,70 @@ module Reality
       name
     end
 
+    # @private
     def to_s?
       # FIXME: fuuuuuuuu
       "#{name.include?(',') ? '"' + name + '"' : name}#{loaded? ? '' : '?'}"
     end
 
+    # Loads entity data from all external sources.
+    #
+    # Note that this method is called implicitly on {#method_missing},
+    # {#describe} or {#to_h}.
+    #
+    # Note also that if you need several entities to be loaded, its much
+    # more effective to have them grouped into {List} and batch-loaded
+    # via {List#load!}.
+    #
+    # @return [self]
     def load!
       if @wikidata_id
-        @wikidata = Wikidata::Entity.fetch_by_id(@wikidata_id)
+        @wikidata = Wikidata::Entity.one_by_id(@wikidata_id)
         if @wikidata && @wikidata.en_wikipage
           @wikipage = Infoboxer.wikipedia.get(@wikidata.en_wikipage)
         end
       else
         @wikipage = Infoboxer.wikipedia.get(name)
-        if @wikipage
-          @wikidata = Wikidata::Entity.fetch(@wikipage.title).first
+        @wikidata = if @wikipage
+          Wikidata::Entity.one_by_wikititle(@wikipage.title)
+        else
+          Wikidata::Entity.one_by_label(name)
         end
       end
       after_load
       self
     end
 
+    # @private
     def setup!(wikipage: nil, wikidata: nil)
       @wikipage, @wikidata = wikipage, wikidata
-      after_load if @wikipage
+      after_load if @wikipage || @wikidata
+      self
     end
 
+    # Returns `true` if entity is loaded already.
+    #
+    # @return [Boolean]
     def loaded?
-      !!@wikipage
+      !!(@wikipage || @wikidata)
     end
 
+    # @private
     # Don't try to convert me!
     UNSUPPORTED_METHODS = [:to_hash, :to_ary, :to_a, :to_str, :to_int]
 
+    # Entity handles `method_missing` this way:
+    #
+    # * loads itself if it was not loaded;
+    # * returns one of {values} by method name.
+    # 
+    # Note, that even if there's no value with required key, `method_missing`
+    # will return `nil` (and not through `NoMethodError` as someone may
+    # expect). That's because even supposedly homogenous entities may have different
+    # property sets, and typically you want to do something like
+    # `cities.map(&:area).compact.inject(:+)`, not handling exceptions
+    # about "this city has no 'area' property".
+    #
     def method_missing(sym, *arg, **opts, &block)
       if arg.empty? && opts.empty? && !block && sym !~ /[=?!]/ &&
         !UNSUPPORTED_METHODS.include?(sym)
@@ -92,28 +234,87 @@ module Reality
       end
     end
 
-    def respond_to?(sym)
-      sym !~ /[=?!]/ && !UNSUPPORTED_METHODS.include?(sym) || super
+    # @private
+    def respond_to?(sym, include_all = false)
+      sym !~ /[=?!]/ && !UNSUPPORTED_METHODS.include?(sym) || super(sym)
     end
 
     class << self
-      def load(name, type = nil)
-        Entity.new(name, load: true).tap{|entity|
-          return nil if entity.instance_variable_get('@wikipage').nil?
-          return nil if type && entity.wikipedia_type != type
+      # Loads Entity from all datasources. Returns either loaded entity
+      # or `nil` if entity not found.
+      #
+      # @param name [String] See {#initialize} for explanations about
+      #   entity names.
+      #
+      # @return [Entity, nil]
+      def load(name)
+        Entity.new(name).load!.tap{|entity|
+          return nil if !entity.loaded?
         }
       end
     end
 
-    #def to_h
-      #if respond_to?(:properties)
-        #properties.map{|sym|
-          #[sym, to_simple_type(self.send(sym))]
-        #}.to_h
-      #else
-        #{}
-      #end
-    #end
+    # Converts Entity to hash, preserving only _core types_ (so, you can
+    # store this hash in YAML or JSON, for example). Some notes on conversion:
+    # * Entity name goes to `:name` key;
+    # * Rational values became floating point;
+    # * {Measure} and {Geo::Coord} became hashes;
+    # * other entities became: when loaded - hashes, when not loaded -
+    #    just strings of entity name
+    #
+    # Example:
+    #
+    # ```ruby
+    # argentina = Reality::Entity('Argentina')
+    # # => #<Reality::Entity(Argentina):country>
+    # argentina.head_of_government.load!
+    # # => #<Reality::Entity(Mauricio Macri)>
+    # agentina.to_h
+    # # {:name=>"Argentina",
+    # # :long_name=>"Argentine Republic",
+    # # :area=>{:amount=>2780400.0, :unit=>"km²"},
+    # # :gdp_ppp=>{:amount=>964279000000.0, :unit=>"$"},
+    # # :population=>{:amount=>43417000.0, :unit=>"person"},
+    # # :head_of_government=>
+    # #   {:name=>"Mauricio Macri", 
+    # #   :birthday=>"1959-02-08",
+    # #   ....},
+    # # :country=>"Argentina",
+    # # :continent=>"South America",
+    # # :head_of_state=>"Mauricio Macri",
+    # # :capital=>"Buenos Aires",
+    # # :currency=>"peso",
+    # # :neighbours=>["Uruguay", "Brazil", "Chile", "Paraguay", "Bolivia"],
+    # # :tld=>".ar",
+    # # :adm_divisions=>["Buenos Aires", "Buenos Aires Province", ....],
+    # # :iso2_code=>"AR",
+    # # :iso3_code=>"ARG",
+    # # :part_of=>["Latin America"],
+    # # :tz_offset=>"-03:00",
+    # # :organizations=>["United Nations","Union of South American Nations","Mercosur",...],
+    # # :calling_code=>"+54",
+    # # :created_at=>"1816-01-01",
+    # # :highest_point=>"Aconcagua",
+    # # :coord=>{:lat=>-34.0, :lng=>-64.0},
+    # # :official_website=>"http://www.argentina.gob.ar/",
+    # # :gdp_nominal=>{:amount=>537659972702.0, :unit=>"$"}}
+    # # 
+    # ```
+    #
+    # @return [Hash]
+    def to_h
+      load! unless loaded?
+      {name: name}.merge \
+        values.map{|k, v| [k.to_sym, Coercion.to_simple_type(v)]}.to_h
+    end
+
+    # Converts entity to JSON (same as `entity.to_h.to_json`)
+    #
+    # @see #to_h
+    # @return [String]
+    def to_json
+      to_h.to_json
+    end
 
     protected
 
@@ -131,22 +332,9 @@ module Reality
       end
     end
 
-    def to_simple_type(val)
-      case val
-      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.to_s
-      when Reality::Measure
-        val.amount.to_i
-      else
-        fail ArgumentError, "Non-coercible value #{val.class}"
-      end
+    def _describe
+      load! unless loaded?
+      Util::Format.describe(inspect, values.map{|k,v| [k, v.inspect]})
     end
-
   end
 end