axlsx 1.0.12 → 1.0.14

data/lib/axlsx/package.rb

@@ -0,0 +1,223 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+  # Package is responsible for managing all the bits and peices that Open Office XML requires to make a valid
+  # xlsx document including valdation and serialization.
+  class Package
+
+    # provides access to the app doc properties for this package
+    # see App
+    attr_reader :app
+
+    # provides access to the core doc properties for the package
+    # see Core
+    attr_reader :core
+
+    # Initializes your package
+    #
+    # @param [Hash] options A hash that you can use to specify the author and workbook for this package.
+    # @option options [String] :author The author of the document
+    # @example Package.new :author => 'you!', :workbook => Workbook.new
+    def initialize(options={})
+      @workbook = nil
+      @core, @app  =  Core.new, App.new
+      @core.creator = options[:author] || @core.creator
+      yield self if block_given?
+    end
+
+    # The workbook this package will serialize or validate.
+    # @return [Workbook] If no workbook instance has been assigned with this package a new Workbook instance is returned.
+    # @raise ArgumentError if workbook parameter is not a Workbook instance.
+    # @note As there are multiple ways to instantiate a workbook for the package, 
+    #   here are a few examples:
+    #     # assign directly during package instanciation
+    #     wb = Package.new(:workbook => Workbook.new).workbook
+    #
+    #     # get a fresh workbook automatically from the package
+    #     wb = Pacakge.new().workbook
+    #     #     # set the workbook after creating the package
+    #     wb = Package.new().workbook = Workbook.new
+    def workbook
+      @workbook || @workbook = Workbook.new
+      yield @workbook if block_given?
+      @workbook
+    end
+    
+    #def self.parse(input, confirm_valid = false)
+    #  p = Package.new
+    #  z = Zip::ZipFile.open(input)
+    #  p.workbook = Workbook.parse z.get_entry(WORKBOOK_PN)
+    #  p
+    #end    
+
+    # @see workbook
+    def workbook=(workbook) DataTypeValidator.validate "Package.workbook", Workbook, workbook; @workbook = workbook; end
+
+    # Serialize your workbook to disk as an xlsx document.
+    #
+    # @param [File] output The file you want to serialize your package to
+    # @param [Boolean] confirm_valid Validate the package prior to serialization.
+    # @return [Boolean] False if confirm_valid and validation errors exist. True if the package was serialized
+    # @note A tremendous amount of effort has gone into ensuring that you cannot create invalid xlsx documents.
+    #   confirm_valid should be used in the rare case that you cannot open the serialized file. 
+    # @see Package#validate
+    # @example
+    #   # This is how easy it is to create a valid xlsx file. Of course you might want to add a sheet or two, and maybe some data, styles and charts.
+    #   # Take a look at the README for an example of how to do it!
+    #   f = File.open('test.xlsx', 'w')
+    #   Package.new.serialize(f)
+    #
+    #   # You will find a file called test.xlsx
+    def serialize(output, confirm_valid=false)
+      return false unless !confirm_valid || self.validate.empty?
+      p = parts
+      Zip::ZipOutputStream.open(output) do |zip|
+        p.each do |part| 
+          unless part[:doc].nil?
+            zip.put_next_entry(part[:entry]);
+            entry = ['1.9.2', '1.9.3'].include?(RUBY_VERSION) ? part[:doc].force_encoding('BINARY') : part[:doc]
+            zip.puts(entry)
+          end
+          unless part[:path].nil?
+            zip.put_next_entry(part[:entry]); 
+            # binread for 1.9.3
+            zip.write IO.respond_to?(:binread) ? IO.binread(part[:path]) : IO.read(part[:path])
+          end          
+        end
+      end
+      true
+    end
+    
+    
+    # Validate all parts of the package against xsd schema. 
+    # @return [Array] An array of all validation errors found.
+    # @note This gem includes all schema from OfficeOpenXML-XMLSchema-Transitional.zip and OpenPackagingConventions-XMLSchema.zip
+    #   as per ECMA-376, Third edition. opc schema require an internet connection to import remote schema from dublin core for dc,
+    #   dcterms and xml namespaces. Those remote schema are included in this gem, and the original files have been altered to 
+    #   refer to the local versions.
+    #
+    #   If by chance you are able to creat a package that does not validate it indicates that the internal
+    #   validation is not robust enough and needs to be improved. Please report your errors to the gem author.
+    # @see http://www.ecma-international.org/publications/standards/Ecma-376.htm
+    # @example
+    #  # The following will output any error messages found in serialization.
+    #  p = Axlsx::Package.new
+    #  # ... code to create sheets, charts, styles etc.
+    #  p.validate.each { |error| puts error.message }
+    def validate
+      errors = []
+      parts.each { |part| errors.concat validate_single_doc(part[:schema], part[:doc]) unless part[:schema].nil? }
+      errors
+    end
+
+    private 
+
+    # The parts of a package
+    # @return [Array] An array of hashes that define the entry, document and schema for each part of the package. 
+    # @private
+    def parts
+      @parts = [
+       {:entry => RELS_PN, :doc => relationships.to_xml, :schema => RELS_XSD},
+       {:entry => "xl/#{STYLES_PN}", :doc => workbook.styles.to_xml, :schema => SML_XSD},
+       {:entry => CORE_PN, :doc => @core.to_xml, :schema => CORE_XSD},
+       {:entry => APP_PN, :doc => @app.to_xml, :schema => APP_XSD},
+       {:entry => WORKBOOK_RELS_PN, :doc => workbook.relationships.to_xml, :schema => RELS_XSD},
+       {:entry => CONTENT_TYPES_PN, :doc => content_types.to_xml, :schema => CONTENT_TYPES_XSD},
+       {:entry => WORKBOOK_PN, :doc => workbook.to_xml, :schema => SML_XSD}
+      ]
+      workbook.drawings.each do |drawing|
+        @parts << {:entry => "xl/#{drawing.rels_pn}", :doc => drawing.relationships.to_xml, :schema => RELS_XSD}
+        @parts << {:entry => "xl/#{drawing.pn}", :doc => drawing.to_xml, :schema => DRAWING_XSD}
+      end
+        
+      workbook.charts.each do |chart|          
+        @parts << {:entry => "xl/#{chart.pn}", :doc => chart.to_xml, :schema => DRAWING_XSD}
+      end                  
+
+      workbook.images.each do |image|
+        @parts << {:entry => "xl/#{image.pn}", :path => image.image_src}
+      end
+
+      workbook.worksheets.each do |sheet|            
+        @parts << {:entry => "xl/#{sheet.rels_pn}", :doc => sheet.relationships.to_xml, :schema => RELS_XSD}
+        @parts << {:entry => "xl/#{sheet.pn}", :doc => sheet.to_xml, :schema => SML_XSD}        
+      end
+      @parts
+    end
+
+    # Performs xsd validation for a signle document
+    #
+    # @param [String] schema path to the xsd schema to be used in validation.
+    # @param [String] doc The xml text to be validated
+    # @return [Array] An array of all validation errors encountered.
+    # @private
+    def validate_single_doc(schema, doc)
+      schema = Nokogiri::XML::Schema(File.open(schema))
+      doc = Nokogiri::XML(doc)
+
+      errors = []
+      schema.validate(doc).each do |error|
+        errors << error
+      end
+      errors
+    end
+
+    # Appends override objects for drawings, charts, and sheets as they exist in your workbook to the default content types.
+    # @return [ContentType]
+    # @private
+    def content_types
+      c_types = base_content_types
+      workbook.drawings.each do |drawing|
+        c_types << Axlsx::Override.new(:PartName => "/xl/#{drawing.pn}", 
+                                       :ContentType => DRAWING_CT)
+      end
+      workbook.charts.each do |chart|
+        c_types << Axlsx::Override.new(:PartName => "/xl/#{chart.pn}", 
+                                       :ContentType => CHART_CT)                    
+      end
+      workbook.worksheets.each do |sheet|
+        c_types << Axlsx::Override.new(:PartName => "/xl/#{sheet.pn}", 
+                                         :ContentType => WORKSHEET_CT)
+      end
+      exts = workbook.images.map { |image| image.extname }
+      exts.uniq.each do |ext|
+        ct = if  ['jpeg', 'jpg'].include?(ext)
+               JPEG_CT
+             elsif ext == 'gif'
+               GIF_CT
+             elsif ext == 'png'
+               PNG_CT
+             end
+        c_types << Axlsx::Default.new(:ContentType => ct, :Extension => ext )
+      end
+      c_types
+    end
+
+    # Creates the minimum content types for generating a valid xlsx document.
+    # @return [ContentType]
+    # @private
+    def base_content_types
+      c_types = ContentType.new()
+      c_types <<  Default.new(:ContentType => RELS_CT, :Extension => RELS_EX)
+      c_types <<  Default.new(:Extension => XML_EX, :ContentType => XML_CT)
+      c_types << Override.new(:PartName => "/#{APP_PN}", :ContentType => APP_CT)
+      c_types << Override.new(:PartName => "/#{CORE_PN}", :ContentType => CORE_CT)
+      c_types << Override.new(:PartName => "/xl/#{STYLES_PN}", :ContentType => STYLES_CT)
+      c_types << Axlsx::Override.new(:PartName => "/#{WORKBOOK_PN}", :ContentType => WORKBOOK_CT)      
+      c_types.lock
+      c_types
+    end
+
+    # Creates the relationships required for a valid xlsx document
+    # @return [Relationships]
+    # @private
+    def relationships
+      rels = Axlsx::Relationships.new
+      rels << Relationship.new(WORKBOOK_R, WORKBOOK_PN)
+      rels << Relationship.new(CORE_R, CORE_PN)
+      rels << Relationship.new(APP_R, APP_PN)
+      rels.lock
+      rels
+    end
+  end
+end
+

