wikidatum 0.2.0 → 0.3.0

data/lib/wikidatum/data_type/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# For more information on the possible types that can be returned by
+# datavalues, see the official documentation:
+# https://doc.wikimedia.org/Wikibase/master/php/md_docs_topics_json.html#json_datavalues
+module Wikidatum::DataType
+  class Base
+    # Represents the type for this instance.
+    #
+    # Possible values for the `type` attribute are:
+    #
+    # - `:no_value`: No value
+    # - `:some_value`: Unknown value
+    # - `:globe_coordinate`: {DataType::GlobeCoordinate}
+    # - `:monolingual_text`: {DataType::MonolingualText}
+    # - `:quantity`: {DataType::Quantity}
+    # - `:string`: {DataType::WikibaseString}
+    # - `:time`: {DataType::Time}
+    # - `:wikibase_item`: {DataType::WikibaseItem}
+    #
+    # @return [Symbol]
+    attr_reader :type
+
+    # The value of the "content" attribute in the response.
+    #
+    # If the `type` is `novalue` or `somevalue`, this returns `nil`.
+    #
+    # @return [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil]
+    attr_reader :content
+
+    # @param type [Symbol]
+    # @param content [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil] nil if type is no_value or some_value
+    # @return [void]
+    def initialize(type:, content:)
+      @type = type
+      @content = content
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        type: @type,
+        content: @content&.to_h
+      }
+    end
+
+    # @!visibility private
+    #
+    # @param data_type [String] The value of `data-type` for the given Statement or Qualifier's property.
+    # @param data_value_json [Hash] The `content` part of value object.
+    # @return [Wikidatum::DataType::Base] An instance of Base.
+    def self.marshal_load(data_type, data_value_json)
+      unless Wikidatum::DataType::DATA_TYPES.keys.include?(data_type.to_sym)
+        puts "WARNING: Unsupported data type (#{data_type})"
+        return nil
+      end
+
+      Object.const_get(Wikidatum::DataType::DATA_TYPES[data_type.to_sym]).marshal_load(data_value_json)
+    end
+  end
+end

data/lib/wikidatum/{data_value_type → data_type}/globe_coordinate.rb

@@ -1,23 +1,27 @@
 # frozen_string_literal: true
 
-require 'wikidatum/data_value_type/base'
+require 'wikidatum/data_type/base'
 
-# The Globe Coordinate type datavalue JSON looks like this:
+# The Globe Coordinate type JSON looks like this:
 #
 # ```json
 # {
-#   "datavalue": {
-#     "value": {
-#       "latitude": 52.516666666667,
-#       "longitude": 13.383333333333,
-#       "precision": 0.016666666666667,
+#   "property": {
+#     "id": "P740",
+#     "data-type": "globe-coordinate"
+#   },
+#   "value": {
+#     "type": "value",
+#     "content": {
+#       "latitude": 38.8977,
+#       "longitude": -77.0365,
+#       "precision": 0.0001,
 #       "globe": "http://www.wikidata.org/entity/Q2"
-#     },
-#     "type": "globecoordinate"
+#     }
 #   }
 # }
 # ```
-class Wikidatum::DataValueType::GlobeCoordinate
+class Wikidatum::DataType::GlobeCoordinate
   # @return [Float]
   attr_reader :latitude
 
@@ -56,22 +60,19 @@ class Wikidatum::DataValueType::GlobeCoordinate
   #
   # @return [String]
   def wikibase_type
-    'globecoordinate'
+    'globe-coordinate'
   end
 
-  # The "datatype" value used by Wikibase, usually identical to wikibase_type
-  # but not always.
-  #
-  # @return [String]
-  def wikibase_datatype
-    'globe-coordinate' # yes, really
+  # @return [Symbol]
+  def self.symbolized_name
+    :monolingual_text
   end
 
   # @!visibility private
   def self.marshal_load(data_value_json)
