Class: CiteProc::Name

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Attributes, Comparable
Defined in:
lib/citeproc/names.rb

Overview

Names consist of several dependent parts of strings. Simple personal names are composed of family and given elements, containing respectively the family and given name of the individual.

Name.new(:family => 'Doe', :given => 'Jane')

Institutional and other names that should always be presented literally (such as “The Artist Formerly Known as Prince”, “Banksy”, or “Ramses IV”) should be delivered as a single :literal element:

Name.new(:literal => 'Banksy')

Name particles, such as the “von” in “Alexander von Humboldt”, can be delivered separately from the family and given name, as :dropping-particle and :non-dropping-particle elements.

Name suffixes such as the “Jr.” in “Frank Bennett, Jr.” and the “III” in “Horatio Ramses III” can be delivered as a suffix element.

Name.new do |n|
  n.family, n.given, n.suffix = 'Ramses', 'Horatio', 'III'
end

Names not written in the Latin or Cyrillic scripts are always displayed with the family name first. Sometimes it might be desired to handle a Latin or Cyrillic transliteration as if it were a fixed (non-Byzantine) name (e.g., for Hungarian names). This behavior can be prompted by including activating static-ordering:

Name.new(:family => 'Murakami', :given => 'Haruki').to_s
#-> "Haruki Murakami"

Name.new(:family => 'Murakami', :given => 'Haruki').static_order!.to_s
#-> "Murakami Haruki"

Class Attribute Summary collapse

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Attributes

#attribute?, #eql?, #hash, #merge, #read_attribute, #reverse_merge, #to_citeproc, #to_hash, #to_json, #write_attribute

Constructor Details

#initialize(attributes = {}, options = {}) {|_self| ... } ⇒ Name

Instance methods

Yields:

  • (_self)

Yield Parameters:



115
116
117
118
119
120
121
122
 
# File 'lib/citeproc/names.rb', line 115

def initialize(attributes = {}, options = {})
  @options = Name.defaults.merge(options)
  @sort_prefix = (/^(the|an?|der|die|das|eine?|l[ae])\s+|^l\W/i).freeze

  merge(attributes)

  yield self if block_given?
end

Class Attribute Details

.defaults ⇒ Object (readonly)

Returns the value of attribute defaults.



65
66
67
 
# File 'lib/citeproc/names.rb', line 65

def defaults
  @defaults
end

.parts ⇒ Object (readonly)

Returns the value of attribute parts.



65
66
67
 
# File 'lib/citeproc/names.rb', line 65

def parts
  @parts
end

.romanesque ⇒ Object (readonly)

Returns the value of attribute romanesque.



65
66
67
 
# File 'lib/citeproc/names.rb', line 65

def romanesque
  @romanesque
end

Instance Attribute Details

#options ⇒ Object (readonly)

Returns the name’s formatting options.

Returns:

  • the name’s formatting options



74
75
76
 
# File 'lib/citeproc/names.rb', line 74

def options
  @options
end

#sort_prefix ⇒ Object (readonly)

Returns the value of attribute sort_prefix.



76
77
78
 
# File 'lib/citeproc/names.rb', line 76

def sort_prefix
  @sort_prefix
end

Instance Method Details

#<=>(other) ⇒ Fixnum?

Compares two names. The comparison is based on #sort_order_downcase

Parameters:

Returns:

  • (Fixnum, nil) —

    -1, 0, or 1 depending on the result of the comparison; nil if the name cannot be compared to the passed-in object

See Also:



304
305
306
307
 
# File 'lib/citeproc/names.rb', line 304

def <=>(other)
  return nil unless other.respond_to?(:sort_order_downcase)
  sort_order_downcase <=> other.sort_order_downcase
end

#always_demote_non_dropping_particle! ⇒ Object Also known as: always_demote_particle!, demote_particle! 



287
288
289
290
 
# File 'lib/citeproc/names.rb', line 287

def always_demote_non_dropping_particle!
  options[:'demote-non-dropping-particle'] = 'display-and-sort'
  self
end

#always_demote_non_dropping_particle? ⇒ Boolean Also known as: always_demote_particle?

Returns:

  • (Boolean) 


283
284
285
 
# File 'lib/citeproc/names.rb', line 283

def always_demote_non_dropping_particle?
  !!(options[:'demote-non-dropping-particle'] =~ /^(display-and-sort|always)$/i)
end

#demote_non_dropping_particle? ⇒ Boolean Also known as: demote_particle?

Returns:

  • (Boolean) 


264
265
266
267
 
# File 'lib/citeproc/names.rb', line 264

def demote_non_dropping_particle?
  always_demote_non_dropping_particle? ||
    !!(sort_order? && options[:'demote-non-dropping-particle'] =~ /^sort(-only)?$/i)