data/lib/axlsx/rels/relationship.rb

@@ -0,0 +1,44 @@
+module Axlsx
+  # A relationship defines a reference between package parts.
+  # @note Packages automatcially manage relationships.
+  class Relationship
+
+    # The location of the relationship target
+    # @return [String]
+    attr_reader :Target
+
+    # The type of relationship
+    # @note Supported types are defined as constants in Axlsx:
+    # @see XML_NS_R
+    # @see TABLE_R
+    # @see WORKBOOK_R
+    # @see WORKSHEET_R
+    # @see APP_R
+    # @see RELS_R
+    # @see CORE_R
+    # @see STYLES_R
+    # @see CHART_R
+    # @see DRAWING_R
+    # @return [String]
+    attr_reader :Type
+    def initialize(type, target)
+      self.Target=target
+      self.Type=type
+    end
+
+    # @see Target
+    def Target=(v) Axlsx::validate_string v; @Target = v end
+    # @see Type
+    def Type=(v) Axlsx::validate_relationship_type v; @Type = v end
+
+    # Serializes the relationship    
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @param [String] rId the reference id of the object.
+    # @return [String]
+    def to_xml(xml, rId)
+      h = self.instance_values
+      h[:Id] = rId
+      xml.Relationship(h)
+    end
+  end
+end

