faker 2.0.0 → 3.8.0

data/lib/faker/default/industry_segments.rb

@@ -5,18 +5,54 @@ module Faker
     flexible :industry_segments
 
     class << self
+      ##
+      # Produces the name of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.industry #=> "Basic Materials"
+      #
+      # @faker.version 1.9.2
       def industry
         fetch('industry_segments.industry')
       end
 
+      ##
+      # Produces the name of a super-sector of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.super_sector #=> "Basic Resources"
+      #
+      # @faker.version 1.9.2
       def super_sector
         fetch('industry_segments.super_sector')
       end
 
+      ##
+      # Produces the name of a sector of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.sector #=> "Industrial Metals & Mining"
+      #
+      # @faker.version 1.9.2
       def sector
         fetch('industry_segments.sector')
       end
 
+      ##
+      # Produces the name of a subsector of an industry.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IndustrySegments.industry #=> "Basic Materials"
+      #
+      # @faker.version 1.9.2
       def sub_sector
         fetch('industry_segments.sub_sector')
       end

data/lib/faker/default/invoice.rb

@@ -5,21 +5,48 @@ module Faker
     flexible :invoice
 
     class << self
-      # Generate random amount between values with 2 decimals
+      ##
+      # Produces a random amount between values with 2 decimals
+      #
+      # @param from [Integer] Specifies lower limit.
+      # @param to [Integer] Specifies upper limit.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Invoice.amount_between #=> 0
+      #   Faker::Invoice.amount_between(from: 0, to: 10) #=> 4.33
+      #
+      # @faker.version 1.9.0
       def amount_between(from: 0, to: 0)
         Faker::Base.rand_in_range(from, to).round(2)
       end
 
-      # International bank slip reference https://en.wikipedia.org/wiki/Creditor_Reference
-      # ref is optional so that we can create unit tests
+      ##
+      # Produces a random valid reference according to the International bank slip reference https://en.wikipedia.org/wiki/Creditor_Reference
+      #
+      # @param ref [String] Specifies reference base.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Invoice.creditor_reference #=> "RF34118592570724925498"
+      #
+      # @faker.version 1.9.0
       def creditor_reference(ref: '')
         ref = reference if ref.empty?
 
-        'RF' + iban_checksum('RF', ref) + ref
+        "RF#{iban_checksum('RF', ref)}#{ref}"
       end
 
-      # Payment references have some rules in certain countries
-      # ref is optional so that we can create unit tests
+      ##
+      # Produces a random valid reference.
+      #
+      # @param ref [String] Specifies reference base.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Invoice.reference #=> "45656646957845"
+      #
+      # @faker.version 1.9.0
       def reference(ref: '')
         pattern = fetch('invoice.reference.pattern')
 
@@ -75,7 +102,7 @@ module Faker
         mod10_remainder(weighted_sum)
       end
 
-      # Calculates weigthed sum
+      # Calculates weighted sum
       #
       # For example with 12345678, [1,2]
       # Ref.num. 1 2 3 4 5 6 7 8

data/lib/faker/default/job.rb

@@ -5,18 +5,54 @@ module Faker
     flexible :job
 
     class << self
+      ##
+      # Produces a random job title.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Job.title #=> "Construction Manager"
+      #
+      # @faker.version 1.7.0
       def title
         parse('job.title')
       end
 
+      ##
+      # Produces a random job position.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Job.position #=> "Strategist"
+      #
+      # @faker.version 1.8.7
       def position
         fetch('job.position')
       end
 
+      ##
+      # Produces a random job field.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Job.field #=> "Banking"
+      #
+      # @faker.version 1.7.0
       def field
         fetch('job.field')
       end
 
+      ##
+      # Produces a random job skill.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Job.key_skill #=> "Leadership"
+      #
+      # @faker.version 1.7.0
       def key_skill
         fetch('job.key_skills')
       end

data/lib/faker/default/json.rb

@@ -1,22 +1,79 @@
+# frozen_string_literal: true
+
 module Faker
   class Json < Base
     require 'json'
 
     class << self
