wikidatum 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2ee435a3831b816e6e64465040a5197de654450551812b835b28329be9c287d
-  data.tar.gz: d23fb1902df5465b123fc0bcea0c7594fb64a6e918604a9f1bb1f4e4eadf6eff
+  metadata.gz: bcaa080ee9ab979f63dbde3fc8bca7f819ffd47b0a7d463c5f34bd57e1f2a988
+  data.tar.gz: c0226585d7af46f01c7127b7de8ec13cc22a593f414431acd3ec11f580425b88
 SHA512:
-  metadata.gz: ccd8210a5120fbbfb35ed03899938bf4ca4e5302bc93e3e53652180b86b221a3ec23afe57db78777ffcda5971150f7c0ed6af89cde7b294fe21d716491653c49
-  data.tar.gz: cb4e092b80c6ab871c1dd7f5bd46f700029eab7438c7a4063a2aee42b389c0e86ec0e387fc15fa996037d2478f494ac46572879078930c41c18ae6b7e4073e00
+  metadata.gz: '058da6289ed70d623511a2732b3c83c4d1b574aadc8570cbceee83c23df7adf71ef34e8413783cc1c0e9173c8ea7fcbb419d01b9fd58816278614bfd2f10e83f'
+  data.tar.gz: 0a0220e396643884380d858b0fe4cd4ab867f5f3a7ff92ccbbc54440ac4668f490a172f7244d567b093cd753044f845ced5daae3482514fa897cb0a42234ffe6

data/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
 
+## 0.3.2 - 2022-12-29
+### Added
+
+- Add support for the `commonsMedia`, `url`, and `external-id` data types.
+- Add `humanized_content` method to `Wikidatum::DataType::Base` class, for easier access to a Struct, string, or nil which represents the contents of the given data type.
+
 ## 0.3.1 - 2022-12-28
 ### Added
 

data/lib/wikidatum/client.rb

@@ -10,6 +10,8 @@ module Wikidatum
     STATEMENT_REGEX = /^Q?\d+\$[\w-]+$/.freeze
     VALID_RANKS = ['preferred', 'normal', 'deprecated'].freeze
     VALID_DATA_TYPES = [
+      'Wikidatum::DataType::CommonsMedia',
+      'Wikidatum::DataType::ExternalId',
       'Wikidatum::DataType::GlobeCoordinate',
       'Wikidatum::DataType::MonolingualText',
       'Wikidatum::DataType::NoValue',
@@ -17,7 +19,8 @@ module Wikidatum
       'Wikidatum::DataType::SomeValue',
       'Wikidatum::DataType::Time',
       'Wikidatum::DataType::WikibaseItem',
-      'Wikidatum::DataType::WikibaseString'
+      'Wikidatum::DataType::WikibaseString',
+      'Wikidatum::DataType::WikibaseUrl'
     ].freeze
 
     # @return [String] the root URL of the Wikibase instance we want to interact
@@ -110,6 +113,19 @@ module Wikidatum
       Wikidatum::Statement.marshal_load(response)
     end
 
+    # @!private
+    CONTENT_DATA_TYPES = [
+      'Wikidatum::DataType::CommonsMedia',
+      'Wikidatum::DataType::ExternalId',
+      'Wikidatum::DataType::GlobeCoordinate',
+      'Wikidatum::DataType::MonolingualText',
+      'Wikidatum::DataType::Quantity',
+      'Wikidatum::DataType::WikibaseString',
+      'Wikidatum::DataType::Time',
+      'Wikidatum::DataType::WikibaseItem',
+      'Wikidatum::DataType::WikibaseUrl'
+    ].freeze
+
     # Add a statement to an item.
     #
     # NOTE: Adding references/qualifiers with `add_statement` is untested and
@@ -195,9 +211,36 @@ module Wikidatum
     #     )
     #   )
     #
+    # @example Add a URL statement.
+    #   wikidatum_client.add_statement(
+    #     id: 'Q123',
+    #     property: 'P124',
+    #     value: Wikidatum::DataType::WikibaseUrl.new(
+    #       string: 'https://example.com'
+    #     )
+    #   )
+    #
+    # @example Add an External ID statement.
+    #   wikidatum_client.add_statement(
+    #     id: 'Q123',
+    #     property: 'P124',
+    #     value: Wikidatum::DataType::ExternalId.new(
+    #       string: '123'
+    #     )
+    #   )
+    #
+    # @example Add a statement for an image, video, or audio file from Wikimedia Commons.
+    #   wikidatum_client.add_statement(
+    #     id: 'Q123',
+    #     property: 'P124',
+    #     value: Wikidatum::DataType::CommonsMedia.new(
+    #       string: 'FooBar.jpg'
+    #     )
+    #   )
+    #
     # @param id [String, Integer] the ID of the item on which the statement will be added.
     # @param property [String, Integer] property ID in the format 'P123', or an integer.