data/lib/axlsx/rels/relationships.rb

@@ -0,0 +1,25 @@
+module Axlsx
+require 'axlsx/rels/relationship.rb'
+
+  # Relationships are a collection of Relations that define how package parts are related.
+  # @note The package automatically manages releationships.
+  class Relationships < SimpleTypedList
+
+    # Creates a new Relationships collection based on SimpleTypedList
+    def initialize
+      super Relationship
+    end
+
+    # Serializes the relationships document.
+    # @return [String]
+    def to_xml()
+      builder = Nokogiri::XML::Builder.new(:encoding => ENCODING) do |xml|
+        xml.Relationships(:xmlns => Axlsx::RELS_R) {
+          each_with_index { |rel, index| rel.to_xml(xml, "rId#{index+1}") }
+        }
+      end
+      builder.to_xml
+    end
+  
+  end
+end

data/lib/axlsx/stylesheet/border.rb

@@ -0,0 +1,57 @@
+module Axlsx
+  # This class details a border used in Office Open XML spreadsheet styles.
+  class Border
+
+    # @return [Boolean] The diagonal up property for the border that indicates if the border should include a diagonal line from the bottom left to the top right of the cell. 
+    attr_reader :diagonalUp
+    
+    # @return [Boolean] The diagonal down property for the border that indicates if the border should include a diagonal line from the top left to the top right of the cell.
+    attr_reader :diagonalDown
+
+    # @return [Boolean] The outline property for the border indicating that top, left, right and bottom borders should only be applied to the outside border of a range of cells.
+    attr_reader :outline
+
+    # @return [SimpleTypedList] A list of BorderPr objects for this border. 
+    attr_reader :prs
+
+    # Creates a new Border object
+    # @option options [Boolean] diagonalUp
+    # @option options [Boolean] diagonalDown
+    # @option options [Boolean] outline
+    # @example Making a border
+    #   p = Package.new
+    #   red_border = Border.new
+    #   [:left, :right, :top, :bottom].each do |item| 
+    #     red_border.prs << BorderPr.new(:name=>item, :style=>:thin, :color=>Color.new(:rgb=>"FFFF0000"))     #   
+    #   end
+    #   # this sets red_border to be the index for the created border.
+    #   red_border = p.workbook.styles.@borders << red_border
+    #   #used in row creation as follows. This will add a red border to each of the cells in the row.
+    #   p.workbook.add_worksheet.rows << :values=>[1,2,3] :style=>red_border
+    def initialize(options={})
+      @prs = SimpleTypedList.new BorderPr
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end        
+
+    # @see diagonalUp
+    def diagonalUp=(v) Axlsx::validate_boolean v; @diagonalUp = v end
+    # @see diagonalDown
+    def diagonalDown=(v) Axlsx::validate_boolean v; @diagonalDown = v end
+    # @see outline
+    def outline=(v) Axlsx::validate_boolean v; @outline = v end
+
+    # Serializes the border element
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    def to_xml(xml)
+      xml.border(self.instance_values.select{ |k,v| [:diagonalUp, :diagonalDown, :outline].include? k }) {
+        [:start, :end, :left, :right, :top, :bottom, :diagonal, :vertical, :horizontal].each do |k|
+          @prs.select { |pr| pr.name == k }.each do |part| 
+            part.to_xml(xml) 
+          end
+        end
+      }
+    end
+  end
+end

