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

defaults[R]

@!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

options[R]

@!attribute [r] options @return [Hash] the current formatting options

Public Class Methods

new(*arguments) click to toggle source
Calls superclass method
# File lib/citeproc/names.rb, line 546
def initialize(*arguments)
  @options = Names.defaults.dup
  super(arguments.flatten(1))
end
parse(names) click to toggle source

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
parse!(names) click to toggle source

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

<=>(other) click to toggle source

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
connector() click to toggle source

@return [String] the connector between the penultimate and the last name

# File lib/citeproc/names.rb, line 672
def connector
  options[:and]
end
delimiter() click to toggle source

@return [String] the delimiter between names

# File lib/citeproc/names.rb, line 595
def delimiter
  options[:delimiter]
end
delimiter_always_precedes_last!() click to toggle source

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
Also aliased as: delimiter_precedes_last!
delimiter_always_precedes_last?() click to toggle source

@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
delimiter_contextually_precedes_last!() click to toggle source

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
delimiter_contextually_precedes_last?() click to toggle source

@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
delimiter_never_precedes_last!() click to toggle source

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
delimiter_never_precedes_last?() click to toggle source

@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
delimiter_precedes_last!()
delimiter_precedes_last?() click to toggle source

@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
each(&block) click to toggle source

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
initialize_copy(other) click to toggle source
# File lib/citeproc/names.rb, line 551
def initialize_copy(other)
  @options, @value = other.options.dup, other.value.map(&:dup)
end
inspect() click to toggle source

@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
last_delimiter() click to toggle source

@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
max_names() click to toggle source

@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
numeric?() click to toggle source

@return [false] Names are non-numeric Variables

# File lib/citeproc/names.rb, line 677
def numeric?
  false
end
plural?() click to toggle source

@return [Boolean] whether or not the variable holds more than one Name

# File lib/citeproc/names.rb, line 682
def plural?
        length > 1
end
replace(values) click to toggle source
# 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
to_bibtex() click to toggle source

@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
to_citeproc() click to toggle source

@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
to_s() click to toggle source

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
truncate?() click to toggle source

@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
truncate_subsequent?() click to toggle source

@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
truncated_delimiter() click to toggle source

@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