faker 2.11.0 → 3.4.2

data/lib/faker/default/relationship.rb

@@ -14,11 +14,7 @@ module Faker
       #   Faker::Relationship.familial #=> "Grandfather"
       #
       # @faker.version 1.9.2
-      def familial(legacy_connection = NOT_GIVEN, connection: nil)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :connection if legacy_connection != NOT_GIVEN
-        end
-
+      def familial(connection: nil)
         familial_connections = translate('faker.relationship.familial').keys
 
         if connection.nil?
@@ -32,7 +28,7 @@ module Faker
           end
         end
 
-        fetch('relationship.familial.' + connection)
+        fetch("relationship.familial.#{connection}")
       end
 
       ##

data/lib/faker/default/religion.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Faker
+  module Religion
+  end
+end

data/lib/faker/default/science.rb

@@ -3,6 +3,47 @@
 module Faker
   class Science < Base
     class << self
+      BRANCHES = {
+        empirical: %i[empirical_natural_basic empirical_natural_applied empirical_social_basic empirical_social_applied],
+        formal: %i[formal_basic formal_applied],
+        natural: %i[empirical_natural_basic empirical_natural_applied],
+        social: %i[empirical_social_basic empirical_social_applied],
+        basic: %i[empirical_natural_basic empirical_social_basic formal_basic],
+        applied: %i[empirical_natural_applied empirical_social_applied formal_applied]
+      }.freeze
+
+      ##
+      # Produces a name of a science
+      # You can optionally filter by specifying one or more of the following:
+      # `:empirical, :formal, :natural, :social, :basic, :applied`
+      # @see https://en.wikipedia.org/wiki/Science#Branches_of_science
+      # @see Faker::Educator.subject
+      #
+      # @param branches [Array<Symbol>]
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.science #=> "Space science"
+      #   Faker::Science.science(:natural, :applied) #=> "Engineering"
+      #   Faker::Science.science(:formal, :applied) #=> "Computer Science"
+      #
+      # @faker.version next
+      def science(*branches)
+        selected = BRANCHES.values.flatten.uniq
+        branches.each do |branch|
+          selected &= BRANCHES[branch] if BRANCHES.key? branch
+        end
+
+        raise ArgumentError, 'Filters do not match any sciences' if selected.empty?
+
+        sciences = []
+        selected.each do |branch|
+          sciences += translate("faker.science.branch.#{branch}")
+        end
+
+        sample(sciences)
+      end
+
       ##
       # Produces the name of a element.
       #
@@ -29,6 +70,32 @@ module Faker
         fetch('science.element_symbol')
       end
 
+      ##
+      # Produces the state of an element.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.element_state #=> "Liquid"
+      #
+      # @faker.version next
+      def element_state
+        fetch('science.element_state')
+      end
+
+      ##
+      # Produces the subcategory of an element.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.element_subcategory #=> "Reactive nonmetal"
+      #
+      # @faker.version next
+      def element_subcategory
+        fetch('science.element_subcategory')
+      end
+
       ##
       # Produces the name of a scientist.
       #
@@ -41,6 +108,47 @@ module Faker
       def scientist
         fetch('science.scientist')
       end
+
+      ##
+      # Produces a scientifically sounding word
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.modifier #=> "Quantum"
+      #   Faker::Science.modifier #=> "Superconductive"
+      #
+      # @faker.version next
+      def modifier
+        fetch('science.modifier')
+      end
+
+      ##
+      # Produces the name of a scientific tool.
+      # By default it uses a science word modifier to generate more diverse data, which can be disabled.
+      #
+      # @param simple [Boolean] Whether to generate simple realistic tool names, (no Q-word).
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.tool #=> "Superconductive Microcentrifuge"
+      #   Faker::Science.tool #=> "Portable Cryostat"
+      #   Faker::Science.tool #=> "Quantum Spectrophotometer"
+      #   Faker::Science.tool(simple: true) #=> "Microcentrifuge"
+      #
+      # @faker.version next
+      def tool(simple: false)
+        tool = fetch('science.tool')
+        return tool if simple
+
+        # Makes sure the modifier are different
+        loop do
+          modifier = self.modifier
+          break unless tool.start_with?(modifier)
+        end
+
+        "#{modifier} #{tool}"
+      end
     end
   end
 end

