faker 2.2.0 → 3.2.2

data/lib/faker/default/finance.rb

@@ -6,7 +6,21 @@ module Faker
                            diners_club jcb switch solo dankort
                            maestro forbrugsforeningen laser].freeze
 
+    MARKET_LIST = %i[nyse nasdaq].freeze
+
     class << self
+      ##
+      # Produces a random credit card number.
+      #
+      # @param types [String] Specific credit card type.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.credit_card #=> "3018-348979-1853"
+      #   Faker::Finance.credit_card(:mastercard) #=> "6771-8921-2291-6236"
+      #   Faker::Finance.credit_card(:mastercard, :visa) #=> "4448-8934-1277-7195"
+      #
+      # @faker.version 1.2.0
       def credit_card(*types)
         types = CREDIT_CARD_TYPES if types.empty?
         type = sample(types)
@@ -14,9 +28,9 @@ module Faker
 
         # calculate the luhn checksum digit
         multiplier = 1
-        luhn_sum = template.gsub(/[^0-9]/, '').split('').reverse.map(&:to_i).inject(0) do |sum, digit|
+        luhn_sum = template.gsub(/[^0-9]/, '').chars.reverse.map(&:to_i).inject(0) do |sum, digit|
           multiplier = (multiplier == 2 ? 1 : 2)
-          sum + (digit * multiplier).to_s.split('').map(&:to_i).inject(0) { |digit_sum, cur| digit_sum + cur }
+          sum + (digit * multiplier).to_s.chars.map(&:to_i).inject(0) { |digit_sum, cur| digit_sum + cur }
         end
 
         # the sum plus whatever the last digit is must be a multiple of 10. So, the
@@ -26,12 +40,19 @@ module Faker
         template.gsub('L', luhn_digit.to_s)
       end
 
-      def vat_number(legacy_country = NOT_GIVEN, country: 'BR')
-        if legacy_country != NOT_GIVEN
-          warn_with_uplevel 'Passing `country` with the 1st argument of `Finance.vat_number` is deprecated. Use keyword argument like `Finance.vat_number(country: ...)` instead.', uplevel: 1
-          country = legacy_country
-        end
-
+      ##
+      # Produces a random vat number.
+      #
+      # @param country [String] Two capital letter country code to use for the vat number.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.vat_number #=> "BR38.395.329/2471-83"
+      #   Faker::Finance.vat_number('DE') #=> "DE593306671"
+      #   Faker::Finance.vat_number('ZA') #=> "ZA79494416181"
+      #
+      # @faker.version 1.9.2
+      def vat_number(country: 'BR')
         numerify(fetch("finance.vat_number.#{country}"))
       rescue I18n::MissingTranslationData
         raise ArgumentError, "Could not find vat number for #{country}"
@@ -40,6 +61,52 @@ module Faker
       def vat_number_keys
         translate('faker.finance.vat_number').keys
       end
+
+      ##
+      # Returns a randomly-selected stock ticker from a specified market.
+      #
+      # @param markets [String] The name of the market to choose the ticker from (e.g. NYSE, NASDAQ)
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.ticker #=> 'AMZN'
+      #   Faker::Finance.vat_number('NASDAQ') #=> 'GOOG'
+      #
+      # @faker.version next
+      def ticker(*markets)
+        markets = MARKET_LIST if markets.empty?
+        market = sample(markets)
+        fetch("finance.ticker.#{market}")
+      rescue I18n::MissingTranslationData
+        raise ArgumentError, "Could not find market named #{market}"
+      end
+
+      ##
+      # Returns a randomly-selected stock market.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.stock_market #=> 'NASDAQ'
+      #
+      # @faker.version next
+      def stock_market
+        fetch('finance.stock_market')
+      end
+
+      ##
+      # Returns a random condominium fiscal code.
+      #
+      # @param country [String] Two capital letter country code to use for the vat number.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Finance.condominium_fiscal_code #=> "012345678"
+      #
+      # @faker.version next
+      def condominium_fiscal_code(country: 'IT')
+        numerify(fetch("finance.condominium_fiscal_code.#{country}"))
+      end
     end
   end
 end

