whatis 0.0.1

data/lib/whatis/formatter.rb

@@ -0,0 +1,51 @@
+class WhatIs
+  using Refinements
+
+  # @private
+  class Formatter
+    def call(title, object)
+      str =
+        case object
+        when ThisIs
+          format_thisis(object)
+        when ThisIs::Ambigous
+          format_ambigous(object)
+        when ThisIs::NotFound
+          format_notfound(object)
+        end
+      "#{title}: #{str}"
+    end
+
+    private
+
+    def format_thisis(object)
+      [
+        object.title,
+        object.coordinates&.to_s&.surround(' {', '}'),
+        ' - ',
+        short_description(object)
+      ].join
+    end
+
+    def short_description(obj) # rubocop:disable Metrics/AbcSize
+      case
+      when obj.categories.any?
+        obj.categories.sort.join('; ')
+      when obj.languages.count == 1
+        obj.languages.values.first
+      when !obj.description.to_s.empty?
+        obj.description
+      else
+        obj.extract
+      end
+    end
+
+    def format_ambigous(object)
+      "#{object.title}, #{object.variants.count} options - #{object.variants.join('; ')}"
+    end
+
+    def format_notfound(*)
+      'not found'
+    end
+  end
+end

data/lib/whatis/refinements.rb

@@ -0,0 +1,34 @@
+class WhatIs
+  # @private
+  module Refinements
+    refine String do
+      def append(after)
+        "#{self}#{after}"
+      end
+
+      def prepend(before)
+        "#{before}#{self}"
+      end
+
+      def surround(before, after = before)
+        "#{before}#{self}#{after}"
+      end
+    end
+
+    refine Object do
+      def yield_self
+        yield self
+      end
+
+      def iff
+        yield(self) ? self : nil
+      end
+    end
+
+    refine Hash do
+      def transform_keys
+        map { |key, val| [yield(key), val] }.to_h
+      end
+    end
+  end
+end

data/lib/whatis/thisis.rb

