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
@!attribute [r] options @return the name’s formatting options
Public Class Methods
Source
# 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
Instance methods
Public Instance Methods
Source
# 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
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
Source
# File lib/citeproc/names.rb, line 286 def always_demote_non_dropping_particle! options[:'demote-non-dropping-particle'] = 'display-and-sort' self end
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
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
Source
# File lib/citeproc/names.rb, line 195 def display_order!(toggle = true) options[:'name-as-sort-order'] = !toggle self end
Sets the name to use display-order. The reverse of {#sort_order!}. @return [self]
Source
# 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
@return [String] the name formatted according to the current options
Source
# File lib/citeproc/names.rb, line 123 def initialize_copy(other) @attributes = other.attributes.deep_copy @options = other.options.dup end
Source
# File lib/citeproc/names.rb, line 240 def initialize_existing_only? options[:initialize].to_s == 'false' end
Source
# File lib/citeproc/names.rb, line 236 def initialize_with options[:'initialize-with'].to_s end
Source
# File lib/citeproc/names.rb, line 248 def initialize_without_hyphen! options[:'initialize-with-hyphen'] = false end
Source
# File lib/citeproc/names.rb, line 244 def initialize_without_hyphen? !options[:'initialize-with-hyphen'] end
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
Source
# File lib/citeproc/names.rb, line 232 def initials? !!options[:'initialize-with'] && personal? && romanesque? end
@return [Boolean] whether or not initials will be used for printing
Source
# File lib/citeproc/names.rb, line 367 def inspect "#<CiteProc::Name #{to_s.inspect}>" end
@return [String] a human-readable representation of the name object
Source
# File lib/citeproc/names.rb, line 226 def long_form! options[:form] = 'long' self end
Use long form for printing the name @return [self]
Source
# File lib/citeproc/names.rb, line 220 def long_form? !short_form? end
@return [Boolean] whether or not the long form will be used for printing
Source
# File lib/citeproc/names.rb, line 274 def never_demote_non_dropping_particle! options[:'demote-non-dropping-particle'] = 'never' self end
Source
# File lib/citeproc/names.rb, line 270 def never_demote_non_dropping_particle? !!(options[:'demote-non-dropping-particle'] =~ /^never$/i) end
Source
# File lib/citeproc/names.rb, line 143 def personal? !empty? && !literal? end
@return [Boolean] whether or not the Name
looks like it belongs to a person
Source
# File lib/citeproc/names.rb, line 138 def reset dup.reset! end
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
Source
# File lib/citeproc/names.rb, line 131 def reset! @options = Name.defaults.dup end
Resets the object’s options to the default settings. @return [self]
Source
# File lib/citeproc/names.rb, line 153 def romanesque? !!([given&.unicode_normalize(:nfc), family&.unicode_normalize(:nfc)].join.gsub(Variable.markup, '') =~ Name.romanesque) end
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
Source
# File lib/citeproc/names.rb, line 214 def short_form! options[:form] = 'short' self end
Use short form for printing the name @return [self]
Source
# File lib/citeproc/names.rb, line 208 def short_form? options[:form].to_s =~ /short/i end
@return [Boolean] whether or not the short form will be used for printing
Source
# 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
@return [Array<String>] an ordered array of formatted name parts to be used for sorting
Source
# File lib/citeproc/names.rb, line 188 def sort_order!(toggle = true) options[:'name-as-sort-order'] = !!toggle self end
Sets the name to use sort-order. The reverse of {#display_order!}. @return [self]
Source
# File lib/citeproc/names.rb, line 178 def sort_order? !!(options[:'name-as-sort-order'].to_s =~ /^(y(es)?|always|t(rue)?)$/i) end
@return [Boolean] whether or not the name will be printed in sort-order
Source
# File lib/citeproc/names.rb, line 362 def sort_order_downcase sort_order.map { |s| s.downcase.gsub(Variable.markup, '') } end
@return [Array<String>] the sort order array stripped off markup and downcased
Source
# File lib/citeproc/names.rb, line 201 def sort_separator options[:'sort-separator'] end
@return [String] the current sort separator
Source
# File lib/citeproc/names.rb, line 169 def static_order! self.static_ordering = true self end
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]
Source
# File lib/citeproc/names.rb, line 160 def static_order? static_ordering? || !romanesque? end
@return [Boolean] whether or not the name should be printed in static order
Source
# File lib/citeproc/names.rb, line 352 def strip_markup gsub(Variable.markup, '') end
@return [String] the name as a string stripped off all markup
Source
# File lib/citeproc/names.rb, line 357 def strip_markup! gsub!(Variable.markup, '') end
@return [self] the name with all parts stripped off markup
Source
# File lib/citeproc/names.rb, line 308 def to_s [given, family].compact_join(' ') end
Private Instance Methods
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
Source
# 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
CiteProc::Attributes#filter_key
Source
# File lib/citeproc/names.rb, line 391 def initialize_hyphen!(string) if initialize_without_hyphen? string.tr!('-', '') else string.gsub!(/\s*-/, '-') end end
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