end

#display_order!(toggle = true) ⇒ self

Sets the name to use display-order. The reverse of #sort_order!.

Returns:

  • (self) 


196
197
198
199
 
# File 'lib/citeproc/names.rb', line 196

def display_order!(toggle = true)
  options[:'name-as-sort-order'] = !toggle
  self
end

#display_order? ⇒ Boolean

Returns:

  • (Boolean) 


183
184
185
 
# File 'lib/citeproc/names.rb', line 183

def display_order?
  !sort_order?
end

#format ⇒ String Also known as: print

Returns the name formatted according to the current options.

Returns:

  • (String) —

    the name formatted according to the current options



314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/citeproc/names.rb', line 314

def format
  case
  when literal?
    literal.to_s
  when static_order?
    [family, initials].compact.join(' ')
  when !short_form?
    case
    when !sort_order?
      [[initials, dropping_particle, particle, family].compact_join(' '),
        suffix].compact_join(comma_suffix? ? comma : ' ')

    when !demote_particle?
      [[particle, family].compact_join(' '), [initials,
        dropping_particle].compact_join(' '), suffix].compact_join(comma)

    else
      [family, [initials, dropping_particle, particle].compact_join(' '),
        suffix].compact_join(comma)
    end
  else
    [particle, family].compact_join(' ')
  end
end

#initialize_copy(other) ⇒ Object 



124
125
126
127
 
# File 'lib/citeproc/names.rb', line 124

def initialize_copy(other)
  @attributes = other.attributes.deep_copy
  @options = other.options.dup
end

#initialize_existing_only? ⇒ Boolean

Returns:

  • (Boolean) 


241
242
243
 
# File 'lib/citeproc/names.rb', line 241

def initialize_existing_only?
  options[:initialize].to_s == 'false'
end

#initialize_with ⇒ Object 



237
238
239
 
# File 'lib/citeproc/names.rb', line 237

def initialize_with
  options[:'initialize-with'].to_s
end

#initialize_without_hyphen! ⇒ Object 



249
250
251
 
# File 'lib/citeproc/names.rb', line 249

def initialize_without_hyphen!
  options[:'initialize-with-hyphen'] = false
end

#initialize_without_hyphen? ⇒ Boolean

Returns:

  • (Boolean) 


245
246
247
 
# File 'lib/citeproc/names.rb', line 245

def initialize_without_hyphen?
  !options[:'initialize-with-hyphen']
end

#initials ⇒ Object 



253
254
255
256
257
258
259
260
261
262
 
# File 'lib/citeproc/names.rb', line 253

def initials
  case
  when !initials?
    given
  when initialize_existing_only?
    existing_initials_of given
  else
    initials_of given
  end
end

#initials? ⇒ Boolean

Returns whether or not initials will be used for printing.

Returns:

  • (Boolean) —

    whether or not initials will be used for printing



233
234
235
 
# File 'lib/citeproc/names.rb', line 233

def initials?
  !!options[:'initialize-with'] && personal? && romanesque?
end

#inspect ⇒ String

Returns a human-readable representation of the name object.

Returns:

  • (String) —

    a human-readable representation of the name object



368
369
370
 
# File 'lib/citeproc/names.rb', line 368

def inspect
  "#<CiteProc::Name #{to_s.inspect}>"
end

#long_form! ⇒ self

Use long form for printing the name

Returns:

  • (self) 


227
228
229
230
 
# File 'lib/citeproc/names.rb', line 227

def long_form!
  options[:form] = 'long'
  self
end

#long_form? ⇒ Boolean

Returns whether or not the long form will be used for printing.

Returns:

  • (Boolean) —

    whether or not the long form will be used for printing



221
222
223
 
# File 'lib/citeproc/names.rb', line 221

def long_form?
  !short_form?
end

#never_demote_non_dropping_particle! ⇒ Object Also known as: never_demote_particle! 



275
276
277
278
 
# File 'lib/citeproc/names.rb', line 275

def never_demote_non_dropping_particle!
  options[:'demote-non-dropping-particle'] = 'never'
  self
end

#never_demote_non_dropping_particle? ⇒ Boolean Also known as: never_demote_particle?

Returns:

  • (Boolean) 


271
272
273
 
# File 'lib/citeproc/names.rb', line 271

def never_demote_non_dropping_particle?
  !!(options[:'demote-non-dropping-particle'] =~ /^never$/i)
end

#personal? ⇒ Boolean

Returns whether or not the Name looks like it belongs to a person.

Returns:

  • (Boolean) —

    whether or not the Name looks like it belongs to a person



144
145
146
 
# File 'lib/citeproc/names.rb', line 144

def personal?
  !empty? && !literal?
end

#reset ⇒ Name