@@ -0,0 +1,181 @@
+class WhatIs
+  using Refinements
+
+  # Represents one resolved entity, provides introspection and access to individual properties.
+  # You should never create instances of this class directly, but rather obtain it from {WhatIs#this}
+  # and {WhatIs#these}.
+  #
+  # @example
+  #   paris = WhatIs.this('Paris')
+  #   # => #<ThisIs Paris [img] {48.856700,2.350800}>
+  #   paris.describe
+  #   # => Paris
+  #   #        title: "Paris"
+  #   #  description: "capital city of France"
+  #   #  coordinates: #<Geo::Coord 48.856700,2.350800>
+  #   #      extract: "Paris (French pronunciation: ​[paʁi] ( listen)) is the capital and most populous city of France, with an administrative-limits area of 105 square kilometres (41 square miles) and a 2015 population of 2,229,621."
+  #   #        image: "https://upload.wikimedia.org/wikipedia/commons/0/08/Seine_and_Eiffel_Tower_from_Tour_Saint_Jacques_2013-08.JPG"
+  #   #
+  #   paris.coordinates
+  #   # => #<Geo::Coord 48.856700,2.350800>
+  #   paris2 = paris.what(languages: :ru, categories: true) # fetch more details
+  #   # => #<ThisIs Paris/Париж, 12 categories [img] {48.856700,2.350800}>
+  #   paris2.describe
+  #   # => Paris
+  #   #        title: "Paris"
+  #   #  description: "capital city of France"
+  #   #  coordinates: #<Geo::Coord 48.856700,2.350800>
+  #   #   categories: ["3rd-century BC establishments", "Capitals in Europe", "Catholic pilgrimage sites", "Cities in France", "Cities in Île-de-France", "Companions of the Liberation", "Departments of Île-de-France", "European culture", "French culture", "Paris", "Populated places established in the 3rd century BC", "Prefectures in France"]
+  #   #    languages: {"ru"=>#<ThisIs::Link ru:Париж>}
+  #   #      extract: "Paris (French pronunciation: ​[paʁi] ( listen)) is the capital and most populous city of France, with an administrative-limits area of 105 square kilometres (41 square miles) and a 2015 population of 2,229,621."
+  #   #        image: "https://upload.wikimedia.org/wikipedia/commons/0/08/Seine_and_Eiffel_Tower_from_Tour_Saint_Jacques_2013-08.JPG"
+  #   paris2.languages['ru'].resolve(categories: true)
+  #   # => #<ThisIs Париж, 10 categories [img] {48.833333,2.333333}>
+  #
+  # See also:
+  #
+  # * {ThisIs::Ambigous} Representing disambiguation page, allows fetching variants.
+  # * {ThisIs::NotFound} Representing not found entity, allows searching for possible options.
+  class ThisIs
+    # @private
+    EXTRACTORS = {
+      title: ->(page) { page.title },
+      description: ->(page) { page.source.dig('terms', 'description', 0) },
+      coordinates: ->(page) {
+        coord = page.source['coordinates']&.first or return nil
+        Geo::Coord.from_h(coord)
+      },
+      categories: ->(page) {
+        Array(page.source['categories'])
+          .reject { |c| c.key?('hidden') }
+          .map { |c| c['title'].split(':', 2).last }
+      },
+      languages: ->(page) {
+        Array(page.source['langlinks'])
+          .map { |l| [l['lang'], l['*']] }
+          .map { |code, title| [code, Link.new(title, language: code)] }.to_h
+          .to_h
+      },
+      extract: ->(page) {
+        # remove HTML tags
+        # NB: Wikipedia "extracts" submodule has "plaintext=true" option, but it produces wrong 1-sentece
+        # extracts (broken by first ".", which can be somewhere in transcription of the main entity).
+        # HTML extracts, on the other hand, return proper sentences
+        #
+        # Link: https://en.wikipedia.org/w/api.php?action=help&modules=query%2Bextracts
+        page.source['extract']&.gsub(/<[^>]+>/, '')&.strip
+      },
+      image: ->(page) { page.source.dig('original', 'source') }
+    }.freeze
+
+    # @private
+    def self.create(owner, title, page)
+      case
+      when page.nil?
+        NotFound.new(owner, title)
+      when Array(page.source['categories']).any? { |c| owner.ambigous_categories.include?(c['title']) }
+        Ambigous.new(owner, page)
+      else
+        new(owner, page)
+      end
+    end
+
+    # Original [Infoboxer page](http://www.rubydoc.info/gems/infoboxer/Infoboxer/MediaWiki/Page) data.
+    # @return [Infoboxer::MediaWiki::Page]
+    attr_reader :page
+
+    # @private
+    def initialize(owner, page)
+      @owner = owner
+      @page = page
+      @data = EXTRACTORS.map { |sym, proc| [sym, proc.call(page)] }.to_h
+    end
+
+    # @!method title
+    #   Title of Wikipedia page
+    #   @return [String]
+    # @!method description
+    #   Short entity description phrase from Wikidata. Not always present.
+    #   @return [String]
+    # @!method extract
+    #   First sentence of Wikipedia page
+    #   @return [String]
+    # @!method coordinates
+    #   Geographical coordinates, associated with the page, if known, wrapped in
+    #   [Geo::Coord](https://github.com/zverok/geo_coord) type.
+    #   @return [Geo::Coord]
+    # @!method image
+    #   URL of page's main image, if known.
+    #   @return [Geo::Coord]
+    # @!method categories
+    #   List of page's categories, present only if page was fetched with `categories: true` option.
+    #   @return [Array<String>]
+    # @!method languages
+    #   Hash of other language version of page. Present only if the page wath fetched with `:languages`
+    #   option. Keys are language codes, values are {ThisIs::Link} objects, allowing to fetch corresponding
+    #   entities with {ThisIs::Link#resolve}.
+    #   @return [Hash{String => ThisIs::Link}]
+
+    EXTRACTORS.each_key { |title| define_method(title) { @data[title] } }
+
+    alias to_s title
+
+    # @return [String]
+    def inspect # rubocop:disable Metrics/AbcSize
+      [
+        'ThisIs ',
+        title,
+        languages.iff { |l| l.count == 1 }&.yield_self { |l| l.values.first.title.prepend('/') },
+        languages.iff { |l| l.count > 1 }&.yield_self { |l| " +#{l.count} translations" },
+        categories.iff(&:any?)&.yield_self { |c| ", #{c.count} categories" },
+        image&.yield_self { ' [img]' },
+        coordinates&.to_s&.surround(' {', '}')
+      ].compact.join.surround('#<', '>')
+    end
+
+    # @return [Description]
+    def describe(*)
+      maxlength = @data.keys.map(&:length).max
+      Description.new(
+        "#{self}\n" +
+          clean_data
+            .map { |k, v| "  #{k.to_s.rjust(maxlength)}: #{v.inspect}" }.join("\n")
+      )
+    end
+
+    # @return [Hash]
+    def to_h
+      {type: 'ThisIs'} # To be at the beginning of a hash
+        .merge(@data)
+        .merge(
+          coordinates: coordinates&.to_s,
+          languages: languages.transform_values(&:to_s)
+        ).reject { |_, v| v.nil? || v.respond_to?(:empty?) && v.empty? }
+    end
+
+    # @return [String]
+    def to_json(opts)
+      to_h.to_json(opts)
+    end
+
+    # Refetch page with more data, see {WhatIs#this} for options explanation. Returns new object.
+    #
+    # @param options [Hash]
+    # @option options [true, String, Symbol] :languages
+    # @option options [true, false] :categories
+    # @return [ThisIs]
+    def what(**options)
+      @owner.this(title, **options)
+    end
+
+    private
+
+    def clean_data
+      @data.reject { |_, v| v.nil? || v.respond_to?(:empty?) && v.empty? }
+    end
+  end
+end
+
+require_relative 'thisis/ambigous'
+require_relative 'thisis/notfound'
+require_relative 'thisis/link'