data/lib/faker/default/food.rb

@@ -5,45 +5,135 @@ module Faker
     flexible :food
 
     class << self
-      # Retrieves a typical dish from each country
+      ##
+      # Retrieves an allergen.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.allergen #=> "Peanuts"
+      #
+      # @faker.version next
+      def allergen
+        fetch('food.allergens')
+      end
+
+      ##
+      # Retrieves a typical dish from each country.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.dish #=> "Feijoada"
+      #
+      # @faker.version 1.8.0
       def dish
         fetch('food.dish')
       end
 
+      ##
       # Retrieves a description about some dish
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.description #=> "Breaded fried chicken with waffles. Served with maple syrup."
+      #
+      # @faker.version 1.9.0
       def description
         fetch('food.descriptions')
       end
 
+      ##
       # Retrieves an ingredient
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.ingredient #=> "Olives"
+      #
+      # @faker.version 1.7.0
       def ingredient
         fetch('food.ingredients')
       end
 
+      ##
       # Retrieves a fruit
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.fruits #=> "Papaya"
+      #
+      # @faker.version 1.9.0
       def fruits
         fetch('food.fruits')
       end
 
+      ##
       # Retrieves a vegetable
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.vegetables #=> "Broccolini"
+      #
+      # @faker.version 1.9.0
       def vegetables
         fetch('food.vegetables')
       end
 
+      ##
       # Retrieves some random spice
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.spice #=> "Garlic Chips"
+      #
+      # @faker.version 1.7.0
       def spice
         fetch('food.spices')
       end
 
+      ##
       # Retrieves cooking measures
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.measurement #=> "1/3"
+      #
+      # @faker.version 1.7.0
       def measurement
-        fetch('food.measurement_sizes') + ' ' + fetch('food.measurements')
+        "#{fetch('food.measurement_sizes')} #{fetch('food.measurements')}"
       end
 
-      # Retrieves metric mesurements
+      ##
+      # Retrieves metric measurements
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.metric_measurement #=> "centiliter"
+      #
+      # @faker.version 1.8.3
       def metric_measurement
         fetch('food.metric_measurements')
       end
+
+      ##
+      # Retrieves ethnic category
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Food.ethnic_category #=> "Indian cuisine"
+      #
+      # @faker.version next
+      def ethnic_category
+        fetch('food.ethnic_category')
+      end
     end
   end
 end

data/lib/faker/default/funny_name.rb

@@ -5,10 +5,28 @@ module Faker
     flexible :funny_name
 
     class << self
+      ##
+      # Retrieves a funny name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::FunnyName.name #=> "Sam Pull"
+      #
+      # @faker.version 1.8.0
       def name
         fetch('funny_name.name')
       end
 
+      ##
+      # Retrieves a funny two word name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::FunnyName.two_word_name #=> "Shirley Knot"
+      #
+      # @faker.version 1.8.0
       def two_word_name
         two_word_names = fetch_all('funny_name.name').select do |name|
           name.count(' ') == 1
@@ -17,6 +35,15 @@ module Faker
         sample(two_word_names)
       end
 
+      ##
+      # Retrieves a funny three word name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::FunnyName.three_word_name #=> "Carson O. Gin"
+      #
+      # @faker.version 1.8.0
       def three_word_name
         three_word_names = fetch_all('funny_name.name').select do |name|
           name.count(' ') == 2
@@ -25,6 +52,15 @@ module Faker
         sample(three_word_names)
       end
 
+      ##
+      # Retrieves a funny four word name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::FunnyName.four_word_name #=> "Maude L. T. Ford"
+      #
+      # @faker.version 1.8.0
       def four_word_name
         four_word_names = fetch_all('funny_name.name').select do |name|
           name.count(' ') == 3