data/lib/faker/default/slack_emoji.rb

@@ -3,38 +3,119 @@
 module Faker
   class SlackEmoji < Base
     class << self
+      ##
+      # Produces a random slack emoji from people category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.people #=> ":sleepy:"
+      #
+      # @faker.version 1.5.0
       def people
         fetch('slack_emoji.people')
       end
 
+      ##
+      # Produces a random slack emoji from nature category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.nature #=> ":mount_fuji:"
+      #
+      # @faker.version 1.5.0
       def nature
         fetch('slack_emoji.nature')
       end
 
+      ##
+      # Produces a random slack emoji from food and drink category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.food_and_drink #=> ":beers:"
+      #
+      # @faker.version 1.5.0
       def food_and_drink
         fetch('slack_emoji.food_and_drink')
       end
 
+      ##
+      # Produces a random slack emoji from celebration category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.celebration #=> ":tada:"
+      #
+      # @faker.version 1.5.0
       def celebration
         fetch('slack_emoji.celebration')
       end
 
+      ##
+      # Produces a random slack emoji from activity category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.activity #=> ":soccer:"
+      #
+      # @faker.version 1.5.0
       def activity
         fetch('slack_emoji.activity')
       end
 
+      ##
+      # Produces a random slack emoji from travel and places category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.travel_and_places #=> ":metro:"
+      #
+      # @faker.version 1.5.0
       def travel_and_places
         fetch('slack_emoji.travel_and_places')
       end
 
+      ##
+      # Produces a random slack emoji from objects and symbols category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.objects_and_symbols #=> ":id:"
+      #
+      # @faker.version 1.5.0
       def objects_and_symbols
         fetch('slack_emoji.objects_and_symbols')
       end
 
+      ##
+      # Produces a random slack emoji from custom category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.custom #=> ":slack:"
+      #
+      # @faker.version 1.5.0
       def custom
         fetch('slack_emoji.custom')
       end
 
+      ##
+      # Produces a random slack emoji from any category.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SlackEmoji.emoji #=> ":pizza:"
+      #
+      # @faker.version 1.5.0
       def emoji
         parse('slack_emoji.emoji')
       end

data/lib/faker/default/source.rb

@@ -17,11 +17,7 @@ module Faker
       #     #=> "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
-        end
-
+      def hello_world(lang: :ruby)
         fetch("source.hello_world.#{lang}")
       end
 
@@ -39,13 +35,7 @@ module Faker
       #     #=> "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
-        end
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :lang if legacy_lang != NOT_GIVEN
-        end
+      def print(str: 'some string', lang: :ruby)
         code = fetch("source.print.#{lang}")
         code.gsub('faker_string_to_print', str)
       end
@@ -65,10 +55,7 @@ module Faker
       #   #    }"
       #
       # @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
+      def print_1_to_10(lang: :ruby)
         fetch("source.print_1_to_10.#{lang}")
       end
     end

data/lib/faker/default/south_africa.rb

@@ -3,46 +3,136 @@
 module Faker
   class SouthAfrica < Base
     class << self
+      ##
+      # Produces a South African ID number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.id_number #=> "6110311856083"
+      #
+      # @faker.version 1.9.2
       def id_number
-        Faker::IDNumber.south_african_id_number
+        Faker::IdNumber.south_african_id_number
       end
 
+      ##
+      # Produces a valid South African ID number
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.valid_id_number #=> "6110311856083"
+      #
+      # @faker.version 1.9.2
       def valid_id_number
-        Faker::IDNumber.valid_south_african_id_number
+        Faker::IdNumber.valid_south_african_id_number
       end
 
+      ##
+      # Produces an invalid South African ID number
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.invalid_id_number #=> "7018356904081"
+      #
+      # @faker.version 1.9.2
       def invalid_id_number
