faker 2.2.0 → 3.2.2

data/lib/faker/default/app.rb

@@ -3,34 +3,64 @@
 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
 
-      # rubocop:disable Metrics/ParameterLists
-      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
-        if legacy_major != NOT_GIVEN
-          warn_with_uplevel 'Passing `major` with the 1st argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(major: ...)` instead.', uplevel: 1
-          major = legacy_major
-        end
-        if legacy_minor != NOT_GIVEN
-          warn_with_uplevel 'Passing `minor` with the 2nd argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(minor: ...)` instead.', uplevel: 1
-          minor = legacy_minor
-        end
-        if legacy_patch != NOT_GIVEN
-          warn_with_uplevel 'Passing `patch` with the 3rd argument of `App.semantic_version` is deprecated. Use keyword argument like `App.semantic_version(patch: ...)` instead.', uplevel: 1
-          patch = legacy_patch
-        end
-
+      ##
+      # 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(major: 0..9, minor: 0..9, patch: 1..9)
         [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,32 +3,40 @@
 module Faker
   class Avatar < Base
     class << self
+      # @private
       SUPPORTED_FORMATS = %w[png jpg bmp].freeze
 
-      # rubocop:disable Metrics/ParameterLists
-      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
-        if legacy_slug != NOT_GIVEN
-          warn_with_uplevel 'Passing `slug` with the 1st argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(slug: ...)` instead.', uplevel: 1
-          slug = legacy_slug
-        end
-        if legacy_size != NOT_GIVEN
-          warn_with_uplevel 'Passing `size` with the 2nd argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(size: ...)` instead.', uplevel: 1
-          size = legacy_size
-        end
-        if legacy_format != NOT_GIVEN
-          warn_with_uplevel 'Passing `format` with the 3rd argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(format: ...)` instead.', uplevel: 1
-          format = legacy_format
-        end
-        if legacy_set != NOT_GIVEN
-          warn_with_uplevel 'Passing `set` with the 4th argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(set: ...)` instead.', uplevel: 1
-          set = legacy_set
-        end
-        if legacy_bgset != NOT_GIVEN
-          warn_with_uplevel 'Passing `bgset` with the 5th argument of `Avatar.image` is deprecated. Use keyword argument like `Avatar.image(bgset: ...)` instead.', uplevel: 1
-          bgset = legacy_bgset
-        end
-
+      ##
+      # 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(slug: nil, size: '300x300', format: 'png', set: 'set1', bgset: nil)
         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,27 +5,42 @@ module Faker
     flexible :bank
 
     class << self
-      def account_number(legacy_digits = NOT_GIVEN, digits: 10)
-        if legacy_digits != NOT_GIVEN
-          warn_with_uplevel 'Passing `digits` with the 1st argument of `Bank.account_number` is deprecated. Use keyword argument like `Bank.account_number(digits: ...)` instead.', uplevel: 1
-          digits = legacy_digits
-        end
-
+      ##
+      # Produces a bank account number.
+      #
+      # @param digits [Integer] Number of digits that the generated account number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.account_number #=> 6738582379
+      #   Faker::Bank.account_number(digits: 13) #=> 673858237902
+      #
+      # @faker.version 1.9.1
+      def account_number(digits: 10)
         output = ''
 
-        output += rand.to_s[2..-1] while output.length < digits
+        output += rand.to_s[2..] while output.length < digits
 
         output[0...digits]
       end
 
-      def iban(legacy_country_code = NOT_GIVEN, country_code: 'GB')
-        # Each country has it's own format for bank accounts
+      ##
+      # Produces a bank iban number.
+      #
+      # @param country_code [String, nil] Specifies what country prefix is used to generate the iban code. Providing `nil` will use a random country.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.iban #=> "GB76DZJM33188515981979"
+      #   Faker::Bank.iban(country_code: "be") #=> "BE6375388567752043"
+      #   Faker::Bank.iban(country_code: nil) #=> "DE45186738071857270067"
+      #
+      # @faker.version 1.7.0
+      def iban(country_code: 'GB')
+        # Each country has its 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
-        if legacy_country_code != NOT_GIVEN
-          warn_with_uplevel 'Passing `country_code` with the 1st argument of `Bank.iban` is deprecated. Use keyword argument like `Bank.iban(country_code: ...)` instead.', uplevel: 1
-          country_code = legacy_country_code
-        end
+        country_code ||= iban_country_code
 
         begin
           pattern = fetch("bank.iban_details.#{country_code.downcase}.bban_pattern")
@@ -40,66 +55,140 @@ module Faker
         country_code.upcase + iban_checksum(country_code, account) + account
       end
 
+      ##
+      # Produces the ISO 3166 code of a country that uses the IBAN system.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.iban_country_code #=> "CH"
+      #
+      # @faker.version next
+      def iban_country_code
+        sample(translate('faker.bank.iban_details').keys).to_s.upcase
+      end
+
+      ##
+      # Produces a bank name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.name #=> "ABN AMRO CORPORATE FINANCE LIMITED"
+      #
+      # @faker.version 1.7.0
       def name
         fetch('bank.name')
       end
 
+      ##
+      # Produces a routing number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.routing_number #=> "729343831"
+      #
+      # @faker.version 1.9.1
       def routing_number
         valid_routing_number
       end
 
+      ##
+      # Produces a valid routing number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.routing_number #=> "729343831"
+      #
+      # @faker.version 1.9.1
       def routing_number_with_format
         compile_fraction(valid_routing_number)
       end
 
+      ##
+      # Produces a swift / bic number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.swift_bic #=> "AAFMGB21"
+      #
+      # @faker.version 1.7.0
       def swift_bic
         fetch('bank.swift_bic')
       end
 
+      ##
+      # Produces an Australian BSB (Bank-State-Branch) number
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Bank.bsb_number
+      #     #=> "036616"
+      #
+      # @faker.version 2.13.0
+      def bsb_number
+        compile_bsb_number
+      end
+
       private
 
       def checksum(num_string)
-        num_array = num_string.split('').map(&:to_i)
-        digit = (7 * (num_array[0] + num_array[3] + num_array[6]) + 3 * (num_array[1] + num_array[4] + num_array[7]) + 9 * (num_array[2] + num_array[5])) % 10
-        digit == num_array[8]
+        num_array = num_string.chars.map(&:to_i)
+        (
+          7 * (num_array[0] + num_array[3] + num_array[6]) +
+            3 * (num_array[1] + num_array[4] + num_array[7]) +
+            9 * (num_array[2] + num_array[5])
+        ) % 10
       end
 
       def compile_routing_number
         digit_one_two = %w[00 01 02 03 04 05 06 07 08 09 10 11 12]
         ((21..32).to_a + (61..72).to_a + [80]).each { |x| digit_one_two << x.to_s }
-        routing_num = digit_one_two.sample + rand_numstring + rand_numstring + rand_numstring + rand_numstring + rand_numstring + rand_numstring + rand_numstring
-        routing_num
+        digit_one_two.sample + rand_numstring + rand_numstring + rand_numstring + rand_numstring + rand_numstring + rand_numstring + rand_numstring
+      end
+
+      def compile_bsb_number
+        digit_one_two = %w[01 03 06 08 11 12 73 76 78 30]
+        state = (2..7).to_a.map(&:to_s).sample
+        digit_one_two.sample + state + rand_numstring + rand_numstring + rand_numstring
       end
 
       # Calculates the mandatory checksum in 3rd and 4th characters in IBAN format
-      # source: https://en.wikipedia.org/wiki/International_Bank_Account_Number#Validating_the_IBAN
+      # source: https://en.wikipedia.org/wiki/International_Bank_Account_Number#Generating_IBAN_check_digits
       def iban_checksum(country_code, account)
         # Converts letters to numbers according the iban rules, A=10..Z=35
         account_to_number = "#{account}#{country_code}00".upcase.chars.map do |d|
           d =~ /[A-Z]/ ? (d.ord - 55).to_s : d
         end.join.to_i
 
-        # This is answer to (iban_to_num + checksum) % 97 == 1
-        checksum = (1 - account_to_number) % 97
+        # This is the correct answer to (iban_to_num + checksum) % 97 == 1
+        checksum = 98 - (account_to_number % 97)
 
         # Use leftpad to make the size always to 2
         checksum.to_s.rjust(2, '0')
       end
 
       def valid_routing_number
-        for _ in 0..50
-          micr = compile_routing_number
+        routing_number = compile_routing_number
+        checksum = checksum(routing_number)
+        return routing_number if valid_checksum?(routing_number, checksum)
 
-          break if checksum(micr)
-        end
-        micr
+        routing_number[0..7] + checksum.to_s
+      end
+
+      def valid_checksum?(routing_number, checksum)
+        routing_number[8].to_i == checksum
       end
 
       def compile_fraction(routing_num)
         prefix = (1..50).to_a.map(&:to_s).sample
-        numerator = routing_num.split('')[5..8].join.to_i.to_s
-        denominator = routing_num.split('')[0..4].join.to_i.to_s
-        prefix + '-' + numerator + '/' + denominator
+        numerator = routing_num.chars[5..8].join.to_i.to_s
+        denominator = routing_num.chars[0..4].join.to_i.to_s
+        "#{prefix}-#{numerator}/#{denominator}"
       end
 
       def rand_numstring

data/lib/faker/default/barcode.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Faker
+  class Barcode < Base
+    class << self
+      ##
+      # Returns a EAN 8 or 13 digit format barcode number with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.ean      => "85657526"
+      #     Faker::Barcode.ean(8)   => "30152700"
+      #     Faker::Barcode.ean(13)  => "2115190480285"
+      #
+      # @faker.version 2.14.0
+      def ean(length = 8)
+        generate_barcode("barcode.ean_#{Integer(length)}")
+      end
+
+      ##
+      # Returns a EAN 8 or 13 digit format barcode number with composite string attached with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.ean_with_composite_sumbology      => "41007624|JHOC6649"
+      #     Faker::Barcode.ean_with_composite_sumbology(8)   => "38357961|XUYJ3266"
+      #     Faker::Barcode.ean_with_composite_sumbology(13)  => "9530722443911|CKHWQHID"
+      #
+      # @faker.version 2.14.0
+      def ean_with_composite_symbology(length = 8)
+        "#{ean(length)}|#{bothify(parse('barcode.composite_symbol'))}"
+      end
+
+      ##
+      # Returns a UPC_A format barcode number with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.upc_a      => "766807541831"
+      #
+      # @faker.version 2.14.0
+      def upc_a
+        generate_barcode('barcode.upc_a')
+      end
+
+      ##
+      # Returns a UPC_E format barcode number with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.upc_e      => "03746820"
+      #
+      # @faker.version 2.14.0
+      def upc_e
+        generate_barcode('barcode.upc_e')
+      end
+
+      ##
+      # Returns a UPC_A format barcode number with composite string attached with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.upc_a_with_composite_symbology      => "790670155765|JOVG6208"
+      #
+      # @faker.version 2.14.0
+      def upc_a_with_composite_symbology
+        "#{upc_a}|#{bothify(parse('barcode.composite_symbol'))}"
+      end
+
+      ##
+      # Returns a UPC_E format barcode number with composite string attached with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.upc_e_with_composite_symbology      => "05149247|BKZX9722"
+      #
+      # @faker.version 2.14.0
+      def upc_e_with_composite_symbology
+        "#{upc_e}|#{bothify(parse('barcode.composite_symbol'))}"
+      end
+
+      ##
+      # Returns a ISBN format barcode number with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.isbn      => "9798363807732"
+      #
+      # @faker.version 2.14.0
+      def isbn
+        generate_barcode('barcode.isbn')
+      end
+
+      ##
+      # Returns a ISMN format barcode number with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.ismn      => "9790527672897"
+      #
+      # @faker.version 2.14.0
+      def ismn
+        generate_barcode('barcode.ismn')
+      end
+
+      ##
+      # Returns a ISSN format barcode number with check digit
+      #  @return [String]
+      #
+      #  @example
+      #     Faker::Barcode.issn      => "9775541703338"
+      #
+      # @faker.version 2.14.0
+      def issn
+        generate_barcode('barcode.issn')
+      end
+
+      private
+
+      def generate_barcode(key)
+        barcode = parse(key)
+        check_digit = generate_check_digit(*sum_even_odd(barcode))
+        "#{barcode}#{check_digit}"
+      end
+
+      ##
+      # Returns the sum of even and odd numbers from value passed
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Barcode.send(:sum_even_odd, 12345)   => [9, 5]
+      #   Faker::Barcode.send(:sum_even_odd, 87465)   => [17, 13]
+      #
+      # @faker.version 2.14.0
+      def sum_even_odd(fake_num)
+        number = fake_num.to_i
+        sum_even, sum_odd = 0, 0, index = 1
+
+        while number != 0
+          index.even? ? sum_even += number % 10 : sum_odd += number % 10
+
+          number /= 10
+          index += 1
+        end
+
+        [sum_odd, sum_even]
+      end
+
+      ##
+      # Generates the check digits from sum passed
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Barcode.send(:generate_check_digit, 12, 4)   => 0
+      #   Faker::Barcode.send(:generate_check_digit, 23, 5)   => 6
+      #
+      # @faker.version 2.14.0
+      def generate_check_digit(odd_sum, even_sum)
+        (10 - (odd_sum * 3 + even_sum) % 10) % 10
+      end
+    end
+  end
+end

data/lib/faker/default/beer.rb

@@ -5,36 +5,108 @@ module Faker
     flexible :beer
 
     class << self
+      ##
+      # Produces a random beer name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.name #=> "Pliny The Elder"
+      #
+      # @faker.version 1.6.2
       def name
         fetch('beer.name')
       end
 
+      ##
+      # Produces a random beer style.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.style #=> "Wood-aged Beer"
+      #
+      # @faker.version 1.6.2
       def style
         fetch('beer.style')
       end
 
+      ##
+      # Produces a random beer hops.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.hop #=> "Sterling"
+      #
+      # @faker.version 1.6.2
       def hop
         fetch('beer.hop')
       end
 
+      ##
+      # Produces a random beer yeast.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.yeast #=> "5335 - Lactobacillus"
+      #
+      # @faker.version 1.6.2
       def yeast
         fetch('beer.yeast')
       end
 
+      ##
+      # Produces a random beer malt.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.malts #=> "Munich"
+      #
+      # @faker.version 1.6.2
       def malts
         fetch('beer.malt')
       end
 
+      ##
+      # Produces a random beer IBU.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.ibu #=> "87 IBU"
+      #
+      # @faker.version 1.6.2
       def ibu
-        rand(10..100).to_s + ' IBU'
+        "#{rand(10..100)} IBU"
       end
 
+      ##
+      # Produces a random beer alcohol percentage.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.alcohol #=> "5.4%"
+      #
+      # @faker.version 1.6.2
       def alcohol
-        rand(2.0..10.0).round(1).to_s + '%'
+        "#{rand(2.0..10.0).round(1)}%"
       end
 
+      ##
+      # Produces a random beer blg level.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Beer.blg #=> "5.1Blg"
+      #
+      # @faker.version 1.6.2
       def blg
-        rand(5.0..20.0).round(1).to_s + '°Blg'
+        "#{rand(5.0..20.0).round(1)}°Blg"
       end
     end
   end