axlsx 1.0.16 → 1.0.17

data/.yardopts

@@ -2,3 +2,4 @@
 --no-private
 --title "AXLSX"
 --files LICENSE
+--files CHANGELOG.md

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 CHANGELOG
 ---------
+- **January.6.12**: 1.0.15 release
+   https://github.com/randym/axlsx/compare/1.0.14...1.0.15
+   - Bug fix add_style specified number formats must be explicity applied for libraOffice
+   - performance improvements from ochko when creating cells with options.
+   - Bug fix setting types=>[:n] when adding a row incorrectly determines the cell type to be string as the value is null during creation.
+   - Release in preparation for password protection merge
+
 - **December.14.11**: 1.0.14 release
    - Added support for merging cells
    - Added support for auto filters

data/README.md

@@ -7,16 +7,16 @@ Axlsx: Office Open XML Spreadsheet Generation
 **Author**:       Randy Morgan   
 **Copyright**:    2011      
 **License**:      MIT License      
-**Latest Version**: 1.0.16   
+**Latest Version**: 1.0.17   
 **Ruby Version**: 1.8.7, 1.9.2, 1.9.3 
 
-**Release Date**: February 2nd 2012     
+**Release Date**: February 14th 2012     
 
 Synopsis
 --------
 
 Axlsx is an Office Open XML Spreadsheet generator for the Ruby programming language.
-With Axlsx you can create excel worksheets with charts, images, automated column width, customizable styles, functins, merged cells and auto filters as well as full schema validation. Axlsx excels at helping you generate beautiful Office Open XML Spreadsheet documents without having to understand the entire ECMA specification.
+With Axlsx you can create excel worksheets with charts, images (with links), automated and fixed column widths, customizable styles, functions, merged cells, auto filters, file adn stream serialization  as well as full schema validation. Axlsx excels at helping you generate beautiful Office Open XML Spreadsheet documents without having to understand the entire ECMA specification.
 
 If you are working in rails, or with active record see:
 http://github.com/randym/acts_as_xlsx 
@@ -40,15 +40,15 @@ Feature List
 
 **4. Automatic type support: Axlsx will automatically determine the type of data you are generating. In this release Float, Integer, String and Time types are automatically identified and serialized to your spreadsheet.
 
-**5. Automatic column widths: Axlsx will automatically determine the appropriate width for your columns based on the content in the worksheet.
+**5. Automatic and fixed column widths: Axlsx will automatically determine the appropriate width for your columns based on the content in the worksheet, or use any value you specify for the really funky stuff.
 
 **6. Support for automatically formatted 1904 and 1900 epocs configurable in the workbook.
 
 **7. Add jpg, gif and png images to worksheets with hyperlinks
 
-**8. Refernce cells in your worksheet with "A1" and "A1:D4" style references or from the workbook using "Sheett1!A3:B4" style references
+**8. Reference cells in your worksheet with "A1" and "A1:D4" style references or from the workbook using "Sheett1!A3:B4" style references
 
-**9. Cell level style overrides for default and customized style object
+**9. Cell level style overrides for default and customized style objects
 
 **10. Support for formulas
 
@@ -56,6 +56,10 @@ Feature List
 
 **12. Auto filtering tables with worksheet.auto_filter
 
+**13. Export using shared strings or inline strings so we can inter-op with iWork Numbers (sans charts for now).
+
+**14. Output to file or StringIO
+
 Installing
 ----------
 
@@ -90,6 +94,7 @@ To install Axlsx, use the following command:
      end
 
 ##Using Custom Formatting and date1904
+
      require 'date'
      wb.styles do |s|
        date = s.add_style(:format_code => "yyyy-mm-dd", :border => Axlsx::STYLE_THIN_BORDER)
@@ -253,11 +258,28 @@ To install Axlsx, use the following command:
        sheet.auto_filter = "A2:D5"
      end  
 
+##Specifying Column Widths
+
+     wb.add_worksheet(:name => "custom column widths") do |sheet|
+       sheet.add_row ["I use auto_fit and am very wide", "I use a custom width and am narrow"]
+       sheet.column_widths nil, 3
+     end
+
 ##Validate and Serialize
 
      p.validate.each { |e| puts e.message }
      p.serialize("example.xlsx")
 