data/lib/axlsx/stylesheet/border_pr.rb

@@ -0,0 +1,68 @@
+module Axlsx
+  # A border part. 
+  class BorderPr
+    
+    # @return [Color] The color of this border part.
+    attr_reader :color
+
+    # @return [Symbol] The syle of this border part. 
+    # @note 
+    #  The following are allowed
+    #   :none 
+    #   :thin
+    #   :medium
+    #   :dashed
+    #   :dotted
+    #   :thick
+    #   :double
+    #   :hair 
+    #   :mediumDashed
+    #   :dashDot
+    #   :mediumDashDot
+    #   :dashDotDot
+    #   :mediumDashDotDot
+    #   :slantDashDot
+    attr_reader :style
+
+    # @return [Symbol] The name of this border part
+    # @note 
+    #  The following are allowed
+    #   :start
+    #   :end
+    #   :left
+    #   :right
+    #   :top
+    #   :bottom
+    #   :diagonal
+    #   :vertical
+    #   :horizontal
+    attr_reader :name
+    
+    # Creates a new Border Part Object
+    # @option options [Color] color
+    # @option options [Symbol] name
+    # @option options [Symbol] style
+    # @see Axlsx::Border
+    def initialize(options={})
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # @see name
+    def name=(v) RestrictionValidator.validate "BorderPr.name", [:start, :end, :left, :right, :top, :bottom, :diagonal, :vertical, :horizontal], v; @name = v end
+    # @see color
+    def color=(v) DataTypeValidator.validate(:color, Color, v); @color = v end    
+    # @see style
+    def style=(v) RestrictionValidator.validate "BorderPr.style", [:none, :thin, :medium, :dashed, :dotted, :thick, :double, :hair, :mediumDashed, :dashDot, :mediumDashDot, :dashDotDot, :mediumDashDotDot, :slantDashDot], v; @style = v end
+
+    # Serializes the border part
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.send(@name, :style => @style) {
+        @color.to_xml(xml) if @color.is_a? Color
+      } 
+    end
+  end
+end

