bibtex-ruby 1.3.12 → 2.0.0pre1

data/lib/bibtex/elements.rb

@@ -28,13 +28,22 @@ module BibTeX
 		attr_reader :bibliography
 		
 		# Returns an array of BibTeX elements.
-    def self.parse(string, options = {})
-      elements = BibTeX::Parser.new(options).parse(string).data
-      elements.each do |e|
-        e.parse_names unless !e.respond_to?(:parse_names) || options[:parse_names] == false
-        e.parse_month unless !e.respond_to?(:parse_month) || options[:parse_months] == false
-      end
-      elements
+    def self.parse(input, options = {})
+			case input
+			when Element
+				[input]
+			when Hash
+				[Entry.new(input)]
+			when Array
+				input.inject([]) { |s,a| s.concat(parse(a, options)) }
+			when ::String
+	      Parser.new(options).parse(input).data.each do |e|
+	        e.parse_names unless !e.respond_to?(:parse_names) || options[:parse_names] == false
+	        e.parse_month unless !e.respond_to?(:parse_month) || options[:parse_months] == false
+	      end
+			else
+				raise BibTeXError, "failed to parse Element from #{input.inspect}"
+			end
     end
     
 		# Returns a string containing the object's content.
@@ -47,24 +56,26 @@ module BibTeX
     def join; self; end
     
     # Returns the element's id.
-    def id; @id ||= object_id.to_s.intern; end
+    def id; @id ||= object_id.to_s; end
     
     # Returns the BibTeX type (if applicable) or the normalized class name.
     def type
       self.class.name.split(/::/).last.gsub(/([[:lower:]])([[:upper:]])/) { "#{$1}_#{$2}" }.downcase.intern
     end
   
+		# Returns a list of names for that Element. All Elements except Entries return an empty list.
+		def names
+			[]
+		end
+		
     def has_type?(type)
       self.type == type.intern || defined?(type) == 'constant' && is_a?(type)
     end
     
     [:entry, :book, :article, :collection, :string, :preamble, :comment]. each do |type|
-      method_id = "#{type}?"
-      unless method_defined?(method_id)
-        define_method(method_id) { has_type?(type) }
-        alias_method("is_#{method_id}", method_id)
-      end
-    end
+			method_id = "#{type}?"
+			define_method(method_id) { has_type?(type) } unless method_defined?(method_id)
+		end
     
     # Returns true if the element matches the given query.
     def matches?(query)
@@ -72,7 +83,7 @@ module BibTeX
       
       case query
       when Symbol
-        query == id
+        query.to_s == id.to_s
       when Element
         query == self
       when Regexp
@@ -84,7 +95,7 @@ module BibTeX
       when /^\/(.+)\/$/
         to_s.match(Regexp.new($1))
       else
-        id == query.to_sym
+        id.to_s == query
       end      
     end
     
@@ -95,7 +106,7 @@ module BibTeX
     def meets?(*conditions)
       conditions.flatten.all? do |condition|
         property, value = condition.split(/\s*=\s*/)
-        property.nil? || send(property).to_s == value
+        property.nil? || (respond_to?(property) && send(property).to_s == value)
       end
     end
     
@@ -105,7 +116,7 @@ module BibTeX
 		
 		def to_hash(options = {})
 		  { type => content }
-	  end
+		end
 	  
 	  def to_yaml(options = {})
 	    require 'yaml'
@@ -113,8 +124,7 @@ module BibTeX
 	  end
 	  
 	  def to_json(options = {})
-	    require 'json'
-	    to_hash.to_json
+	    MultiJson.encode(to_hash(options))
 	  end
 	  
 	  def to_xml(options = {})
@@ -126,6 +136,7 @@ module BibTeX
 
 		# Called when the element was added to a bibliography.
 		def added_to_bibliography(bibliography)
+			# raise BibTeXError, "failed to add element to Bibliography: already registered with another Bibliography" unless @bibliography.nil?
 			@bibliography = bibliography
 			self
 		end
@@ -141,6 +152,10 @@ module BibTeX
 		  [type, to_s] <=> [other.type, other.to_s]
 		end
 		
+		# Returns the Element as a nicely formatted string.
+		def inspect
+			"#<#{self.class} #{content.gsub(/\n/, ' ')}>"
+		end
 	end
 
  
@@ -169,11 +184,11 @@ module BibTeX
 		def key=(key)
 		  raise(ArgumentError, "keys must be convertible to Symbol; was: #{type.class.name}.") unless type.respond_to?(:to_sym)
 			
-      unless @bibliography.nil?
-  			@bibliography.strings.delete(@key)
-  			@bibliography.strings[key.to_sym] = self
-  		end
-  		
+			unless bibliography.nil?
+				bibliography.strings.delete(@key)
+				bibliography.strings[key.to_sym] = self
+			end
+
 			@key = key.to_sym
 		end
 
@@ -214,11 +229,15 @@ module BibTeX
 		def to_xml(options = {})
 		  require 'rexml/document'
 	    
-		  xml = REXML::Element.new(:string)
-		  key = REXML::Element.new(:key)
-		  val = REXML::Element.new(:value)
-		  key.text = @key.to_s
-		  val.text = @value.to_s(:quotes => '"')
+			xml = REXML::Element.new(:string)
+			
+			k, v = REXML::Element.new(:key), REXML::Element.new(:value)
+			k.text = key.to_s
+			v.text = value.to_s(:quotes => '"')
+		
+			xml.add_elements(k)
+			xml.add_elements(v)
+			
 		  xml
 		end
 	end

data/lib/bibtex/entry.rb

@@ -26,7 +26,7 @@ module BibTeX
 	  extend Forwardable	  
 	  include Enumerable
 
-		# Hash containing the required fields of the standard entry types
+		# Defines the required fields of the standard entry types
 		REQUIRED_FIELDS = Hash.new([]).merge({
 			:article       => [:author,:title,:journal,:year],
 			:book          => [[:author,:editor],:title,:publisher,:year],
@@ -44,6 +44,13 @@ module BibTeX
 			:unpublished   => [:author,:title,:note]
 		}).freeze
 
+		# Defines the default fallbacks for values defined in cross-references
+		FIELD_ALIASES = {
+			:booktitle => :title,
+			# :editor => :author
+		}.freeze
+		
+		
     NAME_FIELDS = [:author,:editor,:translator].freeze
     DATE_FIELDS = [:year,:month].freeze
     
@@ -102,13 +109,14 @@ module BibTeX
     }.map(&:intern)]).freeze
 
 	  
-		attr_reader :fields, :type		
+		attr_reader :fields, :type
+		
     def_delegators :@fields, :empty?, :each, :each_pair
 
 		# Creates a new instance. If a hash is given, the entry is populated accordingly.
 		def initialize(attributes = {})
 			@fields = {}
-		  
+		
 		  self.type = attributes.delete(:type) if attributes.has_key?(:type)
 		  self.key = attributes.delete(:key) if attributes.has_key?(:key)
 			
@@ -125,17 +133,29 @@ module BibTeX
       
       add(other.fields)
     end
-    
-		# Sets the key of the entry
+  
+		# Returns the Entry's field name aliases.
+		def aliases
+			@aliases ||= FIELD_ALIASES.dup
+		end
+		
+		# Sets the Entry's key. If the Entry is currently registered with a
+		# Bibliography, re-registers the Entry with the new key; note that this
+		# may change the key value if another Entry is already regsitered with
+		# the same key.
+		#
+		# Returns the new key.
 		def key=(key)
-			raise(ArgumentError, "keys must be convertible to Symbol; was: #{type.class.name}.") unless type.respond_to?(:to_sym)
-
-      unless @bibliography.nil?
-  			@bibliography.entries.delete(@key)
-  			@bibliography.entries[key] = self
+			key = key.to_s
+			
+      if registered?
+  			bibliography.entries.delete(@key)
+  			key = register(key)
       end
 
-			@key = key.to_sym
+			@key = key
+		rescue => e
+			raise BibTeXError, "failed to set key to #{key.inspect}: #{e.message}"
 		end
 		
 		def key
@@ -148,7 +168,7 @@ module BibTeX
 		# TODO we should be more lenient: allow strings as key or don't check at all
 		# Sets the type of the entry.
 		def type=(type)
-			raise(ArgumentError, "types must be convertible to Symbol; was: #{type.class.name}.") unless type.respond_to?(:to_sym)
+			# raise(ArgumentError, "types must be convertible to Symbol; was: #{type.class.name}.") unless type.respond_to?(:to_sym)
 			@type = type.to_sym
 		end
 		
