faker 2.2.0 → 3.2.2

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

@@ -5,12 +5,16 @@ module Faker
     flexible :relationship
 
     class << self
-      def familial(legacy_connection = NOT_GIVEN, connection: nil)
-        if legacy_connection != NOT_GIVEN
-          warn_with_uplevel 'Passing `connection` with the 1st argument of `Relationship.familial` is deprecated. Use keyword argument like `Relationship.familial(connection: ...)` instead.', uplevel: 1
-          connection = legacy_connection
-        end
-
+      ##
+      # Produces a random family relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.familial #=> "Grandfather"
+      #
+      # @faker.version 1.9.2
+      def familial(connection: nil)
         familial_connections = translate('faker.relationship.familial').keys
 
         if connection.nil?
@@ -24,21 +28,57 @@ module Faker
           end
         end
 
-        fetch('relationship.familial.' + connection)
+        fetch("relationship.familial.#{connection}")
       end
 
+      ##
+      # Produces a random in-law relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.in_law #=> "Brother-in-law"
+      #
+      # @faker.version 1.9.2
       def in_law
         fetch('relationship.in_law')
       end
 
+      ##
+      # Produces a random spouse relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.spouse #=> "Husband"
+      #
+      # @faker.version 1.9.2
       def spouse
         fetch('relationship.spouse')
       end
 
+      ##
+      # Produces a random parent relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.parent #=> "Father"
+      #
+      # @faker.version 1.9.2
       def parent
         fetch('relationship.parent')
       end
 
+      ##
+      # Produces a random sibling relationship.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Relationship.sibling #=> "Sister"
+      #
+      # @faker.version 1.9.2
       def sibling
         fetch('relationship.sibling')
       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/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,17 +3,152 @@
 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.
+      #
+      # @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 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.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Science.scientist #=> "Isaac Newton"
+      #
+      # @faker.version 1.8.5
       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

@@ -3,35 +3,59 @@
 module Faker
   class Source < Base
     class << self
-      def hello_world(legacy_lang = NOT_GIVEN, lang: :ruby)
-        if legacy_lang != NOT_GIVEN
-          warn_with_uplevel 'Passing `lang` with the 1st argument of `Source.hello_world` is deprecated. Use keyword argument like `Source.hello_world(lang: ...)` instead.', uplevel: 1
-          lang = legacy_lang
-        end
-
+      ##
+      # 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(lang: :ruby)
         fetch("source.hello_world.#{lang}")
       end
 
-      def print(legacy_str = NOT_GIVEN, legacy_lang = NOT_GIVEN, str: 'some string', lang: :ruby)
-        if legacy_str != NOT_GIVEN
-          warn_with_uplevel 'Passing `str` with the 1st argument of `Source.print` is deprecated. Use keyword argument like `Source.print(str: ...)` instead.', uplevel: 1
-          str = legacy_str
-        end
-        if legacy_lang != NOT_GIVEN
-          warn_with_uplevel 'Passing `lang` with the 2nd argument of `Source.print` is deprecated. Use keyword argument like `Source.print(lang: ...)` instead.', uplevel: 1
-          lang = legacy_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(str: 'some string', lang: :ruby)
         code = fetch("source.print.#{lang}")
         code.gsub('faker_string_to_print', str)
       end
 
-      def print_1_to_10(legacy_lang = NOT_GIVEN, lang: :ruby)
-        if legacy_lang != NOT_GIVEN
-          warn_with_uplevel 'Passing `lang` with the 1st argument of `Source.print_1_to_10` is deprecated. Use keyword argument like `Source.print_1_to_10(lang: ...)` instead.', uplevel: 1
-          lang = legacy_lang
-        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(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
       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
       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
       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