+      ##
+      # Produces a random simple JSON formatted string.
+      #
+      # @param width [Integer] Specifies the number of key-value pairs.
+      # @param options [Hash] Specifies a Faker gem class to use for keys and for values, respectably. options_hash = {key: Class.method, value: Class.method}
+      # @return [Hash{String => String}]
+      #
+      # @example
+      #   Faker::Json.shallow_json(width: 3, options: { key: 'RockBand.name', value: 'Seinfeld.quote' }) # =>
+      #     {"Parliament Funkadelic":"They're real, and they're spectacular.",
+      #     "Fleetwood Mac":"I'm not a lesbian. I hate men, but I'm not a lesbian.",
+      #     "The Roots":"It became very clear to me sitting out there today that every decision
+      #     I've made in my entire life has been wrong. My life is the complete opposite of everything
+      #     I want it to be. Every instinct I have, in every aspect of life, be it something to wear,
+      #     something to eat - it's all been wrong."}
+      #
+      # @faker.version 1.9.2
       def shallow_json(width: 3, options: { key: 'Name.first_name', value: 'Name.first_name' })
-        options[:key] = 'Faker::' + options[:key]
-        options[:value] = 'Faker::' + options[:value]
+        options[:key] = "Faker::#{options[:key]}"
+        options[:value] = "Faker::#{options[:value]}"
 
         hash = build_shallow_hash(width, options)
         JSON.generate(hash)
       end
 
+      ##
+      # Produces a random nested JSON formatted string that can take JSON as an additional argument.
+      #
+      # @param json [Hash{String => String}] Specifies a Json.shallow_json and uses its keys as keys of the nested JSON.
+      # @param width [Integer] Specifies the number of nested key-value pairs.
+      # @param options [Hash] Specifies a Faker gem class to use for nested keys and for values, respectably. options_hash = {key: Class.method, value: Class.method}
+      # @return [Hash{String => String}]
+      #
+      # @example
+      #   json = Faker::Json.shallow_json(width: 3, options: { key: 'Name.first_name', value: 'Name.last_name' })
+      #   puts json # =>
+      #     {"Alisha":"Olson","Everardo":"DuBuque","Bridgette":"Turner"}
+      #
+      #   json2 = Faker::Json.add_depth_to_json(json: json, width: 2, options: { key: 'Name.first_name', value: 'Name.last_name' })
+      #   puts json2 # =>
+      #     {"Alisha":{"Daisy":"Trantow","Oda":"Haag"},
+      #      "Everardo":{"Javier":"Marvin","Eliseo":"Schuppe"},
+      #      "Bridgette":{"Jorge":"Kertzmann","Lelah":"MacGyver"}}
+      #
+      #    json3 = Faker::Json.add_depth_to_json(json: json2, width: 4, options: { key: 'Name.first_name', value: 'Name.last_name' })
+      #      puts json3 # =>
+      #        {"Alisha":
+      #          {"Daisy":
+      #            {"Bulah":"Wunsch","Cristian":"Champlin","Lester":"Bartoletti","Greg":"Jacobson"},
+      #           "Oda":
+      #             {"Salvatore":"Kuhlman","Aubree":"Okuneva","Larry":"Schmitt","Velva":"Gibson"}},
+      #         "Everardo":
+      #           {"Javier":
+      #             {"Eduardo":"Orn","Laila":"Kub","Thad":"Legros","Dion":"Wilderman"},
+      #           "Eliseo":
+      #             {"Olin":"Hilpert","Marisa":"Greenfelder","Karlee":"Schmitt","Judd":"Larkin"}},
+      #         "Bridgette":
+      #           {"Jorge":
+      #             {"Eloy":"Pfeffer","Kody":"Hansen","Paxton":"Lubowitz","Abe":"Lesch"},
+      #           "Lelah":
+      #             {"Rick":"Wiza","Bonita":"Bayer","Gardner":"Auer","Felicity":"Abbott"}}}
+      #
+      # @faker.version 1.9.2
       def add_depth_to_json(json: shallow_json, width: 3, options: { key: 'Name.first_name', value: 'Name.first_name' })
-        options[:key] = 'Faker::' + options[:key]
-        options[:value] = 'Faker::' + options[:value]
+        options[:key] = "Faker::#{options[:key]}"
+        options[:value] = "Faker::#{options[:value]}"
 
         hash = JSON.parse(json)
-        hash.each do |key, _|
+        hash.each_key do |key|
           add_hash_to_bottom(hash, [key], width, options)
         end
         JSON.generate(hash)
@@ -38,7 +95,7 @@ module Faker
       def add_hash_to_bottom(hash, key_array, width, options)
         key_string = build_keys_from_array(key_array)
         if eval("hash#{key_string}").is_a?(::Hash)
