faker 2.2.0 → 3.2.2

data/lib/faker/default/vehicle.rb

@@ -6,162 +6,325 @@ module Faker
 
     MILEAGE_MIN = 10_000
     MILEAGE_MAX = 90_000
-    VIN_LETTERS = 'ABCDEFGHJKLMNPRSTUVWXYZ'
-    VIN_MAP = '0123456789X'
-    VIN_WEIGHTS = '8765432X098765432'
-    VIN_REGEX = /^[A-Z0-9]{3}[A-Z0-9]{5}[A-Z0-9]{1}[A-Z0-9]{1}[A-Z0-0]{1}[A-Z0-9]{1}\d{5}$/
+    VIN_KEYSPACE = %w[A B C D E F G H J K L M N P R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9].freeze
+    VIN_TRANSLITERATION = { A: 1, B: 2, C: 3, D: 4, E: 5, F: 6, G: 7, H: 8, J: 1, K: 2, L: 3, M: 4, N: 5, P: 7, R: 9, S: 2, T: 3, U: 4, V: 5, W: 6, X: 7, Y: 8, Z: 9 }.freeze
+    VIN_WEIGHT = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2].freeze
     SG_CHECKSUM_WEIGHTS = [3, 14, 2, 12, 2, 11, 1].freeze
     SG_CHECKSUM_CHARS = 'AYUSPLJGDBZXTRMKHEC'
 
     class << self
+      # Produces a random vehicle VIN number.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.vin #=> "LLDWXZLG77VK2LUUF"
+      #
+      # @faker.version 1.6.4
       def vin
-        regexify(VIN_REGEX)
+        generate(:string) do |g|
+          g.letter(name: :wmi, ranges: ['100'..'199', '400'..'499', '500'..'599', '700'..'799', '7A0'..'7F9'])
+          g.letter(name: :vds, length: 5, ranges: [VIN_KEYSPACE])
+          g.computed(name: :checksum, deps: %i[wmi vds model_year plant_code vis]) do |wmi, vds, model_year, plant_code, vis|
+            checksum = "#{wmi}#{vds}0#{model_year}#{plant_code}#{vis}".chars.each_with_index.map do |char, i|
+              value = (char =~ /\A\d\z/ ? char.to_i : VIN_TRANSLITERATION[char.to_sym])
+              value * VIN_WEIGHT[i]
+            end.inject(:+) % 11
+
+            if checksum == 10
+              'X'
+            else
+              checksum
+            end
+          end
+          g.letter(name: :model_year, length: 1, ranges: [VIN_KEYSPACE - %w[U Z 0]])
+          g.letter(name: :plant_code, length: 1, ranges: [VIN_KEYSPACE])
+          g.int(name: :vis, length: 6)
+        end
       end
 
+      # Produces a random vehicle manufacturer.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.manufacture #=> "Lamborghini"
+      #
+      # @faker.version 1.6.4
       def manufacture
         fetch('vehicle.manufacture')
       end
 
+      ##
+      # Produces a random vehicle make.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.make #=> "Honda"
+      #
+      # @faker.version 1.6.4
       def make
         fetch('vehicle.makes')
       end
 
-      def model(legacy_make_of_model = NOT_GIVEN, make_of_model: '')
-        if legacy_make_of_model != NOT_GIVEN
-          warn_with_uplevel 'Passing `make_of_model` with the 1st argument of `Vehicle.model` is deprecated. Use keyword argument like `Vehicle.model(make_of_model: ...)` instead.', uplevel: 1
-          make_of_model = legacy_make_of_model
-        end
-
+      ##
+      # Produces a random vehicle model.
+      #
+      # @param make_of_model [String] Specific valid vehicle make.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.model #=> "A8"
+      #   Faker::Vehicle.model(make_of_model: 'Toyota') #=> "Prius"
+      #
+      # @faker.version 1.6.4
+      def model(make_of_model: '')
         return fetch("vehicle.models_by_make.#{make}") if make_of_model.empty?
 
         fetch("vehicle.models_by_make.#{make_of_model}")
       end
 
+      ##
+      # Produces a random vehicle make and model.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.make_and_model #=> "Dodge Charger"
+      #
+      # @faker.version 1.6.4
       def make_and_model
         m = make
 
         "#{m} #{model(make_of_model: m)}"
       end
 
+      ##
+      # Produces a random vehicle style.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.style #=> "ESi"
+      #
+      # @faker.version 1.6.4
       def style
         fetch('vehicle.styles')
       end
 
+      ##
+      # Produces a random vehicle color.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.color #=> "Red"
+      #
+      # @faker.version 1.6.4
       def color
         fetch('vehicle.colors')
       end
 
+      ##
+      # Produces a random vehicle transmission.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.transmission #=> "Automanual"
+      #
+      # @faker.version 1.6.4
       def transmission
         fetch('vehicle.transmissions')
       end
 
