Class: CiteProc::Item

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

Overview

Items are similar to a Ruby Hash but pose a number of constraints on their contents: keys are always (implicitly converted to) symbols and values are strictly Variables. When Items are constructed from (or merged with) JSON objects or Hashes Variable instances are automatically created by passing the variable’s key as type to Variable.create; this will create the expected Variable type for all fields defined in CSL (for example, the ‘issued’ field will become a Date object; unknown types will be converted to simple Variable instances, which should be fine for numeric or string values but may cause problems for more complex types.

Every Item provides accessor methods for all known field names; unknown fields can still be accessed using array accessor syntax.

i = Item.new(:edition => 3, :unknown_field => 42)
i.edition
#-> #<CiteProc::Number "3">

i[:unknown_field]
#-> #<CiteProc::Variable "42">

Items can be converted to the CiteProc JSON format via Attributes#to_citeproc and Attributes#to_json.

Class Attribute Summary collapse

Instance Method Summary collapse

Methods included from Attributes

#attribute?, #eql?, #hash, #merge, #reverse_merge, #to_citeproc, #to_hash, #to_json, #write_attribute

Constructor Details

#initialize(attributes = nil) {|_self| ... } ⇒ Item

Returns a new instance of Item.

Yields:

  • (_self)

Yield Parameters:



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

def initialize(attributes = nil)
  merge(attributes)
  yield self if block_given?
end

Class Attribute Details

.bibtex_types ⇒ Object (readonly)

Returns the value of attribute bibtex_types.



54
55
56
 
# File 'lib/citeproc/item.rb', line 54

def bibtex_types
  @bibtex_types
end

.types ⇒ Object (readonly)

Returns the value of attribute types.



54
55
56
 
# File 'lib/citeproc/item.rb', line 54

def types
  @types
end

Instance Method Details

#<=>(other) ⇒ Object 



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

def <=>(other)
  return nil unless other.is_a?(Attributes)
  eql?(other) ? 0 : length <=> other.length
end

#==(other) ⇒ Object 



219
220
221
222
 
# File 'lib/citeproc/item.rb', line 219

def ==(other)
  return false unless other.is_a?(Item)
  id == other.id
end

#cite(number = nil) ⇒ CitationItem

Returns a CitationItem with a copy of this item attached as data.

If given, number is added as the item’s citation-number variable.

Parameters:

  • number (Fixnum) (defaults to: nil) —

    the item’s citation-number

Returns:



95
96
97
98
99
100
 
# File 'lib/citeproc/item.rb', line 95

def cite(number = nil)
  CitationItem.new :id => id do |c|
    c.data = dup
    c.data[:'citation-number'] = number unless number.nil?
  end
end

#each {|field, value| ... } ⇒ self, Enumerator Also known as: each_pair

Calls a block once for each field in the item, passing the field’s name-value pair as parameters.

If not block is given, an enumerator is returned instead.

item.each { |name, value| block }
#-> item

item.each
#-> an enumerator

Yield Parameters:

  • field (Symbol) —

    the field name

  • value (Variable) —

    the value

Returns:

  • (self, Enumerator) —

    the item or an enumerator if no block is given



168
169
170
171
172
173
174
175
 
# File 'lib/citeproc/item.rb', line 168

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

#each_value {|value| ... } ⇒ self, Enumerator

Calls a block once for each field in the item, passing the field’s value as parameters.

If not block is given, an enumerator is returned instead.

item.each_value { |value| block }
#-> item

item.each_value
#-> an enumerator

Yield Parameters:

Returns:

  • (self, Enumerator) —

    the item or an enumerator if no block is given



191
192
193
194
195
196
197
198
 
# File 'lib/citeproc/item.rb', line 191

def each_value(&block)
  if block_given?
    attributes.each_value(&block)
    self
  else
    enum_for :each_value
  end
end

#english? ⇒ Boolean Also known as: en?

An Item is interpreted as being English unless it has an attribute ‘language’ set to something other than ‘en’.

Returns:

  • (Boolean) —

    whether or not this is an English Item



148
149
150
151
 
# File 'lib/citeproc/item.rb', line 148

def english?
  lang = language
  lang.nil? || lang == 'en'
end

#initialize_copy(other) ⇒ Object 



82
83
84
 
# File 'lib/citeproc/item.rb', line 82

def initialize_copy(other)
  @attributes = other.attributes.deep_copy
end

#inspect ⇒ String

Returns a string containing a human-readable representation of the item.

Returns:

  • (String) —

    a string containing a human-readable representation of the item



264
265
266
 
# File 'lib/citeproc/item.rb', line 264

def inspect
  "#<CiteProc::Item id=#{id.to_s.inspect} attributes={#{attributes.length}}>"
end

#language ⇒ Object 



140
141
142
 
# File 'lib/citeproc/item.rb', line 140

def language
  unobservable_read_attribute(:language)
end

#observable_read_attribute(key) ⇒ Object Also known as: read_attribute 



102
103
104
105
106
107
108
109
 
# File 'lib/citeproc/item.rb', line 102

def observable_read_attribute(key)
  value = original_read_attribute(key)
  return if suppressed?(key)
  value
ensure
  changed
  notify_observers :read, key, value
end

#simulate_read_attribute(key, value) ⇒ Object 



111
112
113
114
 
# File 'lib/citeproc/item.rb', line 111

def simulate_read_attribute(key, value)
  changed
  notify_observers :read, key, value
end

#suppress!(*keys) ⇒ Object 



204
205
206
207
208
209
210
211
212
213
 
# File 'lib/citeproc/item.rb', line 204

def suppress!(*keys)
  keys.flatten.each do |key|
    suppressed << key.to_s
  end

  suppressed.sort!
  suppressed.uniq!

  self
end

#suppressed ⇒ Object 



215
216
217
 
# File 'lib/citeproc/item.rb', line 215

def suppressed
  @suppressed ||= []
end

#suppressed?(key) ⇒ Boolean

Returns:

  • (Boolean) 


200
201
202
 
# File 'lib/citeproc/item.rb', line 200

def suppressed?(key)
  suppressed.include?(key.to_s)
end

#to_bibtex ⇒ Object

Returns a corresponding BibTeX::Entry if the bibtex-ruby gem is installed; otherwise returns a BibTeX string.



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/citeproc/item.rb', line 231

def to_bibtex
  # hash = to_hash
  #
  # hash[:type] = Item.bibtex_types[hash[:type]]
  #
  # if hash.has_key?(:issued)
  #   date = hash.delete(:issued)
  #   hash[:year] = date.year
  #   hash[:month] = date.month
  # end
  #
  # Variable.fields[:date].each do |field|
  #   hash[field] = hash[field].to_s if hash.has_key?(field)
  # end
  #
  # Variable.fields[:names].each do |field|
  #   hash[field] = hash[field].to_bibtex
  # end

  raise 'not implemented yet'
end

#to_sym ⇒ Symbol?

Returns the item’s id.

Returns:

  • (Symbol, nil) —

    the item’s id



254
255
256
257
258
259
260
 
# File 'lib/citeproc/item.rb', line 254

def to_sym
  if id?
    id.to_s.intern
  else
    nil
  end
end

#variable(name, options = {}) ⇒ Variable?

Returns the matching variable.

Parameters:

  • name (Symbol) —

    the name of the variable

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :form (:short) — default: nil —

    when given, the variable’s short form will be returned if available.

Returns:

  • (Variable, nil) —

    the matching variable



131
132
133
134
135
136
137
138
 
# File 'lib/citeproc/item.rb', line 131

def variable(name, options = {})
  if options.key?(:form) && options[:form].to_sym == :short
    var = read_attribute "#{name}-short"
    return var unless var.nil?
  end

  read_attribute name
end