Class: Workbook::Book

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

Overview

The Book class is the container of sheets. It can be inialized by either the standard initalizer or the open method. The Book class can also keep a reference to a template class, storing shared formatting options.

Constant Summary

Constant Summary

Constants included from Readers::XlsShared

Readers::XlsShared::XLS_COLORS

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

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_xlsx, #parse_xlsx

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::XlsWriter

#format_to_xls_format, #html_color_to_xls_color, #init_spreadsheet_template, #strftime_to_ms_format, #to_xls, #write_to_xls, #xls_sheet, #xls_template

Constructor Details

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

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



30
31
32
33
34
35
36
 
# File 'lib/workbook/book.rb', line 30

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

Instance Attribute Details

- (Workbook::Format) template

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



39
40
41
 
# File 'lib/workbook/book.rb', line 39

def template
  @template
end

- (String) title

The title of the workbook

Returns:

  • (String) —

    the title of the workbook



52
53
54
 
# File 'lib/workbook/book.rb', line 52

def title
  @title
end

Class Method Details

+ (Workbook::Book) open(filename, extension = nil)

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:



150
151
152
153
154
 
# File 'lib/workbook/book.rb', line 150

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

+ (Workbook::Book) read(stringio_or_string, filetype)

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:



161
162
163
164
165
 
# File 'lib/workbook/book.rb', line 161

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

Instance Method Details

- (Object) create_or_open_sheet_at(index)

Create or open the existing sheet at an index value

Parameters:

  • index (Integer) —

    the index of the sheet



181
182
183
184
185
186
 
# File 'lib/workbook/book.rb', line 181

def create_or_open_sheet_at index
  s = self[index]
  s = self[index] = Workbook::Sheet.new if s == nil
  s.book = self
  s
end

- (String) file_extension(filename)

The file extension

Parameters:

  • filename (String) —

    The full filename, or path

Returns:

  • (String) —

    The file extension



141
142
143
 
# File 'lib/workbook/book.rb', line 141

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

- (Boolean) has_contents?

If the first sheet has any contents

Returns:

  • (Boolean) —

    returns true if the first sheet has contents



74
75
76
 
# File 'lib/workbook/book.rb', line 74

def has_contents?
  sheet.has_contents?
end

- (Workbook::Book) open(filename, extension = nil)

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:



83
84
85
86
87
88
89
90
 
# File 'lib/workbook/book.rb', line 83

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

- (Workbook::Book) open_binary(filename, extension = nil)

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:



97
98
99
100
101
 
# File 'lib/workbook/book.rb', line 97

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

- (Object) open_text(filename, extension = nil)

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’)



107
108
109
110
111
112
113
 
# File 'lib/workbook/book.rb', line 107

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

- (Object) push(sheet = Workbook::Sheet.new)

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

Parameters:



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

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

- (Object) read(stringio_or_string, filetype)

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) 


171
172
173
174
175
176
 
# File 'lib/workbook/book.rb', line 171

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

- (Workbook::Sheet) 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



66
67
68
69
 
# File 'lib/workbook/book.rb', line 66

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

- (Object) text_to_utf8(text)

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

Parameters:

  • text (String) —

    a string to convert



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/workbook/book.rb', line 119

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