axlsx 1.2.0 → 2.0.0

data/lib/axlsx/workbook/worksheet/worksheet.rb

@@ -3,12 +3,14 @@ module Axlsx
 
   # The Worksheet class represents a worksheet in the workbook.
   class Worksheet
+    include Axlsx::OptionsParser
 
     # definition of characters which are less than the maximum width of 0-9 in the default font for use in String#count.
     # This is used for autowidth calculations
     # @return [String]
     def self.thin_chars
-      @thin_chars ||= "^.acefijklrstxyzFIJL()-"
+      # removed 'e' and 'y' from this list - as a GUESS
+      @thin_chars ||= "^.acfijklrstxzFIJL()-"
     end
 
     # Creates a new worksheet.
@@ -17,16 +19,15 @@ module Axlsx
     # @option options [String] name The name of this worksheet.
     # @option options [Hash] page_margins A hash containing page margins for this worksheet. @see PageMargins
     # @option options [Hash] print_options A hash containing print options for this worksheet. @see PrintOptions
+    # @option options [Hash] header_footer A hash containing header/footer options for this worksheet. @see HeaderFooter
     # @option options [Boolean] show_gridlines indicates if gridlines should be shown for this sheet.
     def initialize(wb, options={})
       self.workbook = wb
-      @workbook.worksheets << self
       @sheet_protection = nil
 
       initialize_page_options(options)
-      options.each do |o|
-        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
-      end
+      parse_options options
+      @workbook.worksheets << self
     end
 
     # Initalizes page margin, setup and print options
@@ -35,6 +36,9 @@ module Axlsx
       @page_margins = PageMargins.new options[:page_margins] if options[:page_margins]
       @page_setup = PageSetup.new options[:page_setup]  if options[:page_setup]
       @print_options = PrintOptions.new options[:print_options] if options[:print_options]
+      @header_footer = HeaderFooter.new options[:header_footer] if options[:header_footer]
+      @row_breaks = RowBreaks.new
+      @col_breaks = ColBreaks.new
     end
 
     # The name of the worksheet
@@ -43,6 +47,12 @@ module Axlsx
       @name ||=  "Sheet" + (index+1).to_s
     end
 
+    # The sheet calculation properties
+    # @return [SheetCalcPr]
+    def sheet_calc_pr
+      @sheet_calc_pr ||= SheetCalcPr.new
+    end
+
     # The sheet protection object for this workbook
     # @return [SheetProtection]
     # @see SheetProtection
@@ -61,6 +71,15 @@ module Axlsx
       @sheet_view
     end
 
+    # The sheet format pr for this worksheet
+    # @return [SheetFormatPr]
+    # @see [SheetFormatPr]
+    def sheet_format_pr
+      @sheet_format_pr ||= SheetFormatPr.new
+      yeild @sheet_format_pr if block_given?
+      @sheet_format_pr
+    end
+
     # The workbook that owns this worksheet
     # @return [Workbook]
     attr_reader :workbook
@@ -70,7 +89,35 @@ module Axlsx
     def tables
       @tables ||=  Tables.new self
     end
-    
+
+    # The pivot tables in this worksheet
+    # @return [Array] of Table
+    def pivot_tables
+      @pivot_tables ||=  PivotTables.new self
+    end
+
+    # A collection of column breaks added to this worksheet
+    # @note Please do not use this directly. Instead use
+    # add_page_break
+    # @see Worksheet#add_page_break
+    def col_breaks
+      @col_breaks ||= ColBreaks.new
+    end
+
+    # A collection of row breaks added to this worksheet
+    # @note Please do not use this directly. Instead use
+    # add_page_break
+    # @see Worksheet#add_page_break
+    def row_breaks
+      @row_breaks ||= RowBreaks.new
+    end
+
+    # A typed collection of hyperlinks associated with this worksheet
+    # @return [WorksheetHyperlinks]
+    def hyperlinks
+      @hyperlinks ||= WorksheetHyperlinks.new self
+    end
+
     # The a shortcut to the worksheet_comments list of comments
     # @return [Array|SimpleTypedList]
     def comments
@@ -85,15 +132,20 @@ module Axlsx
       @rows ||=  SimpleTypedList.new Row
     end
 
-    # returns the sheet data as columnw
-    def cols
-      @rows.transpose
+    # returns the sheet data as columns
+    # If you pass a block, it will be evaluated whenever a row does not have a
+    # cell at a specific index. The block will be called with the row and column
+    # index in the missing cell was found.
+    # @example
+    #     cols { |row_index, column_index| p "warn - row #{row_index} is does not have a cell at #{column_index}
+    def cols(&block)
+      @rows.transpose(&block)
     end
 
