Petrovich Ruby Library

Because some names and last names do not clearly indicate gender, you should provide the gender argument to ensure correct declension. If omitted, Petrovich will attempt to determine the gender automatically.

Supported values for gender:

• :male (Symbol)
• 'male' (String)
• :female (Symbol)
• 'female' (String)

Petrovich(
  lastname: 'Андрейчук',
  firstname: 'Саша',
  gender: :male
).to(:instrumental).to_s # => "Андрейчуку Саше"

To use Petrovich in your Ruby project, add it to your Gemfile:

gem 'petrovich', '~> 1.0'

Then run bundle to install. Alternatively, you can install it directly via the command line:

gem install petrovich

Requirements:

• Ruby version 1.9.3 or higher.
• The gem is independent of Ruby on Rails and can be used in any Ruby application.

The petrovich CLI allows you to decline Russian names (last name, first name, and middle name) into a specific grammatical case. You can also query the gender of a name.

To use the CLI, provide the name components via flags and specify the target case using the --case flag.

# Example: Decline a name into the dative case
# Assuming the CLI is in your PATH
petrovich --lastname Ivanov --firstname Ivan --middlename Ivanovich --case dative

# Example: Get only the gender of a name
petrovich --lastname Ivanov --firstname Ivan --gender male --only-gender

Petrovich provides methods to check the gender of a person based on their name components.

• .gender: Returns the gender as a symbol (e.g., :male).
• .male?: Returns true if the person is male.
• .female?: Returns true if the person is female.
• .androgynous?: Returns true if the gender cannot be determined or is ambiguous.

Petrovich(lastname: 'Склифасовский').gender # => :male
Petrovich(firstname: 'Саша', lastname: 'Андрейчук').androgynous? # => true

You can use Petrovich from the command line. Use petrovich --help for a detailed guide.

Common flags:

• -l: Lastname
• -f: Firstname
• -m: Middlename (Patronymic)
• -g: Gender (male or female)
• -c: Case (genitive, dative, accusative, instrumental, prepositional)
• -n: Output only the name (no extra formatting)
• -o: Output only the patronymic

Example usage:

petrovich -l Иванов -f Иван -m Иванович -g male -c accusative

Use Petrovich.assert_case!(name_case) to ensure a provided case is one of the supported symbols in Petrovich::CASES. It raises an ArgumentError if the case is unknown.

Petrovich.assert_case!(:dative)

Create a new Petrovich::Name instance by passing an options hash. The library will automatically normalize the provided name components. You can optionally provide a :gender to ensure correct declension if the name is ambiguous.

Supported keys in the opts hash:

• lastname: The person's last name.
• firstname: The person's first name.
• middlename: The person's middle name (patronymic).
• gender: The gender of the person. Use :male, :female, or the strings 'male'/'female'. If omitted, the gem will attempt to detect the gender automatically.

name = Petrovich::Name.new(
  lastname: 'Ivanov',
  firstname: 'Ivan',
  middlename: 'Ivanovich',
  gender: :male
)

The Petrovich::Name class provides methods to decline a name into various Russian grammatical cases. Each method returns an Inflected object containing the declined name components.

To decline a name, call the method corresponding to the desired case (e.g., genitive, dative, accusative, instrumental, prepositional). The library uses the internal Petrovich.CASES list to define these methods.

You can also use the generic .to(name_case) method, where name_case must be a valid case recognized by Petrovich.assert_case!.

name = Petrovich::Name.new(lastname: 'Ivanov', firstname: 'Ivan', gender: :male)

# Using specific case methods
dative_name = name.dative

# Using the generic .to method
accusative_name = name.to(:accusative)

Use Petrovich.assert_name!(name) to verify that an object is a valid Petrovich::Value and contains at least one name component (lastname, firstname, or middlename). It raises an ArgumentError if the validation fails.

# name must be an instance of Petrovich::Value
Petrovich.assert_name!(name)

The library uses a rule_set to manage inflection and gender rules loaded from YAML files. You can access or replace the rule set via Petrovich.rule_set. To ensure rules are loaded, call Petrovich.load_rules!. Note that load_rules! is called automatically upon library initialization.

# Manually trigger rule loading if necessary
Petrovich.load_rules!

# Access the current rule set
rules = Petrovich.rule_set

You can retrieve the individual components of a name using the following methods:

• #lastname
• #firstname
• #middlename

Calling #to_s on a Petrovich::Name instance returns the full name as a single string, joining the components with a space.

name = Petrovich::Name.new(lastname: 'Ivanov', firstname: 'Ivan')

name.lastname  # => "Ivanov"
name.firstname # => "Ivan"
name.to_s      # => "Ivanov Ivan"