faker 2.10.2 → 2.15.0

data/lib/faker/default/code.rb

@@ -4,32 +4,76 @@ module Faker
   class Code < Base
     flexible :code
     class << self
-      # Generates a 10 digit NPI (National Provider Identifier
-      # issued to health care providers in the United States)
+      ##
+      # Produces a random NPI (National Provider Identifer) code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.npi #=> "9804062802"
+      #
+      # @faker.version 1.9.4
       def npi
         rand(10**10).to_s.rjust(10, '0')
       end
 
-      # By default generates 10 sign isbn code in format 123456789-X
-      # You can pass 13 to generate new 13 sign code
+      ##
+      # Produces a random ISBN (International Standard Book Number) code.
+      #
+      # @param base [Integer] the length of the code to generate (either 10 or 13)
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.isbn(base: 13) #=> "896579606969-8"
+      # @example
+      #   Faker::Code.isbn #=> "170366802-2"
+      #
+      # @faker.version 2.2.0
       def isbn(legacy_base = NOT_GIVEN, base: 10)
         warn_for_deprecated_arguments do |keywords|
           keywords << :base if legacy_base != NOT_GIVEN
         end
 
-        base == 13 ? generate_base13_isbn : generate_base10_isbn
+        case base
+        when 10 then generate_base10_isbn
+        when 13 then generate_base13_isbn
+        else raise ArgumentError, 'base must be 10 or 13'
+        end
       end
 
-      # By default generates 13 sign ean code in format 1234567890123
-      # You can pass 8 to generate ean8 code
+      ##
+      # Produces a random EAN (European Article Number) code.
+      #
+      # @param base [Integer] the length of the code to generate (either 8 or 13)
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.ean(base: 8) #=> "36941070"
+      # @example
+      #   Faker::Code.ean #=> "9941880131907"
+      #
+      # @faker.version 2.2.0
       def ean(legacy_base = NOT_GIVEN, base: 13)
         warn_for_deprecated_arguments do |keywords|
           keywords << :base if legacy_base != NOT_GIVEN
         end
 
-        base == 8 ? generate_base8_ean : generate_base13_ean
+        case base
+        when 8 then generate_base8_ean
+        when 13 then generate_base13_ean
+        else raise ArgumentError, 'base must be 3 or 13'
+        end
       end
 
+      ##
+      # Produces a random RUT (Rol Unico Nacional) code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.rut #=> "91611842-2"
+      #
+      # @faker.version 1.9.4
       def rut
         value = Number.number(digits: 8).to_s
         vd = rut_verificator_digit(value)
@@ -38,6 +82,23 @@ module Faker
 
       # By default generates a Singaporean NRIC ID for someone
       # who is born between the age of 18 and 65.
+      #
+      # Produces a random NRIC (National Registry Identity Card) code.
+      #
+      # @param min_age [Integer] the min age of the person in years
+      # @param max_age [Integer] the max age of the person in years
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.nric(min_age: 25, max_age: 50) #=> "S9347283G"
+      # @example
+      #   Faker::Code.nric(max_age: 55) #=> "S7876903C"
+      # @example
+      #   Faker::Code.nric(min_age: 25) #=> "S6281697Z"
+      # @example
+      #   Faker::Code.nric #=> "S6372958B"
+      #
+      # @faker.version 2.2.0
       def nric(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65)
         warn_for_deprecated_arguments do |keywords|
           keywords << :min_age if legacy_min_age != NOT_GIVEN
@@ -52,19 +113,41 @@ module Faker
         "#{prefix}#{values}#{check_alpha}"
       end
 
-      # Generate GSM modem, device or mobile phone 15 digit IMEI number.
+      ##
+      # Produces a random IMEI (International Mobile Equipment Number) code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.imei #=> "492033129092256"
+      #
+      # @faker.version 1.9.4
       def imei
         generate_imei
       end
 
-      # Retrieves a real Amazon ASIN code list taken from
-      # https://archive.org/details/asin_listing
+      ##
+      # Retrieves a real Amazon ASIN code from https://archive.org/details/asin_listing
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.asin #=> "B000MZW1GE"
+      #
+      # @faker.version 1.9.4
       def asin
         fetch('code.asin')
       end
 
