Class: Namae::Name

Inherits:
Struct
  • Object
show all
Defined in:
lib/namae/name.rb

Overview

A Name represents a single personal name, exposing its constituent parts (e.g., family name, given name etc.). Name instances are typically created and returned from Namae.parse.

name = Namae.parse('Yukihiro "Matz" Matsumoto')[0]

name.family #=> Matsumoto
name.nick #=> Matz
name.given #=> Yukihiro

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(attributes = {}) ⇒ Name

Returns a new instance of Name.

Examples:

Name.new(:family => 'Matsumoto')

Parameters:

  • attributes (Hash) (defaults to: {}) —

    the individual parts of the name



51
52
53
 
# File 'lib/namae/name.rb', line 51

def initialize(attributes = {})
  super(*attributes.values_at(*Name.parts))
end

Class Attribute Details

.defaults ⇒ Object (readonly)

Returns the value of attribute defaults.



28
29
30
 
# File 'lib/namae/name.rb', line 28

def defaults
  @defaults
end

.parts ⇒ Object (readonly)

Returns the value of attribute parts.



28
29
30
 
# File 'lib/namae/name.rb', line 28

def parts
  @parts
end

Instance Attribute Details

#appellation ⇒ Object

Returns the value of attribute appellation

Returns:

  • (Object) —

    the current value of appellation



13
14
15
 
# File 'lib/namae/name.rb', line 13

def appellation
  @appellation
end

#dropping_particle ⇒ Object

Returns the value of attribute dropping_particle

Returns:

  • (Object) —

    the current value of dropping_particle



13
14
15
 
# File 'lib/namae/name.rb', line 13

def dropping_particle
  @dropping_particle
end

#family ⇒ Object

Returns the value of attribute family

Returns:

  • (Object) —

    the current value of family



13
14
15
 
# File 'lib/namae/name.rb', line 13

def family
  @family
end

#given ⇒ Object

Returns the value of attribute given

Returns:

  • (Object) —

    the current value of given



13
14
15
 
# File 'lib/namae/name.rb', line 13

def given
  @given
end

#nick ⇒ Object

Returns the value of attribute nick

Returns:

  • (Object) —

    the current value of nick



13
14
15
 
# File 'lib/namae/name.rb', line 13

def nick
  @nick
end

#particle ⇒ Object

Returns the value of attribute particle

Returns:

  • (Object) —

    the current value of particle



13
14
15
 
# File 'lib/namae/name.rb', line 13

def particle
  @particle
end

#suffix ⇒ Object

Returns the value of attribute suffix

Returns:

  • (Object) —

    the current value of suffix



13
14
15
 
# File 'lib/namae/name.rb', line 13

def suffix
  @suffix
end

#title ⇒ Object

Returns the value of attribute title

Returns:

  • (Object) —

    the current value of title



13
14
15
 
# File 'lib/namae/name.rb', line 13

def title
  @title
end

Class Method Details

.parse(name) ⇒ Name

Returns the parsed name.

Parameters:

  • name (String) —

    the name to be parsed

Returns:

  • (Name) —

    the parsed name



40
41
42
43
44
 
# File 'lib/namae/name.rb', line 40

def parse(name)
  parse!(name)
rescue
  new
end

.parse!(name) ⇒ Name

Returns the parsed name.

Parameters:

  • name (String) —

    the name to be parsed

Returns:

  • (Name) —

    the parsed name

Raises:

  • (ArgumentError) —

    if the name cannot be parsed or if the input contains more than a single name



34
35
36
 
# File 'lib/namae/name.rb', line 34

def parse!(name)
  Parser.instance.parse!(name)[0] || new
end

Instance Method Details

#display_order ⇒ String Also known as: to_s

Returns the name in display order.

Returns:

  • (String) —

    the name in display order



61
62
63
 
# File 'lib/namae/name.rb', line 61

def display_order
  [given_part, family_part].reject(&:empty?).join(' ')
end

#empty? ⇒ Boolean

Returns whether or not all the name components are nil.

Returns:

  • (Boolean) —

    whether or not all the name components are nil.



66
67
68
 
# File 'lib/namae/name.rb', line 66

def empty?
  values.compact.empty?
end

#initials(options = {}) ⇒ String

Returns the name’s initials.

Parameters:

  • options (Hash) (defaults to: {}) —

    the options to create the initials

Options Hash (options):

  • :expand (true, false) — default: false —

    whether or not to expand the family name

  • :dots (true, false) — default: true —

    whether or not to print dots between the initials

  • :spaces (true, false) — default: false —

    whether or not to print spaces between the initals

Returns:

  • (String) —

    the name’s initials.



93
94
95
96
97
98
99
100
101
 
# File 'lib/namae/name.rb', line 93

def initials(options = {})
  options = Name.defaults[:initials].merge(options)
  
  if options[:expand]
    [initials_of(given_part, options), family].compact.join(' ')
  else
    initials_of([given_part, family_part].join(' '), options)
  end
end

#inspect ⇒ String

Returns a string representation of the name.

Returns:

  • (String) —

    a string representation of the name



120
121
122
 
# File 'lib/namae/name.rb', line 120

def inspect
  "#<Name #{each_pair.map { |k,v| [k,v.inspect].join('=') if v }.compact.join(' ')}>"
end

#merge(other) ⇒ self

Merges the name with the passed-in name or hash.

Parameters:

  • other (#each_pair) —

    the other name or hash

Returns:

  • (self)

Raises:

  • (ArgumentError) 


74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/namae/name.rb', line 74

def merge(other)
  raise ArgumentError, "failed to merge #{other.class} into Name" unless
    other.respond_to?(:each_pair)
    
  other.each_pair do |part, value|
    writer = "#{part}="
    send(writer, value) if !value.nil? && respond_to?(writer)
  end
  
  self
end

#sort_order(delimiter = ', ') ⇒ String

Returns the name in sort order.

Returns:

  • (String) —

    the name in sort order



56
57
58
 
# File 'lib/namae/name.rb', line 56

def sort_order(delimiter = ', ')
  [family_part, given_part].reject(&:empty?).join(delimiter)
end

#values_at(selector, ...) ⇒ Array

Returns the list of values.

Examples:

name.values_at(:family, :nick) #=> ['Matsumoto', 'Matz']

Returns an array containing the elements in self corresponding to the given selector(s). The selectors may be either integer indices, ranges (functionality inherited from Struct) or symbols idenifying valid keys.

Returns:

  • (Array) —

    the list of values

See Also:

  • Struct#values_at


114
115
116
 
# File 'lib/namae/name.rb', line 114

def values_at(*arguments)
  super(*arguments.flatten.map { |k| k.is_a?(Symbol) ? Name.parts.index(k) : k })
end