faker 2.11.0 → 2.18.0

data/lib/faker/default/mountain.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Faker
+  class Mountain < Base
+    class << self
+      ##
+      # Produces a name of a mountain
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Mountain.name #=> "Mount Everest"
+      #
+      #  @faker.version next
+      def name
+        fetch('mountain.name')
+      end
+
+      ##
+      # Produces a name of a range
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Mountain.range #=> "Dhaulagiri Himalaya"
+      #
+      # @faker.version next
+      def range
+        fetch('mountain.range')
+      end
+    end
+  end
+end

data/lib/faker/default/name.rb

@@ -5,14 +5,41 @@ module Faker
     flexible :name
 
     class << self
+      ##
+      # Produces a random name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.name #=> "Tyshawn Johns Sr."
+      #
+      # @faker.version 0.9.0
       def name
         parse('name.name')
       end
 
+      ##
+      # Produces a random name with middle name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.name_with_middle #=> "Aditya Elton Douglas"
+      #
+      # @faker.version 1.6.4
       def name_with_middle
         parse('name.name_with_middle')
       end
 
+      ##
+      # Produces a random first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.first_name #=> "Kaci"
+      #
+      # @faker.version 0.9.0
       def first_name
         if parse('name.first_name').empty?
           fetch('name.first_name')
@@ -21,31 +48,102 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random male first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.male_first_name #=> "Edward"
+      #
+      # @faker.version 1.9.1
       def male_first_name
         fetch('name.male_first_name')
       end
       alias first_name_men male_first_name
       alias masculine_name male_first_name
 
+      ##
+      # Produces a random female first name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.female_first_name #=> "Natasha"
+      #
+      # @faker.version 1.9.1
       def female_first_name
         fetch('name.female_first_name')
       end
       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.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.last_name #=> "Ernser"
+      #
+      # @faker.version 0.9.0
       def last_name
         parse('name.last_name')
       end
       alias middle_name last_name
 
+      ##
+      # Produces a random name prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.prefix #=> "Mr."
+      #
+      # @faker.version 0.9.0
       def prefix
         fetch('name.prefix')
       end
 
+      ##
+      # Produces a random name suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.suffix #=> "IV"
+      #
+      # @faker.version 0.9.0
       def suffix
         fetch('name.suffix')
       end
 
+      ##
+      # Produces random initials.
+      #
+      # @param number [Integer] Number of digits that the generated initials should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Name.initials            #=> "NJM"
+      #   Faker::Name.initials(number: 2) #=> "NM"
+      #
+      # @faker.version 1.8.5
       def initials(legacy_number = NOT_GIVEN, number: 3)
         warn_for_deprecated_arguments do |keywords|
           keywords << :number if legacy_number != NOT_GIVEN

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

@@ -40,7 +40,7 @@ module Faker
           keywords << :digits if legacy_digits != NOT_GIVEN
         end
 
-        '0' + (2..digits).collect { digit }.join
+        "0#{(2..digits).collect { digit }.join}"
       end
 
       ##
@@ -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
 
@@ -141,11 +139,26 @@ module Faker
         hex
       end
 
+      # Produces a number in binary format.
+      #
+      # @param digits [Integer] Number of digits to generate the binary as string
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.binary(digits: 4) #=> "1001"
+      #
+      # @faker.version next
+      def binary(digits: 4)
+        bin = ''
+        digits.times { bin += rand(2).to_s(2) }
+        bin
+      end
+
       ##
       # Produces a float given a mean and standard deviation.
       #
       # @param mean [Integer]
-      # @param standard_deviation [Integer, Float]
+      # @param standard_deviation [Numeric]
       # @return [Float]
       #
       # @example
@@ -167,12 +180,13 @@ module Faker
       ##
       # Produces a number between two provided values. Boundaries are inclusive.
       #
-      # @param from [Integer] The lowest number to include.
-      # @param to [Integer] The highest number to include.
-      # @return [Integer]
+      # @param from [Numeric] The lowest number to include.
+      # @param to [Numeric] The highest number to include.
+      # @return [Numeric]
       #
       # @example
       #   Faker::Number.between(from: 1, to: 10) #=> 7
+      #   Faker::Number.between(from: 0.0, to: 1.0) #=> 0.7844640543957383
       #
       # @faker.version 1.0.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
@@ -188,10 +202,11 @@ module Faker
       # Produces a number within two provided values. Boundaries are inclusive or exclusive depending on the range passed.
       #
       # @param range [Range] The range from which to generate a number.
-      # @return [Integer]
+      # @return [Numeric]
       #
       # @example
       #   Faker::Number.within(range: 1..10) #=> 7
+      #   Faker::Number.within(range: 0.0..1.0) #=> 0.7844640543957383
       #
       # @faker.version 1.0.0
       def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00)

data/lib/faker/default/omniauth.rb

@@ -9,6 +9,8 @@ module Faker
                 :email
 
     def initialize(name: nil, email: nil)
+      super()
+
       @name = name || "#{Name.first_name} #{Name.last_name}"
       @email = email || Internet.safe_email(name: self.name)
       @first_name, @last_name = self.name.split
@@ -16,8 +18,18 @@ module Faker
 
     class << self
       # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Generate a mock Omniauth response from Google.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-google.
