Class: CiteProc::Names

Inherits:
Variable show all
Includes:
Enumerable
Defined in:
lib/citeproc/names.rb

Overview

Represents a Variable containing an ordered list of Name objects. The names can be formatted using CSL formatting options (see Names.defaults for details).

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes inherited from Variable

#value

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Variable

create, create!, #date?, #romanize, #strip_markup, #strip_markup!, #to_f, #to_json, #tokenize, #type

Constructor Details

#initialize(*arguments) ⇒ Names

Returns a new instance of Names.



547
548
549
550
 
# File 'lib/citeproc/names.rb', line 547

def initialize(*arguments)
  @options = Names.defaults.dup
  super(arguments.flatten(1))
end

Class Attribute Details

.defaults ⇒ Hash (readonly)

Returns the Names’ default formatting options.

Examples:

{
  :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)
}

Returns:

  • (Hash) —

    the Names’ default formatting options



473
474
475
 
# File 'lib/citeproc/names.rb', line 473

def defaults
  @defaults
end

Instance Attribute Details

#options ⇒ Hash (readonly)

Returns the current formatting options.

Returns:

  • (Hash) —

    the current formatting options



507
508
509
 
# File 'lib/citeproc/names.rb', line 507

def options
  @options
end

Class Method Details

.parse(names) ⇒ Names?

Parses the passed-in string and returns a Names object. Behaves like parse but returns nil for bad input without raising an error.

Parameters:

  • names (String) —

    the name or names to be parsed

Returns:

  • (Names, nil) —

    the parsed names

See Also:



482
483
484
485
486
 
# File 'lib/citeproc/names.rb', line 482

def parse(names)
  parse!(names)
rescue ParseError
  nil
end

.parse!(names) ⇒ Names

Parses the passed-in string and returns a Names object.

Parameters:

  • names (String) —

    the name or names to be parsed

Returns:

  • (Names) —

    the parsed names

Raises:

  • (ParseError) —

    if the string cannot be parsed.



494
495
496
497
498
 
# File 'lib/citeproc/names.rb', line 494

def parse!(names)
  new Namae.parse!(names)
rescue
  raise ParseError, $!.message
end

Instance Method Details

#<=>(other) ⇒ Fixnum?

Compares two lists of Names.

Parameters:

  • other ((Name)) —

    a list of names

Returns:

  • (Fixnum, nil) —

    -1, 0, or 1 depending on the result of the comparison; or nil if the two objects cannot be compared



705
706
707
708
 
# File 'lib/citeproc/names.rb', line 705

def <=>(other)
  return nil unless other.respond_to?(:to_a)
  to_a <=> other.to_a
end

#connector ⇒ String

Returns the connector between the penultimate and the last name.

Returns:

  • (String) —

    the connector between the penultimate and the last name



673
674
675
 
# File 'lib/citeproc/names.rb', line 673

def connector
  options[:and]
end

#delimiter ⇒ String

Returns the delimiter between names.

Returns:

  • (String) —

    the delimiter between names



596
597
598
 
# File 'lib/citeproc/names.rb', line 596

def delimiter
  options[:delimiter]
end

#delimiter_always_precedes_last! ⇒ self Also known as: delimiter_precedes_last!

Set the :‘delimiter-precedes-last’ option to :always

Returns:

  • (self) —

    self



638
639
640
641
 
# File 'lib/citeproc/names.rb', line 638

def delimiter_always_precedes_last!
  options[:'delimiter-precedes-last'] = :always
  self
end

#delimiter_always_precedes_last? ⇒ Boolean

Returns whether or not the should always be inserted between the penultimate and the last name.

Returns:

  • (Boolean) —

    whether or not the should always be inserted between the penultimate and the last name



632
633
634
 
# File 'lib/citeproc/names.rb', line 632

def delimiter_always_precedes_last?
  !!(options[:'delimiter-precedes-last'].to_s =~ /^always$/i)
end

#delimiter_contextually_precedes_last! ⇒ self

Set the :‘delimiter-precedes-last’ option to :contextual

Returns:

  • (self) —

    self



667
668
669
670
 
# File 'lib/citeproc/names.rb', line 667

def delimiter_contextually_precedes_last!
  options[:'delimiter-precedes-last'] = :contextual
  self
end

#delimiter_contextually_precedes_last? ⇒ Boolean

Returns whether or not the should be inserted between the penultimate and the last name depending on the number of names.

Returns:

  • (Boolean) —

    whether or not the should be inserted between the penultimate and the last name depending on the number of names



661
662
663
 
# File 'lib/citeproc/names.rb', line 661

def delimiter_contextually_precedes_last?
  !!(options[:'delimiter-precedes-last'].to_s =~ /^contextual/i)
end

#delimiter_never_precedes_last! ⇒ self

Set the :‘delimiter-precedes-last’ option to :never

Returns:

  • (self) —

    self



654
655
656
657
 
# File 'lib/citeproc/names.rb', line 654

def delimiter_never_precedes_last!
  options[:'delimiter-precedes-last'] = :never
  self
end

#delimiter_never_precedes_last? ⇒ Boolean

Returns whether or not the should never be inserted between the penultimate and the last name.

Returns:

  • (Boolean) —

    whether or not the should never be inserted between the penultimate and the last name



648
649
650
 
# File 'lib/citeproc/names.rb', line 648

def delimiter_never_precedes_last?
  !!(options[:'delimiter-precedes-last'].to_s =~ /^never$/i)
end

