Class: WhatIs

Inherits:
Object
  • Object
show all
Defined in:
lib/whatis.rb,
lib/whatis/cli.rb,
lib/whatis/thisis.rb,
lib/whatis/formatter.rb,
lib/whatis/refinements.rb,
lib/whatis/thisis/link.rb,
lib/whatis/thisis/ambigous.rb,
lib/whatis/thisis/notfound.rb

Overview

‘WhatIs` is a simple entity resolver through Wikipedia.

See #this and #these methods docs for details on call sequence and options, and response classes:

  • ThisIs – normal response object;

  • ThisIs::Ambigous – response object representing disambiguation page;

  • ThisIs::NotFound – response object for not found page, includes search for term service.

Examples:

# Simplest usage
WhatIs.this('Sparta') # => #<ThisIs Sparta [img] {37.081944,22.423611}>

# Additional options
WhatIs.this('Sparta', languages: :el, categories: true)
# => #<ThisIs Sparta/Αρχαία Σπάρτη, 7 categories [img] {37.081944,22.423611}>

# Several pages at once (in batch requests to Wikipedia API)
WhatIs.these('Paris', 'Athens', 'Rome')
# => {"Paris"=>#<ThisIs Paris [img] {48.856700,2.350800}>, "Athens"=>#<ThisIs Athens [img] {37.983972,23.727806}>, "Rome"=>#<ThisIs Rome [img] {41.900000,12.500000}>}

# Other language Wikipedia
 WhatIs[:ru].this('Спарта') # => #<ThisIs Спарта [img]>

Defined Under Namespace

Modules: Refinements Classes: CLI, Description, Formatter, ThisIs

Constant Summary collapse

AMBIGOUS_CATEGORIES =

This constant lists Wikipedia ambiguity categories per Wikipedia language. For ThisIs::Ambigous feature to work for your language, this list should include it.

{
  be: ['Катэгорыя:Неадназначнасці'],
  en: ['Category:All disambiguation pages', 'Category:All set index articles'],
  ru: ['Категория:Страницы значений по алфавиту'],
  uk: ['Категорія:Всі статті визначеного індексу', 'Категорія:Всі сторінки неоднозначності статей']
}.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(language = :en) ⇒ WhatIs

Returns a new instance of WhatIs.



99
100
101
102
 
# File 'lib/whatis.rb', line 99

def initialize(language = :en)
  @language = language
  @infoboxer = Infoboxer.wikipedia(language)
end

Instance Attribute Details

#language ⇒ Object (readonly) 



96
97
98
 
# File 'lib/whatis.rb', line 96

def language
  @language
end

Class Method Details

.[](lang) ⇒ WhatIs

Parameters:

  • lang (Symbol, String) —

    Wikipedia version language code, usually two-letter (“en”, “fr”), but not for all languages (for example, “be-x-old” or “zh-classical”).

Returns:



58
59
60
 
# File 'lib/whatis.rb', line 58

def [](lang)
  all[lang.to_s]
end

.these(*titles, **options) ⇒ Hash{String => ThisIs, ThisIs::Ambigous, ThisIs::NotFound}

Shortcut for ‘WhatIs.these`, see #these for details.

Parameters:

  • titles (Array<String>) —

    Titles of entities to resolve.

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :languages (true, String, Symbol) —

    If ‘true`, fetches all titles of languages versions of entity resolved; if some language code (like “ru” or “zh-classical”) is passed, fetches only this language’s title, the latter is faster.

  • :categories (true, false) —

    Fetch entity’s categories. Due to how Wikipedia’s API work, this may lead to additional API calls, so use with caution.

Returns:



71
72
73
 
# File 'lib/whatis.rb', line 71

def these(*titles, **options)
  self[:en].these(*titles, **options)
end

.this(title, **options) ⇒ ThisIs, ...

Shortcut for ‘WhatIs.this`, see #this for details.

Parameters:

  • title (String) —

    Title of the entity to resolve.

  • options (Hash)