data/lib/whatis/thisis/ambigous.rb

@@ -0,0 +1,128 @@
+class WhatIs
+  class ThisIs
+    # Represents disambiguation page.
+    #
+    # You should never create instances of this class directly, but rather obtain it from {WhatIs#this}
+    # and {WhatIs#these}.
+    #
+    # `Ambigous` consists of {#variants}, each of them represented by a {ThisIs::Link} which can
+    # be {ThisIs::Link#resolve resolved}.
+    #
+    # @note This functionality (special wrapper for disambiguation
+    #   pages) works only for those language Wikis which have their "disambiguation" category known
+    #   to `WhatIs`. See {WhatIs::AMBIGOUS_CATEGORIES}.
+    #
+    # @example
+    #   a = WhatIs.this('Bela Crkva')
+    #   # => #<ThisIs::Ambigous Bela Crkva (6 options)>
+    #   a.describe
+    #   # => Bela Crkva: ambigous (6 options)
+    #   #  #<ThisIs::Link Bela Crkva, Banat>: Bela Crkva, Banat, a town in Vojvodina, Serbia
+    #   #  #<ThisIs::Link Bela Crkva, Krivogaštani>: Bela Crkva, Krivogaštani, a village in the Municipality of Krivogaštani, Macedonia
+    #   #  #<ThisIs::Link Bela Crkva (Krupanj)>: Bela Crkva (Krupanj), a village in the Mačva District of Serbia
+    #   #  #<ThisIs::Link Toplička Bela Crkva>: Toplička Bela Crkva, original name of the city of Kuršumlija, Serbia
+    #   #  #<ThisIs::Link See also/Bila Tserkva>: Bila Tserkva (Біла Церква), a city in the Kiev Oblast of Ukraine
+    #   #  #<ThisIs::Link See also/Byala Cherkva>: Byala Cherkva, a town in the Veliko Turnovo oblast of Bulgaria
+    #   #
+    #   #  Usage: .variants[0].resolve, .resolve_all
+    #
+    #   a.variants[0]
+    #   # => #<ThisIs::Link Bela Crkva, Banat>
+    #   a.variants[0].resolve
+    #   # => #<ThisIs Bela Crkva, Banat [img] {44.897500,21.416944}>
+    #   a.variants[0].resolve(categories: true)
+    #   # => #<ThisIs Bela Crkva, Banat, 5 categories [img] {44.897500,21.416944}>
+    #   a.resolve_all
+    #   # => {"Bela Crkva, Banat"=>#<ThisIs Bela Crkva, Banat [img] {44.897500,21.416944}>, "Bela Crkva, Krivogaštani"=>#<ThisIs Bela Crkva, Krivogaštani {41.280833,21.345278}>, "Bela Crkva (Krupanj)"=>#<ThisIs Bela Crkva (Krupanj) [img] {44.395000,19.479400}>, "Toplička Bela Crkva"=>#<ThisIs Kuršumlija [img] {43.150000,21.266667}>, "Bila Tserkva"=>#<ThisIs Bila Tserkva [img] {49.798889,30.115278}>, "Byala Cherkva"=>#<ThisIs Byala Cherkva [img] {43.200000,25.300000}>}
+    #
+    class Ambigous
+      # Original [Infoboxer page](http://www.rubydoc.info/gems/infoboxer/Infoboxer/MediaWiki/Page) data.
+      # @return [Infoboxer::MediaWiki::Page]
+      attr_reader :page
+
+      # Each link can be {ThisIs::Link#resolve resolved} individually, like
+      # `ambigous.variants[0].resolve`, or you can resolve them all at once with {#resolve_all}.
+      #
+      # @return [Array<ThisIs::Link>]
+      attr_reader :variants
+
+      # @private
+      def initialize(owner, page)
+        @owner = owner
+        @page = page
+        @variants = extract_variants
+      end
+
+      # @return [String]
+      def title
+        page.title
+      end
+
+      # @return [String]
+      def inspect
+        "#<ThisIs::Ambigous #{title} (#{variants.count} options)>"
+      end
+
+      # @return [String]
+      def to_s
+        "#{title}: ambigous (#{variants.count} options)"
+      end
+
+      # @return [Hash]
+      def to_h
+        {
+          type: 'ThisIs::Ambigous',
+          title: title,
+          variants: variants.map(&:to_s)
+        }
+      end
+
+      # @return [String]
+      def to_json(opts)
+        to_h.to_json(opts)
+      end
+
+      # @return [Description]
+      def describe(help: true)
+        Description.new(
+          "#{self}\n" +
+            variants.map { |link| "  #{link.inspect}: #{link.description}" }.join("\n") +
+            describe_help(help)
+        )
+      end
+
+      # Resolves all ambigous variants with one query.
+      # See {WhatIs#this} for options explanation.
+      #
+      # @param options [Hash]
+      # @option options [true, String, Symbol] :languages
+      # @option options [true, false] :categories
+      # @return [Hash{String => ThisIs}]
+      def resolve_all(**options)
+        @owner.these(*variants.map(&:title), **options)
+      end
+
+      private
+
+      def describe_help(render = true)
+        return '' unless render
+        "\n\n  Usage: .variants[0].resolve, .resolve_all"
+      end
+
+      def extract_variants
+        page.wikipath('//ListItem')
+          .reject { |item| item.wikilinks.empty? }
+          .map(&method(:item_to_link))
+      end
+
+      def item_to_link(item)
+        Link.new(
+          item.wikilinks.first.link,
+          owner: @owner,
+          section: item.in_sections.map(&:heading).map(&:text_).reverse.reject(&:empty?).join('/'),
+          description: item.children.map(&:text).join
+        )
+      end
+    end
+  end
+end

