faker 1.9.6 → 2.7.0

data/lib/faker/default/name.rb

@@ -5,8 +5,6 @@ module Faker
     flexible :name
 
     class << self
-      extend Gem::Deprecate
-
       def name
         parse('name.name')
       end
@@ -48,8 +46,12 @@ module Faker
         fetch('name.suffix')
       end
 
-      def initials(character_count = 3)
-        (0...character_count).map { rand(65..90).chr }.join
+      def initials(legacy_number = NOT_GIVEN, number: 3)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+        end
+
+        (0...number).map { rand(65..90).chr }.join
       end
     end
   end

data/lib/faker/default/nation.rb

@@ -4,27 +4,70 @@ module Faker
   class Nation < Base
     flexible :nation
     class << self
-      # Fetch random nationality
+      ##
+      # Produces a random nationality.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.nationality #=> "Nepalese"
+      #
+      # @faker.version 1.9.0
       def nationality
         fetch('nation.nationality')
       end
 
-      # Fetch random national flag emoji
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Produces a random national flag emoji.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.flag #=> "🇫🇮"
+      #
+      # @faker.version 1.9.0
       def flag
         sample(translate('faker.nation.flag')).pack('C*').force_encoding('utf-8')
       end
+      # rubocop:enable Style/AsciiComments
 
-      # Fetch random language
+      ##
+      # Produces a random national language.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.language #=> "Nepali"
+      #
+      # @faker.version 1.9.0
       def language
         fetch('nation.language')
       end
 
-      # Fetch random capital city
+      ##
+      # Produces a random capital city.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.capital_city #=> "Kathmandu"
+      #
+      # @faker.version 1.9.0
       def capital_city
         fetch('nation.capital_city')
       end
 
-      # Fetch random natinal sport
+      ##
+      # Produces a random national sport.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.national_sport #=> "dandi biyo"
+      #
+      # @faker.version 1.9.0
       def national_sport
         fetch('team.sport')
       end

data/lib/faker/default/nato_phonetic_alphabet.rb

@@ -3,6 +3,15 @@
 module Faker
   class NatoPhoneticAlphabet < Base
     class << self
+      ##
+      # Produces a code word from the NATO phonetic alphabet.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::NatoPhoneticAlphabet.code_word #=> "Hotel"
+      #
+      # @faker.version 1.9.0
       def code_word
         fetch('nato_phonetic_alphabet.code_word')
       end

data/lib/faker/default/nhs.rb

@@ -7,15 +7,19 @@ module Faker
         base_number = rand(400_000_001...499_999_999)
         # If the check digit is equivalent to 10, the number is invalid.
         # See https://en.wikipedia.org/wiki/NHS_number
-        base_number -= 1 if check_digit(base_number) == 10
-        "#{base_number}#{check_digit(base_number)}".to_s
-                                                   .chars
-                                                   .insert(3, ' ')
-                                                   .insert(7, ' ')
-                                                   .join('')
+        base_number -= 1 if check_digit(number: base_number) == 10
+        "#{base_number}#{check_digit(number: base_number)}".to_s
+                                                           .chars
+                                                           .insert(3, ' ')
+                                                           .insert(7, ' ')
+                                                           .join('')
       end
 
-      def check_digit(number = 0)
+      def check_digit(legacy_number = NOT_GIVEN, number: 0)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+        end
+
         sum = 0
         number.to_s.chars.each_with_index do |digit, idx|
           position = idx + 1

data/lib/faker/default/number.rb

@@ -3,82 +3,257 @@
 module Faker
   class Number < Base
     class << self
-      extend Gem::Deprecate
-
-      def number(digits = 10)
-        num = ''
-
-        if digits > 1
-          num = non_zero_digit
-          digits -= 1
+      ##
+      # Produce a random number.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.number(digits: 10) #=> 1968353479
+      #
+      # @faker.version 1.0.0
+      def number(legacy_digits = NOT_GIVEN, digits: 10)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
         end
 