data/lib/axlsx/stylesheet/cell_alignment.rb

@@ -0,0 +1,105 @@
+module Axlsx
+  # CellAlignment stores information about the cell alignment of a style Xf Object.
+  # @note Using Styles#add_style is the recommended way to manage cell alignment. 
+  # @see Styles#add_style
+  class CellAlignment
+    # The horizontal alignment of the cell.
+    # @note 
+    #  The horizontal cell alignement style must be one of
+    #   :general
+    #   :left
+    #   :center
+    #   :right
+    #   :fill
+    #   :justify
+    #   :centerContinuous
+    #   :distributed
+    # @return [Symbol]
+    attr_reader :horizontal
+
+    # The vertical alignment of the cell.
+    # @note
+    #  The vertical cell allingment style must be one of the following:
+    #   :top
+    #   :center
+    #   :bottom
+    #   :justify
+    #   :distributed
+    # @return [Symbol]
+    attr_reader :vertical
+
+    # The textRotation of the cell.
+    # @return [Integer]
+    attr_reader :textRotation
+
+    # Indicate if the text of the cell should wrap
+    # @return [Boolean]
+    attr_reader :wrapText
+    
+    # The amount of indent
+    # @return [Integer]
+    attr_reader :indent
+
+    # The amount of relativeIndent
+    # @return [Integer]
+    attr_reader :relativeIndent
+
+    # Indicate if the last line should be justified.
+    # @return [Boolean]
+    attr_reader :justifyLastLine
+
+    # Indicate if the text should be shrunk to the fit in the cell.
+    # @return [Boolean]
+    attr_reader :shrinkToFit
+
+    # The reading order of the text
+    # 0 Context Dependent 
+    # 1 Left-to-Right
+    # 2 Right-to-Left
+    # @return [Integer]
+    attr_reader :readingOrder
+    
+    # Create a new cell_alignment object
+    # @option options [Symbol] horizontal
+    # @option options [Symbol] vertical
+    # @option options [Integer] textRotation
+    # @option options [Boolean] wrapText
+    # @option options [Integer] indent
+    # @option options [Integer] relativeIndent
+    # @option options [Boolean] justifyLastLine
+    # @option options [Boolean] shrinkToFit
+    # @option options [Integer] readingOrder
+    def initialize(options={})
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end        
+    
+    # @see horizontal
+    def horizontal=(v) Axlsx::validate_horizontal_alignment v; @horizontal = v end    
+    # @see vertical
+    def vertical=(v) Axlsx::validate_vertical_alignment v; @vertical = v end    
+    # @see textRotation
+    def textRotation=(v) Axlsx::validate_unsigned_int v; @textRotation = v end    
+    # @see wrapText
+    def wrapText=(v) Axlsx::validate_boolean v; @wrapText = v end    
+    # @see indent
+    def indent=(v) Axlsx::validate_unsigned_int v; @indent = v end    
+    # @see relativeIndent
+    def relativeIndent=(v) Axlsx::validate_int v; @relativeIndent = v end    
+    # @see justifyLastLine
+    def justifyLastLine=(v) Axlsx::validate_boolean v; @justifyLastLine = v end    
+    # @see shrinkToFit
+    def shrinkToFit=(v) Axlsx::validate_boolean v; @shrinkToFit = v end    
+    # @see readingOrder
+    def readingOrder=(v) Axlsx::validate_unsigned_int v; @readingOrder = v end  
+
+    # Serializes the cell alignment
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.alignment(self.instance_values)      
+    end
+    
+  end
+end