data/lib/whatis/thisis/link.rb

@@ -0,0 +1,75 @@
+class WhatIs
+  using Refinements
+
+  class ThisIs
+    # Represents link to some entity that can be resolved to proper entity definition.
+    #
+    # You should never create instances of this class directly, it occurs as variant links from
+    # {Ambigous}, and as {ThisIs::languages} links.
+    #
+    # @example
+    #   # Ambigous variants link
+    #   a = WhatIs.this('Bela Crkva')
+    #   # => #<ThisIs::Ambigous Bela Crkva (6 options)>
+    #   a.variants[0]
+    #   # => #<ThisIs::Link Bela Crkva, Banat>
+    #   a.variants[0].resolve
+    #   # => #<ThisIs Bela Crkva, Banat [img] {44.897500,21.416944}>
+    #
+    #   # Languages link
+    #   paris = WhatIs.this('Paris', languages: :ru)
+    #   # => #<ThisIs Paris/Париж, [img] {48.856700,2.350800}>
+    #   paris.languages
+    #   # => {"ru"=>#<ThisIs::Link ru:Париж>}
+    #   paris.languages['ru'].resolve(categories: true)
+    #   # => #<ThisIs Париж, 10 categories [img] {48.833333,2.333333}>
+    #
+    class Link
+      # @return [String]
+      attr_reader :title
+      # @private
+      attr_reader :language
+
+      # @private
+      #   For pretty output only
+      attr_reader :section, :description
+
+      # @private
+      def initialize(title, section: nil, owner: nil, language: nil, description: nil)
+        @owner = owner
+        @title = title
+        @language = language&.to_s
+        @section = section unless section == ''
+        @description = description
+      end
+
+      # @return [String]
+      def inspect
+        "#<ThisIs::Link #{language&.append(':')}#{section&.append('/')}#{title}>"
+      end
+
+      alias to_s title
+
+      # Resolves the link, fetching entity from Wikipedia API.
+      #
+      # See {WhatIs#this} for options explanation.
+      #
+      # @param options [Hash]
+      # @option options [true, String, Symbol] :languages
+      # @option options [true, false] :categories
+      # @return [ThisIs, ThisIs::Ambigous]
+      def resolve(**options)
+        engine = @owner || language && WhatIs[language] or
+          fail "Can't resolve #{inspect}"
+
+        engine.this(title, **options)
+      end
+
+      # @private
+      #   For tests only
+      def ==(other)
+        other.is_a?(Link) && other.language == language && other.title == title
+      end
+    end
+  end
+end