faker 2.2.0 → 2.5.0

data/lib/faker/default/string.rb

@@ -4,9 +4,8 @@ module Faker
   class String < Base
     class << self
       def random(legacy_length = NOT_GIVEN, length: 32)
-        if legacy_length != NOT_GIVEN
-          warn_with_uplevel 'Passing `length` with the 1st argument of `String.random` is deprecated. Use keyword argument like `String.random(length: ...)` instead.', uplevel: 1
-          length = legacy_length
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :length if legacy_length != NOT_GIVEN
         end
 
         utf8string select_a length

data/lib/faker/default/stripe.rb

@@ -4,9 +4,8 @@ module Faker
   class Stripe < Base
     class << self
       def valid_card(legacy_card_type = NOT_GIVEN, card_type: nil)
-        if legacy_card_type != NOT_GIVEN
-          warn_with_uplevel 'Passing `card_type` with the 1st argument of `Stripe.valid_card` is deprecated. Use keyword argument like `Stripe.valid_card(card_type: ...)` instead.', uplevel: 1
-          card_type = legacy_card_type
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :card_type if legacy_card_type != NOT_GIVEN
         end
 
         valid_cards = translate('faker.stripe.valid_cards').keys
@@ -24,9 +23,8 @@ module Faker
       end
 
       def valid_token(legacy_card_type = NOT_GIVEN, card_type: nil)
-        if legacy_card_type != NOT_GIVEN
-          warn_with_uplevel 'Passing `card_type` with the 1st argument of `Stripe.valid_token` is deprecated. Use keyword argument like `Stripe.valid_token(card_type: ...)` instead.', uplevel: 1
-          card_type = legacy_card_type
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :card_type if legacy_card_type != NOT_GIVEN
         end
 
         valid_tokens = translate('faker.stripe.valid_tokens').keys
@@ -44,9 +42,8 @@ module Faker
       end
 
       def invalid_card(legacy_card_error = NOT_GIVEN, card_error: nil)
-        if legacy_card_error != NOT_GIVEN
-          warn_with_uplevel 'Passing `card_error` with the 1st argument of `Stripe.invalid_card` is deprecated. Use keyword argument like `Stripe.invalid_card(card_error: ...)` instead.', uplevel: 1
-          card_error = legacy_card_error
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :card_error if legacy_card_error != NOT_GIVEN
         end
 
         invalid_cards = translate('faker.stripe.invalid_cards').keys
@@ -73,9 +70,8 @@ module Faker
       end
 
       def ccv(legacy_card_type = NOT_GIVEN, card_type: nil)
-        if legacy_card_type != NOT_GIVEN
-          warn_with_uplevel 'Passing `card_type` with the 1st argument of `Stripe.ccv` is deprecated. Use keyword argument like `Stripe.ccv(card_type: ...)` instead.', uplevel: 1
-          card_type = legacy_card_type
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :card_type if legacy_card_type != NOT_GIVEN
         end
 
         (card_type.to_s == 'amex' ? rand_in_range(1000, 9999) : rand_in_range(100, 999)).to_s

data/lib/faker/default/subscription.rb

@@ -2,22 +2,67 @@
 
 module Faker
   class Subscription < Base
+    ##
+    # Produces the name of a subscription plan.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Subscription.plan #=> "Platinum"
+    #
+    # @faker.version 1.9.2
     def self.plan
       fetch('subscription.plans')
     end
 
+    ##
+    # Produces a subscription status.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Subscription.status #=> "Active"
+    #
+    # @faker.version 1.9.2
     def self.status
       fetch('subscription.statuses')
     end
 
+    ##
+    # Produces the name of a payment method.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Subscription.payment_method #=> "PayPal"
+    #
+    # @faker.version 1.9.2
     def self.payment_method
       fetch('subscription.payment_methods')
     end
 
+    ##
+    # Produces the name of a subscription term.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Subscription.subscription_term #=> "Annual"
+    #
+    # @faker.version 1.9.2
     def self.subscription_term
       fetch('subscription.subscription_terms')
     end
 
+    ##
+    # Produces the name of a payment term.
+    #
+    # @return [String]
+    #
+    # @example
+    #   Faker::Subscription.payment_term #=> "Monthly"
+    #
+    # @faker.version 1.9.2
     def self.payment_term
       fetch('subscription.payment_terms')
     end

data/lib/faker/default/superhero.rb

@@ -3,22 +3,67 @@
 module Faker
   class Superhero < Base
     class << self
+      ##
+      # Produces a superpower.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Superhero.power #=> "Photokinesis"
+      #
+      # @faker.version 1.6.2
       def power
         fetch('superhero.power')
       end
 
+      ##
+      # Produces a superhero name prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Superhero.prefix #=> "the Fated"
+      #
+      # @faker.version 1.6.2
       def prefix
         fetch('superhero.prefix')
       end
 
+      ##
+      # Produces a superhero name suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Superhero.suffix #=> "Captain"
+      #
+      # @faker.version 1.6.2
       def suffix
         fetch('superhero.suffix')
       end
 
+      ##
+      # Produces a superhero descriptor.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Superhero.descriptor #=> "Bizarro"
+      #
+      # @faker.version 1.6.2
       def descriptor
         fetch('superhero.descriptor')
       end
 
+      ##
+      # Produces a random superhero name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Superhero.name #=> "Magnificent Shatterstar"
+      #
+      # @faker.version 1.6.2
       def name
         parse('superhero.name')
       end

data/lib/faker/default/time.rb

@@ -14,19 +14,35 @@ module Faker
 
     class << self
       # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Produce a random time between two times.
+      #
+      # @param from [Time, Date, DateTime] The start of the usable time range.
+      # @param to [Time, Date, DateTime] The end of the usable time range.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   # Random Stringified time between two times, formatted to the specified I18n format
+      #   # (Examples are from a Rails console with rails-i18n 5.1.1 defaults loaded)
+      #   I18n.locale = 'en-US'
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "Tue, 16 Oct 2018 10:48:27 AM -05:00"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "15 Oct 10:48 AM"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "October 15, 2018 10:48 AM"
+      #
+      #   I18n.locale = 'ja'
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :default) #=> "2018/10/15 10:48:27"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :short) #=> "18/10/15 10:48"
+      #   Faker::Time.between(from: DateTime.now - 1, to: DateTime.now, format: :long) #=> "2018年10月16日(火) 10時48分27秒 -0500"
+      #
+      # @faker.version 1.5.0
       def between(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, format: nil)
-        # rubocop:enable Metrics/ParameterLists
-        if legacy_from != NOT_GIVEN
-          warn_with_uplevel 'Passing `from` with the 1st argument of `Time.between` is deprecated. Use keyword argument like `Time.between(from: ...)` instead.', uplevel: 1
-          from = legacy_from
-        end
-        if legacy_to != NOT_GIVEN
-          warn_with_uplevel 'Passing `to` with the 2nd argument of `Time.between` is deprecated. Use keyword argument like `Time.between(to: ...)` instead.', uplevel: 1
-          to = legacy_to
-        end
-        if legacy_format != NOT_GIVEN
-          warn_with_uplevel 'Passing `format` with the 3rd argument of `Time.between` is deprecated. Use keyword argument like `Time.between(format: ...)` instead.', uplevel: 1
-          format = legacy_format
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
+          keywords << :format if legacy_format != NOT_GIVEN
         end
 
         from = get_time_object(from)
@@ -35,25 +51,42 @@ module Faker
         time = Faker::Base.rand_in_range(from, to)
         time_with_format(time, format)
       end
-
-      # rubocop:disable Metrics/ParameterLists
+      # rubocop:enable Style/AsciiComments
+
+      ##
+      # Produce a random time between two dates.
+      #
+      # @param from [Date] The start of the usable time range.
+      # @param to [Date] The end of the usable time range.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :all)
+      #     #=> "2014-09-19 07:03:30 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :day)
+      #     #=> "2014-09-18 16:28:13 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :night)
+      #     #=> "2014-09-20 19:39:38 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :morning)
+      #     #=> "2014-09-19 08:07:52 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :afternoon)
+      #     #=> "2014-09-18 12:10:34 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :evening)
+      #     #=> "2014-09-19 20:21:03 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 1, to: Date.today, period: :midnight)
+      #     #=> "2014-09-20 00:40:14 -0700"
+      #   Faker::Time.between_dates(from: Date.today - 5, to: Date.today + 5, period: :afternoon, format: :default)
+      #     #=> "Fri, 19 Oct 2018 15:17:46 -0500"
+      #
+      # @faker.version 1.0.0
       def between_dates(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, from:, to:, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
-        if legacy_from != NOT_GIVEN
-          warn_with_uplevel 'Passing `from` with the 1st argument of `Time.between_dates` is deprecated. Use keyword argument like `Time.between_dates(from: ...)` instead.', uplevel: 1
-          from = legacy_from
-        end
-        if legacy_to != NOT_GIVEN
-          warn_with_uplevel 'Passing `to` with the 2nd argument of `Time.between_dates` is deprecated. Use keyword argument like `Time.between_dates(to: ...)` instead.', uplevel: 1
-          to = legacy_to
-        end
-        if legacy_period != NOT_GIVEN
-          warn_with_uplevel 'Passing `period` with the 3rd argument of `Time.between_dates` is deprecated. Use keyword argument like `Time.between_dates(period: ...)` instead.', uplevel: 1
-          period = legacy_period
-        end
-        if legacy_format != NOT_GIVEN
-          warn_with_uplevel 'Passing `format` with the 4th argument of `Time.between_dates` is deprecated. Use keyword argument like `Time.between_dates(format: ...)` instead.', uplevel: 1
-          format = legacy_format
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :from if legacy_from != NOT_GIVEN
+          keywords << :to if legacy_to != NOT_GIVEN
+          keywords << :period if legacy_period != NOT_GIVEN
+          keywords << :format if legacy_format != NOT_GIVEN
         end
 
         date = Faker::Date.between(from: from, to: to)
@@ -61,43 +94,56 @@ module Faker
         time_with_format(time, format)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produce a random time in the future (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the future.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.forward(days: 23, period: :morning)
+      #     # => "2014-09-26 06:54:47 -0700"
+      #   Faker::Time.forward(days: 5,  period: :evening, format: :long)
+      #     #=> "October 21, 2018 20:47"
+      #
+      # @faker.version 1.5.0
       def forward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
-        if legacy_days != NOT_GIVEN
-          warn_with_uplevel 'Passing `days` with the 1st argument of `Time.forward` is deprecated. Use keyword argument like `Time.forward(days: ...)` instead.', uplevel: 1
-          days = legacy_days
-        end
-        if legacy_period != NOT_GIVEN
-          warn_with_uplevel 'Passing `period` with the 2nd argument of `Time.forward` is deprecated. Use keyword argument like `Time.forward(period: ...)` instead.', uplevel: 1
-          period = legacy_period
-        end
-        if legacy_format != NOT_GIVEN
-          warn_with_uplevel 'Passing `format` with the 3rd argument of `Time.forward` is deprecated. Use keyword argument like `Time.forward(format: ...)` instead.', uplevel: 1
-          format = legacy_format
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :days if legacy_days != NOT_GIVEN
+          keywords << :period if legacy_period != NOT_GIVEN
+          keywords << :format if legacy_format != NOT_GIVEN
         end
 
         time_with_format(date_with_random_time(Faker::Date.forward(days: days), period), format)
       end
 
-      # rubocop:disable Metrics/ParameterLists
+      ##
+      # Produce a random time in the past (up to N days).
+      #
+      # @param days [Integer] The maximum number of days to go into the past.
+      # @param period [Symbol] The time of day, if any. See {TIME_RANGES}.
+      # @param format [Symbol] The name of a DateTime format to use.
+      # @return [Time]
+      #
+      # @example
+      #   Faker::Time.backward(days: 14, period: :evening)
+      #     #=> "2014-09-17 19:56:33 -0700"
+      #   Faker::Time.backward(days: 5, period: :morning, format: :short)
+      #     #=> "14 Oct 07:44"
+      #
+      # @faker.version 1.5.0
       def backward(legacy_days = NOT_GIVEN, legacy_period = NOT_GIVEN, legacy_format = NOT_GIVEN, days: 365, period: :all, format: nil)
-        # rubocop:enable Metrics/ParameterLists
-        if legacy_days != NOT_GIVEN
-          warn_with_uplevel 'Passing `days` with the 1st argument of `Time.backward` is deprecated. Use keyword argument like `Time.backward(days: ...)` instead.', uplevel: 1
-          days = legacy_days
-        end
-        if legacy_period != NOT_GIVEN
-          warn_with_uplevel 'Passing `period` with the 2nd argument of `Time.backward` is deprecated. Use keyword argument like `Time.backward(period: ...)` instead.', uplevel: 1
-          period = legacy_period
-        end
-        if legacy_format != NOT_GIVEN
-          warn_with_uplevel 'Passing `format` with the 3rd argument of `Time.backward` is deprecated. Use keyword argument like `Time.backward(format: ...)` instead.', uplevel: 1
-          format = legacy_format
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :days if legacy_days != NOT_GIVEN
+          keywords << :period if legacy_period != NOT_GIVEN
+          keywords << :format if legacy_format != NOT_GIVEN
         end
 
         time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private
 

data/lib/faker/default/twitter.rb

@@ -4,13 +4,9 @@ module Faker
   class Twitter < Base
     class << self
       def user(legacy_include_status = NOT_GIVEN, legacy_include_email = NOT_GIVEN, include_status: true, include_email: false)
-        if legacy_include_status != NOT_GIVEN
-          warn_with_uplevel 'Passing `include_status` with the 1st argument of `Twitter.user` is deprecated. Use keyword argument like `Twitter.user(include_status: ...)` instead.', uplevel: 1
-          include_status = legacy_include_status
-        end
-        if legacy_include_email != NOT_GIVEN
-          warn_with_uplevel 'Passing `include_email` with the 2nd argument of `Twitter.user` is deprecated. Use keyword argument like `Twitter.user(include_email: ...)` instead.', uplevel: 1
-          include_email = legacy_include_email
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :include_status if legacy_include_status != NOT_GIVEN
+          keywords << :include_email if legacy_include_email != NOT_GIVEN
         end
 
         user_id = id
@@ -24,7 +20,7 @@ module Faker
           default_profile_image: Faker::Boolean.boolean(true_ratio: 0.1),
           default_profile: Faker::Boolean.boolean(true_ratio: 0.1),
           description: Faker::Lorem.sentence,
-          entities:  user_entities,
+          entities: user_entities,
           favourites_count: Faker::Number.between(to: 1, from: 100_000),
           follow_request_sent: false,
           followers_count: Faker::Number.between(to: 1, from: 10_000_000),
@@ -64,13 +60,9 @@ module Faker
       end
 
       def status(legacy_include_user = NOT_GIVEN, legacy_include_photo = NOT_GIVEN, include_user: true, include_photo: false)
-        if legacy_include_user != NOT_GIVEN
-          warn_with_uplevel 'Passing `include_user` with the 1st argument of `Twitter.status` is deprecated. Use keyword argument like `Twitter.status(include_user: ...)` instead.', uplevel: 1
-          include_user = legacy_include_user
-        end
-        if legacy_include_photo != NOT_GIVEN
-          warn_with_uplevel 'Passing `include_photo` with the 2nd argument of `Twitter.status` is deprecated. Use keyword argument like `Twitter.status(include_photo: ...)` instead.', uplevel: 1
-          include_photo = legacy_include_photo
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :include_user if legacy_include_user != NOT_GIVEN
+          keywords << :include_photo if legacy_include_photo != NOT_GIVEN
         end
 
         status_id = id
@@ -80,7 +72,7 @@ module Faker
           contributors: nil,
           coordinates: nil,
           created_at: created_at,
-          entities:  status_entities(include_photo: include_photo),
+          entities: status_entities(include_photo: include_photo),
           favorite_count: Faker::Number.between(to: 1, from: 10_000),
           favorited: false,
           geo: nil,
@@ -94,7 +86,7 @@ module Faker
           place: nil,
           possibly_sensitive: Faker::Boolean.boolean(true_ratio: 0.1),
           retweet_count: Faker::Number.between(to: 1, from: 10_000),
-          retweeted_status:  nil,
+          retweeted_status: nil,
           retweeted: false,
           source: "<a href=\"#{Faker::Internet.url(host: 'example.com')}\" rel=\"nofollow\">#{Faker::Company.name}</a>",
           text: Faker::Lorem.sentence,
@@ -125,26 +117,25 @@ module Faker
 
       def user_entities
         {
-          url:  {
+          url: {
             urls: []
           },
-          description:  {
+          description: {
             urls: []
           }
         }
       end
 
       def status_entities(legacy_include_photo = NOT_GIVEN, include_photo: false)
-        if legacy_include_photo != NOT_GIVEN
-          warn_with_uplevel 'Passing `include_photo` with the 1st argument of `Twitter.status_entities` is deprecated. Use keyword argument like `Twitter.status_entities(include_photo: ...)` instead.', uplevel: 1
-          include_photo = legacy_include_photo
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :include_photo if legacy_include_photo != NOT_GIVEN
         end
 
         entities = {
-          hashtags:  [],
-          symbols:  [],
-          user_mentions:  [],
-          urls:  []
+          hashtags: [],
+          symbols: [],
+          user_mentions: [],
+          urls: []
         }
         entities[:media] = [photo_entity] if include_photo
         entities
@@ -158,7 +149,7 @@ module Faker
         {
           id: media_id,
           id_str: media_id.to_s,
-          indices:  [
+          indices: [
             103,
             126
           ],
@@ -168,23 +159,23 @@ module Faker
           display_url: 'example.com',
           expanded_url: Faker::Internet.url(host: 'example.com'),
           type: 'photo',
-          sizes:  {
-            medium:  {
+          sizes: {
+            medium: {
               w: 1064,
               h: 600,
               resize: 'fit'
             },
-            large:  {
+            large: {
               w: 1064,
               h: 600,
               resize: 'fit'
             },
-            small:  {
+            small: {
               w: 680,
               h: 383,
               resize: 'fit'
             },
-            thumb:  {
+            thumb: {
               w: 150,
               h: 150,
               resize: 'crop'