axlsx 1.0.0 → 1.0.1

data/lib/axlsx/drawing/series.rb~

@@ -0,0 +1,114 @@
+module Axlsx
+  # A Series defines the title, data and labels for chart data.
+  # @note The recommended way to manage series is to use Chart#add_series
+  # @see Worksheet#add_chart
+  # @see Chart#add_series
+  class Series
+
+    # The series title.
+    # @return [String]
+    attr_accessor :title
+
+    # The chart that owns this series
+    # @return [Chart]
+    attr_reader :chart
+    
+    # The data for this series. 
+    # @return [Array, SimpleTypedList]
+    attr_reader :data
+
+
+    # The index of this series in the chart's series.
+    # @return [Integer]
+    attr_reader :index
+
+    # The labels for this series.
+    # @return [Array, SimpleTypedList]
+    attr_reader :labels
+
+
+    # Creates a new series
+    # @option options [Array, SimpleTypedList] data
+    # @option options [Array, SimpleTypedList] labels
+    # @option options [String] title
+    # @param [Chart] chart
+    def initialize(chart, options={})
+      self.chart = chart
+      @chart.series << self
+      self.data = options[:data]  || []
+      self.labels = options[:labels] || []
+      @title = options[:title] || ''
+    end    
+
+    # Serializes the series
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.send('c:ser') {
+        xml.send('c:idx', :val=>index)
+        xml.send('c:order', :val=>index)
+        xml.send('c:tx') {
+          xml.send('c:v', self.title)
+        }
+        
+        if !labels.empty?
+          xml.send('c:cat') {
+            xml.send('c:strRef') {
+              xml.send('c:f', range(labels))
+              xml.send('c:strCache') {
+                xml.send('c:ptCount', :val=>labels.size)
+                labels.each_with_index do |cell, index|
+                  v = cell.is_a?(Cell) ? cell.value : cell
+                  xml.send('c:pt', :idx=>index) {
+                    xml.send('c:v', v)
+                  }                          
+                end
+              }
+            }
+          }
+        end
+        xml.send('c:val') {
+          xml.send('c:numRef') {
+            xml.send('c:f', range(data))
+            xml.send('c:numCache') {
+              xml.send('c:formatCode', 'General')
+              xml.send('c:ptCount', :val=>data.size)
+              data.each_with_index do |cell, index|
+                v = cell.is_a?(Cell) ? cell.value : cell
+                xml.send('c:pt', :idx=>index) {
+                  xml.send('c:v', v) 
+                }
+              end
+            }                        
+          }
+        }
+      }                  
+      
+    end
+
+    def index
+      @chart.series.index(self)
+    end
+    
+    private 
+
+    # determines the cell range for the items provided
+    def range(items)
+      return "" unless items.first.is_a? Cell      
+
+      "#{items.first.row.worksheet.name}!" +
+        "#{items.first.r_abs}:#{items.last.r_abs}"
+    end
+
+
+    # assigns the data for this series
+    def data=(v) DataTypeValidator.validate "Series.data", [Array, SimpleTypedList], v; @data = v; end
+
+    # assigns the labels for this series
+    def labels=(v) DataTypeValidator.validate "Series.labels", [Array, SimpleTypedList], v; @labels = v; end
+
+    # assigns the chart for this series
+    def chart=(v)  DataTypeValidator.validate "Series.chart", [Chart, Pie3DChart], v; @chart = v; end    
+  end
+
+end

data/lib/axlsx/drawing/title.rb~

