class CiteProc::Name

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"

Attributes

defaults[R]
parts[R]
romanesque[R]
options[R]

@!attribute [r] options @return the name’s formatting options

sort_prefix[R]

Public Class Methods

new(attributes = {}, options = {}) { |self| ... } click to toggle source

Instance methods

# File lib/citeproc/names.rb, line 114
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

Public Instance Methods

<=>(other) click to toggle source

Compares two names. The comparison is based on sort_order_downcase

@see sort_order_downcase

@param other [#sort_order_downcase] the other name @return [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
# File lib/citeproc/names.rb, line 303
def <=>(other)
  return nil unless other.respond_to?(:sort_order_downcase)
  sort_order_downcase <=> other.sort_order_downcase
end
always_demote_non_dropping_particle!() click to toggle source
# File lib/citeproc/names.rb, line 286
def always_demote_non_dropping_particle!
  options[:'demote-non-dropping-particle'] = 'display-and-sort'
  self
end
always_demote_non_dropping_particle?() click to toggle source
# File lib/citeproc/names.rb, line 282
def always_demote_non_dropping_particle?
  !!(options[:'demote-non-dropping-particle'] =~ /^(display-and-sort|always)$/i)
end
Also aliased as: always_demote_particle?
always_demote_particle!()
always_demote_particle?()
byzantine?()
Alias for: romanesque?
comma()
Alias for: sort_separator
demote_non_dropping_particle?() click to toggle source
# File lib/citeproc/names.rb, line 263
def demote_non_dropping_particle?
  always_demote_non_dropping_particle? ||
    !!(sort_order? && options[:'demote-non-dropping-particle'] =~ /^sort(-only)?$/i)
end
Also aliased as: demote_particle?
demote_particle!()
demote_particle?()
display_order!(toggle = true) click to toggle source

Sets the name to use display-order. The reverse of {#sort_order!}. @return [self]

# File lib/citeproc/names.rb, line 195
def display_order!(toggle = true)
  options[:'name-as-sort-order'] = !toggle
  self
end
display_order?() click to toggle source
# File lib/citeproc/names.rb, line 182
def display_order?
  !sort_order?
end
format() click to toggle source

@return [String] the name formatted according to the current options

# File lib/citeproc/names.rb, line 313
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
Also aliased as: print
initialize_copy(other) click to toggle source
# File lib/citeproc/names.rb, line 123
def initialize_copy(other)
  @attributes = other.attributes.deep_copy
  @options = other.options.dup
end
initialize_existing_only?() click to toggle source
# File lib/citeproc/names.rb, line 240
def initialize_existing_only?
  options[:initialize].to_s == 'false'
end
initialize_with() click to toggle source
# File lib/citeproc/names.rb, line 236
def initialize_with
  options[:'initialize-with'].to_s
end
initialize_without_hyphen!() click to toggle source
# File lib/citeproc/names.rb, line 248
def initialize_without_hyphen!
  options[:'initialize-with-hyphen'] = false
end
initialize_without_hyphen?() click to toggle source
# File lib/citeproc/names.rb, line 244
def initialize_without_hyphen?
  !options[:'initialize-with-hyphen']
end
initials() click to toggle source
# File lib/citeproc/names.rb, line 252
def initials
  case
  when !initials?
    given
  when initialize_existing_only?
    existing_initials_of given
  else
    initials_of given
  end
end
initials?() click to toggle source

@return [Boolean] whether or not initials will be used for printing

# File lib/citeproc/names.rb, line 232
def initials?
  !!options[:'initialize-with'] && personal? && romanesque?
end
inspect() click to toggle source

@return [String] a human-readable representation of the name object

# File lib/citeproc/names.rb, line 367
def inspect
  "#<CiteProc::Name #{to_s.inspect}>"
end
long_form!() click to toggle source

Use long form for printing the name @return [self]

# File lib/citeproc/names.rb, line 226
def long_form!
  options[:form] = 'long'
  self
end
long_form?() click to toggle source

@return [Boolean] whether or not the long form will be used for printing

# File lib/citeproc/names.rb, line 220
def long_form?
  !short_form?
end
never_demote_non_dropping_particle!() click to toggle source
# File lib/citeproc/names.rb, line 274
def never_demote_non_dropping_particle!
  options[:'demote-non-dropping-particle'] = 'never'
  self
end
Also aliased as: never_demote_particle!
never_demote_non_dropping_particle?() click to toggle source
# File lib/citeproc/names.rb, line 270
def never_demote_non_dropping_particle?
  !!(options[:'demote-non-dropping-particle'] =~ /^never$/i)
end
Also aliased as: never_demote_particle?
never_demote_particle!()
never_demote_particle?()
personal?() click to toggle source

@return [Boolean] whether or not the Name looks like it belongs to a person

# File lib/citeproc/names.rb, line 143
def personal?
  !empty? && !literal?
end
print()
Alias for: format
reset() click to toggle source

Returns a copy of the name object with all options reset to their default settings. @return [Name] a copy of the name with default options

# File lib/citeproc/names.rb, line 138
def reset
  dup.reset!
end
reset!() click to toggle source

Resets the object’s options to the default settings. @return [self]

# File lib/citeproc/names.rb, line 131
def reset!
  @options = Name.defaults.dup
end
romanesque?() click to toggle source

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.

@return [Boolean] whether or not the name is romanesque

# File lib/citeproc/names.rb, line 153
def romanesque?
  !!([given, family].join.gsub(Variable.markup, '') =~ Name.romanesque)
end
Also aliased as: byzantine?
short_form!() click to toggle source

Use short form for printing the name @return [self]

# File lib/citeproc/names.rb, line 214
def short_form!
  options[:form] = 'short'
  self
end
short_form?() click to toggle source

@return [Boolean] whether or not the short form will be used for printing

# File lib/citeproc/names.rb, line 208
def short_form?
  options[:form].to_s =~ /short/i
end
sort_order() click to toggle source

@return [Array<String>] an ordered array of formatted name parts to be used for sorting

# File lib/citeproc/names.rb, line 340
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) click to toggle source

Sets the name to use sort-order. The reverse of {#display_order!}. @return [self]

# File lib/citeproc/names.rb, line 188
def sort_order!(toggle = true)
  options[:'name-as-sort-order'] = !!toggle
  self
end
sort_order?() click to toggle source

@return [Boolean] whether or not the name will be printed in sort-order

# File lib/citeproc/names.rb, line 178
def sort_order?
  !!(options[:'name-as-sort-order'].to_s =~ /^(y(es)?|always|t(rue)?)$/i)
end
sort_order_downcase() click to toggle source

@return [Array<String>] the sort order array stripped off markup and downcased

# File lib/citeproc/names.rb, line 362
def sort_order_downcase
  sort_order.map { |s| s.downcase.gsub(Variable.markup, '') }
end
sort_separator() click to toggle source

@return [String] the current sort separator

# File lib/citeproc/names.rb, line 201
def sort_separator
  options[:'sort-separator']
end
Also aliased as: comma
static_order!() click to toggle source

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.

@return [self]

# File lib/citeproc/names.rb, line 169
def static_order!
  self.static_ordering = true
  self
end
static_order?() click to toggle source

@return [Boolean] whether or not the name should be printed in static order

# File lib/citeproc/names.rb, line 160
def static_order?
  static_ordering? || !romanesque?
end
strip_markup() click to toggle source

@return [String] the name as a string stripped off all markup

# File lib/citeproc/names.rb, line 352
def strip_markup
  gsub(Variable.markup, '')
end
strip_markup!() click to toggle source

@return [self] the name with all parts stripped off markup

# File lib/citeproc/names.rb, line 357
def strip_markup!
  gsub!(Variable.markup, '')
end
to_s() click to toggle source
# File lib/citeproc/names.rb, line 308
def to_s
  [given, family].compact_join(' ')
end

Private Instance Methods

existing_initials_of(string) click to toggle source
# File lib/citeproc/names.rb, line 399
def existing_initials_of(string)
  return unless string
  string = string.dup

  string.gsub!(/([[:upper:]])([[:upper:]])/, '\1 \2')
  string.gsub!(/\b([[:upper:]])\b[^[:alpha:]-]*/, "\\1#{initialize_with}")

  initialize_hyphen!(string)

  string.strip!
  string
end
filter_key(key) click to toggle source
Calls superclass method CiteProc::Attributes#filter_key
# File lib/citeproc/names.rb, line 373
def filter_key(key)
  key = key.to_s.tr('_', '-')
  key = 'non-dropping-particle' if key == 'particle'
  super key
end
initialize_hyphen!(string) click to toggle source
# File lib/citeproc/names.rb, line 391
def initialize_hyphen!(string)
  if initialize_without_hyphen?
    string.tr!('-', '')
  else
    string.gsub!(/\s*-/, '-')
  end
end
initials_of(string) click to toggle source
# File lib/citeproc/names.rb, line 379
def initials_of(string)
  return unless string
  string = string.dup

  string.gsub!(/([[:upper:]])[^[:upper:]\s-]*\s*/, "\\1#{initialize_with}")

  initialize_hyphen!(string)

  string.strip!
  string
end