runeterra_cards 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 275e8ca4e8362b65da7022dc3042e9fbe3b0970f52443e652476757be52125f1
-  data.tar.gz: ab803e005acf47f9499aad38aaad76d0e1c59c275dc4457bc8735208f08baace
+  metadata.gz: 5e7902d9b185d9d9230fefa7917c9ebf6cfcc7342dedb80e2388594538d940e5
+  data.tar.gz: 7412372ff827c53911e6a16430979a80f8f9bb12ce4e0901e1e95ca60673409a
 SHA512:
-  metadata.gz: f406aad97cd4b6b57b356f08ff665661d3edecd608467b0a04b2c76d434927bc406cd01fec7f02aa171701f0a0f89fd2e322de7cbc871d18cb58993c9ae4d9e3
-  data.tar.gz: 96023313de8c2868fbf551185224a9441a13e30ddb297f9766b69b07481f4d21c1a56b78052ec09ba3a5aa22878c39f1c94ef196a235838b5cc447bb08255d96
+  metadata.gz: 5f5caa2b4ebe93ce457b5806fea9add1da1aaf0486cf8f6983846b1564adc3ee920331397f0a3b054affce1f8e6464f9e8eb355456ce58366308599c57f9e9af
+  data.tar.gz: f613c1bdd35331fcb7ceac4846a252630f3e68556b0d577500e655a0dbc60e5c6406f1ecbe423e73ff9c0d2c0313622b821d7254cf421714d1c28647c8f5e6b4

data/.yardopts

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

data/doc/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+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.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.
+
+## [0.2.0] - 2020-08-29
+### Added
+- Added support for the Mount Targon faction
+- UnrecognizedVersionError#version returns the version number that wasn't recognized.
+- UnrecognizedFactionError, which is raised by CardAndCount#new (and by extension, CardSet#from_deck_code) if an unrecognized faction number is encountered.
+
+### Changed
+- FACTION_IDENTIFIERS_FROM_INT is now a Hash instead of an Array. The API for looking up a faction identifier by integer should remain unchanged in most cases.
+
+## [0.1.0] - 2020-08-28
+### Added
+- Initial public release, with support for loading deck codes (Bilgewater and earlier) and loading metadata from Legends of Runeterra Data Dragon.

data/doc/README.md

@@ -0,0 +1,64 @@
+<!-- This is the README file for the Gem documentation / online documentation. It should be thorough and authoritative for using the Gem, but not discuss development concerns, which belong in the Github README. -->
+
+## Description
+
+This library makes it easy to decode Legends of Runeterra deck codes, load Data Dragon metadata for cards, and perform operations on the data.
+
+## Installation
+
+Add the following to your `Gemfile`:
+
+```
+gem 'runeterra_cards', '~> 0.3.0'
+```
+
+Or, if you're building a Gem, your `.gemspec`:
+
+```
+  spec.add_dependency 'runeterra_cards', '~> 0.3.0'
+```
+
+## Updates & Versioning
+
+This library will conform to [semantic versioning](https://semver.org/) once it hits 1.0. In the meantime, you can rely on the minor version (Y in x.Y.z) being bumped for backwards-incompatible changes.
+
+All changes are documented in the {file:doc/CHANGELOG.md}.
+
+## Main Concepts
+
+Your typical main entry points to this library will be {RuneterraCards::CardSet} for manipulating deck codes and/or {RuneterraCards::Metadata} for handling Data Dragon card data.
+
+## Examples
+
+Load a deck code:
+
+```
+require 'runeterra_cards'
+
+deck_code = 'CEBAOAQGC4OSKJZJF44ACAQFBIBAIAQGAEPCYNIBAICQOAYCAECSOMADAIDAKGRWAEBAKAY'
+deck = RuneterraCards::CardSet.from_deck_code(deck_code)
+
+deck.count_for_card_code('02BW053') #=> 2
+
+deck.cards.each do |card, count|
+  puts "#{card} x#{count}"
+end
+```
+
+Load metadata from Legends of Runeterra Data Dragon:
+
+```
+require 'runeterra_cards'
+
+metadata = RuneterraCards::Metadata.new
+
+metadata.add_set_file 'set1-en_us.json'
+metadata.add_set_file 'set2-en_us.json'
+
+card = metadata.lookup_card '02BW053'
+card.name #=> "Nautilus"
+```
+
+## Development & Contributing
+
+See the [Github project](https://github.com/zofrex/runeterra_cards) for more details.

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

@@ -23,17 +23,19 @@ module RuneterraCards
         @code = code
       else
         padded_set = format('%<i>02d', i: set)
-        faction = FACTION_IDENTIFIERS_FROM_INT.fetch(faction_number)
+        faction = FACTION_IDENTIFIERS_FROM_INT.fetch(faction_number) { |key| raise UnrecognizedFactionError, key }
         padded_card_number = format('%<i>03d', i: card_number)
         @code = "#{padded_set}#{faction}#{padded_card_number}"
       end
       @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

@@ -51,8 +51,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])
@@ -80,6 +92,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

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,6 +8,7 @@ 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.' \
         ' Probably an invalid deck code, or possibly a bug in the Base32 handling.')
