Add birds (#2299)

* added tests for all simple bird look-ups

* added bird words (bird is the word)

* added birds!

* added tests for plausible and implausible common names for birds and correcting tests for adjectives and common_name roots

* added .plausible_common_name and .implausible_common_name and made .common_name string be lowercase

* added documentation of bird methods

* corrected Rubocop offenses and made test failures on #test_plausible_common_names and #test_implausible_common_names more clear

* fixed TestFakerCreatureBird#test_plausible_common_names to allow for names like "Painted bunting"

* Apply suggestions from code review

Co-authored-by: Koichi ITO <koic.ito@gmail.com>

* added a test for #order_with_common_names

* modified list to allow for matching common names to orders

* tests for new versions of Faker::Creature::Bird #order_with_common_names and #common_name accepts a parameter for the order to restrict on

* added tests to make sure that Faker::Creature::Bird #common_name and #order_with_common_names work properly

* corrected Faker::Creature::Bird #order_with_common_name and made #common_name more robust when passed a bad parameter

* changed @faker.version to correct next version

* corrected rubocop offenses

* updated documentation

* added additional silly - management apologizes for the insufficient irreverance of previous birb offerings

* Fix typo in documentation doc/creature/bird.md

Co-authored-by: Koichi ITO <koic.ito@gmail.com>

Co-authored-by: Koichi ITO <koic.ito@gmail.com>

README.md

@@ -234,6 +234,7 @@ gem 'faker', :git => 'https://github.com/faker-ruby/faker.git', :branch => 'mast
 
 ### Creature
   - [Faker::Creature::Animal](doc/creature/animal.md)
+  - [Faker::Creature::Bird](doc/creature/bird.md)
   - [Faker::Creature::Cat](doc/creature/cat.md)
   - [Faker::Creature::Dog](doc/creature/dog.md)
   - [Faker::Creature::Horse](doc/creature/horse.md)

doc/creature/bird.md

@@ -0,0 +1,42 @@
+# Faker::Creature::Bird
+
+```ruby
+# Random common family name of a bird
+Faker::Creature::Bird.common_family_name #=> "Owls"
+
+# Random taxonomic order from the class Aves (ie. those are birds)
+Faker::Creature::Bird.order #=> "Passeriformes" # Fun fact, 60% of birds are Passeriformes!
+
+# Random bird anatomy word
+Faker::Creature::Bird.anatomy #=> "rump"
+
+# Random bird anatomy word, in the past tense
+Faker::Creature::Bird.anatomy_past_tense #=> "breasted"
+
+# Random bird geography word
+Faker::Creature::Bird.geo #=> "Eurasian"
+
+# Random bird color word
+Faker::Creature::Bird.color #=> "ferruginous"
+
+# Random bird adjective word
+Faker::Creature::Bird.adjective #=> "common"
+
+# Random emotional adjective NOT typically used in bird names
+Faker::Creature::Bird.emotional_adjective #=> "cantankerous"
+
+# Random silly adjective NOT used in bird names
+Faker::Creature::Bird.silly_adjective #=> "drunk"
+
+# Random common name for a bird
+Faker::Creature::Bird.common_name #=> 'wren'
+
+# Random plausible common name for a bird
+Faker::Creature::Bird.plausible_common_name #=> 'Hellinger's Wren'
+
+# Random implausible common name for a bird
+Faker::Creature::Bird.implausible_common_name #=> 'Hellinger's Cantankerous Chickadee'
+
+# Returns a random pair order / common name pair
+Faker::Creature::Bird.order_with_common_name #=> {:order=>"Coliiformes", :common_name=>"Mousebird"}
+```

lib/faker/creature/bird.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Faker
+  class Creature
+    class Bird < Base
+      flexible :bird
+
+      class << self
+        ##
+        # Produces a random common family name of a bird.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.common_family_name #=> "Owls"
+        #
+        # @faker.version next
+        def common_family_name
+          fetch('creature.bird.common_family_name')
+        end
+
+        ##
+        # Produces a random common taxonomic order from the class Aves
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.order #=> "Passeriformes"
+        #
+        # @faker.version next
+        def order
+          orders = I18n.translate('faker.creature.bird.order_common_map').keys
+          sample(orders).to_s
+        end
+
+        ##
+        # Produces a random bird anatomy word
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.anatomy #=> "rump"
+        #
+        # @faker.version next
+        def anatomy
+          fetch('creature.bird.anatomy')
+        end
+
+        ##
+        # Produces a random, past tensed bird anatomy word
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.anatomy #=> "breasted"
+        #
+        # @faker.version next
+        def anatomy_past_tense
+          fetch('creature.bird.anatomy_past_tense')
+        end
+
+        ##
+        # Produces a random geographical word used in describing birds
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.geo #=> "Eurasian"
+        #
+        # @faker.version next
+        def geo
+          fetch('creature.bird.geo')
+        end
+
+        ##
+        # Produces a random color word used in describing birds
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.color #=> "ferruginous"
+        #
+        # @faker.version next
+        def color
+          fetch('creature.bird.colors')
+        end
+
+        ##
+        # Produces a random adjective used to described birds
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.adjective #=> 'common'
+        #
+        # @faker.version next
+        def adjective
+          fetch('creature.bird.adjectives')
+        end
+
+        ##
+        # Produces a random emotional adjective NOT used to described birds
+        # ...but could be
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.emotional_adjective #=> 'cantankerous'
+        #
+        # @faker.version next
+        def emotional_adjective
+          fetch('creature.bird.emotional_adjectives')
+        end
+
+        ##
+        # Produces a random adjective NOT used to described birds
+        # ...but probably shouldn't
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.silly_adjective #=> 'drunk'
+        #
+        # @faker.version next
+        def silly_adjective
+          fetch('creature.bird.silly_adjectives')
+        end
+
+        ##
+        # Produces a random common name for a bird
+        #
+        # @param [String | Symbol | nil] tax_order Tax
+        # @return [String]
+        # @raises TypeError If `tax_order` cannot be converted into a Symbol
+        # @raises ArgumentError If `tax_order` is not a valid taxonomic order
+        #
+        # @example
+        #   Faker::Creature::Bird.common_name #=> 'wren'
+        #
+        # @faker.version next
+        def common_name(tax_order = nil)
+          map = translate('faker.creature.bird.order_common_map')
+          if tax_order.nil?
+            sample(map.values.flatten).downcase
+          else
+            raise TypeError, 'tax_order parameter must be symbolizable' \
+              unless tax_order.respond_to?(:to_sym)
+            raise ArgumentError, "#{tax_order} is not a valid taxonomic order" \
+                                 unless map.keys.include?(tax_order.to_sym)
+
+            the_order = translate('faker.creature.bird.order_common_map')[tax_order.to_sym]
+            sample(the_order).downcase
+          end
+        end
+
+        ##
+        # Produces a random and plausible common name for a bird
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.plausible_common_name #=> 'Hellinger's Wren'
+        #
+        # @faker.version next
+        def plausible_common_name
+          parse('creature.bird.plausible_common_names').capitalize
+        end
+
+        ##
+        # Produces a random and IMplausible common name for a bird
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Creature::Bird.implausible_common_name #=> 'Hellinger's Cantankerous Chickadee'
+        #
+        # @faker.version next
+        def implausible_common_name
+          parse('creature.bird.implausible_common_names').capitalize
+        end
+
+        ##
+        # Produces a hash entry with a random order and a random common name
+        # that is of that order
+        #
+        # @return [Hash<order,common_name>]
+        #
+        # @example
+        #  Faker::Creature::Bird.order_with_common_name #=> {
+        #    order: ''Accipitriformes',
+        #    common_name: 'Osprey'
+        # }
+        #
+        # @faker.version next
+        def order_with_common_name(tax_order = nil)
+          map = I18n.translate('faker.creature.bird.order_common_map')
+          o = tax_order.nil? ? order : tax_order
+          { order: o, common_name: sample(map[o.to_sym]) }
+        end
+      end
+    end
+  end
+end