Class: CiteProc::Name

Inherits:
Variable show all
Defined in:
lib/citeproc/name.rb

Overview

Name Variables

When present in the item data, CSL name variables must be delivered as a list of JavaScript arrays, with one array for each name represented by the variable. Simple personal names are composed of family and given elements, containing respectively the family and given name of the individual.

{ “author” : [

  { "family" : "Doe", "given" : "Jonathan" },
  { "family" : "Roe", "given" : "Jane" }
],
"editor" : [
  { "family" : "Saunders",
    "given" : "John Bertrand de Cusance Morant" }
]

}

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 in the name array:

{ “author” : [

  { "literal" : "Society for Putting Things on Top of Other Things" }
]

}

If the name is spelled using a ‘byzantine’ alphabet (i.e., latin or cyrillic) its sort and display order is computed according to the given arguments.

Constant Summary collapse

ROMANESQUE =

Based on the regular expression in citeproc-js

/^[a-zA-Z\u0080-\u017f\u0400-\u052f\u0386-\u03fb\u1f00-\u1ffe\.,\s'\u0027\u02bc\u2019-]*$/

Instance Attribute Summary

Attributes included from Support::Attributes

#attributes, #key_filter, #value_filter

Instance Method Summary collapse

Methods inherited from Variable

fields, filter, #initialize, parse, #to_i

Methods included from Support::Attributes

#[], #[]=, included, #merge, #reverse_merge

Constructor Details

This class inherits a constructor from CiteProc::Variable

Instance Method Details

#<=>(other) ⇒ Object 



265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
 
# File 'lib/citeproc/name.rb', line 265

def <=>(other)

  tests = self.sort_order.zip(other.sort_order).map do |pair|
    this, that = pair.map { |token| token.gsub(/[\s-]+/,'_').gsub(/literal/, 'literal_sort_order') }          

    this = this.split(/\+/).map { |token| self.send(token) }.join.downcase
    that = that.split(/\+/).map { |token| other.send(token) }.join.downcase

    # TODO should we ignore '' here?
    this <=> that
  end

  tests = tests.reject(&:nil?)
  zeroes = tests.take_while(&:zero?)

  zeroes.length != tests.length ? tests[zeroes.length] : zeroes.empty? ? nil : 0
end

#comma ⇒ Object 



168
169
170
 
# File 'lib/citeproc/name.rb', line 168

def comma
  options['sort-separator'] || ', '
end

#comma_suffix ⇒ Object 



164
165
166
 
# File 'lib/citeproc/name.rb', line 164

def comma_suffix
  self.comma_suffix? && self.suffix? ? comma : nil
end

#defaults ⇒ Object 



48
49
50
 
# File 'lib/citeproc/name.rb', line 48

def defaults
  Hash['form', 'long', 'name-as-sort-order', 'false', 'demote-non-dropping-particle', 'display-and-sort']
end

#delimiter ⇒ Object 



172
173
174
 
# File 'lib/citeproc/name.rb', line 172

def delimiter
  romanesque? ? ' ' : ''
end

#display(options = {}) ⇒ Object

display order options.



249
250
251
 
# File 'lib/citeproc/name.rb', line 249

def display(options={})
  normalize((display_order(options).map { |token| send(token.tr('-', '_')) }.compact.join(delimiter)))
end

#display_order(opts = {}) ⇒ Object

tokens when displaying the name.



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/citeproc/name.rb', line 206

def display_order(opts={})
  merge_options(opts)

  case
  when literal?
    return %w{ literal }
  
  when static_order?
    return %w{ family given }
    
  when options['form'] != 'short' && !sort_order?
    return %w{ given dropping-particle non-dropping-particle family comma-suffix suffix }

  when options['form'] != 'short' && sort_order? && ['never', 'sort-only'].include?(options['demote-non-dropping-particle'])
    return %w{ non-dropping-particle family comma given dropping-particle comma suffix }

  when options['form'] != 'short' && sort_order? && options['demote-non-dropping-particle'] == 'display-and-sort'
    return %w{ family comma given dropping-particle non-dropping-particle comma suffix }

  else # options['form'] == 'short'
    return %w{ non-dropping-particle family}
  end
  
end

#given ⇒ Object 



74
75
76
 
# File 'lib/citeproc/name.rb', line 74

def given
  initialize? ? to_initials(self['given']) : self['given']
end

#initialize? ⇒ Boolean

CSL1.0 Warning

to be displayed using initials. Takes into account whether or not the family name is set (if not, given name should not be turned to initials, this is not sepcified in CSL 1.0).

Returns:

  • (Boolean) 


188
189
190
 
# File 'lib/citeproc/name.rb', line 188

def initialize?
  options.has_key?('initialize-with') && family? && romanesque?
end

#literal_as_sort_order ⇒ Object 



261
262
263
 
# File 'lib/citeproc/name.rb', line 261

def literal_as_sort_order
  literal.gsub(/^(the|an?|der|die|das|eine?|l[ae])\s+/i, '')
end

#merge!(argument) ⇒ Object 



65
66
67
68
69
70
71
72
 
# File 'lib/citeproc/name.rb', line 65

def merge!(argument)
  if argument['parse-names'] && argument.delete('parse-names') != 'false'
    parse_family!(argument.delete('family'))
    parse_given!(argument.delete('given'))
  end
  
  argument.map { |key, value| self[key] = value }
end

#merge_options(options) ⇒ Object 



56
57
58
 
# File 'lib/citeproc/name.rb', line 56

def merge_options(options)
  options.each_pair { |key, value| self.options[key] = value unless value.nil? }
end

#normalize(string) ⇒ Object 



253
254
255
 
# File 'lib/citeproc/name.rb', line 253

def normalize(string)
  string.squeeze(' ').gsub(/^[\s,]+|[\s,]+$|\s(,)/, '\1').squeeze(',')
end

#numeric? ⇒ Boolean

Returns:

  • (Boolean) 


200
201
202
 
# File 'lib/citeproc/name.rb', line 200

def numeric?
  false
end

#options ⇒ Object 



52
53
54
 
# File 'lib/citeproc/name.rb', line 52

def options
  @options ||= defaults
end

#parse!(argument) ⇒ Object 



60
61
62
63
 
# File 'lib/citeproc/name.rb', line 60

def parse!(argument)
  return super unless argument.is_a?(String)
  parse_name!(argument)
end

#parse_family!(string) ⇒ Object

See Also:



121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/citeproc/name.rb', line 121

def parse_family!(string)
  return if string.nil?
  
  tokens = string.scan(/^['"](.+)['"]$|^([[:lower:]\s]+)?([[:upper:]][[:alpha:]\s]*)$/).first
        
  if tokens.nil?
    self['family'] = string
  else
    self['family'] = tokens[0] || tokens[2] || string
    self['non-dropping-particle'] = tokens[1].gsub(/^\s+|\s+$/, '') unless tokens[1].nil?
  end
  
  self
end

#parse_given!(string) ⇒ Object

See Also:



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/citeproc/name.rb', line 137

def parse_given!(string)
  return if string.nil?

  tokens = string.scan(/^((?:[[:upper:]][[:alpha:]\.]*\s*)+)([[:lower:]\s]+)?(?:,!?\s([[:alpha:]\.\s]+))?$/).first

  if tokens.nil?
    self['given'] = string
  else
    self['given'] = (tokens[0] || string).gsub(/^\s+|\s+$/, '')
    self['dropping-particle'] = tokens[1] unless tokens[1].nil?
    self['suffix'] = tokens[2] unless tokens[2].nil?
    self['comma-suffix'] = 'true' if string.match(/,!/)
  end
  
  self
end

#parse_name!(string) ⇒ Object

Parses a string and sets :family, :given, :suffix, and :particles correspondingly.

  • non-dropping-particle: A string at the beginning of the family field consisting of spaces and lowercase roman or Cyrillic characters will be treated as a non-dropping-particle. The particles preceding some names should be treated as part of the last name, depending on the cultural heritage and personal preferences of the individual. To suppress parsing and treat such particles as part of the family name field, enclose the family name field content in double-quotes

  • dropping-particle: A string at the end of the given name field consisting of spaces and lowercase roman or Cyrillic characters will be treated as a dropping-particle.

  • suffix: Content following a comma in the given name field will be parse out as a name suffix. Modern typographical convention does not place a comma between suffixes such as “Jr.” and the last name, when rendering the name in normal order: “John Doe Jr.” If an individual prefers that the traditional comma be used in rendering their name, the comma can be force by placing a exclamation mark after the comma.



109
110
111
112
113
114
115
116
117
118
 
# File 'lib/citeproc/name.rb', line 109

def parse_name!(string)
  return if string.nil?

  tokens = string.split(/,\s+/)

  parse_family!(tokens[0])
  parse_given!(tokens[1])
  
  self
end

#personal? ⇒ Boolean

Returns:

  • (Boolean) 


154
155
156
 
# File 'lib/citeproc/name.rb', line 154

def personal?
  self.family?
end

#romanesque? ⇒ Boolean Also known as: byzantine?

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/citeproc/name.rb', line 158

def romanesque?
  (self['given'].nil? || self['given'].match(ROMANESQUE)) && (self['family'].nil? || self['family'].match(ROMANESQUE))
end

#sort_order(opts = {}) ⇒ Object

individual tokens when sorting the name.



233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/citeproc/name.rb', line 233

def sort_order(opts={})
  merge_options(opts)

  case
  when literal?
    return %w{ literal }
    
  when options['demote-non-dropping-particle'] == 'never'
    return %w{ non-dropping-particle+family dropping-particle given suffix }
  else
    return %w{ family non-dropping-particle+dropping-particle given suffix }
  end
end

#sort_order? ⇒ Boolean

Returns:

  • (Boolean) 


196
197
198
 
# File 'lib/citeproc/name.rb', line 196

def sort_order?
  ['all', 'true', 'yes', 'always'].include?(options['name-as-sort-order'])
end

#static_order? ⇒ Boolean

Returns:

  • (Boolean) 


192
193
194
 
# File 'lib/citeproc/name.rb', line 192

def static_order?
  static_ordering? || !romanesque?
end

#to_initials(name) ⇒ Object 



78
79
80
81
82
83
84
85
86
87
 
# File 'lib/citeproc/name.rb', line 78

def to_initials(name)
  return name if name.nil?
  
  name.split(/\s+|\.\s*/).map do |token|
    token.split(/-/).map do |part|
      # Keep all-lowercase names; otherwise keep only upper case letters
      part.match(/^[[:lower:]]+$/) ? part.center(part.length + 2) : part.scan(/[[:upper:]]/).join.capitalize + options['initialize-with']
    end.join(options['initialize-with-hyphen'] == 'false' ? '' : '-' ).gsub(/\s+-/, '-')
  end.join
end

#to_s ⇒ Object 



257
258
259
 
# File 'lib/citeproc/name.rb', line 257

def to_s
  display
end

#value ⇒ Object 



176
177
178
 
# File 'lib/citeproc/name.rb', line 176

def value
  self
end