class CFF::Reference

Reference provides a reference pertaining to the software version or the software itself, e.g., a software paper describing the abstract concepts of the software, a paper describing an algorithm that has been implemented in the software version, etc.

Reference implements all of the fields listed in the [CFF standard](citation-file-format.github.io/). Complex fields - `authors`, `contact`, `editors`, `editors_series`, `identifiers`, `keywords`, `languages`, `patent_states`, `recipients`, `senders` and `translators` - are documented below. All other fields are simple strings and can be set as such. A field which has not been set will return the empty string. The simple fields are (with defaults in parentheses):

Constants

REFERENCE_STATUS_TYPES

The [defined set of reference status types](github.com/citation-file-format/citation-file-format#status-strings).

REFERENCE_TYPES

The [defined set of reference types](github.com/citation-file-format/citation-file-format#reference-types).

Public Class Methods

from_cff(File, type: 'software') → Reference click to toggle source
from_cff(Model, type: 'software') → Reference

Create a Reference from another CFF File or Model. This is useful for easily adding a reference to something with its own CITATION.cff file already.

This method assumes that the type of the Reference should be `software`, but this can be overridden with the `type` parameter.

# File lib/cff/reference.rb, line 173
def self.from_cff(model, type: 'software')
  new(model.title, type) do |ref|
    %w[
      abstract authors contact commit date_released doi
      identifiers keywords license license_url repository
      repository_artifact repository_code url version
    ].each do |field|
      value = model.send(field)
      ref.send("#{field}=", value.dup) unless value == ''
    end
  end
end
new(title) → Reference click to toggle source
new(title) { |ref| block } → Reference
new(title, type) → Reference
new(title, type) { |ref| block } → Reference

Create a new Reference with the supplied title and, optionally, type. If type is not given, or is not one of the [defined set of reference types](github.com/citation-file-format/citation-file-format#reference-types), 'generic' will be used by default.

# File lib/cff/reference.rb, line 142
def initialize(param, *more) # rubocop:disable Metrics/AbcSize
  if param.is_a?(Hash)
    @fields = build_model(param)
    @fields.default = ''
  else
    @fields = Hash.new('')
    type = more[0] &&= more[0].downcase
    @fields['type'] = REFERENCE_TYPES.include?(type) ? type : 'generic'
    @fields['title'] = param
  end

  [
    'authors', 'contact', 'editors', 'editors-series', 'identifiers',
    'keywords', 'patent-states', 'recipients', 'senders', 'translators'
  ].each do |field|
    @fields[field] = [] if @fields[field].empty?
  end

  yield self if block_given?
end

Public Instance Methods

add_language language click to toggle source

Add a language to this Reference. Input is converted to the ISO 639-3 three letter language code, so `GER` becomes `deu`, `french` becomes `fra` and `en` becomes `eng`.

# File lib/cff/reference.rb, line 192
def add_language(lang)
  @fields['languages'] = [] if @fields['languages'].empty?
  lang = LanguageList::LanguageInfo.find(lang)
  return if lang.nil?

  lang = lang.iso_639_3
  @fields['languages'] << lang unless @fields['languages'].include? lang
end
authors → Array click to toggle source

Return the list of authors for this Reference. To add an author to the list, use:

“` reference.authors << author “`

Authors can be a Person or Entity.

# File lib/cff/reference.rb, line 339
    
authors = array_of_authors → Array click to toggle source

Replace the list of authors for this reference.

Authors can be a Person or Entity.

# File lib/cff/reference.rb, line 353
    
contact → Array click to toggle source

Return the list of contacts for this Reference. To add a contact to the list, use:

“` reference.contact << contact “`

Contacts can be a Person or Entity.

# File lib/cff/reference.rb, line 362
    
contact = array_of_contacts → Array click to toggle source

Replace the list of contacts for this reference.

Contacts can be a Person or Entity.

# File lib/cff/reference.rb, line 376
    
date_accessed = date click to toggle source

Set the `date-accessed` field. If a non-Date object is passed in it will be parsed into a Date.

# File lib/cff/reference.rb, line 222
def date_accessed=(date)
  date = Date.parse(date) unless date.is_a?(Date)

  @fields['date-accessed'] = date
end
date_downloaded = date click to toggle source

Set the `date-downloaded` field. If a non-Date object is passed in it will be parsed into a Date.

# File lib/cff/reference.rb, line 233
def date_downloaded=(date)
  date = Date.parse(date) unless date.is_a?(Date)

  @fields['date-downloaded'] = date
end
date_published = date click to toggle source

Set the `date-published` field. If a non-Date object is passed in it will be parsed into a Date.

# File lib/cff/reference.rb, line 244
def date_published=(date)
  date = Date.parse(date) unless date.is_a?(Date)

  @fields['date-published'] = date
end
date_released = date click to toggle source

Set the `date-released` field. If a non-Date object is passed in it will be parsed into a Date.

# File lib/cff/reference.rb, line 255
def date_released=(date)
  date = Date.parse(date) unless date.is_a?(Date)

  @fields['date-released'] = date
end
editors → Array click to toggle source

Return the list of editors for this Reference. To add an editor to the list, use:

“` reference.editors << editor “`

An editor can be a Person or Entity.

# File lib/cff/reference.rb, line 385
    
editors = array_of_editors → Array click to toggle source

Replace the list of editors for this reference.

Editors can be a Person or Entity.

# File lib/cff/reference.rb, line 399
    
editors_series → Array click to toggle source

Return the list of series editors for this Reference. To add a series editor to the list, use:

“` reference.editors_series << editor “`

An editor can be a Person or Entity.

# File lib/cff/reference.rb, line 408
    
editors_series = array_of_series_editors → Array click to toggle source

Replace the list of series editors for this reference.

Series editors can be a Person or Entity.

# File lib/cff/reference.rb, line 422
    
identifiers → Array click to toggle source

Return the list of identifiers for this citation. To add a identifier to the list, use:

“` model.identifiers << identifier “`

# File lib/cff/reference.rb, line 431
    
identifiers = array_of_identifiers → Array click to toggle source

Replace the list of identifiers for this citation.

# File lib/cff/reference.rb, line 443
    
keywords → Array click to toggle source

Return the list of keywords for this reference. To add a keyword to the list, use:

“` model.keywords << keyword “`

Keywords will be converted to Strings on output.

# File lib/cff/reference.rb, line 450
    
keywords = array_of_keywords → Array click to toggle source

Replace the list of keywords for this reference.

Keywords will be converted to Strings on output.

# File lib/cff/reference.rb, line 464
    
languages → Array click to toggle source

Return the list of languages associated with this Reference.

# File lib/cff/reference.rb, line 213
def languages
  @fields['languages'].empty? ? [] : @fields['languages'].dup
end
patent_states → Array click to toggle source

Return the list of patent states for this reference. To add a patent state to the list, use:

“` model.patent_states << patent_state “`

Patent states will be converted to Strings on output.

# File lib/cff/reference.rb, line 473
    
patent_states = array_of_states → Array click to toggle source

Replace the list of patent states for this reference.

Patent states will be converted to Strings on output.

# File lib/cff/reference.rb, line 487
    
recipients → Array click to toggle source

Return the list of recipients for this Reference. To add a recipient to the list, use:

“` reference.recipients << recipient “`

Recipients can be a Person or Entity.

# File lib/cff/reference.rb, line 496
    
recipients = array_of_recipients → Array click to toggle source

Replace the list of recipients for this reference.

Recipients can be a Person or Entity.

# File lib/cff/reference.rb, line 510
    
reset_languages click to toggle source

Reset the list of languages for this Reference to be empty.

# File lib/cff/reference.rb, line 205
def reset_languages
  @fields.delete('languages')
end
senders → Array click to toggle source

Return the list of senders for this Reference. To add a sender to the list, use:

“` reference.senders << sender “`

Senders can be a Person or Entity.

# File lib/cff/reference.rb, line 519
    
senders = array_of_senders → Array click to toggle source

Replace the list of senders for this reference.

Senders can be a Person or Entity.

# File lib/cff/reference.rb, line 533
    
status = status click to toggle source

Sets the status of this Reference. The status is restricted to a [defined set of status types](github.com/citation-file-format/citation-file-format#status-strings).

# File lib/cff/reference.rb, line 282
def status=(status)
  status = status.downcase
  @fields['status'] = status if REFERENCE_STATUS_TYPES.include?(status)
end
translators → Array click to toggle source

Return the list of translators for this Reference. To add a translator to the list, use:

“` reference.translators << translator “`

Translators can be a Person or Entity.

# File lib/cff/reference.rb, line 542
    
translators = array_of_translators → Array click to toggle source

Replace the list of translators for this reference.

Translators can be a Person or Entity.

# File lib/cff/reference.rb, line 556
  
type = type click to toggle source

Sets the type of this Reference. The type is restricted to a [defined set of reference types](github.com/citation-file-format/citation-file-format#reference-types).

# File lib/cff/reference.rb, line 292
def type=(type)
  type = type.downcase
  @fields['type'] = type if REFERENCE_TYPES.include?(type)
end