Class: Workbook::Book

Inherits:
Array
  • Object
show all
Includes:
Modules::BookDiffSort, Readers::CsvReader, Readers::OdsReader, Readers::TxtReader, Readers::XlsReader, Readers::XlsShared, Readers::XlsxReader, Writers::HtmlWriter, Writers::XlsWriter, Writers::XlsxWriter
Defined in:
lib/workbook/book.rb

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

#extract_xlsx_backgrounds, #extract_xlsx_number_formats, #load_xlsm, #load_xlsx, #pad_xlsx_row, #parse_shared_string_file, #parse_xlsx, #parse_xlsx_cell, #parse_xlsx_column, #parse_xlsx_fonts, #parse_xlsx_row, #parse_xlsx_sheet, #parse_xlsx_styles

Methods included from Readers::XlsShared

#html_color_to_xls_color, #ms_formatting_to_strftime, #num_fmt_id_to_ms_formatting, #strftime_to_ms_format, #xls_number_to_date, #xls_number_to_time

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, #parse_xls_cell, #parse_xls_format, #parse_xls_row

Methods included from Writers::HtmlWriter

#to_html, #write_to_html

Methods included from Writers::XlsxWriter

#format_to_xlsx_format, #formats_to_xlsx_format, #init_xlsx_spreadsheet_template, #make_sure_f_is_a_workbook_format, #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 = nil) ⇒ Workbook::Book

Parameters:

  • sheet (Workbook::Sheet, Array) (defaults to: nil) —

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



54
55
56
57
58
59
60
 
# 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

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:



211
212
213
214
215
 
# 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 = {}) ⇒ 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:



222
223
224
225
226
 
# 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

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:



95
96
97
98
99
 
# 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) ⇒ Object

Create or open the existing sheet at an index value

Parameters:

  • index (Integer) —

    the index of the sheet



198
199
200
201
202
203
 
# 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) ⇒ String

Returns The file extension.

Parameters:

  • filename (String, File) —

    The full filename, or path

Returns:

  • (String) —

    The file extension



178
179
180
181
182
 
# 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? ⇒ Boolean

If the first sheet has any contents

Returns:

  • (Boolean) —

    returns true if the first sheet has contents



113
114
115
 
# File 'lib/workbook/book.rb', line 113

def has_contents?
  sheet.has_contents?
end

#import(filename, extension = nil, options = {}) ⇒ 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:



122
123
124
125
126
127
128
129
 
# 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 = {}) ⇒ 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:



136
137
138
139
140
 
# 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 = {}) ⇒ 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’)



146
147
148
149
150
 
# 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) ⇒ Object

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

Parameters:



87
88
89
90
 
# 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 = {}) ⇒ 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) 


188
189
190
191
192
193
 
# 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 ⇒ Workbook::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



105
106
107
108
 
# File 'lib/workbook/book.rb', line 105

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

#template ⇒ Workbook::Template

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

Returns:

  • (Workbook::Template) —

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



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

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) 


68
69
70
71
 
# 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) ⇒ Object

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

Parameters:

  • text (String) —

    a string to convert



165
166
167
168
169
170
171
172
173
 
# 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 ⇒ String

The title of the workbook

Returns:

  • (String) —

    the title of the workbook



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

def title
  (defined?(@title) and !@title.nil?) ? @title : "untitled document"
end

#title=(t) ⇒ Object 



80
81
82
 
# File 'lib/workbook/book.rb', line 80

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



156
157
158
159
 
# File 'lib/workbook/book.rb', line 156

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