Class: RCite::Processor

Inherits:
Object
  • Object
show all
Defined in:
lib/rcite/processor.rb

Overview

The Processor class is responsible for chaining the two steps involved in creating a citation or bibliography together:

  1. Load a BibTeX file with bibliographic information about all the texts.
  2. Load a style that defines how to construct citations and bibliography entries from the former.

Moreover, it provides shortcuts for citing and bibliography entry creation by mapping Style#cite and Style#bib.

Constant Summary

@@style_counter = 
1

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Instance Attribute Details

- (BibTeX::Bibliography) bibliography

A BibTeX::Bibliography with bibliographic data loaded from a BibTeX file. Can be nil if no data file has been loaded yet.

Returns:

  • (BibTeX::Bibliography) —

    the current bibliography



38
39
40
 
# File 'lib/rcite/processor.rb', line 38

def bibliography
  @bibliography
end

- (RCite::Style?) style

The style that is used to turn bibliographic data gathered from a BibTeX file to actual citations/bibliographic entries. Should usually be a subclass of Style. Can be nil if no style has been loaded yet.

Returns:



25
26
27
 
# File 'lib/rcite/processor.rb', line 25

def style
  @style
end

- (Class?) style_class (readonly)

Returns the class that the current #style is an instance of. The classname changes with each call of #load_style. Can be nil if no style has been loaded yet.

Returns:

  • (Class, nil) —

    the style's class.



32
33
34
 
# File 'lib/rcite/processor.rb', line 32

def style_class
  @style_class
end

Instance Method Details

- (String) bib(id, fields = {})

Generates a bibliography entry for the text with given id. This method searches the #bibliography for a text where key == id and -- if it happens to find one -- returns @style.bib(text, fields).

Parameters:

  • id (Symbol) —

    The unique identifier (key) set in the BibTeX file.

  • fields (Hash) (defaults to: {}) —

    A hash where each key represents a BibTeX field and each value represents its value. This can be used to set fields 'on the fly', most notably the thepage field that indicates which page the user wants to cite.

Returns:

  • (String) —

    A bibliography entry for the given text.

Raises:

  • (ArgumentError) —

    if #style or #bibliography are nil, or if there is no text with given id in bib.



134
135
136
137
138
139
140
141
142
143
 
# File 'lib/rcite/processor.rb', line 134

def bib(id, fields = {})
  check_attrs

  text = find_text(id)
  if text
    @style.bib(text, fields)
  else
    raise ArgumentError.new "No text with id #{id} found."
  end
end

- (String) cite(id, fields = {})

Generates a citation for the text with given id. This method searches the #bibliography for a text where :key == id and -- if it happens to find one -- returns @style.cite(text, additional_fields).

Parameters:

  • id (Symbol) —

    The unique identifier (key) set in the BibTeX file.

  • fields (Hash) (defaults to: {}) —

    A hash where each key represents a BibTeX field and each value represents its value. This can be used to set fields 'on the fly', most notably the thepage field that indicates which page the user wants to cite.

Returns:

  • (String) —

    A citation for the given text.

Raises:

  • (ArgumentError) —

    if #style or #bibliography are nil, or if there is no text with given id in bib.



112
113
114
115
116
117
118
119
120
121
 
# File 'lib/rcite/processor.rb', line 112

def cite(id, fields = {})
  check_attrs

  text = find_text(id)
  if text
    @style.cite(text, fields)
  else
    raise ArgumentError, "No text with id #{id} found."
  end
end

- (BibTeX::Bibliography) load_data(file)

Loads the specified BibTeX file and sets #bibliography accordingly. This method is merely a wrapper for BibTeX::Bibliography#open.

Parameters:

  • file (String) —

    The BibTeX file that should be loaded.

Returns:

  • (BibTeX::Bibliography) —

    The bibliography that has been loaded from the style.

Raises:

  • all errors that BibTeX::Bibliography raises.



92
93
94
 
# File 'lib/rcite/processor.rb', line 92

def load_data(file)
  @bibliography = BibTeX::Bibliography.open(file)
end

- (void) load_style(file)

This method returns an undefined value.

Loads an RCite style.

Styles simply consist of Ruby code (mainly method definitions) that are executed in the context of a newly created class RCite::StyleClass that inherits from Style. Think of the code in the style file as being surrounded by

class RCite::StyleClass < Style
  # code from the style file
end

The style's StyleClass is different for each call of this method. Use #style_class to get the current Class object.

This method also sets #style to a new instance of the loaded class.

Parameters:

  • file (String) —

    Relative or absolute path of the file that should be loaded.

Raises:

  • (LoadError) —

    if the specified file cannot be loaded by the Kernel method load.



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/rcite/processor.rb', line 67

def load_style(file)
  style = Class.new(RCite::Style)
  raise LoadError, "Could not read file: #{file}" unless
    File.exists?(file) && File.readable?(file)

  style.module_eval(File.read(File.absolute_path(file)))

  @@style_counter += 1
  classname = "Style#{@@style_counter}".to_sym
  RCite.const_set(classname, style)

  @style_class = style
  @style = @style_class.new
  @style.preamble if @style.respond_to?(:preamble)
end