deckstrings 0.0.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6148776b7c2053194b8395f146073d1cbb2e4287
-  data.tar.gz: adbbba2b83eb857c7ae1fe1cbf037b2289c53794
+  metadata.gz: a5a397bdd301581b9c7e06931ad8f123bab9c6f1
+  data.tar.gz: 12821a30968d65f31d565dd3b0542263e453d263
 SHA512:
-  metadata.gz: 4e2f2054b7934284201237c9d1bb33d2015f6c60033a9cee779d6049ce87078ab7dbcc158c1b7a3b5b03dd7109ee4de18f9e285267cc2496a3b81b5b690723ea
-  data.tar.gz: 5bf099a6dbd36e59c28d5bb22a452b7c8122b4c45b0db91f8e48a4f79c2510234981dae0832594264b1b234881144d3c8b7ca84e68eaedb7cc99a7a8458c795f
+  metadata.gz: 76acb89402c69393cc41ca7a5a5a65e2dd02c85d1bfa7962e9c78ef7edf3b894407640cd106686e627ec1a0b047e1f2432af00a7f5067b5a55e9a09f97d2c4f1
+  data.tar.gz: ecf7998ac4975afd1382631a11b81c722e2d33816d63217154aaeffa29f8f2c72be85e7a9132bb1874a0c4fd03ed35aff765e9c32265eb109137b0566e470d24

data/README.md

@@ -20,7 +20,7 @@ For additional entity metadata (e.g. hero class, card cost, card name), the DBF
 
 ## Decoding
 
