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):
-
`abbreviation`
-
`abstract`
-
`collection_doi`
-
`collection_title`
-
`collection_type`
-
`commit`
-
`conference`
-
`copyright`
-
`data-type`
-
`database`
-
`database_provider`
-
`date_accessed` - Note: returns a `Date` object
-
`date_downloaded` - Note: returns a `Date` object
-
`date_published` - Note: returns a `Date` object
-
`date_released` - Note: returns a `Date` object
-
`department`
-
`doi`
-
`edition`
-
`end`
-
`entry`
-
`filename`
-
`format`
-
`institution`
-
`isbn`
-
`issn`
-
`issue`
-
`issue_date` - Note: returns a `Date` object
-
`issue_title`
-
`journal`
-
`license` - Note: see documentation for `license =` below
-
`license_url`
-
`loc_end`
-
`loc_start`
-
`location`
-
`medium`
-
`month`
-
`nihmsid`
-
`notes`
-
`number`
-
`number_volumes`
-
`pages`
-
`pmcid`
-
`publisher`
-
`repository`
-
`repository_code`
-
`repository_artifact`
-
`scope`
-
`section`
-
`start`
-
`status` - Note: see documentation for `status =` below
-
`thesis_type`
-
`title`
-
`type` - Note: see documentation for `type =` below
-
`url`
-
`version`
-
`volume`
-
`volume_title`
-
`year`
-
`year_original`
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
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
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 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
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
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
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
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
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
Replace the list of identifiers for this citation.
# File lib/cff/reference.rb, line 443
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
Replace the list of keywords for this reference.
Keywords will be converted to Strings on output.
# File lib/cff/reference.rb, line 464
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
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
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
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
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
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