faker 2.11.0 → 2.13.0

data/lib/faker/default/file.rb

@@ -3,6 +3,21 @@
 module Faker
   class File < Base
     class << self
+      ##
+      # Produces a random directory name.
+      #
+      # @param segment_count [Integer] Specifies the number of nested folders in the generated string.
+      # @param root [String] Specifies the root of the generated string.
+      # @param directory_separator [String] Specifies the separator between the segments.
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.dir #=> "et_error/sint_voluptas/quas_veritatis"
+      #   Faker::File.dir(segment_count: 2) #=> "ea-suscipit/ut-deleniti"
+      #   Faker::File.dir(segment_count: 3, root: nil, directory_separator: '/') #=> "est_porro/fugit_eveniet/incidunt-autem"
+      #   Faker::File.dir(segment_count: 3, root: nil, directory_separator: '\\') #=> "aut-ullam\\quia_quisquam\\ut-eos"
+      #
+      # @faker.version 1.6.4
       # rubocop:disable Metrics/ParameterLists
       def dir(legacy_segment_count = NOT_GIVEN, legacy_root = NOT_GIVEN, legacy_directory_separator = NOT_GIVEN, segment_count: 3, root: nil, directory_separator: ::File::Separator)
         # rubocop:enable Metrics/ParameterLists
@@ -20,14 +35,48 @@ module Faker
           .squeeze(directory_separator)
       end
 
+      ##
+      # Produces a random file extension.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.extension #=> "mp3"
+      #
+      # @faker.version 1.6.4
       def extension
         fetch('file.extension')
       end
 
+      ##
+      # Produces a random mime type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.mime_type #=> "application/pdf"
+      #
+      # @faker.version 1.6.4
       def mime_type
         fetch('file.mime_type')
       end
 
+      ##
+      # Produces a random file name.
+      #
+      # @param dir [String] Specifies the path used for the generated file.
+      # @param name [String] Specifies the filename used for the generated file.
+      # @param ext [String] Specifies the extension used the generated file.
+      # @param directory_separator [String] Specifies the separator between the directory and name elements.
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.file_name(dir: 'path/to') #=> "path/to/something_random.jpg"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz') #=> "foo/bar/baz.zip"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz', ext: 'doc') #=> "foo/bar/baz.doc"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz', ext: 'mp3', directory_separator: '\\') #=> "foo/bar\\baz.mp3"
+      #
+      # @faker.version 1.6.4
       # rubocop:disable Metrics/ParameterLists
       def file_name(legacy_dir = NOT_GIVEN, legacy_name = NOT_GIVEN, legacy_ext = NOT_GIVEN, legacy_directory_separator = NOT_GIVEN, dir: nil, name: nil, ext: nil, directory_separator: ::File::Separator)
         # rubocop:enable Metrics/ParameterLists

data/lib/faker/default/finance.rb

@@ -7,6 +7,18 @@ module Faker
                            maestro forbrugsforeningen laser].freeze
 
     class << self
+      ##
+      # Produces a random credit card number.
+      #
+      # @param types [String] Specific credit card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.credit_card #=> "3018-348979-1853"
+      #   Faker::Finance.credit_card(:mastercard) #=> "6771-8921-2291-6236"
+      #   Faker::Finance.credit_card(:mastercard, :visa) #=> "4448-8934-1277-7195"
+      #
+      # @faker.version 1.2.0
       def credit_card(*types)
         types = CREDIT_CARD_TYPES if types.empty?
         type = sample(types)
@@ -26,6 +38,18 @@ module Faker
         template.gsub('L', luhn_digit.to_s)
       end
 
+      ##
+      # Produces a random vat number.
+      #
+      # @param country [String] Two capital letter country code to use for the vat number.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.vat_number #=> "BR38.395.329/2471-83"
+      #   Faker::Finance.vat_number('DE') #=> "DE593306671"
+      #   Faker::Finance.vat_number('ZA') #=> "ZA79494416181"
+      #
+      # @faker.version 1.9.2
       def vat_number(legacy_country = NOT_GIVEN, country: 'BR')
         warn_for_deprecated_arguments do |keywords|
           keywords << :country if legacy_country != NOT_GIVEN

data/lib/faker/default/gender.rb

@@ -37,7 +37,7 @@ module Faker
       # @example
       #   Faker::Gender.short_binary_type #=> "f"
       #
-      # @faker.version next
+      # @faker.version 2.13.0
       def short_binary_type
         fetch('gender.short_binary_types')
       end

data/lib/faker/default/hipster.rb

@@ -3,11 +3,35 @@
 module Faker
   class Hipster < Base
     class << self