-`Deckstrings::decode` provides the simplest decoding with the least validation.
+[`Deckstrings::decode`](http://www.rubydoc.info/gems/deckstrings/Deckstrings#decode-class_method) decodes a deckstring with basic validation.
 
 ```ruby
 deckstring = 'AAECAZICCPIF+Az5DK6rAuC7ApS9AsnHApnTAgtAX/4BxAbkCLS7Asu8As+8At2+AqDNAofOAgA='
@@ -31,11 +31,11 @@ puts Deckstrings::decode(deckstring)
 {:format=>2, :heroes=>[274], :cards=>{754=>1, 1656=>1, 1657=>1, 38318=>1, 40416=>1, 40596=>1, 41929=>1, 43417=>1, 64=>2, 95=>2, 254=>2, 836=>2, 1124=>2, 40372=>2, 40523=>2, 40527=>2, 40797=>2, 42656=>2, 42759=>2}}
 ```
 
-`Deckstrings::Deck.parse` provides extended validation and additional deck information including card name and cost.
+[`Deckstrings::Deck.decode`](http://www.rubydoc.info/gems/deckstrings/Deckstrings/Deck#decode-class_method) decodes a deckstring with extended validation and additional deck information including card names and costs.
 
 ```ruby
 deckstring = 'AAECAZICCPIF+Az5DK6rAuC7ApS9AsnHApnTAgtAX/4BxAbkCLS7Asu8As+8At2+AqDNAofOAgA='
-puts Deckstrings::Deck.parse(deckstring)
+puts Deckstrings::Deck.decode(deckstring)
 ```
 
 ```text
@@ -66,9 +66,73 @@ Hero: Malfurion Stormrage
 
 ## Encoding
 
-`Deckstrings::encode`
+[`Deckstrings::encode`](http://www.rubydoc.info/gems/deckstrings/Deckstrings#encode-class_method) encodes deck information in a deckstring with basic validation.
 
-`Deckstrings::Deck`
+```ruby
+puts Deckstrings::encode(
+  format: Deckstrings::Format.standard,
+  heroes: [Deckstrings::Hero.malfurion],
+  cards: {
+    254 => 2,
+    40372 => 2,
+    1124 => 2,
+    836 => 2,
+    40523 => 2,
+    64 => 2,
+    40527 => 2,
+    38318 => 1,
+    754 => 1,
+    95 => 2,
+    1657 => 1,
+    42656 => 2,
+    1656 => 1,
+    40596 => 1,
+    40797 => 2,
+    43417 => 1,
+    41929 => 1,
+    42759 => 2,
+    40416 => 1    
+  }
+)
+```
+
+```text
+AAECAZICCPIF+Az5DK6rAuC7ApS9AsnHApnTAgtAX/4BxAbkCLS7Asu8As+8At2+AqDNAofOAgA=
+```
+
+[`Deckstrings::Deck.encode`](http://www.rubydoc.info/gems/deckstrings/Deckstrings/Deck#encode-class_method) encodes deck information in a deckstring with extended validation.
+
+```ruby
+puts Deckstrings::Deck.encode(
+  format: 2,
+  heroes: [274],
+  cards: {
+    254 => 2,
+    40372 => 2,
+    1124 => 2,
+    836 => 2,
+    40523 => 2,
+    64 => 2,
+    40527 => 2,
+    38318 => 1,
+    754 => 1,
+    95 => 2,
+    1657 => 1,
+    42656 => 2,
+    1656 => 1,
+    40596 => 1,
+    40797 => 2,
+    43417 => 1,
+    41929 => 1,
+    42759 => 2,
+    40416 => 1    
+  }
+)
+```
+
+```text
+AAECAZICCPIF+Az5DK6rAuC7ApS9AsnHApnTAgtAX/4BxAbkCLS7Asu8As+8At2+AqDNAofOAgA=
+```
 
 ## License
 

data/lib/deckstrings/deckstrings.rb

@@ -2,10 +2,8 @@ require 'base64'
 require 'json'
 
 module Deckstrings
+  # An error indicating a malformed deckstring.
   class FormatError < StandardError
-    def initialize(message)
-      super(message)
-    end
   end
 
   # Enumeration of valid format types: wild and standard.
@@ -21,6 +19,7 @@ module Deckstrings
     define :standard, 2, 'Standard'
   end
 
+  # Enumeration of all nine Hearthstone classes.
   class HeroClass
     include Enum
 
@@ -92,6 +91,7 @@ module Deckstrings
       @id = id
       @name = name
       @hero_class = HeroClass.parse(hero_class)
+      raise ArgumentError, "Invalid hero class: #{hero_class}." if @hero_class.nil?
     end
 
     # @return [Hero] Jaina Proudmoore.
@@ -231,8 +231,8 @@ module Deckstrings
       Hero.new(id, hero['name'], hero['class'])
     end
 
-    # @see https://hearthstonejson.com/ HearthstoneJSON for hero metadata.
     # @return [Integer] Hearthstone DBF ID of the hero.
+    # @see https://hearthstonejson.com/ HearthstoneJSON
     attr_reader :id
 
     # @return [String] Name of the hero.
@@ -243,7 +243,7 @@ module Deckstrings
   end
 
   # A Hearthstone card with basic metadata.
-  # @see Deck.parse
+  # @see Deck.decode
   class Card
     def initialize(id, name, cost)
       @id = id
@@ -251,8 +251,8 @@ module Deckstrings
       @cost = cost
     end
 
-    # @see https://hearthstonejson.com/ HearthstoneJSON for card metadata.
     # @return [Integer] Hearthstone DBF ID of the card.
+    # @see https://hearthstonejson.com/ HearthstoneJSON
     attr_reader :id
 
     # @return [String] Name of the card.
@@ -262,50 +262,103 @@ module Deckstrings
     attr_reader :cost
   end
 
-  # A Hearthstone deck convertible to and from a deckstring.
-  # @see Deck.parse
-  # @see Deck#deckstring
+  # A Hearthstone deck with metadata that is convertible to and from a deckstring.
+  # @see Deck.decode
+  # @see Deck.encode
   class Deck
+    # Create a new deck from component parts.
+    # @param format [Integer, Deckstrings::Format] Format for this deck: wild or standard.
+    # @param heroes [Array<Integer, Deckstrings::Hero>] Heroes for this deck. Multiple heroes are supported, but typically
+    #   this array will contain one element.
+    # @param cards [Hash{Integer, Deckstrings::Card => Integer}] Cards in the deck. A Hash from card ID to its instance count in the deck.
+    # @raise [ArgumentError] If format, heroes, or any cards are unknown.
     def initialize(format:, heroes:, cards:)
-      # TODO: Translate RangeError -> FormatError.
-
       @format = Format.parse(format) if !format.is_a?(Format)
-      if !@format
-        raise FormatError.new("Unknown format: #{format}.")
-      end
+      raise ArgumentError, "Unknown format: #{format}." if !@format
 
       @heroes = heroes.map do |id|
         hero = Database.instance.heroes[id]
-        raise FormatError.new("Unknown hero: #{id}.") if hero.nil?
+        raise ArgumentError, "Unknown hero: #{id}." if hero.nil?
         Hero.new(id, hero['name'], hero['class'])
       end
 
       @cards = cards.map do |id, count|
         card = Database.instance.cards[id]
-        raise FormatError.new("Unknown card: #{id}.") if card.nil?
+        raise ArgumentError, "Unknown card: #{id}." if card.nil?
         [Card.new(id, card['name'], card['cost']), count]
       end.sort_by { |card, _| card.cost }.to_h
     end
 
-    # @see .encode
-    # @see .decode
+    # Raw deck details.
+    # @return [{ format: Integer, heroes: Array<Integer>, cards: Hash{Integer => Integer} }] See {Deckstrings.decode} for details.
+    # @see Deckstrings.decode
     def raw
       heroes = @heroes.map(&:id)
       cards = @cards.map { |card, count| [card.id, count] }.to_h
       { format: @format.value, heroes: heroes, cards: cards }
     end
 
+    # Encoded deckstring for this deck.
     # @return [String] Base64-encoded compact byte string representing the deck.
+    # @see Deckstrings.encode
     # @see .encode
     def deckstring
       return Deckstrings::encode(self.raw)
     end
 
-    # @see .decode
-    # @see #deckstring
-    def self.parse(deckstring)
+    # Decodes a Hearthstone deckstring into a {Deck} with basic hero and card metadata.
+    #
+    # This method validates the well-formedness of the deckstring, the embedded version, the format, card counts, and
+    # each hero/card ID.
+    #
+    # All IDs refer to unique Hearthstone DBF IDs which can be used in conjunction with [HearthstoneJSON metadata](https://hearthstonejson.com/).
+    # @example
+    #   deck = Deckstrings::Deck.decode('AAEBAf0GAA/yAaIC3ALgBPcE+wWKBs4H2QexCMII2Q31DfoN9g4A')
+    # @example
+    #   deck = Deckstrings::Deck.decode('AAECAZICCPIF+Az5DK6rAuC7ApS9AsnHApnTAgtAX/4BxAbkCLS7Asu8As+8At2+AqDNAofOAgA=')
+    # @param deckstring [String] Base64-encoded Hearthstone deckstring.
+    # @raise [FormatError] If the deckstring is malformed or contains invalid deck data.
+    # @return [Deck] Decoded Hearthstone deck.
+    # @see Deckstrings.decode
+    # @see Deck.encode
+    # @see https://hearthstonejson.com/ HearthstoneJSON
+    def self.decode(deckstring)
       parts = Deckstrings::decode(deckstring)
-      Deck.new(parts)
+      begin
+        Deck.new(parts)
+      rescue ArgumentError => e
+        raise FormatError, e.to_s
+      end
+    end
+
+    # Encodes a Hearthstone deck as a compact deckstring.
+    #
+    # This method validates card counts, format, and each hero/card ID.
+    #
+    # All IDs refer to unique Hearthstone DBF IDs which can be seen in [HearthstoneJSON metadata](https://hearthstonejson.com/).
+    # @example
+    #   deckstring = Deckstrings::Deck.encode(format: 2, heroes: [637], cards: { 1004 => 2, 315 => 2 })
+    # @example
+    #   deckstring = Deckstrings::Deck.encode(
+    #     format: Deckstrings::Format.standard,
+    #     heroes: [Deckstrings::Hero.mage],
+    #     cards: { 1004 => 2, 315 => 2 }
+    #   )
+    # @param format [Integer, Deckstrings::Format] Format for this deck: wild or standard.
+    # @param heroes [Array<Integer, Deckstrings::Hero>] Heroes for this deck. Multiple heroes are supported, but typically
+    #   this array will contain one element.
+    # @param cards [Hash{Integer, Deckstrings::Card => Integer}] Cards in the deck. A Hash from card ID to its instance count in the deck.
+    # @raise [FormatError] If any card counts are less than 1, or if any IDs do not refer to valid Hearthstone entities.
+    # @return [String] Base64-encoded compact byte string representing the deck.
+    # @see .encode
+    # @see Deck.decode
+    # @see https://hearthstonejson.com/ HearthstoneJSON
+    def self.encode(format:, heroes:, cards:)
+      begin
+        Deck.new(format: format, heroes: heroes, cards: cards).deckstring
+      rescue ArgumentError => e
+        raise FormatError, e.to_s
+      end
     end
 
     # @return [Boolean] `true` if the deck is Wild format, `false` otherwise.
@@ -320,6 +373,9 @@ module Deckstrings
       format.standard?
     end
 
+    # Pretty-printed deck listing.
+    # @example
+    #   puts Deckstrings::Deck.decode('AAECAZICCPIF+Az5DK6rAuC7ApS9AsnHApnTAgtAX/4BxAbkCLS7Asu8As+8At2+AqDNAofOAgA=')
     # @example
     #   Format: Standard
     #   Class: Druid
@@ -346,41 +402,57 @@ module Deckstrings
     #   1× Kun the Forgotten King
     # @return [String] A pretty-printed listing of deck details.
     def to_s
+      listing = "Format: #{format}"
+
       hero = @heroes.first
-      "Format: #{format}\nClass: #{hero.hero_class}\nHero: #{hero.name}\n\n" + cards.map do |card, count|
-        "#{count}× #{card.name}"
-      end.join("\n")
+      if hero
+        listing += "\nClass: #{hero.hero_class}\nHero: #{hero.name}"
+      end
+
+      if !cards.empty?
+        listing += "\n\n" + cards.map { |card, count| "#{count}× #{card.name}" }.join("\n")
+      end
+
+      listing
     end
 
     # @return [Format] Format for this deck.
     attr_reader :format
 
-    # @return [Array<Hero>] Heroes associated with this deck. Typically, this array will contain one element.
+    # The heroes associated with this deck.
+    # @return [Array<Hero>] Typically, this array will contain one element.
     attr_reader :heroes
 
-    # @return [Hash{Card => Integer}] The cards contained in the deck. A map between {Card} and the instance count in the deck.
+    # The cards contained in this deck.
+    # @return [Hash{Card => Integer}] A Hash from {Card} to its instance count in the deck.
     attr_reader :cards
   end
 
   using VarIntExtensions
 
   # Encodes a Hearthstone deck as a compact deckstring.
+  #
+  # This method validates card counts, but does not validate the format or individual hero/card IDs. For stricter validation,
+  # see {Deck.encode}.
+  #
+  # All IDs refer to unique Hearthstone DBF IDs which can be seen in [HearthstoneJSON metadata](https://hearthstonejson.com/).
   # @example
-  #   Deckstrings.encode(format: 2, heroes: [7], cards: { 44 => 1, 45 => 2 })
+  #   deckstring = Deckstrings::encode(format: 2, heroes: [637], cards: { 1004 => 2, 315 => 2 })
   # @example
-  #   Deckstrings.encode(
+  #   deckstring = Deckstrings::encode(
   #     format: Deckstrings::Format.standard,
-  #     heroes: [Deckstrings::Hero.warrior],
-  #     cards: { 1 => 2, 2 => 2 }
+  #     heroes: [Deckstrings::Hero.mage],
+  #     cards: { 1004 => 2, 315 => 2 }
   #   )
   # @param format [Integer, Deckstrings::Format] Format for this deck: wild or standard.
   # @param heroes [Array<Integer, Deckstrings::Hero>] Heroes for this deck. Multiple heroes are supported, but typically
   #   this array will contain one element.
-  # @param cards [Hash{Integer, Deckstrings::Card => Integer}] Cards in the deck.
-  # @raise [ArgumentError] If any card counts are less than 1.
+  # @param cards [Hash{Integer, Deckstrings::Card => Integer}] Cards in the deck. A Hash from card ID to its instance count in the deck.
+  # @raise [FormatError] If any card counts are less than 1.
   # @return [String] Base64-encoded compact byte string representing the deck.
-  # @see Deck#deckstring
+  # @see Deck.encode
   # @see .decode
+  # @see https://hearthstonejson.com/ HearthstoneJSON
   def self.encode(format:, heroes:, cards:)
     stream = StringIO.new('')
 
@@ -403,7 +475,7 @@ module Deckstrings
 
     invalid = by_count.keys.select { |count| count < 1 }
     unless invalid.empty?
-      raise ArgumentError.new("Invalid card count: #{invalid.join(', ')}.")
+      raise FormatError, "Invalid card count: #{invalid.join(', ')}."
     end
 
     1.upto(3) do |count|
@@ -415,10 +487,15 @@ module Deckstrings
       end
     end
 
-    Base64::encode64(stream.string).strip
+    Base64::strict_encode64(stream.string).strip
   end
 
-  # Decodes a Hearthstone deckstring into format, hero, and card details.
+  # Decodes a Hearthstone deckstring into format, hero, and card counts.
+  #
+  # This method validates the well-formedness of the deckstring and the embedded version, but does not validate
+  # the format, individual hero/card IDs, or card counts. For stricter validation and additional deck info, see {Deck.decode}.
+  #
+  # All IDs refer to unique Hearthstone DBF IDs which can be used in conjunction with [HearthstoneJSON metadata](https://hearthstonejson.com/).
   # @example
   #   deck = Deckstrings::decode('AAEBAf0GAA/yAaIC3ALgBPcE+wWKBs4H2QexCMII2Q31DfoN9g4A')
   # @example
@@ -426,24 +503,31 @@ module Deckstrings
   # @param deckstring [String] Base64-encoded Hearthstone deckstring.
   # @raise [FormatError] If the deckstring is malformed or contains invalid deck data.
   # @return [{ format: Integer, heroes: Array<Integer>, cards: Hash{Integer => Integer} }] Parsed Hearthstone deck details.
-  # @see Deck#parse
+  #   `heroes` is an array of hero IDs, but this will usually be just one element. `cards` is a
+  #   Hash from card ID to its instance count in the deck.
+  # @see Deck.decode
   # @see .encode
+  # @see https://hearthstonejson.com/ HearthstoneJSON
   def self.decode(deckstring)
-    begin
-      if deckstring.nil? || deckstring.empty?
-        raise ArgumentError.new('Invalid deckstring.')
-      end
+    if deckstring.nil? || deckstring.empty?
+      raise FormatError, 'Invalid deckstring.'
+    end
 
-      stream = StringIO.new(Base64::decode64(deckstring))
+    stream = begin
+      StringIO.new(Base64::strict_decode64(deckstring))
+    rescue ArgumentError
+      raise FormatError, 'Invalid base64-encoded string.'
+    end
 
+    begin
       reserved = stream.read_varint
       if reserved != 0
-        raise FormatError.new("Unexpected reserved byte: #{reserved}.")
+        raise FormatError, "Unexpected reserved byte: #{reserved}."
       end
 
       version = stream.read_varint
       if version != 1
-        raise FormatError.new("Unexpected version: #{version}.")
+        raise FormatError, "Unexpected version: #{version}."
       end
 
       format = stream.read_varint
@@ -464,14 +548,14 @@ module Deckstrings
           cards[card] = i < 3 ? i : stream.read_varint
         end
       end
-
-      return {
-        format: format,
-        heroes: heroes,
-        cards: cards
-      }
     rescue EOFError
       raise FormatError, 'Unexpected end of data.'
     end
+
+    return {
+      format: format,
+      heroes: heroes,
+      cards: cards
+    }
   end
 end

data/lib/deckstrings/enum.rb

@@ -18,9 +18,7 @@ module Deckstrings
       end
 
       def parse(value)
-        enum = @@values[value]
-        raise RangeError.new("Unknown value: #{value}.") if !enum
-        enum
+        @@values[value]
       end
     end
 

data/lib/deckstrings/varint.rb

@@ -7,7 +7,7 @@ module Deckstrings
         shift = 0
         loop do
           octet = self.getbyte
-          raise EOFError.new('Unexpected end of data.') if octet.nil?
+          raise EOFError, 'Unexpected end of data.' if octet.nil?
 
           num |= (octet & 0x7f) << shift
           return num if octet & 0x80 == 0

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: deckstrings
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Chris Schmich
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-15 00:00:00.000000000 Z
-dependencies: []
+date: 2017-09-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: Ruby library for encoding and decoding Hearthstone deckstrings.
 email: schmch@gmail.com
 executables: []