Class: Workbook::Book

Constant Summary

Constant Summary

Constants included from Readers::XlsShared

Readers::XlsShared::XLS_COLORS

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Modules::BookDiffSort

#diff, included

Methods included from Readers::TxtReader

#load_txt, #parse_txt

Methods included from Readers::CsvReader

#csv_lib, #load_csv, #parse_csv

Methods included from Readers::XlsxReader

#load_xlsm, #load_xlsx, #parse_xlsx

Methods included from Readers::XlsShared

#html_color_to_xls_color, #ms_formatting_to_strftime, #strftime_to_ms_format

Methods included from Readers::OdsReader

#get_column_count, #get_repeat, #load_ods, #parse_local_cell, #parse_local_row, #parse_local_table, #parse_local_value, #parse_ods, #parse_ods_style, #set_cell_attributes, #set_format_property

Methods included from Readers::XlsReader

#load_xls, #parse_xls

Methods included from Writers::HtmlWriter

#to_html, #write_to_html

Methods included from Writers::XlsxWriter

#init_xlsx_spreadsheet_template, #stream_xlsx, #to_xlsx, #write_to_xlsx, #xlsx_sheet, #xlsx_template

Methods included from Writers::XlsWriter

#format_to_xls_format, #init_spreadsheet_template, #parse_font_family, #to_xls, #write_to_xls, #xls_sheet, #xls_template

Constructor Details

#initialize(sheet = Workbook::Sheet.new([], self, options={})) ⇒ Workbook::Book

Parameters:

  • sheet (Workbook::Sheet, Array) (defaults to: Workbook::Sheet.new([], self, options={}))

    create a new workbook based on an existing sheet, or initialize a sheet based on the array



50
51
52
53
54
55
56
# File 'lib/workbook/book.rb', line 50

def initialize sheet=Workbook::Sheet.new([], self, options={})
  if sheet.is_a? Workbook::Sheet
    self.push sheet
  else
    self.push Workbook::Sheet.new(sheet, self, options)
  end
end

Class Method Details

.open(filename, extension = nil) ⇒ Workbook::Book

Create an instance from a file, using open.

Parameters:

  • filename (String)

    of the document

  • extension (String) (defaults to: nil)

    of the document (not required). The parser used is based on the extension of the file, this option allows you to override the default.

Returns:



216
217
218
219
220
# File 'lib/workbook/book.rb', line 216

def open filename, extension=nil
  wb = self.new
  wb.open filename, extension
  return wb
end

.read(stringio_or_string, filetype) ⇒ Workbook::Book

Create an instance from the given stream or string, which should be in CSV or TXT format

Parameters:

  • stringio_or_string (StringIO)

    StringIO stream or String object, with data in CSV or TXT format

  • filetype (Symbol)

    (currently only :csv or :txt), indicating the format of the first parameter

Returns:



227
228
229
230
231
# File 'lib/workbook/book.rb', line 227

def read(stringio_or_string, filetype)
  wb = self.new
  wb.read(stringio_or_string, filetype)
  wb
end

Instance Method Details

#<<(sheet = Workbook::Sheet.new) ⇒ Object

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

Parameters:



91
92
93
94
95
# File 'lib/workbook/book.rb', line 91

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) ⇒ Object

Create or open the existing sheet at an index value

Parameters:

  • index (Integer)

    the index of the sheet



203
204
205
206
207
208
# File 'lib/workbook/book.rb', line 203

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) ⇒ String

Returns The file extension

Parameters:

  • filename (String, File)

    The full filename, or path

Returns:

  • (String)

    The file extension



185
186
187
# File 'lib/workbook/book.rb', line 185

def file_extension(filename)
  File.extname(filename).gsub('.','').downcase if filename
end

#has_contents?Boolean

If the first sheet has any contents

Returns:

  • (Boolean)

    returns true if the first sheet has contents



109
110
111
# File 'lib/workbook/book.rb', line 109

def has_contents?
  sheet.has_contents?
end

#open(filename, extension = nil) ⇒ Workbook::Book

Loads an external file into an existing worbook

Parameters:

  • filename (String)

    a string with a reference to the file to be opened

  • extension (String) (defaults to: nil)

    an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')

Returns:



118
119
120
121
122
123
124
125
# File 'lib/workbook/book.rb', line 118