-    # An range that excel will apply an autfilter to "A1:B3"
+    # An range that excel will apply an auto-filter to "A1:B3"
     # This will turn filtering on for the cells in the range.
-    # The first row is considered the header, while subsequent rows are considerd to be data.
-    # @return String 
+    # The first row is considered the header, while subsequent rows are considered to be data.
+    # @return String
     def auto_filter
       @auto_filter ||= AutoFilter.new self
     end
@@ -182,6 +234,21 @@ module Axlsx
       @print_options
     end
 
+    # Options for headers and footers.
+    # @example
+    #   wb = Axlsx::Package.new.workbook
+    #   # would generate something like: "file.xlsx : sheet_name 2 of 7 date with timestamp"
+    #   header = {:different_odd_ => false, :odd_header => "&L&F : &A&C&Pof%N%R%D %T"}
+    #   ws = wb.add_worksheet :header_footer => header
+    #
+    # @see HeaderFooter#initialize
+    # @return [HeaderFooter]
+    def header_footer
+      @header_footer ||= HeaderFooter.new
+      yield @header_footer if block_given?
+      @header_footer
+    end
+
     # convinience method to access all cells in this worksheet
     # @return [Array] cells
     def cells
@@ -226,7 +293,7 @@ module Axlsx
     # Indicates if gridlines should be shown in the sheet.
     # This is true by default.
     # @return [Boolean]
-    # @deprecated Use {SheetView#show_grid_lines=} instead.
+    # @deprecated Use SheetView#show_grid_lines= instead.
     def show_gridlines=(v)
       warn('axlsx::DEPRECIATED: Worksheet#show_gridlines= has been depreciated. This value can be set over SheetView#show_grid_lines=.')
       Axlsx::validate_boolean v
@@ -235,7 +302,7 @@ module Axlsx
 
     # @see selected
     # @return [Boolean]
-    # @deprecated Use {SheetView#tab_selected=} instead.
+    # @deprecated Use SheetView#tab_selected= instead.
     def selected=(v)
       warn('axlsx::DEPRECIATED: Worksheet#selected= has been depreciated. This value can be set over SheetView#tab_selected=.')
       Axlsx::validate_boolean v
@@ -244,7 +311,7 @@ module Axlsx
 
     # Indicates if the worksheet should show gridlines or not
     # @return Boolean
-    # @deprecated Use {SheetView#show_grid_lines} instead.
+    # @deprecated Use SheetView#show_grid_lines instead.
     def show_gridlines
       warn('axlsx::DEPRECIATED: Worksheet#show_gridlines has been depreciated. This value can get over SheetView#show_grid_lines.')
       sheet_view.show_grid_lines
@@ -254,7 +321,7 @@ module Axlsx
     # It is possible to have more than one worksheet selected, however it might cause issues
     # in some older versions of excel when using copy and paste.
     # @return Boolean
-    # @deprecated Use {SheetView#tab_selected} instead.
+    # @deprecated Use SheetView#tab_selected instead.
     def selected
       warn('axlsx::DEPRECIATED: Worksheet#selected has been depreciated. This value can get over SheetView#tab_selected.')
       sheet_view.tab_selected
@@ -269,7 +336,7 @@ module Axlsx
 
     # The name of the worksheet
     # The name of a worksheet must be unique in the workbook, and must not exceed 31 characters
-    # @param [String] name 
+    # @param [String] name
     def name=(name)
       validate_sheet_name name
       @name=Axlsx::coder.encode(name)
@@ -283,6 +350,10 @@ module Axlsx
       auto_filter.range = v
     end
 
+    # Accessor for controlling whether leading and trailing spaces in cells are
+    # preserved or ignored. The default is to preserve spaces.
+    attr_accessor :preserve_spaces
+
     # The part name of this worksheet
     # @return [String]
     def pn
@@ -295,10 +366,11 @@ module Axlsx
       "#{WORKSHEET_RELS_PN % (index+1)}"
     end
 
-    # The relationship Id of thiw worksheet
+    # The relationship id of this worksheet.
     # @return [String]
+    # @see Relationship#Id
     def rId
-      "rId#{index+1}"
+      @workbook.relationships.for(self).Id
     end
 
     # The index of this worksheet in the owning Workbook's worksheets list.