-        num + (1..digits).collect { digit }.join
+        return if digits < 1
+        return rand(0..9).round if digits == 1
+
+        # Ensure the first digit is not zero
+        ([non_zero_digit] + generate(digits - 1)).join.to_i
       end
 
-      def leading_zero_number(digits = 10)
+      ##
+      # Produce a random number with a leading zero.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.leading_zero_number(digits: 10) #=> "0669336915"
+      #
+      # @faker.version 1.0.0
+      def leading_zero_number(legacy_digits = NOT_GIVEN, digits: 10)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
+        end
+
         '0' + (2..digits).collect { digit }.join
       end
 
-      def decimal_part(digits = 10)
+      ##
+      # Produce a number with a number of digits, preserves leading zeroes.
+      #
+      # @param digits [Integer] Number of digits that the generated number should have.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.decimal_part(digits: 2) #=> "09"
+      #
+      # @faker.version 1.0.0
+      def decimal_part(legacy_digits = NOT_GIVEN, digits: 10)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
+        end
+
         num = ''
         if digits > 1
           num = non_zero_digit
           digits -= 1
         end
-        leading_zero_number(digits) + num
+        leading_zero_number(digits: digits) + num.to_s
       end
 
-      def decimal(l_digits = 5, r_digits = 2)
-        l_d = number(l_digits)
-        r_d = decimal_part(r_digits)
+      ##
+      # Produces a float.
+      #
+      # @param l_digits [Integer] Number of digits that the generated decimal should have to the left of the decimal point.
+      # @param r_digits [Integer] Number of digits that the generated decimal should have to the right of the decimal point.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.decimal(l_digits: 2) #=> 11.88
+      #   Faker::Number.decimal(l_digits: 3, r_digits: 3) #=> 181.843
+      #
+      # @faker.version 1.0.0
+      def decimal(legacy_l_digits = NOT_GIVEN, legacy_r_digits = NOT_GIVEN, l_digits: 5, r_digits: 2)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :l_digits if legacy_l_digits != NOT_GIVEN
+          keywords << :r_digits if legacy_r_digits != NOT_GIVEN
+        end
 
-        "#{l_d}.#{r_d}"
+        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
+        "#{l_d}.#{r_d}".to_f
       end
 
+      ##
+      # Produces a non-zero single-digit integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.non_zero_digit #=> 8
+      #
+      # @faker.version 1.0.0
       def non_zero_digit
-        rand(1..9).to_s
+        rand(1..9)
       end
 
+      ##
+      # Produces a single-digit integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Number.digit #=> 1
+      #
+      # @faker.version 1.0.0
       def digit
-        rand(10).to_s
+        rand(10)
       end
 
-      def hexadecimal(digits = 6)
+      ##
+      # Produces a number in hexadecimal format.
+      #
+      # @param digits [Integer] Number of digits in the he
+      # @return [String]
+      #
+      # @example
+      #   Faker::Number.hexadecimal(digits: 3) #=> "e74"
+      #
+      # @faker.version 1.0.0
+      def hexadecimal(legacy_digits = NOT_GIVEN, digits: 6)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
+        end
+
         hex = ''
         digits.times { hex += rand(15).to_s(16) }
         hex
       end
 
-      def normal(mean = 1, standard_deviation = 1)
+      ##
+      # Produces a float given a mean and standard deviation.
+      #
+      # @param mean [Integer]
+      # @param standard_deviation [Integer, Float]
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.normal(mean: 50, standard_deviation: 3.5) #=> 47.14669604069156
+      #
+      # @faker.version 1.0.0
+      def normal(legacy_mean = NOT_GIVEN, legacy_standard_deviation = NOT_GIVEN, mean: 1, standard_deviation: 1)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :mean if legacy_mean != NOT_GIVEN
+          keywords << :standard_deviation if legacy_standard_deviation != NOT_GIVEN
+        end
+
         theta = 2 * Math::PI * rand
         rho = Math.sqrt(-2 * Math.log(1 - rand))
         scale = standard_deviation * rho
         mean + scale * Math.cos(theta)
       end
 