-          eval("hash#{key_string}").each do |key, _|
+          eval("hash#{key_string}").each_key do |key|
             key_array << key
             add_hash_to_bottom(hash, key_array, width, options)
           end
@@ -49,17 +106,20 @@ module Faker
       end
 
       def add_hash(key_array, hash, width, options)
-        string_to_eval = 'hash'
+        string_to_eval = 'hash'.dup
+
         key_array.length.times do |index|
           string_to_eval << "['#{key_array[index]}']"
         end
         string_to_eval << " = #{build_shallow_hash(width, options)}"
         eval(string_to_eval)
+
         hash
       end
 
       def build_keys_from_array(key_array)
-        key_string = ''
+        key_string = ''.dup
+
         key_array.each do |value|
           key_string << "['#{value}']"
         end

data/lib/faker/default/kpop.rb

@@ -3,26 +3,80 @@
 module Faker
   class Kpop < Base
     class << self
+      ##
+      # Produces the name of a 1990's 'OG' K-Pop group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.i_groups #=> "Seo Taiji and Boys"
+      #
+      # @faker.version 1.8.5
       def i_groups
         fetch('kpop.i_groups')
       end
 
+      ##
+      # Produces the name of a 2000's K-Pop group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.ii_groups #=> "Girls' Generation"
+      #
+      # @faker.version 1.8.5
       def ii_groups
         fetch('kpop.ii_groups')
       end
 
+      ##
+      # Produces the name of a 2010's K-Pop group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.iii_groups #=> "Trouble Maker"
+      #
+      # @faker.version 1.8.5
       def iii_groups
         fetch('kpop.iii_groups')
       end
 
+      ##
+      # Produces the name of a K-Pop girl group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.girl_groups #=> "2NE1"
+      #
+      # @faker.version 1.8.5
       def girl_groups
         fetch('kpop.girl_groups')
       end
 
+      ##
+      # Produces the name of a K-Pop boy band.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.boy_bands #=> "Exo"
+      #
+      # @faker.version 1.8.5
       def boy_bands
         fetch('kpop.boy_bands')
       end
 
+      ##
+      # Produces the name of a solo K-Pop artist.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Kpop.solo #=> "T.O.P"
+      #
+      # @faker.version 1.8.5
       def solo
         fetch('kpop.solo')
       end

data/lib/faker/default/lorem.rb

@@ -4,62 +4,235 @@ module Faker
   # Based on Perl's Text::Lorem
   class Lorem < Base
     class << self
-      def word
-        sample(translate('faker.lorem.words'))
+      ##
+      # Returs the random word
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.word   #=> "soluto"
+      #   Faker::Lorem.word(exclude_words: 'error') #=> "nisi"
+      #   Faker::Lorem.word(exclude_words: 'id, error') #=> "et"
+      #   Faker::Lorem.word(exclude_words: ['id', 'error']) #=> "consequatur"
+      #
+      # @faker.version 2.1.3
+      def word(exclude_words: nil)
+        words(number: 1, exclude_words: exclude_words).first
       end
 
-      def words(number: 3, supplemental: false)
+      ##
+      # Generates random 3 words
+      #
+      # @param number [Integer] Number of words to be generated
+      # @param supplemental [Boolean] Whether to attach supplemental words at the end, default is false
+      #
+      # @return [Array] Array for words
+      #
+      # @example
+      #   Faker::Lorem.words                                    #=> ["hic", "quia", "nihil"]
+      #   Faker::Lorem.words(number: 4)                         #=> ["est", "temporibus", "et", "quaerat"]
+      #   Faker::Lorem.words(number: 4, supplemental: true)    #=> ["nisi", "sit", "allatus", "consequatur"]
+      #   Faker::Lorem.words(number: 4, supplemental: true, exclude_words: 'sit') #=> ["nisi", "allatus", "consequatur", "aut"]
+      #
+      # @faker.version 2.1.3
+      def words(number: 3, supplemental: false, exclude_words: nil)
         resolved_num = resolve(number)
         word_list = (
           translate('faker.lorem.words') +
           (supplemental ? translate('faker.lorem.supplemental') : [])
         )
+        if exclude_words
+          exclude_words = exclude_words.split(', ') if exclude_words.instance_of?(::String)
+          word_list -= exclude_words
+        end
         word_list *= ((resolved_num / word_list.length) + 1)
-        shuffle(word_list)[0, resolved_num]
+        sample(word_list, resolved_num)
       end
 
