class CiteProc::Names
Represents a {Variable} containing an ordered list of {Name} objects. The names can be formatted using CSL formatting options (see {Names.defaults} for details).
Attributes
@!attribute [r] defaults @example
{ :and => '&', # The delimiter between the penultimate and last name :delimiter => ', ', # The delimiter between the other names :'delimiter-precedes-last' => :contextual, # Determines in which cases the delimiter used to delimit names # is also used to separate the second to last and the last name # in name lists. The possible values are: 'contextual' (default, # the delimiter is only included for name lists with three or # more names), 'always', and 'never' :'et-al' => 'et al.', # The string used for the phrase 'and others' :'et-al-min' => 5, :'et-al-use-first' => 3, # Together, these attributes control et-al abbreviation. When # the number of names in a name variable matches or exceeds # the number set on et-al-min, the rendered name list is truncated # at the number of names set on et-al-use-first. If truncation # occurs, the "et-al" term is appended to the names rendered. # With a single name (et-al-use-first="1"), the "et-al" term is # preceded by a space (e.g. "Doe et al."). With multiple names, # the "et-al" term is preceded by the name delimiter (e.g. # "Doe, Smith, et al.") :'et-al-subsequent-min' => 5, :'et-al-subsequent-use-first' => 3 # See above. Abbreviation rules for subsequent cites (cites # referencing earlier cited items) }
@return [Hash] the Names’ default formatting options
@!attribute [r] options @return [Hash] the current formatting options
Public Class Methods
# File lib/citeproc/names.rb, line 546 def initialize(*arguments) @options = Names.defaults.dup super(arguments.flatten(1)) end
Parses the passed-in string and returns a Names
object. Behaves like parse but returns nil for bad input without raising an error.
@see .parse!
@param names [String] the name or names to be parsed @return [Names,nil] the parsed names
# File lib/citeproc/names.rb, line 481 def parse(names) parse!(names) rescue ParseError nil end
Parses the passed-in string and returns a Names
object.
@param names [String] the name or names to be parsed @return [Names] the parsed names
@raise [ParseError] if the string cannot be parsed.
# File lib/citeproc/names.rb, line 493 def parse!(names) new Namae.parse!(names) rescue raise ParseError, $!.message end
Public Instance Methods
Compares two lists of Names
. @param other [(Name
)] a list of names @return [Fixnum,nil] -1, 0, or 1 depending on the result of the
comparison; or nil if the two objects cannot be compared
# File lib/citeproc/names.rb, line 704 def <=>(other) return nil unless other.respond_to?(:to_a) to_a <=> other.to_a end
@return [String] the connector between the penultimate and the last name
# File lib/citeproc/names.rb, line 672 def connector options[:and] end
@return [String] the delimiter between names
# File lib/citeproc/names.rb, line 595 def delimiter options[:delimiter] end
Set the :‘delimiter-precedes-last’ option to :always @return [self] self
# File lib/citeproc/names.rb, line 637 def delimiter_always_precedes_last! options[:'delimiter-precedes-last'] = :always self end
@return [Boolean] whether or not the should always be inserted between
the penultimate and the last name
# File lib/citeproc/names.rb, line 631 def delimiter_always_precedes_last? !!(options[:'delimiter-precedes-last'].to_s =~ /^always$/i) end
Set the :‘delimiter-precedes-last’ option to :contextual @return [self] self
# File lib/citeproc/names.rb, line 666 def delimiter_contextually_precedes_last! options[:'delimiter-precedes-last'] = :contextual self end
@return [Boolean] whether or not the should be inserted between the
penultimate and the last name depending on the number of names
# File lib/citeproc/names.rb, line 660 def delimiter_contextually_precedes_last? !!(options[:'delimiter-precedes-last'].to_s =~ /^contextual/i) end
Set the :‘delimiter-precedes-last’ option to :never @return [self] self
# File lib/citeproc/names.rb, line 653 def delimiter_never_precedes_last! options[:'delimiter-precedes-last'] = :never self end
@return [Boolean] whether or not the should never be inserted between
the penultimate and the last name
# File lib/citeproc/names.rb, line 647 def delimiter_never_precedes_last? !!(options[:'delimiter-precedes-last'].to_s =~ /^never$/i) end
@return [Boolean] whether or not the delimiter will be inserted between
the penultimate and the last name
# File lib/citeproc/names.rb, line 618 def delimiter_precedes_last? case when delimiter_never_precedes_last? false when delimiter_always_precedes_last? true else length > 2 end end
Calls a block once for each name. If no block is given, an enumerator is returned instead.
@yieldparam name [Name] a name in the list @return [self,Enumerator] self or an enumerator if no block is given
# File lib/citeproc/names.rb, line 691 def each(&block) if block_given? names.each(&block) self else to_enum end end
# File lib/citeproc/names.rb, line 551 def initialize_copy(other) @options, @value = other.options.dup, other.value.map(&:dup) end
@return [String] a human-readable representation of the Names
object
# File lib/citeproc/names.rb, line 736 def inspect "#<CiteProc::Names #{to_s.inspect}>" end
@return [String] the delimiter between the penultimate and last name @see connector
@see delimiter_precedes_last?
# File lib/citeproc/names.rb, line 602 def last_delimiter if delimiter_precedes_last? [delimiter, connector].compact.join.squeeze(' ') else connector end end
@return [Fixnum] the maximum number of names that should be printed
# File lib/citeproc/names.rb, line 579 def max_names [length, options[:'et-al-use-first'].to_i.abs].min end
@return [false] Names
are non-numeric Variables
# File lib/citeproc/names.rb, line 677 def numeric? false end
@return [Boolean] whether or not the variable holds more than one Name
# File lib/citeproc/names.rb, line 682 def plural? length > 1 end
# File lib/citeproc/names.rb, line 555 def replace(values) @value = [] [*values].each do |value| case when value.is_a?(Name) @value << value when value.respond_to?(:each_pair), value.respond_to?(:to_hash) @value << Name.new(value) when value.respond_to?(:to_s) begin @value.concat Namae.parse!(value.to_s).map { |n| Name.new n } rescue raise TypeError, $!.message end else raise TypeError, "failed to create names from #{value.inspect}" end end self end
@return [String] the names in a BibTeX-compatible format
# File lib/citeproc/names.rb, line 726 def to_bibtex map { |n| n.dup.sort_order!.format }.join(' and ') end
@return [Array<Hash>] the list of names converted to hash objects
# File lib/citeproc/names.rb, line 731 def to_citeproc map(&:to_citeproc) end
Converts the list of names into a formatted string depending on the current formatting options. @return [String] the formatted list of names
# File lib/citeproc/names.rb, line 714 def to_s case when truncate? [names[0...max_names].join(delimiter), options[:'et-al']].join(truncated_delimiter) when length < 3 names.join(last_delimiter) else [names[0...-1].join(delimiter), names[-1]].join(last_delimiter) end end
@return [Boolean] whether or not the Names
should be truncate
# File lib/citeproc/names.rb, line 584 def truncate? length >= options[:'et-al-min'].to_i.abs end
@return [Boolean] whether ot not the Names
, if printed on subsequent
cites, should be truncated
# File lib/citeproc/names.rb, line 590 def truncate_subsequent? length >= options[:'et-al-subsequent-min'].to_i end
@return [String] the delimiter between the last name printed name and
the 'and others' term
# File lib/citeproc/names.rb, line 612 def truncated_delimiter max_names > 1 ? delimiter : ' ' end