faker 1.9.6 → 2.7.0

data/lib/faker/creature/horse.rb

@@ -1,15 +1,33 @@
 # frozen_string_literal: true
 
 module Faker
-  module Creature
+  class Creature
     class Horse < Base
       flexible :horse
 
       class << self
+        ##
+        # Produces a random name for a horse
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Horse.name #=> "Noir"
+        #
+        # @faker.version 1.9.2
         def name
           fetch('creature.horse.name')
         end
 
+        ##
+        # Produces a random horse breed
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Horse.breed #=> "Spanish Barb see Barb Horse"
+        #
+        # @faker.version 1.9.2
         def breed
           fetch('creature.horse.breed')
         end

data/lib/faker/default/address.rb

@@ -5,7 +5,11 @@ module Faker
     flexible :address
 
     class << self
-      def city(options = {})
+      def city(legacy_options = NOT_GIVEN, options: {})
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :options if legacy_options != NOT_GIVEN
+        end
+
         parse(options[:with_state] ? 'address.city_with_state' : 'address.city')
       end
 
@@ -13,7 +17,11 @@ module Faker
         parse('address.street_name')
       end
 
-      def street_address(include_secondary = false)
+      def street_address(legacy_include_secondary = NOT_GIVEN, include_secondary: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :include_secondary if legacy_include_secondary != NOT_GIVEN
+        end
+
         numerify(parse('address.street_address') + (include_secondary ? ' ' + secondary_address : ''))
       end
 
@@ -29,7 +37,11 @@ module Faker
         parse('address.community')
       end
 
-      def zip_code(state_abbreviation = '')
+      def zip_code(legacy_state_abbreviation = NOT_GIVEN, state_abbreviation: '')
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :state_abbreviation if legacy_state_abbreviation != NOT_GIVEN
+        end
+
         if state_abbreviation.empty?
           letterified_string = letterify(fetch('address.postcode'))
           return numerify(letterified_string, leading_zero: true)
@@ -71,11 +83,19 @@ module Faker
         fetch('address.country')
       end
 
-      def country_by_code(code: 'US')
+      def country_by_code(legacy_code = NOT_GIVEN, code: 'US')
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :code if legacy_code != NOT_GIVEN
+        end
+
         fetch('address.country_by_code.' + code)
       end
 
-      def country_name_to_code(name: 'united_states')
+      def country_name_to_code(legacy_name = NOT_GIVEN, name: 'united_states')
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :name if legacy_name != NOT_GIVEN
+        end
+
         fetch('address.country_by_name.' + name)
       end
 

data/lib/faker/default/alphanumeric.rb

@@ -2,22 +2,71 @@
 
 module Faker
   class Alphanumeric < Base
-    class << self
-      ALPHABET = ('a'..'z').to_a
-      ALPHANUMS = ALPHABET + (0..9).to_a
+    ##
+    # List of characters allowed for alphanumeric strings
+    # @private
+    ALPHANUMS = LLetters + Numbers
 
-      def alpha(char_count = 32)
-        char_count = resolve(char_count)
+    class << self
+      ##
+      # Produces a random string of alphabetic characters (no digits)
+      #
+      # @param number [Integer] The length of the string to generate
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Alphanumeric.alpha(number: 10) #=> "zlvubkrwga"
+      #
+      # @faker.version 1.9.2
+      def alpha(legacy_number = NOT_GIVEN, number: 32)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+        end
+        char_count = resolve(number)
         return '' if char_count.to_i < 1
 
-        Array.new(char_count) { sample(ALPHABET) }.join
+        Array.new(char_count) { sample(self::LLetters) }.join
       end
 
-      def alphanumeric(char_count = 32)
-        char_count = resolve(char_count)
+      ##
+      # Produces a random string of alphanumeric characters
+      #
+      # @param number [Integer] The number of characters to generate
+      # @param min_alpha [Integer] The minimum number of alphabetic to add to the string
+      # @param min_numeric [Integer] The minimum number of numbers to add to the string
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Alphanumeric.alphanumeric(number: 10) #=> "3yfq2phxtb"
+      # @example
+      #   Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3) #=> "3yfq2phxtb"
+      # @example
+      #   Faker::Alphanumeric.alphanumeric(number: 10, min_alpha: 3, min_numeric: 3) #=> "3yfq2phx8b"
+      #
+      # @faker.version 2.1.3
+      def alphanumeric(legacy_number = NOT_GIVEN, number: 32, min_alpha: 0, min_numeric: 0)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+        end
+        char_count = resolve(number)
         return '' if char_count.to_i < 1
+        raise ArgumentError, 'min_alpha must be greater than or equal to 0' if min_alpha&.negative?
+        raise ArgumentError, 'min_numeric must be greater than or equal to 0' if min_numeric&.negative?
+
+        return Array.new(char_count) { sample(ALPHANUMS) }.join if min_alpha.zero? && min_numeric.zero?
+
+        raise ArgumentError, 'min_alpha + min_numeric must be <= number' if min_alpha + min_numeric > char_count
+
+        random_count = char_count - min_alpha - min_numeric
+
+        alphas = Array.new(min_alpha) { sample(self::LLetters) }
+        numbers = Array.new(min_numeric) { sample(self::Numbers) }
+        randoms = Array.new(random_count) { sample(ALPHANUMS) }
 
-        Array.new(char_count) { sample(ALPHANUMS) }.join
+        combined = alphas + numbers + randoms
+        combined.shuffle.join
       end
     end
   end

data/lib/faker/default/app.rb

@@ -3,19 +3,73 @@
 module Faker
   class App < Base
     class << self
+      ##
+      # Produces an app name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.name #=> "Treeflex"
+      #
+      # @faker.version 1.4.3
       def name
         fetch('app.name')
       end
 
+      ##
+      # Produces a version string.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.version #=> "1.85"
+      #
+      # @faker.version 1.4.3
       def version
         parse('app.version')
       end
 
+      ##
+      # Produces the name of an app's author.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.author #=> "Daphne Swift"
+      #
+      # @faker.version 1.4.3
       def author
         parse('app.author')
       end
 
-      def semantic_version(major: 0..9, minor: 0..9, patch: 1..9)
+      # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a String representing a semantic version identifier.
+      #
+      # @param major [Integer, Range] An integer to use or a range to pick the integer from.
+      # @param minor [Integer, Range] An integer to use or a range to pick the integer from.
+      # @param patch [Integer, Range] An integer to use or a range to pick the integer from.
+      # @return [String]
+      #
+      # @example
+      #   Faker::App.semantic_version #=> "3.2.5"
+      # @example
+      #   Faker::App.semantic_version(major: 42) #=> "42.5.2"
+      # @example
+      #   Faker::App.semantic_version(minor: 100..101) #=> "42.100.4"
+      # @example
+      #   Faker::App.semantic_version(patch: 5..6) #=> "7.2.6"
+      #
+      # @faker.version 1.4.3
+      def semantic_version(legacy_major = NOT_GIVEN, legacy_minor = NOT_GIVEN, legacy_patch = NOT_GIVEN, major: 0..9, minor: 0..9, patch: 1..9)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :major if legacy_major != NOT_GIVEN
+          keywords << :minor if legacy_minor != NOT_GIVEN
+          keywords << :patch if legacy_patch != NOT_GIVEN
+        end
+
         [major, minor, patch].map { |chunk| sample(Array(chunk)) }.join('.')
       end
     end

data/lib/faker/default/appliance.rb

@@ -3,10 +3,28 @@
 module Faker
   class Appliance < Base
     class << self
+      ##
+      # Produces the name of an appliance brand.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Appliance.brand #=> "Bosch"
+      #
+      # @faker.version 1.9.0
       def brand
         fetch('appliance.brand')
       end
 
+      ##
+      # Produces the name of a type of appliance equipment.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Appliance.equipment #=> "Appliance plug"
+      #
+      # @faker.version 1.9.0
       def equipment
         fetch('appliance.equipment')
       end

data/lib/faker/default/artist.rb

@@ -3,6 +3,15 @@
 module Faker
   class Artist < Base
     class << self
+      ##
+      # Produces the name of an artist.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Artist.name #=> "Michelangelo"
+      #
+      # @faker.version 1.8.8
       def name
         fetch('artist.names')
       end

data/lib/faker/default/avatar.rb

@@ -3,9 +3,51 @@
 module Faker
   class Avatar < Base
     class << self
+      # @private
       SUPPORTED_FORMATS = %w[png jpg bmp].freeze
 
-      def image(slug = nil, size = '300x300', format = 'png', set = 'set1', bgset = nil)
+      # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produces a URL for an avatar from robohash.org
+      #
+      # @param slug [String, nil]
+      # @param size [String] image size in pixels, in the format of 'AxB'
+      # @param format [String] The image file format
+      # @param set [String] The avatar set to use
+      # @param bgset [String, nil] The background set to use
+      # @return [String] A robohash.org URL
+      #
+      # @example
+      #   Faker::Avatar.image
+      #     #=> "https://robohash.org/sitsequiquia.png?size=300x300&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug")
+      #     #=> "https://robohash.org/my-own-slug.png?size=300x300&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50")
+      #     #=> "https://robohash.org/my-own-slug.png?size=50x50&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "jpg")
+      #     #=> "https://robohash.org/my-own-slug.jpg?size=50x50&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "bmp")
+      #     #=> "https://robohash.org/my-own-slug.bmp?size=50x50&set=set1"
+      # @example
+      #   Faker::Avatar.image(slug: "my-own-slug", size: "50x50", format: "bmp", set: "set1", bgset: "bg1")
+      #     #=> "https://robohash.org/my-own-slug.bmp?size=50x50&set=set1&bgset=bg1"
+      #
+      # @faker.version 1.4.3
+      def image(legacy_slug = NOT_GIVEN, legacy_size = NOT_GIVEN, legacy_format = NOT_GIVEN, legacy_set = NOT_GIVEN, legacy_bgset = NOT_GIVEN, slug: nil, size: '300x300', format: 'png', set: 'set1', bgset: nil)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :slug if legacy_slug != NOT_GIVEN
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :format if legacy_format != NOT_GIVEN
+          keywords << :set if legacy_set != NOT_GIVEN
+          keywords << :bgset if legacy_bgset != NOT_GIVEN
+        end
+
         raise ArgumentError, 'Size should be specified in format 300x300' unless size =~ /^[0-9]+x[0-9]+$/
         raise ArgumentError, "Supported formats are #{SUPPORTED_FORMATS.join(', ')}" unless SUPPORTED_FORMATS.include?(format)
 

data/lib/faker/default/bank.rb

@@ -5,7 +5,11 @@ module Faker
     flexible :bank
 
     class << self
-      def account_number(digits = 10)
+      def account_number(legacy_digits = NOT_GIVEN, digits: 10)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
+        end
+
         output = ''
 
         output += rand.to_s[2..-1] while output.length < digits
@@ -13,10 +17,14 @@ module Faker
         output[0...digits]
       end
 
-      def iban(country_code = 'GB')
+      def iban(legacy_country_code = NOT_GIVEN, country_code: 'GB')
         # Each country has it's own format for bank accounts
         # Many of them use letters in certain parts of the account
         # Using regex patterns we can create virtually any type of bank account
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :country_code if legacy_country_code != NOT_GIVEN
+        end
+
         begin
           pattern = fetch("bank.iban_details.#{country_code.downcase}.bban_pattern")
         rescue I18n::MissingTranslationData

data/lib/faker/default/boolean.rb

@@ -3,7 +3,22 @@
 module Faker
   class Boolean < Base
     class << self
-      def boolean(true_ratio = 0.5)
+      ##
+      # Produces a boolean
+      #
+      # @param true_ratio [Float] The likelihood (as a float, out of 1.0) for the method to return `true`.
+      # @return [Boolean]
+      #
+      # @example
+      #   Faker::Boolean.boolean #=> true
+      # @example
+      #   Faker::Boolean.boolean(true_ratio: 0.2) #=> false
+      #
+      # @faker.version 1.6.2
+      def boolean(legacy_true_ratio = NOT_GIVEN, true_ratio: 0.5)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :true_ratio if legacy_true_ratio != NOT_GIVEN
+        end
         (rand < true_ratio)
       end
     end

data/lib/faker/default/cannabis.rb

@@ -37,5 +37,9 @@ module Faker
     def self.buzzword
       fetch('cannabis.buzzwords')
     end
+
+    def self.brand
+      fetch('cannabis.brands')
+    end
   end
 end

data/lib/faker/default/chile_rut.rb

@@ -6,7 +6,12 @@ module Faker
       @last_rut = nil
 
       # Fixed param added for testing a specific RUT and check digit combination.
-      def rut(min_rut = 1, fixed = false)
+      def rut(legacy_min_rut = NOT_GIVEN, legacy_fixed = NOT_GIVEN, min_rut: 1, fixed: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :min_rut if legacy_min_rut != NOT_GIVEN
+          keywords << :fixed if legacy_fixed != NOT_GIVEN
+        end
+
         @last_rut = fixed ? min_rut : rand_in_range(min_rut, 99_999_999)
       end
 
@@ -34,8 +39,13 @@ module Faker
         dv
       end
 
-      def full_rut(min_rut = 0, fixed = false)
-        "#{rut(min_rut, fixed)}-#{dv}"
+      def full_rut(legacy_min_rut = NOT_GIVEN, legacy_fixed = NOT_GIVEN, min_rut: 0, fixed: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :min_rut if legacy_min_rut != NOT_GIVEN
+          keywords << :fixed if legacy_fixed != NOT_GIVEN
+        end
+
+        "#{rut(min_rut: min_rut, fixed: fixed)}-#{dv}"
       end
 
       attr_reader :last_rut

data/lib/faker/default/chuck_norris.rb

@@ -2,7 +2,7 @@
 
 module Faker
   class ChuckNorris < Base
-    flexible :name
+    flexible :chuck_norris
 
     class << self
       # from: https://github.com/jenkinsci/chucknorris-plugin/blob/master/src/main/java/hudson/plugins/chucknorris/FactGenerator.java