-    Wikidatum::DataValueType::Base.new(
-      type: :globe_coordinate,
-      value: new(
+    Wikidatum::DataType::Base.new(
+      type: symbolized_name,
+      content: new(
         latitude: data_value_json['latitude'],
         longitude: data_value_json['longitude'],
         precision: data_value_json['precision'],

data/lib/wikidatum/{data_value_type → data_type}/monolingual_text.rb

@@ -1,21 +1,25 @@
 # frozen_string_literal: true
 
-require 'wikidatum/data_value_type/base'
+require 'wikidatum/data_type/base'
 
-# The Monolingual Text type datavalue JSON looks like this:
+# The Monolingual Text type JSON looks like this:
 #
 # ```json
 # {
-#   "datavalue": {
-#     "value": {
-#       "text": "South Pole Telescope eyes birth of first massive galaxies",
-#       "language": "en"
-#     },
-#     "type": "monolingualtext"
+#   "property": {
+#     "id": "P13432",
+#     "data-type": "monolingualtext"
+#   },
+#   "value": {
+#     "type": "value",
+#     "content": {
+#       "text": "foo",
+#       "language": "en-gb"
+#     }
 #   }
 # }
 # ```
-class Wikidatum::DataValueType::MonolingualText
+class Wikidatum::DataType::MonolingualText
   # @return [String] the language code, e.g. 'en'
   attr_reader :language
 
@@ -45,19 +49,16 @@ class Wikidatum::DataValueType::MonolingualText
     'monolingualtext'
   end
 
-  # The "datatype" value used by Wikibase, usually identical to wikibase_type
-  # but not always.
-  #
-  # @return [String]
-  def wikibase_datatype
-    wikibase_type
+  # @return [Symbol]
+  def self.symbolized_name
+    :monolingual_text
   end
 
   # @!visibility private
   def self.marshal_load(data_value_json)
-    Wikidatum::DataValueType::Base.new(
-      type: :monolingual_text,
-      value: new(
+    Wikidatum::DataType::Base.new(
+      type: symbolized_name,
+      content: new(
         language: data_value_json['language'],
         text: data_value_json['text']
       )

data/lib/wikidatum/{data_value_type → data_type}/no_value.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'wikidatum/data_value_type/base'
+require 'wikidatum/data_type/base'
 
 # The NoValue type actually has no datavalue key in the blob at all. We work
 # around this by just passing nil to the serializer.
 
 # Represents "no value".
-class Wikidatum::DataValueType::NoValue < Wikidatum::DataValueType::Base
+class Wikidatum::DataType::NoValue < Wikidatum::DataType::Base
   # The "type" value used by Wikibase, for use when creating/updating statements.
   #
   # @return [String]
@@ -14,16 +14,8 @@ class Wikidatum::DataValueType::NoValue < Wikidatum::DataValueType::Base
     'string'
   end
 
-  # The "datatype" value used by Wikibase, usually identical to wikibase_type
-  # but not always.
-  #
-  # @return [String]
-  def wikibase_datatype
-    wikibase_type
-  end
-
   # @!visibility private
   def self.marshal_load(_data_value_json)
-    new(type: :no_value, value: nil)
+    new(type: :no_value, content: nil)
   end
 end

data/lib/wikidatum/data_type/quantity.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+
+# The Quantity type JSON looks like this:
+#
+# ```json
+# {
+#   "property": {
+#     "id": "P937",
+#     "data-type": "quantity"
+#   },
+#   "value": {
+#     "type": "value",
+#     "content": {
+#       "amount": "+15",
+#       "unit": "1"
+#     }
+#   }
+# }
+# ```
+class Wikidatum::DataType::Quantity
+  # @return [String] A string value like "+2", usually an integer but not always.
+  attr_reader :amount
+
+  # @return [String] a URL describing the unit for this quantity, e.g. "meter", "kilometer", "pound", "chapter", "section", etc.
+  attr_reader :unit
+
+  # @param amount [String]
+  # @param unit [String]
+  # @return [void]
+  def initialize(amount:, unit:)
+    @amount = amount
+    @unit = unit
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      amount: @amount,
+      unit: @unit
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'quantity'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :quantity
+  end
+
+  # @!visibility private
+  def self.marshal_load(data_value_json)
+    Wikidatum::DataType::Base.new(
+      type: symbolized_name,
+      content: new(
+        amount: data_value_json['amount'],
+        unit: data_value_json['unit']
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    {
+      amount: @amount,
+      unit: @unit
+    }
+  end
+end

data/lib/wikidatum/{data_value_type → data_type}/some_value.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'wikidatum/data_value_type/base'
+require 'wikidatum/data_type/base'
 
 # The SomeValue type actually has no datavalue key in the blob at all. We work
 # around this by just passing nil to the serializer.
 
 # Represents a value of "unknown value".
-class Wikidatum::DataValueType::SomeValue < Wikidatum::DataValueType::Base
+class Wikidatum::DataType::SomeValue < Wikidatum::DataType::Base
   # The "type" value used by Wikibase, for use when creating/updating statements.
   #
   # @return [String]
@@ -14,16 +14,8 @@ class Wikidatum::DataValueType::SomeValue < Wikidatum::DataValueType::Base
     'string'
   end
 
-  # The "datatype" value used by Wikibase, usually identical to wikibase_type
-  # but not always.
-  #
-  # @return [String]
-  def wikibase_datatype
-    wikibase_type
-  end
-
   # @!visibility private
   def self.marshal_load(_data_value_json)
-    new(type: :some_value, value: nil)
+    new(type: :some_value, content: nil)
   end
 end

data/lib/wikidatum/{data_value_type → data_type}/time.rb

@@ -1,33 +1,30 @@
 # frozen_string_literal: true
 
-require 'wikidatum/data_value_type/base'
+require 'wikidatum/data_type/base'
 
-# The time type datavalue JSON looks like this:
+# The time type JSON looks like this:
 #
 # ```json
 # {
-#   "datavalue": {
-#     "value": {
+#   "property": {
+#     "id": "P761",
+#     "data-type": "time"
+#   },
+#   "value": {
+#     "type": "value",
+#     "content": {
 #       "time": "+2019-11-14T00:00:00Z",
-#       "timezone": 0,
-#       "before": 0,
-#       "after": 0,
 #       "precision": 11,
 #       "calendarmodel": "http://www.wikidata.org/entity/Q1985727"
-#     },
-#     "type": "time"
+#     }
 #   }
 # }
 # ```
 #
-# We do not include before and after because the documentation states that
-# they're unused and "may be removed in the future".
-#
-# NOTE: For consistency with Ruby snake_case attribute names, `timezone` from
-# the API is represented as `time_zone` and `calendarmodel` is
-# `calendar_model`. However, we expose aliases so `timezone` and
+# NOTE: For consistency with Ruby snake_case attribute names, `calendarmodel`
+# in the API is `calendar_model`. However, we expose an alias so
 # `calendarmodel` will still work.
-class Wikidatum::DataValueType::Time
+class Wikidatum::DataType::Time
   # A string representing the time in a format that is very similar to ISO 8601.
   #
   # For example, here are what dates look like for the most common precisions:
@@ -48,11 +45,6 @@ class Wikidatum::DataValueType::Time
   # @return [String] the time value, in a format like "+2022-01-01T00:00:00Z", though how this should be interpreted depends on the precision.
   attr_reader :time
 
-  # @return [Integer] an integer for the offset (in minutes) from UTC. 0 means
-  #   UTC, will currently always be 0 but the Wikibase backend may change that
-  #   in the future.
-  attr_reader :time_zone
-
   # An integer representing the precision of the date, where the integers correspond to the following:
   #
   # - 0: 1 Gigayear
@@ -91,13 +83,11 @@ class Wikidatum::DataValueType::Time
   attr_reader :calendar_model
 
   # @param time [String]
-  # @param time_zone [Integer]
   # @param precision [Integer]
   # @param calendar_model [String]
   # @return [void]
-  def initialize(time:, time_zone:, precision:, calendar_model:)
+  def initialize(time:, precision:, calendar_model:)
     @time = time
-    @time_zone = time_zone
     @precision = precision
     @calendar_model = calendar_model
   end
@@ -106,7 +96,6 @@ class Wikidatum::DataValueType::Time
   def to_h
     {
       time: @time,
-      time_zone: @time_zone,
       precision: @precision,
       pretty_precision: pretty_precision,
       calendar_model: @calendar_model
@@ -120,21 +109,17 @@ class Wikidatum::DataValueType::Time
     'time'
   end
 
-  # The "datatype" value used by Wikibase, usually identical to wikibase_type
-  # but not always.
-  #
-  # @return [String]
-  def wikibase_datatype
-    wikibase_type
+  # @return [Symbol]
+  def self.symbolized_name
+    :time
   end
 
   # @!visibility private
   def self.marshal_load(data_value_json)
-    Wikidatum::DataValueType::Base.new(
-      type: :time,
-      value: new(
+    Wikidatum::DataType::Base.new(
+      type: symbolized_name,
+      content: new(
         time: data_value_json['time'],
-        time_zone: data_value_json['timezone'],
         precision: data_value_json['precision'],
         calendar_model: data_value_json['calendarmodel']
       )
@@ -145,7 +130,6 @@ class Wikidatum::DataValueType::Time
   def marshal_dump
     {
       time: @time,
-      timezone: @time_zone,
       precision: @precision,
       calendarmodel: @calendar_model
     }
@@ -182,6 +166,5 @@ class Wikidatum::DataValueType::Time
 
   # Aliases to match the name returned by the REST API.
 
-  alias timezone time_zone
   alias calendarmodel calendar_model
 end

data/lib/wikidatum/data_type/wikibase_item.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+
+# The Wikibase Item type JSON looks like this:
+#
+# ```json
+# {
+#   "property": {
+#     "id": "P963",
+#     "data-type": "wikibase-item"
+#   },
+#   "value": {
+#     "type": "value",
+#     "content": "Q524026"
+#   }
+# }
+# ```
+class Wikidatum::DataType::WikibaseItem
+  # @return [String] in the format "Q123".
+  attr_reader :id
+
+  # @param id [String]
+  # @return [void]
+  def initialize(id:)
+    @id = id
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      id: @id
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'wikibase-item'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :wikibase_item
+  end
+
+  # @!visibility private
+  def self.marshal_load(id)
+    Wikidatum::DataType::Base.new(
+      type: symbolized_name,
+      content: new(
+        id: id
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    {
+      id: @id
+    }
+  end
+end

data/lib/wikidatum/{data_value_type → data_type}/wikibase_string.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
 
-require 'wikidatum/data_value_type/base'
+require 'wikidatum/data_type/base'
 
-# The String type datavalue JSON looks like this:
+# The String type JSON looks like this:
 #
 # ```json
 # {
-#   "datavalue": {
-#     "value": "Foobar",
-#     "type": "string"
+#   "property": {
+#     "id": "P143",
+#     "data-type": "string"
+#   },
+#   "value": {
+#     "type": "value",
+#     "content": "foo"
 #   }
 # }
 # ```
-class Wikidatum::DataValueType::WikibaseString
+class Wikidatum::DataType::WikibaseString
   # @return [String] the value for the string.
   attr_reader :string
 
@@ -36,19 +40,16 @@ class Wikidatum::DataValueType::WikibaseString
     'string'
   end
 
-  # The "datatype" value used by Wikibase, usually identical to wikibase_type
-  # but not always.
-  #
-  # @return [String]
-  def wikibase_datatype
-    wikibase_type
+  # @return [Symbol]
+  def self.symbolized_name
+    :string
   end
 
   # @!visibility private
   def self.marshal_load(string)
-    Wikidatum::DataValueType::Base.new(
-      type: :string,
-      value: new(
+    Wikidatum::DataType::Base.new(
+      type: symbolized_name,
+      content: new(
         string: string
       )
     )

data/lib/wikidatum/data_type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/globe_coordinate'
+require 'wikidatum/data_type/monolingual_text'
+require 'wikidatum/data_type/no_value'
+require 'wikidatum/data_type/quantity'
+require 'wikidatum/data_type/some_value'
+require 'wikidatum/data_type/time'
+require 'wikidatum/data_type/wikibase_item'
+require 'wikidatum/data_type/wikibase_string'

data/lib/wikidatum/item.rb

@@ -186,8 +186,8 @@ class Wikidatum::Item
     statements = item_json['statements'].to_a.flat_map do |_property_id, st_arr|
       st_arr.map { |statement| Wikidatum::Statement.marshal_load(statement) }
     end
-    sitelinks = item_json['sitelinks'].to_a.map do |_name, sitelink|
-      Wikidatum::Sitelink.new(site: sitelink['site'], title: sitelink['title'], badges: sitelink['badges'])
+    sitelinks = item_json['sitelinks'].to_a.map do |site, sitelink|
+      Wikidatum::Sitelink.new(site: site, title: sitelink['title'], badges: sitelink['badges'])
     end
 
     Wikidatum::Item.new(

data/lib/wikidatum/qualifier.rb

@@ -1,7 +1,55 @@
 # frozen_string_literal: true
 
-require 'wikidatum/snak'
+class Wikidatum::Qualifier
+  # @return [String] ID of the property for this Qualifier, in the format 'P123'.
+  attr_reader :property_id
 
-# Wikidatum::Qualifier is actually just an alias for snak, because qualifiers
-# are effectively just snaks.
-Wikidatum::Qualifier = Wikidatum::Snak
+  # @return [String]
+  attr_reader :data_type
+
+  # For more information on the possible types that can be returned by
+  # datavalues, see the official documentation:
+  # https://doc.wikimedia.org/Wikibase/master/php/md_docs_topics_json.html#json_datavalues
+  #
+  # @return [Wikidatum::DataType::Base] the value of the statement, can take various forms
+  attr_reader :value
+
+  # @!visibility private
+  # @param property_id [String] ID of the property for this Qualifier, in the format 'P123'.
+  # @param data_type [String]
+  # @param value [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, DataType::NoValue, DataType::SomeValue]
+  def initialize(property_id:, data_type:, value:)
+    @property_id = property_id
+    @data_type = data_type
+    @value = value
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      property_id: @property_id,
+      data_type: @data_type,
+      value: @value.to_h
+    }
+  end
+
+  # @return [String]
+  def inspect
+    "<Wikidatum::Qualifier property_id=#{@property_id.inspect} data_type=#{@data_type.inspect} value=#{@value.inspect}>"
+  end
+
+  # @!visibility private
+  #
+  # This takes in the JSON blob (as a hash) that is output for a given
+  # qualifier the API and turns it into an actual instance of a Qualifier.
+  #
+  # @param qualifier_json [Hash]
+  # @return [Wikidatum::Qualifier]
+  def self.marshal_load(qualifier_json)
+    Wikidatum::Qualifier.new(
+      property_id: qualifier_json.dig('property', 'id'),
+      data_type: qualifier_json.dig('property', 'data-type'),
+      value: Wikidatum::Utils.ingest_snak(qualifier_json)
+    )
+  end
+end