-      # Generates Social Insurance Number issued in Canada
-      # https://en.wikipedia.org/wiki/Social_Insurance_Number
+      ##
+      # Produces a random SIN (Social Insurance Number for Canada) code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Code.sin #=> "996586962"
+      #
+      # @faker.version 1.9.4
       def sin
         # 1   - province or temporary resident
         # 2-8 - random numbers
@@ -77,7 +160,7 @@ module Faker
         partial = Array.new(7) { Faker::Config.random.rand(0..9) }.join
 
         # Generate 9th digit
-        check_digit = generate_sin_check_digit(registry + partial + '0').to_s
+        check_digit = generate_sin_check_digit("#{registry}#{partial}0").to_s
 
         registry + partial + check_digit
       end
@@ -90,8 +173,6 @@ module Faker
       def generate_imei
         str = Array.new(15, 0)
         sum = 0
-        t = 0
-        len_offset = 0
         len = 15
 
         # Fill in the first two values of the string based with the specified prefix.
@@ -137,7 +218,7 @@ module Faker
       def generate_base13_isbn
         values = regexify(/\d{12}/)
         remainder = sum(values) { |value, index| index.even? ? value.to_i : value.to_i * 3 } % 10
-        values << "-#{((10 - remainder) % 10)}"
+        values << "-#{(10 - remainder) % 10}"
       end
 
       def sum(values)

data/lib/faker/default/commerce.rb

@@ -3,10 +3,30 @@
 module Faker
   class Commerce < Base
     class << self
+      ##
+      # Produces a random color.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.color #=> "lavender"
+      #
+      # @faker.version 1.2.0
       def color
         fetch('color.name')
       end
 
+      ##
+      # Produces a random promotion code.
+      #
+      # @param digits [Integer] Updates the number of numerical digits used to generate the promotion code.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.promotion_code #=> "AmazingDeal829102"
+      #   Faker::Commerce.promotion_code(digits: 2) #=> "AmazingPrice57"
+      #
+      # @faker.version 1.7.0
       def promotion_code(legacy_digits = NOT_GIVEN, digits: 6)
         warn_for_deprecated_arguments do |keywords|
           keywords << :digits if legacy_digits != NOT_GIVEN
@@ -19,6 +39,19 @@ module Faker
         ].join
       end
 
