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.

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:



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

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.



35
36
37
 
# File 'lib/bibtex/bibliography.rb', line 35

def defaults
  @defaults
end

Instance Attribute Details

#data ⇒ Object (readonly)

Returns the value of attribute data.



86
87
88
 
# File 'lib/bibtex/bibliography.rb', line 86

def data
  @data
end

#entries ⇒ Object (readonly)

Returns the value of attribute entries.



86
87
88
 
# File 'lib/bibtex/bibliography.rb', line 86

def entries
  @entries
end

#errors ⇒ Object (readonly)

Returns the value of attribute errors.



86
87
88
 
# File 'lib/bibtex/bibliography.rb', line 86

def errors
  @errors
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



86
87
88
 
# File 'lib/bibtex/bibliography.rb', line 86

def options
  @options
end

#path ⇒ Object

Returns the value of attribute path.



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

def path
  @path
end

#strings ⇒ Object (readonly)

Returns the value of attribute strings.



86
87
88
 
# File 'lib/bibtex/bibliography.rb', line 86

def strings
  @strings
end

Class Method Details

.attr_by_type(*arguments) ⇒ Object

Defines a new accessor that selects elements by type.



76
77
78
79
80
81
 
# File 'lib/bibtex/bibliography.rb', line 76

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)



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

def open(path, options = {})
  b = parse(Kernel.open(path, 'r:UTF-8').read, 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.



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

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 



508
509
510
 
# File 'lib/bibtex/bibliography.rb', line 508

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
239
240
 
# 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)

  case
  when arguments[0].is_a?(Numeric) || arguments[0].is_a?(Range)
    data[*arguments]
  when arguments.length == 1
    case
    when arguments[0].nil?
      nil
    when arguments[0].respond_to?(:empty?) && arguments[0].empty?
      nil
    when arguments[0].is_a?(Symbol)
      entries[arguments[0]]
    when 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.



115
116
117
118
119
120
 
# File 'lib/bibtex/bibliography.rb', line 115

def add(*arguments)
  Element.parse(arguments.flatten).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!



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

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.



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

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

#duplicates? ⇒ Boolean

Returns:

  • (Boolean) 


522
523
524
 
# File 'lib/bibtex/bibliography.rb', line 522

def duplicates?
  !select_duplicates_by?.empty?
end

#each ⇒ Object 



143
144
145
146
147
148
149
150
 
# File 'lib/bibtex/bibliography.rb', line 143

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

#each_entry ⇒ Object 



494
495
496
497
498
499
500
 
# File 'lib/bibtex/bibliography.rb', line 494

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

#errors? ⇒ Boolean

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

Returns:

  • (Boolean) 


244
245
246
 
# File 'lib/bibtex/bibliography.rb', line 244

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.



297
298
299
300
301
302
303
304
305
 
# File 'lib/bibtex/bibliography.rb', line 297

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



315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/bibtex/bibliography.rb', line 315

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

    if group[:prototype].nil? || group[:prototype].first.to_s.length < name.first.to_s.length
      group[:prototype] = name
    end
  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 



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

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

#group_by(*arguments, &block) ⇒ Object 



365
366
367
368
369
370
371
372
373
 
# File 'lib/bibtex/bibliography.rb', line 365

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
 
# 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) }
  add(other.data)
end

#inspect ⇒ Object 



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

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

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



279
280
281
282
 
# File 'lib/bibtex/bibliography.rb', line 279

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.



255
256
257
 
# File 'lib/bibtex/bibliography.rb', line 255

def names
  map(&:names).flatten
end

#parse_months ⇒ Object 



158
159
160
161
 
# File 'lib/bibtex/bibliography.rb', line 158

def parse_months
  entries.each_value { |e| e.parse_month }
  self
end

#parse_names ⇒ Object 



153
154
155
156
 
# File 'lib/bibtex/bibliography.rb', line 153

def parse_names
  entries.each_value { |e| e.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) }



474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
 
# File 'lib/bibtex/bibliography.rb', line 474

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

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

  send(query_handler(selector), &filter)
end

#rename(*arguments, &block) ⇒ Object 



286
287
288
289
 
# File 'lib/bibtex/bibliography.rb', line 286

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



272
273
274
275
 
# File 'lib/bibtex/bibliography.rb', line 272

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

#save(options = {}) ⇒ Object

Saves the bibliography to the current path.



127
128
129
 
# File 'lib/bibtex/bibliography.rb', line 127

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.



132
133
134
135
136
137
138
139
140
 
# File 'lib/bibtex/bibliography.rb', line 132

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) ⇒ Object Also known as: duplicates 



512
513
514
515
516
517
518
 
# File 'lib/bibtex/bibliography.rb', line 512

def select_duplicates_by(*arguments)
  arguments = [:year, :title] if arguments.empty?

  group_by(*arguments) { |digest|
    digest.gsub(/\s+/, '').downcase
  }.values.select { |d| d.length > 1 }
end

#sort(*arguments, &block) ⇒ Object 



375
376
377
378
 
# File 'lib/bibtex/bibliography.rb', line 375

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

#to_a(options = {}) ⇒ Object 



389
390
391
 
# File 'lib/bibtex/bibliography.rb', line 389

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.



409
410
411
 
# File 'lib/bibtex/bibliography.rb', line 409

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.



394
395
396
 
# File 'lib/bibtex/bibliography.rb', line 394

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

#to_json(options = {}) ⇒ Object

Returns a JSON representation of the bibliography.



404
405
406
 
# File 'lib/bibtex/bibliography.rb', line 404

def to_json(options = {})
  MultiJson.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.



432
433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/bibtex/bibliography.rb', line 432

def to_rdf(options = {})
  require 'rdf'

  graph = RDF::Graph.new

  q('@entry').each do |entry|
    graph << entry.to_rdf(options)
  end

  graph
rescue LoadError
  BibTeX.log.error "Please gem install rdf for RDF support."
end

#to_s(options = {}) ⇒ Object

Returns a string representation of the bibliography.



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

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.



415
416
417
418
419
420
421
422
423
424
425
426
427
428
 
# File 'lib/bibtex/bibliography.rb', line 415

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.



399
400
401
 
# File 'lib/bibtex/bibliography.rb', line 399

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

#unify(field, pattern, value = nil) ⇒ 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.



347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
 
# File 'lib/bibtex/bibliography.rb', line 347

def unify(field, pattern, value = nil)
  pattern = Regexp.new(pattern) unless pattern.is_a?(Regexp)

  block = if block_given?
    Proc.new
  else
    Proc.new { |e| e[field] = value }
  end

  each_entry do |entry|
    if entry.field?(field) && entry[field].to_s =~ pattern
      block.call(entry)
    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) 


250
251
252
 
# File 'lib/bibtex/bibliography.rb', line 250

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