faker 2.12.0 → 2.13.0

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

data/lib/faker/default/internet_http.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Faker
+  class Internet
+    class HTTP < Base
+      STATUS_CODES = {
+        information: [100, 101, 102, 103],
+        successful: [200, 201, 202, 203, 204, 205, 206, 207, 208, 226],
+        redirect: [300, 301, 302, 303, 304, 305, 306, 307, 308],
+        client_error: [400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412,
+                       413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428,
+                       429, 431, 451],
+        server_error: [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511]
+      }.freeze
+
+      STATUS_CODES_GROUPS = STATUS_CODES.keys.freeze
+
+      class << self
+        ##
+        # Produces an HTTP status code
+        #
+        # @return [Integer]
+        #
+        # @example
+        #   Faker::Internet::HTTP.status_code #=> 418
+        # @example
+        #   Faker::Internet::HTTP.status_code(group: :information) #=> 102
+        # @example
+        #   Faker::Internet::HTTP.status_code(group: :successful) #=> 200
+        # @example
+        #   Faker::Internet::HTTP.status_code(group: :redirect) #=> 306
+        # @example
+        #   Faker::Internet::HTTP.status_code(group: :client_error) #=> 451
+        # @example
+        #   Faker::Internet::HTTP.status_code(group: :server_error) #=> 502
+        #
+        # @faker.version 2.13.0
+        def status_code(group: nil)
+          return STATUS_CODES[STATUS_CODES_GROUPS.sample].sample unless group
+
+          raise ArgumentError, 'Invalid HTTP status code group' unless STATUS_CODES_GROUPS.include?(group)
+
+          STATUS_CODES[group].sample
+        end
+      end
+    end
+  end
+end

data/lib/faker/default/lorem_flickr.rb

@@ -5,6 +5,22 @@ module Faker
     class << self
       SUPPORTED_COLORIZATIONS = %w[red green blue].freeze
 
+      ##
+      # Produces a random image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.image #=> "https://loremflickr.com/300/300"
+      #   Faker::LoremFlickr.image(size: "50x60") #=> "https://loremflickr.com/50/60"
+      #   Faker::LoremFlickr.image(size: "50x60", search_terms: ['sports']) #=> "https://loremflickr.com/50/60/sports"
+      #   Faker::LoremFlickr.image(size: "50x60", search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/50/60/sports,fitness"
+      #   Faker::LoremFlickr.image(size: "50x60", search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/50/60/sports,fitness/all"
+      #
+      # @faker.version 1.9.0
       # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: [], match_all: false)
         # rubocop:enable Metrics/ParameterLists
@@ -17,6 +33,22 @@ module Faker
         build_url(size, nil, search_terms, match_all)
       end
 
+      ##
+      # Produces a random grayscale image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.grayscale_image #=> "https://loremflickr.com/g/300/300/all"
+      #   Faker::LoremFlickr.grayscale_image(size: "50x60") #=> "https://loremflickr.com/g/50/60/all"
+      #   Faker::LoremFlickr.grayscale_image(size: "50x60", search_terms: ['sports']) #=> "https://loremflickr.com/g/50/60/sports"
+      #   Faker::LoremFlickr.grayscale_image(size: "50x60", search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/50/60/g/sports,fitness"
+      #   Faker::LoremFlickr.grayscale_image(size: "50x60", search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/g/50/60/sports,fitness/all"
+      #
+      # @faker.version 1.9.0
       # rubocop:disable Metrics/ParameterLists
       def grayscale_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
         # rubocop:enable Metrics/ParameterLists
@@ -31,6 +63,22 @@ module Faker
         build_url(size, 'g', search_terms, match_all)
       end
 
+      ##
+      # Produces a random pixelated image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.pixelated_image #=> "https://loremflickr.com/p/300/300/all"
+      #   Faker::LoremFlickr.pixelated_image(size: "50x60") #=> "https://loremflickr.com/p/50/60/all"
+      #   Faker::LoremFlickr.pixelated_image(size: "50x60", search_terms: ['sports']) #=> "https://loremflickr.com/p/50/60/sports"
+      #   Faker::LoremFlickr.pixelated_image(size: "50x60", search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/p/50/60/sports,fitness"
+      #   Faker::LoremFlickr.pixelated_image(size: "50x60", search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/p/50/60/sports,fitness/all"
+      #
+      # @faker.version 1.9.0
       # rubocop:disable Metrics/ParameterLists
       def pixelated_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
         # rubocop:enable Metrics/ParameterLists
@@ -45,6 +93,23 @@ module Faker
         build_url(size, 'p', search_terms, match_all)
       end
 