+      #
+      # @faker.version 1.8.0
       def google(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 9).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -72,9 +84,18 @@ module Faker
         }
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Generate a mock Omniauth response from Facebook.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param username [String] A specific username to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-facebook.
+      #
+      # @faker.version 1.8.0
       def facebook(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_username = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, username: nil, uid: Number.number(digits: 7).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -123,9 +144,17 @@ module Faker
         }
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Generate a mock Omniauth response from Twitter.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param nickname [String] A specific nickname to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-twitter.
+      #
+      # @faker.version 1.8.0
       def twitter(legacy_name = NOT_GIVEN, legacy_nickname = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, nickname: nil, uid: Number.number(digits: 6).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :nickname if legacy_nickname != NOT_GIVEN
@@ -204,9 +233,17 @@ module Faker
         }
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Generate a mock Omniauth response from LinkedIn.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-linkedin.
+      #
+      # @faker.version 1.8.0
       def linkedin(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 6).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -275,9 +312,17 @@ module Faker
         }
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Generate a mock Omniauth response from Github.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-github.
+      #
+      # @faker.version 1.8.0
       def github(legacy_name = NOT_GIVEN, legacy_email = NOT_GIVEN, legacy_uid = NOT_GIVEN, name: nil, email: nil, uid: Number.number(digits: 8).to_s)
-        # rubocop:enable Metrics/ParameterLists
         warn_for_deprecated_arguments do |keywords|
           keywords << :name if legacy_name != NOT_GIVEN
           keywords << :email if legacy_email != NOT_GIVEN
@@ -340,15 +385,18 @@ module Faker
           }
         }
       end
+      # rubocop:enable Metrics/ParameterLists
 
       ##
-      # Generate a mock Omniauth response from Apple
+      # Generate a mock Omniauth response from Apple.
+      #
+      # @param name [String] A specific name to return in the response.
+      # @param email [String] A specific email to return in the response.
+      # @param uid [String] A specific UID to return in the response.
       #
-      # @param name [String] A specific name to return in the response
-      # @param email [String] A specific email to return in the response
-      # @param uid [String] A specific UID to return in the response
+      # @return [Hash] An auth hash in the format provided by omniauth-apple.
       #
-      # @return [Hash] An auth hash in the format provided by omniauth-apple
+      # @faker.version 2.3.0
       def apple(name: nil, email: nil, uid: nil)
         uid ||= "#{Number.number(digits: 6)}.#{Number.hexadecimal(digits: 32)}.#{Number.number(digits: 4)}"
         auth = Omniauth.new(name: name, email: email)

data/lib/faker/default/phone_number.rb

@@ -3,43 +3,126 @@
 module Faker
   class PhoneNumber < Base
     class << self
+      ##
+      # Produces a random phone number in a random format (may or may not have a country code, extension and can have different dividers).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.phone_number #=> "397.693.1309 x4321"
+      #
+      # @faker.version 0.3.0
       def phone_number
         parse('phone_number.formats')
       end
 
+      ##
+      # Produces a random cell phone number in a random format (may or may not have a country code and can have different dividers).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone #=> "(186)285-7925"
+      #
+      # @faker.version 1.0.0
       def cell_phone
         parse('cell_phone.formats')
       end
 
+      ##
+      # Produces a random country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.country_code #=> "+20"
+      #
+      # @faker.version 1.9.2
       def country_code
         "+#{fetch('country_code')}"
       end
 
+      ##
+      # Produces a random phone number with country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.phone_number_with_country_code #=> "+95 1-672-173-8153"
+      #
+      # @faker.version 1.9.2
       def phone_number_with_country_code
         "#{country_code} #{phone_number}"
       end
 
+      ##
+      # Produces a random cell phone number with country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone_with_country_code #=> "+974 (190) 987-9034"
+      #
+      # @faker.version 1.9.2
       def cell_phone_with_country_code
         "#{country_code} #{cell_phone}"
       end
 
-      # US and Canada only
+      ##
+      # Produces a random phone number in e164 format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone_in_e164 #=> "+944937040625"
+      #
+      # @faker.version 1.9.2
+      def cell_phone_in_e164
+        cell_phone_with_country_code.delete('^+0-9')
+      end
+
+      ##
+      # Produces a random US or Canada-based area code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.area_code #=> "201"
+      #
+      # @faker.version 1.3.0
       def area_code
         fetch('phone_number.area_code')
       rescue I18n::MissingTranslationData
         nil
       end
 
-      # US and Canada only
+      ##
+      # Produces a random US or Canada-based exchange code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.exchange_code #=> "208"
+      #
+      # @faker.version 1.3.0
       def exchange_code
         fetch('phone_number.exchange_code')
       rescue I18n::MissingTranslationData
         nil
       end
 
-      # US and Canada only
-      # Can be used for both extensions and last four digits of phone number.
-      # Since extensions can be of variable length, this method taks a length parameter
+      ##
+      # Produces a random US or Canada-based extension / subscriber number. Can be used for both extensions and last four digits of phone number.
+      #
+      # @param length [Integer] Speficies the length of the return value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.subscriber_number #=> "3873"
+      #   Faker::PhoneNumber.subscriber_number(length: 2) #=> "39"
+      #   Faker::PhoneNumber.extension #=> "3764"
+      #
+      # @faker.version 1.3.0
       def subscriber_number(legacy_length = NOT_GIVEN, length: 4)
         warn_for_deprecated_arguments do |keywords|
           keywords << :length if legacy_length != NOT_GIVEN