runeterra_cards 0.2.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e072725d1ac2b1af062cfa42826a5efd9eb991eb51f65d8897b90a5110fbf8c7
-  data.tar.gz: a3a260958b84602a94e53d0ccaa19f714fb7fbdccf036569d195419e13dbbc77
+  metadata.gz: 13de26db2b79d60bca9fce39d36d3d82fcaaa19fbcdae3dc2c6f34c785253d91
+  data.tar.gz: 061a9c9e56f751fc2451166af0e9b27f415c4b9293b1ac1d0dc58df714a46a6b
 SHA512:
-  metadata.gz: f7c8a7b954a62793eb396e299e52ea104e8cf08b0d9d18c616b8d37bad973620c01981460dced44320f09bfc9f7a84423d1e5f6f8caba58db9c9ba35ec70ce01
-  data.tar.gz: ac21bf2ed0a0ee367771a33b0417456eb1986469998760484875e5d5871d03e7a720cfd1a2ef9a808e69eb42339cd92ecc10439755b4b6959e60ca36b4b510ea
+  metadata.gz: cde13398e27b94c917c74efb2cedf4fa82c3af5b8cc7e2da4a19af959176bf24703574170718d17ace331cf20e23b019001150fdd12a90a81688cd2f17f186c3
+  data.tar.gz: 18d73970af5591a2f65ccf9ba4739800d1025f042499416ed5e2ccd6b5ad33797c3b4640bd7b89dd99600b1a4f2a3bc0f641be0499d392ad56385ec53318dc22

data/.yardopts

