Class: BibTeX::Bibliography

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

Overview

The Bibliography class models a BibTeX bibliography; typically, it corresponds to a ‘.bib’ file.

Defined Under Namespace

Classes: RDFConverter

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

Creates a new bibliography.

Yields:

  • (_self)

Yield Parameters:



95
96
97
98
99
100
101
102
103
 
# File 'lib/bibtex/bibliography.rb', line 95

def initialize(options = {})
  @options = Bibliography.defaults.merge(options)
  @data = []
  @strings = {}
  @errors = []
  @entries = Hash.new { |h, k| h.fetch(k.to_s, nil) }

  yield self if block_given?
end

Class Attribute Details

.defaults ⇒ Object (readonly)

Returns the value of attribute defaults.



33
34
35
 
# File 'lib/bibtex/bibliography.rb', line 33

def defaults
  @defaults
end

Instance Attribute Details

#data ⇒ Object (readonly)

Returns the value of attribute data.



84
85
86
 
# File 'lib/bibtex/bibliography.rb', line 84

def data
  @data
end

#entries ⇒ Object (readonly)

Returns the value of attribute entries.



84
85
86
 
# File 'lib/bibtex/bibliography.rb', line 84

def entries
  @entries
end

#errors ⇒ Object (readonly)

Returns the value of attribute errors.



84
85
86
 
# File 'lib/bibtex/bibliography.rb', line 84

def errors
  @errors
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



84
85
86
 
# File 'lib/bibtex/bibliography.rb', line 84

def options
  @options
end

#path ⇒ Object

Returns the value of attribute path.



82
83
84
 
# File 'lib/bibtex/bibliography.rb', line 82

def path
  @path
end

#strings ⇒ Object (readonly)

Returns the value of attribute strings.



84
85
86
 
# File 'lib/bibtex/bibliography.rb', line 84

def strings
  @strings
end

Class Method Details

.attr_by_type(*arguments) ⇒ Object

Defines a new accessor that selects elements by type.



74
75
76
77
78
79
 
# File 'lib/bibtex/bibliography.rb', line 74

def attr_by_type(*arguments)
  arguments.each do |type|
    method_id = "#{type}s"
    define_method(method_id) { find_by_type(type) } unless respond_to?(method_id)
  end
end

.open(path, options = {}) ⇒ Object

Opens and parses the ‘.bib’ file at the given path. Returns a new Bibliography instance corresponding to the file, or, if a block is given, yields the instance to the block, ensuring that the file is saved after the block’s execution (use the :out option if you want to specify a save path other than the path from where the file is loaded).

The options argument is passed on to BibTeX::Parser.new. Additional option parameters are:

-:parse_names: set to false to disable automatic name parsing -:parse_months: set to false to disable automatic month conversion -:filter: convert all entries using the sepcified filter (not set by default)



49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/bibtex/bibliography.rb', line 49

def open(path, options = {})
  b = parse(File.read(path, encoding: 'utf-8'), options)
  b.path = path
  return b unless block_given?

  begin
    yield b
  ensure
    b.save_to(options[:out] || path)
  end
end

.parse(input, options = {}) ⇒ Object

Parses the given string and returns a corresponding Bibliography instance.



62
63
64
65
66
67
68
69
70
71
 
# File 'lib/bibtex/bibliography.rb', line 62

def parse(input, options = {})
  case input
  when Array, Hash, Element
    Bibliography.new(options).add(input)
  when ::String
    Parser.new(options).parse(input) || Bibliography.new(options)
  else
    raise ArgumentError, "failed to parse #{input.inspect}"
  end
end

Instance Method Details

#<=>(other) ⇒ Object 



501
502
503
 
# File 'lib/bibtex/bibliography.rb', line 501

def <=>(other)
  other.respond_to?(:to_a) ? to_a <=> other.to_a : nil
end

#[](*arguments) ⇒ Object

call-seq: >> bib

> Returns the last element of the Bibliography or nil

>> bib

> Returns the second and third elements or nil

>> bib >> Same as above >> bib

> Returns the first entry with key ‘key’ or nil

>> bib

> Same as above

>> bib