@@ -156,25 +176,92 @@ module BibTeX
 			type.to_s.match(/^entry$/i) || @type == type.to_sym || super
 		end
     
-    def has_field?(field)
-      @fields.has_key?(field)
+    def has_field?(name)
+			name.respond_to?(:to_sym) ? fields.has_key?(name.to_sym) : false
     end
+
+		def inherits?(name)
+			!has_field(name) && has_parent? && parent.provides?(name)
+		end
+		
+		# Returns true if the Entry has a field (or alias) for the passed-in name.
+		def provides?(name)
+			return nil unless name.respond_to?(:to_sym)
+			has_field?(name) || has_field?(aliases[name.to_sym])
+		end
     
+		# Returns the field value referenced by the passed-in name.
+		# For example, this will return the 'title' value for 'booktitle' if a
+		# corresponding alias is defined.
+		def provide(name)
+			return nil unless name.respond_to?(:to_sym)
+			name = name.to_sym			
+			fields[name] || fields[aliases[name]]
+		end
+		
+		# If the Entry has a cross-reference, copies all referenced all inherited
+		# values from the parent.
+		#
+		# Returns the Entry.
+		def save_inherited_fields
+			inherited_fields.each do |name|
+				fields[name] = parent.provide(name)
+			end
+			
+			self
+		end
+		
+		# Returns a sorted list of the Entry's field names. If a +filter+ is passed
+		# as argument, returns all field names that are also defined by the filter.
+		# If the +filter+ is empty, returns all field names.
+		#
+		# If the second optional argument is true (default) and the Entry contains
+		# a cross-reference, the list will include all inherited fields.
+		def field_names(filter = [], include_inherited = true)
+			names = fields.keys
+			
+			if include_inherited && has_parent?
+				names.concat(inherited_fields)
+			end
+			
+			unless filter.empty?
+				names = names & filter.map(&:to_sym)
+			end
+			
+			names.sort!
+			names
+		end
+
+		# Returns a sorted list of all field names referenced by this Entry's cross-reference.
+		def inherited_fields
+			return [] unless has_parent?
+			
+			names = parent.fields.keys - fields.keys
+			names.concat(parent.aliases.reject { |k,v| !parent.has_field?(v) }.keys)
+			names.sort!
+			
+			names
+		end
+		
+		
 		def method_missing(name, *args, &block)
 			case
-			when @fields.has_key?(name)
-				@fields[name]
+			when fields.has_key?(name)
+				fields[name]
 			when name.to_s =~ /^(.+)=$/
 				send(:add, $1.to_sym, args[0]) 		  
 			when name =~ /^(?:convert|from)_([a-z]+)(!)?$/
 				$2 ? convert!($1, &block) : convert($1, &block)
+			when has_parent? && parent.provides?(name)
+				parent.provide(name)
 			else
 				super
 			end
 		end
 
 		def respond_to?(method)
-		  @fields.has_key?(method.to_sym) || method.to_s.match(/=$/) || method =~ /^(?:convert|from)_([a-z]+)(!)?$/ || super
+		  provides?(method.to_sym) || method.to_s.match(/=$/) ||
+				method =~ /^(?:convert|from)_([a-z]+)(!)?$/ || (has_parent? && parent.respond_to(method)) || super
 		end
 		
 		# Returns a copy of the Entry with all the field names renamed.
@@ -186,20 +273,28 @@ module BibTeX
 		# exists.
 		def rename!(*arguments)
 			Hash[*arguments.flatten].each_pair do |from,to|
-				if @fields.has_key?(from) && !@fields.has_key?(to)
-					@fields[to] = @fields[from]
-					@fields.delete(from)
+				if fields.has_key?(from) && !fields.has_key?(to)
+					fields[to] = fields[from]
+					fields.delete(from)
 				end
 			end
 			self
 		end
 
-		alias :rename_fields :rename
-		alias :rename_fields! :rename!
+		alias rename_fields rename
+		alias rename_fields! rename!
 		
-		# Returns the value of the field with the given name.
+		# Returns the value of the field with the given name. If the value is not
+		# defined and the entry has cross-reference, returns the cross-referenced
+		# value instead.
 		def [](name)