@@ -0,0 +1,4 @@
+--output-dir yard
+--readme doc/README.md
+-
+doc/*

data/doc/CHANGELOG.md

@@ -4,9 +4,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2021-02-05
+
+Fixed
+
+- Fixed issue where card numbers > 127 came out extremely wrong, e.g. Aphelios and several other of the new cards ([issue #4](https://github.com/zofrex/runeterra_cards/issues/4))
+## [0.4.0] - 2020-12-08
+### Added
+- [`CardMetadata` now has a `#cost` attribute representing the mana cost of a card.](https://github.com/zofrex/runeterra_cards/pull/3) (thanks, [nieszkah](https://github.com/alpm)!) Technically this is backwards-compatibility breaking as it makes a new field in metadata json mandatory.
+
+## [0.3.0] - 2020-08-31
+### Added
+- `Cost` class to represent crafting cost as wildcards & shards.
+- `Metadata#cost_of` to get the cost of crafting a `CardSet`.
+- Documented everything that is public & non-deprecated.
+
+## [0.2.3] - 2020-08-31
+### Fixed
+- Fixed issue with documentation not rendering on rubydoc.info.
+
+## [0.2.2] - 2020-08-30
+### Fixed
+- Included .yardopts in the Gem so README and CHANGELOG get included in documentation generated from the Gem.
+
 ## [0.2.1] - 2020-08-29
 ### Fixed
-- Correctly packaged README and CHANGELOG in the Gem
+- Correctly packaged README and CHANGELOG in the Gem.
 
 ## [0.2.0] - 2020-08-29
 ### Added

data/doc/README.md

@@ -9,13 +9,13 @@ This library makes it easy to decode Legends of Runeterra deck codes, load Data
 Add the following to your `Gemfile`:
 
 ```
-gem 'runeterra_cards', '~> 0.2.0'
+gem 'runeterra_cards', '~> 0.4.1'
 ```
 
 Or, if you're building a Gem, your `.gemspec`:
 
 ```
-  spec.add_dependency 'runeterra_cards', '~> 0.2.0'
+  spec.add_dependency 'runeterra_cards', '~> 0.4.1'
 ```
 
 ## Updates & Versioning

data/lib/runeterra_cards.rb

@@ -7,8 +7,15 @@ require 'runeterra_cards/card_and_count'
 require 'runeterra_cards/card_metadata'
 require 'runeterra_cards/metadata'
 require 'runeterra_cards/card_set'
+require 'runeterra_cards/cost'
 
+# The top-level module for +runeterra_cards+.
+#
+# Some of the most useful classes are {CardSet} and {Metadata}.
+#
+# You might also want to check out the {file:doc/README.md} and the {file:doc/CHANGELOG.md}.
 module RuneterraCards
   # The version of deck encoding supported
   SUPPORTED_VERSION = 2
+  public_constant :SUPPORTED_VERSION
 end

data/lib/runeterra_cards/card_and_count.rb

@@ -16,7 +16,7 @@ module RuneterraCards
     # @param faction_number [Fixnum]
     # @param card_number [Fixnum]
     # @param count [Fixnum]
-    def initialize(code: nil, count:, set: nil, faction_number: nil, card_number: nil)
+    def initialize(count:, code: nil, set: nil, faction_number: nil, card_number: nil)
       if code
         raise if set || faction_number || card_number
 
@@ -30,10 +30,12 @@ module RuneterraCards
       @count = count
     end
 
+    #:nodoc:
     def eql?(other)
       code.eql?(other.code) && count.equal?(other.count)
     end
 
+    #:nodoc:
     def hash
       [code, count].hash
     end

data/lib/runeterra_cards/card_metadata.rb

@@ -26,6 +26,10 @@ module RuneterraCards
     # @return [String]
     attr_reader :card_code
 
+    # Returns the cost attribute. For example: 3.
+    # @return [Fixnum]
+    attr_reader :cost
+
     # Returns the card's rarity as a symbol. Can be one of: +:none+, +:common+, +:rare+, +:epic+, or +:champion+
     # @return [Symbol]
     attr_reader :rarity
@@ -38,12 +42,15 @@ module RuneterraCards
     # @option hash [String] name
     # @option hash [String] cardCode
     # @option hash [Boolean] collectible
+    # @option hash [Fixnum] cost
+    # @option hash [String] rarityRef
     #
     # @raise [MissingCardDataError] if any of the expected hash parameters are missing, or if +rarityRef+ contains an
     #   unexpected value.
     def initialize(hash)
       begin
-        @name, @card_code, @collectible, rarity_ref = hash.fetch_values('name', 'cardCode', 'collectible', 'rarityRef')
+        @name, @card_code, @collectible, @cost, rarity_ref =
+          hash.fetch_values('name', 'cardCode', 'collectible', 'cost', 'rarityRef')
       rescue KeyError => e
         raise MetadataLoadError.new(hash['name'] || hash['cardCode'], "Missing expected key: #{e.key}")
       end
@@ -51,8 +58,7 @@ module RuneterraCards
       @rarity = RARITIES[rarity_ref]
       return unless rarity.nil?
 
-      raise MetadataLoadError.new(name, "Invalid value for rarityRef, got: #{rarity_ref}, "\
-"expected one of: #{RARITIES.keys.join ', '}")
+      raise MetadataLoadError.invalid_rarity(name, rarity_ref, RARITIES.keys)
     end
 
     # Whether or not the card is collectible.

data/lib/runeterra_cards/card_set.rb

@@ -7,8 +7,10 @@ module RuneterraCards
   #
   # @todo The API to this class is very unstable and will change a lot in a coming release.
   class CardSet
+    # @return [Hash<String,Fixnum>]
     attr_reader :cards
 
+    # @param [Hash<String,Fixnum>] cards A Hash of card codes mapping to card counts
     def initialize(cards)
       @cards = cards
     end
@@ -18,30 +20,40 @@ module RuneterraCards
       new(Hash[set.map { |cac| [cac.code, cac.count] }])
     end
 
+    # Subtract another {CardSet CardSet} from this one. Items with count 0 are not represented in the returned
+    # {CardSet CardSet}, they are removed altogether.
+    # @param [CardSet] other An object that responds to {#count_for_card_code}
+    # @return [CardSet]
     def -(other)
-      remaining_cards = cards.each_with_object({}) do |(code, count), result|
-        new_count = count - other.count_for_card_code(code)
-        result[code] = new_count unless new_count.equal?(0)
-      end
+      remaining_cards =
+        cards.each_with_object({}) do |(code, count), result|
+          new_count = count - other.count_for_card_code(code)
+          result[code] = new_count unless new_count.equal?(0)
+        end
 
       CardSet.new(remaining_cards)
     end
 
-    # @return Enumerator<CardAndCount>
+    # @return [Enumerator<CardAndCount>]
     # @deprecated
     def as_card_and_counts
       cards.map { |code, count| CardAndCount.new(code: code, count: count) }
     end
 
+    # Returns how many of the given card are in this CardSet.
+    # @param [String] code Card code, e.g. "01DE031"
+    # @return [Fixnum] How many of the card are in this CardSet, or 0 if it isn't present.
     def count_for_card_code(code)
       cards[code] || 0
     end
 
+    # Parse a Deck Code.
     # @param deck_code [String]
     # @raise [Base32Error] if the deck code cannot be Base32 decoded.
     # @raise [UnrecognizedVersionError] if the deck code's version is not supported by this library
     #   (see {SUPPORTED_VERSION}).
     # @raise [EmptyInputError] if the deck code is an empty string.
+    # @return [CardSet]
     def self.from_deck_code(deck_code)
       binary_data = decode_base32(deck_code)
       format, version = decode_format_and_version(binary_data[0])
@@ -50,8 +62,9 @@ module RuneterraCards
 
       raise unless format.equal? 1
 
-      int_array = binary_data[1..].unpack('w*')
+      int_array = unpack_uleb128(binary_data[1..])
       cards = assemble_card_list(int_array)
+
       from_card_and_counts(cards)
     end
 
@@ -80,6 +93,8 @@ module RuneterraCards
 
     private_class_method :decode_format_and_version
 
+    # @param [Array<Fixnum>] array
+    # @return [Array<CardAndCount>]
     def self.assemble_card_list(array)
       3.downto(1).flat_map do |number_of_copies|
         set_faction_combination_count = array.shift
@@ -94,5 +109,19 @@ module RuneterraCards
     end
 
     private_class_method :assemble_card_list
+
+    # @param [String] binary
+    # @return [Enumerable<Fixnum>]
+    def self.unpack_uleb128(binary)
+      binary.each_byte.slice_after { |b| (b & 0b1000_0000).zero? }.map do |int_bytes|
+        acc = 0
+        int_bytes.each_with_index do |byte, index|
+          acc += (byte & 0b0111_1111) << (7 * index)
+        end
+        acc
+      end
+    end
+
+    private_class_method :unpack_uleb128
   end
 end

data/lib/runeterra_cards/cost.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RuneterraCards
+  # Represents the cost of a {CardSet}, as wildcards or shards.
+  # To get the cost of a {CardSet} you need to call {Metadata#cost_of}, as rarity (and therefore cost) is a property
+  # of metadata.
+  #
+  # A {Cost} object tells you how many wildcards would be needed to craft a {CardSet}, or alternatively how many
+  # shards would be needed. You can figure out the cost of a mixture of wildcards and shards by creating a new {Cost}
+  # object representing the wildcards to be spent, and subtracting that from the original {Cost} object.
+  #
+  # @example Getting the shard cost for a {CardSet}
+  #   cost = metadata.cost_of(card_set)
+  #   cost.shards #=> 3000
+  #
+  # @example Getting wildcard costs for a {CardSet}
+  #   cost = metadata.cost_of(card_set)
+  #   cost.common #=> 3
+  #   cost.rare #=> 1
+  #   # etc
+  #
+  # @example Getting remaining cost after spending some wildcards
+  #   cost = metadata.cost_of(card_set)
+  #   cost.dust #=> 11500
+  #
+  #   wildcards_in_hand = Cost.new(10, 5, 3, 1)
+  #   remaining_cost = cost - wildcards_in_hand
+  #   remaining_cost.dust #=> 5100
+  class Cost
+    # The number of Common wildcards needed
+    # @return [Fixnum] count
+    attr_reader :common
+
+    # The number of Rare wildcards needed
+    # @return [Fixnum] count
+    attr_reader :rare
+
+    # The number of Epic wildcards needed
+    # @return [Fixnum] count
+    attr_reader :epic
+
+    # The number of Champion wildcards needed
+    # @return [Fixnum] count
+    attr_reader :champion
+
+    # @param [Fixnum] common
+    # @param [Fixnum] rare
+    # @param [Fixnum] epic
+    # @param [Fixnum] champion
+    def initialize(common, rare, epic, champion)
+      @common, @rare, @epic, @champion = common, rare, epic, champion
+    end
+
+    # The number of shards needed. I.e. the equivalent amount of shards for all these wildcards.
+    # @return [Fixnum] shards
+    def shards
+      common * 100 +
+        rare * 300 +
+        epic * 1200 +
+        champion * 3000
+    end
+
+    # Whether this Cost is equal to another. Equality means exactly the same number of each wildcard, not just the
+    # same shard count.
+    # @param [Cost] other an object that response to {#common}, {#rare}, {#epic}, and {#champion}.
+    # @return [Boolean] equal?
+    def ==(other)
+      common.equal?(other.common) &&
+        rare.equal?(other.rare) &&
+        epic.equal?(other.epic) &&
+        champion.equal?(other.champion)
+    end
+
+    # Subtracts another Cost from this one. Subtraction is performed by subtracting each wildcard type individually,
+    # not by operating on the shard count. The minimum value any wildcard will have is zero, so +5 - 7 = 0+ for
+    # example.
+    # @note This will not return negative values.
+    # @param [Cost] other an object that response to {#common}, {#rare}, {#epic}, and {#champion}.
+    # @return [Cost] The remaining cost, with a floor of 0.
+    # @example
+    #   minuend    = Cost.new(9, 8, 5, 2)
+    #   subtrahend = Cost.new(7, 8, 2, 3)
+    #   result = minuend - subtrahend
+    #   result   #=> Cost.new(2, 0, 3, 0)
+    def -(other)
+      Cost.new(
+        [common   - other.common,   0].max,
+        [rare     - other.rare,     0].max,
+        [epic     - other.epic,     0].max,
+        [champion - other.champion, 0].max
+      )
+    end
+  end
+end

data/lib/runeterra_cards/errors.rb

@@ -8,14 +8,17 @@ module RuneterraCards
   # This exception is raised if the deck code cannot be Base32-decoded. This probably means it isn't a deck code, or
   # got malformed somehow.
   class Base32Error < DeckCodeParseError
+    # Returns a new instance of Base32Error with a helpful error message preloaded.
     def initialize
-      super('Encountered an error while Base32 decoding deck code.' \
+      super(
+        'Encountered an error while Base32 decoding deck code.' \
         ' Probably an invalid deck code, or possibly a bug in the Base32 handling.')
     end
   end
 
   # This exception is raised if the deck code is an empty string.
   class EmptyInputError < DeckCodeParseError
+    # Returns a new instance of EmptyInputError with a helpful error message preloaded.
     def initialize
       super('The input was an empty string')
     end
@@ -32,9 +35,12 @@ module RuneterraCards
     # @return [Fixnum] the version number encountered in the deck code
     attr_accessor :version
 
+    # @param [Fixnum] expected The version number we were expecting to see in the deck code.
+    # @param [Fixnum] got The version number we actually got.
     def initialize(expected, got)
-      super("Unrecognized deck code version number: #{got}, was expecting: #{expected}. \
-Possibly an invalid deck code, possibly you need to update the deck code library version.")
+      super(
+        "Unrecognized deck code version number: #{got}, was expecting: #{expected}. "\
+        'Possibly an invalid deck code, possibly you need to update the deck code library version.')
       @version = got
     end
   end
@@ -50,8 +56,10 @@ Possibly an invalid deck code, possibly you need to update the deck code library
     # @return [Fixnum] the faction number that was unrecognized
     attr_reader :faction_number
 
+    # @param [Fixnum] faction_number The faction number we encountered and did not recognise.
     def initialize(faction_number)
-      super("Unrecognized faction number '#{faction_number}'."\
+      super(
+        "Unrecognized faction number '#{faction_number}'."\
         ' Possibly you need to update this library to a newer version')
       @faction_number = faction_number
     end
@@ -61,7 +69,7 @@ Possibly an invalid deck code, possibly you need to update the deck code library
   # The message will tell you what data was not right, and the {#card} attribute will tell you which card had issues,
   # if possible.
   #
-  # @see CardMetadata#initialize
+  # @see CardMetadata#initialize CardMetadata#initialize for details on when this error is raised.
   class MetadataLoadError < StandardError
     # Return the name or card code of the card that was missing an expected attribute.
     # @return [String] name if the name was present
@@ -69,6 +77,8 @@ Possibly an invalid deck code, possibly you need to update the deck code library
     # @return [nil] if neither name nor card code were present
     attr_reader :card
 
+    # @param [String] card The card's name or cardCode.
+    # @param [String] problem Details on the problem encountered loading the card.
     def initialize(card, problem)
       if card.nil?
         super("Error loading data for unknown card (no code or name): #{problem}")
@@ -77,5 +87,15 @@ Possibly an invalid deck code, possibly you need to update the deck code library
       end
       @card = card
     end
+
+    # Create a {MetadataLoadError MetadataLoadError} with a helpful message regarding an invalid value for rarityRef.
+    # @param [String] card The card name that had an invalid rarityRef value.
+    #
+    # @param [String] given The value that rarityRef had.
+    # @param [Enumerable<String>] expected A list of values that would have been valid.
+    # @return [MetadataLoadError]
+    def self.invalid_rarity(card, given, expected)
+      new(card, "Invalid value for rarityRef, got: #{given}, expected one of: #{expected.join ', '}")
+    end
   end
 end

data/lib/runeterra_cards/factions.rb

@@ -15,6 +15,7 @@ module RuneterraCards
     6 => 'BW',
     9 => 'MT',
   }.freeze
+  public_constant :FACTION_IDENTIFIERS_FROM_INT
 
   # A map from two-letter Faction identifiers to their integer identifiers
   # @example
@@ -30,4 +31,5 @@ module RuneterraCards
     'BW' => 6,
     'MT' => 9,
   }.freeze
+  public_constant :FACTION_INTS_FROM_IDENTIFIER
 end

data/lib/runeterra_cards/metadata.rb

@@ -20,6 +20,7 @@ module RuneterraCards
   # @note This class cannot yet handle metadata for multiple locales at the same time. You will need multiple instances
   #   of this class, one for each locale, if you wish to handle multiple locales at this time.
   class Metadata
+    # Create a new, empty, metadata repository.
     def initialize
       @cards = {}
     end
@@ -57,5 +58,15 @@ module RuneterraCards
     def full_set
       CardSet.new(all_collectible.keys.each_with_object({}) { |code, result| result[code] = 3 })
     end
+
+    # @param [CardSet] card_set
+    # @return [Cost] the cost of crafting all the cards in the supplied CardSet
+    def cost_of(card_set)
+      rarity_and_count = card_set.cards.map { |card, count| [lookup_card(card).rarity, count] }
+      total = { common: 0, rare: 0, epic: 0, champion: 0 }
+      rarity_and_count.each { |(rarity, count)| total[rarity] += count }
+
+      Cost.new(total.fetch(:common), total.fetch(:rare), total.fetch(:epic), total.fetch(:champion))
+    end
   end
 end

data/lib/runeterra_cards/version.rb

@@ -2,5 +2,6 @@
 
 module RuneterraCards
   # The version of this library
-  VERSION = '0.2.1'
+  VERSION = '0.4.1'
+  public_constant :VERSION
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: runeterra_cards
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.1
 platform: ruby
 authors:
 - James "zofrex" Sanderson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-29 00:00:00.000000000 Z
+date: 2021-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -80,20 +80,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.4.2
+- !ruby/object:Gem::Dependency
+  name: mutant
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: mutant-minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.10.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -114,14 +128,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.89.1
+        version: '1.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.89.1
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: rubocop-minitest
   requirement: !ruby/object:Gem::Requirement
@@ -142,28 +156,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.5.1
 - !ruby/object:Gem::Dependency
   name: rubocop-performance
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '1.8'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -185,6 +199,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE.txt
 - doc/CHANGELOG.md
 - doc/README.md
@@ -192,6 +207,7 @@ files:
 - lib/runeterra_cards/card_and_count.rb
 - lib/runeterra_cards/card_metadata.rb
 - lib/runeterra_cards/card_set.rb
+- lib/runeterra_cards/cost.rb
 - lib/runeterra_cards/errors.rb
 - lib/runeterra_cards/factions.rb
 - lib/runeterra_cards/metadata.rb
@@ -201,9 +217,9 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/zofrex/runeterra_cards/issues
-  changelog_uri: https://www.rubydoc.info/gems/runeterra_cards/doc/CHANGELOG.md
-  mailing_list_uri: https://groups.example.com/bestgemever
+  changelog_uri: https://www.rubydoc.info/gems/runeterra_cards/file/doc/CHANGELOG.md
   source_code_uri: https://github.com/zofrex/runeterra_cards
+  documentation_uri: https://www.rubydoc.info/gems/runeterra_cards/
 post_install_message: 
 rdoc_options: []
 require_paths: