faker 2.0.0 → 3.8.0

data/lib/faker/default/cannabis.rb

@@ -2,42 +2,132 @@
 
 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/chile_rut.rb

@@ -5,13 +5,35 @@ module Faker
     class << self
       @last_rut = nil
 
-      # Fixed param added for testing a specific RUT and check digit combination.
-      def rut(min_rut: 1, fixed: false)
-        @last_rut = fixed ? min_rut : rand_in_range(min_rut, 99_999_999)
+      ##
+      # Produces a random Chilean RUT (Rol Unico Tributario, ID with 8 digits).
+      #
+      # @param min_rut [Integer] Specifies the minimum value of the RUT.
+      # @param max_rut [Integer] Specifies the maximum value of the RUT.
+      # @param fixed [Boolean] Determines if the RUT is fixed (returns the min_rut value).
+      # @return [Number]
+      #
+      # @example
+      #   Faker::ChileRut.rut #=> 11235813
+      #   Faker::ChileRut.rut(min_rut: 10_000_000, max_rut: 30_000_000) #=> 21853211
+      #   Faker::ChileRut.rut(min_rut: 20_890_156, fixed: true) #=> 20890156
+      #
+      # @faker.version next
+      def rut(min_rut: 1, max_rut: 99_999_999, fixed: false)
+        @last_rut = fixed ? min_rut : rand_in_range(min_rut, max_rut)
       end
 
+      ##
+      # Produces a random Chilean digito verificador (check-digit).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChileRut.dv #=> "k"
+      #
+      # @faker.version 1.9.2
       def dv
-        split_reversed_rut = @last_rut.to_s.reverse.split('')
+        split_reversed_rut = @last_rut.to_s.reverse.chars
         seq = [2, 3, 4, 5, 6, 7]
         i = 0
         digit_sum = split_reversed_rut.reduce(0) do |sum, n|
@@ -20,25 +42,57 @@ module Faker
           partial_result
         end
         partial_check_digit = 11 - (digit_sum % 11)
-        if partial_check_digit == 11
+        case partial_check_digit
+        when 11
           '0'
-        elsif partial_check_digit == 10
+        when 10
           'k'
         else
           partial_check_digit.to_s
         end
       end
 
+      ##
+      # Produces a random Chilean digito verificador (check-digit).
       # Alias for english speaking devs.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChileRut.check_digit #=> "5"
+      #
+      # @faker.version 1.9.2
       def check_digit
         dv
       end
 
-      def full_rut(min_rut: 0, fixed: false)
-        "#{rut(min_rut: min_rut, fixed: fixed)}-#{dv}"
+      ##
+      # Produces a random Chilean RUT (Rol Unico Tributario, ID with 8 digits) with a dv (digito verificador, check-digit).
+      #
+      # @param min_rut [Integer] Specifies the minimum value of the RUT.
+      # @param max_rut [Integer] Specifies the maximum value of the RUT.
+      # @param fixed [Boolean] Determines if the RUT is fixed (returns the min_rut value).
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChileRut.full_rut #=> "30686957-4"
+      #   Faker::ChileRut.full_rut(min_rut: 10_000_000, max_rut: 30_000_000) #=> "20686957-4"
+      #   Faker::ChileRut.full_rut(min_rut: 30_686_957, fixed: true) #=> "30686957-4"
+      #
+      # @faker.version next
+      def full_rut(min_rut: 1, max_rut: 99_999_999, fixed: false, formatted: false)
+        this_rut = rut(min_rut: min_rut, max_rut: max_rut, fixed: fixed)
+        this_rut = format_rut(this_rut) if formatted
+        "#{this_rut}-#{dv}"
       end
 
       attr_reader :last_rut
+
+      private
+
+      def format_rut(rut)
+        rut.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1.').reverse
+      end
     end
   end
 end

data/lib/faker/default/chuck_norris.rb

@@ -2,10 +2,21 @@
 
 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
+      ##
+      # Produces a Chuck Norris Fact.
+      # Original list of facts:
+      # https://github.com/jenkinsci/chucknorris-plugin/blob/master/src/main/java/hudson/plugins/chucknorris/FactGenerator.java
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ChuckNorris.fact
+      #     #=> "Chuck Norris can solve the Towers of Hanoi in one move."
+      #
+      # @faker.version 1.6.4
       def fact
         fetch('chuck_norris.fact')
       end

data/lib/faker/default/code.rb

@@ -4,54 +4,149 @@ 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 Identifier) 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(base: 10)
-        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(base: 13)
-        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 8 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)
         value << "-#{vd}"
       end
 
+      ##
+      # Produces a random NRIC (National Registry Identity Card) code.
       # By default generates a Singaporean NRIC ID for someone
       # who is born between the age of 18 and 65.
+      #
+      # @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(min_age: 18, max_age: 65)
         birthyear = Date.birthday(min_age: min_age, max_age: max_age).year
-        prefix = birthyear < 2000 ? 'S' : 'T'
-        values = birthyear.to_s[-2..-1]
-        values << regexify(/\d{5}/)
-        check_alpha = generate_nric_check_alphabet(values, prefix)
-        "#{prefix}#{values}#{check_alpha}"
+
+        generate(:string) do |g|
+          g.computed(name: :prefix) do
+            if birthyear < 2000
+              'S'
+            else
+              'T'
+            end
+          end
+          g.computed(name: :yy) do
+            birthyear.to_s[-2..]
+          end
+          g.int(name: :values, length: 5)
+          g.computed(name: :check, deps: %i[prefix yy values]) do |prefix, yy, values|
+            generate_nric_check_alphabet("#{yy}#{values}", prefix)
+          end
+        end
       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
@@ -64,7 +159,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
@@ -73,12 +168,11 @@ module Faker
 
       # Reporting body identifier
       RBI = %w[01 10 30 33 35 44 45 49 50 51 52 53 54 86 91 98 99].freeze
+      private_constant :RBI
 
       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.
@@ -112,50 +206,83 @@ module Faker
         str[len - 1] = (10 - (sum % 10)) % 10
 
         # Output the IMEI value.
-        str.join('')
+        str.join
       end
 
       def generate_base10_isbn
-        values = regexify(/\d{9}/)
-        remainder = sum(values) { |value, index| (index + 1) * value.to_i } % 11
-        values << "-#{remainder == 10 ? 'X' : remainder}"
+        generate(:string) do |g|
+          g.int(name: :values, length: 9)
+          g.lit('-')
+          g.computed(name: :checksum, deps: [:values]) do |values|
+            remainder = sum(values.to_s) { |value, offset| (offset + 1) * value.to_i } % 11
+            if remainder == 10
+              'X'
+            else
+              remainder.to_s
+            end
+          end
+        end
       end
 
       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)}"
+        generate(:string) do |g|
+          g.int(name: :values, length: 12)
+          g.lit('-')
+          g.computed(name: :checksum, deps: [:values]) do |values|
+            remainder = sum(values.to_s) { |value, offset| offset.even? ? value.to_i : value.to_i * 3 } % 10
+            (10 - remainder) % 10
+          end
+        end
       end
 
       def sum(values)
-        values.split(//).each_with_index.inject(0) do |sum, (value, index)|
+        values.chars.each_with_index.inject(0) do |sum, (value, index)|
           sum + yield(value, index)
         end
       end
 
       def generate_base8_ean
-        values = regexify(/\d{7}/)
-        check_digit = 10 - values.split(//).each_with_index.inject(0) { |s, (v, i)| s + v.to_i * EAN_CHECK_DIGIT8[i] } % 10
-        values << (check_digit == 10 ? 0 : check_digit).to_s
+        generate(:string) do |g|
+          g.int(name: :values, length: 7)
+          g.computed(name: :checksum, deps: [:values]) do |values|
+            check_digit = 10 - values.to_s.chars.each_with_index.inject(0) { |s, (v, i)| s + v.to_i * EAN_CHECK_DIGIT8[i] } % 10
+            if check_digit == 10
+              0
+            else
+              check_digit
+            end
+          end
+        end
       end
 
       def generate_base13_ean
-        values = regexify(/\d{12}/)
-        check_digit = 10 - values.split(//).each_with_index.inject(0) { |s, (v, i)| s + v.to_i * EAN_CHECK_DIGIT13[i] } % 10
-        values << (check_digit == 10 ? 0 : check_digit).to_s
+        generate(:string) do |g|
+          g.int(name: :values, length: 12)
+          g.computed(name: :checksum, deps: [:values]) do |values|
+            check_digit = 10 - values.to_s.chars.each_with_index.inject(0) { |s, (v, i)| s + v.to_i * EAN_CHECK_DIGIT13[i] } % 10
+            if check_digit == 10
+              0
+            else
+              check_digit
+            end
+          end
+        end
       end
 
       EAN_CHECK_DIGIT8 = [3, 1, 3, 1, 3, 1, 3].freeze
+      private_constant :EAN_CHECK_DIGIT8
+
       EAN_CHECK_DIGIT13 = [1, 3, 1, 3, 1, 3, 1, 3, 1, 3, 1, 3].freeze
+      private_constant :EAN_CHECK_DIGIT13
 
       def rut_verificator_digit(rut)
-        total = rut.to_s.rjust(8, '0').split(//).zip(%w[3 2 7 6 5 4 3 2]).collect { |a, b| a.to_i * b.to_i }.inject(:+)
-        (11 - total % 11).to_s.gsub(/10/, 'k').gsub(/11/, '0')
+        total = rut.to_s.rjust(8, '0').chars.zip(%w[3 2 7 6 5 4 3 2]).collect { |a, b| a.to_i * b.to_i }.inject(:+)
+        (11 - total % 11).to_s.gsub('10', 'k').gsub('11', '0')
       end
 
       def generate_nric_check_alphabet(values, prefix)
         weight = %w[2 7 6 5 4 3 2]
-        total = values.split(//).zip(weight).collect { |a, b| a.to_i * b.to_i }.inject(:+)
+        total = values.chars.zip(weight).collect { |a, b| a.to_i * b.to_i }.inject(:+)
         total += 4 if prefix == 'T'
         %w[A B C D E F G H I Z J][10 - total % 11]
       end

data/lib/faker/default/coffee.rb

@@ -5,24 +5,69 @@ module Faker
     flexible :coffee
 
     class << self
+      ##
+      # Produces a random blend name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.blend_name #=> "Major Java"
+      #
+      # @faker.version 1.9.0
       def blend_name
         parse('coffee.blend_name')
       end
 
+      ##
+      # Produces a random coffee origin place.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.origin #=> "Oaxaca, Mexico"
+      #
+      # @faker.version 1.9.0
       def origin
         country = fetch('coffee.country')
         region = fetch("coffee.regions.#{search_format(country)}")
         "#{region}, #{country}"
       end
 
+      ##
+      # Produces a random coffee variety.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.variety #=> "Red Bourbon"
+      #
+      # @faker.version 1.9.0
       def variety
         fetch('coffee.variety')
       end
 
+      ##
+      # Produces a string containing a random description of a coffee's taste.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.notes #=> "dull, tea-like, cantaloupe, soy sauce, marshmallow"
+      #
+      # @faker.version 1.9.0
       def notes
         parse('coffee.notes')
       end
 
+      ##
+      # Produces a random coffee taste intensity.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coffee.intensifier #=> "mild"
+      #
+      # @faker.version 1.9.0
       def intensifier
         fetch('coffee.intensifier')
       end

data/lib/faker/default/coin.rb

@@ -3,10 +3,28 @@
 module Faker
   class Coin < Base
     class << self
+      ##
+      # Retrieves a random coin from any country.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coin.name #=> "Brazilian Real"
+      #
+      # @faker.version 1.9.2
       def name
         fetch('currency.name')
       end
 
+      ##
+      # Retrieves a face to a flipped coin
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Coin.flip #=> "Heads"
+      #
+      # @faker.version 1.9.2
       def flip
         fetch('coin.flip')
       end