-			@fields[name.to_sym]
+			fields[name.to_sym] || parent && parent.provide(name)
+		end
+		
+		alias get []
+		
+		def fetch(name, default = nil)
+			get(name) || block_given? ? yield(name) : default
 		end
 
 		# Adds a new field (name-value pair) to the entry.
@@ -216,11 +311,11 @@ module BibTeX
 		# add(:author, "Edgar A. Poe", :title, "The Raven")
 		# add([:author, "Edgar A. Poe", :title, "The Raven"])
 		# add(:author => "Edgar A. Poe", :title => "The Raven")
-		#
 		def add(*arguments)
 		  Hash[*arguments.flatten].each_pair do |name, value|
-			  @fields[name.to_sym] = Value.new(value)
+			  fields[name.to_sym] = Value.new(value)
 			end
+			
 			self
 		end
 		
@@ -229,34 +324,64 @@ module BibTeX
 		# Removes the field with a given name from the entry.
 		# Returns the value of the deleted field; nil if the field was not set.
 		def delete(name)
-			@fields.delete(name.to_sym)
+			fields.delete(name.to_sym)
 		end
 
 		# Returns false if the entry is one of the standard entry types and does not have
 		# definitions of all the required fields for that type.
 		def valid?
 			REQUIRED_FIELDS[@type].all? do |f|
-				f.is_a?(Array) ? !(f & @fields.keys).empty? : !@fields[f].nil?
+				f.is_a?(Array) ? !(f & fields.keys).empty? : !fields[f].nil?
 			end
 		end
 
+		def generate_hash(filter = [])
+			Digest::MD5.hexdigest(field_names(filter).map { |k| [k, fields[k]] }.flatten.join)
+		end
+		
 		# Called when the element was added to a bibliography.
 		def added_to_bibliography(bibliography)
 			super
-			bibliography.entries[key] = self
-			parse_names if bibliography.options[:parse_names]
-			parse_months if bibliography.options[:parse_months]
-			convert(bibliography.options[:filter]) if bibliography.options[:filter]
+
+			@key = register(key)
+			
+			[:parse_names, :parse_months].each do |parser|
+				send(parser) if bibliography.options[parser]
+			end
+			
+			if bibliography.options.has_key?(:filter)
+				convert!(bibliography.options[:filter])
+			end
+			
 			self
 		end
-				
+
 		# Called when the element was removed from a bibliography.
 		def removed_from_bibliography(bibliography)
 			super
-			bibliography.entries[key] = nil
+			bibliography.entries.delete(key)
 			self
 		end
 
+		# Returns true if the Entry is currently registered with the associated Bibliography.
+		def registered?
+			!!(bibliography && bibliography.entries[key].equal?(self))
+		end
+		
+		# Registers this Entry in the associated Bibliographies entries hash.
+		# This method may change the Entry's key, if another entry is already
+		# registered with the current key.
+		#
+		# Returns the key or nil if the Entry is not associated with a Bibliography.
+		def register(key)
+			return nil if bibliography.nil?
+			
+			k = key.dup
+			k.succ! while bibliography.has_key?(k)
+			bibliography.entries[k] = self
+			k
+		end
+		
 		def replace(*arguments)
 		  arguments = bibliography.q('@string') if arguments.empty?
 			@fields.values.each { |v| v.replace(*arguments) }
@@ -269,11 +394,11 @@ module BibTeX
     end
 
     def month=(month)
-      @fields[:month] = MONTHS_FILTER[month]
+      fields[:month] = MONTHS_FILTER[month]
     end
     
     def parse_month
-      @fields[:month] = MONTHS_FILTER[@fields[:month]] if @fields.has_key?(:month)
+      fields[:month] = MONTHS_FILTER[fields[:month]] if fields.has_key?(:month)
       self
     end
     
@@ -284,18 +409,65 @@ module BibTeX
     def parse_names
       strings = bibliography ? bibliography.strings.values : []
       NAME_FIELDS.each do |key|
-        if name = @fields[key]
-          name.replace(strings).join
-          name = name.to_name
-          @fields[key] = name
+        if name = fields[key]
+          name = name.dup.replace(strings).join.to_name
+          fields[key] = name unless name.nil?
         end
       end
       self
     end
     