@@ -0,0 +1,69 @@
+module Axlsx
+  # A Title stores information about the title of a chart
+  class Title
+    
+    # The text to be shown. Setting this property directly with a string will remove the cell reference.
+    # @return [String]
+    attr_accessor :text
+
+    # The cell that holds the text for the title. Setting this property will automatically update the text attribute.
+    # @return [Cell]
+    attr_accessor :cell
+
+    # Creates a new Title object
+    # @param [String, Cell] title The cell or string to be used for the chart's title
+    def initialize(title="")
+      self.cell = title if title.is_a?(Cell)
+      self.text = title.to_s unless title.is_a?(Cell)
+    end
+    
+    def text=(v) 
+      DataTypeValidator.validate 'Title.text', String, v
+      @text = v
+      @cell = nil
+      v
+    end
+
+    def cell=(v)
+      DataTypeValidator.validate 'Title.text', Cell, v
+      @cell = v
+      @text = v.value.to_s      
+      v
+    end
+
+    # Not implemented at this time.
+    #def tx=(v) DataTypeValidator.validate 'Title.tx', Tx, v; @tx=v; end
+    #def layout=(v) DataTypeValidator.validate 'Title.layout', Layout, v; @layout = v; end
+    #def overlay=(v) Axlsx::validate_boolean v; @overlay=v; end
+    #def spPr=(v) DataTypeValidator.validate 'Title.spPr', SpPr, v; @spPr = v; end
+    
+    # Serializes the chart title
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.send('c:title') {
+        xml.send('c:tx') {
+          xml.send('c:strRef') {
+            xml.send('c:f', range)
+            xml.send('c:strCache') {
+              xml.send('c:ptCount', :val=>1)
+              xml.send('c:pt', :idx=>0) {
+                xml.send('c:v', @text)
+              }
+            }
+          }
+        }
+      }      
+    end
+
+    private 
+
+    # returns the excel style abslute reference for the title when title is a Cell object
+    # @return [String]
+    def range
+      return "" unless @data.is_a?(Cell)
+      "#{@data.row.worksheet.name}!#{data.row.r_abs}"
+    end
+
+  end
+end

data/lib/axlsx/drawing/two_cell_anchor.rb~

@@ -0,0 +1,70 @@
+module Axlsx
+  # This class details the anchor points for drawings.
+  # @note The recommended way to manage drawings and charts is Worksheet#add_chart. Anchors are specified by the :start_at and :end_at options to that method.
+  # @see Worksheet#add_chart
+  class TwoCellAnchor
+
+    # A marker that defines the from cell anchor. The default from column and row are 0 and 0 respectively
+    # @return [Marker]
+    attr_reader :from
+    # A marker that returns the to cell anchor. The default to column and row are 5 and 10 respectively
+    # @return [Marker]
+    attr_reader :to
+
+    # The frame for your chart
+    # @return [GraphicFrame]
+    attr_reader :graphic_frame
+
+    # Creates a new TwoCellAnchor object
+    # @param [Drawing] drawing
+    # @param [Chart] chart
+    # @option options [Array] start_at
+    # @option options [Array] end_at
+    def initialize(drawing, chart, options)
+      raise ArgumentError, "TwoCellAnchor.chart must be a Chart" unless chart.is_a? Chart
+      @from, @to =  Marker.new, Marker.new(:col => 5, :row=>10)
+      @graphic_frame = GraphicFrame.new(chart)
+      # BUG? what happens if :start_at is not defined?
+      self.start_at(options[:start_at][0], options[:start_at][1]) if options[:start_at].is_a?(Array)
+      self.end_at(options[:end_at][0], options[:end_at][1]) if options[:end_at].is_a?(Array)
+      drawing.anchors << self
+    end
+    
+    # This is a short cut method to set the start anchor position
+    # @param [Integer] x The column
+    # @param [Integer] y The row
+    # @return [Marker]
+    def start_at(x, y)
+      @from.col = x
+      @from.row = y
+      @from
+    end
+
+    # This is a short cut method to set the end anchor position
+    # @param [Integer] x The column
+    # @param [Integer] y The row
+    # @return [Marker]
+    def end_at(x, y)
+      @to.col = x
+      @to.row = y
+      @to
+    end
+
+    # Serializes the two cell anchor
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      #build it for now, break it down later!
+      xml.send('xdr:twoCellAnchor') {
+        xml.send('xdr:from') {
+          from.to_xml(xml)
+        }
+        xml.send('xdr:to') {
+          to.to_xml(xml)
+        }
+        @graphic_frame.to_xml(xml)
+        xml.send('xdr:clientData')
+      }
+    end    
+  end
+end

data/lib/axlsx/drawing/val_axis.rb~