+      ##
+      # Produces a random hipster word.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.word #=> "irony"
+      #
+      # @faker.version 1.6.0
       def word
         random_word = sample(translate('faker.hipster.words'))
         random_word =~ /\s/ ? word : random_word
       end
 
+      ##
+      # Produces a random hipster word.
+      #
+      # @param number [Integer] Specifies the number of words returned
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @param spaces_allowed [Boolean] Specifies if the words may contain spaces
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Hipster.words #=> ["pug", "pitchfork", "chia"]
+      #   Faker::Hipster.words(number: 4) #=> ["ugh", "cardigan", "poutine", "stumptown"]
+      #   Faker::Hipster.words(number: 4, supplemental: true) #=> ["iste", "seitan", "normcore", "provident"]
+      #   Faker::Hipster.words(number: 4, supplemental: true, spaces_allowed: true) #=> ["qui", "magni", "craft beer", "est"]
+      #
+      # @faker.version 1.6.0
       # rubocop:disable Metrics/ParameterLists
       def words(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_spaces_allowed = NOT_GIVEN, number: 3, supplemental: false, spaces_allowed: false)
         # rubocop:enable Metrics/ParameterLists
@@ -30,6 +54,22 @@ module Faker
         words.each_with_index { |w, i| words[i] = word if w =~ /\s/ }
       end
 
+      ##
+      # Produces a random hipster sentence.
+      #
+      # @param word_count [Integer] Specifies the number of words in the sentence
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @param random_words_to_add [Boolean] Specifies the number of random words to add
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.sentence #=> "Park iphone leggings put a bird on it."
+      #   Faker::Hipster.sentence(word_count: 3) #=> "Pour-over swag godard."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: true) #=> "Beard laboriosam sequi celiac."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: false, random_words_to_add: 4) #=> "Bitters retro mustache aesthetic biodiesel 8-bit."
+      #   Faker::Hipster.sentence(word_count: 3, supplemental: true, random_words_to_add: 4) #=> "Occaecati deleniti messenger bag meh crucifix autem."
+      #
+      # @faker.version 1.6.0
       # rubocop:disable Metrics/ParameterLists
       def sentence(legacy_word_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, supplemental: false, random_words_to_add: 6)
         # rubocop:enable Metrics/ParameterLists
@@ -42,6 +82,19 @@ module Faker
         words(number: word_count + rand(random_words_to_add.to_i).to_i, supplemental: supplemental, spaces_allowed: true).join(' ').capitalize + '.'
       end
 
+      ##
+      # Produces random hipster sentences.
+      #
+      # @param number [Integer] Specifies the number of sentences returned
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Hipster.sentences #=> ["Godard pitchfork vinegar chillwave everyday 90's whatever.", "Pour-over artisan distillery street waistcoat.", "Salvia yr leggings franzen blue bottle."]
+      #   Faker::Hipster.sentences(number: 1) #=> ["Before they sold out pinterest venmo umami try-hard ugh hoodie artisan."]
+      #   Faker::Hipster.sentences(number: 1, supplemental: true) #=> ["Et sustainable optio aesthetic et."]
+      #
+      # @faker.version 1.6.0
       def sentences(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -55,6 +108,22 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random hipster paragraph.
+      #
+      # @param sentence_count [Integer] Specifies the number of sentences in the paragraph
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @param random_sentences_to_add [Boolean] Specifies the number of random sentences to add
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.paragraph #=> "Migas fingerstache pbr&b tofu. Polaroid distillery typewriter echo tofu actually. Slow-carb fanny pack pickled direct trade scenester mlkshk plaid. Banjo venmo chambray cold-pressed typewriter. Fap skateboard intelligentsia."
+      #   Faker::Hipster.paragraph(sentence_count: 2) #=> "Yolo tilde farm-to-table hashtag. Lomo kitsch disrupt forage +1."
+      #   Faker::Hipster.paragraph(sentence_count: 2, supplemental: true) #=> "Typewriter iste ut viral kombucha voluptatem. Sint voluptates saepe. Direct trade irony chia excepturi yuccie. Biodiesel esse listicle et quam suscipit."
+      #   Faker::Hipster.paragraph(sentence_count: 2, supplemental: false, random_sentences_to_add: 4) #=> "Selvage vhs chartreuse narwhal vinegar. Authentic vinyl truffaut carry vhs pop-up. Hammock everyday iphone locavore thundercats bitters vegan goth. Fashion axe banh mi shoreditch whatever artisan."
+      #   Faker::Hipster.paragraph(sentence_count: 2, supplemental: true, random_sentences_to_add: 4) #=> "Deep v gluten-free unde waistcoat aperiam migas voluptas dolorum. Aut drinking illo sustainable sapiente. Direct trade fanny pack kale chips ennui semiotics."
+      #
+      # @faker.version 1.6.0
       # rubocop:disable Metrics/ParameterLists
       def paragraph(legacy_sentence_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_sentences_to_add = NOT_GIVEN, sentence_count: 3, supplemental: false, random_sentences_to_add: 3)
         # rubocop:enable Metrics/ParameterLists
@@ -67,6 +136,19 @@ module Faker
         sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i).to_i, supplemental: supplemental).join(' ')
       end
 
