human_readable 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5307eeacfd4961a43325a641b37da77388aedcb419f1c2bd0ae1021eec63417b
-  data.tar.gz: 44414551a3e4333ab02beb913c69bf8afddce406b2e1701c2f7d79e1150a464d
+  metadata.gz: c0c42d3ef19502845eba7a407bd1b341c10598cf4625a748c740eec35467e572
+  data.tar.gz: 3b1f3ea6ce717b68854f5f7c30e43a27c988fa6c4f863140c36f5cab66d962d7
 SHA512:
-  metadata.gz: 1662e91b1671caf3ac01da210016eb0544d6b82a9eec0f93279eaa9460472bea09fa8ba078d5204551dbb948c81c0a9f874a62d4001c41cfe9cd8c7c2dda38a0
-  data.tar.gz: b728158418c8b4ea875dc80cccc4055107fbf48014821c325b8e76dfbe6c63f38394d57544c8f13909c376e47f45b19e812fc3ca100994ca2a0a42a2d12eaef9
+  metadata.gz: 78ab8e290c1cf235581efb86d42357a55f1c8972fd5a1d642c908291dcd6b7f8656ec4988579017c13bb20bd7487a75e30b9963fdc2ffef83d80da30b40fa25b
+  data.tar.gz: bec6d603d7670e5fd47e5f8ccea02d5a65fc6fda31dbc78df0dd3d86302516cacb265ab8758505550b39654ae62f61bfe800d14d592dcb74a4c44cf3f313e2ac

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 Release History
 ===============
+# 0.9.0
+* Emoji support!!
+* Minimum Ruby version bumped to 2.5.0 for Emoji support
+* Extend or exclude available characters using config arrays
+* Allow arrays in substitution keys
 
 # 0.8.0
 * Initial release

data/README.md