+		# Returns a list of all names (authors, editors, translators).
+		def names
+			NAME_FIELDS.map { |k| has_field?(k) ? @fields[k].tokens : nil }.flatten.compact
+		end
+			
+		
+		# Returns true if the Entry has a valid cross-reference in the Bibliography.
+		def has_parent?
+			!parent.nil?
+		end
+
+		alias has_cross_reference? has_parent?		
+
+		# Returns true if the Entry cross-references an Entry which is not
+		# registered in the current Bibliography.
+		def parent_missing?
+			has_field?(:crossref) && !has_parent?
+		end
+	
+		alias cross_reference_missing? parent_missing?
+		
+		# Returns the cross-referenced Entry from the Bibliography or nil if this
+		# Entry does define a cross-reference.
+		def parent
+			bibliography && bibliography[fields[:crossref]]
+		end
+		
+		alias cross_reference parent
+
+
+		# Returns true if the entry is cross-referenced by another entry in the
+		# Bibliography.
+		def has_children?
+			!children.empty?
+		end
+		
+		alias cross_referenced? has_children?
+		
+		# Returns a list of all entries in the Bibliography containing a
+		# cross-reference to this entry or [] if there are no references to this
+		# entry.
+		def children
+			(bibliography && bibliography.q("@entry[crossref=#{key}]")) || []
+		end
+
+		alias cross_referenced_by children
+		
+		
 		# Returns a string of all the entry's fields.
 		def content(options = {})
-			@fields.map { |k,v| "#{k} = #{ @fields[k].to_s(options) }" }.join(",\n")
+			fields.map { |k,v| "#{k} = #{ fields[k].to_s(options) }" }.join(",\n")
 		end
 
 		# Returns a string representation of the entry.
@@ -332,27 +504,37 @@ module BibTeX
 		def to_xml(options = {})
 		  require 'rexml/document'
 	    
-  		xml = REXML::Element.new(type)
-  		xml.attributes['key'] = key
-      @fields.each do |k,v|
-        e = REXML::Element.new(k.to_s)
-        e.text = v.to_s(options)
-        xml.add_element(e)
+			xml = REXML::Element.new('bibtex:entry')
+			xml.attributes['id'] = key
+
+  		entry = REXML::Element.new("bibtex:#{type}")
+
+      fields.each do |key, value|
+        field = REXML::Element.new("bibtex:#{key}")
+				
+				if options[:extended] && value.name?
+					value.each { |n| entry.add_element(n.to_xml) }
+				else
+        	field.text = value.to_s(options)
+				end
+				
+        entry.add_element(field)
       end
-      xml
+
+      xml.add_element(entry)
+			xml
 		end
 		
 		# Returns a duplicate entry with all values converted using the filter.
 		# If an optional block is given, only those values will be converted where
 		# the block returns true (the block will be called with each key-value pair).
 		#
-		# @see convert!
-		#
+		# @see #convert!
 		def convert (filter)
 		  block_given? ? dup.convert!(filter, &Proc.new) : dup.convert!(filter)
 		end
 		
-		# In-place variant of @see convert
+		# In-place variant of @see #convert
 		def convert! (filter)
 		  @fields.each_pair { |k,v| !block_given? || yield(k,v) ? v.convert!(filter) : v }
 		  self
@@ -361,29 +543,18 @@ module BibTeX
 		def <=>(other)
 		  type != other.type ? type <=> other.type : key != other.key ? key <=> other.key : to_s <=> other.to_s
 		end
+
+		private
 		
-		protected
-		
+		# Returns a default key for this entry.
 		def default_key
-			a = case fields[:author]
-			when Names
-				author[0].last
-			when Value
-				author.to_s[/\w+/]
-			else
-				nil
-			end
-			
-			case
-			when a && has_field?(:year) && has_field?(:title)
-				[a,year,title.to_s[/\w{4,}/]].join.downcase.to_sym
-			when a && has_field?(:year)
-				[a,year].join.downcase.to_sym
-			when has_field?(:year) && has_field?(:title)
-				[year,title.to_s[/\w{4,}/]].join.downcase.to_sym
-			else
-		  	object_id.to_s
-			end
+			k = names[0]
+			k = k.respond_to?(:family) ? k.family : k.to_s
+			k = k[/[A-Za-z]+/] || 'unknown'
+			k << (has_field?(:year) ? year : '-')
+			k << 'a'			
+			k.downcase!
+			k
 		end
 		
 	end