-      def between(from = 1.00, to = 5000.00)
+      ##
+      # 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]
+      #
+      # @example
+      #   Faker::Number.between(from: 1, to: 10) #=> 7
+      #
+      # @faker.version 1.0.0
+      def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
+        end
+
         Faker::Base.rand_in_range(from, to)
       end
 
-      def within(range = 1.00..5000.00)
-        between(range.min, range.max)
+      ##
+      # 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]
+      #
+      # @example
+      #   Faker::Number.within(range: 1..10) #=> 7
+      #
+      # @faker.version 1.0.0
+      def within(legacy_range = NOT_GIVEN, range: 1.00..5000.00)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :range if legacy_range != NOT_GIVEN
+        end
+
+        between(from: range.min, to: range.max)
       end
 
-      def positive(from = 1.00, to = 5000.00)
-        random_number = between(from, to)
+      ##
+      # Produces a positive float.
+      #
+      # @param from [Integer] The lower boundary.
+      # @param to [Integer] The higher boundary.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.positive #=> 235.59238499107653
+      #
+      # @faker.version 1.0.0
+      def positive(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 1.00, to: 5000.00)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
+        end
+
+        random_number = between(from: from, to: to)
 
         greater_than_zero(random_number)
       end
 
-      def negative(from = -5000.00, to = -1.00)
-        random_number = between(from, to)
+      ##
+      # Produces a negative float.
+      #
+      # @param from [Integer] The lower boundary.
+      # @param to [Integer] The higher boundary.
+      # @return [Float]
+      #
+      # @example
+      #   Faker::Number.negative #=> -4480.042585669558
+      #
+      # @faker.version 1.0.0
+      def negative(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: -5000.00, to: -1.00)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
+        end
+
+        random_number = between(from: from, to: to)
 
         less_than_zero(random_number)
       end
 
       private
 
+      def generate(count)
+        return [] if count.zero?
+
+        Array.new(count) { digit }
+      end
+
       def greater_than_zero(number)
         should_be(number, :>)
       end
@@ -94,9 +269,6 @@ module Faker
           number * -1
         end
       end
-
-      deprecate :decimal_part, nil, 2019, 06
-      deprecate :leading_zero_number, nil, 2019, 06
     end
   end
 end

data/lib/faker/default/omniauth.rb

@@ -10,12 +10,20 @@ module Faker
 
     def initialize(name: nil, email: nil)
       @name = name || "#{Name.first_name} #{Name.last_name}"
-      @email = email || Internet.safe_email(self.name)
+      @email = email || Internet.safe_email(name: self.name)
       @first_name, @last_name = self.name.split
     end
 
     class << self
-      def google(name: nil, email: nil, uid: Number.number(9))
+      # rubocop:disable Metrics/ParameterLists
+      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
+          keywords << :uid if legacy_uid != NOT_GIVEN
+        end
+
         auth = Omniauth.new(name: name, email: email)
         {
           provider: 'google_oauth2',
@@ -27,7 +35,7 @@ module Faker
             email: auth.email,
             image: image
           },