+      ##
+      # Produces a random colorized image URL from loremflickr.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param color [String] Specifies the color of image to generate.
+      # @param search_terms [Array<String>] Adds search terms to the image URL.
+      # @param match_all [Boolean] Add "all" as part of the URL.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremFlickr.image #=> "https://loremflickr.com/red/300/300/all"
+      #   Faker::LoremFlickr.image(size: "50x60", color: 'blue') #=> "https://loremflickr.com/blue/50/60/all"
+      #   Faker::LoremFlickr.image(size: "50x60", color: 'blue', search_terms: ['sports']) #=> "https://loremflickr.com/blue/50/60/sports"
+      #   Faker::LoremFlickr.image(size: "50x60", color: 'blue', search_terms: ['sports', 'fitness']) #=> "https://loremflickr.com/blue/50/60/sports,fitness"
+      #   Faker::LoremFlickr.image(size: "50x60", color: 'blue', search_terms: ['sports', 'fitness'], match_all: true) #=> "https://loremflickr.com/blue/50/60/sports,fitness/all"
+      #
+      # @faker.version 1.9.0
       # rubocop:disable Metrics/ParameterLists
       def colorized_image(legacy_size = NOT_GIVEN, legacy_color = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', color: 'red', search_terms: ['all'], match_all: false)
         # rubocop:enable Metrics/ParameterLists

data/lib/faker/default/lorem_pixel.rb

@@ -17,6 +17,28 @@ module Faker
                                 technics
                                 transport].freeze
 
+      ##
+      # Produces a random image URL from lorempixel.com.
+      #
+      # @param size [String] Specifies the size of image to generate.
+      # @param is_gray [Boolean] Determines if the image is gray.
+      # @param category [Symbol] Adds the category of the generated image to the URL.
+      # @param number [Integer] Adds a number as part of the URL.
+      # @param text [Integer] Adds dummy text as part of the URL.
+      # @param secure [Boolean] Changes the image URL between http and https.
+      # @return [String]
+      #
+      # @example
+      #   Faker::LoremPixel.image #=> "https://lorempixel.com/300/300"
+      #   Faker::LoremPixel.image(size: "50x60") #=> "https://lorempixel.com/50/60"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: true) #=> "https://lorempixel.com/g/50/60"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports') #=> "https://lorempixel.com/50/60/sports"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports', number: 3) #=> "https://lorempixel.com/50/60/sports/3"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports', number: 3, text: 'Dummy-text') #=> "https://lorempixel.com/50/60/sports/3/Dummy-text"
+      #   Faker::LoremPixel.image(size: "50x60", is_gray: false, category: 'sports', number: nil, text: 'Dummy-text') #=> "https://lorempixel.com/50/60/sports/Dummy-text"
+      #   Faker::LoremPixel.image(secure: false) #=> "http://lorempixel.com/300/300"
+      #
+      # @faker.version 1.7.0
       # rubocop:disable Metrics/ParameterLists
       def image(legacy_size = NOT_GIVEN, legacy_is_gray = NOT_GIVEN, legacy_category = NOT_GIVEN, legacy_number = NOT_GIVEN, legacy_text = NOT_GIVEN, legacy_secure = NOT_GIVEN, size: '300x300', is_gray: false, category: nil, number: nil, text: nil, secure: true)
         warn_for_deprecated_arguments do |keywords|

data/lib/faker/default/markdown.rb

@@ -3,10 +3,28 @@
 module Faker
   class Markdown < Base
     class << self
+      ##
+      # Produces a random header format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.headers #=> "##### Autem"
+      #
+      # @faker.version 1.8.0
       def headers
         "#{fetch('markdown.headers')} #{Lorem.word.capitalize}"
       end
 
+      ##
+      # Produces a random emphasis formatting on a random word in two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.emphasis #=> "_Incidunt atque quis repellat id impedit.  Quas numquam quod incidunt dicta non. Blanditiis delectus laudantium atque reiciendis qui._"
+      #
+      # @faker.version 1.8.0
       def emphasis
         paragraph = Faker::Lorem.paragraph(sentence_count: 3)
         words = paragraph.split(' ')
@@ -16,6 +34,15 @@ module Faker
         words.join(' ')
       end
 
+      ##
+      # Produces a random ordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.ordered_list #=> "1. Qui reiciendis non consequatur atque.\n2. Quo doloremque veritatis tempora aut.\n3. Aspernatur.\n4. Ea ab.\n5. Qui.\n6. Sit pariatur nemo eveniet.\n7. Molestiae aut.\n8. Nihil molestias iure placeat.\n9. Dolore autem quisquam."
+      #
+      # @faker.version 1.8.0
       def ordered_list
         number = rand(1..10)
 
@@ -26,6 +53,15 @@ module Faker
         result.join('')
       end
 
+      ##
+      # Produces a random unordered list of items between 1 and 10 randomly.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.unordered_list #=> "* Voluptatum aliquid tempora molestiae facilis non sed.\n* Nostrum omnis iste impedit voluptatum dolor.\n* Esse quidem et facere."
+      #
+      # @faker.version 1.8.0
       def unordered_list
         number = rand(1..10)
 
@@ -36,14 +72,41 @@ module Faker
         result.join('')
       end
 
