wikidatum 0.1.0 → 0.2.0

data/lib/wikidatum/data_value_type/globe_coordinate.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_type/base'
+
+# The Globe Coordinate type datavalue JSON looks like this:
+#
+# ```json
+# {
+#   "datavalue": {
+#     "value": {
+#       "latitude": 52.516666666667,
+#       "longitude": 13.383333333333,
+#       "precision": 0.016666666666667,
+#       "globe": "http://www.wikidata.org/entity/Q2"
+#     },
+#     "type": "globecoordinate"
+#   }
+# }
+# ```
+class Wikidatum::DataValueType::GlobeCoordinate
+  # @return [Float]
+  attr_reader :latitude
+
+  # @return [Float]
+  attr_reader :longitude
+
+  # @return [Float]
+  attr_reader :precision
+
+  # @return [String] A URL (usually in the same Wikibase instance) representing the given globe model (e.g. Earth).
+  attr_reader :globe
+
+  # @param latitude [Float]
+  # @param longitude [Float]
+  # @param precision [Float]
+  # @param globe [String]
+  # @return [void]
+  def initialize(latitude:, longitude:, precision:, globe:)
+    @latitude = latitude
+    @longitude = longitude
+    @precision = precision
+    @globe = globe
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      latitude: @latitude,
+      longitude: @longitude,
+      precision: @precision,
+      globe: @globe
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'globecoordinate'
+  end
+
+  # The "datatype" value used by Wikibase, usually identical to wikibase_type
+  # but not always.
+  #
+  # @return [String]
+  def wikibase_datatype
+    'globe-coordinate' # yes, really
+  end
+
+  # @!visibility private
+  def self.marshal_load(data_value_json)
+    Wikidatum::DataValueType::Base.new(
+      type: :globe_coordinate,
+      value: new(
+        latitude: data_value_json['latitude'],
+        longitude: data_value_json['longitude'],
+        precision: data_value_json['precision'],
+        globe: data_value_json['globe']
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    {
+      latitude: @latitude,
+      longitude: @longitude,
+      precision: @precision,
+      globe: @globe
+    }
+  end
+end

data/lib/wikidatum/data_value_type/monolingual_text.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_type/base'
+
+# The Monolingual Text type datavalue JSON looks like this:
+#
+# ```json
+# {
+#   "datavalue": {
+#     "value": {
+#       "text": "South Pole Telescope eyes birth of first massive galaxies",
+#       "language": "en"
+#     },
+#     "type": "monolingualtext"
+#   }
+# }
+# ```
+class Wikidatum::DataValueType::MonolingualText
+  # @return [String] the language code, e.g. 'en'
+  attr_reader :language
+
+  # @return [String]
+  attr_reader :text
+
+  # @param language [String]
+  # @param text [String]
+  # @return [void]
+  def initialize(language:, text:)
+    @language = language
+    @text = text
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      language: @language,
+      text: @text
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'monolingualtext'
+  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)
+    Wikidatum::DataValueType::Base.new(
+      type: :monolingual_text,
+      value: new(
+        language: data_value_json['language'],
+        text: data_value_json['text']
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    {
+      language: @language,
+      text: @text
+    }
+  end
+end

data/lib/wikidatum/data_value_type/no_value.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_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
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    '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)
+  end
+end

data/lib/wikidatum/data_value_type/quantity.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_type/base'
+
+# The Quantity type datavalue JSON looks like this:
+#
+# ```json
+# {
+#   "datavalue": {
+#     "value": {
+#       "amount": "+10.38",
+#       "upperBound": "+10.375",
+#       "lowerBound": "+10.385",
+#       "unit": "http://www.wikidata.org/entity/Q712226"
+#     },
+#     "type": "quantity"
+#   }
+# }
+# ```
+class Wikidatum::DataValueType::Quantity
+  # @return [String] A string value like "+2", usually an integer but not always.
+  attr_reader :amount
+
+  # @return [String, nil] upper bound, if one is defined.
+  attr_reader :upper_bound
+
+  # @return [String, nil] lower bound, if one is defined.
+  attr_reader :lower_bound
+
+  # @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 upper_bound [String]
+  # @param lower_bound [String]
+  # @param unit [String]
+  # @return [void]
+  def initialize(amount:, upper_bound:, lower_bound:, unit:)
+    @amount = amount
+    @upper_bound = upper_bound
+    @lower_bound = lower_bound
+    @unit = unit
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      amount: @amount,
+      upper_bound: @upper_bound,
+      lower_bound: @lower_bound,
+      unit: @unit
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'quantity'
+  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)
+    Wikidatum::DataValueType::Base.new(
+      type: :quantity,
+      value: new(
+        amount: data_value_json['amount'],
+        upper_bound: data_value_json['upperBound'],
+        lower_bound: data_value_json['lowerBound'],
+        unit: data_value_json['unit']
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    {
+      amount: @amount,
+      upperBound: @upper_bound,
+      lowerBound: @lower_bound,
+      unit: @unit
+    }
+  end
+end

data/lib/wikidatum/data_value_type/some_value.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_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
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    '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)
+  end
+end

data/lib/wikidatum/data_value_type/time.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_type/base'
+
+# The time type datavalue JSON looks like this:
+#
+# ```json
+# {
+#   "datavalue": {
+#     "value": {
+#       "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
+# `calendarmodel` will still work.
+class Wikidatum::DataValueType::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:
+  #
+  # - years (9): "+2022-00-00T00:00:00Z", meaning "2022"
+  # - months (10): "+2022-03-00T00:00:00Z", meaning "March 2022"
+  # - days (11): "+2022-01-01T00:00:00Z", meaning "January 1, 2022"
+  #
+  # NOTE: Due to how precision works, it's probably not a good idea to use the
+  # Ruby `Date` or `Time` classes to parse these values unless it's a day-level
+  # precision. `Date.parse` will error if you give it a string like
+  # "2022-00-00", but it'll handle "2022-01-01" fine. `Time.new` will parse
+  # "2022-00-00" as January 1, 2022. There are various other pitfalls that make
+  # this generally dangerous unless you're very careful, which is why Wikidatum
+  # just handles the time as a string and leaves it to end-users to do what they
+  # like with it.
+  #
+  # @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
+  # - 1: 100 Megayears
+  # - 2: 10 Megayears
+  # - 3: Megayear
+  # - 4: 100 Kiloyears
+  # - 5: 10 Kiloyears
+  # - 6: millennium
+  # - 7: century
+  # - 8: 10 years
+  # - 9: years
+  # - 10: months
+  # - 11: days
+  # - 12: hours (unused)
+  # - 13: minutes (unused)
+  # - 14: seconds (unused)
+  #
+  # Usually only 9, 10, and 11 are used in actual items, though for some items
+  # you'll need to handle the other cases.
+  #
+  # For example, the date August 12, 2022 (aka "2022-08-12") would have a
+  # precision of days (11).
+  #
+  # If the time represented is August 2022 because the value is only precise
+  # to the month (e.g. a person who's birth is only known to the month rather
+  # than the exact day) that would have a precision of months (10).
+  #
+  # If the time represented is "2022" because it's only precise to the year,
+  # that would have a precision of years (9).
+  #
+  # @return [Integer]
+  attr_reader :precision
+
+  # @return [String] a URL (usually in the same Wikibase instance) representing the given calendar model (e.g. Gregorian, Julian).
+  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:)
+    @time = time
+    @time_zone = time_zone
+    @precision = precision
+    @calendar_model = calendar_model
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      time: @time,
+      time_zone: @time_zone,
+      precision: @precision,
+      pretty_precision: pretty_precision,
+      calendar_model: @calendar_model
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'time'
+  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)
+    Wikidatum::DataValueType::Base.new(
+      type: :time,
+      value: new(
+        time: data_value_json['time'],
+        time_zone: data_value_json['timezone'],
+        precision: data_value_json['precision'],
+        calendar_model: data_value_json['calendarmodel']
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    {
+      time: @time,
+      timezone: @time_zone,
+      precision: @precision,
+      calendarmodel: @calendar_model
+    }
+  end
+
+  PRETTY_PRECISIONS = {
+    0 => :gigayear,
+    1 => :'100_megayear',
+    2 => :'10_megayear',
+    3 => :megayear,
+    4 => :'100_kiloyear',
+    5 => :'10_kiloyear',
+    6 => :millennium,
+    7 => :century,
+    8 => :decade,
+    9 => :year,
+    10 => :month,
+    11 => :day,
+    12 => :hour,
+    13 => :minute,
+    14 => :second
+  }.freeze
+
+  # Returns a symbol representation of the precision, in singular form.
+  #
+  # Possible values are `:gigayear`, `:'100_megayear'`, `:'10_megayear'`,
+  # `:megayear`, `:'100_kiloyear'`, `:'10_kiloyear'`, `:millennium`, `:century`,
+  # `:decade`, `:year`, `:month`, `:day`, `:hour`, `:minute`, and `:second`.
+  #
+  # @return [Symbol]
+  def pretty_precision
+    PRETTY_PRECISIONS[@precision]
+  end
+
+  # Aliases to match the name returned by the REST API.
+
+  alias timezone time_zone
+  alias calendarmodel calendar_model
+end

data/lib/wikidatum/data_value_type/wikibase_entity_id.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_type/base'
+
+# The Wikibase Entity ID type datavalue JSON looks like this:
+#
+# ```json
+# {
+#   "datavalue": {
+#     "value": {
+#       "entity-type": "item",
+#       "numeric-id": 552863,
+#       "id": "Q552863"
+#     },
+#     "type": "wikibase-entityid"
+#   }
+# }
+# ```
+class Wikidatum::DataValueType::WikibaseEntityId
+  # @return [String] usually "item"
+  attr_reader :entity_type
+
+  # @return [Integer] the integer representation of the Wikibase ID.
+  attr_reader :numeric_id
+
+  # @return [String] in the format "Q123".
+  attr_reader :id
+
+  # @param entity_type [String]
+  # @param numeric_id [Integer]
+  # @param id [String]
+  # @return [void]
+  def initialize(entity_type:, numeric_id:, id:)
+    @entity_type = entity_type
+    @numeric_id = numeric_id
+    @id = id
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      entity_type: @entity_type,
+      numeric_id: @numeric_id,
+      id: @id
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'wikibase-entityid'
+  end
+
+  # The "datatype" value used by Wikibase, usually identical to wikibase_type
+  # but not always.
+  #
+  # @return [String]
+  def wikibase_datatype
+    'wikibase-item' # yes, really
+  end
+
+  # @!visibility private
+  def self.marshal_load(data_value_json)
+    Wikidatum::DataValueType::Base.new(
+      type: :wikibase_entity_id,
+      value: new(
+        entity_type: data_value_json['entity-type'],
+        numeric_id: data_value_json['numeric-id'],
+        id: data_value_json['id']
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    {
+      'entity-type': @entity_type,
+      'numeric-id': @numeric_id,
+      id: @id
+    }
+  end
+end

data/lib/wikidatum/data_value_type/wikibase_string.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_value_type/base'
+
+# The String type datavalue JSON looks like this:
+#
+# ```json
+# {
+#   "datavalue": {
+#     "value": "Foobar",
+#     "type": "string"
+#   }
+# }
+# ```
+class Wikidatum::DataValueType::WikibaseString
+  # @return [String] the value for the string.
+  attr_reader :string
+
+  # @param string [String]
+  # @return [void]
+  def initialize(string:)
+    @string = string
+  end
+
+  # @return [Hash]
+  def to_h
+    {
+      string: @string
+    }
+  end
+
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    '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(string)
+    Wikidatum::DataValueType::Base.new(
+      type: :string,
+      value: new(
+        string: string
+      )
+    )
+  end
+
+  # @!visibility private
+  def marshal_dump
+    @string
+  end
+end

data/lib/wikidatum/data_value_type.rb

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