+      ##
+      # Produces a random department.
+      #
+      # @param max [Integer] Updates the maximum number of names used to generate the department name.
+      # @param fixed_amount [Boolean] Fixes the amount of departments to use instead of using a range.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.department #=> "Grocery, Health & Beauty"
+      #   Faker::Commerce.department(max: 5) #=> "Grocery, Books, Health & Beauty"
+      #   Faker::Commerce.department(max: 2, fixed_amount: true) #=> "Books & Tools"
+      #
+      # @faker.version 1.2.0
       def department(legacy_max = NOT_GIVEN, legacy_fixed_amount = NOT_GIVEN, max: 3, fixed_amount: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :max if legacy_max != NOT_GIVEN
@@ -30,19 +63,55 @@ module Faker
 
         categories = categories(num)
 
-        return merge_categories(categories) if num > 1
-
-        categories[0]
+        if categories.is_a?(Array)
+          if categories.length > 1
+            merge_categories(categories)
+          else
+            categories[0]
+          end
+        else
+          categories
+        end
       end
 
+      ##
+      # Produces a random product name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.product_name #=> "Practical Granite Shirt"
+      #
+      # @faker.version 1.2.0
       def product_name
         "#{fetch('commerce.product_name.adjective')} #{fetch('commerce.product_name.material')} #{fetch('commerce.product_name.product')}"
       end
 
+      ##
+      # Produces a random material.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Commerce.material #=> "Plastic"
+      #
+      # @faker.version 1.5.0
       def material
         fetch('commerce.product_name.material')
       end
 
+      ##
+      # Produces a random product price.
+      #
+      # @param range [Range] A range to generate the random number within.
+      # @param as_string [Boolean] Changes the return value to [String].
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Commerce.price #=> 44.6
+      #   Faker::Commerce.price(range: 0..10.0, as_string: true) #=> "2.18"
+      #
+      # @faker.version 1.2.0
       def price(legacy_range = NOT_GIVEN, legacy_as_string = NOT_GIVEN, range: 0..100.0, as_string: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :range if legacy_range != NOT_GIVEN
@@ -52,7 +121,7 @@ module Faker
         price = (rand(range) * 100).floor / 100.0
         if as_string
           price_parts = price.to_s.split('.')
-          price = price_parts[0] + '.' + price_parts[-1].ljust(2, '0')
+          price = "#{price_parts[0]}.#{price_parts[-1].ljust(2, '0')}"
         end
         price
       end
@@ -60,13 +129,7 @@ module Faker
       private
 
       def categories(num)
-        categories = []
-        while categories.length < num
-          category = fetch('commerce.department')
-          categories << category unless categories.include?(category)
-        end
-
-        categories
+        sample(fetch_all('commerce.department'), num)
       end
 
       def merge_categories(categories)

data/lib/faker/default/company.rb

@@ -162,12 +162,17 @@ module Faker
       # @faker.version 1.8.5
       #
       # Get a random Spanish organization number. See more here https://es.wikipedia.org/wiki/N%C3%BAmero_de_identificaci%C3%B3n_fiscal
-      def spanish_organisation_number
+      def spanish_organisation_number(organization_type: nil)
         # Valid leading character: A, B, C, D, E, F, G, H, J, N, P, Q, R, S, U, V, W
-        # 7 digit numbers
+        # format: 1 digit letter (organization type) + 7 digit numbers + 1 digit control (letter or number based on
+        # organization type)
         letters = %w[A B C D E F G H J N P Q R S U V W]
-        base = [sample(letters), format('%07d', rand(10**7))].join
-        base
+
+        organization_type = sample(letters) unless letters.include?(organization_type)
+        code = format('%07d', rand(10**7))
+        control = spanish_cif_control_digit(organization_type, code)
+
+        [organization_type, code, control].join
       end
 
       ##
@@ -399,6 +404,11 @@ module Faker
         formatted ? format('%s.%s.%s/%s-%s', *number.scan(/(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})/).flatten) : number
       end
 
+      # Get a random Russian tax number.
+      def russian_tax_number(region: nil, type: :legal)
+        inn_number(region, type)
+      end
+
       ##
       # Produces a company sic code.
       #
@@ -454,13 +464,11 @@ module Faker
           end
         end
 
-        control_digit = if (sum % 10).zero?
-                          0
-                        else
-                          (sum / 10 + 1) * 10 - sum
-                        end
-
-        control_digit
+        if (sum % 10).zero?
+          0
+        else
+          (sum / 10 + 1) * 10 - sum
+        end
       end
 
       def abn_checksum(abn)
@@ -491,6 +499,65 @@ module Faker
         end
         sum
       end
+
+      # rubocop:disable Style/AsciiComments
+      #
+      # For more on Russian tax number algorithm here:
+      # https://ru.wikipedia.org/wiki/Идентификационный_номер_налогоплательщика#Вычисление_контрольных_цифр
+      #
+      # Range of regions:
+      # https://ru.wikipedia.org/wiki/Коды_субъектов_Российской_Федерации
+      #
+      # rubocop:enable Style/AsciiComments
+      def inn_number(region, type)
+        n10 = [2, 4, 10, 3, 5, 9, 4, 6, 8]
+        n11 = [7, 2, 4, 10, 3, 5, 9, 4, 6, 8]
+        n12 = [3, 7, 2, 4, 10, 3, 5, 9, 4, 6, 8]
+
+        region = format('%.2d', rand(0o1..92)) if region.nil?
+        checksum = if type == :legal
+                     number = region.to_s + rand(1_000_000..9_999_999).to_s
+                     inn_checksum(n10, number)
+                   else
+                     number = region.to_s + rand(10_000_000..99_999_999).to_s
+                     inn_checksum(n11, number) + inn_checksum(n12, number + inn_checksum(n11, number))
+                   end
+
+        number + checksum
+      end
+
+      def inn_checksum(factor, number)
+        (
+          factor.map.with_index.reduce(0) do |v, i|
+            v + i[0] * number[i[1]].to_i
+          end % 11 % 10
+        ).to_s
+      end
+
+      def spanish_cif_control_digit(organization_type, code)
+        letters = %w[J A B C D E F G H]
+
+        control = code.split('').each_with_index.inject(0) do |sum, (value, index)|
+          if (index + 1).even?
+            sum + value.to_i
+          else
+            sum + spanish_b_algorithm(value.to_i)
+          end
+        end
+
+        control = control.to_s[-1].to_i
+        control = control.zero? ? control : 10 - control
+
+        %w[A B C D E F G H J U V].include?(organization_type) ? control : letters[control]
+      end
+
+      def spanish_b_algorithm(value)
+        result = value.to_i * 2
+
+        return result if result < 10
+
+        result.to_s[0].to_i + result.to_s[1].to_i
+      end
     end
   end
 end

data/lib/faker/default/compass.rb

@@ -3,62 +3,197 @@
 module Faker
   class Compass < Base
     class << self
+      ##
+      # Produces a random cardinal.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.cardinal #=> "north"
+      #
+      # @faker.version 1.8.0
       def cardinal
         fetch('compass.cardinal.word')
       end
 
+      ##
+      # Produces a random ordinal.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.ordinal #=> "northwest"
+      #
+      # @faker.version 1.8.0
       def ordinal
         fetch('compass.ordinal.word')
       end
 
+      ##
+      # Produces a random half wind.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.half_wind #=> "north-northwest"
+      #
+      # @faker.version 1.8.0
       def half_wind
         fetch('compass.half-wind.word')
       end
 
+      ##
+      # Produces a random quarter wind.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.quarter_wind #=> "north by west"
+      #
+      # @faker.version 1.8.0
       def quarter_wind
         fetch('compass.quarter-wind.word')
       end
 
+      ##
+      # Produces a random direction.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.direction #=> "southeast"
+      #
+      # @faker.version 1.8.0
       def direction
         parse('compass.direction')
       end
 
+      ##
+      # Produces a random abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.abbreviation #=> "NEbN"
+      #
+      # @faker.version 1.8.0
       def abbreviation
         parse('compass.abbreviation')
       end
 
+      ##
+      # Produces a random azimuth.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.azimuth #=> "168.75"
+      #
+      # @faker.version 1.8.0
       def azimuth
         parse('compass.azimuth')
       end
 
+      ##
+      # Produces a random cardinal abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.cardinal_abbreviation #=> "N"
+      #
+      # @faker.version 1.8.0
       def cardinal_abbreviation
         fetch('compass.cardinal.abbreviation')
       end
 
+      ##
+      # Produces a random ordinal abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.ordinal_abbreviation #=> "SW"
+      #
+      # @faker.version 1.8.0
       def ordinal_abbreviation
         fetch('compass.ordinal.abbreviation')
       end
 
+      ##
+      # Produces a random half wind abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.half_wind_abbreviation #=> "NNE"
+      #
+      # @faker.version 1.8.0
       def half_wind_abbreviation
         fetch('compass.half-wind.abbreviation')
       end
 
+      ##
+      # Produces a random quarter wind abbreviation.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.quarter_wind_abbreviation #=> "SWbS"
+      #
+      # @faker.version 1.8.0
       def quarter_wind_abbreviation
         fetch('compass.quarter-wind.abbreviation')
       end
 
+      ##
+      # Produces a random cardinal azimuth.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.cardinal_azimuth #=> "90"
+      #
+      # @faker.version 1.8.0
       def cardinal_azimuth
         fetch('compass.cardinal.azimuth')
       end
 
+      ##
+      # Produces a random ordinal azimuth.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.ordinal_azimuth #=> "135"
+      #
+      # @faker.version 1.8.0
       def ordinal_azimuth
         fetch('compass.ordinal.azimuth')
       end
 
+      ##
+      # Produces a random half wind azimuth.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.half_wind_azimuth #=> "292.5"
+      #
+      # @faker.version 1.8.0
       def half_wind_azimuth
         fetch('compass.half-wind.azimuth')
       end
 
+      ##
+      # Produces a random quarter wind azimuth
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Compass.quarter_wind_azimuth #=> "56.25"
+      #
+      # @faker.version 1.8.0
       def quarter_wind_azimuth
         fetch('compass.quarter-wind.azimuth')
       end