@@ -377,7 +449,7 @@ module Axlsx
       cf = ConditionalFormatting.new( :sqref => cells )
       cf.add_rules rules
       conditional_formattings << cf
-      conditional_formattings      
+      conditional_formattings
     end
 
     # Add data validation to this worksheet.
@@ -391,6 +463,14 @@ module Axlsx
       data_validations << dv
     end
 
+    # Adds a new hyperlink to the worksheet
+    # @param [Hash] options for the hyperlink
+    # @see WorksheetHyperlink for a list of options
+    # @return [WorksheetHyperlink]
+    def add_hyperlink(options={})
+      hyperlinks.add(options)
+    end
+
     # Adds a chart to this worksheets drawing. This is the recommended way to create charts for your worksheet. This method wraps the complexity of dealing with ooxml drawing, anchors, markers graphic frames chart objects and all the other dirty details.
     # @param [Class] chart_type
     # @option options [Array] start_at
@@ -417,6 +497,12 @@ module Axlsx
       tables.last
     end
 
+    def add_pivot_table(ref, range, options={})
+      pivot_tables << PivotTable.new(ref, range, self, options)
+      yield pivot_tables.last if block_given?
+      pivot_tables.last
+    end
+
     # Shortcut to worsksheet_comments#add_comment
     def add_comment(options={})
       worksheet_comments.add_comment(options)
@@ -430,6 +516,24 @@ module Axlsx
       image
     end
 
+    # Adds a page break (row break) to the worksheet
+    # @param cell A Cell object or excel style string reference indicating where the break
+    # should be added to the sheet.
+    # @example
+    #   ws.add_page_break("A4")
+    def add_page_break(cell)
+      DataTypeValidator.validate "Worksheet#add_page_break cell", [String, Cell], cell
+      column_index, row_index = if cell.is_a?(String)
+          Axlsx.name_to_indices(cell)
+        else
+          cell.pos
+        end
+      if column_index > 0
+        col_breaks.add_break(:id => column_index)
+      end
+      row_breaks.add_break(:id => row_index)
+    end
+
     # This is a helper method that Lets you specify a fixed width for multiple columns in a worksheet in one go.
     # Axlsx is sparse, so if you have not set data for a column, you cannot set the width.
     # Setting a fixed column width to nil will revert the behaviour back to calculating the width for you on the next call to add_row.
@@ -477,22 +581,25 @@ module Axlsx
     # This intentionally does not use nokogiri for performance reasons
     # @return [String]
     def to_xml_string
+      auto_filter.apply if auto_filter.range
       str = '<?xml version="1.0" encoding="UTF-8"?>'
       str << worksheet_node
       serializable_parts.each do |item|
         item.to_xml_string(str) if item
       end
       str << '</worksheet>'
-      str.gsub(/[[:cntrl:]]/,'')
+      Axlsx::sanitize(str)
     end
 
     # The worksheet relationships. This is managed automatically by the worksheet
     # @return [Relationships]
     def relationships
       r = Relationships.new
-      r + [tables.relationships, 
-           worksheet_comments.relationships, 
-           worksheet_drawing.relationship].flatten.compact || []
+      r + [tables.relationships,
+           worksheet_comments.relationships,
+           hyperlinks.relationships,
+           worksheet_drawing.relationship,
+           pivot_tables.relationships].flatten.compact || []
       r
     end
 
@@ -531,25 +638,57 @@ module Axlsx
       @styles ||= self.workbook.styles
     end
 
+    # shortcut level to specify the outline level for a series of rows
+    # Oulining is what lets you add collapse and expand to a data set.
+    # @param [Integer] start_index The zero based index of the first row of outlining.
+    # @param [Integer] end_index The zero based index of  the last row to be outlined
+    # @param [integer] level The level of outline to apply
+    # @param [Integer] collapsed The initial collapsed state of the outline group
+    def outline_level_rows(start_index, end_index, level = 1, collapsed = true)
+      outline rows, (start_index..end_index), level, collapsed
+    end
+
+    # shortcut level to specify the outline level for a series of columns
+    # Oulining is what lets you add collapse and expand to a data set.
+    # @param [Integer] start_index The zero based index of the first column of outlining.
+    # @param [Integer] end_index The zero based index of  the last column to be outlined
+    # @param [integer] level The level of outline to apply
+    # @param [Integer] collapsed The initial collapsed state of the outline group
+    def outline_level_columns(start_index, end_index, level = 1, collapsed = true)
+      outline column_info, (start_index..end_index), level, collapsed
+    end
 
     private
 
