faker 1.9.6 → 2.7.0

data/lib/faker/default/json.rb

@@ -3,7 +3,12 @@ module Faker
     require 'json'
 
     class << self
-      def shallow_json(width = 3, options = { key: 'Name.first_name', value: 'Name.first_name' })
+      def shallow_json(legacy_width = NOT_GIVEN, legacy_options = NOT_GIVEN, width: 3, options: { key: 'Name.first_name', value: 'Name.first_name' })
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :width if legacy_width != NOT_GIVEN
+          keywords << :options if legacy_options != NOT_GIVEN
+        end
+
         options[:key] = 'Faker::' + options[:key]
         options[:value] = 'Faker::' + options[:value]
 
@@ -11,7 +16,19 @@ module Faker
         JSON.generate(hash)
       end
 
-      def add_depth_to_json(json = shallow_json, width = 3, options = { key: 'Name.first_name', value: 'Name.first_name' })
+      # rubocop:disable Metrics/ParameterLists
+      def add_depth_to_json(legacy_json = NOT_GIVEN, legacy_width = NOT_GIVEN, legacy_options = NOT_GIVEN, json: shallow_json, width: 3, options: { key: 'Name.first_name', value: 'Name.first_name' })
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :json if legacy_json != NOT_GIVEN
+        end
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :width if legacy_width != NOT_GIVEN
+        end
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :options if legacy_options != NOT_GIVEN
+        end
+
         options[:key] = 'Faker::' + options[:key]
         options[:value] = 'Faker::' + options[:value]
 

data/lib/faker/default/lorem.rb

@@ -8,8 +8,13 @@ module Faker
         sample(translate('faker.lorem.words'))
       end
 
