faker 2.11.0 → 3.2.0

data/lib/faker/default/stripe.rb

@@ -3,11 +3,18 @@
 module Faker
   class Stripe < Base
     class << self
-      def valid_card(legacy_card_type = NOT_GIVEN, card_type: nil)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :card_type if legacy_card_type != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random valid card number.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.valid_card #=> "4242424242424242"
+      #   Faker::Stripe.valid_card(card_type: "visa_debit") #=> "4000056655665556"
+      #
+      # @faker.version 1.9.0
+      def valid_card(card_type: nil)
         valid_cards = translate('faker.stripe.valid_cards').keys
 
         if card_type.nil?
@@ -19,14 +26,21 @@ module Faker
           end
         end
 
-        fetch('stripe.valid_cards.' + card_type)
+        fetch("stripe.valid_cards.#{card_type}")
       end
 
-      def valid_token(legacy_card_type = NOT_GIVEN, card_type: nil)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :card_type if legacy_card_type != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random valid Stripe token.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.valid_token #=> "tok_visa"
+      #   Faker::Stripe.valid_token(card_type: "mc_debit") #=> "tok_mastercard_debit"
+      #
+      # @faker.version 1.9.0
+      def valid_token(card_type: nil)
         valid_tokens = translate('faker.stripe.valid_tokens').keys
 
         if card_type.nil?
@@ -38,14 +52,20 @@ module Faker
           end
         end
 
-        fetch('stripe.valid_tokens.' + card_type)
+        fetch("stripe.valid_tokens.#{card_type}")
       end
 
-      def invalid_card(legacy_card_error = NOT_GIVEN, card_error: nil)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :card_error if legacy_card_error != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random invalid card number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.invalid_card #=> "4000000000000002"
+      #   Faker::Stripe.invalid_card(card_error: "addressZipFail") #=> "4000000000000010"
+      #
+      # @faker.version 1.9.0
+      def invalid_card(card_error: nil)
         invalid_cards = translate('faker.stripe.invalid_cards').keys
 
         if card_error.nil?
@@ -57,23 +77,48 @@ module Faker
           end
         end
 
-        fetch('stripe.invalid_cards.' + card_error)
+        fetch("stripe.invalid_cards.#{card_error}")
       end
 
+      ##
+      # Produces a random month in two digits format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.month #=> "10"
+      #
+      # @faker.version 1.9.0
       def month
         format('%02d', rand_in_range(1, 12))
       end
 
+      ##
+      # Produces a random year that is always in the future.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.year #=> "2018" # This will always be a year in the future
+      #
+      # @faker.version 1.9.0
       def year
         start_year = ::Time.new.year + 1
         rand_in_range(start_year, start_year + 5).to_s
       end
 
-      def ccv(legacy_card_type = NOT_GIVEN, card_type: nil)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :card_type if legacy_card_type != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random ccv number.
+      #
+      # @param card_type [String] Specific valid card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Stripe.ccv #=> "123"
+      #   Faker::Stripe.ccv(card_type: "amex") #=> "1234"
+      #
+      # @faker.version 1.9.0
+      def ccv(card_type: nil)
         (card_type.to_s == 'amex' ? rand_in_range(1000, 9999) : rand_in_range(100, 999)).to_s
       end
     end

data/lib/faker/default/tea.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Faker
+  class Tea < Base
+    flexible :tea
+
+    class << self
+      ##
+      # Produces a random variety or blend of tea.
+      #
+      # @param type [String, nil] the type of tea to query for (valid types: 'Black', 'Green', 'Oolong', 'White', and 'Herbal')
+      # @return [String] a variety of tea
+      #
+      # @example
+      #   Faker::Tea.variety
+      #     #=> "Earl Grey"
+      #
+      # @example
+      #   Faker::Tea.variety(type: 'Green')
+      #     #=> "Jasmine"
+      # @faker.version next
+      def variety(type: nil)
+        type ||= fetch('tea.type')
+        fetch "tea.variety.#{type.downcase}"
+      end
+
+      ##
+      # Produces a random type of tea.
+      #
+      # @return [String] a type of tea
+      #
+      # @example
+      #   Faker::Tea.type
+      #     #=> "Green"
+      # @faker.version next
+      def type
+        fetch 'tea.type'
+      end
+    end
+  end
+end

data/lib/faker/default/time.rb

@@ -13,9 +13,6 @@ module Faker
     }.freeze
 
     class << self
-      # rubocop:disable Metrics/ParameterLists
-      # rubocop:disable Style/AsciiComments
-
       ##
       # Produce a random time between two times.
       #
@@ -38,20 +35,13 @@ module Faker
       #   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)
-        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
-
+      def between(from:, to:, format: nil)
         from = get_time_object(from)
         to = get_time_object(to)
 
         time = Faker::Base.rand_in_range(from, to)
         time_with_format(time, format)
       end
-      # rubocop:enable Style/AsciiComments
 
       ##
       # Produce a random time between two dates.
@@ -81,14 +71,7 @@ module Faker
       #     #=> "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)
-        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
-
+      def between_dates(from:, to:, period: :all, format: nil)
         date = Faker::Date.between(from: from, to: to)
         time = date_with_random_time(date, period)
         time_with_format(time, format)
@@ -109,13 +92,7 @@ module Faker
       #     #=> "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)
-        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
-
+      def forward(days: 365, period: :all, format: nil)
         time_with_format(date_with_random_time(Faker::Date.forward(days: days), period), format)
       end
 
@@ -134,16 +111,9 @@ module Faker
       #     #=> "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)
-        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
-
+      def backward(days: 365, period: :all, format: nil)
         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

@@ -3,14 +3,22 @@
 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)
-        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
-
+      ##
+      # Produces a random Twitter user.
+      #
+      # @param include_status [Boolean] Include or exclude user status details
+      # @param include_email [Boolean] Include or exclude user email details
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Twitter.user #=>  {:id=>8821452687517076614, :name=>"Lincoln Paucek", :screen_name=>"cody"...
+      #   Faker::Twitter.user(include_status: false) # Just get a user object with no embed status
+      #   Faker::Twitter.user(include_email: true) # Simulate an authenticated user with the email permission
+      #
+      # @faker.version 1.7.3
+      def user(include_status: true, include_email: false)
         user_id = id
-        background_image_url = Faker::LoremPixel.image(size: '600x400') # TODO: Make the dimensions change
+        background_image_url = Faker::LoremFlickr.image(size: '600x400')
         profile_image_url = Faker::Avatar.image(slug: user_id, size: '48x48')
         user = {
           id: user_id,
@@ -38,7 +46,7 @@ module Faker
           profile_background_image_url_https: background_image_url,
           profile_background_image_url: background_image_url.sub('https://', 'http://'),
           profile_background_tile: Faker::Boolean.boolean(true_ratio: 0.1),
-          profile_banner_url: Faker::LoremPixel.image(size: '1500x500'),
+          profile_banner_url: Faker::LoremFlickr.image(size: '1500x500'),
           profile_image_url_https: profile_image_url,
           profile_image_url: profile_image_url.sub('https://', 'http://'),
           profile_link_color: Faker::Color.hex_color,
@@ -55,16 +63,24 @@ module Faker
           verified: Faker::Boolean.boolean(true_ratio: 0.1)
         }
         user[:status] = Faker::Twitter.status(include_user: false) if include_status
-        user[:email] = Faker::Internet.safe_email if include_email
+        user[:email] = Faker::Internet.email if include_email
         user
       end
 
-      def status(legacy_include_user = NOT_GIVEN, legacy_include_photo = NOT_GIVEN, include_user: true, include_photo: false)
-        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
-
+      ##
+      # Produces a random Twitter user.
+      #
+      # @param include_user [Boolean] Include or exclude user details
+      # @param include_photo [Boolean] Include or exclude user photo
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Twitter.status #=> {:id=>8821452687517076614, :text=>"Ea et laboriosam vel non."...
+      #   Faker::Twitter.status(include_user: false) # Just get a status object with no embed user
+      #   Faker::Twitter.status(include_photo: true) # Includes entities for an attached image
+      #
+      # @faker.version 1.7.3
+      def status(include_user: true, include_photo: false)
         status_id = id
         status = {
           id: status_id,
@@ -97,6 +113,15 @@ module Faker
         status
       end
 
+      ##
+      # Produces a random screen name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Twitter.screen_name #=> "audreanne_hackett"
+      #
+      # @faker.version 1.7.3
       def screen_name
         Faker::Internet.username(specifier: nil, separators: ['_'])[0...20]
       end
@@ -126,11 +151,7 @@ module Faker
         }
       end
 
-      def status_entities(legacy_include_photo = NOT_GIVEN, include_photo: false)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :include_photo if legacy_include_photo != NOT_GIVEN
-        end
-
+      def status_entities(include_photo: false)
         entities = {
           hashtags: [],
           symbols: [],
@@ -142,9 +163,7 @@ module Faker
       end
 
       def photo_entity
-        # TODO: Dynamic image sizes
-        # TODO: Return accurate indices
-        media_url = Faker::LoremPixel.image(size: '1064x600')
+        media_url = Faker::LoremFlickr.image(size: '1064x600')
         media_id = id
         {
           id: media_id,

data/lib/faker/default/types.rb

@@ -7,11 +7,16 @@ module Faker
     COMPLEX_TYPES = %i[hash array].freeze
 
     class << self
-      def rb_string(legacy_words = NOT_GIVEN, words: 1)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :words if legacy_words != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random String created from word (Faker::Lorem.word)
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Types.rb_string #=> "foobar"
+      #
+      # @faker.version 1.8.6
+      def rb_string(words: 1)
         resolved_num = resolve(words)
         word_list =
           translate('faker.lorem.words')
@@ -20,45 +25,81 @@ module Faker
         shuffle(word_list)[0, resolved_num].join(' ')
       end
 
+      ##
+      # Produces a random character from the a-z, 0-9 ranges.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Types.character #=> "n"
+      #
+      # @faker.version 1.8.6
       def character
         sample(CHARACTERS)
       end
 
-      def rb_integer(legacy_from = NOT_GIVEN, legacy_to = NOT_GIVEN, from: 0, to: 100)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :from if legacy_from != NOT_GIVEN
-          keywords << :to if legacy_to != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random integer.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Types.rb_integer #=> 1
+      #
+      # @faker.version 1.8.6
+      def rb_integer(from: 0, to: 100)
         rand(from..to).to_i
       end
 
-      def rb_hash(legacy_number = NOT_GIVEN, legacy_type = NOT_GIVEN, number: 1, type: random_type)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :number if legacy_number != NOT_GIVEN
-          keywords << :type if legacy_type != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random hash with random keys and values.
+      #
+      # @param number [Integer] Specifies the number of key-value pairs.
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Types.rb_hash #=> {name: "bob"}
+      #   Faker::Types.rb_hash(number: 1) #=> {name: "bob"}
+      #   Faker::Types.rb_hash(number: 2) #=> {name: "bob", last: "marley"}
+      #
+      # @faker.version 1.8.6
+      def rb_hash(number: 1, type: -> { random_type })
         {}.tap do |hsh|
           Lorem.words(number: number * 2).uniq.first(number).each do |s|
-            hsh.merge!(s.to_sym => type)
+            value = type.is_a?(Proc) ? type.call : type
+            hsh.merge!(s.to_sym => value)
           end
         end
       end
 
-      def complex_rb_hash(legacy_number = NOT_GIVEN, number: 1)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :number if legacy_number != NOT_GIVEN
-        end
-
-        rb_hash(number: number, type: random_complex_type)
+      ##
+      # Produces a random complex hash with random keys and values where the values may include other hashes and arrays.
+      #
+      # @param number [Integer] Specifies the number of key-value pairs.
+      # @return [Hash]
+      #
+      # @example
+      #   Faker::Types.complex_rb_hash #=> {user: {first: "bob", last: "marley"}}
+      #   Faker::Types.complex_rb_hash(number: 1) #=> {user: {first: "bob", last: "marley"}}
+      #   Faker::Types.complex_rb_hash(number: 2) #=> {user: {first: "bob", last: "marley"}, son: ["damien", "marley"]}
+      #
+      # @faker.version 1.8.6
+      def complex_rb_hash(number: 1)
+        rb_hash(number: number, type: -> { random_complex_type })
       end
 
-      def rb_array(legacy_len = NOT_GIVEN, len: 1)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :len if legacy_len != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random array.
+      #
+      # @param len [Integer] Specifies the number of elements in the array.
+      # @return [Array]
+      #
+      # @example
+      #   Faker::Types.rb_array #=> ["a"]
+      #   Faker::Types.rb_array(len: 4) #=> ["a", 1, 2, "bob"]
+      #
+      # @faker.version 1.8.6
+      def rb_array(len: 1)
         [].tap do |ar|
           len.times do
             ar.push random_type
@@ -66,6 +107,15 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random type that's either a String or an Integer.
+      #
+      # @return [String, Integer]
+      #
+      # @example
+      #   Faker::Types.random_type #=> 1 or "a" or "bob"
+      #
+      # @faker.version 1.8.6
       def random_type
         type_to_use = SIMPLE_TYPES[rand(0..SIMPLE_TYPES.length - 1)]
         case type_to_use
@@ -76,6 +126,15 @@ module Faker
         end
       end
 
+      ##
+      # Produces a random complex type that's either a String, an Integer, an array or a hash.
+      #
+      # @return [String, Integer]
+      #
+      # @example
+      #   Faker::Types.random_complex_type #=> 1 or "a" or "bob" or {foo: "bar"}
+      #
+      # @faker.version 1.8.6
       def random_complex_type
         types = SIMPLE_TYPES + COMPLEX_TYPES
         type_to_use = types[rand(0..types.length - 1)]

data/lib/faker/default/university.rb

@@ -5,22 +5,67 @@ module Faker
     flexible :university
 
     class << self
+      ##
+      # Produces a random university name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.name #=> "Eastern Mississippi Academy"
+      #
+      # @faker.version 1.5.0
       def name
         parse('university.name')
       end
 
+      ##
+      # Produces a random university prefix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.prefix #=> "Western"
+      #
+      # @faker.version 1.5.0
       def prefix
         fetch('university.prefix')
       end
 
+      ##
+      # Produces a random university suffix.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.suffix #=> "Academy"
+      #
+      # @faker.version 1.5.0
       def suffix
         fetch('university.suffix')
       end
 
+      ##
+      # Produces a random greek organization.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::University.greek_organization #=> "BEX"
+      #
+      # @faker.version 1.5.0
       def greek_organization
         Array.new(3) { |_| sample(greek_alphabet) }.join
       end
 
+      ##
+      # Produces a greek alphabet.
+      #
+      # @return [Array]
+      #
+      # @example
+      #   Faker::University.greek_alphabet #=> ["Α", "B", "Γ", "Δ", ...]
+      #
+      # @faker.version 1.5.0
       def greek_alphabet
         %w[Α B Γ Δ E Z H Θ I K Λ M N Ξ
            O Π P Σ T Y Φ X Ψ Ω]