> Returns all entries of type ‘article’ or []

>> bib

> Returns all preamble objects (this is the same as Bibliography#preambles) or []

>> bib

> Returns all objects that match ‘ruby’ anywhere or []

>> bib[‘@book’]

> Returns all books whose keywords attribute equals ‘ruby’ or []

Returns an element or a list of elements according to the given index, range, or query. Contrary to the Bibliography#query this method does not yield to a block for additional refinement of the query.

Raises:



218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/bibtex/bibliography.rb', line 218

def [](*arguments)
  raise(ArgumentError, "wrong number of arguments (#{arguments.length} for 1..2)") unless arguments.length.between?(1, 2)

  if arguments[0].is_a?(Numeric) || arguments[0].is_a?(Range)
    data[*arguments]
  elsif arguments.length == 1
    if arguments[0].nil?
      nil
    elsif arguments[0].respond_to?(:empty?) && arguments[0].empty?
      nil
    elsif arguments[0].is_a?(Symbol)
      entries[arguments[0]]
    elsif arguments[0].respond_to?(:start_with?) && !arguments[0].start_with?('@', '!@')
      entries[arguments[0]]
    else
      query(*arguments)
    end
  else
    query(*arguments)
  end
end

#add(*arguments) ⇒ Object Also known as: <<, push

Adds a new element, or a list of new elements to the bibliography. Returns the Bibliography for chainability.



121
122
123
124
125
126
 
# File 'lib/bibtex/bibliography.rb', line 121

def add(*arguments)
  Element.parse(arguments.flatten, @options).each do |element|
    data << element.added_to_bibliography(self)
  end
  self
end

#convert(*filters) ⇒ Object

Converts all enties using the given filter(s). If an optional block is given the block is used as a condition (the block will be called with each entry). @see Entry#convert!



169
170
171
172
173
174
175
176
177
 
# File 'lib/bibtex/bibliography.rb', line 169

def convert(*filters)
  filters = filters.flatten.map { |f| Filters.resolve!(f) }

  entries.each_value do |entry|
    entry.convert!(*filters) if !block_given? || yield(entry)
  end

  self
end

#delete(*arguments, &block) ⇒ Object Also known as: remove, rm

Deletes an object, or a list of objects from the bibliography. If a list of objects is to be deleted, you can either supply the list of objects or use a query or block to define the list.

Returns the object (or the list of objects) that were deleted; nil if the object was not part of the bibliography.



185
186
187
188
189
 
# File 'lib/bibtex/bibliography.rb', line 185

def delete(*arguments, &block)
  objects = q(*arguments, &block).map { |o| o.removed_from_bibliography(self) }
  @data -= objects
  objects.length == 1 ? objects[0] : objects
end

#duplicates? ⇒ Boolean

Returns:

  • (Boolean) 


520
521
522
 
# File 'lib/bibtex/bibliography.rb', line 520

def duplicates?
  !select_duplicates_by.empty?
end

#each(&block) ⇒ Object 



147
148
149
150
151
152
153
154
 
# File 'lib/bibtex/bibliography.rb', line 147

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

#each_entry(&block) ⇒ Object 



487
488
489
490
491
492
493
 
# File 'lib/bibtex/bibliography.rb', line 487

def each_entry(&block)
  if block_given?
    q('@entry').each(&block)
  else
    q('@entry').to_enum
  end
end

#errors? ⇒ Boolean

Returns true if there are object which could not be parsed.

Returns:

  • (Boolean) 


241
242
243
 
# File 'lib/bibtex/bibliography.rb', line 241

def errors?
  !errors.empty?
end

#extend_initials(*arguments) ⇒ Object

call-seq:

b.extend_initials(['Edgar Allen', 'Poe'], ['Nathaniel', 'Hawthorne'])
#=> Extends the initials in names like 'E.A. Poe' or 'Hawethorne, N.'
    in the bibliography.

Extends the initials for the given names. Returns the Bibliography.



294
295
296
297
298
299
300
301
302
 
# File 'lib/bibtex/bibliography.rb', line 294

def extend_initials(*arguments)
  arguments.each do |with_first, for_last|
    names.each do |name|
      name.extend_initials(with_first, for_last)
    end
  end

  self
end

#extend_initials! ⇒ Object

This method combines all names in the bibliography that look identical when using initials as first names and then tries to extend the first names for all names in each group to the longest available form. Returns the bibliography.

If your bibliography contains the names ‘Poe, Edgar A.’, ‘Poe, E.A.’, and ‘Poe, E. A.’ calling this method would convert all three names to ‘Poe, Edgar A.’.



312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/bibtex/bibliography.rb', line 312

def extend_initials!
  groups = Hash.new do |h, k|
    h[k] = { prototype: nil, names: [] }
  end

  # group names together
  names.each do |name|
    group = groups[name.sort_order(initials: true).downcase]
    group[:names] << name

    group[:prototype] = name if group[:prototype].nil? || group[:prototype].first.to_s.length < name.first.to_s.length
  end

  # extend all names in group to prototype
  groups.each_value do |group|
    group[:names].each do |name|
      name.set(group[:prototype])
    end
  end

  self
end

#find_by_type(*types, &block) ⇒ Object Also known as: find_by_types 



495
496
497
 
# File 'lib/bibtex/bibliography.rb', line 495

def find_by_type(*types, &block)
  q(types.flatten.compact.map { |t| "@#{t}" }.join(', '), &block)
end

#group_by(*arguments, &block) ⇒ Object 



353
354
355
356
357
358
359
360
361
 
# File 'lib/bibtex/bibliography.rb', line 353

def group_by(*arguments, &block)
  groups = Hash.new { |h, k| h[k] = [] }

  entries.values.each do |e|
    groups[e.digest(arguments, &block)] << e
  end

  groups
end

#initialize_copy(other) ⇒ Object 



105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/bibtex/bibliography.rb', line 105

def initialize_copy(other)
  @options = other.options.dup
  @errors = other.errors.dup
  @data = []
  @strings = {}
  @entries = Hash.new { |h, k| h.fetch(k.to_s, nil) }

  other.each do |element|
    add element.dup
  end

  self
end

#inspect ⇒ Object 



382
383
384
 
# File 'lib/bibtex/bibliography.rb', line 382

def inspect
  "#<#{self.class} data=[#{length}]>"
end

#join(filter = '') ⇒ Object Also known as: join_strings 



276
277
278
279
 
# File 'lib/bibtex/bibliography.rb', line 276

def join(filter = '')
  q(filter, &:join)
  self
end

#names ⇒ Object

Returns a list of the names of all authors, editors and translators in the Bibliography.



252
253
254
 
# File 'lib/bibtex/bibliography.rb', line 252

def names
  map(&:names).flatten
end

#parse_months ⇒ Object 



161
162
163
164
 
# File 'lib/bibtex/bibliography.rb', line 161

def parse_months
  entries.each_value(&:parse_month)
  self
end

#parse_names ⇒ Object 



156
157
158
159
 
# File 'lib/bibtex/bibliography.rb', line 156

def parse_names
  entries.each_value(&:parse_names)
  self
end

#query(*arguments, &block) ⇒ Object Also known as: q

call-seq:

bib.query()          #=> returns all elements
bib.query('@book')   #=> returns all books
bib.query('@entry')  #=> returns all entries (books, articles etc.)
bib.query('@*')      #=> same as above
bib.query(:first, '@book, @article')
  #=> returns the first book or article or nil
bib.query('@book[year<=2011], @article)
  #=> returns all books published in 2011 or earlier and all articles
bib.query('@book, @article) { |o| o.year == '2011' }
  #=> returns all books and articles published in 2011
bib.query('@book[year=2011], @article[year=2011])
  #=> same as above without using a block

Returns objects in the Bibliography which match the given selector and, optionally, the conditions specified in the given block.

Queries offer syntactic sugar for common enumerator invocations:

>> bib.query(:all, '@book')
=> same as bib.select { |b| b.has_type?(:book) }
>> bib.query('@book')
=> same as above
>> bib.query(:first, '@book')
=> same as bib.detect { |b| b.has_type?(:book) }
>> bib.query(:none, '@book')
=> same as bib.reject { |b| b.has_type?(:book) }



465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'lib/bibtex/bibliography.rb', line 465

def query(*arguments, &block)
  case arguments.length
  when 0
    selector = :all
    q = nil
  when 1
    selector = :all
    q = arguments[0]
  when 2
    selector, q = arguments
  else
    raise ArgumentError, "wrong number of arguments (#{arguments.length} for 0..2)"
  end

  filter = block ? proc { |e| e.match?(q) && block.call(e) } :
    proc { |e| e.match?(q) }

  send(query_handler(selector), &filter)
end

#rename(*arguments, &block) ⇒ Object 



283
284
285
286
 
# File 'lib/bibtex/bibliography.rb', line 283

def rename(*arguments, &block)
  q('@entry') { |e| e.rename(*arguments, &block) }
  self
end

#replace(filter = '') ⇒ Object Also known as: replace_strings

Replaces all string symbols which are defined in the bibliography.

By default symbols in @string, @preamble and entries are replaced; this behaviour can be changed using the optional query parameter.

Note that strings are replaced in the order in which they occur in the bibliography.

call-seq: bib.replace #=> replaces all symbols bib.replace(‘@string, @preamble’) #=> replaces only symbols in @string and @preamble objects



269
270
271
272
 
# File 'lib/bibtex/bibliography.rb', line 269

def replace(filter = '')
  q(filter) { |e| e.replace(@strings.values) }
  self
end

#save(options = {}) ⇒ Object

Saves the bibliography to the current path.



132
133
134
 
# File 'lib/bibtex/bibliography.rb', line 132

def save(options = {})
  save_to(@path, options)
end

#save_to(path, options = {}) ⇒ Object

Saves the bibliography to a file at the given path. Returns the bibliography.



137
138
139
140
141
142
143
144
145
 
# File 'lib/bibtex/bibliography.rb', line 137

def save_to(path, options = {})
  options[:quotes] ||= %w[{ }]

  File.open(path, 'w:UTF-8') do |f|
    f.write(to_s(options))
  end

  self
end

#select_duplicates_by(*arguments, &block) ⇒ Object Also known as: duplicates 



505
506
507
508
509
510
511
512
513
514
515
516
 
# File 'lib/bibtex/bibliography.rb', line 505

def select_duplicates_by(*arguments, &block)
  arguments = %i[year title] if arguments.empty?

  group_by(*arguments) do |digest, entry|
    # 1.8 compatibility
    # digest = digest[0] if digest.is_a?(Array)

    digest.gsub(/\s+/, '').downcase
    digest = block.call(digest, entry) unless block.nil?
    digest
  end.values.select { |d| d.length > 1 }
end

#sort(*arguments, &block) ⇒ Object 



368
369
370
 
# File 'lib/bibtex/bibliography.rb', line 368

def sort(*arguments, &block)
  dup.sort!(*arguments, &block)
end

#sort!(*arguments, &block) ⇒ Object 



363
364
365
366
 
# File 'lib/bibtex/bibliography.rb', line 363

def sort!(*arguments, &block)
  data.sort!(*arguments, &block)
  self
end

#sort_by!(*arguments, &block) ⇒ Object 



372
373
374
375
 
# File 'lib/bibtex/bibliography.rb', line 372

def sort_by!(*arguments, &block)
  data.sort_by!(*arguments, &block)
  self
end

#to_a(options = {}) ⇒ Object 



386
387
388
 
# File 'lib/bibtex/bibliography.rb', line 386

def to_a(options = {})
  map { |o| o.to_hash(options) }
end

#to_citeproc(options = {}) ⇒ Object

Returns a CiteProc JSON representation of the bibliography. Only BibTeX enrties are exported.



406
407
408
 
# File 'lib/bibtex/bibliography.rb', line 406

def to_citeproc(options = {})
  q('@entry').map { |o| o.to_citeproc(options) }
end

#to_hash(options = {}) ⇒ Object

Returns a Ruby hash representation of the bibliography.



391
392
393
 
# File 'lib/bibtex/bibliography.rb', line 391

def to_hash(options = {})
  { bibliography: map { |o| o.to_hash(options) } }
end

#to_json(options = {}) ⇒ Object

Returns a JSON representation of the bibliography.



401
402
403
 
# File 'lib/bibtex/bibliography.rb', line 401

def to_json(options = {})
  ::JSON.dump(to_a(options))
end

#to_rdf(_options = {}) ⇒ Object

Returns an RDF::Graph representation of the bibliography. The graph can be serialized using any of the RDF serializer plugins.



429
430
431
432
433
434
435
 
# File 'lib/bibtex/bibliography.rb', line 429

def to_rdf(_options = {})
  if defined?(::RDF)
    RDFConverter.convert(self)
  else
    BibTeX.log.error 'Please `gem install rdf` for RDF support.'
  end
end

#to_s(options = {}) ⇒ Object

Returns a string representation of the bibliography.



378
379
380
 
# File 'lib/bibtex/bibliography.rb', line 378

def to_s(options = {})
  map { |o| o.to_s(options) }.join
end

#to_xml(options = {}) ⇒ Object

Returns a REXML::Document representation of the bibliography using the BibTeXML format.



412
413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'lib/bibtex/bibliography.rb', line 412

def to_xml(options = {})
  require 'rexml/document'

  xml =  REXML::Document.new
  xml << REXML::XMLDecl.new('1.0', 'UTF-8')

  root = REXML::Element.new('bibtex:file')
  root.add_namespace('bibtex', 'http://bibtexml.sf.net/')

  each { |e| root.add_element(e.to_xml(options)) if e.is_a?(Entry) }

  xml.add_element(root)
  xml
end

#to_yaml(options = {}) ⇒ Object

Returns a YAML representation of the bibliography.



396
397
398
 
# File 'lib/bibtex/bibliography.rb', line 396

def to_yaml(options = {})
  to_a(options).to_yaml
end

#unify(field, pattern, value = nil, &block) ⇒ Object

call-seq:

b.unify :publisher, /o'?reilly/i, "O'Reilly"
#=> Unifies the publisher name "O'Reilly" in the bibliography

Sets all fields matching the passed-in pattern to the supplied value. If a block is given, each matching entry will be passed to the block instead. Returns the bibliography.



342
343
344
345
346
347
348
349
350
351
 
# File 'lib/bibtex/bibliography.rb', line 342

def unify(field, pattern, value = nil, &block)
  pattern = Regexp.new(pattern) unless pattern.is_a?(Regexp)
  block = proc { |e| e[field] = value } unless block_given?

  each_entry do |entry|
    block.call(entry) if entry.field?(field) && entry[field].to_s =~ pattern
  end

  self
end

#uniq(*_arguments) ⇒ Object

Experimental! Returns a new Bibliography with all duplicates removed.



558
559
560
 
# File 'lib/bibtex/bibliography.rb', line 558

def uniq(*_arguments)
  dup.uniq!
end

#uniq!(*arguments, &block) ⇒ Object

call-seq:

bib.uniq!                                 -> bib
bib.uniq!(:title, :year)                  -> bib
bib.uniq! { |digest, entry| ... }         -> bib
bib.uniq!(:title) { |digest, entry| ... } -> bib

Removes duplicate entries from the Bibliography.

All arguments given will be used to calculate a digest for each entry. If a block is given, it will be be passed the computed digest as well as each entry; the block must then yield the final digest that will be used to compute duplicates.

This method will always retain the first entry and will discard subsequent duplicates on the basis of each entry’s digest.

See Also:



545
546
547
548
549
550
551
552
553
554
 
# File 'lib/bibtex/bibliography.rb', line 545

def uniq!(*arguments, &block)
  select_duplicates_by(*arguments, &block).each do |dupes|
    dupes.shift
    dupes.each do |dupe|
      remove dupe
    end
  end

  self
end

#valid? ⇒ Boolean

Returns true if the Bibliography contains no errors and only valid BibTeX objects (meta content is ignored).

Returns:

  • (Boolean) 


247
248
249
 
# File 'lib/bibtex/bibliography.rb', line 247

def valid?
  !errors? && entries.values.all?(&:valid?)
end