-      def words(num = 3, supplemental = false)
-        resolved_num = resolve(num)
+      def words(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+        end
+
+        resolved_num = resolve(number)
         word_list = (
           translate('faker.lorem.words') +
           (supplemental ? translate('faker.lorem.supplemental') : [])
@@ -22,44 +27,110 @@ module Faker
         sample(Types::CHARACTERS)
       end
 
-      def characters(char_count = 255)
-        Alphanumeric.alphanumeric(char_count)
+      ##
+      # Produces a random string of alphanumeric characters
+      #
+      # @param number [Integer] The number of characters to generate
+      # @param min_alpha [Integer] The minimum number of alphabetic to add to the string
+      # @param min_numeric [Integer] The minimum number of numbers to add to the string
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Lorem.characters #=> "uw1ep04lhs0c4d931n1jmrspprf5w..."
+      #   Faker::Lorem.characters(number: 10) #=> "ang9cbhoa8"
+      #   Faker::Lorem.characters(number: 10, min_alpha: 4) #=> "ang9cbhoa8"
+      #   Faker::Lorem.characters(number: 10, min_alpha: 4, min_numeric: 1) #=> "ang9cbhoa8"
+      #
+      # @faker.version 2.1.3
+      def characters(legacy_number = NOT_GIVEN, number: 255, min_alpha: 0, min_numeric: 0)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+        end
+
+        Alphanumeric.alphanumeric(number: number, min_alpha: min_alpha, min_numeric: min_numeric)
       end
 
       def multibyte
         sample(translate('faker.lorem.multibyte')).pack('C*').force_encoding('utf-8')
       end
 
-      def sentence(word_count = 4, supplemental = false, random_words_to_add = 0)
-        words(word_count + rand(random_words_to_add.to_i), supplemental).join(' ').capitalize + locale_period
+      # rubocop:disable Metrics/ParameterLists
+      def sentence(legacy_word_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, supplemental: false, random_words_to_add: 0)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :word_count if legacy_word_count != NOT_GIVEN
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+          keywords << :random_words_to_add if legacy_random_words_to_add != NOT_GIVEN
+        end
+
+        words(number: word_count + rand(random_words_to_add.to_i), supplemental: supplemental).join(' ').capitalize + locale_period
       end
 
-      def sentences(sentence_count = 3, supplemental = false)
-        1.upto(resolve(sentence_count)).collect { sentence(3, supplemental) }
+      def sentences(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+        end
+
+        1.upto(resolve(number)).collect { sentence(word_count: 3, supplemental: supplemental) }
       end
 
-      def paragraph(sentence_count = 3, supplemental = false, random_sentences_to_add = 0)
-        sentences(resolve(sentence_count) + rand(random_sentences_to_add.to_i), supplemental).join(locale_space)
+      # rubocop:disable Metrics/ParameterLists
+      def paragraph(legacy_sentence_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_sentences_to_add = NOT_GIVEN, sentence_count: 3, supplemental: false, random_sentences_to_add: 0)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :sentence_count if legacy_sentence_count != NOT_GIVEN
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+          keywords << :random_sentences_to_add if legacy_random_sentences_to_add != NOT_GIVEN
+        end
+
+        sentences(number: resolve(sentence_count) + rand(random_sentences_to_add.to_i), supplemental: supplemental).join(locale_space)
       end
 
-      def paragraphs(paragraph_count = 3, supplemental = false)
-        1.upto(resolve(paragraph_count)).collect { paragraph(3, supplemental) }
+      def paragraphs(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+        end
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+        end
+
+        1.upto(resolve(number)).collect { paragraph(sentence_count: 3, supplemental: supplemental) }
       end
 
-      def paragraph_by_chars(chars = 256, supplemental = false)
-        paragraph = paragraph(3, supplemental)
+      def paragraph_by_chars(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 256, supplemental: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+        end
+
+        paragraph = paragraph(sentence_count: 3, supplemental: supplemental)
 
-        paragraph += ' ' + paragraph(3, supplemental) while paragraph.length < chars
+        paragraph += ' ' + paragraph(sentence_count: 3, supplemental: supplemental) while paragraph.length < number
 
-        paragraph[0...chars - 1] + '.'
+        paragraph[0...number - 1] + '.'
       end
 
-      def question(word_count = 4, supplemental = false, random_words_to_add = 0)
-        words(word_count + rand(random_words_to_add), supplemental).join(' ').capitalize + locale_question_mark
+      # rubocop:disable Metrics/ParameterLists
+      def question(legacy_word_count = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, legacy_random_words_to_add = NOT_GIVEN, word_count: 4, supplemental: false, random_words_to_add: 0)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :word_count if legacy_word_count != NOT_GIVEN
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+          keywords << :random_words_to_add if legacy_random_words_to_add != NOT_GIVEN
+        end
+
+        words(number: word_count + rand(random_words_to_add), supplemental: supplemental).join(' ').capitalize + locale_question_mark
       end
 
-      def questions(question_count = 3, supplemental = false)
-        1.upto(resolve(question_count)).collect { question(3, supplemental) }
+      def questions(legacy_number = NOT_GIVEN, legacy_supplemental = NOT_GIVEN, number: 3, supplemental: false)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :number if legacy_number != NOT_GIVEN
+          keywords << :supplemental if legacy_supplemental != NOT_GIVEN
+        end
+
+        1.upto(resolve(number)).collect { question(word_count: 3, supplemental: supplemental) }
       end
 
       private

data/lib/faker/default/lorem_flickr.rb

@@ -5,23 +5,56 @@ module Faker
     class << self
       SUPPORTED_COLORIZATIONS = %w[red green blue].freeze
 
-      def image(size = '300x300', search_terms = [], match_all = false)
+      # rubocop:disable Metrics/ParameterLists
+      def image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: [], match_all: false)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
+        end
+
         build_url(size, nil, search_terms, match_all)
       end
 
-      def grayscale_image(size = '300x300', search_terms = ['all'], match_all = false)
+      # rubocop:disable Metrics/ParameterLists
+      def grayscale_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
+        end
+
         raise ArgumentError, 'Search terms must be specified for grayscale images' unless search_terms.any?
 
         build_url(size, 'g', search_terms, match_all)
       end
 
-      def pixelated_image(size = '300x300', search_terms = ['all'], match_all = false)
+      # rubocop:disable Metrics/ParameterLists
+      def pixelated_image(legacy_size = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', search_terms: ['all'], match_all: false)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
+        end
+
         raise ArgumentError, 'Search terms must be specified for pixelated images' unless search_terms.any?
 
         build_url(size, 'p', search_terms, match_all)
       end
 
-      def colorized_image(size = '300x300', color = 'red', search_terms = ['all'], match_all = false)
+      # rubocop:disable Metrics/ParameterLists
+      def colorized_image(legacy_size = NOT_GIVEN, legacy_color = NOT_GIVEN, legacy_search_terms = NOT_GIVEN, legacy_match_all = NOT_GIVEN, size: '300x300', color: 'red', search_terms: ['all'], match_all: false)
+        # rubocop:enable Metrics/ParameterLists
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :color if legacy_color != NOT_GIVEN
+          keywords << :search_terms if legacy_search_terms != NOT_GIVEN
+          keywords << :match_all if legacy_match_all != NOT_GIVEN
+        end
+
         raise ArgumentError, 'Search terms must be specified for colorized images' unless search_terms.any?
         raise ArgumentError, "Supported colorizations are #{SUPPORTED_COLORIZATIONS.join(', ')}" unless SUPPORTED_COLORIZATIONS.include?(color)
 
@@ -33,7 +66,7 @@ module Faker
       def build_url(size, format, search_terms, match_all)
         raise ArgumentError, 'Size should be specified in format 300x300' unless size =~ /^[0-9]+x[0-9]+$/
 
-        url_parts = ['http://loremflickr.com']
+        url_parts = ['https://loremflickr.com']
         url_parts << format
         url_parts += size.split('x')
         url_parts << search_terms.compact.join(',') if search_terms.any?

data/lib/faker/default/lorem_pixel.rb

@@ -18,7 +18,16 @@ module Faker
                                 transport].freeze
 
       # rubocop:disable Metrics/ParameterLists
-      def image(size = '300x300', is_gray = false, category = nil, number = nil, text = nil, secure: true)
+      def image(legacy_size = NOT_GIVEN, legacy_is_gray = NOT_GIVEN, legacy_category = NOT_GIVEN, legacy_number = NOT_GIVEN, legacy_text = NOT_GIVEN, legacy_secure = NOT_GIVEN, size: '300x300', is_gray: false, category: nil, number: nil, text: nil, secure: true)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :size if legacy_size != NOT_GIVEN
+          keywords << :is_gray if legacy_is_gray != NOT_GIVEN
+          keywords << :category if legacy_category != NOT_GIVEN
+          keywords << :number if legacy_number != NOT_GIVEN
+          keywords << :text if legacy_text != NOT_GIVEN
+          keywords << :secure if legacy_secure != NOT_GIVEN
+        end
+
         raise ArgumentError, 'Size should be specified in format 300x300' unless size =~ /^[0-9]+x[0-9]+$/
         raise ArgumentError, "Supported categories are #{SUPPORTED_CATEGORIES.join(', ')}" unless category.nil? || SUPPORTED_CATEGORIES.include?(category)
         raise ArgumentError, 'Category required when number is passed' if !number.nil? && category.nil?

data/lib/faker/default/markdown.rb

@@ -8,7 +8,7 @@ module Faker
       end
 
       def emphasis
-        paragraph = Faker::Lorem.paragraph(3)
+        paragraph = Faker::Lorem.paragraph(sentence_count: 3)
         words = paragraph.split(' ')
         position = rand(0..words.length - 1)
         formatting = fetch('markdown.emphasis')
@@ -21,7 +21,7 @@ module Faker
 
         result = []
         number.times do |i|
-          result << "#{i}. #{Faker::Lorem.sentence(1)} \n"
+          result << "#{i}. #{Faker::Lorem.sentence(word_count: 1)} \n"
         end
         result.join('')
       end
@@ -31,17 +31,17 @@ module Faker
 
         result = []
         number.times do |_i|
-          result << "* #{Faker::Lorem.sentence(1)} \n"
+          result << "* #{Faker::Lorem.sentence(word_count: 1)} \n"
         end
         result.join('')
       end
 
       def inline_code
-        "`#{Faker::Lorem.sentence(1)}`"
+        "`#{Faker::Lorem.sentence(word_count: 1)}`"
       end
 
       def block_code
-        "```ruby\n#{Lorem.sentence(1)}\n```"
+        "```ruby\n#{Lorem.sentence(word_count: 1)}\n```"
       end
 
       def table
@@ -59,11 +59,16 @@ module Faker
         send(method_list[rand(0..method_list.length - 1)])
       end
 
-      def sandwich(sentences = 3, repeat = 1)
+      def sandwich(legacy_sentences = NOT_GIVEN, legacy_repeat = NOT_GIVEN, sentences: 3, repeat: 1)
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :sentences if legacy_sentences != NOT_GIVEN
+          keywords << :repeat if legacy_repeat != NOT_GIVEN
+        end
+
         text_block = []
         text_block << headers
         repeat.times do
-          text_block << Faker::Lorem.paragraph(sentences)
+          text_block << Faker::Lorem.paragraph(sentence_count: sentences)
           text_block << random
         end
         text_block.join("\n")

data/lib/faker/default/marketing.rb

@@ -5,6 +5,15 @@ module Faker
     flexible :marketing
 
     class << self
+      ##
+      # Produces the name of a video game console or platform.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Marketing.buzzwords #=> "rubber meets the road"
+      #
+      # @faker.version 1.9.4
       def buzzwords
         fetch('marketing.buzzwords')
       end

data/lib/faker/default/measurement.rb

@@ -6,35 +6,67 @@ module Faker
       ALL = 'all'
       NONE = 'none'
 
-      def height(amount = rand(10))
+      def height(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'height')
       end
 
-      def length(amount = rand(10))
+      def length(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'length')
       end
 
-      def volume(amount = rand(10))
+      def volume(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'volume')
       end
 
-      def weight(amount = rand(10))
+      def weight(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'weight')
       end
 
-      def metric_height(amount = rand(10))
+      def metric_height(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'metric_height')
       end
 
-      def metric_length(amount = rand(10))
+      def metric_length(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'metric_length')
       end
 
-      def metric_volume(amount = rand(10))
+      def metric_volume(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'metric_volume')
       end
 
-      def metric_weight(amount = rand(10))
+      def metric_weight(legacy_amount = NOT_GIVEN, amount: rand(10))
+        warn_for_deprecated_arguments do |keywords|
+          keywords << :amount if legacy_amount != NOT_GIVEN
+        end
+
         define_measurement_locale(amount, 'metric_weight')
       end
 

data/lib/faker/default/military.rb

@@ -3,22 +3,67 @@
 module Faker
   class Military < Base
     class << self
+      ##
+      # Produces a rank in the U.S. Army.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.army_rank #=> "Staff Sergeant"
+      #
+      # @faker.version 1.9.0
       def army_rank
         fetch('military.army_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Marines.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.marines_rank #=> "Gunnery Sergeant"
+      #
+      # @faker.version 1.9.0
       def marines_rank
         fetch('military.marines_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Navy.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.navy_rank #=> "Seaman"
+      #
+      # @faker.version 1.9.0
       def navy_rank
         fetch('military.navy_rank')
       end
 
+      ##
+      # Produces a rank in the U.S. Air Force.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.air_force_rank #=> "Captain"
+      #
+      # @faker.version 1.9.0
       def air_force_rank
         fetch('military.air_force_rank')
       end
 
+      ##
+      # Produces a U.S. Department of Defense Paygrade.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Military.dod_paygrade #=> "E-6"
+      #
+      # @faker.version 1.9.0
       def dod_paygrade
         fetch('military.dod_paygrade')
       end