faker 2.9.0 → 2.12.0

data/lib/faker/default/blood.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Faker
+  class Blood < Base
+    flexible :blood
+
+    class << self
+      ##
+      # Produces a random blood type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Blood.type #=> "AB"
+      #
+      # @faker.version next
+      def type
+        fetch('blood.type')
+      end
+
+      ##
+      # Produces a random blood RH-Factor.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Blood.rh_factor #=> "-"
+      #
+      # @faker.version next
+      def rh_factor
+        fetch('blood.rh_factor')
+      end
+
+      ##
+      # Produces a random blood group name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Blood.group #=> "AB-"
+      #
+      # @faker.version next
+      def group
+        parse('blood.group')
+      end
+    end
+  end
+end

data/lib/faker/default/business.rb

@@ -26,7 +26,7 @@ module Faker
       # @return [Date]
       #
       # @example
-      #   Faker::Business.credit_card_number #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
+      #   Faker::Business.credit_card_expiry_date #=> <Date: 2015-11-11 ((2457338j,0s,0n),+0s,2299161j)>
       #
       # @faker.version 1.2.0
       def credit_card_expiry_date

data/lib/faker/default/cannabis.rb

@@ -2,42 +2,122 @@
 
 module Faker
   class Cannabis < Base
+    # Produces a random strain.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.strain #=> "Super Glue"
+    #
+    # @faker.version 1.9.1
     def self.strain
       fetch('cannabis.strains')
     end
 
+    # Produces a random abbreviation.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.cannabinoid_abbreviation #=> "CBGa"
+    #
+    # @faker.version 1.9.1
     def self.cannabinoid_abbreviation
       fetch('cannabis.cannabinoid_abbreviations')
     end
 
+    # Produces a random cannabinoid type.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.cannabinoid #=> "Cannabinolic Acid"
+    #
+    # @faker.version 1.9.1
     def self.cannabinoid
       fetch('cannabis.cannabinoids')
     end
 
+    # Produces a random terpene type.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.terpene #=> "Terpinene"
+    #
+    # @faker.version 1.9.1
     def self.terpene
       fetch('cannabis.terpenes')
     end
 
+    # Produces a random kind of medical use.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.medical_use #=> "anti-cancer"
+    #
+    # @faker.version 1.9.1
     def self.medical_use
       fetch('cannabis.medical_uses')
     end
 
+    # Produces a random health benefit.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.health_benefit #=> "prevents infection"
+    #
+    # @faker.version 1.9.1
     def self.health_benefit
       fetch('cannabis.health_benefits')
     end
 
+    # Produces a random category.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.category #=> "crystalline"
+    #
+    # @faker.version 1.9.1
     def self.category
       fetch('cannabis.categories')
     end
 
+    # Produces a random type.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.type #=> "indica"
+    #
+    # @faker.version 1.9.1
     def self.type
       fetch('cannabis.types')
     end
 
+    # Produces a random buzzword.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.buzzword #=> "high"
+    #
+    # @faker.version 1.9.1
     def self.buzzword
       fetch('cannabis.buzzwords')
     end
 
+    # Produces a random brand.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Cannabis.brand #=> "Cannavore Confections"
+    #
+    # @faker.version 1.9.1
     def self.brand
       fetch('cannabis.brands')
     end

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
@@ -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

@@ -5,57 +5,163 @@ module Faker
     flexible :company
 
     class << self
+      ##
+      # Produces a company name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.name #=> "Roberts Inc"
+      #
+      # @faker.version 1.6.0
       def name
         parse('company.name')
       end
 
+      ##
+      # Produces a company suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.suffix #=> "LLC"
+      #
+      # @faker.version 1.6.0
       def suffix
         fetch('company.suffix')
       end
 
+      ##
+      # Produces a company industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.industry #=> "Food & Beverages"
+      #
+      # @faker.version 1.6.0
       def industry
         fetch('company.industry')
       end
 
