class CiteProc::Bibliography
Typically a {Bibliography} is returned by a {Processor} instance. It contains a list of references and formatting options.
A Bibliography
can be created from (and exported to) CiteProc
JSON bibliographies; these consist of a two-element list, composed of a JavaScript array containing certain formatting parameters, and a list of strings representing bibliography entries.
See {.defaults} for the default formatting options.
Attributes
@!attribute [r] defaults @example Default Formatting Options
{ :offset => 0, # Some citation styles apply a label (either a number or an # alphanumeric code) to each bibliography entry, and use this # label to cite bibliography items in the main text. In the # bibliography, the labels may either be hung in the margin, # or they may be set flush to the margin, with the citations # indented by a uniform amount to the right. In the latter case, # the amount of indentation needed depends on the maximum width # of any label. The :offset option gives the maximum number of # characters that appear in any label used in the bibliography. # The client that controls the final rendering of the bibliography # string should use this value to calculate and apply a suitable # indentation length. :'entry-spacing' => 1, # An integer representing the spacing between entries in the # bibliography. :'line-spacing' => 1, # An integer representing the spacing between the lines within # each bibliography entry. :'hanging-indent' => false, :'second-field-align' => false # When the second-field-align CSL option is set, this returns # either "flush" or "margin". The calling application should # align text in the bibliography output as described by the CSL # specification. Where second-field-align is not set, this # return value is set to false. }
@return [Hash] default formatting options
@!attribute [r] errors @return [Array<String>] a list of errors
@!attribute header @return [String] content included before the reference list
@!attribute [r] options @see .defaults @return [Hash] the current formatting options
@!attribute prefix @return [String] content included before each reference
@!attribute [r] refrences @return [Array<String>] the list of references
@!attribute suffix @return [String] content included after each reference
Public Class Methods
Source
# File lib/citeproc/bibliography.rb, line 81 def create(input, &block) create!(input, &block) rescue nil end
Create a new Bibliography
from the passed-in string or array, or nil if the input cannot be parsed.
Source
# File lib/citeproc/bibliography.rb, line 89 def create!(input) case when input.is_a?(String) create!(::JSON.parse(input)) when input.is_a?(Hash) create!([input]) when input.is_a?(Array) && input.length == 2 options, references = input new do |b| b.references.concat(references) b.ids.concat(options.fetch('entry_ids', [])) b.errors.concat(options.fetch('bibliography_errors', [])) b.header, b.footer = options['bibstart'], options['bibend'] (options.keys & cp2rb.keys).each do |k| b.options[cp2rb[k]] = options[k] end yield b if block_given? end else raise ParseError, "failed to create Bibliography from #{input.inspect}" end end
Create a new Bibliography
from the passed-in string or array. Raises ParseError
if the input cannot be parsed.
Source
# File lib/citeproc/bibliography.rb, line 162 def initialize(options = {}) @options = Bibliography.defaults.merge(options) @errors, @references, @ids, @connector = [], [], [], "\n" yield self if block_given? end
Public Instance Methods
Source
# File lib/citeproc/bibliography.rb, line 224 def <=>(other) return nil unless other.respond_to?(:references) references <=> other.references end
Source
# File lib/citeproc/bibliography.rb, line 229 def citeproc_options Hash[*options.map { |k,v| [Bibliography.rb2cp[k] || k.to_s, v] }.flatten] end
Source
# File lib/citeproc/bibliography.rb, line 215 def each(&block) if block_given? references.each(&block) self else to_enum end end
Source
# File lib/citeproc/bibliography.rb, line 187 def entry_spacing options[:'entry-spacing'].to_f end
Source
# File lib/citeproc/bibliography.rb, line 195 def hanging_indent? options[:'hanging_indent'] end
Source
# File lib/citeproc/bibliography.rb, line 181 def has_errors? !errors.empty? end
Source
# File lib/citeproc/bibliography.rb, line 169 def initialize_copy(other) @options, @connector = other.options.dup, other.connector.dup @errors, @references, @ids = other.errors.dup, other.references.dup, other.ids.dup end
Source
# File lib/citeproc/bibliography.rb, line 253 def inspect "#<CiteProc::Bibliography @references=[#{references.length}], @errors=[#{errors.length}]>" end
@return [String] a human-readable representation of the bibliography
Source
# File lib/citeproc/bibliography.rb, line 199 def join() [ header, references.map { |r| [prefix, r, suffix].compact.join('') }.join(connector), footer ].compact.join(connector) end
Source
# File lib/citeproc/bibliography.rb, line 191 def line_spacing options[:'line-spacing'].to_f end
Source
# File lib/citeproc/bibliography.rb, line 174 def push(id, reference) ids << id references << reference self end
Source
# File lib/citeproc/bibliography.rb, line 235 def to_citeproc [ citeproc_options.merge({ 'bibstart' => prefix, 'bibend' => suffix, 'bibliography_errors' => errors }), references ] end
Source
# File lib/citeproc/bibliography.rb, line 248 def to_json ::JSON.dump(to_citeproc) end