Class: CaRuby::Person::Name

Inherits:
Object
  • Object
show all
Defined in:
lib/caruby/helpers/person.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(last, first = nil, middle = nil) ⇒ Name

Creates a new Name with the required last and optional first and middle components.

Parameters:

  • last (String) —

    the required last name

  • first (String, nil) (defaults to: nil) —

    the optional first name

  • middle (String, nil) (defaults to: nil) —

    the optional middle name



30
31
32
33
34
35
 
# File 'lib/caruby/helpers/person.rb', line 30

def initialize(last, first=nil, middle=nil)
  # replace empty with nil
  @first = first unless first == ''
  @last = last unless last == ''
  @middle = middle unless middle == ''
end

Instance Attribute Details

#credentials ⇒ String

Returns the trailing name credentials, e.g. ‘MD’.

Returns:

  • (String) —

    the trailing name credentials, e.g. ‘MD’



14
15
16
 
# File 'lib/caruby/helpers/person.rb', line 14

def credentials
  @credentials
end

#first ⇒ String (readonly)

Returns the first name.

Returns:



17
18
19
 
# File 'lib/caruby/helpers/person.rb', line 17

def first
  @first
end

#last ⇒ String (readonly)

Returns the ;ast name.

Returns:



23
24
25
 
# File 'lib/caruby/helpers/person.rb', line 23

def last
  @last
end

#middle ⇒ String (readonly)

Returns the middle name.

Returns:

  • (String) —

    the middle name



20
21
22
 
# File 'lib/caruby/helpers/person.rb', line 20

def middle
  @middle
end

#qualifier ⇒ String

Returns the trailing name qualifier, e.g. ‘III’.

Returns:

  • (String) —

    the trailing name qualifier, e.g. ‘III’



11
12
13
 
# File 'lib/caruby/helpers/person.rb', line 11

def qualifier
  @qualifier
end

#salutation ⇒ String

Returns the salutation, e.g. ‘Mr.’.

Returns:

  • (String) —

    the salutation, e.g. ‘Mr.’



8
9
10
 
# File 'lib/caruby/helpers/person.rb', line 8

def salutation
  @salutation
end

Class Method Details

.parse(name_s) ⇒ Name

Parses the name_s String into a Name. The name can be in one of the following formats:

  • last, first middle

  • salutation
    first [middle]

    last [qualifier] [, credentials]

where salutation ends in a period.

Example input:

  • Longfellow, Henry Wadsworth

  • Longfellow, Henry Gallifant Wadsworth

  • Henry Longfellow

  • Longfellow

  • Mr. Henry Wadsworth Longfellow III, MD, Ph.D.

Parameters:

  • name_s (String) —

    the name to parse

Returns:

  • (Name) —

    the parsed Name



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/caruby/helpers/person.rb', line 74

def self.parse(name_s)
  return if name_s.blank?
  # the name component variables
  first = middle = last = salutation = qualifier = credentials = nil
  # split into comma-delimited tokens
  tokens = name_s.split(',')
  # the word(s) before the first comma
  before_comma = tokens[0].split(' ')
  # if this is a last, first middle format, then parse it that way.
  # otherwise the format is [salutation] [first [middle]] last [qualifier] [credentials]
  if before_comma.size == 1 then
    last = before_comma[0]
    if tokens.size > 1 then
      after_comma = tokens[1].split(' ')
      first = after_comma.shift
      middle = after_comma.join(' ')
    end
  else
    # extract the salutation from the front, if any
    salutation = before_comma.shift if salutation?(before_comma[0])
    # extract the qualifier from the end, if any
    qualifier = before_comma.pop if qualifier?(before_comma[-1])
    # extract the last name from the end
    last = before_comma.pop
    # extract the first name from the front
    first = before_comma.shift
    # the middle name is whatever is left before the comma
    middle = before_comma.join(' ')
    # the credentials are the comma-delimited words after the first comma
    credentials = tokens[1..-1].join(',').strip
  end
  # if there is only one name field, then it is the last name
  if last.nil? then
    last = first
    first = nil
  end
  # make the name
  name = self.new(last, first, middle)
  name.salutation = salutation
  name.qualifier = qualifier
  name.credentials = credentials
  name
end

.qualifier?(s) ⇒ Boolean

Returns whether the given name fragment is a recognized qualifier. The following qualifiers are recognized:

  • Jr with optional period

  • Sr with optional period

  • I, II or III

Parameters:

  • s (String) —

    a name fragment

Returns:

  • (Boolean) —

    whether s is a recognized qualifier



143
144
145
 
# File 'lib/caruby/helpers/person.rb', line 143

def self.qualifier?(s)
  s and (s =~ /[J|S]r[.]?/ or s =~ /\AI+\Z/)
end

.salutation?(s) ⇒ Boolean

Returns whether the fragment ends in a period.

Parameters:

  • s (String) —

    a name fragment

Returns:

  • (Boolean) —

    whether the fragment ends in a period



131
132
133
 
# File 'lib/caruby/helpers/person.rb', line 131

def self.salutation?(s)
  s =~ /\.$/
end

Instance Method Details

#==(other) ⇒ Boolean

Returns whether this Person’s first, middle and last name components equal the other Person’s.

Returns:

  • (Boolean) —

    whether this Person’s first, middle and last name components equal the other Person’s



54
55
56
 
# File 'lib/caruby/helpers/person.rb', line 54

def ==(other)
  self.class == other.class and first == other.first and middle == other.middle and last == other.last
end

#to_a ⇒ (String, String, String)

middle and last fields

Examples:

Person.parse("Abe Lincoln").to_a #=> ["Abe", nil, "Lincoln"]

Returns:



42
43
44
 
# File 'lib/caruby/helpers/person.rb', line 42

def to_a
  [@first, @middle, @last]
end

#to_s ⇒ String Also known as: inspect

Returns this Name in the format [Salutation] First [Middle] Last[, Credentials].

Returns:

  • (String) —

    this Name in the format [Salutation] First [Middle] Last[, Credentials]



47
48
49
50
51
 
# File 'lib/caruby/helpers/person.rb', line 47

def to_s
  name_s = [salutation, first, middle, last, qualifier].reject { |part| part.nil? }.join(' ')
  name_s << ', ' << credentials if credentials
  name_s
end

#validate ⇒ Object

or if there is a middle name but no first name

Raises:

  • (ValidationError) —

    if there is neither a first nor a last name



120
121
122
123
124
125
126
127
 
# File 'lib/caruby/helpers/person.rb', line 120

def validate
  if last.nil? and first.nil? then
    raise Jinx::ValidationError.new("Name is missing both the first and last fields")
  end
  if !middle.nil? and first.nil? then
    raise Jinx::ValidationError.new("Name with middle field #{middle} is missing the first field")
  end
end