@@ -16,6 +17,7 @@ module RuneterraCards
 
   # 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
@@ -29,9 +31,34 @@ module RuneterraCards
   # issue relating to this. If none exists, then file one!
   # @see SUPPORTED_VERSION
   class UnrecognizedVersionError < DeckCodeParseError
+    # @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.")
+      @version = got
+    end
+  end
+
+  # This exception is raised if the deck code contains an unexpected faction number. (see the table at
+  # {https://github.com/RiotGames/LoRDeckCodes} for what 'faction number' means.) This most likely means that
+  # Legends of Runeterra has a new faction and you need to update to a newer version of this library to handle it.
+  #
+  # Check that the {#faction_number} causing issues is listed in {https://github.com/RiotGames/LoRDeckCodes
+  # the table on Github}. If it isn't then something else has gone wrong. If it is, and updating this library doesn't
+  # fix the issue, then the library needs updating - {https://github.com/zofrex/runeterra_cards/issues file an issue}.
+  class UnrecognizedFactionError < DeckCodeParseError
+    # @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}'."\
+        ' Possibly you need to update this library to a newer version')
+      @faction_number = faction_number
     end
   end
 
@@ -39,7 +66,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
@@ -47,6 +74,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}")
@@ -55,5 +84,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

@@ -1,11 +1,21 @@
 # frozen_string_literal: true
 
 module RuneterraCards
-  # An array of the two-letter Faction identifiers, indexed by their integer identifiers
+  # An map from integer faction identifiers to their two-letter identifiers
   # @example
   #   FACTION_IDENTIFIERS_FROM_INT[2] #=> "IO"
-  # @return [Array<String>]
-  FACTION_IDENTIFIERS_FROM_INT = %w[DE FR IO NX PZ SI BW].freeze
+  # @return [Hash<Fixnum,String>]
+  FACTION_IDENTIFIERS_FROM_INT = {
+    0 => 'DE',
+    1 => 'FR',
+    2 => 'IO',
+    3 => 'NX',
+    4 => 'PZ',
+    5 => 'SI',
+    6 => 'BW',
+    9 => 'MT',
+  }.freeze
+  public_constant :FACTION_IDENTIFIERS_FROM_INT
 
   # A map from two-letter Faction identifiers to their integer identifiers
   # @example
@@ -19,5 +29,7 @@ module RuneterraCards
     'PZ' => 4,
     'SI' => 5,
     '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.1.0'
+  VERSION = '0.3.0'
+  public_constant :VERSION
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: runeterra_cards
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
-- zofrex
+- James "zofrex" Sanderson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-28 00:00:00.000000000 Z
+date: 2020-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base32
@@ -178,18 +178,22 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.9.25
-description: Legends of Runeterra deck encoder/decoder and general purpose card info
+description: Legends of Runeterra deck code decoder & Data Dragon card data loader.
 email:
 - zofrex@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - LICENSE.txt
+- doc/CHANGELOG.md
+- doc/README.md
 - lib/runeterra_cards.rb
 - 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
@@ -197,7 +201,10 @@ files:
 homepage: 
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/zofrex/runeterra_cards/issues
+  changelog_uri: https://www.rubydoc.info/gems/runeterra_cards/doc/CHANGELOG.md
+  source_code_uri: https://github.com/zofrex/runeterra_cards
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -216,5 +223,5 @@ requirements: []
 rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
-summary: Legends of Runeterra deck encoder/decoder and general purpose card info
+summary: Legends of Runeterra deck code decoder & Data Dragon card data loader.
 test_files: []