def open filename, extension=nil
  extension = file_extension(filename) unless extension
  if ['txt','csv','xml'].include?(extension)
    open_text filename, extension
  else
    open_binary filename, extension
  end
end

#open_binary(filename, extension = nil) ⇒ Workbook::Book

Open the file in binary, read-only mode, do not read it, but pas it throug to the extension determined loaded

Parameters:

  • filename (String)

    a string with a reference to the file to be opened

  • extension (String) (defaults to: nil)

    an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')

Returns:



132
133
134
135
136
# File 'lib/workbook/book.rb', line 132

def open_binary filename, extension=nil
  extension = file_extension(filename) unless extension
  f = File.open(filename,'rb')
  send("load_#{extension}".to_sym,f)
end

#open_text(filename, extension = nil) ⇒ Object

Open the file in non-binary, read-only mode, read it and parse it to UTF-8

Parameters:

  • filename (String)

    a string with a reference to the file to be opened

  • extension (String) (defaults to: nil)

    an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')



142
143
144
145
146
147
148
# File 'lib/workbook/book.rb', line 142

def open_text filename, extension=nil
  extension = file_extension(filename) unless extension
  f = File.open(filename,'r')
  t = f.read
  t = text_to_utf8(t)
  send("load_#{extension}".to_sym,t)
end

#push(sheet = Workbook::Sheet.new) ⇒ Object

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

Parameters:



83
84
85
86
# File 'lib/workbook/book.rb', line 83

def push sheet=Workbook::Sheet.new
  super(sheet)
  sheet.book=(self)
end

#read(stringio_or_string, filetype) ⇒ Object

Load the CSV data contained in the given StringIO or String object

Parameters:

  • stringio_or_string (StringIO)

    StringIO stream or String object, with data in CSV format

  • filetype (Symbol)

    (currently only :csv or :txt), indicating the format of the first parameter

Raises:

  • (ArgumentError)


193
194
195
196
197
198
# File 'lib/workbook/book.rb', line 193

def read(stringio_or_string, filetype)
  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)
end

#sheetWorkbook::Sheet

Sheet returns the first sheet of a workbook, or an empty one.

Returns:

  • (Workbook::Sheet)

    The first sheet, and creates an empty one if one doesn't exists



101
102
103
104
# File 'lib/workbook/book.rb', line 101

def sheet
  push Workbook::Sheet.new unless first
  first
end

#templateWorkbook::Format

Returns the template describing how the document should be/is formatted

Returns:

  • (Workbook::Format)

    returns the template describing how the document should be/is formatted



59
60
61
# File 'lib/workbook/book.rb', line 59

def template
  @template ||= Workbook::Template.new
end

#template=(template) ⇒ Object

Parameters:

  • template (Workbook::Format)

    a template describing how the document should be/is formatted

Raises:

  • (ArgumentError)


64
65
66
67
# File 'lib/workbook/book.rb', line 64

def template= template
  raise ArgumentError, "format should be a Workboot::Format" unless template.is_a? Workbook::Template
  @template = template
end

#text_to_utf8(text) ⇒ Object

Helper method to convert text in a file to UTF-8

Parameters:

  • text (String)

    a string to convert



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
# File 'lib/workbook/book.rb', line 163

def text_to_utf8 text
  if RUBY_VERSION < '1.9'
    require 'rchardet'
    require 'iconv'
    detected_encoding = CharDet.detect(text)
    detected_encoding = detected_encoding['encoding']
    text = Iconv.conv("UTF-8//TRANSLIT//IGNORE",detected_encoding,text)
    text = text.gsub("\xEF\xBB\xBF", '') # removing the BOM...
  else
    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
  end
  return text
end

#titleString

The title of the workbook

Returns:

  • (String)

    the title of the workbook



72
73
74
# File 'lib/workbook/book.rb', line 72

def title
  @title ? @title : "untitled document"
end

#title=(t) ⇒ Object



76
77
78
# File 'lib/workbook/book.rb', line 76

def title= t
  @title = t
end

#write(filename, options = {}) ⇒ Object

Writes the book to a file. Filetype is based on the extension, but can be overridden

Parameters:

  • filename (String)

    a string with a reference to the file to be written to

  • options (Hash) (defaults to: {})

    depends on the writer chosen by the file's filetype



154
155
156
157
# File 'lib/workbook/book.rb', line 154

def write filename, options={}
  extension = file_extension(filename)
  send("write_to_#{extension}".to_sym, filename, options)
end