@@ -33,6 +69,15 @@ module Faker
         sample(four_word_names)
       end
 
+      ##
+      # Retrieves a funny name with an initial.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::FunnyName.name_with_initial #=> "Heather N. Yonn"
+      #
+      # @faker.version 1.8.0
       def name_with_initial
         names_with_initials = fetch_all('funny_name.name').select do |name|
           name.count('.').positive?

data/lib/faker/default/gender.rb

@@ -3,13 +3,44 @@
 module Faker
   class Gender < Base
     class << self
+      ##
+      # Produces the name of a gender identity.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Gender.type #=> "Non-binary"
+      #
+      # @faker.version 1.9.0
       def type
         fetch('gender.types')
       end
 
+      ##
+      # Produces either 'Male' or 'Female'.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Gender.binary_type #=> "Female"
+      #
+      # @faker.version 1.9.0
       def binary_type
         fetch('gender.binary_types')
       end
+
+      ##
+      # Produces either 'f' or 'm'.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Gender.short_binary_type #=> "f"
+      #
+      # @faker.version 2.13.0
+      def short_binary_type
+        fetch('gender.short_binary_types')
+      end
     end
   end
 end

data/lib/faker/default/greek_philosophers.rb

@@ -3,10 +3,28 @@
 module Faker
   class GreekPhilosophers < Base
     class << self
+      ##
+      # Produces the name of a Greek philosopher.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::GreekPhilosophers.name #=> "Socrates"
+      #
+      # @faker.version 1.9.0
       def name
         fetch('greek_philosophers.names')
       end
 
+      ##
+      # Produces a quote from a Greek philosopher.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::GreekPhilosophers.quote #=> "Only the educated are free."
+      #
+      # @faker.version 1.9.0
       def quote
         fetch('greek_philosophers.quotes')
       end

data/lib/faker/default/hacker.rb

@@ -1,35 +1,93 @@
 # frozen_string_literal: true
 
-# Port of http://shinytoylabs.com/jargon/
 module Faker
+  # Port of http://shinytoylabs.com/jargon/
+  # Are you having trouble writing tech-savvy dialogue for your latest screenplay?
+  # Worry not! Hollywood-grade technical talk is ready to fill out any form where you need to look smart.
   class Hacker < Base
     flexible :hacker
 
     class << self
+      ##
+      # Produces something smart.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.say_something_smart
+      #     #=> "Try to compress the SQL interface, maybe it will program the back-end hard drive!"
+      #
+      # @faker.version 1.4.0
       def say_something_smart
         sample(phrases)
       end
 
+      ##
+      # Short technical abbreviations.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.abbreviation #=> "RAM"
+      #
+      # @faker.version 1.4.0
       def abbreviation
         fetch('hacker.abbreviation')
       end
 
+      ##
+      # Hacker-centric adjectives.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.adjective #=> "open-source"
+      #
+      # @faker.version 1.4.0
       def adjective
         fetch('hacker.adjective')
       end
 
+      ##
+      # Only the best hacker-related nouns.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.noun #=> "bandwidth"
+      #
+      # @faker.version 1.4.0
       def noun
         fetch('hacker.noun')
       end
 
+      ##
+      # Actions that hackers take.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.verb #=> "bypass"
+      #
+      # @faker.version 1.4.0
       def verb
         fetch('hacker.verb')
       end
 
+      ##
+      # Produces a verb that ends with '-ing'.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Hacker.ingverb #=> "synthesizing"
+      #
+      # @faker.version 1.4.0
       def ingverb
         fetch('hacker.ingverb')
       end
 
+      # @private
       def phrases
         ["If we #{verb} the #{noun}, we can get to the #{abbreviation} #{noun} through the #{adjective} #{abbreviation} #{noun}!",
          "We need to #{verb} the #{adjective} #{abbreviation} #{noun}!",