unique_names_generator 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c3735cb47c574108e11dde60274f4d2013c0b281fd2bdf08cecc595e9acd2ac
-  data.tar.gz: 9ccbf1f0f972547de8baabe8675b1a1540ace3a4a24caf3dd88728d86650ba52
+  metadata.gz: f9773f651a33cab35886353896b6138a9e1df7d1bbecf1c0573be4da2567eda2
+  data.tar.gz: 3dac60147e276911a7c17c505afe95e305800e6aeb897797d925a1844fe2d57d
 SHA512:
-  metadata.gz: c049f7832bc38164a17215c3ddaf830b534ec642b25494045f89c39ccb08d7c639a39af7fd061e988173bc7c5190eb8a634f2ebaed562b286d80411cbe77cdb9
-  data.tar.gz: f9a0be92fb3dbbe8a48bc588b202217d97edcd299f21699a26d7712d9b5129cb8dd0a535ffb7c4f0976bc0377f983f4e047fb9a597800131157262efc623de92
+  metadata.gz: 61b362f06916f9f08ab89e91421a4ee0c482433a4d6c9843645d6b02feab966d6197383993425fbf8b1740d211ea53ef149e9d632df0669172755a57be977a32
+  data.tar.gz: 0534cb36f75cc5e04fe72c9cdae7e05199880d0e06f1b3e0d7f6f797644f882980356232a79a2c06bb0a54da29ffbdc67f07e22ee6b2e96b9d51548e0aae78e5

data/.gitignore

@@ -0,0 +1,3 @@
+*.gem
+.DS_Store
+.yardoc

data/.rubocop.yml

@@ -27,5 +27,12 @@ Style/SymbolArray:
   Exclude:
     - 'spec/**/*'
 
+Layout/SpaceInsideBlockBraces:
+  Exclude:
+    - 'spec/**/*'
+
 Style/NumericPredicate:
