Class: CiteProc::Bibliography

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Comparable, Enumerable
Defined in:
lib/citeproc/bibliography.rb

Overview

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 Bibliography.defaults for the default formatting options.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|_self| ... } ⇒ Bibliography

Returns a new instance of Bibliography.

Yields:

  • (_self)

Yield Parameters:



162
163
164
165
166
167
 
# 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

Class Attribute Details

.cp2rb ⇒ Object (readonly)

Returns the value of attribute cp2rb.



77
78
79
 
# File 'lib/citeproc/bibliography.rb', line 77

def cp2rb
  @cp2rb
end

.defaults ⇒ Hash (readonly)

Returns default formatting options.

Examples:

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.
}

Returns:

  • (Hash) —

    default formatting options



75
76
77
 
# File 'lib/citeproc/bibliography.rb', line 75

def defaults
  @defaults
end

.rb2cp ⇒ Object (readonly)

Returns the value of attribute rb2cp.



77
78
79
 
# File 'lib/citeproc/bibliography.rb', line 77

def rb2cp
  @rb2cp
end

Instance Attribute Details

#connector ⇒ Object

Returns the value of attribute connector.



160
161
162
 
# File 'lib/citeproc/bibliography.rb', line 160

def connector
  @connector
end

#errors ⇒ Array<String> (readonly)

Returns a list of errors.

Returns:



139
140
141
 
# File 'lib/citeproc/bibliography.rb', line 139

def errors
  @errors
end

#footer ⇒ String

Returns content included after the reference list.

Returns:

  • (String) —

    content included after the reference list



147
148
149
 
# File 'lib/citeproc/bibliography.rb', line 147

def footer
  @footer
end

#header ⇒ String

Returns content included before the reference list.

Returns:

  • (String) —

    content included before the reference list



143
144
145
 
# File 'lib/citeproc/bibliography.rb', line 143

def header
  @header
end

#ids ⇒ Object (readonly)

Returns the value of attribute ids.



130
131
132
 
# File 'lib/citeproc/bibliography.rb', line 130

def ids
  @ids
end

#options ⇒ Hash (readonly)

Returns the current formatting options.

Returns:

  • (Hash) —

    the current formatting options

See Also:



135
136
137
 
# File 'lib/citeproc/bibliography.rb', line 135

def options
  @options
end

#prefix ⇒ String

Returns content included before each reference.

Returns:

  • (String) —

    content included before each reference



151
152
153
 
# File 'lib/citeproc/bibliography.rb', line 151

def prefix
  @prefix
end

#references ⇒ Array<String> (readonly)

Returns the list of references.

Returns:



128
129
130
 
# File 'lib/citeproc/bibliography.rb', line 128

def references
  @references
end

#refrences ⇒ Array<String> (readonly)

Returns the list of references.

Returns:



128
 
# File 'lib/citeproc/bibliography.rb', line 128

attr_reader :references

#suffix ⇒ String

Returns content included after each reference.

Returns:

  • (String) —

    content included after each reference



155
156
157
 
# File 'lib/citeproc/bibliography.rb', line 155

def suffix
  @suffix
end

Class Method Details

.create(input, &block) ⇒ Object

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



81
82
83
84
85
 
# File 'lib/citeproc/bibliography.rb', line 81

def create(input, &block)
  create!(input, &block)
rescue
  nil
end

.create!(input) ⇒ Object

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



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# 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

Instance Method Details

#<=>(other) ⇒ Object 



224
225
226
227
 
# File 'lib/citeproc/bibliography.rb', line 224

def <=>(other)
  return nil unless other.respond_to?(:references)
  references <=> other.references
end

#citeproc_options ⇒ Object 



229
230
231
232
233
 
# 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) ⇒ Object 



215
216
217
218
219
220
221
222
 
# File 'lib/citeproc/bibliography.rb', line 215

def each(&block)
  if block_given?
    references.each(&block)
    self
  else
    to_enum
  end
end

#entry_spacing ⇒ Object 



187
188
189
 
# File 'lib/citeproc/bibliography.rb', line 187

def entry_spacing
  options[:'entry-spacing'].to_f
end

#hanging_indent? ⇒ Boolean

Returns:

  • (Boolean) 


195
196
197
 
# File 'lib/citeproc/bibliography.rb', line 195

def hanging_indent?
  options[:'hanging_indent']
end

#has_errors? ⇒ Boolean Also known as: errors?

Returns:

  • (Boolean) 


181
182
183
 
# File 'lib/citeproc/bibliography.rb', line 181

def has_errors?
  !errors.empty?
end

#initialize_copy(other) ⇒ Object 



169
170
171
172
 
# 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 ⇒ String

Returns a human-readable representation of the bibliography.

Returns:

  • (String) —

    a human-readable representation of the bibliography



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

def inspect
  "#<CiteProc::Bibliography @references=[#{references.length}], @errors=[#{errors.length}]>"
end

#join ⇒ Object 



199
200
201
202
203
204
205
206
207
208
209
 
# 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 ⇒ Object 



191
192
193
 
# File 'lib/citeproc/bibliography.rb', line 191

def line_spacing
  options[:'line-spacing'].to_f
end

#push(id, reference) ⇒ Object Also known as: << 



174
175
176
177
178
 
# File 'lib/citeproc/bibliography.rb', line 174

def push(id, reference)
  ids << id
  references << reference
  self
end

#to_citeproc ⇒ Object 



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

def to_citeproc
  [
    citeproc_options.merge({
      'bibstart' => prefix,
      'bibend' => suffix,
      'bibliography_errors' => errors
    }),

    references

  ]
end

#to_json ⇒ Object 



248
249
250
 
# File 'lib/citeproc/bibliography.rb', line 248

def to_json
  ::JSON.dump(to_citeproc)
end

#to_s ⇒ Object 



211
212
213
 
# File 'lib/citeproc/bibliography.rb', line 211

def to_s
  join
end