-      # Generate a buzzword-laden catch phrase.
+      ##
+      # Produces a company catch phrase.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.catch_phrase #=> "Grass-roots grid-enabled portal"
+      #
+      # @faker.version 1.6.0
       def catch_phrase
         translate('faker.company.buzzwords').collect { |list| sample(list) }.join(' ')
       end
 
+      ##
+      # Produces a company buzzword.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.buzzword #=> "flexibility"
+      #
+      # @faker.version 1.8.7
       def buzzword
         sample(translate('faker.company.buzzwords').flatten)
       end
 
+      ##
+      # Produces some company BS.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.bs #=> "empower customized functionalities"
+      #
+      # @faker.version 1.6.0
       # When a straight answer won't do, BS to the rescue!
       def bs
         translate('faker.company.bs').collect { |list| sample(list) }.join(' ')
       end
 
+      ##
+      # Produces a company EIN (Employer Identification Number).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.ein #=> "07-4009024"
+      #
+      # @faker.version 1.6.0
       def ein
         format('%09d', rand(10**9)).gsub(/(\d{2})(\d{7})/, '\\1-\\2')
       end
 
+      ##
+      # Produces a company duns number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.duns_number #=> "70-655-5105"
+      #
+      # @faker.version 1.6.0
       def duns_number
         format('%09d', rand(10**9)).gsub(/(\d{2})(\d{3})(\d{4})/, '\\1-\\2-\\3')
       end
 
+      ##
+      # Produces a company logo.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.logo #=> "https://pigment.github.io/fake-logos/logos/medium/color/12.png"
+      #
+      # @faker.version 1.8.7
       # Get a random company logo url in PNG format.
       def logo
         rand_num = rand(1..13)
         "https://pigment.github.io/fake-logos/logos/medium/color/#{rand_num}.png"
       end
 
+      ##
+      # Produces a company type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.type #=> "Partnership"
+      #
+      # @faker.version 1.8.7
       def type
         fetch('company.type')
       end
 
+      ##
+      # Produces a company profession.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.profession #=> "factory worker"
+      #
+      # @faker.version 1.6.0
       def profession
         fetch('company.profession')
       end
 
-      # rubocop:disable Style/AsciiComments
-      # Get a random Spanish organization number. See more here https://es.wikipedia.org/wiki/Número_de_identificación_fiscal
-      # rubocop:enable Style/AsciiComments
+      ##
+      # Produces a company spanish organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.spanish_organisation_number #=> "D6819358"
+      #
+      # @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
         # Valid leading character: A, B, C, D, E, F, G, H, J, N, P, Q, R, S, U, V, W
         # 7 digit numbers
@@ -64,6 +170,15 @@ module Faker
         base
       end
 
+      ##
+      # Produces a company swedish organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.swedish_organisation_number #=> "3866029808"
+      #
+      # @faker.version 1.7.0
       # Get a random Swedish organization number. See more here https://sv.wikipedia.org/wiki/Organisationsnummer
       def swedish_organisation_number
         # Valid leading digit: 1, 2, 3, 5, 6, 7, 8, 9
@@ -73,6 +188,15 @@ module Faker
         base + luhn_algorithm(base).to_s
       end
 
+      ##
+      # Produces a company czech organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.czech_organisation_number #=> "90642741"
+      #
+      # @faker.version 1.9.1
       def czech_organisation_number
         sum = 0
         base = []
@@ -84,18 +208,45 @@ module Faker
         base.join
       end
 
+      ##
+      # Produces a company french siren number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.french_siren_number #=> "163417827"
+      #
+      # @faker.version 1.8.5
       # Get a random French SIREN number. See more here https://fr.wikipedia.org/wiki/Syst%C3%A8me_d%27identification_du_r%C3%A9pertoire_des_entreprises
       def french_siren_number
         base = (1..8).map { rand(10) }.join
         base + luhn_algorithm(base).to_s
       end
 