#delimiter_precedes_last? ⇒ Boolean

Returns whether or not the delimiter will be inserted between the penultimate and the last name.

Returns:

  • (Boolean) —

    whether or not the delimiter will be inserted between the penultimate and the last name



619
620
621
622
623
624
625
626
627
628
 
# File 'lib/citeproc/names.rb', line 619

def delimiter_precedes_last?
  case
  when delimiter_never_precedes_last?
    false
  when delimiter_always_precedes_last?
    true
  else
    length > 2
  end
end

#each {|name| ... } ⇒ self, Enumerator

Calls a block once for each name. If no block is given, an enumerator is returned instead.

Yield Parameters:

  • name (Name) —

    a name in the list

Returns:

  • (self, Enumerator) —

    self or an enumerator if no block is given



692
693
694
695
696
697
698
699
 
# File 'lib/citeproc/names.rb', line 692

def each(&block)
  if block_given?
    names.each(&block)
    self
  else
    to_enum
  end
end

#initialize_copy(other) ⇒ Object 



552
553
554
 
# File 'lib/citeproc/names.rb', line 552

def initialize_copy(other)
  @options, @value = other.options.dup, other.value.map(&:dup)
end

#inspect ⇒ String

Returns a human-readable representation of the Names object.

Returns:

  • (String) —

    a human-readable representation of the Names object



737
738
739
 
# File 'lib/citeproc/names.rb', line 737

def inspect
  "#<CiteProc::Names #{to_s.inspect}>"
end

#last_delimiter ⇒ String

Returns the delimiter between the penultimate and last name.

Returns:

  • (String) —

    the delimiter between the penultimate and last name

See Also:



603
604
605
606
607
608
609
 
# File 'lib/citeproc/names.rb', line 603

def last_delimiter
  if delimiter_precedes_last?
    [delimiter, connector].compact.join.squeeze(' ')
  else
    connector
  end
end

#max_names ⇒ Fixnum

Returns the maximum number of names that should be printed.

Returns:

  • (Fixnum) —

    the maximum number of names that should be printed



580
581
582
 
# File 'lib/citeproc/names.rb', line 580

def max_names
  [length, options[:'et-al-use-first'].to_i.abs].min
end

#numeric? ⇒ false

Returns Names are non-numeric Variables.

Returns:

  • (false) —

    Names are non-numeric Variables



678
679
680
 
# File 'lib/citeproc/names.rb', line 678

def numeric?
  false
end

#plural? ⇒ Boolean

Returns whether or not the variable holds more than one Name.

Returns:

  • (Boolean) —

    whether or not the variable holds more than one Name



683
684
685
 
# File 'lib/citeproc/names.rb', line 683

def plural?
	length > 1
end

#push(name) ⇒ self

Appends the given name to the list of names.

Parameters:

  • name (Name) —

    a name

Returns:

  • (self) 


540
541
542
543
544
545
 
# File 'lib/citeproc/names.rb', line 540

[:<<, :push, :unshift].each do |m|
  define_method(m) do |*arguments, &block|
    names.send(m, *arguments, &block)
    self
  end
end

#replace(values) ⇒ Object 



556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
 
# File 'lib/citeproc/names.rb', line 556

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 ⇒ String

Returns the names in a BibTeX-compatible format.

Returns:

  • (String) —

    the names in a BibTeX-compatible format



727
728
729
 
# File 'lib/citeproc/names.rb', line 727

def to_bibtex
  map { |n| n.dup.sort_order!.format }.join(' and ')
end

#to_citeproc ⇒ Array<Hash>

Returns the list of names converted to hash objects.

Returns:

  • (Array<Hash>) —

    the list of names converted to hash objects



732
733
734
 
# File 'lib/citeproc/names.rb', line 732

def to_citeproc
  map(&:to_citeproc)
end

#to_s ⇒ String

Converts the list of names into a formatted string depending on the current formatting options.

Returns:

  • (String) —

    the formatted list of names



715
716
717
718
719
720
721
722
723
724
 
# File 'lib/citeproc/names.rb', line 715

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? ⇒ Boolean

Returns whether or not the Names should be truncate.

Returns:

  • (Boolean) —

    whether or not the Names should be truncate



585
586
587
 
# File 'lib/citeproc/names.rb', line 585

def truncate?
  length >= options[:'et-al-min'].to_i.abs
end

#truncate_subsequent? ⇒ Boolean

Returns whether ot not the Names, if printed on subsequent cites, should be truncated.

Returns:

  • (Boolean) —

    whether ot not the Names, if printed on subsequent cites, should be truncated



591
592
593
 
# File 'lib/citeproc/names.rb', line 591

def truncate_subsequent?
  length >= options[:'et-al-subsequent-min'].to_i
end

#truncated_delimiter ⇒ String

Returns the delimiter between the last name printed name and the ‘and others’ term.

Returns:

  • (String) —

    the delimiter between the last name printed name and the ‘and others’ term



613
614
615
 
# File 'lib/citeproc/names.rb', line 613

def truncated_delimiter
  max_names > 1 ? delimiter : ' '
end

#unshift(name) ⇒ self

Inserts the given name at the beginning of the list of names.

Parameters:

  • name (Name) —

    a name

Returns:

  • (self) 


540
541
542
543
544
545
 
# File 'lib/citeproc/names.rb', line 540

[:<<, :push, :unshift].each do |m|
  define_method(m) do |*arguments, &block|
    names.send(m, *arguments, &block)
    self
  end
end