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

cp2rb[R]
defaults[R]

@!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

rb2cp[R]
connector[RW]
errors[R]

@!attribute [r] errors @return [Array<String>] a list of errors

header[RW]

@!attribute header @return [String] content included before the reference list

ids[R]
options[R]

@!attribute [r] options @see .defaults @return [Hash] the current formatting options

prefix[RW]

@!attribute prefix @return [String] content included before each reference

references[R]

@!attribute [r] refrences @return [Array<String>] the list of references

suffix[RW]

@!attribute suffix @return [String] content included after each reference

Public Class Methods

create(input, &block) click to toggle source

Create a new Bibliography from the passed-in string or array, or nil if the input cannot be parsed.

# File lib/citeproc/bibliography.rb, line 81
def create(input, &block)
  create!(input, &block)
rescue
  nil
end
create!(input) { |b| ... } click to toggle source

Create a new Bibliography from the passed-in string or array. Raises ParseError if the input cannot be parsed.

# 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
new(options = {}) { |self| ... } click to toggle 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

<<(id, reference)
Alias for: push
<=>(other) click to toggle source
# File lib/citeproc/bibliography.rb, line 224
def <=>(other)
  return nil unless other.respond_to?(:references)
  references <=> other.references
end
citeproc_options() click to toggle 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
each(&block) click to toggle source
# File lib/citeproc/bibliography.rb, line 215
def each(&block)
  if block_given?
    references.each(&block)
    self
  else
    to_enum
  end
end
entry_spacing() click to toggle source
# File lib/citeproc/bibliography.rb, line 187
def entry_spacing
  options[:'entry-spacing'].to_f
end
errors?()
Alias for: has_errors?
hanging_indent?() click to toggle source
# File lib/citeproc/bibliography.rb, line 195
def hanging_indent?
  options[:'hanging_indent']
end
has_errors?() click to toggle source
# File lib/citeproc/bibliography.rb, line 181
def has_errors?
  !errors.empty?
end
Also aliased as: errors?
initialize_copy(other) click to toggle 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
inspect() click to toggle source

@return [String] a human-readable representation of the bibliography

# File lib/citeproc/bibliography.rb, line 253
def inspect
  "#<CiteProc::Bibliography @references=[#{references.length}], @errors=[#{errors.length}]>"
end
join() click to toggle 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
line_spacing() click to toggle source
# File lib/citeproc/bibliography.rb, line 191
def line_spacing
  options[:'line-spacing'].to_f
end
push(id, reference) click to toggle source
# File lib/citeproc/bibliography.rb, line 174
def push(id, reference)
  ids << id
  references << reference
  self
end
Also aliased as: <<
to_citeproc() click to toggle source
# File lib/citeproc/bibliography.rb, line 235
def to_citeproc
  [
    citeproc_options.merge({
      'bibstart' => prefix,
      'bibend' => suffix,
      'bibliography_errors' => errors
    }),

    references

  ]
end
to_json() click to toggle source
# File lib/citeproc/bibliography.rb, line 248
def to_json
  ::JSON.dump(to_citeproc)
end
to_s() click to toggle source
# File lib/citeproc/bibliography.rb, line 211
def to_s
  join
end