faker 2.0.0 → 3.8.0

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/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/team.rb

@@ -5,22 +5,67 @@ module Faker
     flexible :team
 
     class << self
+      ##
+      # Produces a team name from a state and a creature.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Team.name #=> "Oregon vixens"
+      #
+      # @faker.version 1.3.0
       def name
         parse('team.name')
       end
 
+      ##
+      # Produces a team creature.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Team.creature #=> "geese"
+      #
+      # @faker.version 1.3.0
       def creature
         fetch('team.creature')
       end
 
+      ##
+      # Produces a team state.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Team.state #=> "Oregon"
+      #
+      # @faker.version 1.3.0
       def state
         fetch('address.state')
       end
 
+      ##
+      # Produces a team sport.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Team.sport #=> "Lacrosse"
+      #
+      # @faker.version 1.5.0
       def sport
         fetch('team.sport')
       end
 
+      ##
+      # Produces the name of a team mascot.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Team.mascot #=> "Hugo"
+      #
+      # @faker.version 1.8.1
       def mascot
         fetch('team.mascot')
       end

data/lib/faker/default/theater.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Faker
+  class Theater < Base
+    class << self
+      ##
+      # Produces the name of a musical for an older audience
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Theater.adult_musical
+      #     #=> "Mamma Mia!"
+      #
+      # @faker.version 2.13.0
+      def adult_musical
+        fetch('theater.adult_musical')
+      end
+
+      ##
+      # Produces the name of a musical for a younger audience
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Theater.kids_musical
+      #     #=> "Into the Woods JR."
+      #
+      # @faker.version 2.13.0
+      def kids_musical
+        fetch('theater.kids_musical')
+      end
+
+      ##
+      # Produces the name of a play
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Theater.play
+      #     #=> "Death of a Salesman"
+      #
+      # @faker.version 2.13.0
+      def play
+        fetch('theater.play')
+      end
+    end
+  end
+end

data/lib/faker/default/time.rb

@@ -13,6 +13,28 @@ module Faker
     }.freeze
 
     class << self
+      ##
+      # 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(from:, to:, format: nil)
         from = get_time_object(from)
         to = get_time_object(to)
@@ -21,16 +43,74 @@ module Faker
         time_with_format(time, format)
       end
 
+      ##
+      # 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(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)
       end
 
+      ##
+      # 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(days: 365, period: :all, format: nil)
         time_with_format(date_with_random_time(Faker::Date.forward(days: days), period), format)
       end
 
+      ##
+      # 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(days: 365, period: :all, format: nil)
         time_with_format(date_with_random_time(Faker::Date.backward(days: days), period), format)
       end

data/lib/faker/default/types.rb

@@ -7,45 +7,116 @@ module Faker
     COMPLEX_TYPES = %i[hash array].freeze
 
     class << self
+      ##
+      # 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')
-
+        word_list = translate('faker.lorem.words')
         word_list *= ((resolved_num / word_list.length) + 1)
-        shuffle(word_list)[0, resolved_num].join(' ')
+        sample(word_list, 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
 
+      ##
+      # 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(number: 1, type: random_type)
+      ##
+      # 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
 
+      ##
+      # 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)
+        rb_hash(number: number, type: -> { random_complex_type })
       end
 
-      def rb_array(len: 1)
+      ##
+      # 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::Types.rb_array(len: 2, type: -> { Faker::Types.rb_string }) #=> ["cat", "foo"]
+      #
+      # @faker.version 1.8.6
+      def rb_array(len: 1, type: -> { random_type })
         [].tap do |ar|
           len.times do
-            ar.push random_type
+            ar.push type.is_a?(Proc) ? type.call : type
           end
         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)]
+        type_to_use = SIMPLE_TYPES[rand(0..(SIMPLE_TYPES.length - 1))]
         case type_to_use
         when :string
           rb_string
@@ -54,9 +125,18 @@ 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)]
+        type_to_use = types[rand(0..(types.length - 1))]
         case type_to_use
         when :string
           rb_string

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 Ψ Ω]