+      ##
+      # Produces a random vehicle drive type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.drive_type #=> "4x2/2-wheel drive"
+      #
+      # @faker.version 1.6.4
       def drive_type
         fetch('vehicle.drive_types')
       end
 
+      ##
+      # Produces a random vehicle fuel type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.fuel_type #=> "Diesel"
+      #
+      # @faker.version 1.6.4
       def fuel_type
         fetch('vehicle.fuel_types')
       end
 
+      ##
+      # Produces a random car type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.car_type #=> "Sedan"
+      #
+      # @faker.version 1.6.4
       def car_type
         fetch('vehicle.car_types')
       end
 
+      ##
+      # Produces a random engine cylinder count.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.engine_size #=> 6
+      #   Faker::Vehicle.engine #=> 4
+      #
+      # @faker.version 1.6.4
       def engine
         "#{sample(fetch_all('vehicle.doors'))} #{fetch('vehicle.cylinder_engine')}"
       end
 
       alias engine_size engine
 
+      ##
+      # Produces a random list of car options.
+      #
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Vehicle.car_options #=> ["DVD System", "MP3 (Single Disc)", "Tow Package", "CD (Multi Disc)", "Cassette Player", "Bucket Seats", "Cassette Player", "Leather Interior", "AM/FM Stereo", "Third Row Seats"]
+      #
+      # @faker.version 1.6.4
       def car_options
         Array.new(rand(5...10)) { fetch('vehicle.car_options') }
       end
 
+      ##
+      # Produces a random list of standard specs.
+      #
+      # @return [Array<String>]
+      #
+      # @example
+      #   Faker::Vehicle.standard_specs #=> ["Full-size spare tire w/aluminum alloy wheel", "Back-up camera", "Carpeted cargo area", "Silver accent IP trim finisher -inc: silver shifter finisher", "Back-up camera", "Water-repellent windshield & front door glass", "Floor carpeting"]
+      #
+      # @faker.version 1.6.4
       def standard_specs
         Array.new(rand(5...10)) { fetch('vehicle.standard_specs') }
       end
 
+      ##
+      # Produces a random vehicle door count.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Vehicle.doors #=> 1
+      #   Faker::Vehicle.door_count #=> 3
+      #
+      # @faker.version 1.6.4
       def doors
         sample(fetch_all('vehicle.doors'))
       end
       alias door_count doors
 
+      ##
+      # Produces a random car year between 1 and 15 years ago.
+      #
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Vehicle.year #=> 2008
+      #
+      # @faker.version 1.6.4
       def year
         Faker::Time.backward(days: rand_in_range(365, 5475), period: :all, format: '%Y').to_i
       end
 
-      def mileage(legacy_min = NOT_GIVEN, legacy_max = NOT_GIVEN, min: MILEAGE_MIN, max: MILEAGE_MAX)
-        if legacy_min != NOT_GIVEN
-          warn_with_uplevel 'Passing `min` with the 1st argument of `Vehicle.mileage` is deprecated. Use keyword argument like `Vehicle.mileage(min: ...)` instead.', uplevel: 1
-          min = legacy_min
-        end
-        if legacy_max != NOT_GIVEN
-          warn_with_uplevel 'Passing `max` with the 2nd argument of `Vehicle.mileage` is deprecated. Use keyword argument like `Vehicle.mileage(max: ...)` instead.', uplevel: 1
-          max = legacy_max
-        end
-
+      ##
+      # Produces a random mileage/kilometrage for a vehicle.
+      #
+      # @param min [Integer] Specific minimum limit for mileage generation.
+      # @param max [Integer] Specific maximum limit for mileage generation.
+      # @return [Integer]
+      #
+      # @example
+      #   Faker::Vehicle.mileage #=> 26961
+      #   Faker::Vehicle.mileage(min: 50_000) #=> 81557
+      #   Faker::Vehicle.mileage(min: 50_000, max: 250_000) #=> 117503
+      #   Faker::Vehicle.kilometrage #=> 35378
+      #
+      # @faker.version 1.6.4
+      def mileage(min: MILEAGE_MIN, max: MILEAGE_MAX)
         rand_in_range(min, max)
       end
 
       alias kilometrage mileage
 