+    def xml_space
+      workbook.xml_space
+    end
+
+    def outline(collection, range, level = 1, collapsed = true)
+       range.each do |index|
+        unless (item = collection[index]).nil?
+          item.outline_level = level
+          item.hidden = collapsed
+        end
+        sheet_view.show_outline_symbols = true
+      end
+    end
+
     def validate_sheet_name(name)
       DataTypeValidator.validate "Worksheet.name", String, name
       raise ArgumentError, (ERR_SHEET_NAME_TOO_LONG % name) if name.size > 31
-      raise ArgumentError, (ERR_SHEET_NAME_COLON_FORBIDDEN % name) if name.include? ':'
-      name = Axlsx::coder.encode(name) 
-      sheet_names = @workbook.worksheets.map { |s| s.name }
+      raise ArgumentError, (ERR_SHEET_NAME_CHARACTER_FORBIDDEN % name) if '[]*/\?:'.chars.any? { |char| name.include? char }
+      name = Axlsx::coder.encode(name)
+      sheet_names = @workbook.worksheets.reject { |s| s == self }.map { |s| s.name }
       raise ArgumentError, (ERR_DUPLICATE_SHEET_NAME % name) if sheet_names.include?(name)
     end
 
-
     def serializable_parts
-      [sheet_pr, dimension, sheet_view, column_info,
-       sheet_data, @sheet_protection, protected_ranges,
+      [sheet_pr, dimension, sheet_view, sheet_format_pr, column_info,
+       sheet_data, sheet_calc_pr, @sheet_protection, protected_ranges,
        auto_filter, merged_cells, conditional_formattings,
-       data_validations, print_options, page_margins,
-       page_setup, worksheet_drawing, worksheet_comments,
+       data_validations, hyperlinks, print_options, page_margins,
+       page_setup, header_footer, row_breaks, col_breaks, worksheet_drawing, worksheet_comments,
        tables]
     end
 
@@ -569,7 +708,7 @@ module Axlsx
     # @see Worksheet#protect_range
     # @return [SimpleTypedList] The protected ranges for this worksheet
     def protected_ranges
-      @protected_ranges ||= ProtectedRanges.new self 
+      @protected_ranges ||= ProtectedRanges.new self
       # SimpleTypedList.new ProtectedRange
     end
 
@@ -582,7 +721,7 @@ module Axlsx
     # data validations array
     # @return [Array]
     def data_validations
-      @data_validations ||= DataValidations.new self 
+      @data_validations ||= DataValidations.new self
     end
 
     # merged cells array
@@ -595,7 +734,7 @@ module Axlsx
     # Helper method for parsingout the root node for worksheet
     # @return [String]
     def worksheet_node
-      "<worksheet xmlns=\"%s\" xmlns:r=\"%s\">" % [XML_NS, XML_NS_R]
+       "<worksheet xmlns=\"%s\" xmlns:r=\"%s\" xml:space=\"#{xml_space}\">" % [XML_NS, XML_NS_R]
     end
 
     def sheet_data

data/lib/axlsx/workbook/worksheet/worksheet_comments.rb

@@ -40,10 +40,11 @@ module Axlsx
       !comments.empty?
     end
 
-    # The index in the worksheet's relationships for the VML drawing that will render the comments
-    # @return [Integer]
-    def index
-      worksheet.relationships.index { |r| r.Type == VML_DRAWING_R } + 1
+    # The relationship id of the VML drawing that will render the comments.
+    # @see Relationship#Id
+    # @return [String]
+    def drawing_rId
+      comments.relationships.find{ |r| r.Type == VML_DRAWING_R }.Id
     end
 
     # Seraalize the object
@@ -51,7 +52,7 @@ module Axlsx
     # @return [String]
     def to_xml_string(str = '')
       return unless has_comments?
-      str << "<legacyDrawing r:id='rId#{index}' />"
+      str << "<legacyDrawing r:id='#{drawing_rId}' />"
     end
   end
 end

data/lib/axlsx/workbook/worksheet/worksheet_drawing.rb

@@ -10,7 +10,7 @@ module Axlsx
     # @param [Worksheet] worksheet
     def initialize(worksheet)
       raise ArgumentError, 'you must provide a worksheet' unless worksheet.is_a?(Worksheet)
-      @worksheet = worksheet      
+      @worksheet = worksheet
       @drawing = nil
     end
 
@@ -41,24 +41,18 @@ module Axlsx
       @drawing.is_a? Drawing
     end
 
-    # The relationship required by this object
+    # The relationship instance for this drawing.
     # @return [Relationship]
     def relationship
       return unless has_drawing?
-      Relationship.new(DRAWING_R, "../#{drawing.pn}") 
-    end
-
-    # returns the index of the worksheet releationship that defines this drawing.
-    # @return [Integer]
-    def index
-       worksheet.relationships.index{ |r| r.Type == DRAWING_R } +1 
+      Relationship.new(self, DRAWING_R, "../#{drawing.pn}") 
     end
 
     # Serialize the drawing for the worksheet
     # @param [String] str
     def to_xml_string(str = '')
       return unless has_drawing? 
-      str << "<drawing r:id='rId#{index}'/>"
+      str << "<drawing r:id='#{relationship.Id}'/>"
     end
   end
 end

data/lib/axlsx/workbook/worksheet/worksheet_hyperlink.rb

@@ -0,0 +1,74 @@
+module Axlsx
+
+  # A worksheet hyperlink object. Note that this is not the same as a drawing hyperlink object.
+  class WorksheetHyperlink
+
+    include Axlsx::OptionsParser
+    include Axlsx::Accessors
+    include Axlsx::SerializedAttributes
+    # Creates a new hyperlink object.
+    # @note the preferred way to add hyperlinks to your worksheet is the Worksheet#add_hyperlink method
+    # @param [Worksheet] worksheet the Worksheet that owns this hyperlink
+    # @param [Hash] options options to use when creating this hyperlink
+    # @option [String] display Display string, if different from string in string table. This is a property on the hyperlink object, but does not need to appear in the spreadsheet application UI.
+    # @option [String] location Location within target. If target is a workbook (or this workbook) this shall refer to a sheet and cell or a defined name. Can also be an HTML anchor if target is HTML file.
+    # @option [String] tooltip The tip to display when the user positions the mouse cursor over this hyperlink
+    # @option [Symbol] target This is :external by default. If you set it to anything else, the location is interpreted to be the current workbook.
+    # @option [String|Cell] ref The location of this hyperlink in the worksheet
+    def initialize(worksheet, options={})
+      DataTypeValidator.validate "Hyperlink.worksheet", [Worksheet], worksheet
+      @worksheet = worksheet
+      @target = :external
+      parse_options options
+      yield self if block_given?
+    end
+
+    string_attr_accessor :display, :location, :tooltip
+
+    serializable_attributes :display, :tooltip, :ref
+
+    #Cell location of hyperlink on worksheet.
+    # @return [String]
+    attr_reader :ref
+
+    # Sets the target for this hyperlink. Anything other than :external instructs the library to treat the location as an in-workbook reference.
+    # @param [Symbol] target
+    def target=(target)
+      @target = target
+    end
+
+    # Sets the cell location of this hyperlink in the worksheet
+    # @param [String|Cell] cell_reference The string reference or cell that defines where this hyperlink shows in the worksheet.
+    def ref=(cell_reference)
+      cell_reference = cell_reference.r if cell_reference.is_a?(Cell)
+      Axlsx::validate_string cell_reference
+      @ref = cell_reference
+    end
+
+    # The relationship instance for this hyperlink.
+    # A relationship is only required if `@target` is `:external`. If not, this method will simply return `nil`.
+    # @see #target=
+    # @return [Relationship]
+    def relationship
+      return unless @target == :external
+      Relationship.new(self, HYPERLINK_R, location, :target_mode => :External)
+    end
+
+    # Seralize the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str='')
+      str << '<hyperlink '
+      serialized_attributes str, location_or_id
+      str << '/>'
+    end
+
+    # The values to be used in serialization based on the target.
+    # location should only be specified for non-external targets.
+    # r:id should only be specified for external targets.
+    # @return [Hash]
+    def location_or_id
+      @target == :external ?  { :"r:id" => relationship.Id } : { :location => Axlsx::coder.encode(location) }
+    end
+  end
+end

data/lib/axlsx/workbook/worksheet/worksheet_hyperlinks.rb

@@ -0,0 +1,38 @@
+module Axlsx
+
+  #A collection of hyperlink objects for a worksheet
+  class WorksheetHyperlinks < SimpleTypedList
+
+    # Creates a new Hyperlinks collection
+    # @param [Worksheet] worksheet the worksheet that owns these hyperlinks
+    def initialize(worksheet)
+      DataTypeValidator.validate "Hyperlinks.worksheet", [Worksheet], worksheet
+      @worksheet = worksheet
+      super WorksheetHyperlink
+    end
+
+    # Creates and adds a new hyperlink based on the options provided
+    # @see WorksheetHyperlink#initialize
+    # @return [WorksheetHyperlink]
+    def add(options)
+      @list << WorksheetHyperlink.new(@worksheet, options)
+      @list.last
+    end
+
+    # The relationships required by this collection's hyperlinks
+    # @return Array
+    def relationships
+      return [] if empty?
+      map { |hyperlink| hyperlink.relationship }
+    end
+
+    # seralize the collection of hyperlinks
+    # @return [String]
+    def to_xml_string(str='')
+      return if empty?
+      str << '<hyperlinks>'
+      @list.each { |hyperlink| hyperlink.to_xml_string(str) }
+      str << '</hyperlinks>'
+    end
+  end
+end

data/lib/axlsx.rb

@@ -5,7 +5,9 @@ require 'axlsx/version.rb'
 require 'axlsx/util/simple_typed_list.rb'
 require 'axlsx/util/constants.rb'
 require 'axlsx/util/validators.rb'
-
+require 'axlsx/util/accessors.rb'
+require 'axlsx/util/serialized_attributes'
+require 'axlsx/util/options_parser'
 # to be included with parsable intitites.
 #require 'axlsx/util/parser.rb'
 
@@ -37,15 +39,25 @@ if !Object.respond_to?(:instance_values)
   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.
+# 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
 
   # determines the cell range for the items provided
   def self.cell_range(cells, absolute=true)
     return "" unless cells.first.is_a? Cell
-    sort_cells(cells)
+    cells = sort_cells(cells)
     reference = "#{cells.first.reference(absolute)}:#{cells.last.reference(absolute)}"
-    absolute ? "'#{cells.first.row.worksheet.name}'!#{reference}" : reference
+    if absolute
+      escaped_name = cells.first.row.worksheet.name.gsub "'", "''"
+      "'#{escaped_name}'!#{reference}"
+    else
+      reference
+    end
   end
 
   # sorts the array of cells provided to start from the minimum x,y to
@@ -61,10 +73,11 @@ module Axlsx
   def self.coder
     @@coder ||= ::HTMLEntities.new
   end
-  
+
   # returns the x, y position of a cell
   def self.name_to_indices(name)
     raise ArgumentError, 'invalid cell name' unless name.size > 1
+    # capitalization?!?
     v = name[/[A-Z]+/].reverse.chars.reduce({:base=>1, :i=>0}) do  |val, c|
       val[:i] += ((c.bytes.first - 64) * val[:base]); val[:base] *= 26; val
     end
@@ -91,12 +104,49 @@ module Axlsx
     Axlsx::col_ref(c_index).to_s << (r_index+1).to_s
   end
 
+  # Creates an array of individual cell references based on an excel reference range.
+  # @param [String] range A cell range, for example A1:D5
+  # @return [Array]
+  def self.range_to_a(range)
+    range.match(/^(\w+?\d+)\:(\w+?\d+)$/)
+    start_col, start_row = name_to_indices($1)
+    end_col,   end_row   = name_to_indices($2)
+    (start_row..end_row).to_a.map do |row_num|
+      (start_col..end_col).to_a.map do |col_num|
+        "#{col_ref(col_num)}#{row_num+1}"
+      end
+    end
+  end
+
   # performs the increadible feat of changing snake_case to CamelCase
   # @param [String] s The snake case string to camelize
   # @return [String]
   def self.camel(s="", all_caps = true)
+    s = s.to_s
     s = s.capitalize if all_caps
     s.gsub(/_(.)/){ $1.upcase }
   end
 
+    # returns the provided string with all invalid control charaters
+    # removed.
+    # @param [String] str The sting to process
+    # @return [String]
+    def self.sanitize(str)
+      str.gsub(CONTROL_CHAR_REGEX, '')
+    end
+
+
+  # Instructs the serializer to not try to escape cell value input. 
+  # This will give you a huge speed bonus, but if you content has <, > or other xml character data
+  # the workbook will be invalid and excel will complain.
+  def self.trust_input
+    @trust_input ||= false
+  end
+
+  # @param[Boolean] trust_me A boolean value indicating if the cell value content is to be trusted
+  # @return [Boolean]
+  # @see Axlsx::trust_input
+  def self.trust_input=(trust_me)
+    @trust_input = trust_me
+  end
 end