Options Hash (**options):

  • :languages (true, String, Symbol) —

    If ‘true`, fetches all titles of languages versions of entity resolved; if some language code (like “ru” or “zh-classical”) is passed, fetches only this language’s title, the latter is faster.

  • :categories (true, false) —

    Fetch entity’s categories. Due to how Wikipedia’s API work, this may lead to additional API calls, so use with caution.

Returns:



84
85
86
 
# File 'lib/whatis.rb', line 84

def this(title, **options)
  self[:en].this(title, **options)
end

Instance Method Details

#ambigous_categories ⇒ Object 



173
174
175
 
# File 'lib/whatis.rb', line 173

def ambigous_categories
  @ambigous_categories = AMBIGOUS_CATEGORIES.fetch(language.to_sym, [])
end

#inspect ⇒ String

Returns:

  • (String) 


160
161
162
 
# File 'lib/whatis.rb', line 160

def inspect
  "#<WhatIs(#{language}). Usage: .this(*pages, **options)>"
end

#search(title, limit = 5, **options) ⇒ Object

Used by WhatIs::ThisIs::NotFound#search



166
167
168
169
170
 
# File 'lib/whatis.rb', line 166

def search(title, limit = 5, **options)
  @infoboxer
    .search(title, limit: limit) { |req| setup_request(req, **options) }
    .map { |page| ThisIs.create(self, page.title, page) }
end

#these(*titles, **options) ⇒ Hash{String => ThisIs, ThisIs::Ambigous, ThisIs::NotFound}

Batch resolving of several entities. Wikipedia API allows batch fetching of pages, so there would be roughly 1 API call for each 50 entities. Number of API calls could be larger if additional information (languages, categories) is requested.

Examples:

WhatIs.these('Warszawa', 'Warsaw', 'Berlin', 'Kharkov', languages: :fr)
# => {
#  "Warszawa" => #<ThisIs Warsaw/Varsovie [img] {52.233333,21.016667}>,
#  "Warsaw" => #<ThisIs Warsaw/Varsovie [img] {52.233333,21.016667}>,
#  "Berlin" => #<ThisIs Berlin/Berlin [img] {52.516667,13.388889}>,
#  "Kharkov" => #<ThisIs Kharkiv/Kharkiv [img] {50.004444,36.231389}>,
#  "Bela Crkva" => #<ThisIs::Ambigous Bela Crkva (6 options)>,
#  "Hrmpf" => #<ThisIs::NotFound Hrmpf>
# }

Parameters:

  • titles (Array<String>) —

    Titles of entities to resolve.

  • options (Hash) —

    a customizable set of options

Options Hash (**options):

  • :languages (true, String, Symbol) —

    If ‘true`, fetches all titles of languages versions of entity resolved; if some language code (like “ru” or “zh-classical”) is passed, fetches only this language’s title, the latter is faster.

  • :categories (true, false) —

    Fetch entity’s categories. Due to how Wikipedia’s API work, this may lead to additional API calls, so use with caution.

Returns:

See Also:



127
128
129
130
131
132
133
 
# File 'lib/whatis.rb', line 127

def these(*titles, **options)
  titles.any? or
    fail(ArgumentError, "Usage: `these('Title 1', 'Title 2', ..., **options). At least one title is required.")
  @infoboxer
    .get_h(*titles) { |req| setup_request(req, **options) }
    .map { |title, page| [title, ThisIs.create(self, title, page)] }.to_h
end

#this(title, **options) ⇒ ThisIs, ...

Note:

Special WhatIs::ThisIs::Ambigous wrapper for disambiguation pages can be created only for those language Wikipedias which ‘WhatIs` knows “disambiguation” category name, see AMBIGOUS_CATEGORIES.

Resolves one entity through Wikipedia API.

Examples:

WhatIs.this('Warszawa', languages: :fr)
# => #<ThisIs Warsaw/Varsovie [img] {52.233333,21.016667}>
WhatIs.this('Bela Crkva', languages: :fr)
# => #<ThisIs::Ambigous Bela Crkva (6 options)>
WhatIs.this('Hrmpf', languages: :fr)
# => #<ThisIs::NotFound Hrmpf>

Parameters:

  • title (String) —

    Title of the entity to resolve.

  • options (Hash)

Options Hash (**options):

  • :languages (true, String, Symbol) —

    If ‘true`, fetches all titles of languages versions of entity resolved; if some language code (like “ru” or “zh-classical”) is passed, fetches only this language’s title, the latter is faster.

  • :categories (true, false) —

    Fetch entity’s categories. Due to how Wikipedia’s API work, this may lead to additional API calls, so use with caution.

Returns:

See Also:



155
156
157
 
# File 'lib/whatis.rb', line 155

def this(title, **options)
  these(title, **options).values.first
end