-      def license_plate(legacy_state_abreviation = NOT_GIVEN, state_abreviation: '')
-        if legacy_state_abreviation != NOT_GIVEN
-          warn_with_uplevel 'Passing `state_abreviation` with the 1st argument of `Vehicle.license_plate` is deprecated. Use keyword argument like `Vehicle.license_plate(state_abreviation: ...)` instead.', uplevel: 1
-          state_abreviation = legacy_state_abreviation
-        end
-
-        return regexify(bothify(fetch('vehicle.license_plate'))) if state_abreviation.empty?
-
-        key = 'vehicle.license_plate_by_state.' + state_abreviation
+      ##
+      # Produces a random license plate number.
+      #
+      # @param state_abbreviation [String] Two letter state abbreviation for license plate generation.
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.license_plate #=> "DEP-2483"
+      #   Faker::Vehicle.license_plate(state_abbreviation: 'FL') #=> "977 UNU"
+      #
+      # @faker.version 1.6.4
+      def license_plate(state_abbreviation: '')
+        return regexify(bothify(fetch('vehicle.license_plate'))) if state_abbreviation.empty?
+
+        key = "vehicle.license_plate_by_state.#{state_abbreviation}"
         regexify(bothify(fetch(key)))
       end
 
+      ##
+      # Produces a random license plate number for Singapore.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Vehicle.singapore_license_plate #=> "SLV1854M"
+      #
+      # @faker.version 1.6.4
       def singapore_license_plate
         key = 'vehicle.license_plate'
         plate_number = regexify(bothify(fetch(key)))
         "#{plate_number}#{singapore_checksum(plate_number)}"
       end
 
-      private
-
-      def first_eight(number)
-        return number[0...8] unless number.nil?
-
-        regexify(VIN_REGEX)
-      end
-      alias last_eight first_eight
-
-      def calculate_vin_check_digit(vin)
-        sum = 0
-
-        vin.each_char.with_index do |c, i|
-          n = vin_char_to_number(c).to_i
-          weight = VIN_WEIGHTS[i].to_i
-          sum += weight * n
-        end
-
-        mod = sum % 11
-        mod == 10 ? 'X' : mod
+      ##
+      # Produces a car version
+      #
+      # @return [String]
+      #
+      # @example
+      #  Faker::Vehicle.version #=> "40 TFSI Premium"
+      #
+      # @faker.version next
+      def version
+        fetch('vehicle.version')
       end
 
-      def vin_char_to_number(char)
-        index = VIN_LETTERS.split('').index(char)
-
-        return char.to_i if index.nil?
-
-        VIN_MAP[index]
-      end
+      private
 
       def singapore_checksum(plate_number)
-        padded_alphabets = format('%3s', plate_number[/^[A-Z]+/]).tr(' ', '-').split('')
-        padded_digits = format('%04d', plate_number[/\d+/]).split('').map(&:to_i)
+        padded_alphabets = format('%3s', plate_number[/^[A-Z]+/]).tr(' ', '-').chars
+        padded_digits = format('%04d', plate_number[/\d+/]).chars.map(&:to_i)
         sum = [*padded_alphabets, *padded_digits].each_with_index.reduce(0) do |memo, (char, i)|
           value = char.is_a?(Integer) ? char : char.ord - 64
           memo + (SG_CHECKSUM_WEIGHTS[i] * value)
         end
 
-        SG_CHECKSUM_CHARS.split('')[sum % 19]
+        SG_CHECKSUM_CHARS.chars[sum % 19]
       end
     end
   end

data/lib/faker/default/verb.rb

@@ -3,22 +3,67 @@
 module Faker
   class Verb < Base
     class << self
+      ##
+      # Produces the base form of a random verb.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Verb.base #=> "hurt"
+      #
+      # @faker.version 1.9.0
       def base
         fetch('verbs.base')
       end
 
+      ##
+      # Produces a random verb in past tense.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Verb.past #=> "completed"
+      #
+      # @faker.version 1.9.0
       def past
         fetch('verbs.past')
       end
 
+      ##
+      # Produces a random verb in past participle.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Verb.past_participle #=> "digested"
+      #
+      # @faker.version 1.9.0
       def past_participle
         fetch('verbs.past_participle')
       end
 
+      ##
+      # Produces a random verb in simple present.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Verb.simple_present #=> "climbs"
+      #
+      # @faker.version 1.9.0
       def simple_present
         fetch('verbs.simple_present')
       end
 
+      ##
+      # Produces a random verb in the .ing form.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Verb.ing_form #=> "causing"
+      #
+      # @faker.version 1.9.0
       def ing_form
         fetch('verbs.ing_form')
       end

data/lib/faker/default/vulnerability_identifier.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Faker
+  class VulnerabilityIdentifier < Base
+    class << self
+      ##
+      # Produces a Common Vulnerabilities and Exposures (CVE) identifier.
+      #
+      # @param year [Integer] The year-part of the CVE identifier (defaults to the current year)
+      # @return [String]
+      #
+      # @example
+      #   Faker::VulnerabilityIdentifier.cve #=> "CVE-2021-1337"
+      #   Faker::VulnerabilityIdentifier.cve(year: 1999) #=> "CVE-1999-0523"
+      #
+      # @faker.version next
+      def cve(year: ::Date.today.year)
+        index = rand_in_range(1, 99_999).to_s.rjust(4, '0')
+        "CVE-#{year}-#{index}"
+      end
+    end
+  end
+end