+     # alternatively, serilaize to StringIO
+     s = p.to_stream()
+     File.open('example_streamed.xlsx', 'w') { |f| f.write(s.read) }
+
+##Using Shared Strings
+
+     p.use_shared_strings = true
+     p.serialize("shared_strings_example.xlsx")
+
+
 
 #Documentation
 --------------
@@ -272,19 +294,21 @@ This gem has 100% test coverage using test/unit. To execute tests for this gem,
  
 #Changelog
 ---------
+- ** February.14.12**: 1.0.17 release
+   https://github.com/randym/axlsx/compare/1.0.16...1.0.17
+   - Added in support for serializing to StringIO
+   - Added in support for using shared strings table. This makes most of the features in axlsx interoperable with iWorks Numbers
+   - Added in support for fixed column_widths
+   - Removed unneded depenencies on activesupport and i18n
+
 - ** February.2.12**: 1.0.16 release
+   https://github.com/randym/axlsx/compare/1.0.15...1.0.16
    - Bug fix for schema file locations when validating in rails
    - Added hyperlink to images
    - date1904 now automatically set in bsd and mac environments
    - removed whitespace/indentation from xml outputs
    - col_style now skips rows that do not contain cells at the column index
  
-- **January.6.12**: 1.0.15 release
-   - Bug fix add_style specified number formats must be explicity applied for libraOffice
-   - performance improvements from ochko when creating cells with options.
-   - Bug fix setting types=>[:n] when adding a row incorrectly determines the cell type to be string as the value is null during creation.
-   - Release in preparation for password protection merge
-
  
 Please see the {file:CHANGELOG.md} document for past release information.
 
