faker 1.9.6 → 2.7.0

data/lib/faker/default/code.rb

@@ -12,26 +12,39 @@ module Faker
 
       # By default generates 10 sign isbn code in format 123456789-X
       # You can pass 13 to generate new 13 sign code
-      def isbn(base = 10)
+      def isbn(legacy_base = NOT_GIVEN, base: 10)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :base if legacy_base != NOT_GIVEN
+        end
+
         base == 13 ? generate_base13_isbn : generate_base10_isbn
       end
 
       # By default generates 13 sign ean code in format 1234567890123
       # You can pass 8 to generate ean8 code
-      def ean(base = 13)
+      def ean(legacy_base = NOT_GIVEN, base: 13)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :base if legacy_base != NOT_GIVEN
+        end
+
         base == 8 ? generate_base8_ean : generate_base13_ean
       end
 
       def rut
-        value = Number.number(8)
+        value = Number.number(digits: 8).to_s
         vd = rut_verificator_digit(value)
         value << "-#{vd}"
       end
 
       # By default generates a Singaporean NRIC ID for someone
       # who is born between the age of 18 and 65.
-      def nric(min_age = 18, max_age = 65)
-        birthyear = Date.birthday(min_age, max_age).year
+      def nric(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :min_age if legacy_min_age != NOT_GIVEN
+          keywords << :max_age if legacy_max_age != NOT_GIVEN
+        end
+
+        birthyear = Date.birthday(min_age: min_age, max_age: max_age).year
         prefix = birthyear < 2000 ? 'S' : 'T'
         values = birthyear.to_s[-2..-1]
         values << regexify(/\d{5}/)

data/lib/faker/default/commerce.rb

@@ -7,15 +7,24 @@ module Faker
         fetch('color.name')
       end
 
-      def promotion_code(digits = 6)
+      def promotion_code(legacy_digits = NOT_GIVEN, digits: 6)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :digits if legacy_digits != NOT_GIVEN
+        end
+
         [
           fetch('commerce.promotion_code.adjective'),
           fetch('commerce.promotion_code.noun'),
-          Faker::Number.number(digits)
+          Faker::Number.number(digits: digits)
         ].join
       end
 
-      def department(max = 3, fixed_amount = false)
+      def department(legacy_max = NOT_GIVEN, legacy_fixed_amount = NOT_GIVEN, max: 3, fixed_amount: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :max if legacy_max != NOT_GIVEN
+          keywords << :fixed_amount if legacy_fixed_amount != NOT_GIVEN
+        end
+
         num = max if fixed_amount
         num ||= 1 + rand(max)
 
@@ -34,7 +43,12 @@ module Faker
         fetch('commerce.product_name.material')
       end
 
-      def price(range = 0..100.0, as_string = false)
+      def price(legacy_range = NOT_GIVEN, legacy_as_string = NOT_GIVEN, range: 0..100.0, as_string: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :range if legacy_range != NOT_GIVEN
+          keywords << :as_string if legacy_as_string != NOT_GIVEN
+        end
+
         price = (rand(range) * 100).floor / 100.0
         if as_string
           price_parts = price.to_s.split('.')

data/lib/faker/default/company.rb

@@ -126,7 +126,11 @@ module Faker
       end
 
       # Get a random Polish register of national economy number. More info https://pl.wikipedia.org/wiki/REGON
-      def polish_register_of_national_economy(length = 9)
+      def polish_register_of_national_economy(legacy_length = NOT_GIVEN, length: 9)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :length if legacy_length != NOT_GIVEN
+        end
+
         raise ArgumentError, 'Length should be 9 or 14' unless [9, 14].include? length
 
         random_digits = []
@@ -153,7 +157,11 @@ module Faker
         regexify(/IT\d{2,4}\/\d{2,10}/)
       end
 
-      def brazilian_company_number(formatted: false)
+      def brazilian_company_number(legacy_formatted = NOT_GIVEN, formatted: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :formatted if legacy_formatted != NOT_GIVEN
+        end
+
         digits = Array.new(8) { Faker::Number.digit.to_i } + [0, 0, 0, Faker::Number.non_zero_digit.to_i]
 
         factors = [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2, 6].cycle
@@ -198,7 +206,7 @@ module Faker
       def luhn_algorithm(number)
         multiplications = []
 
-        number.reverse.split(//).each_with_index do |digit, i|
+        number.to_s.reverse.split(//).each_with_index do |digit, i|
           multiplications << if i.even?
                                digit.to_i * 2
                              else

data/lib/faker/default/crypto_coin.rb

@@ -7,15 +7,27 @@ module Faker
       ACRONYM = 1
       URL_LOGO = 2
 
-      def coin_name(coin = coin_array)
+      def coin_name(legacy_coin = NOT_GIVEN, coin: coin_array)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :coin if legacy_coin != NOT_GIVEN
+        end
+
         coin[COIN_NAME]
       end
 
-      def acronym(coin = coin_array)
+      def acronym(legacy_coin = NOT_GIVEN, coin: coin_array)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :coin if legacy_coin != NOT_GIVEN
+        end
+
         coin[ACRONYM]
       end
 
-      def url_logo(coin = coin_array)
+      def url_logo(legacy_coin = NOT_GIVEN, coin: coin_array)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :coin if legacy_coin != NOT_GIVEN
+        end
+
         coin[URL_LOGO]
       end
 
@@ -25,7 +37,12 @@ module Faker
 
       def coin_hash
         coin = coin_array
-        { name: coin_name(coin), acronym: acronym(coin), url_logo: url_logo(coin) }
+
+        {
+          name: coin_name(coin: coin),
+          acronym: acronym(coin: coin),
+          url_logo: url_logo(coin: coin)
+        }
       end
     end
   end

data/lib/faker/default/date.rb

@@ -3,45 +3,158 @@
 module Faker
   class Date < Base
     class << self
-      def between(from, to)
+      ##
+      # Produce a random date between two dates.
+      #
+      # @param from [Date] The start of the usable date range.
+      # @param to [Date] The end of the usable date range.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.between(from: 2.days.ago, to: Date.today)
+      #     #=> #<Date: 2014-09-24>
+      #
+      # @faker.version 1.0.0
+      def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from:, to:)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
+        end
+
         from = get_date_object(from)
         to   = get_date_object(to)
 
         Faker::Base.rand_in_range(from, to)
       end
 
-      def between_except(from, to, excepted)
+      # rubocop:disable Metrics/ParameterLists
+
+      ##
+      # Produce a random date between two dates.
+      #
+      # @param from [Date] The start of the usable date range.
+      # @param to [Date] The end of the usable date range.
+      # @param excepted [Date] A date to exclude.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.between_except(from: 1.year.ago, to: 1.year.from_now, excepted: Date.today)
+      #     #=> #<Date: 2014-10-03>
+      #
+      # @faker.version 1.6.2
+      def between_except(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_excepted = NOT_GIVEN, from:, to:, excepted:)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+        end
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :to if legacy_to != NOT_GIVEN
+        end
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :excepted if legacy_excepted != NOT_GIVEN
+        end
+
         raise ArgumentError, 'From date, to date and excepted date must not be the same' if from == to && to == excepted
 
         excepted = get_date_object(excepted)
 
         loop do
-          date = between(from, to)
+          date = between(from: from, to: to)
           break date.to_date if date != excepted
         end
       end
+      # rubocop:enable Metrics/ParameterLists
+
+      ##
+      # Produce a random date in the future (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the future.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.forward(days: 23) #=> #<Date: 2014-10-03>
+      #
+      # @faker.version 1.0.0
+      def forward(legacy_days = NOT_GIVEN, days: 365)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :days if legacy_days != NOT_GIVEN
+        end
 
-      def forward(days = 365)
         from = ::Date.today + 1
         to   = ::Date.today + days
 
-        between(from, to).to_date
+        between(from: from, to: to).to_date
       end
 
-      def backward(days = 365)
+      ##
+      # Produce a random date in the past (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the past.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.backward(days: 14) #=> #<Date: 2019-09-12>
+      #
+      # @faker.version 1.0.0
+      def backward(legacy_days = NOT_GIVEN, days: 365)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :days if legacy_days != NOT_GIVEN
+        end
+
         from = ::Date.today - days
         to   = ::Date.today - 1
 
-        between(from, to).to_date
+        between(from: from, to: to).to_date
       end
 
-      def birthday(min_age = 18, max_age = 65)
+      ##
+      # Produce a random date in the past (up to N days).
+      #
+      # @param min_age [Integer] The minimum age that the birthday would imply.
+      # @param max_age [Integer] The maximum age that the birthday would imply.
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.birthday(min_age: 18, max_age: 65) #=> #<Date: 1986-03-28>
+      #
+      # @faker.version 1.4.3
+      def birthday(legacy_min_age = NOT_GIVEN, legacy_max_age = NOT_GIVEN, min_age: 18, max_age: 65)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :min_age if legacy_min_age != NOT_GIVEN
+        end
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :max_age if legacy_max_age != NOT_GIVEN
+        end
+
         t = ::Date.today
 
         from = birthday_date(t, max_age)
         to   = birthday_date(t, min_age)
 
-        between(from, to).to_date
+        between(from: from, to: to).to_date
+      end
+
+      ##
+      # Produces a date in the year and/or month specified.
+      #
+      # @param month [Integer] represents the month of the date
+      # @param year [Integer] represents the year of the date
+      # @return [Date]
+      #
+      # @example
+      #   Faker::Date.in_date_period #=> #<Date: 2019-09-01>
+      #
+      # @example
+      #   Faker::Date.in_date_period(year: 2018, month: 2) #=> #<Date: 2018-02-26>
+      #
+      # @example
+      #   Faker::Date.in_date_period(month: 2) #=> #<Date: 2019-02-26>
+      #
+      # @faker.version next
+      def in_date_period(month: nil, year: ::Date.today.year)
+        from = ::Date.new(year, month || 1, 1)
+        to = ::Date.new(year, month || 12, ::Date.civil(year, month || 12, -1).day)
+
+        between(from: from, to: to).to_date
       end
 
       private

data/lib/faker/default/demographic.rb

@@ -23,7 +23,11 @@ module Faker
         fetch('demographic.sex')
       end
 
-      def height(unit = :metric)
+      def height(legacy_unit = NOT_GIVEN, unit: :metric)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :unit if legacy_unit != NOT_GIVEN
+        end
+
         case unit
         when :imperial
           inches = rand_in_range(57, 86)

data/lib/faker/default/dessert.rb

@@ -5,14 +5,41 @@ module Faker
     flexible :dessert
 
     class << self
+      ##
+      # Produces the name of a dessert variety.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Dessert.variety #=> "Cake"
+      #
+      # @faker.version 1.8.0
       def variety
         fetch('dessert.variety')
       end
 
+      ##
+      # Produces the name of a dessert topping.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Dessert.topping #=> "Gummy Bears"
+      #
+      # @faker.version 1.8.0
       def topping
         fetch('dessert.topping')
       end
 
+      ##
+      # Produces the name of a dessert flavor.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Dessert.flavor #=> "Salted Caramel"
+      #
+      # @faker.version 1.8.0
       def flavor
         fetch('dessert.flavor')
       end

data/lib/faker/default/device.rb

@@ -3,28 +3,82 @@
 module Faker
   class Device < Base
     class << self
+      ##
+      # Produces a build number between 1 and 500.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Device.build_number #=> 5
+      #
+      # @faker.version 1.9.0
       def build_number
-        Faker::Number.between(1, 500)
+        Faker::Number.between(from: 1, to: 500)
       end
 
+      ##
+      # Produces the name of a manufacturer for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.manufacturer #=> "Apple"
+      #
+      # @faker.version 1.9.0
       def manufacturer
         fetch('device.manufacturer')
       end
 
+      ##
+      # Produces a model name for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.model_name #=> "iPhone 4"
+      #
+      # @faker.version 1.9.0
       def model_name
         fetch('device.model_name')
       end
 
+      ##
+      # Produces the name of a platform for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.platform #=> "webOS"
+      #
+      # @faker.version 1.9.0
       def platform
         fetch('device.platform')
       end
 
+      ##
+      # Produces a serial code for a device.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Device.serial #=> "ejfjnRNInxh0363JC2WM"
+      #
+      # @faker.version 1.9.0
       def serial
         fetch('device.serial')
       end
 
+      ##
+      # Produces a version number between 1 and 1000.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Device.version #=> 42
+      #
+      # @faker.version 1.9.0
       def version
-        Faker::Number.between(1, 1000)
+        Faker::Number.between(from: 1, to: 1000)
       end
     end
   end