+      ##
+      # Produces random hipster paragraphs.
+      #
+      # @param number [Integer] Specifies the number of paragraphs
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Hipster.paragraphs #=> ["Tilde microdosing blog cliche meggings. Intelligentsia five dollar toast forage yuccie. Master kitsch knausgaard. Try-hard everyday trust fund mumblecore.", "Normcore viral pickled. Listicle humblebrag swag tote bag. Taxidermy street hammock neutra butcher cred kale chips. Blog portland humblebrag trust fund irony.", "Single-origin coffee fixie cleanse tofu xoxo. Post-ironic tote bag ramps gluten-free locavore mumblecore hammock. Umami loko twee. Ugh kitsch before they sold out."]
+      #   Faker::Hipster.paragraphs(number: 1) #=> ["Skateboard cronut synth +1 fashion axe. Pop-up polaroid skateboard asymmetrical. Ennui fingerstache shoreditch before they sold out. Tattooed pitchfork ramps. Photo booth yr messenger bag raw denim bespoke locavore lomo synth."]
+      #   Faker::Hipster.paragraphs(number: 1, supplemental: true) #=> ["Quae direct trade pbr&b quo taxidermy autem loko. Umami quas ratione migas cardigan sriracha minima. Tenetur perspiciatis pickled sed eum doloribus truffaut. Excepturi dreamcatcher meditation."]
+      #
+      # @faker.version 1.6.0
       def paragraphs(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN
@@ -80,6 +162,18 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random hipster paragraph by characters.
+      #
+      # @param characters [Integer] Specifies the number of characters in the paragraph
+      # @param supplemental [Boolean] Specifies if the words are supplemental
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hipster.paragraph_by_chars #=> "Truffaut stumptown trust fund 8-bit messenger bag portland. Meh kombucha selvage swag biodiesel. Lomo kinfolk jean shorts asymmetrical diy. Wayfarers portland twee stumptown. Wes anderson biodiesel retro 90's pabst. Diy echo 90's mixtape semiotics. Cornho."
+      #   Faker::Hipster.paragraph_by_chars(characters: 256, supplemental: false) #=> "Hella kogi blog narwhal sartorial selfies mustache schlitz. Bespoke normcore kitsch cred hella fixie. Park aesthetic fixie migas twee. Cliche mustache brunch tumblr fixie godard. Drinking pop-up synth hoodie dreamcatcher typewriter. Kitsch biodiesel green."
+      #
+      # @faker.version 1.6.0
       def paragraph_by_chars(legacy_characters = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, characters: 256, supplemental: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :characters if legacy_characters != NOT_GIVEN

data/lib/faker/default/id_number.rb

@@ -19,10 +19,28 @@ module Faker
     CHILEAN_MODULO = 11
 
     class << self
+      ##
+      # Produces a random valid US Social Security number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.valid #=> "552-56-3593"
+      #
+      # @faker.version 1.6.0
       def valid
         _translate('valid')
       end
 
+      ##
+      # Produces a random invalid US Social Security number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.invalid #=> "311-72-0000"
+      #
+      # @faker.version 1.6.0
       def invalid
         _translate('invalid')
       end
@@ -33,6 +51,15 @@ module Faker
         INVALID_SSN.any? { |regex| regex =~ ssn } ? ssn_valid : ssn
       end
 
+      ##
+      # Produces a random Spanish citizen identifier (DNI).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.spanish_citizen_number #=> "53290236-H"
+      #
+      # @faker.version 1.9.0
       def spanish_citizen_number
         num = Faker::Number.number(digits: 8)
         mod = num.to_i % 23
@@ -40,6 +67,15 @@ module Faker
         "#{num}-#{check}"
       end
 
+      ##
+      # Produces a random Spanish foreign born citizen identifier (NIE).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.spanish_foreign_citizen_number #=> "Z-1600870-Y"
+      #
+      # @faker.version 1.9.0
       def spanish_foreign_citizen_number
         code = 'XYZ'
         digits = Faker::Number.number(digits: 7)
@@ -50,6 +86,16 @@ module Faker
         "#{prefix}-#{digits}-#{check}"
       end
 
+      ##
+      # Produces a random valid South African ID Number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.south_african_id_number #=> "8105128870184"
+      #   Faker::IDNumber.valid_south_african_id_number #=> "8105128870184"
+      #
+      # @faker.version 1.9.2
       def valid_south_african_id_number
         id_number = [
           Faker::Date.birthday.strftime('%y%m%d'),
@@ -63,6 +109,15 @@ module Faker
 
       alias south_african_id_number valid_south_african_id_number
 
+      ##
+      # Produces a random invalid South African ID Number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.invalid_south_african_id_number #=> "1642972065088"
+      #
+      # @faker.version 1.9.2
       def invalid_south_african_id_number
         invalid_date_of_birth = [
           Faker::Number.number(digits: 2),
@@ -80,6 +135,17 @@ module Faker
         [id_number, south_african_id_checksum_digit(id_number)].join
       end
 
+      ##
+      # Produces a random Brazilian Citizen Number (CPF).
+      #
+      # @param formatted [Boolean] Specifies if the number is formatted with dividers.
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.brazilian_citizen_number #=> "53540542221"
+      #   Faker::IDNumber.brazilian_citizen_number(formatted: true) #=> "535.405.422-21"
+      #
+      # @faker.version 1.9.2
       def brazilian_citizen_number(legacy_formatted = NOT_GIVEN, formatted: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :formatted if legacy_formatted != NOT_GIVEN
@@ -94,6 +160,17 @@ module Faker
 
       alias brazilian_cpf brazilian_citizen_number
 
+      ##
+      # Produces a random Brazilian ID Number (RG).
+      #
+      # @param formatted [Boolean] Specifies if the number is formatted with dividers.
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.brazilian_id #=> "493054029"
+      #   Faker::IDNumber.brazilian_id(formatted: true) #=> "49.305.402-9"
+      #
+      # @faker.version 2.1.2
       def brazilian_id(legacy_formatted = NOT_GIVEN, formatted: false)
         warn_for_deprecated_arguments do |keywords|
           keywords << :formatted if legacy_formatted != NOT_GIVEN
@@ -107,6 +184,15 @@ module Faker
 
       alias brazilian_rg brazilian_id
 
+      ##
+      # Produces a random Chilean ID (Rut with 8 digits).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::IDNumber.chilean_id #=> "15620613-K"
+      #
+      # @faker.version 2.1.2
       def chilean_id
         digits = Faker::Number.number(digits: 8)
         verification_code = chilean_verification_code(digits)

data/lib/faker/default/internet.rb

@@ -9,11 +9,14 @@ module Faker
           keywords << :separators if legacy_separators != NOT_GIVEN
         end
 
-        if separators
-          [username(specifier: name, separators: separators), domain_name(domain: domain)].join('@')
-        else
-          [username(specifier: name), domain_name(domain: domain)].join('@')
-        end
+        local_part = if separators
+                       username(specifier: name, separators: separators)
+                     else
+                       username(specifier: name)
+                     end
+
+        sanitized_local_part = sanitize_email_local_part(local_part)
+        construct_email(sanitized_local_part, domain_name(domain: domain))
       end
 
       def free_email(legacy_name = NOT_GIVEN, name: nil)
@@ -21,7 +24,10 @@ module Faker
           keywords << :name if legacy_name != NOT_GIVEN
         end
 
-        [username(specifier: name), fetch('internet.free_email')].join('@')
+        construct_email(
+          sanitize_email_local_part(username(specifier: name)),
+          fetch('internet.free_email')
+        )
       end
 
       def safe_email(legacy_name = NOT_GIVEN, name: nil)
@@ -29,7 +35,10 @@ module Faker
           keywords << :name if legacy_name != NOT_GIVEN
         end
 
-        [username(specifier: name), 'example.' + sample(%w[org com net])].join('@')
+        construct_email(
+          sanitize_email_local_part(username(specifier: name)),
+          'example.' + sample(%w[org com net])
+        )
       end
 
       def username(legacy_specifier = NOT_GIVEN, legacy_separators = NOT_GIVEN, specifier: nil, separators: %w[. _])
@@ -325,6 +334,25 @@ module Faker
       end
 
       alias user_name username
+
+      private
+
+      def sanitize_email_local_part(local_part)
+        char_range = [
+          Array('0'..'9'),
+          Array('A'..'Z'),
+          Array('a'..'z'),
+          "!#$%&'*+-/=?^_`{|}~.".split(//)
+        ].flatten
+
+        local_part.split(//).map do |char|
+          char_range.include?(char) ? char : '#'
+        end.join
+      end
+
+      def construct_email(local_part, domain_name)
+        [local_part, domain_name].join('@')
+      end
     end
   end
 end