@@ -1,6 +1,8 @@
+[![Gem Version](https://badge.fury.io/rb/human_readable.svg)](https://badge.fury.io/rb/human_readable)
+
 # HumanReadable
 
-Human readable random tokens with limited ambiguous characters.
+Human readable random tokens without ambiguous characters, and optional Emoji support.
 
 Focus is readability in poor conditions or from potentially damaged printed documents rather than cryptographic uses.
 Despite this focus, SecureRandom is used to help avoid collisions.
@@ -28,27 +30,45 @@ Or install it yourself as:
 ## Usage
 
 For 10 characters of the default character set, use `HumanReadable.generate`.
-For other lengths (2..x), use `HumanReadable.generate(output_size: 50)`.
+For other lengths (2..x), use `HumanReadable.generate(output_size: 50)`, or change `output_size` in the configuration.
 
 ## Configuration
 
-* Change available characters and substitution by manipulating `substitution_hash`
-* To include non-default characters, add a self-reference to the hash
+* Add or change substitutions by configuring `substitution_hash`
+* To include non-default characters without substitution, configure `extend_chars`
+* To exclude default characters, configure `exclude_chars`
 * Inspect available characters using `HumanReadable.charset`
-* For convenience, numbers and symbols are allowed in the hash and are translated to characters during usage
+* For convenience, numbers and symbols are allowed in `substitution_hash` and are translated to characters during usage
 
-**CAUTION:** Changing `substitution_hash` keys alters the check character, invalidating previous tokens.
+**CAUTION:** Changing available characters alters the check character, invalidating previous tokens.
 
 
     HumanReadable.configure do |c|
-      # Default: substitution_hash = { I: 1, L: 1, O: 0, U: :V }
+      c.substitution_hash = { %w[I L] => 1, O: 0, U: :V } # Default
+      c.output_size = 10                                  # Default
 
-      # Modifications
+      # Add or change substitutions
       c.substitution_hash[:B] = 8
       c.substitution_hash[:U] = nil
-      c.substitution_hash['$'] = '$'
       # or equivalently
-      c.substitution_hash = { I: 1, L: 1, O: 0, U: nil, B: 8, '$' => '$'}
+      c.substitution_hash = { %w[I L] => 1, O: 0, U: nil, B: 8}
+
+      # Extend charset when no substitution is needed
+      c.extend_chars << %w[~ ! @ $]
+
+      # Exclude from charset
+      c.exclude_chars = %w[X Y Z]
+
+      # Supports Emoji!!
+      c.extend_chars << %w[⛰️ 🧻 ✂️ 🦎 🖖]
+      c.substitution_hash['🖤'] = '❤️'
+
+      # And understands skin tones
+      c.remove_skin_tones = false                         # Default
+      c.substitution_hash[%w[👍🏻 👍🏼 👍🏽 👍🏾 👍🏿]] = '👍'
+      # -or-
+      c.remove_skin_tones = true
+      c.extend_chars << '👍'
     end
 
 ## Development
@@ -59,7 +79,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/MacksMind/human_readable.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/MacksMind/human_readable>.
 
 
 ## License

data/lib/human_readable.rb

@@ -2,11 +2,11 @@
 
 # Copyright 2020 Mack Earnhardt
 
-require 'human_readable/version'
+require_relative 'human_readable/version'
 require 'ostruct'
 require 'securerandom'
 
-# Human readable random tokens with no ambiguous characters
+# Human readable random tokens without ambiguous characters, and optional Emoji support
 module HumanReadable
   # +#generate+ output_size must be >= 2 due to check character
   class MinSizeTwo < StandardError; end
@@ -15,34 +15,54 @@ module HumanReadable
     # Yields block for configuration
     #
     #   HumanReadable.configure do |c|
+    #     c.substitution_hash = { %w[I L] => 1, O: 0, U: :V } # Default
+    #     c.output_size = 10                                  # Default
+    #
+    #     # Substitution hash
     #     c.substitution_hash[:B] = 8
     #     c.substitution_hash[:U] = nil
-    #     c.substitution_hash['$'] = '$'
     #     # or equivalently
-    #     c.substitution_hash = { I: 1, L: 1, O: 0, U: nil, B: 8, '$' => '$'}
-    #   end
+    #     c.substitution_hash = { %w[I L] => 1, O: 0, U: nil, B: 8}
+    #
+    #     # Extend charset
+    #     c.extend_chars = %w[~ ! @ $]
     #
-    # DEFAULT:
-    #   substitution_hash: { I: 1, L: 1, O: 0, U: :V }
+    #     # Exclude charset
+    #     c.exclude_chars = %w[X Y Z]
+    #
+    #     # Supports Emoji!!
+    #     c.extend_chars << %w[⛰️ 🧻 ✂️ 🦎 🖖]
+    #     c.substitution_hash['🖤'] = '❤️'
+    #
+    #     # And understands skin tones
+    #     c.remove_skin_tones = false                         # Default
+    #     c.substitution_hash[%w[👍🏻 👍🏼 👍🏽 👍🏾 👍🏿]] = '👍'
+    #     # -or-
+    #     c.remove_skin_tones = true
+    #     c.extend_chars << '👍'
+    #   end
     #
     # Specified keys won't be used during generation, and values will be substituted during
     # validation, increasing the likelihood that a misread character can be restored. Extend
-    # or replace the substitutions to use a different character set. For convenience, numbers
+    # or replace the substitutions to alter the character set. For convenience, digits
     # and symbols are allowed in the hash and are translated to characters during usage.
-    # Alter as needed per examples below.
     #
-    # *CAUTION:* Changing substitution_hash keys alters the check character, invalidating previous tokens.
+    # @note Changing substitution_hash keys alters the check character, invalidating previous tokens.
+    # @return [nil]
     def configure
       yield(configuration)
+      nil
     end
 
     # Generates a random token of the requested size
     #
-    # Minimum size is 2 since the last character is a check character
-    def generate(output_size: 10)
+    # @note Minimum size is 2 since the last character is a check character
+    # @param output_size [Integer] desired number of printable characters
+    # @return [String] random token with check character
+    def generate(output_size: configuration.output_size)
       raise(MinSizeTwo) if output_size < 2
 
-      (token = generate_random(output_size - 1)) + check_character(token)
+      "#{token = generate_random(output_size - 1)}#{check_character(token)}"
     end
 
     # Clean and validate a candidate token
@@ -52,11 +72,16 @@ module HumanReadable
     # * Remove characters not in available character set
     # * Validates the check character
     #
-    # Return value: Valid token or nil
+    # @param input [String] the candidate token
+    # @return [String, nil] possibly modified token if valid, else nil
     def valid_token?(input)
       return unless input.is_a?(String)
 
-      codepoints = input.upcase.tr(trans_from, trans_to).chars.map! { |c| charset.index(c) }
+      codepoints =
+        input.upcase.each_grapheme_cluster.map do |c|
+          c.gsub!(SKIN_TONE_REGEXP, '') if configuration.remove_skin_tones
+          charset_hash[validation_hash[c] || c]
+        end
       codepoints.compact!
 
       return if codepoints.size < 2
@@ -72,18 +97,53 @@ module HumanReadable
 
     # Characters available for token generation
     #
-    # Manipulate by configuring +substitution_hash+
+    # DEFAULT: Digits 0-9 and uppercase letters A-Z except for ILOU
     #
-    # DEFAULT: All number and uppercase letters except for ILOU
+    # @note Manipulate via {#configure}
+    # @return [Array] of available characters
     def charset
-      @charset ||= (('0'..'9').to_a + ('A'..'Z').to_a - trans_from.chars + trans_to.chars - nil_substitutions).uniq
+      @charset ||=
+        begin
+          array = (
+            ('0'..'9').to_a +
+            ('A'..'Z').to_a +
+            extend_chars -
+            exclude_chars -
+            validation_hash.keys +
+            validation_hash.values
+          )
+          array.uniq!
+          array.sort!
+        end
+    end
+
+    # Reset configuration and memoizations
+    #
+    # @return [Array] list of variables reset
+    def reset
+      instance_variables.each { |sym| remove_instance_variable(sym) }
     end
 
   private
 
+    SKIN_TONE_REGEXP = /[🏻🏼🏽🏾🏿]/.freeze
+
+    # HumanReadable configuration
+    Configuration = Struct.new(
+      :substitution_hash,
+      :extend_chars,
+      :exclude_chars,
+      :output_size,
+      :remove_skin_tones
+    )
+
     def configuration
-      @configuration ||= OpenStruct.new(
-        substitution_hash: { I: 1, L: 1, O: 0, U: :V }
+      @configuration ||= Configuration.new(
+        { %w[I L] => 1, O: 0, U: :V },
+        [],
+        [],
+        10,
+        false
       )
     end
 
@@ -99,8 +159,6 @@ module HumanReadable
     # Instead we attempt to optimize the number of bytes generated with each
     # call to SecureRandom.
     def generate_random(random_size)
-      return '' unless random_size.positive?
-
       codepoints = []
 
       while codepoints.size < random_size
@@ -123,11 +181,11 @@ module HumanReadable
 
     # Compute check character using Luhn mod N algorithm
     #
-    # *CAUTION:* Changing substitution_hash keys alters the output
+    # CAUTION: Changing charset alters the output
     def check_character(input)
       array =
-        input.chars.reverse.each_with_index.map do |c, i|
-          d = charset.index(c)
+        input.each_grapheme_cluster.to_a.reverse.each_with_index.map do |c, i|
+          d = charset_hash[c]
           d *= 2 if i.even?
           d / charset_size + d % charset_size
         end
@@ -159,36 +217,39 @@ module HumanReadable
       @charset_size ||= charset.size
     end
 
-    def nil_substitutions
-      @nil_substitutions ||=
-        begin
-          array = configuration.substitution_hash.each.map { |k, v| k if v.nil? }
-          array.compact!
-          array.map!(&:to_s)
-          array.map!(&:upcase)
-        end
+    def char_cleanup(array)
+      array.compact!
+      array.flatten!
+      array.map!(&:to_s)
+      array.map! { |element| element.gsub(SKIN_TONE_REGEXP, '') } if configuration.remove_skin_tones
+      array.map!(&:upcase)
     end
 
-    def trans_from
-      @trans_from ||=
-        begin
-          array = configuration.substitution_hash.each.map { |k, v| k unless v.nil? }
-          array.compact!
-          array.map!(&:to_s)
-          array.map!(&:upcase)
-          array.join
-        end
+    def extend_chars
+      @extend_chars ||= char_cleanup(configuration.extend_chars)
+    end
+
+    def exclude_chars
+      @exclude_chars ||= char_cleanup(
+        configuration.exclude_chars + configuration.substitution_hash.each.map { |k, v| k if v.nil? }
+      )
     end
 
-    def trans_to
-      @trans_to ||=
+    # Flattened version of substitution_hash
+    def validation_hash
+      @validation_hash ||=
         begin
-          array = configuration.substitution_hash.values
-          array.compact!
-          array.map!(&:to_s)
-          array.map!(&:upcase)
-          array.join
+          array =
+            configuration.substitution_hash.map do |k, v|
+              (k.is_a?(Array) ? k.map { |k1| [k1, v] } : [k, v]) unless v.nil?
+            end
+          array = char_cleanup(array)
+          Hash[*array]
         end
     end
+
+    def charset_hash
+      @charset_hash ||= Hash[charset.each_with_index.map { |char, i| [char, i] }]
+    end
   end
 end

data/lib/human_readable/version.rb

@@ -4,6 +4,6 @@
 
 module HumanReadable
   # Gem version
-  VERSION = '0.8.0'
+  VERSION = '0.9.0'
   public_constant :VERSION
 end

metadata

@@ -1,20 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: human_readable
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Mack Earnhardt
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-08-15 00:00:00.000000000 Z
+date: 2020-08-18 00:00:00.000000000 Z
 dependencies: []
 description: |
-  Human readable random tokens with no ambiguous characters
-
-  Tranlates invalid characters to their most likely original value
-  and validates using a checksum.
+  Human readable random tokens without ambiguous characters, and optional Emoji support.
+  Translates invalid characters to their most likely original value
+  and validates using a check character.
 email:
 - mack@agilereasoning.com
 executables: []
@@ -41,15 +40,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.4.1
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.0.3
 signing_key:
 specification_version: 4
-summary: Human readable random tokens with no ambiguous characters
+summary: Human readable random tokens without ambiguous characters, and optional Emoji
+  support.
 test_files: []