+      ##
+      # Produces a random inline code snippet between two sentences.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.inline_code #=> "Aut eos quis suscipit. `Dignissimos voluptatem expedita qui.` Quo doloremque veritatis tempora aut."
+      #
+      # @faker.version 1.8.0
       def inline_code
         "`#{Faker::Lorem.sentence(word_count: 1)}`"
       end
 
+      ##
+      # Produces a random code block formatted in Ruby.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.block_code #=> "```ruby\nEos quasi qui.\n```"
+      #
+      # @faker.version 1.8.0
       def block_code
         "```ruby\n#{Lorem.sentence(word_count: 1)}\n```"
       end
 
+      ##
+      # Produces a random 3x4 table with a row of headings, a row of hyphens and two rows of data
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.table #=> "ad | similique | voluptatem\n---- | ---- | ----\ncorrupti | est | rerum\nmolestiae | quidem | et"
+      #
+      # @faker.version 1.8.0
       def table
         table = []
         3.times do
@@ -53,12 +116,38 @@ module Faker
         table.join("\n")
       end
 
+      ##
+      # Produces a random method from the methods above or the methods listed in the arguments.
+      #
+      # @param methods [Symbol] Specify which methods to use.
+      # @return [String, Array<String>]
+      #
+      # @example
+      #   Faker::Markdown.random #=> returns output from a single method outlined above
+      #   Faker::Markdown.random("table") #=> returns output from any single method outlined above except for "table"
+      #   Faker::Markdown.random("ordered_list", "unordered_list") #=> returns output from any single method outlined above except for either ordered_list and unordered_list
+      #
+      # @faker.version 1.8.0
       def random(*args)
         method_list = available_methods
         args&.each { |ex| method_list.delete_if { |meth| meth == ex.to_sym } }
         send(method_list[rand(0..method_list.length - 1)])
       end
 
+      ##
+      # Produces a simulated blog-esque text-heavy block in markdown
+      #
+      # Keyword arguments: sentences, repeat
+      # @param sentences [Integer] Specifies how many sentences make a text block.
+      # @param repeat [Integer] Specifies how many times the text block repeats.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Markdown.sandwich #=> returns newline separated content of 1 header, 1 default lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 5) #=> returns newline separated content of 1 header, 1 5-sentence lorem paragraph, and 1 random markdown element
+      #   Faker::Markdown.sandwich(sentences: 6, repeat: 3) #=> returns newline separated content of 1 header, and then 3 sections consisting of, here, 1 6-sentence lorem paragraph and 1 random markdown element. The random markdown element is chosen at random in each iteration of the paragraph-markdown pairing.
+      #
+      # @faker.version 1.8.0
       def sandwich(legacy_sentences = NOT_GIVEN, legacy_repeat = NOT_GIVEN, sentences: 3, repeat: 1)
         warn_for_deprecated_arguments do |keywords|
           keywords << :sentences if legacy_sentences != NOT_GIVEN

data/lib/faker/default/name.rb

@@ -78,6 +78,21 @@ module Faker
       alias first_name_women female_first_name
       alias feminine_name female_first_name
 
+      ##
+      # Produces a random gender neutral first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.neutral_first_name #=> "Casey"
+      #
+      # @faker.version 2.13.0
+      def neutral_first_name
+        fetch('name.neutral_first_name')
+      end
+      alias first_name_neutral neutral_first_name
+      alias gender_neutral_first_name neutral_first_name
+
       ##
       # Produces a random last name.
       #

data/lib/faker/default/nhs.rb

@@ -3,6 +3,15 @@
 module Faker
   class NationalHealthService < Base
     class << self
+      ##
+      # Produces a random British NHS number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::NationalHealthService.british_number #=> "403 958 5577"
+      #
+      # @faker.version 1.9.2
       def british_number
         base_number = rand(400_000_001...499_999_999)
         # If the check digit is equivalent to 10, the number is invalid.
@@ -15,6 +24,16 @@ module Faker
                                                            .join('')
       end
 
+      ##
+      # Produces a random British NHS number's check digit.
+      #
+      # @param number [Integer] Specifies the NHS number the check digit belongs to.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::NationalHealthService.check_digit(number: 400_012_114) #=> 6
+      #
+      # @faker.version 1.9.2
       def check_digit(legacy_number = NOT_GIVEN, number: 0)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN

data/lib/faker/default/number.rb

@@ -85,13 +85,11 @@ module Faker
         end
 
         l_d = number(digits: l_digits)
-        r_d = if r_digits == 1
-                generate(r_digits)
-              else
-                # Ensure the last digit is not zero
-                # so it does not get truncated on converting to float
-                generate(r_digits - 1).join + non_zero_digit.to_s
-              end
+
+        # Ensure the last digit is not zero
+        # so it does not get truncated on converting to float
+        r_d = generate(r_digits - 1).join + non_zero_digit.to_s
+
         "#{l_d}.#{r_d}".to_f
       end