+      ##
+      # Generates single character
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.character    #=> "e"
+      #
+      # @faker.version 2.1.3
       def character
-        sample(Types::CHARACTERS)
+        sample(Faker::Types::CHARACTERS)
       end
 
-      def characters(number: 255)
-        Alphanumeric.alphanumeric(number: number)
+      ##
+      # 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::Lorem.characters #=> "uw1ep04lhs0c4d931n1jmrspprf5w..."
+      #   Faker::Lorem.characters(number: 10) #=> "ang9cbhoa8"
+      #   Faker::Lorem.characters(number: 10, min_alpha: 4) #=> "ang9cbhoa8"
+      #   Faker::Lorem.characters(number: 10, min_alpha: 4, min_numeric: 1) #=> "ang9cbhoa8"
+      #
+      # @faker.version 2.1.3
+      def characters(number: 255, min_alpha: 0, min_numeric: 0)
+        Faker::Alphanumeric.alphanumeric(number: number, min_alpha: min_alpha, min_numeric: min_numeric)
       end
 
+      ##
+      # Generates the emoji
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.multibyte  #=> "😀"
+      #   Faker::Lorem.multibyte  #=> "❤"
+      #
+      # @faker.version 2.1.3
       def multibyte
         sample(translate('faker.lorem.multibyte')).pack('C*').force_encoding('utf-8')
       end
 
-      def sentence(word_count: 4, supplemental: false, random_words_to_add: 0)
-        words(number: word_count + rand(random_words_to_add.to_i), supplemental: supplemental).join(' ').capitalize + locale_period
+      ##
+      # Generates sentence
+      #
+      # @param word_count [Integer] How many words should be there in a sentence, default to 4
+      # @param supplemental [Boolean] Add supplemental words, default to false
+      # @param random_words_to_add [Integer] Add any random words, default to 0
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.sentence                                                             #=> "Magnam qui aut quidem."
+      #   Faker::Lorem.sentence(word_count: 5)                                              #=> "Voluptas rerum aut aliquam velit."
+      #   Faker::Lorem.sentence(word_count: 5, supplemental: true)                          #=> "Aut viscus curtus votum iusto."
+      #   Faker::Lorem.sentence(word_count: 5, supplemental: true, random_words_to_add:2)   #=> "Crinis quo cruentus velit animi vomer."
+      #
+      # @faker.version 2.1.3
+      def sentence(word_count: 4, supplemental: false, random_words_to_add: 0, exclude_words: nil)
+        words(number: word_count + rand(random_words_to_add.to_i), supplemental: supplemental, exclude_words: exclude_words).join(locale_space).capitalize + locale_period
       end
 
-      def sentences(number: 3, supplemental: false)
-        1.upto(resolve(number)).collect { sentence(word_count: 3, supplemental: supplemental) }
+      ##
+      # Generates three sentences
+      #
+      # @param number [Integer] How many sentences to be generated, default to 3
+      # @param supplemental [Boolean] Should add supplemental words, defaults to false
+      #
+      # @return [Array] Returns array for sentences.
+      #
+      # @example
+      #   Faker::Lorem.sentences                                  #=> ["Possimus non tenetur.", "Nulla non excepturi.", "Quisquam rerum facilis."]
+      #   Faker::Lorem.sentences(number: 2)                       #=> ["Nulla est natus.", "Perferendis autem cum."]
+      #   Faker::Lorem.sentences(number: 2, supplemental: true)   #=> ["Cito cena ad.", "Solvo animus allatus."]
+      #
+      # @faker.version 2.1.3
+      def sentences(number: 3, supplemental: false, exclude_words: nil)
+        1.upto(resolve(number)).collect { sentence(word_count: 3, supplemental: supplemental, exclude_words: exclude_words) }
       end
 
