class Workbook::Book

Public Class Methods

new(sheet=nil) click to toggle source

@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
open(filename, extension=nil) click to toggle source

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
read(stringio_or_string, filetype, options={}) click to toggle source

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

<<(sheet=Workbook::Sheet.new) click to toggle source

<< (like in array) a sheet to the workbook (parameter is optional, default is a new sheet)

@param [Workbook::Sheet] sheet

Calls superclass method
# 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_sheet_at(index) click to toggle source

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
file_extension(filename) click to toggle source

@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
has_contents?() click to toggle source

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
import(filename, extension=nil, options={}) click to toggle source

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_binary(filename, extension=nil, options={}) click to toggle source

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_text(filename, extension=nil, options={}) click to toggle source

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(sheet=Workbook::Sheet.new) click to toggle source

Push (like in array) a sheet to the workbook (parameter is optional, default is a new sheet)

@param [Workbook::Sheet] sheet

Calls superclass method
# File lib/workbook/book.rb, line 87
def push sheet=Workbook::Sheet.new
  super(sheet)
  sheet.book=(self)
end
read(stringio_or_string, filetype, options={}) click to toggle source

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() click to toggle source

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
template() click to toggle source

@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
template=(template) click to toggle source

@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
text_to_utf8(text) click to toggle source

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
title() click to toggle source

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
title=(t) click to toggle source
# File lib/workbook/book.rb, line 80
def title= t
  @title = t
end
write(filename, options={}) click to toggle source

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