-        Faker::IDNumber.invalid_south_african_id_number
+        Faker::IdNumber.invalid_south_african_id_number
       end
 
+      ##
+      # Produces a South African phone number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.phone_number #=> "010 788 5009"
+      #
+      # @faker.version 1.9.2
       def phone_number
         with_locale 'en-ZA' do
           Faker::PhoneNumber.phone_number
         end
       end
 
+      ##
+      # Produces a South African cell phone number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.cell_phone #=> "082 946 7470"
+      #
+      # @faker.version 1.9.2
       def cell_phone
         with_locale 'en-ZA' do
           Faker::PhoneNumber.cell_phone
         end
       end
 
+      ##
+      # Produces a South African private company registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.pty_ltd_registration_number #=> "5301/714689/07"
+      #
+      # @faker.version 1.9.2
       def pty_ltd_registration_number
         Faker::Company.south_african_pty_ltd_registration_number
       end
 
+      ##
+      # Produces a South African close corporation registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.close_corporation_registration_number #=> "CK74/7585/23"
+      #
+      # @faker.version 1.9.2
       def close_corporation_registration_number
         Faker::Company.south_african_close_corporation_registration_number
       end
 
+      ##
+      # Produces a South African listed company registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.listed_company_registration_number #=> "7039/3135/06"
+      #
+      # @faker.version 1.9.2
       def listed_company_registration_number
         Faker::Company.south_african_listed_company_registration_number
       end
 
+      ##
+      # Produces a South African trust registration number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.trust_registration_number #=> "IT38/6489900"
+      #
+      # @faker.version 1.9.2
       def trust_registration_number
         Faker::Company.south_african_trust_registration_number
       end
 
+      ##
+      # Produces a South African VAT number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::SouthAfrica.vat_number #=> "ZA79494416181"
+      #
+      # @faker.version 1.9.2
       def vat_number
         Faker::Finance.vat_number(country: 'ZA')
       end

data/lib/faker/default/space.rb

@@ -158,7 +158,7 @@ module Faker
       #
       # @faker.version 1.6.4
       def distance_measurement
-        rand(10..100).to_s + ' ' + fetch('space.distance_measurement')
+        "#{rand(10..100)} #{fetch('space.distance_measurement')}"
       end
 
       ##

data/lib/faker/default/string.rb

@@ -3,11 +3,21 @@
 module Faker
   class String < Base
     class << self
-      def random(legacy_length = NOT_GIVEN, length: 32)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :length if legacy_length != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random UTF-8 string with optional nested length selectors.
+      #
+      # @param length [Integer, Range, Array<Integer, Range, nil>] The length of produced string and/or specific UTF-8 characters to use.
+      # @return [String]
+      #
+      # @example
+      #   Faker::String.random #=> "3 뇦\u0017&y\u{3A109}$8^4* 녹豿4좘툢ꔾ쉙6ɉ\uA6 8TN畀챵|\"3쇤Ŵ"
+      #   Faker::String.random(length: 4) #=> "⼨%0*"
+      #   Faker::String.random(length: 3..12) #=> "\u{69FDC};秨툫"
+      #   Faker::String.random(length: [0, 6]) #=> "I轤𣴒P溟L"
+      #   Faker::String.random(length: [1, (2..5), [3, 6], nil]) #=> "葓L#ћ"
+      #
+      # @faker.version 1.9.0
+      def random(length: 32)
         utf8string select_a length
       end
 
@@ -38,9 +48,9 @@ module Faker
 
       def utf8character
         sample([
-                 rand(32..90), # latin alphabet
-                 rand(128),             # 7-bit ASCII
-                 rand(0xd800),          # utf-8 codepoints below utf-16 surrogate halves
+                 rand(32..90),           # latin alphabet
+                 rand(128),              # 7-bit ASCII
+                 rand(0xd800),           # utf-8 codepoints below utf-16 surrogate halves
                  rand(57_344..1_114_111) # utf-8 codepoints above utf-16 surrogate halves
                ]).chr(Encoding::UTF_8)
       end

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