-      def paragraph(sentence_count: 3, supplemental: false, random_sentences_to_add: 0)
-        sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i), supplemental: supplemental).join(locale_space)
+      ##
+      # Generates three sentence paragraph
+      #
+      # @param sentence_count [Integer] Number of sentences in the paragraph
+      # @param supplemental [Boolean]
+      # @param random_sentences_to_add [Integer]
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.paragraph
+      #     #=> "Impedit et est. Aliquid deleniti necessitatibus. Et aspernatur minima."
+      #   Faker::Lorem.paragraph(sentence_count: 2)
+      #     #=> "Rerum fugit vitae. Et atque autem."
+      #   Faker::Lorem.paragraph(sentence_count: 2, supplemental: true)
+      #     #=> "Terreo coerceo utor. Vester sunt cogito."
+      #   Faker::Lorem.paragraph(sentence_count: 2, supplemental: true, random_sentences_to_add: 2)
+      #     #=> "Texo tantillus tamisium. Tribuo amissio tamisium. Facere aut canis."
+      #
+      # @faker.version 2.1.3
+      def paragraph(sentence_count: 3, supplemental: false, random_sentences_to_add: 0, exclude_words: nil)
+        sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i), supplemental: supplemental, exclude_words: exclude_words).join(locale_space)
       end
 
-      def paragraphs(number: 3, supplemental: false)
-        1.upto(resolve(number)).collect { paragraph(sentence_count: 3, supplemental: supplemental) }
+      ##
+      # Generates three paragraphs
+      #
+      # @param number [Integer]
+      # @param supplemental [Boolean]
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Lorem.paragraphs
+      #   Faker::Lorem.paragraphs(number:2)
+      #   Faker::Lorem.paragraphs(number:2, supplemental: true)
+      #
+      # @faker.version 2.1.3
+      def paragraphs(number: 3, supplemental: false, exclude_words: nil)
+        1.upto(resolve(number)).collect { paragraph(sentence_count: 3, supplemental: supplemental, exclude_words: exclude_words) }
       end
 
+      ##
+      # Generates paragraph with 256 characters
+      #
+      # @param number [Integer]
+      # @param supplemental [Boolean]
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.paragraph_by_chars
+      #   Faker::Lorem.paragraph_by_chars(number: 20)                       #=> "Sit modi alias. Imp."
+      #   Faker::Lorem.paragraph_by_chars(number: 20, supplemental: true)   #=> "Certus aveho admove."
+      #
+      # @faker.version 2.1.3
       def paragraph_by_chars(number: 256, supplemental: false)
         paragraph = paragraph(sentence_count: 3, supplemental: supplemental)
 
-        paragraph += ' ' + paragraph(sentence_count: 3, supplemental: supplemental) while paragraph.length < number
+        paragraph += " #{paragraph(sentence_count: 3, supplemental: supplemental)}" while paragraph.length < number
 
-        paragraph[0...number - 1] + '.'
+        "#{paragraph[0...(number - 1)]}."
       end
 
-      def question(word_count: 4, supplemental: false, random_words_to_add: 0)
-        words(number: word_count + rand(random_words_to_add), supplemental: supplemental).join(' ').capitalize + locale_question_mark
+      ##
+      # Returns the question with 4 words
+      #
+      # @param word_count [Integer]
+      # @param supplemental [Boolean]
+      # @param random_words_to_add [Integer]
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.question                                                               #=> "Natus deleniti sequi laudantium?"
+      #   Faker::Lorem.question(word_count: 2)                                                #=> "Quo ut?"
+      #   Faker::Lorem.question(word_count: 2, supplemental: true)                            #=> "Terga consequatur?"
+      #   Faker::Lorem.question(word_count: 2, supplemental: true, random_words_to_add: 2)    #=> "Depulso uter ut?"
+      #
+      # @faker.version 2.1.3
+      def question(word_count: 4, supplemental: false, random_words_to_add: 0, exclude_words: nil)
+        words(number: word_count + rand(random_words_to_add), supplemental: supplemental, exclude_words: exclude_words).join(' ').capitalize + locale_question_mark
       end
 
-      def questions(number: 3, supplemental: false)
-        1.upto(resolve(number)).collect { question(word_count: 3, supplemental: supplemental) }
+      ##
+      # Generates array of three questions
+      #
+      # @param number [Integer]
+      # @param supplemental [Boolean]
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Lorem.questions                                  #=> ["Amet culpa enim?", "Voluptatem deleniti numquam?", "Veniam non cum?"]
+      #   Faker::Lorem.questions(number: 2)                       #=> ["Minus occaecati nobis?", "Veniam et alias?"]
+      #   Faker::Lorem.questions(number: 2, supplemental: true)   #=> ["Acceptus subito cetera?", "Aro sulum cubicularis?"]
+      #
+      # @faker.version 2.1.3
+      def questions(number: 3, supplemental: false, exclude_words: nil)
+        1.upto(resolve(number)).collect { question(word_count: 3, supplemental: supplemental, exclude_words: exclude_words) }
       end
 
       private