data/lib/faker/default/world_cup.rb

@@ -3,37 +3,73 @@
 module Faker
   class WorldCup < Base
     class << self
+      ##
+      # Produces a national team name.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.team #=> "Iran"
+      #
+      # @faker.version 1.9.0
       def team
         fetch('world_cup.teams')
       end
 
+      ##
+      # Produces a city name hosting the World Cup match.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.city #=> "Moscow"
+      #
+      # @faker.version 2.13.0
       def city
         fetch('world_cup.cities')
       end
 
+      ##
+      # Produces the name of a stadium that has hosted a World Cup match.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.stadium #=> "Rostov Arena"
+      #
+      # @faker.version 2.13.0
       def stadium
         fetch('world_cup.stadiums')
       end
 
-      def group(legacy_group = NOT_GIVEN, group: 'group_A')
-        if legacy_group != NOT_GIVEN
-          warn_with_uplevel 'Passing `group` with the 1st argument of `WorldCup.group` is deprecated. Use keyword argument like `WorldCup.group(group: ...)` instead.', uplevel: 1
-          group = legacy_group
-        end
-
+      ##
+      # Produces a random national team name from a group.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.group(group: 'group_B') #=> "Spain"
+      # @example
+      #   Faker::WorldCup.group #=> "Russia"
+      #
+      # @faker.version 2.13.0
+      def group(group: 'group_A')
         fetch("world_cup.groups.#{group}")
       end
 
-      def roster(legacy_country = NOT_GIVEN, legacy_type = NOT_GIVEN, country: 'Egypt', type: 'coach')
-        if legacy_country != NOT_GIVEN
-          warn_with_uplevel 'Passing `country` with the 1st argument of `WorldCup.roster` is deprecated. Use keyword argument like `WorldCup.roster(country: ...)` instead.', uplevel: 1
-          country = legacy_country
-        end
-        if legacy_type != NOT_GIVEN
-          warn_with_uplevel 'Passing `type` with the 2nd argument of `WorldCup.roster` is deprecated. Use keyword argument like `WorldCup.roster(type: ...)` instead.', uplevel: 1
-          type = legacy_type
-        end
-
+      ##
+      # Produces a random name from national team roster.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::WorldCup.roster #=> "Hector Cuper"
+      #
+      # @example
+      #   Faker::WorldCup.roster(country: 'Spain', type: 'forwards') #=> "Diego Costa"
+      #
+      # @faker.version 2.13.0
+      def roster(country: 'Egypt', type: 'coach')
         fetch("world_cup.rosters.#{country}.#{type}")
       end
     end

data/lib/faker/fantasy/tolkien.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Faker
+  class Fantasy
+    class Tolkien < Base
+      flexible :tolkien
+
+      class << self
+        ##
+        # Produces a character from Tolkien's legendarium
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Fantasy::Tolkien.character
+        #    #=> "Goldberry"
+        #
+        # @faker.version next
+        def character
+          fetch('tolkien.characters')
+        end
+
+        ##
+        # Produces a location from Tolkien's legendarium
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Fantasy::Tolkien.location
+        #    #=> "Helm's Deep"
+        #
+        # @faker.version next
+        def location
+          fetch('tolkien.locations')
+        end
+
+        ##
+        # Produces a race from Tolkien's legendarium
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Fantasy::Tolkien.race
+        #     #=> "Uruk-hai"
+        #
+        # @faker.version next
+        def race
+          fetch('tolkien.races')
+        end
+
+        ##
+        # Produces the name of a poem from Tolkien's legendarium
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Fantasy::Tolkien.poem
+        #     #=> "Chip the glasses and crack the plates"
+        #
+        # @faker.version next
+        def poem
+          fetch('tolkien.poems')
+        end
+      end
+    end
+  end
+end

data/lib/faker/games/clash_of_clans.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Faker
+  class Games
+    class ClashOfClans < Base
+      class << self
+        ##
+        # Produces the name of a troop from Clash of Clans.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::ClashOfClans.troop #=> "Barbarian"
+        #
+        # @faker.version next
+        def troop
+          fetch('games.clash_of_clans.troops')
+        end
+
+        ##
+        # Produces the name of a rank from Clash Of Clans.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::ClashOfClans.rank #=> "Legend"
+        #
+        # @faker.version next
+        def rank
+          fetch('games.clash_of_clans.ranks')
+        end
+
+        ##
+        # Produces the name of a defensive building from Clash Of Clans.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Games::ClashOfClans.defensive_building #=> "Cannon"
+        #
+        # @faker.version next
+        def defensive_building
+          fetch('games.clash_of_clans.defensive_buildings')
+        end
+      end
+    end
+  end
+end