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
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
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
# File lib/citeproc/names.rb, line 286 def always_demote_non_dropping_particle! options[:'demote-non-dropping-particle'] = 'display-and-sort' self end
# File lib/citeproc/names.rb, line 282 def always_demote_non_dropping_particle? !!(options[:'demote-non-dropping-particle'] =~ /^(display-and-sort|always)$/i) end
# 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
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
# File lib/citeproc/names.rb, line 182 def display_order? !sort_order? end
@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
# File lib/citeproc/names.rb, line 123 def initialize_copy(other) @attributes = other.attributes.deep_copy @options = other.options.dup end
# File lib/citeproc/names.rb, line 240 def initialize_existing_only? options[:initialize].to_s == 'false' end
# File lib/citeproc/names.rb, line 236 def initialize_with options[:'initialize-with'].to_s end
# File lib/citeproc/names.rb, line 248 def initialize_without_hyphen! options[:'initialize-with-hyphen'] = false end
# File lib/citeproc/names.rb, line 244 def initialize_without_hyphen? !options[:'initialize-with-hyphen'] end
# 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
@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
@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
Use long form for printing the name @return [self]
# File lib/citeproc/names.rb, line 226 def long_form! options[:form] = 'long' self end
@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
# File lib/citeproc/names.rb, line 274 def never_demote_non_dropping_particle! options[:'demote-non-dropping-particle'] = 'never' self end
# File lib/citeproc/names.rb, line 270 def never_demote_non_dropping_particle? !!(options[:'demote-non-dropping-particle'] =~ /^never$/i) end
@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
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
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
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
Use short form for printing the name @return [self]
# File lib/citeproc/names.rb, line 214 def short_form! options[:form] = 'short' self end
@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
@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
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
@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
@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
@return [String] the current sort separator
# File lib/citeproc/names.rb, line 201 def sort_separator options[:'sort-separator'] 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]
# File lib/citeproc/names.rb, line 169 def static_order! self.static_ordering = true self end
@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
@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
@return [self] the name with all parts stripped off markup
# File lib/citeproc/names.rb, line 357 def strip_markup! gsub!(Variable.markup, '') end
# File lib/citeproc/names.rb, line 308 def to_s [given, family].compact_join(' ') end
Private Instance Methods
# 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
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
# File lib/citeproc/names.rb, line 391 def initialize_hyphen!(string) if initialize_without_hyphen? string.tr!('-', '') else string.gsub!(/\s*-/, '-') end end
# 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