data/lib/axlsx/stylesheet/cell_protection.rb

@@ -0,0 +1,36 @@
+module Axlsx
+  # CellProtection stores information about locking or hiding cells in spreadsheet.
+  # @note Using Styles#add_style is the recommended way to manage cell protection.
+  # @see Styles#add_style
+  class CellProtection
+    
+    # specifies locking for cells that have the style containing this protection
+    # @return [Boolean]
+    attr_reader :hidden
+
+    # specifies if the cells that have the style containing this protection
+    # @return [Boolean]
+    attr_reader :locked
+
+    # Creates a new CellProtection
+    # @option options [Boolean] hidden value for hidden protection
+    # @option options [Boolean] locked value for locked protection
+    def initialize(options={})
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # @see hidden
+    def hidden=(v) Axlsx::validate_boolean v; @hidden = v end    
+    # @see locked
+    def locked=(v) Axlsx::validate_boolean v; @locked = v end    
+
+    # Serializes the cell protection
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.protection(self.instance_values)
+    end
+  end
+end

data/lib/axlsx/stylesheet/cell_style.rb

@@ -0,0 +1,65 @@
+module Axlsx
+  # CellStyle defines named styles that reference defined formatting records and can be used in your worksheet.
+  # @note Using Styles#add_style is the recommended way to manage cell styling.
+  # @see Styles#add_style
+  class CellStyle
+    # The name of this cell style
+    # @return [String]
+    attr_reader :name
+    
+    # The formatting record id this named style utilizes
+    # @return [Integer]
+    # @see Axlsx::Xf
+    attr_reader :xfId
+
+    # The buildinId to use when this named style is applied
+    # @return [Integer]
+    # @see Axlsx::NumFmt
+    attr_reader :builtinId
+
+    # Determines if this formatting is for an outline style, and what level of the outline it is to be applied to.
+    # @return [Integer]
+    attr_reader :iLevel
+
+    # Determines if this named style should show in the list of styles when using excel
+    # @return [Boolean]
+    attr_reader :hidden
+
+    # Indicates that the build in style reference has been customized.
+    # @return [Boolean]
+    attr_reader :customBuiltin
+
+    # Creats a new CellStyle object
+    # @option options [String] name
+    # @option options [Integer] xfId
+    # @option options [Integer] buildinId
+    # @option options [Integer] iLevel
+    # @option options [Boolean] hidden
+    # @option options [Boolean] customBuiltIn
+    def initialize(options={})
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? o[0]
+      end
+    end
+    # @see name
+    def name=(v)  Axlsx::validate_string v; @name = v end
+    # @see xfId
+    def xfId=(v) Axlsx::validate_unsigned_int v; @xfId = v end
+    # @see builtinId
+    def builtinId=(v) Axlsx::validate_unsigned_int v; @builtinId = v end
+    # @see iLivel
+    def iLevel=(v) Axlsx::validate_unsigned_int v; @iLevel = v end
+    # @see hidden
+    def hidden=(v) Axlsx::validate_boolean v; @hidden = v end
+    # @see customBuiltin
+    def customBuiltin=(v) Axlsx::validate_boolean v; @customBuiltin = v end
+
+    # Serializes the cell style
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.cellStyle(self.instance_values)
+    end
+  end
+
+end