citeproc 0.0.8 → 0.0.9

data/lib/citeproc/bibliography.rb

@@ -1,49 +1,14 @@
-
 module CiteProc
 
-  # = Bibliography
-  #
-  # Typically a Bibliography is returned by the Processor. It contains a list
-  # of references and formatting options. 
+  # Typically a {Bibliography} is returned by a {Processor} instance. It
+  # contains a list of references and formatting options.
   #
   # A Bibliography can be created from (and exported to) CiteProc JSON
-  # bibliographies; these consist of a  two-element list, composed of a
+  # bibliographies; these consist of a two-element list, composed of a
   # JavaScript array containing certain formatting parameters, and a list of
   # strings representing bibliography entries.
   #
-  # == Bibliography Formatting Options
-  #
-  # :offset => 0
-  #   Some citation styles apply a label (either a number or an alphanumeric
-  #   code) to each bibliography entry, and use this label to cite
-  #   bibliography items in the main text. In the bibliography, the labels
-  #   may either be hung in the margin, or they may be set flush to the
-  #   margin, with the citations indented by a uniform amount to the right.
-  #   In the latter case, the amount of indentation needed depends on the
-  #   maximum width of any label. The :offset option gives the maximum
-  #   number of characters that appear in any label used in the
-  #   bibliography. The client that controls the final rendering of the
-  #   bibliography string should use this value to calculate and apply a
-  #   suitable indentation length.
-  #
-  # :entry_spacing => 0
-  #   An integer representing the spacing between entries in the
-  #   bibliography.
-  #
-  # :line_spacing => 0
-  #   An integer representing the spacing between the lines within each
-  #   bibliography entry.
-  #
-  # :indent => 0
-  #   The number of em-spaces to apply in hanging indents within the
-  #   bibliography.
-  #
-  # :align => false
-  #   When the second-field-align CSL option is set, this returns either
-  #   "flush" or "margin". The calling application should align text in
-  #   bibliography output as described in the CSL specification. Where
-  #   second-field-align is not set, this return value is set to false.
-  #
+  # See {.defaults} for the default formatting options.
   class Bibliography
 
     @defaults = {
@@ -72,7 +37,46 @@ module CiteProc
     
     class << self
       
-      attr_reader :defaults, :cp2rb, :rb2cp
+      # @!attribute [r] defaults
+      # @example Default Formatting Options
+      #   {
+      #     :offset => 0,
+      #     # Some citation styles apply a label (either a number or an
+      #     # alphanumeric code) to each bibliography entry, and use this
+      #     # label to cite bibliography items in the main text. In the
+      #     # bibliography, the labels may either be hung in the margin,
+      #     # or they may be set flush to the margin, with the citations
+      #     # indented by a uniform amount to the right. In the latter case,
+      #     # the amount of indentation needed depends on the  maximum width
+      #     # of any label. The :offset option gives the maximum number of
+      #     # characters that appear in any label used in the bibliography.
+      #     # The client that controls the final rendering of the bibliography
+      #     # string should use this value to calculate and apply a suitable
+      #     # indentation length.
+      #
+      #     :entry_spacing => 0,
+      #     # An integer representing the spacing between entries in the
+      #     # bibliography.
+      #
+      #     :line_spacing => 0,
+      #     # An integer representing the spacing between the lines within
+      #     # each bibliography entry.
+      #
+      #     :indent => 0,
+      #     # The number of em-spaces to apply in hanging indents within the
+      #     # bibliography.
+      #
+      #     :align => false
+      #     # When the second-field-align CSL option is set, this returns
+      #     # either "flush" or "margin". The calling application should
+      #     # align text in the bibliography output as described by the CSL
+      #     # specification. Where second-field-align is not set, this
+      #     # return value is set to false.
+      #   }
+      # @return [Hash] default formatting options
+      attr_reader :defaults
+
+      attr_reader :cp2rb, :rb2cp
       
       # Create a new Bibliography from the passed-in string or array, or nil
       # if the input cannot be parsed.
@@ -115,10 +119,29 @@ module CiteProc
         
     extend Forwardable
 
-    attr_reader :options, :errors, :references
+    # @!attribute [r] refrences
+    # @return [Array<String>] the list of references
+    attr_reader :references
+    
+    # @!attribute [r] options
+    # @see .defaults
+    # @return [Hash] the current formatting options
+    attr_reader :options
+    
+    # @!attribute [r] errors
+    # @todo not implemented yet
+    # @return [Array<String>] a list of errors
+    attr_reader :errors
 
+    # @!attribute prefix
+    # @return [String] content included before the reference list
     attr_accessor :prefix, :suffix
 
+    # @!attribute suffix
+    # @return [String] content included after the reference list
+    attr_accessor :suffix
+
+
     # Bibliographies quack sorta like an Array
     def_delegators :@references, :length, :empty?, :[], :include?, :index
 
@@ -150,7 +173,7 @@ module CiteProc
     alias errors? has_errors?
     
     def join(connector = "\n")
-      [prefix, references.join(connector), suffix].join
+      [prefix, references.join(connector), suffix].compact.join
     end
     
     def each
@@ -190,6 +213,7 @@ module CiteProc
       MultiJson.encode(to_citeproc)
     end
     
+    # @return [String] a human-readable representation of the bibliography
     def inspect
       "#<CiteProc::Bibliography @references=[#{references.length}], @errors=[#{errors.length}]>"
     end

data/lib/citeproc/citation_data.rb

@@ -1,29 +1,9 @@
 module CiteProc
 
-	# CitationItems consititue the main input elements to CiteProc's processing
-	# methods. In order to be processed correctly, an item must contain a valid
-	# id attribute used to retrieve the item's bibliographic data. Additionally,
-	# an item may include the following, optional, attributes:
-	#
-	# * locator: a string identifying a page number or other pinpoint location
-	#   or range within the resource;
-  #
-	# * label: a label type, indicating whether the locator is to a page, a
-	#   chapter, or other subdivision of the target resource. Valid labels are
-	#   defined in CitationItem.labels
-	#
-	# * suppress-author: if true, author names will not be included in the
-	#   citation output for this cite;
-	#
-	# * author-only: if true, only the author name will be included in the
-	#   citation output for this cite -- this optional parameter provides a
-	#   means for certain demanding styles that require the processor output
-	#   to be divided between the main text and a footnote.
-	#
-	# * prefix: a string to print before this cite item;
-	#
-	# * suffix: a string to print after this cite item.
-  #
+	# A {CitationItem} consititues the main input elements to CiteProc's
+	# processing methods. In order to be processed correctly, an item must
+	# have a valid {#id} attribute used to retrieve the correpsonding {Item}
+	# containing the actual bibliographic data.
 	class CitationItem
 		
 		include Attributes
@@ -37,27 +17,58 @@ module CiteProc
 			attr_reader :labels			
 		end
 		
+		# @!attribute id
+		# @return [Symbol,String] the id of the corresponding resource
+
+		# @!attribute locator
+		# @return [String] a string identifying a page number or similar to mark
+		#   a location or range within the resource
+
+		# @!attribute label
+		# Labels indicate whether the current locator is to a page, a chapter,
+		# or other subdivision of the target resource. Valid labels are defined
+		# by {.labels}.
+		# @return [Symbol,String] the label type
+
+		# @!attribute suppress_author
+		# @return [Boolean] whether or not author names will not be included
+		#   in the citation output for this cite
+  	
+  	# @!attribute author_only
+  	# This optional parameter provides a means for certain demanding styles
+  	# that require the processor output to be divided between the main text
+  	# and a footnote.
+  	# @return [Boolean] whether or not only the author name will be included
+  	#   in the citation output for this cite
+  	
+  	# @!attribute prefix
+  	# @return [String] a string to print before cites produced for this item
+
+  	# @!attribute suffix
+  	# @return [String] a string to print after cites produced for this item
+
 		attr_predicates :id, :locator, :label, :'suppress-author',
 			:'author-only', :prefix, :suffix
-		
-		# Added by processor	
+
+		# Attributes added by processor	
 		attr_predicates :sortkeys, :postion, :'first-reference-note-number',
 			:'near-note', :unsorted
-		
+
 		attr_accessor :data
-		
+
 		def initialize(attributes = nil)
 			merge(attributes)
 		end
-		
+
 		def initialize_copy(other)
 			@attributes = other.attributes.deep_copy
 		end
-		
+
+		# @return [String] a human-readable representation of the citation item
 		def inspect
-			"#<CiteProc::CitationItem #{id.to_s}, #{locator.to_s} >"
+			"#<CiteProc::CitationItem #{id.to_s.inspect}, #{locator.to_s.inspect}>"
 		end
-		
+
 	end
 	
 	
@@ -102,17 +113,7 @@ module CiteProc
 				self
 			end
 		end
-		
-		def each
-			if block_given?
-				items.each(&Proc.new)
-				self
-			else
-				to_enum
-			end
-		end
-		
-		
+				
 		def initialize(attributes = nil, options = {})
 			@options = CitationData.defaults.merge(options)
 			@items, @sorted_items = [], []
@@ -125,7 +126,7 @@ module CiteProc
 			@sorted_items = other.items.map(&:dup)
 			@id = other.id.dup if other.processed?
 		end
-		
+
     def merge(other)
       return self if other.nil?
       
@@ -151,16 +152,25 @@ module CiteProc
 			options.merge!(convert_from_citeproc(Hash[properties])) unless properties.nil?
 
 			@id = other[:id] if other.has_key?(:id)
-			      
+
       self
     end
 		
 		alias update merge
 		
+		def each
+			if block_given?
+				items.each(&Proc.new)
+				self
+			else
+				to_enum
+			end
+		end
+
 		def processed?
 			!!id
 		end
-		
+
 		def index
 			options[:footnote]
 		end
@@ -186,6 +196,7 @@ module CiteProc
 		
 		alias to_s to_json
 		
+		# @return [String] a human-readable representation of the citation data
 		def inspect
 			"#<CiteProc::CitationData items=[#{length}]>"
 		end

data/lib/citeproc/compatibility.rb

@@ -1,10 +1,12 @@
+# -*- coding: utf-8 -*-
+
 unless Symbol.is_a?(Comparable)
   class Symbol
     include Comparable
-    
-		def =~(pattern)
-			to_s =~ pattern
-		end
+
+    def =~(pattern)
+      to_s =~ pattern
+    end
 
     def <=>(other)
       return nil unless other.is_a?(Symbol)
@@ -12,3 +14,158 @@ unless Symbol.is_a?(Comparable)
     end
   end
 end
+
+
+
+if RUBY_VERSION < '1.9'
+  require 'enumerator'
+
+  $KCODE = 'u'
+  require 'jcode'
+
+  module CiteProc
+
+    def to_unicode(string)
+      string.gsub(/\\?u([\da-f]{4})/i) { |m| [$1.to_i(16)].pack('U') }
+    end
+
+    def ruby_18
+      yield
+    end
+
+    def ruby_19
+      false
+    end
+    
+    begin
+      require 'oniguruma'
+      
+      def oniguruma
+        Oniguruma::ORegexp.new(yield, :syntax => Oniguruma::SYNTAX_JAVA, :encoding => Oniguruma::ENCODING_UTF8)
+      end
+      
+      def oniguruma?
+        true
+      end
+    rescue LoadError
+      def oniguruma
+        false
+      end
+      alias oniguruma? oniguruma
+    end
+  end
+
+  # Remove the 'id' and 'type' methods in Ruby 1.8
+  class Object
+    undef_method :id
+    undef_method :type
+  end
+
+else
+
+  module CiteProc
+    def to_unicode(string)
+      string
+    end
+
+    def ruby_18
+      false
+    end
+
+    def ruby_19
+      yield
+    end
+    
+    def oniguruma
+      Regexp.new(yield)
+    end
+    
+    def oniguruma?
+      true
+    end
+  end
+end
+
+#
+# Robust unicode upcase/downcase
+#
+
+if RUBY_PLATFORM == 'java'
+  require 'java'
+
+  puts java.lang.System.getProperty('file.encoding')
+  
+  module CiteProc
+    def upcase(string)
+      java.lang.String.new(string).to_upper_case(java.util.Locale::ENGLISH).to_s
+    end
+
+    def downcase(string)
+      java.lang.String.new(string).to_lower_case(java.util.Locale::ENGLISH).to_s
+    end
+    
+    # def oniguruma
+    #   Regexp.new(yield)
+    # end
+    # 
+    # def oniguruma?
+    #   true
+    # end
+  end
+
+else
+
+  module CiteProc
+    private
+
+    begin
+      require 'unicode'
+
+      def upcase(string)
+        Unicode.upcase(string)
+      end
+
+      def downcase(string)
+        Unicode.downcase(string)
+      end
+    rescue LoadError
+      begin
+        require 'unicode_utils'
+
+        def upcase(string)
+          UnicodeUtils.upcase(string)
+        end
+
+        def downcase(string)
+          UnicodeUtils.downcase(string)
+        end
+      rescue LoadError
+        begin
+          require 'active_support/multibyte/chars'
+
+          def upcase(string)
+            ActiveSupport::Multibyte::Chars.new(string).upcase.to_s
+          end
+
+          def downcase(string)
+            ActiveSupport::Multibyte::Chars.new(string).downcase.to_s
+          end    
+        rescue LoadError
+
+          def upcase(string)
+            string.upcase
+          end
+
+          def downcase(string)
+            string.downcase
+          end
+        end
+      end
+    end
+  end
+end
+
+module CiteProc
+  module_function :ruby_18, :ruby_19, :oniguruma, :oniguruma?,
+    :to_unicode, :upcase, :downcase
+end