+      ##
+      # Produces a company french siret number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.french_siret_number #=> "76430067900496"
+      #
+      # @faker.version 1.8.5
       def french_siret_number
         location = rand(100).to_s.rjust(4, '0')
         org_no = french_siren_number + location
         org_no + luhn_algorithm(org_no).to_s
       end
 
+      ##
+      # Produces a company norwegian organisation number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.norwegian_organisation_number #=> "842457173"
+      #
+      # @faker.version 1.8.0
       # Get a random Norwegian organization number. Info: https://www.brreg.no/om-oss/samfunnsoppdraget-vart/registera-vare/einingsregisteret/organisasjonsnummeret/
       def norwegian_organisation_number
         # Valid leading digit: 8, 9
@@ -107,6 +258,15 @@ module Faker
         base + mod11_check.to_s
       end
 
+      ##
+      # Produces a company australian business number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.australian_business_number #=> "93579396170"
+      #
+      # @faker.version 1.6.4
       def australian_business_number
         base = format('%09d', rand(10**9))
         abn = "00#{base}"
@@ -114,6 +274,15 @@ module Faker
         (99 - (abn_checksum(abn) % 89)).to_s + base
       end
 
+      ##
+      # Produces a company polish taxpayer identification_number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.polish_taxpayer_identification_number #=> "2767549463"
+      #
+      # @faker.version 1.9.1
       # Get a random Polish taxpayer identification number More info https://pl.wikipedia.org/wiki/NIP
       def polish_taxpayer_identification_number
         result = []
@@ -125,6 +294,15 @@ module Faker
         result.join('')
       end
 
+      ##
+      # Produces a company polish register of national economy.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.polish_register_of_national_economy #=> "788435970"
+      #
+      # @faker.version 1.9.1
       # Get a random Polish register of national economy number. More info https://pl.wikipedia.org/wiki/REGON
       def polish_register_of_national_economy(legacy_length = NOT_GIVEN, length: 9)
         warn_for_deprecated_arguments do |keywords|
@@ -141,22 +319,67 @@ module Faker
         random_digits.join('')
       end
 
+      ##
+      # Produces a company south african pty ltd registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_pty_ltd_registration_number #=> "7043/2400717902/07"
+      #
+      # @faker.version 1.9.2
       def south_african_pty_ltd_registration_number
         regexify(/\d{4}\/\d{4,10}\/07/)
       end
 
+      ##
+      # Produces a company south african close corporation registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_close_corporation_registration_number #=> "CK38/5739937418/23"
+      #
+      # @faker.version 1.9.2
       def south_african_close_corporation_registration_number
         regexify(/(CK\d{2}|\d{4})\/\d{4,10}\/23/)
       end
 
+      ##
+      # Produces a company south african listed company registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_listed_company_registration_number #=> "2512/87676/06"
+      #
+      # @faker.version 1.9.2
       def south_african_listed_company_registration_number
         regexify(/\d{4}\/\d{4,10}\/06/)
       end
 
+      ##
+      # Produces a company south african trust registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.south_african_trust_registration_number #=> "IT5673/937519896"
+      #
+      # @faker.version 1.9.2
       def south_african_trust_registration_number
         regexify(/IT\d{2,4}\/\d{2,10}/)
       end
 
+      ##
+      # Produces a company brazilian company number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.brazilian_company_number #=> "37205322000500"
+      #
+      # @faker.version 1.9.2
       def brazilian_company_number(legacy_formatted = NOT_GIVEN, formatted: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :formatted if legacy_formatted != NOT_GIVEN
@@ -176,6 +399,20 @@ 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.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Company.sic_code #=> "7383"
+      #
+      # @faker.version 1.9.4
       def sic_code
         fetch('company.sic_code')
       end
@@ -259,6 +496,40 @@ 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
     end
   end
 end