faker 2.11.0 → 3.2.0

data/lib/faker/default/phone_number.rb

@@ -3,48 +3,127 @@
 module Faker
   class PhoneNumber < Base
     class << self
+      ##
+      # Produces a random phone number in a random format (may or may not have a country code, extension and can have different dividers).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.phone_number #=> "397.693.1309 x4321"
+      #
+      # @faker.version 0.3.0
       def phone_number
         parse('phone_number.formats')
       end
 
+      ##
+      # Produces a random cell phone number in a random format (may or may not have a country code and can have different dividers).
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone #=> "(186)285-7925"
+      #
+      # @faker.version 1.0.0
       def cell_phone
         parse('cell_phone.formats')
       end
 
+      ##
+      # Produces a random country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.country_code #=> "+20"
+      #
+      # @faker.version 1.9.2
       def country_code
         "+#{fetch('country_code')}"
       end
 
+      ##
+      # Produces a random phone number with country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.phone_number_with_country_code #=> "+95 1-672-173-8153"
+      #
+      # @faker.version 1.9.2
       def phone_number_with_country_code
         "#{country_code} #{phone_number}"
       end
 
+      ##
+      # Produces a random cell phone number with country code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone_with_country_code #=> "+974 (190) 987-9034"
+      #
+      # @faker.version 1.9.2
       def cell_phone_with_country_code
         "#{country_code} #{cell_phone}"
       end
 
-      # US and Canada only
+      ##
+      # Produces a random phone number in e164 format.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.cell_phone_in_e164 #=> "+944937040625"
+      #
+      # @faker.version 1.9.2
+      def cell_phone_in_e164
+        cell_phone_with_country_code.delete('^+0-9')
+      end
+
+      ##
+      # Produces a random US or Canada-based area code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.area_code #=> "201"
+      #
+      # @faker.version 1.3.0
       def area_code
         fetch('phone_number.area_code')
       rescue I18n::MissingTranslationData
         nil
       end
 
-      # US and Canada only
+      ##
+      # Produces a random US or Canada-based exchange code.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.exchange_code #=> "208"
+      #
+      # @faker.version 1.3.0
       def exchange_code
         fetch('phone_number.exchange_code')
       rescue I18n::MissingTranslationData
         nil
       end
 
-      # US and Canada only
-      # Can be used for both extensions and last four digits of phone number.
-      # Since extensions can be of variable length, this method taks a length parameter
-      def subscriber_number(legacy_length = NOT_GIVEN, length: 4)
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :length if legacy_length != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random US or Canada-based extension / subscriber number. Can be used for both extensions and last four digits of phone number.
+      #
+      # @param length [Integer] Specifies the length of the return value.
+      # @return [String]
+      #
+      # @example
+      #   Faker::PhoneNumber.subscriber_number #=> "3873"
+      #   Faker::PhoneNumber.subscriber_number(length: 2) #=> "39"
+      #   Faker::PhoneNumber.extension #=> "3764"
+      #
+      # @faker.version 1.3.0
+      def subscriber_number(length: 4)
         rand.to_s[2..(1 + length)]
       end
 

data/lib/faker/default/placeholdit.rb

@@ -5,17 +5,28 @@ module Faker
     class << self
       SUPPORTED_FORMATS = %w[png jpg gif jpeg].freeze
 
-      # rubocop:disable Metrics/ParameterLists
-      def image(legacy_size = NOT_GIVEN, legacy_format = NOT_GIVEN, legacy_background_color = NOT_GIVEN, legacy_text_color = NOT_GIVEN, legacy_text = NOT_GIVEN, size: '300x300', format: 'png', background_color: nil, text_color: nil, text: nil)
-        # rubocop:enable Metrics/ParameterLists
-        warn_for_deprecated_arguments do |keywords|
-          keywords << :size if legacy_size != NOT_GIVEN
-          keywords << :format if legacy_format != NOT_GIVEN
-          keywords << :background_color if legacy_background_color != NOT_GIVEN
-          keywords << :text_color if legacy_text_color != NOT_GIVEN
-          keywords << :text if legacy_text != NOT_GIVEN
-        end
-
+      ##
+      # Produces a random placeholder image from https://via.placeholder.com.
+      #
+      # @param size [String] Specifies the image's size, dimensions separated by 'x'.
+      # @param format [String] Specifies the image's extension.
+      # @param background_color [String, Symbol] Specifies the background color, either in hexadecimal format (without #) or as :random.
+      # @param text_color [String, Symbol] Specifies the text color, either in hexadecimal format (without #) or as :random.
+      # @param text [String] Specifies a custom text to be used.
+      # @return [String]
+      #
+      # @example
+      #     # Keyword arguments: size, format, background_color, text_color, text
+      #   Faker::Placeholdit.image #=> "https://via.placeholder.com/300x300.png"
+      #   Faker::Placeholdit.image(size: '50x50') #=> "https://via.placeholder.com/50x50.png"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpg') #=> "https://via.placeholder.com/50x50.jpg"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'gif', background_color: 'ffffff') #=> "https://via.placeholder.com/50x50.gif/ffffff"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpeg', background_color: :random) #=> "https://via.placeholder.com/50x50.jpeg/39eba7"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpeg', background_color: 'ffffff', text_color: '000') #=> "https://via.placeholder.com/50x50.jpeg/ffffff/000"
+      #   Faker::Placeholdit.image(size: '50x50', format: 'jpg', background_color: 'ffffff', text_color: '000', text: 'Some Custom Text') #=> "https://via.placeholder.com/50x50.jpg/ffffff/000?text=Some Custom Text"
+      #
+      # @faker.version 1.6.0
+      def image(size: '300x300', format: 'png', background_color: nil, text_color: nil, text: nil)
         background_color = generate_color if background_color == :random
         text_color = generate_color if text_color == :random
 
@@ -24,7 +35,7 @@ module Faker
         raise ArgumentError, "background_color must be a hex value without '#'" unless background_color.nil? || background_color =~ /((?:^\h{3}$)|(?:^\h{6}$)){1}(?!.*\H)/
         raise ArgumentError, "text_color must be a hex value without '#'" unless text_color.nil? || text_color =~ /((?:^\h{3}$)|(?:^\h{6}$)){1}(?!.*\H)/
 
-        image_url = "https://placehold.it/#{size}.#{format}"
+        image_url = "https://via.placeholder.com/#{size}.#{format}"
         image_url += "/#{background_color}" if background_color
         image_url += "/#{text_color}" if text_color
         image_url += "?text=#{text}" if text

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
       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

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