Returns a copy of the name object with all options reset to their default settings.

Returns:

  • (Name) —

    a copy of the name with default options



139
140
141
 
# File 'lib/citeproc/names.rb', line 139

def reset
  dup.reset!
end

#reset! ⇒ self

Resets the object’s options to the default settings.

Returns:

  • (self) 


132
133
134
 
# File 'lib/citeproc/names.rb', line 132

def reset!
  @options = Name.defaults.dup
end

#romanesque? ⇒ Boolean Also known as: byzantine?

A name is ‘romanesque’ if it contains only romanesque characters. This should be the case for the majority of names written in latin- or greek-based script. It will be false, for example, for names written in Chinese, Japanese, Arabic or Hebrew.

Returns:

  • (Boolean) —

    whether or not the name is romanesque



154
155
156
 
# File 'lib/citeproc/names.rb', line 154

def romanesque?
  !!([given, family].join.gsub(Variable.markup, '') =~ Name.romanesque)
end

#short_form! ⇒ self

Use short form for printing the name

Returns:

  • (self) 


215
216
217
218
 
# File 'lib/citeproc/names.rb', line 215

def short_form!
  options[:form] = 'short'
  self
end

#short_form? ⇒ Boolean

Returns whether or not the short form will be used for printing.

Returns:

  • (Boolean) —

    whether or not the short form will be used for printing



209
210
211
 
# File 'lib/citeproc/names.rb', line 209

def short_form?
  options[:form].to_s =~ /short/i
end

#sort_order ⇒ Array<String>

Returns an ordered array of formatted name parts to be used for sorting.

Returns:

  • (Array<String>) —

    an ordered array of formatted name parts to be used for sorting



341
342
343
344
345
346
347
348
349
350
 
# File 'lib/citeproc/names.rb', line 341

def sort_order
  case
  when literal?
    [literal.to_s.sub(sort_prefix, '')]
  when never_demote_particle?
    [[particle, family].compact_join(' '), dropping_particle, given, suffix].map(&:to_s)
  else
    [family, [particle, dropping_particle].compact_join(' '), given, suffix].map(&:to_s)
  end
end

#sort_order!(toggle = true) ⇒ self

Sets the name to use sort-order. The reverse of #display_order!.

Returns:

  • (self) 


189
190
191
192
 
# File 'lib/citeproc/names.rb', line 189

def sort_order!(toggle = true)
  options[:'name-as-sort-order'] = !!toggle
  self
end

#sort_order? ⇒ Boolean

Returns whether or not the name will be printed in sort-order.

Returns:

  • (Boolean) —

    whether or not the name will be printed in sort-order



179
180
181
 
# File 'lib/citeproc/names.rb', line 179

def sort_order?
  !!(options[:'name-as-sort-order'].to_s =~ /^(y(es)?|always|t(rue)?)$/i)
end

#sort_order_downcase ⇒ Array<String>

Returns the sort order array stripped off markup and downcased.

Returns:

  • (Array<String>) —

    the sort order array stripped off markup and downcased



363
364
365
 
# File 'lib/citeproc/names.rb', line 363

def sort_order_downcase
  sort_order.map { |s| s.downcase.gsub(Variable.markup, '') }
end

#sort_separator ⇒ String Also known as: comma

Returns the current sort separator.

Returns:

  • (String) —

    the current sort separator



202
203
204
 
# File 'lib/citeproc/names.rb', line 202

def sort_separator
  options[:'sort-separator']
end

#static_order! ⇒ self

Set the name to use static order for printing, i.e., print the family name before the given name as is customary, for example, in Hungarian and many Asian languages.

Returns:

  • (self) 


170
171
172
173
 
# File 'lib/citeproc/names.rb', line 170

def static_order!
  self.static_ordering = true
  self
end

#static_order? ⇒ Boolean

Returns whether or not the name should be printed in static order.

Returns:

  • (Boolean) —

    whether or not the name should be printed in static order



161
162
163
 
# File 'lib/citeproc/names.rb', line 161

def static_order?
  static_ordering? || !romanesque?
end

#strip_markup ⇒ String

Returns the name as a string stripped off all markup.

Returns:

  • (String) —

    the name as a string stripped off all markup



353
354
355
 
# File 'lib/citeproc/names.rb', line 353

def strip_markup
  gsub(Variable.markup, '')
end

#strip_markup! ⇒ self

Returns the name with all parts stripped off markup.

Returns:

  • (self) —

    the name with all parts stripped off markup



358
359
360
 
# File 'lib/citeproc/names.rb', line 358

def strip_markup!
  gsub!(Variable.markup, '')
end

#to_s ⇒ Object 



309
310
311
 
# File 'lib/citeproc/names.rb', line 309

def to_s
  [given, family].compact_join(' ')
end