@@ -0,0 +1,34 @@
+module Axlsx
+  # the ValAxis class defines a chart value axis.
+  class ValAxis < Axis
+
+    # This element specifies whether the value axis crosses the category axis between categories.
+    # must be one of [:between, :midCat]
+    # @return [Symbol]
+    attr_accessor :crossesBetween
+
+    # Creates a new ValAxis object
+    # @param [Integer] axId the id of this axis
+    # @param [Integer] crossAx the id of the perpendicular axis
+    # @option options [Symbol] axPos
+    # @option options [Symbol] crosses
+    # @option options [Symbol] tickLblPos
+    # @option options [Symbol] crossesBetween
+    def initialize(axId, crossAx, options={})
+      super(axId, crossAx, options)
+      @crossesBetween = :between
+    end
+
+    # Serializes the value  axis
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @return [String]
+    def to_xml(xml)
+      xml.send('c:valAx') {
+        super(xml)
+        xml.send('c:axId', :val=>@axId)
+        @scaling.to_xml(xml)
+        xml.send('c:crossesBetween', :val=>@crossesBetween)
+      }
+    end
+  end
+end

data/lib/axlsx/drawing/view_3D.rb~

@@ -0,0 +1,21 @@
+module Axlsx
+
+  
+  attr_accessor :rotX
+  attr_accessor :hPercent
+  attr_accessor :rotY
+  attr_accessor :depthPercent
+  attr_accessor :rAngAx
+  attr_accessor :perspective
+  
+  def initialize(options={})
+
+  end
+
+  def rotX=(v) DataTypeValidator.validate "#{self.class}.rotX", [Integer, Fixnum], v, lambda {|v| v >= -90 && v <= 90 }; @rotX = v; end
+  
+  def to_xml(xml)
+
+  end
+
+end

data/lib/axlsx/package.rb

@@ -24,12 +24,11 @@ module Axlsx
     #
     # @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
-    # @option options [Workbook] :workbook The workbook associated with this package.
     # @example Package.new :author => 'you!', :workbook => Workbook.new
     def initialize(options={})
       @core, @app = Core.new, App.new
       @core.creator = options[:author] || @core.creator
-      self.workbook= options[:workbook] if options[:workbook]
+      yield self if block_given?
     end
 
     def workbook=(workbook) DataTypeValidator.validate "Package.workbook", Workbook, workbook; @workbook = workbook; end
@@ -55,7 +54,8 @@ module Axlsx
     #   # You will find a file called test.xlsx
     def serialize(output, confirm_valid=false)
       return false unless !confirm_valid || self.validate.empty?
-      Zip::ZipOutputStream.open(output.path) do |zip|
+      f = File.new(output, "w")
+      Zip::ZipOutputStream.open(f.path) do |zip|
         parts.each{ |part| zip.put_next_entry(part[:entry]); zip.puts(part[:doc]) }
       end
       true

data/lib/axlsx/package.rb~

@@ -0,0 +1,181 @@
+# -*- coding: utf-8 -*-
+# Create Office Open XML Spreadsheets (xlsx) with safe and full control over cell styles, automatically resized column widths and 3D pie charts.
+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
+
+    # The workbook this package will serialize or validate.
+    # @attribute
+    # @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
+    attr_accessor :workbook
+
+    # 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
+    # @option options [Workbook] :workbook The workbook associated with this package.
+    # @example Package.new :author => 'you!', :workbook => Workbook.new
+    def initialize(options={})
+      @core, @app = Core.new, App.new
+      @core.creator = options[:author] || @core.creator
+      self.workbook= options[:workbook] if options[:workbook]
+    end
+
+    def workbook=(workbook) DataTypeValidator.validate "Package.workbook", Workbook, workbook; @workbook = workbook; end
+
+    def workbook
+      @workbook || @workbook = Workbook.new
+    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?
+      Zip::ZipOutputStream.open(output.path) do |zip|
+        parts.each{ |part| zip.put_next_entry(part[:entry]); zip.puts(part[:doc]) }
+      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]) }
+      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 => 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 => WORKBOOK_PN, :doc => workbook.to_xml, :schema => SML_XSD},
+       {:entry => CONTENT_TYPES_PN, :doc => content_types.to_xml, :schema => CONTENT_TYPES_XSD},
+       {:entry => "xl/#{STYLES_PN}", :doc => workbook.styles.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.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
+      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
+