-          credentials:  {
+          credentials: {
             token: Crypto.md5,
             refresh_token: Crypto.md5,
             expires_at: Time.forward.to_i,
@@ -35,7 +43,7 @@ module Faker
           },
           extra: {
             raw_info: {
-              sub:  uid,
+              sub: uid,
               email: auth.email,
               email_verified: random_boolean.to_s,
               name: auth.name,
@@ -44,7 +52,7 @@ module Faker
               profile: "https://plus.google.com/#{uid}",
               picture: image,
               gender: gender,
-              birthday: Date.backward(36_400).strftime('%Y-%m-%d'),
+              birthday: Date.backward(days: 36_400).strftime('%Y-%m-%d'),
               local: 'en',
               hd: "#{Company.name.downcase}.com"
             },
@@ -52,7 +60,7 @@ module Faker
               'iss' => 'accounts.google.com',
               'at_hash' => Crypto.md5,
               'email_verified' => true,
-              'sub' => Number.number(28).to_s,
+              'sub' => Number.number(digits: 28).to_s,
               'azp' => 'APP_ID',
               'email' => auth.email,
               'aud' => 'APP_ID',
@@ -64,7 +72,16 @@ module Faker
         }
       end
 
-      def facebook(name: nil, email: nil, username: nil, uid: Number.number(7))
+      # rubocop:disable Metrics/ParameterLists
+      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
+          keywords << :username if legacy_username != NOT_GIVEN
+          keywords << :uid if legacy_uid != NOT_GIVEN
+        end
+
         auth = Omniauth.new(name: name, email: email)
         username ||= "#{auth.first_name.downcase[0]}#{auth.last_name.downcase}"
         {
@@ -92,7 +109,7 @@ module Faker
               link: "http://www.facebook.com/#{username}",
               username: username,
               location: {
-                id: Number.number(9),
+                id: Number.number(digits: 9).to_s,
                 name: city_state
               },
               gender: gender,
@@ -106,7 +123,15 @@ module Faker
         }
       end
 
-      def twitter(name: nil, nickname: nil, uid: Number.number(6))
+      # rubocop:disable Metrics/ParameterLists
+      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
+          keywords << :uid if legacy_uid != NOT_GIVEN
+        end
+
         auth = Omniauth.new(name: name)
         nickname ||= auth.name.downcase.delete(' ')
         location = city_state
@@ -179,7 +204,15 @@ module Faker
         }
       end
 
-      def linkedin(name: nil, email: nil, uid: Number.number(6))
+      # rubocop:disable Metrics/ParameterLists
+      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
+          keywords << :uid if legacy_uid != NOT_GIVEN
+        end
+
         auth = Omniauth.new(name: name, email: email)
         first_name = auth.first_name.downcase
         last_name = auth.last_name.downcase
@@ -242,7 +275,15 @@ module Faker
         }
       end
 
-      def github(name: nil, email: nil, uid: Number.number(8))
+      # rubocop:disable Metrics/ParameterLists
+      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
+          keywords << :uid if legacy_uid != NOT_GIVEN
+        end
+
         auth = Omniauth.new(name: name, email: email)
         login = auth.name.downcase.tr(' ', '-')
         html_url = "https://github.com/#{login}"
@@ -261,7 +302,7 @@ module Faker
           },
           credentials: {
             token: Crypto.md5,
-            expires:  false
+            expires: false
           },
           extra: {
             raw_info: {
@@ -281,7 +322,7 @@ module Faker
               events_url: "#{api_url}/events{/privacy}",
               received_events_url: "#{api_url}/received_events",
               type: 'User',
-              site_admin:  random_boolean,
+              site_admin: random_boolean,
               name: auth.name,
               company: nil,
               blog: nil,
@@ -293,8 +334,50 @@ module Faker
               public_gists: random_number_from_range(1..1000),
               followers: random_number_from_range(1..1000),
               following: random_number_from_range(1..1000),
-              created_at: Time.backward(36_400).iso8601,
-              updated_at: Time.backward(2).iso8601
+              created_at: Time.backward(days: 36_400).iso8601,
+              updated_at: Time.backward(days: 2).iso8601
+            }
+          }
+        }
+      end
+
+      ##
+      # 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
+      #
+      # @return [Hash] An auth hash in the format provided by omniauth-apple
+      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)
+        {
+          provider: 'apple',
+          uid: uid,
+          info: {
+            sub: uid,
+            email: auth.email,
+            first_name: auth.first_name,
+            last_name: auth.last_name
+          },
+          credentials: {
+            token: Crypto.md5,
+            refresh_token: Crypto.md5,
+            expires_at: Time.forward.to_i,
+            expires: true
+          },
+          extra: {
+            raw_info: {
+              iss: 'https://appleid.apple.com',
+              aud: 'CLIENT_ID',
+              exp: Time.forward.to_i,
+              iat: Time.forward.to_i,
+              sub: uid,
+              at_hash: Crypto.md5,
+              auth_time: Time.forward.to_i,
+              email: auth.email,
+              email_verified: true
             }
           }
         }