-    # @param value [Wikidatum::DataType::GlobeCoordinate, Wikidatum::DataType::MonolingualText, Wikidatum::DataType::Quantity, Wikidatum::DataType::WikibaseString, Wikidatum::DataType::Time, Wikidatum::DataType::WikibaseItem, Wikidatum::DataType::NoValue, Wikidatum::DataType::SomeValue] the value of the statement being created.
+    # @param value [Wikidatum::DataType::CommonsMedia, Wikidatum::DataType::ExternalId, Wikidatum::DataType::GlobeCoordinate, Wikidatum::DataType::MonolingualText, Wikidatum::DataType::Quantity, Wikidatum::DataType::WikibaseString, Wikidatum::DataType::Time, Wikidatum::DataType::WikibaseItem, Wikidatum::DataType::WikibaseUrl, Wikidatum::DataType::NoValue, Wikidatum::DataType::SomeValue] the value of the statement being created.
     # @param qualifiers [Array<Wikidatum::Qualifier>]
     # @param references [Array<Wikidatum::Reference>]
     # @param rank [String, Symbol] Valid ranks are 'preferred', 'normal', or
@@ -233,7 +276,7 @@ module Wikidatum
             type: 'somevalue'
           }
         }
-      when 'Wikidatum::DataType::GlobeCoordinate', 'Wikidatum::DataType::MonolingualText', 'Wikidatum::DataType::Quantity', 'Wikidatum::DataType::WikibaseString', 'Wikidatum::DataType::Time', 'Wikidatum::DataType::WikibaseItem'
+      when *CONTENT_DATA_TYPES
         statement_hash = {
           property: {
             id: property

data/lib/wikidatum/data_type/base.rb

@@ -2,7 +2,7 @@
 
 # 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
+# https://doc.wikimedia.org/Wikibase/master/php/docs_topics_json.html#json_datavalues
 module Wikidatum::DataType
   class Base
     # Represents the type for this instance.
@@ -11,11 +11,14 @@ module Wikidatum::DataType
     #
     # - `:no_value`: No value
     # - `:some_value`: Unknown value
+    # - `:commons_media`: {DataType::CommonsMedia}
+    # - `:external_id`: {DataType::ExternalId}
     # - `:globe_coordinate`: {DataType::GlobeCoordinate}
     # - `:monolingual_text`: {DataType::MonolingualText}
     # - `:quantity`: {DataType::Quantity}
     # - `:string`: {DataType::WikibaseString}
     # - `:time`: {DataType::Time}
+    # - `:url`: {DataType::WikibaseUrl}
     # - `:wikibase_item`: {DataType::WikibaseItem}
     #
     # @return [Symbol]
@@ -44,6 +47,14 @@ module Wikidatum::DataType
       }
     end
 
+    # Get the humanized version of the content. Depending on the given data
+    # type, it will return values in different formats.
+    #
+    # @return [String, DataType::GlobeCoordinate::HumanizedStruct, DataType::MonolingualText::HumanizedStruct, DataType::Quantity::HumanizedStruct, DataType::Time::HumanizedStruct, nil]
+    def humanized_content
+      @content.humanized
+    end
+
     # @!visibility private
     #
     # @param data_type [String] The value of `data-type` for the given Statement or Qualifier's property.

data/lib/wikidatum/data_type/commons_media.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/wikibase_string'
+
+# Identical to the WikibaseString type, but we'll change some metadata to make
+# it clear that they're technically distinct types.
+class Wikidatum::DataType::CommonsMedia < Wikidatum::DataType::WikibaseString
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'commonsMedia'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :commons_media
+  end
+end

data/lib/wikidatum/data_type/external_id.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/wikibase_string'
+
+# Identical to the WikibaseString type, but we'll change some metadata to make
+# it clear that they're technically distinct types.
+class Wikidatum::DataType::ExternalId < Wikidatum::DataType::WikibaseString
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'external-id'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :external_id
+  end
+end

data/lib/wikidatum/data_type/globe_coordinate.rb

@@ -63,9 +63,19 @@ class Wikidatum::DataType::GlobeCoordinate
     'globe-coordinate'
   end
 
+  HumanizedStruct = Struct.new(:latitude, :longitude, :precision, :globe, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<latitude, longitude, precision, globe>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
-    :monolingual_text
+    :globe_coordinate
   end
 
   # @!visibility private

data/lib/wikidatum/data_type/monolingual_text.rb

@@ -49,6 +49,16 @@ class Wikidatum::DataType::MonolingualText
     'monolingualtext'
   end
 
+  HumanizedStruct = Struct.new(:language, :text, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<language, text>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :monolingual_text

data/lib/wikidatum/data_type/no_value.rb

@@ -9,11 +9,21 @@ require 'wikidatum/data_type/base'
 class Wikidatum::DataType::NoValue < Wikidatum::DataType::Base
   # The "type" value used by Wikibase, for use when creating/updating statements.
   #
+  # In this case, the type is a lie.
+  #
   # @return [String]
   def wikibase_type
     'string'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [nil]
+  def humanized
+    nil
+  end
+
   # @!visibility private
   def self.marshal_load(_data_value_json)
     new(type: :no_value, content: nil)

data/lib/wikidatum/data_type/quantity.rb

@@ -49,6 +49,16 @@ class Wikidatum::DataType::Quantity
     'quantity'
   end
 
+  HumanizedStruct = Struct.new(:amount, :unit, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<amount, unit>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :quantity

data/lib/wikidatum/data_type/some_value.rb

@@ -9,11 +9,21 @@ require 'wikidatum/data_type/base'
 class Wikidatum::DataType::SomeValue < Wikidatum::DataType::Base
   # The "type" value used by Wikibase, for use when creating/updating statements.
   #
+  # In this case, the type is a lie.
+  #
   # @return [String]
   def wikibase_type
     'string'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [nil]
+  def humanized
+    nil
+  end
+
   # @!visibility private
   def self.marshal_load(_data_value_json)
     new(type: :some_value, content: nil)

data/lib/wikidatum/data_type/time.rb

@@ -109,6 +109,16 @@ class Wikidatum::DataType::Time
     'time'
   end
 
+  HumanizedStruct = Struct.new(:time, :precision, :calendar_model, keyword_init: true)
+
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [HumanizedStruct<time, precision, pretty_precision, calendar_model>]
+  def humanized
+    HumanizedStruct.new(to_h)
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :time

data/lib/wikidatum/data_type/wikibase_item.rb

@@ -40,6 +40,14 @@ class Wikidatum::DataType::WikibaseItem
     'wikibase-item'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [String]
+  def humanized
+    @id
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :wikibase_item

data/lib/wikidatum/data_type/wikibase_string.rb

@@ -40,6 +40,14 @@ class Wikidatum::DataType::WikibaseString
     'string'
   end
 
+  # The content of the data value object. Use this to get a more sensible
+  # representation of the statement's contents.
+  #
+  # @return [String]
+  def humanized
+    @string
+  end
+
   # @return [Symbol]
   def self.symbolized_name
     :string

data/lib/wikidatum/data_type/wikibase_url.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/wikibase_string'
+
+# Identical to the WikibaseString type, but we'll change some metadata to make
+# it clear that they're technically distinct types.
+class Wikidatum::DataType::WikibaseUrl < Wikidatum::DataType::WikibaseString
+  # The "type" value used by Wikibase, for use when creating/updating statements.
+  #
+  # @return [String]
+  def wikibase_type
+    'url'
+  end
+
+  # @return [Symbol]
+  def self.symbolized_name
+    :url
+  end
+end

data/lib/wikidatum/data_type.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'wikidatum/data_type/base'
+require 'wikidatum/data_type/commons_media'
+require 'wikidatum/data_type/external_id'
 require 'wikidatum/data_type/globe_coordinate'
 require 'wikidatum/data_type/monolingual_text'
 require 'wikidatum/data_type/no_value'
@@ -9,3 +11,4 @@ require 'wikidatum/data_type/some_value'
 require 'wikidatum/data_type/time'
 require 'wikidatum/data_type/wikibase_item'
 require 'wikidatum/data_type/wikibase_string'
+require 'wikidatum/data_type/wikibase_url'

data/lib/wikidatum/version.rb

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

data/lib/wikidatum.rb

@@ -65,9 +65,10 @@ module Wikidatum
   end
 
   module DataType
-    # TODO: Add commonsMedia and url to the possible types.
     # rubocop:disable Lint/SymbolConversion
     DATA_TYPES = {
+      'commonsMedia': 'Wikidatum::DataType::CommonsMedia',
+      'external-id': 'Wikidatum::DataType::ExternalId',
       'globe-coordinate': 'Wikidatum::DataType::GlobeCoordinate',
       'monolingualtext': 'Wikidatum::DataType::MonolingualText',
       'novalue': 'Wikidatum::DataType::NoValue',
@@ -75,6 +76,7 @@ module Wikidatum
       'somevalue': 'Wikidatum::DataType::SomeValue',
       'string': 'Wikidatum::DataType::WikibaseString',
       'time': 'Wikidatum::DataType::Time',
+      'url': 'Wikidatum::DataType::WikibaseUrl',
       'wikibase-item': 'Wikidatum::DataType::WikibaseItem'
     }.freeze
     # rubocop:enable Lint/SymbolConversion

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wikidatum
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Connor Shea
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-28 00:00:00.000000000 Z
+date: 2022-12-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -40,6 +40,8 @@ files:
 - lib/wikidatum/client.rb
 - lib/wikidatum/data_type.rb
 - lib/wikidatum/data_type/base.rb
+- lib/wikidatum/data_type/commons_media.rb
+- lib/wikidatum/data_type/external_id.rb
 - lib/wikidatum/data_type/globe_coordinate.rb
 - lib/wikidatum/data_type/monolingual_text.rb
 - lib/wikidatum/data_type/no_value.rb
@@ -48,6 +50,7 @@ files:
 - lib/wikidatum/data_type/time.rb
 - lib/wikidatum/data_type/wikibase_item.rb
 - lib/wikidatum/data_type/wikibase_string.rb
+- lib/wikidatum/data_type/wikibase_url.rb
 - lib/wikidatum/item.rb
 - lib/wikidatum/qualifier.rb
 - lib/wikidatum/reference.rb