class Workbook::Book
Public Class Methods
@param [Workbook::Sheet, Array] sheet create a new workbook based on an existing sheet, or initialize a sheet based on the array @return [Workbook::Book]
# File lib/workbook/book.rb, line 54 def initialize sheet=nil if sheet.is_a? Workbook::Sheet self.push sheet elsif sheet self.push Workbook::Sheet.new(sheet, self, {}) end end
Create an instance from a file, using open.
@param [String] filename of the document @param [String] extension of the document (not required). The parser used is based on the extension of the file, this option allows you to override the default. @return [Workbook::Book] A new instance, based on the filename
# File lib/workbook/book.rb, line 211 def open filename, extension=nil wb = self.new wb.import filename, extension return wb end
Create an instance from the given stream or string, which should be in CSV or TXT format
@param [StringIO] stringio_or_string StringIO stream or String object, with data in CSV or TXT format @param [Symbol] filetype (currently only :csv or :txt), indicating the format of the first parameter @return [Workbook::Book] A new instance
# File lib/workbook/book.rb, line 222 def read stringio_or_string, filetype, options={} wb = self.new wb.read(stringio_or_string, filetype, options) wb end
Public Instance Methods
<< (like in array) a sheet to the workbook (parameter is optional, default is a new sheet)
@param [Workbook::Sheet] sheet
# File lib/workbook/book.rb, line 95 def << sheet=Workbook::Sheet.new sheet = Workbook::Sheet.new(sheet) unless sheet.is_a? Workbook::Sheet super(sheet) sheet.book=(self) end
Create or open the existing sheet at an index value
@param [Integer] index the index of the sheet
# File lib/workbook/book.rb, line 198 def create_or_open_sheet_at index s = self[index] s = self[index] = Workbook::Sheet.new if s == nil s.book = self s end
@param [String, File] filename The full filename, or path
@return [String] The file extension
# File lib/workbook/book.rb, line 178 def file_extension(filename) ext = File.extname(filename).gsub('.','').downcase if filename # for remote files which has asset id after extension ext.split('?')[0] end
If the first sheet has any contents
@return [Boolean] returns true if the first sheet has contents
# File lib/workbook/book.rb, line 113 def has_contents? sheet.has_contents? end
Loads an external file into an existing worbook
@param [String] filename a string with a reference to the file to be opened @param [String] extension an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls') @return [Workbook::Book] A new instance, based on the filename
# File lib/workbook/book.rb, line 122 def import filename, extension=nil, options={} extension = file_extension(filename) unless extension if ['txt','csv','xml'].include?(extension) open_text filename, extension, options else open_binary filename, extension, options end end
Open the file in binary, read-only mode, do not read it, but pas it throug to the extension determined loaded
@param [String] filename a string with a reference to the file to be opened @param [String] extension an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls') @return [Workbook::Book] A new instance, based on the filename
# File lib/workbook/book.rb, line 136 def open_binary filename, extension=nil, options={} extension = file_extension(filename) unless extension f = open(filename) send("load_#{extension}".to_sym, f, options) end
Open the file in non-binary, read-only mode, read it and parse it to UTF-8
@param [String] filename a string with a reference to the file to be opened @param [String] extension an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
# File lib/workbook/book.rb, line 146 def open_text filename, extension=nil, options={} extension = file_extension(filename) unless extension t = text_to_utf8(open(filename).read) send("load_#{extension}".to_sym, t, options) end
Push (like in array) a sheet to the workbook (parameter is optional, default is a new sheet)
@param [Workbook::Sheet] sheet
# File lib/workbook/book.rb, line 87 def push sheet=Workbook::Sheet.new super(sheet) sheet.book=(self) end
Load the CSV data contained in the given StringIO or String object
@param [StringIO] stringio_or_string StringIO stream or String object, with data in CSV format @param [Symbol] filetype (currently only :csv or :txt), indicating the format of the first parameter
# File lib/workbook/book.rb, line 188 def read(stringio_or_string, filetype, options={}) raise ArgumentError.new("The filetype parameter should be either :csv or :txt") unless [:csv, :txt].include?(filetype) t = stringio_or_string.respond_to?(:read) ? stringio_or_string.read : stringio_or_string.to_s t = text_to_utf8(t) send(:"parse_#{filetype}", t, options) end
Sheet
returns the first sheet of a workbook, or an empty one.
@return [Workbook::Sheet] The first sheet, and creates an empty one if one doesn't exists
# File lib/workbook/book.rb, line 105 def sheet push Workbook::Sheet.new unless first first end
@return [Workbook::Template] returns the template describing how the document should be/is formatted
# File lib/workbook/book.rb, line 63 def template @template ||= Workbook::Template.new end
@param [Workbook::Format] template a template describing how the document should be/is formatted
# File lib/workbook/book.rb, line 68 def template= template raise ArgumentError, "format should be a Workboot::Format" unless template.is_a? Workbook::Template @template = template end
Helper method to convert text in a file to UTF-8
@param [String] text a string to convert
# File lib/workbook/book.rb, line 165 def text_to_utf8 text unless text.valid_encoding? and text.encoding == "UTF-8" # TODO: had some ruby 1.9 problems with rchardet ... but ideally it or a similar functionality will be reintroduced source_encoding = text.valid_encoding? ? text.encoding : "US-ASCII" text = text.encode('UTF-8', source_encoding, {:invalid=>:replace, :undef=>:replace, :replace=>""}) text = text.gsub("\u0000","") # TODO: this cleanup of nil values isn't supposed to be needed... end text end
The title of the workbook
@return [String] the title of the workbook
# File lib/workbook/book.rb, line 76 def title (defined?(@title) and !@title.nil?) ? @title : "untitled document" end
# File lib/workbook/book.rb, line 80 def title= t @title = t end
Writes the book to a file. Filetype is based on the extension, but can be overridden
@param [String] filename a string with a reference to the file to be written to @param [Hash] options depends on the writer chosen by the file's filetype
# File lib/workbook/book.rb, line 156 def write filename, options={} extension = file_extension(filename) send("write_to_#{extension}".to_sym, filename, options) end