@@ -294,6 +318,8 @@ Please see the {file:CHANGELOG.md} document for past release information.
 
 [kleine2](https://github.com/kleine2) - for generously donating in return for the image hyperlink feature.
 
+[ffmike](https://github.com/ffmike) - for knocking down an over restrictive i18n dependency, massive patience and great communication skills.
+
 #Copyright and License
 ----------
 

data/examples/example.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # -*- coding: utf-8 -*-
-     require 'axlsx'
+     require 'axlsx.rb'
 
      p = Axlsx::Package.new
      wb = p.workbook
@@ -187,10 +187,27 @@
        sheet.auto_filter = "A2:D5"
      end  
 
+##Specifying Column Widths
+
+     wb.add_worksheet(:name => "custom column widths") do |sheet|
+       sheet.add_row ["I use autowidth and am very wide", "I use a custom width and am narrow"]
+       sheet.column_widths nil, 3
+     end
+
 ##Validate and Serialize
 
      p.validate.each { |e| puts e.message }
      p.serialize("example.xlsx")
 
+     s = p.to_stream()
+     File.open('example_streamed.xlsx', 'w') { |f| f.write(s.read) }
+
+
+##Using Shared Strings
+
+     p.use_shared_strings = true
+     p.serialize("shared_strings_example.xlsx")
+
+
      
 

data/lib/axlsx.rb

@@ -1,14 +1,12 @@
-Encoding::default_internal = 'UTF-8' unless RUBY_VERSION < '1.9'
-Encoding::default_external = 'UTF-8' unless RUBY_VERSION < '1.9'
-
+# encoding: UTF-8
 require 'axlsx/version.rb'
 
 require 'axlsx/util/simple_typed_list.rb'
 require 'axlsx/util/constants.rb'
 require 'axlsx/util/validators.rb'
-# require 'axlsx/util/storage.rb'
-# require 'axlsx/util/cbf.rb'
-# require 'axlsx/util/ms_off_crypto.rb'
+require 'axlsx/util/storage.rb'
+require 'axlsx/util/cbf.rb'
+require 'axlsx/util/ms_off_crypto.rb'
 
 
 # to be included with parsable intitites.
@@ -27,8 +25,6 @@ require 'axlsx/package.rb'
 
 #required gems
 require 'nokogiri'
-require 'active_support/core_ext/object/instance_variables'
-require 'active_support/inflector'
 require 'RMagick'
 require 'zip/zip'
 
@@ -36,6 +32,16 @@ require 'zip/zip'
 require 'bigdecimal'
 require 'time'
 
+#if object does not have this already, I am borrowing it from active_support.
+# I am a very big fan of activesupports instance_values method, but do not want to require nor include the entire 
+# library just for this one method. 
+if !Object.respond_to?(:instance_values)
+  Object.send :public  # patch for 1.8.7 as it uses private scope
+  Object.send :define_method, :instance_values do
+    Hash[instance_variables.map { |name| [name.to_s[1..-1], instance_variable_get(name)] }]
+  end
+end
+
 
 # xlsx generation with charts, images, automated column width, customizable styles and full schema validation. Axlsx excels at helping you generate beautiful Office Open XML Spreadsheet documents without having to understand the entire ECMA specification. Check out the README for some examples of how easy it is. Best of all, you can validate your xlsx file before serialization so you know for sure that anything generated is going to load on your client's machine.
 module Axlsx

data/lib/axlsx/content_type/content_type.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   require 'axlsx/content_type/default.rb'
   require 'axlsx/content_type/override.rb'

data/lib/axlsx/content_type/default.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # An default content part. These parts are automatically created by for you based on the content of your package.
   class Default

data/lib/axlsx/content_type/override.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # An override content part. These parts are automatically created by for you based on the content of your package.
   class Override

data/lib/axlsx/doc_props/app.rb

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+# encoding: UTF-8
 module Axlsx
   # App represents the app.xml document. The attributes for this object are primarily managed by the application the end user uses to edit the document. None of the attributes are required to serialize a valid xlsx object.
   # @see shared-documentPropertiesExtended.xsd

data/lib/axlsx/doc_props/core.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # The core object for the package.
   # @note Packages manage their own core object.

data/lib/axlsx/drawing/axis.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
  # the access class defines common properties and values for a chart axis.
   class Axis

data/lib/axlsx/drawing/bar_3D_chart.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
 
   # The Bar3DChart is a three dimentional barchart (who would have guessed?) that you can add to your worksheet.

data/lib/axlsx/drawing/bar_series.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A BarSeries defines the title, data and labels for bar charts
   # @note The recommended way to manage series is to use Chart#add_series

data/lib/axlsx/drawing/cat_axis.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   #A CatAxis object defines a chart category axis
   class CatAxis < Axis

data/lib/axlsx/drawing/cat_axis_data.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # The CatAxisData class serializes the category axis data for a chart
   class CatAxisData < SimpleTypedList

data/lib/axlsx/drawing/chart.rb

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+# encoding: UTF-8
 module Axlsx
   # A Chart is the superclass for specific charts
   # @note Worksheet#add_chart is the recommended way to create charts for your worksheets.

data/lib/axlsx/drawing/drawing.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   require 'axlsx/drawing/title.rb'
   require 'axlsx/drawing/series_title.rb'

data/lib/axlsx/drawing/graphic_frame.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A graphic frame defines a container for a chart object
   # @note The recommended way to manage charts is Worksheet#add_chart

data/lib/axlsx/drawing/hyperlink.rb

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+# encoding: UTF-8
 module Axlsx
   # a hyperlink object adds an action to an image when clicked so that when the image is clicked the link is fecthed.
   # @note using the hyperlink option when calling add_image on a drawing object is the recommended way to manage hyperlinks

data/lib/axlsx/drawing/line_3D_chart.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
 
   # The Line3DChart is a three dimentional line chart (who would have guessed?) that you can add to your worksheet.

data/lib/axlsx/drawing/line_series.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A LineSeries defines the title, data and labels for line charts
   # @note The recommended way to manage series is to use Chart#add_series

data/lib/axlsx/drawing/marker.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # The Marker class defines a point in the worksheet that drawing anchors attach to.
   # @note The recommended way to manage markers is Worksheet#add_chart Markers are created for a two cell anchor based on the :start and :end options.

data/lib/axlsx/drawing/one_cell_anchor.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # This class details a single cell anchor for drawings.
   # @note The recommended way to manage drawings, images and charts is Worksheet#add_chart or Worksheet#add_image.

data/lib/axlsx/drawing/pic.rb

@@ -1,4 +1,4 @@
-# -*- coding: utf-8 -*-
+# encoding: UTF-8
 module Axlsx
   # a Pic object represents an image in your worksheet
   # Worksheet#add_image is the recommended way to manage images in your sheets

data/lib/axlsx/drawing/picture_locking.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # The picture locking class defines the locking properties for pictures in your workbook. 
   class PictureLocking

data/lib/axlsx/drawing/pie_3D_chart.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
 
 

data/lib/axlsx/drawing/pie_series.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A PieSeries defines the data and labels and explosion for pie charts series.
   # @note The recommended way to manage series is to use Chart#add_series

data/lib/axlsx/drawing/scaling.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # The Scaling class defines axis scaling
   class Scaling

data/lib/axlsx/drawing/ser_axis.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   #A SerAxis object defines a series axis
   class SerAxis < Axis

data/lib/axlsx/drawing/series.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A Series defines the common series attributes and is the super class for all concrete series types.
   # @note The recommended way to manage series is to use Chart#add_series

data/lib/axlsx/drawing/series_title.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A series title is a Title with a slightly different serialization than chart titles.
   class SeriesTitle < Title

data/lib/axlsx/drawing/title.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A Title stores information about the title of a chart
   class Title

data/lib/axlsx/drawing/two_cell_anchor.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 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.

data/lib/axlsx/drawing/val_axis.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # the ValAxis class defines a chart value axis.
   class ValAxis < Axis

data/lib/axlsx/drawing/val_axis_data.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # The ValAxisData class manages the values for a chart value series.
   class ValAxisData < CatAxisData

data/lib/axlsx/drawing/view_3D.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # 3D attributes for a chart.
   class View3D

data/lib/axlsx/package.rb

@@ -1,10 +1,10 @@
-# -*- coding: utf-8 -*-
+# encoding: 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
 
-    # plain text password
+    
     # provides access to the app doc properties for this package
     # see App
     attr_reader :app
@@ -17,14 +17,31 @@ 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 [Boolean] :use_shared_strings This is passed to the workbook to specify that shared strings should be used when serializing the package.
     # @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
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
       yield self if block_given?
     end
 
+    # Shortcut to specify that the workbook should use shared strings
+    # @see Workbook#use_shared_strings
+    def use_shared_strings=(v) 
+      Axlsx::validate_boolean(v); 
+      workbook.use_shared_strings = v
+    end
+
+    # Shortcut to determine if the workbook is configured to use shared strings
+    # @see Workbook#use_shared_strings
+    def use_shared_strings
+      workbook.use_shared_strings
+    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.
@@ -57,6 +74,7 @@ module Axlsx
     #
     # @param [File] output The file you want to serialize your package to
     # @param [Boolean] confirm_valid Validate the package prior to serialization.
+    # @option options stream indicates if we should be writing to a stream or a file. True for stream, nil for file
     # @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. 
@@ -70,26 +88,28 @@ module Axlsx
     #   # 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
+        write_parts(zip)
       end
       true
     end
+
+
+    # Serialize your workbook to a StringIO instance
+    # @param [Boolean] confirm_valid Validate the package prior to serialization.
+    # @return [StringIO|Boolean] False if confirm_valid and validation errors exist. rewound string IO if not.
+    def to_stream(confirm_valid=false)
+      return false unless !confirm_valid || self.validate.empty?
+      zip = write_parts(Zip::ZipOutputStream.new("streamed", true))
+      stream = zip.close_buffer
+      stream.rewind
+      stream
+    end
     
     # Encrypt the package into a CFB using the password provided
+    # This is not ready yet
     def encrypt(file_name, password)      
+      return false
       moc = MsOffCrypto.new(file_name, password)
       moc.save    
     end
@@ -117,6 +137,26 @@ module Axlsx
 
     private 
 
+    # Writes the package parts to a zip archive.
+    # @param [Zip::ZipOutputStream] zip
+    # @return [Zip::ZipOutputStream]
+    def write_parts(zip)
+      p = parts
+        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
+      zip
+    end
+
     # 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
@@ -143,6 +183,10 @@ module Axlsx
         @parts << {:entry => "xl/#{image.pn}", :path => image.image_src}
       end
 
+      if use_shared_strings
+        @parts << {:entry => "xl/#{SHARED_STRINGS_PN}", :doc => workbook.shared_strings.to_xml, :schema => SML_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}        
@@ -195,6 +239,10 @@ module Axlsx
              end
         c_types << Axlsx::Default.new(:ContentType => ct, :Extension => ext )
       end
+      if use_shared_strings
+        c_types << Axlsx::Override.new(:PartName => "/xl/#{SHARED_STRINGS_PN}",
+                                       :ContentType => SHARED_STRINGS_CT)
+      end
       c_types
     end