wikidatum 0.2.1 → 0.3.1

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,62 @@
+# 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
+  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

data/lib/wikidatum/reference.rb

@@ -4,28 +4,28 @@ class Wikidatum::Reference
   # @return [String] Hash of the reference (a cryptographic hash, not a Ruby hash).
   attr_reader :hash
 
-  # @return [Array<Wikidatum::Snak>]
-  attr_reader :snaks
+  # @return [Array<Wikidatum::ReferencePart>]
+  attr_reader :parts
 
   # @!visibility private
   # @param hash [String] Hash of the reference (a cryptographic hash, not a Ruby hash).
-  # @param snaks [Array<Wikidatum::Snak>]
-  def initialize(hash:, snaks:)
+  # @param parts [Array<Wikidatum::ReferencePart>]
+  def initialize(hash:, parts:)
     @hash = hash
-    @snaks = snaks
+    @parts = parts
   end
 
   # @return [Hash]
   def to_h
     {
       hash: @hash,
-      snaks: @snaks.map(&:to_h)
+      parts: @parts.map(&:to_h)
     }
   end
 
   # @return [String]
   def inspect
-    "<Wikidatum::Reference hash=#{@hash.inspect} snaks=#{@snaks.inspect}>"
+    "<Wikidatum::Reference hash=#{@hash.inspect} parts=#{@parts.inspect}>"
   end
 
   # @!visibility private
@@ -37,11 +37,11 @@ class Wikidatum::Reference
   # @param ref_json [Hash]
   # @return [Wikidatum::Reference]
   def self.marshal_load(ref_json)
-    snaks = ref_json['snaks'].values.flatten.map { |snak| Wikidatum::Snak.marshal_load(snak) }
+    parts = ref_json['parts'].map { |part| Wikidatum::ReferencePart.marshal_load(part) }
 
     Wikidatum::Reference.new(
       hash: ref_json['hash'],
-      snaks: snaks
+      parts: parts
     )
   end
 end

data/lib/wikidatum/reference_part.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+class Wikidatum::ReferencePart
+  # @return [String] ID of the property used, in the format "P123".
+  attr_reader :property_id
+
+  # @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 used, 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::ReferencePart 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
+  # reference part in the API and turns it into an actual instance of a
+  # ReferencePart.
+  #
+  # @param part_json [Hash]
+  # @return [Wikidatum::ReferencePart]
+  def self.marshal_load(part_json)
+    Wikidatum::ReferencePart.new(
+      property_id: part_json.dig('property', 'id'),
+      data_type: part_json.dig('property', 'data-type'),
+      value: Wikidatum::Utils.ingest_snak(part_json)
+    )
+  end
+end

data/lib/wikidatum/statement.rb

@@ -7,8 +7,11 @@ class Wikidatum::Statement
   # @return [String] property ID, in the format of 'P123'.
   attr_accessor :property_id
 
-  # @return [Wikidatum::Snak]
-  attr_accessor :mainsnak
+  # @return [String]
+  attr_accessor :data_type
+
+  # @return [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil]
+  attr_accessor :data_value
 
   # @return [Array<Wikidatum::Qualifier>]
   attr_accessor :qualifiers
@@ -22,15 +25,17 @@ class Wikidatum::Statement
 
   # @param id [String]
   # @param property_id [String] The 'P123' ID of the property that this statement represents.
-  # @param mainsnak [Wikidatum::Snak]
+  # @param data_type [String]
+  # @param data_value [DataType::GlobeCoordinate, DataType::MonolingualText, DataType::Quantity, DataType::WikibaseString, DataType::Time, DataType::WikibaseItem, nil]
   # @param qualifiers [Array<Wikidatum::Qualifier>]
   # @param references [Array<Wikidatum::Reference>]
   # @param rank [String] The rank of the given statement.
   #   Can have the values "preferred", "normal", or "deprecated". Defaults to "normal".
-  def initialize(id:, property_id:, mainsnak:, qualifiers:, references:, rank: 'normal')
+  def initialize(id:, property_id:, data_type:, data_value:, qualifiers:, references:, rank: 'normal')
     @id = id
     @property_id = property_id
-    @mainsnak = mainsnak
+    @data_type = data_type
+    @data_value = data_value
     @qualifiers = qualifiers
     @references = references
     @rank = rank
@@ -41,7 +46,8 @@ class Wikidatum::Statement
     {
       id: @id,
       property_id: @property_id,
-      mainsnak: @mainsnak.to_h,
+      data_type: @data_type,
+      data_value: @data_value.to_h,
       qualifiers: @qualifiers.map(&:to_h),
       references: @references.map(&:to_h),
       rank: @rank
@@ -56,10 +62,13 @@ class Wikidatum::Statement
   # @param statement_json [Hash]
   # @return [Wikidatum::Statement]
   def self.marshal_load(statement_json)
-    mainsnak = Wikidatum::Snak.marshal_load(statement_json['mainsnak'])
+    data_type = Wikidatum::Utils.symbolized_name_for_data_type(statement_json['property']['data-type'])
+    data_value = Wikidatum::Utils.ingest_snak(statement_json)
+
+    property_id = statement_json['property']['id']
 
-    qualifiers = statement_json['qualifiers'].to_a.flat_map do |_qualifier_prop_id, qualifier|
-      qualifier.map { |q| Wikidatum::Qualifier.marshal_load(q) }
+    qualifiers = statement_json['qualifiers'].to_a.flat_map do |qualifier|
+      Wikidatum::Qualifier.marshal_load(qualifier)
     end
     references = statement_json['references'].flat_map do |reference|
       Wikidatum::Reference.marshal_load(reference)
@@ -67,8 +76,9 @@ class Wikidatum::Statement
 
     Wikidatum::Statement.new(
       id: statement_json['id'],
-      property_id: mainsnak.property,
-      mainsnak: mainsnak,
+      property_id: property_id,
+      data_type: data_type,
+      data_value: data_value,
       qualifiers: qualifiers,
       references: references,
       rank: statement_json['rank']

data/lib/wikidatum/utils.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Wikidatum::Utils
+  # Yum!
+  def self.ingest_snak(json)
+    # the type can be 'novalue' (no value) or 'somevalue' (unknown), so we handle those as somewhat special cases
+    case json['value']['type']
+    when 'novalue'
+      Wikidatum::DataType::Base.marshal_load('novalue', nil)
+    when 'somevalue'
+      Wikidatum::DataType::Base.marshal_load('somevalue', nil)
+    when 'value'
+      Wikidatum::DataType::Base.marshal_load(json['property']['data-type'], json['value']['content'])
+    end
+  end
+
+  def self.symbolized_name_for_data_type(data_type)
+    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]).symbolized_name
+  end
+end

data/lib/wikidatum/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wikidatum
-  VERSION = '0.2.1'
+  VERSION = '0.3.1'
 end