-  Enabled: false
+  Enabled: false
+
+Metrics/ClassLength:
+  Max: 150

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    unique_names_generator (0.1.0)
+    unique_names_generator (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -12,7 +12,7 @@ by adding `unique_names_generator` to your list of gemfile dependencies:
 Add this line to your application's Gemfile:
 
 ```
-gem 'unique_names_generator', "~> 0.1.0"
+gem 'unique_names_generator', '~> 0.2.0'
 ```
 
 And then execute:
@@ -29,16 +29,19 @@ $ gem install unique_names_generator
 
 ## Usage
 
-In a nutshell, you can begin generating randon names with UniqueNamesGenerator by simply specifying an array of one or more dictionaries via `UniqueNamesGenerator.generate`. Available dictionary types are `[:adjectives, :animals, :colors, :languages, :names, :numbers, :star_wars]`.
+In a nutshell, you can begin generating random names with UniqueNamesGenerator by simply creating a Generator instance and specifying an array of one or more dictionaries. Available dictionary types are `[:adjectives, :animals, :colors, :languages, :names, :numbers, :star_wars]`.
 
 ```ruby
-UniqueNamesGenerator.generate([:adjectives, :animals])
+generator = UniqueNamesGenerator::Generator.new([:adjectives, :animals])
+generator.generate
 # => Generates ex: "dramatic_limpet"
 
-UniqueNamesGenerator.generate([:adjectives, :colors, :animals])
+generator = UniqueNamesGenerator::Generator.new([:adjectives, :colors, :animals])
+generator.generate
 # => Generates ex: "tremendous_brown_cat"
 
-UniqueNamesGenerator.generate([:adjectives, :names, :numbers])
+generator = UniqueNamesGenerator::Generator.new([:adjectives, :names, :numbers])
+generator.generate
 # => Generates ex: "doubtful_wanda_979"
 ```
 
@@ -46,7 +49,9 @@ To use custom dictionaries, simply include your array of strings as part of the
 
 ```ruby
 drinks = ['Sprite', 'Coca-Cola', 'Juice', 'Tea']
-UniqueNamesGenerator.generate([:colors, drinks])
+
+generator = UniqueNamesGenerator::Generator.new([:colors, drinks])
+generator.generate
 # => Generates ex: "cyan_sprite"
 ```
 
@@ -55,17 +60,20 @@ UniqueNamesGenerator.generate([:colors, drinks])
 UniqueNamesGenerator can be used with either the default provided config (`separator: '_', style: :lowercase, creativity: 0`) or by specifying any of your own configuration options for seeding, seperator, style and creativity.
 
 #### More details on possible options
-
-- **Separator options**: Any ASCII character string such as underscore, dash or blank space. `nil` for no space.
+- **Dictionaries**: [Array<Symbol, Array<String>>] List of dictionaries to use for name generation. Can be symbols referring to built-in dictionaries or custom arrays of strings.
+- **Separator**: [String] Character(s) used to join words in the generated name. Default: '_'. `nil` can be used for no space.
   - ex: '_', '-', ' ' or `nil` for no space.
-- **Style options**: Atom, one of `:lowercase`, `:uppercase`, `:capital`.
-- **Creativity options**: An integer or float between 1 and 10.
+- **Style**: [Symbol] Capitalization style for generated names.
+  - Options: `:lowercase`, `:uppercase`, `:capital`. Default: `:lowercase`
+- **Creativity**: [Integer] Level of creativity in name generation, affecting word selection. Must be between 0 and 10. A Float value can also be used. Default: 0
 
 ```ruby
-UniqueNamesGenerator.generate([:colors, :animals], style: :capital, separator: ' ')
+generator = UniqueNamesGenerator::Generator.new([:colors, :animals], style: :capital, separator: ' ')
+generator.generate
 # => Generates ex: "Lavender Marlin"
 
-UniqueNamesGenerator.generate([:colors, :adjectives, :animals], creativity: 8, style: :capital, separator: ' ')
+generator = UniqueNamesGenerator::Generator.new([:colors, :adjectives, :animals], creativity: 8, style: :capital, separator: ' ')
+generator.generate
 # => Generates ex: "Yellow Local Hippopotamus"
 ```
 
@@ -73,20 +81,22 @@ UniqueNamesGenerator.generate([:colors, :adjectives, :animals], creativity: 8, s
 Using the creativity option changes how `UniqueNamesGenerator` selects terms from the dictionaries in use, essentially acting as a multiplier. For dictionaries with a similar term length, while using a seed, the selection may at times appear to be alphabetical or closely related (ex: "Amber Anakin Skywalker"). Utilizing the `creative` option with a value between 1 and 10 will use a sequential multiplier for subsequent dictionaries providing a seemingly more "random" or "creative" result whilst still allowing for seeded generation.
 
 ```ruby
-UniqueNamesGenerator.generate([:colors, :adjectives, :animals], creativity: 8, seed: 'f6da7a28-5ae6-4d6b-b3b8-a197b99ed4eb')
+generator = UniqueNamesGenerator::Generator.new([:colors, :adjectives, :animals], creativity: 8)
+generator.generate(seed: 'f6da7a28-5ae6-4d6b-b3b8-a197b99ed4eb')
 
 # => Seed "f6da7a28-5ae6-4d6b-b3b8-a197b99ed4eb" with creativity of 8 always generates: "plum_flying_cobra"
 ```
 
 ### Seeded Generation
 
-A seed can be used to deterministically generate a name. As long as the provided seed and creativity values are the same between runs, then the generated name will also always be the same. Simply provide a string or integer as the value of the seed key, ie; `seed: 'hello'`. 
+A seed can be used to deterministically generate a name. As long as the provided seed and creativity values are the same between runs, then the generated name will also always be the same. Simply provide a string or integer as an argument to the generate method, ie; `seed: 'hello'`. 
 
-_(**Usecase example:** generate a username for an authenticated user based on UUID. Ex: `13a5d03e-61d0-4b5b-ae3b-57953c268c5f` will always generate the name "beige_boba_fett_145" when used together with the colors/star_wars/numbers dictionaries)._
+_(**Usecase example:** generate a username for an authenticated user based on UUID. Ex: `13a5d03e-61d0-4b5b-ae3b-57953c268c5f` will always generate the name "coral_greedo_320" when used together with the colors/star_wars/numbers dictionaries)._
 
 ```ruby
-UniqueNamesGenerator.generate([:colors, :star_wars, :numbers], seed: '13a5d03e-61d0-4b5b-ae3b-57953c268c5f')
-# => Seed "13a5d03e-61d0-4b5b-ae3b-57953c268c5f" always generates: "beige_boba_fett_145"
+generator = UniqueNamesGenerator::Generator.new([:colors, :star_wars, :numbers])
+generator.generate(seed: '13a5d03e-61d0-4b5b-ae3b-57953c268c5f')
+# => Seed "13a5d03e-61d0-4b5b-ae3b-57953c268c5f" always generates: "coral_greedo_320"
 ```
 
 ## License

data/lib/unique_names_generator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UniqueNamesGenerator
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/unique_names_generator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # An implementation of a unique_names_generator in Ruby
-# with support for PRNG/seeds
+# with support for PRNG/deterministic seeds
 
 require_relative './unique_names_generator/seed'
 
@@ -15,178 +15,170 @@ require_relative './unique_names_generator/dictionaries/star_wars'
 
 # UniqueNamesGenerator implementation
 module UniqueNamesGenerator
-  module_function
-
-  def generate(dictionaries, separator: '_', style: :lowercase, seed: nil, creativity: 0)
-    @separator = separator
-    @style = style
-    @seed = seed
-    @creativity = creativity
+  # UniqueNamesGenerator::Generator
+  #
+  # This class generates unique names based on specified dictionaries and configuration options.
+  # It allows for customizable name generation with various styles, separators, and creativity levels.
+  class Generator
+    def initialize(dictionaries, separator: '_', style: :lowercase, creativity: 0)
+      @dictionaries = dictionaries
+      @separator = separator
+      @style = style
+      @creativity = creativity
+
+      # Will raise error if any specified dictionary is invalid
+      dictionaries.map { |dictionary| word_list(dictionary) }
+      raise ArgumentError, 'Outside creativity range. Must be between 0 and 10.' if outside_creativity_bounds?
+    end
 
-    if creativity.negative? || creativity > 10
-      raise ArgumentError, 'Outside creativity range. Must be between 0 and 10.'
+    def generate(seed: nil)
+      @seed = seed
+      generate_name(@dictionaries)
     end
 
-    generate_name(dictionaries)
-  end
+    private
 
-  def match_word_list(dictionary)
-    module_name = camelize_dictionary(dictionary)
-    begin
-      dictionary = Dictionaries.const_get(module_name)
-      dictionary.list_all
-    rescue NameError
-      raise_invalid_dictionary(dictionary)
+    def outside_creativity_bounds?
+      @creativity.negative? || @creativity > 10
     end
-  end
 
-  def word_list(dictionary)
-    case dictionary
-    when Array
-      dictionary if dictionary.all? { |item| item.is_a?(String) }
-    when Symbol
-      match_word_list(dictionary)
-    else
-      raise ArgumentError, 'Dictionary contains invalid dictionary type'
+    def match_word_list(dictionary)
+      module_name = camelize_dictionary(dictionary)
+      begin
+        dictionary = Dictionaries.const_get(module_name)
+        dictionary.list_all
+      rescue NameError
+        raise_invalid_dictionary(dictionary)
+      end
     end
-  end
 
-  def random_seeded_float
-    seed_value = Seed.generate_seed(@seed)
+    def word_list(dictionary)
+      case dictionary
+      when Array
+        dictionary if dictionary.all? { |item| item.is_a?(String) }
+      when Symbol
+        match_word_list(dictionary)
+      else
+        raise ArgumentError, 'Dictionary contains invalid dictionary type'
+      end
+    end
 
-    prng = @seed.nil? ? Random.new : Random.new(seed_value)
-    prng.rand
-  end
+    def random_seeded_float
+      seed_value = Seed.generate_seed(@seed)
 
-  def map_dictionaries(dictionaries)
-    dictionaries.map { |dictionary| word_list(dictionary) }
-  end
+      prng = @seed.nil? ? Random.new : Random.new(seed_value)
+      prng.rand
+    end
 
-  def split_with_separator(word)
-    if @separator.nil?
-      word.split(/(?=[A-Z])/)
-    else
-      word.split(@separator)
+    def map_dictionaries(dictionaries)
+      dictionaries.map { |dictionary| word_list(dictionary) }
     end
-  end
 
-  def format_parts(parts)
-    parts.map do |part|
-      if part.match?(/[^a-zA-Z]/) && @style == :capital
-        # Preserve original capitalization for parts with non-letter characters
-        part
+    def split_with_separator(word)
+      if @separator.nil?
+        word.split(/(?=[A-Z])/)
       else
-        format_word(part, @style)
+        word.split(@separator)
       end
-    end.join(@separator)
-  end
+    end
 
-  def format_multi_word(word, original_word)
-    if original_word.include?(' ') || original_word.include?('-')
-      parts = split_with_separator(word)
-      format_parts(parts)
-    else
-      format_word(word, @style)
+    def format_parts(parts)
+      parts.map do |part|
+        if part.match?(/[^a-zA-Z]/) && @style == :capital
+          # Preserve original capitalization for parts with non-letter characters
+          part
+        else
+          format_word(part, @style)
+        end
+      end.join(@separator)
     end
-  end
 
-  def generate_name(dictionaries)
-    if @creativity.nil? || @creativity.zero?
-      generate_name_original(dictionaries)
-    else
-      generate_name_creatively(dictionaries)
+    def format_multi_word(word, original_word)
+      if original_word.include?(' ') || original_word.include?('-')
+        parts = split_with_separator(word)
+        format_parts(parts)
+      else
+        format_word(word, @style)
+      end
     end
-  end
 
-  def generate_name_original(dictionaries)
-    map_dictionaries(dictionaries).reduce(nil) do |acc, x|
-      rnd = (random_seeded_float * x.length).floor
-      original_word = x[rnd]
+    def generate_name(dictionaries)
+      if @creativity.nil? || @creativity.zero?
+        generate_name_original(dictionaries)
+      else
+        generate_name_creatively(dictionaries)
+      end
+    end
 
-      output_word(acc, original_word)
+    def generate_name_original(dictionaries)
+      map_dictionaries(dictionaries).reduce(nil) do |acc, x|
+        rnd = (random_seeded_float * x.length).floor
+        original_word = x[rnd]
+
+        output_word(acc, original_word)
+      end
     end
-  end
 
-  def generate_name_creatively(dictionaries)
-    word_lists = map_dictionaries(dictionaries)
+    def generate_name_creatively(dictionaries)
+      word_lists = map_dictionaries(dictionaries)
 
-    word_lists.each_with_index.reduce(nil) do |acc, (word_list, index)|
-      creativity = calculate_creativity(index)
-      rnd = (random_seeded_float * word_list.length * creativity).floor
-      original_word = word_list[rnd % word_list.length] # Ensure we don't go out of bounds
+      word_lists.each_with_index.reduce(nil) do |acc, (word_list, index)|
+        creativity = calculate_creativity(index)
+        rnd = (random_seeded_float * word_list.length * creativity).floor
+        original_word = word_list[rnd % word_list.length] # Ensure we don't go out of bounds
 
-      output_word(acc, original_word)
+        output_word(acc, original_word)
+      end
     end
-  end
 
-  def output_word(acc, original_word)
-    word = format_with_separator(original_word)
-    word = format_multi_word(word, original_word)
+    def output_word(acc, original_word)
+      word = format_with_separator(original_word)
+      word = format_multi_word(word, original_word)
 
-    if acc
-      "#{acc}#{@separator}#{word}"
-    else
-      word
+      if acc
+        "#{acc}#{@separator}#{word}"
+      else
+        word
+      end
     end
-  end
 
-  def calculate_creativity(index)
-    if index.zero?
-      @creativity # Base creativity for the first dictionary
-    else
-      @creativity * (2 + index * 0.5) # Increase creativity for subsequent dictionaries
+    def calculate_creativity(index)
+      if index.zero?
+        @creativity # Base creativity for the first dictionary
+      else
+        @creativity * (2 + index * 0.5) # Increase creativity for subsequent dictionaries
+      end
     end
-  end
 
-  def camelize_dictionary(dictionary)
-    dictionary.to_s.split('_').map(&:capitalize).join
-  end
+    def camelize_dictionary(dictionary)
+      dictionary.to_s.split('_').map(&:capitalize).join
+    end
 
-  def raise_invalid_dictionary(dictionary)
-    raise ArgumentError, "Invalid dictionary: #{dictionary}"
-  end
+    def raise_invalid_dictionary(dictionary)
+      raise ArgumentError, "Invalid dictionary #{dictionary}"
+    end
 
-  def format_with_separator(word)
-    if @separator.nil?
-      # If separator is empty, just remove spaces without changing case
-      word.gsub(/\s+/, '')
-    else
-      # If there's a separator, use it to replace spaces
-      word.gsub(/\s+/, @separator)
+    def format_with_separator(word)
+      if @separator.nil?
+        # If separator is empty, just remove spaces without changing case
+        word.gsub(/\s+/, '')
+      else
+        # If there's a separator, use it to replace spaces
+        word.gsub(/\s+/, @separator)
+      end
     end
-  end
 
-  def format_word(word, style)
-    case style
-    when :lowercase
-      word.downcase
-    when :uppercase
-      word.upcase
-    when :capital
-      word.capitalize
-    else
-      word
+    def format_word(word, style)
+      case style
+      when :lowercase
+        word.downcase
+      when :uppercase
+        word.upcase
+      when :capital
+        word.capitalize
+      else
+        word
+      end
     end
   end
-
-  private_class_method(
-    *%i[
-      generate_name
-      match_word_list
-      word_list
-      random_seeded_float
-      map_dictionaries
-      camelize_dictionary
-      raise_invalid_dictionary
-      format_with_separator
-      format_multi_word
-      format_parts
-      format_word
-      split_with_separator
-      generate_name_original
-      generate_name_creatively
-      calculate_creativity
-      output_word
-    ]
-  )
 end

data/unique_names_generator.gemspec

@@ -15,7 +15,8 @@ Gem::Specification.new do |s|
   s.email         = 'jongirard03@gmail.com'
   s.homepage      = 'https://github.com/jongirard/unique_names_generator_ruby'
   s.metadata      = { 'homepage_uri' => 'https://github.com/jongirard/unique_names_generator_ruby',
-                      'source_code_uri' => 'https://github.com/jongirard/unique_names_generator_ruby' }
+                      'source_code_uri' => 'https://github.com/jongirard/unique_names_generator_ruby',
+                      'documentation_uri' => 'https://www.rubydoc.info/gems/unique_names_generator/' }
   s.require_paths = ['lib']
   s.license       = 'MIT'
   s.files         = Dir.chdir(File.expand_path(__dir__)) do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unique_names_generator
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Jon Girard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-05 00:00:00.000000000 Z
+date: 2024-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -34,6 +34,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ruby.yml"
+- ".gitignore"
 - ".pryrc"
 - ".rspec"
 - ".rubocop.yml"
@@ -59,6 +60,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/jongirard/unique_names_generator_ruby
   source_code_uri: https://github.com/jongirard/unique_names_generator_ruby
+  documentation_uri: https://www.rubydoc.info/gems/unique_names_generator/
 post_install_message:
 rdoc_options: []
 require_paths: