faker 2.2.2 → 2.7.0

data/lib/faker/default/omniauth.rb

@@ -341,6 +341,48 @@ module Faker
         }
       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
+            }
+          }
+        }
+      end
+
       private
 
       def gender

data/lib/faker/default/programming_language.rb

@@ -3,10 +3,28 @@
 module Faker
   class ProgrammingLanguage < Base
     class << self
+      ##
+      # Produces the name of a programming language.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ProgrammingLanguage.name #=> "Ruby"
+      #
+      # @faker.version 1.8.5
       def name
         fetch('programming_language.name')
       end
 
+      ##
+      # Produces the name of a programming language's creator.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::ProgrammingLanguage.creator #=> "Yukihiro Matsumoto"
+      #
+      # @faker.version 1.8.5
       def creator
         fetch('programming_language.creator')
       end

data/lib/faker/default/restaurant.rb

@@ -4,8 +4,60 @@ module Faker
   class Restaurant < Base
     flexible :restaurant
 
-    def self.name
-      bothify(parse('restaurant.name'))
+    class << self
+      ##
+      # Produces the name of a restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.name #=> "Curry King"
+      #
+      # @faker.version 1.9.2
+      def name
+        bothify(parse('restaurant.name'))
+      end
+
+      ##
+      # Produces a type of restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.type #=> "Comfort Food"
+      #
+      # @faker.version 1.9.2
+      def type
+        fetch('restaurant.type')
+      end
+
+      ##
+      # Produces a description of a restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.description
+      #     #=> "We are committed to using the finest ingredients in our recipes. No food leaves our kitchen that we ourselves would not eat."
+      #
+      # @faker.version 1.9.2
+      def description
+        fetch('restaurant.description')
+      end
+
+      ##
+      # Produces a review for a restaurant.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Restaurant.review
+      #     #=> "Brand new. Great design. Odd to hear pop music in a Mexican establishment. Music is a bit loud. It should be background."
+      #
+      # @faker.version 1.9.2
+      def review
+        fetch('restaurant.review')
+      end
     end
   end
 end

data/lib/faker/default/science.rb

@@ -3,14 +3,41 @@
 module Faker
   class Science < Base
     class << self
+      ##
+      # Produces the name of a element.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.element #=> "Carbon"
+      #
+      # @faker.version 1.8.5
       def element
         fetch('science.element')
       end
 
+      ##
+      # Produces the symbol of an element.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.element_symbol #=> "Pb"
+      #
+      # @faker.version 1.9.0
       def element_symbol
         fetch('science.element_symbol')
       end
 
+      ##
+      # Produces the name of a scientist.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.scientist #=> "Isaac Newton"
+      #
+      # @faker.version 1.8.5
       def scientist
         fetch('science.scientist')
       end

data/lib/faker/default/source.rb

@@ -3,6 +3,20 @@
 module Faker
   class Source < Base
     class << self
+      ##
+      # Produces source code for Hello World in a given language.
+      #
+      # @param lang [Symbol] The programming language to use
+      # @return [String]
+      #
+      # @example
+      #   Faker::Source.hello_world #=> "puts 'Hello World!'"
+      #
+      # @example
+      #   Faker::Source.hello_world(lang: :javascript)
+      #     #=> "alert('Hello World!');"
+      #
+      # @faker.version 1.9.0
       def hello_world(legacy_lang = NOT_GIVEN, lang: :ruby)
         warn_for_deprecated_arguments do |keywords|
           keywords << :lang if legacy_lang != NOT_GIVEN
@@ -11,6 +25,20 @@ module Faker
         fetch("source.hello_world.#{lang}")
       end
 
+      ##
+      # Produces source code for printing a string in a given language.
+      #
+      # @param str [String] The string to print
+      # @param lang [Symbol] The programming language to use
+      # @return [String]
+      #
+      # @example
+      #   Faker::Source.print #=> "puts 'faker_string_to_print'"
+      # @example
+      #   Faker::Source.print(str: 'foo bar', lang: :javascript)
+      #     #=> "console.log('foo bar');"
+      #
+      # @faker.version 1.9.0
       def print(legacy_str = NOT_GIVEN, legacy_lang = NOT_GIVEN, str: 'some string', lang: :ruby)
         warn_for_deprecated_arguments do |keywords|
           keywords << :str if legacy_str != NOT_GIVEN
@@ -18,16 +46,29 @@ module Faker
         warn_for_deprecated_arguments do |keywords|
           keywords << :lang if legacy_lang != NOT_GIVEN
         end
-
         code = fetch("source.print.#{lang}")
         code.gsub('faker_string_to_print', str)
       end
 
+      ##
+      # Produces source code for printing 1 through 10 in a given language.
+      #
+      # @param lang [Symbol] The programming language to use
+      # @return [String]
+      #
+      # @example
+      #   Faker::Source.print_1_to_10 #=> "(1..10).each { |i| puts i }"
+      # @example
+      #   Faker::Source.print_1_to_10(lang: :javascript)
+      #   # => "for (let i=0; i<10; i++) {
+      #   #       console.log(i);
+      #   #    }"
+      #
+      # @faker.version 1.9.0
       def print_1_to_10(legacy_lang = NOT_GIVEN, lang: :ruby)
         warn_for_deprecated_arguments do |keywords|
           keywords << :lang if legacy_lang != NOT_GIVEN
         end
-
         fetch("source.print_1_to_10.#{lang}")
       end
     end

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,8 +14,31 @@ 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
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
           keywords << :to if legacy_to != NOT_GIVEN
@@ -28,10 +51,37 @@ 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
         warn_for_deprecated_arguments do |keywords|
           keywords << :from if legacy_from != NOT_GIVEN
           keywords << :to if legacy_to != NOT_GIVEN
@@ -44,9 +94,22 @@ 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
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
           keywords << :period if legacy_period != NOT_GIVEN
@@ -56,9 +119,22 @@ module Faker
         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
         warn_for_deprecated_arguments do |keywords|
           keywords << :days if legacy_days != NOT_GIVEN
           keywords << :period if legacy_period != NOT_GIVEN
@@ -67,6 +143,7 @@ module Faker
 
         time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       private