workbook 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. data/.yardoc/checksums +18 -0
  2. data/.yardoc/object_types +3 -0
  3. data/.yardoc/objects/root.dat +0 -0
  4. data/.yardoc/proxy_types +0 -0
  5. data/Gemfile.lock +1 -1
  6. data/{readme.markdown → README.md} +36 -10
  7. data/doc/RubyXL.html +128 -0
  8. data/doc/RubyXL/Cell.html +202 -0
  9. data/doc/RubyXL/Workbook.html +447 -0
  10. data/doc/Workbook.html +130 -0
  11. data/doc/Workbook/Book.html +1484 -0
  12. data/doc/Workbook/Cell.html +1402 -0
  13. data/doc/Workbook/Format.html +654 -0
  14. data/doc/Workbook/Modules.html +117 -0
  15. data/doc/Workbook/Modules/RawObjectsStorage.html +508 -0
  16. data/doc/Workbook/Modules/TableDiffSort.html +620 -0
  17. data/doc/Workbook/Modules/TypeParser.html +1012 -0
  18. data/doc/Workbook/Readers.html +117 -0
  19. data/doc/Workbook/Readers/CsvReader.html +262 -0
  20. data/doc/Workbook/Readers/TxtReader.html +238 -0
  21. data/doc/Workbook/Readers/XlsReader.html +362 -0
  22. data/doc/Workbook/Readers/XlsShared.html +189 -0
  23. data/doc/Workbook/Readers/XlsxReader.html +295 -0
  24. data/doc/Workbook/Row.html +1939 -0
  25. data/doc/Workbook/Sheet.html +528 -0
  26. data/doc/Workbook/Table.html +883 -0
  27. data/doc/Workbook/Template.html +639 -0
  28. data/doc/Workbook/Writers.html +117 -0
  29. data/doc/Workbook/Writers/CsvTableWriter.html +175 -0
  30. data/doc/Workbook/Writers/XlsWriter.html +865 -0
  31. data/doc/_index.html +336 -0
  32. data/doc/class_list.html +53 -0
  33. data/doc/css/common.css +1 -0
  34. data/doc/css/full_list.css +57 -0
  35. data/doc/css/style.css +328 -0
  36. data/doc/file.README.html +236 -0
  37. data/doc/file_list.html +55 -0
  38. data/doc/frames.html +28 -0
  39. data/doc/index.html +236 -0
  40. data/doc/js/app.js +214 -0
  41. data/doc/js/full_list.js +173 -0
  42. data/doc/js/jquery.js +4 -0
  43. data/doc/method_list.html +972 -0
  44. data/doc/top-level-namespace.html +112 -0
  45. data/lib/workbook/book.rb +38 -29
  46. data/lib/workbook/cell.rb +25 -0
  47. data/lib/workbook/format.rb +9 -2
  48. data/lib/workbook/modules/raw_objects_storage.rb +5 -0
  49. data/lib/workbook/modules/table_diff_sort.rb +8 -6
  50. data/lib/workbook/modules/type_parser.rb +16 -3
  51. data/lib/workbook/readers/xls_reader.rb +1 -70
  52. data/lib/workbook/readers/xls_shared.rb +75 -0
  53. data/lib/workbook/row.rb +89 -17
  54. data/lib/workbook/sheet.rb +26 -0
  55. data/lib/workbook/table.rb +20 -1
  56. data/lib/workbook/template.rb +12 -11
  57. data/lib/workbook/writers/xls_writer.rb +19 -77
  58. data/test/test_modules_table_diff_sort.rb +19 -6
  59. data/test/test_row.rb +54 -0
  60. data/test/test_sheet.rb +8 -0
  61. data/test/test_table.rb +22 -3
  62. data/test/test_writers_xls_writer.rb +3 -0
  63. data/workbook.gemspec +1 -1
  64. metadata +46 -3
data/doc/top-level-namespace.html ADDED
@@ -0,0 +1,112 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4
+ <head>
5
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6
+ <title>
7
+ Top Level Namespace
8
+
9
+ &mdash; Documentation by YARD 0.8.3
10
+
11
+ </title>
12
+
13
+ <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
14
+
15
+ <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
16
+
17
+ <script type="text/javascript" charset="utf-8">
18
+ hasFrames = window.top.frames.main ? true : false;
19
+ relpath = '';
20
+ framesUrl = "frames.html#!" + escape(window.location.href);
21
+ </script>
22
+
23
+
24
+ <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
25
+
26
+ <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
27
+
28
+
29
+ </head>
30
+ <body>
31
+ <div id="header">
32
+ <div id="menu">
33
+
34
+ <a href="_index.html">Index</a> &raquo;
35
+
36
+
37
+ <span class="title">Top Level Namespace</span>
38
+
39
+
40
+ <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
41
+ </div>
42
+
43
+ <div id="search">
44
+
45
+ <a class="full_list_link" id="class_list_link"
46
+ href="class_list.html">
47
+ Class List
48
+ </a>
49
+
50
+ <a class="full_list_link" id="method_list_link"
51
+ href="method_list.html">
52
+ Method List
53
+ </a>
54
+
55
+ <a class="full_list_link" id="file_list_link"
56
+ href="file_list.html">
57
+ File List
58
+ </a>
59
+
60
+ </div>
61
+ <div class="clear"></div>
62
+ </div>
63
+
64
+ <iframe id="search_frame"></iframe>
65
+
66
+ <div id="content"><h1>Top Level Namespace
67
+
68
+
69
+
70
+ </h1>
71
+
72
+ <dl class="box">
73
+
74
+
75
+
76
+
77
+
78
+
79
+
80
+
81
+ </dl>
82
+ <div class="clear"></div>
83
+
84
+ <h2>Defined Under Namespace</h2>
85
+ <p class="children">
86
+
87
+
88
+ <strong class="modules">Modules:</strong> <span class='object_link'><a href="RubyXL.html" title="RubyXL (module)">RubyXL</a></span>, <span class='object_link'><a href="Workbook.html" title="Workbook (module)">Workbook</a></span>
89
+
90
+
91
+
92
+
93
+ </p>
94
+
95
+
96
+
97
+
98
+
99
+
100
+
101
+
102
+
103
+ </div>
104
+
105
+ <div id="footer">
106
+ Generated on Thu Jan 17 13:15:56 2013 by
107
+ <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
108
+ 0.8.3 (ruby-1.8.7).
109
+ </div>
110
+
111
+ </body>
112
+ </html>
data/lib/workbook/book.rb CHANGED
@@ -1,5 +1,6 @@
1
1
  require 'workbook/writers/xls_writer'
2
2
  require 'workbook/readers/xls_reader'
3
+ require 'workbook/readers/xls_shared'
3
4
  require 'workbook/readers/xlsx_reader'
4
5
  require 'workbook/readers/csv_reader'
5
6
  require 'workbook/readers/txt_reader'
@@ -10,6 +11,7 @@ module Workbook
10
11
  # Book class can also keep a reference to a template class, storing shared formatting options.
11
12
  #
12
13
  class Book < Array
14
+ include Workbook::Readers::XlsShared
13
15
  include Workbook::Writers::XlsWriter
14
16
  include Workbook::Readers::XlsReader
15
17
  include Workbook::Readers::XlsxReader
@@ -19,7 +21,7 @@ module Workbook
19
21
  attr_accessor :title
20
22
  attr_accessor :template
21
23
 
22
- # @param [Workbook::Sheet, Array] Create a new workbook based on an existing sheet, or initialize a sheet based on the array
24
+ # @param [Workbook::Sheet, Array] sheet create a new workbook based on an existing sheet, or initialize a sheet based on the array
23
25
  # @return [Workbook::Book]
24
26
  def initialize sheet=Workbook::Sheet.new([], self, options={})
25
27
  if sheet.is_a? Workbook::Sheet
@@ -34,27 +36,36 @@ module Workbook
34
36
  @template ||= Workbook::Template.new
35
37
  end
36
38
 
37
- # @param [Workbook::Format] a template describing how the document should be/is formatted
39
+ # @param [Workbook::Format] template a template describing how the document should be/is formatted
38
40
  def template= template
39
41
  raise ArgumentError, "format should be a Workboot::Format" unless template.is_a? Workbook::Template
40
42
  @template = template
41
43
  end
42
44
 
45
+ # The title of the workbook
46
+ #
43
47
  # @return [String] the title of the workbook
44
48
  def title
45
49
  @title ? @title : "untitled document"
46
50
  end
47
51
 
52
+ # Push (like in array) a sheet to the workbook (parameter is optional, default is a new sheet)
53
+ #
54
+ # @param [Workbook::Sheet] sheet
48
55
  def push sheet=Workbook::Sheet.new
49
56
  super(sheet)
50
57
  end
51
58
 
59
+ # Sheet returns the first sheet of a workbook, or an empty one.
60
+ #
52
61
  # @return [Workbook::Sheet] The first sheet, and creates an empty one if one doesn't exists
53
62
  def sheet
54
63
  push Workbook::Sheet.new unless first
55
64
  first
56
65
  end
57
66
 
67
+ # If the first sheet has any contents
68
+ #
58
69
  # @return [Boolean] returns true if the first sheet has contents
59
70
  def has_contents?
60
71
  sheet.has_contents?
@@ -62,43 +73,43 @@ module Workbook
62
73
 
63
74
  # Loads an external file into an existing worbook
64
75
  #
65
- # @param [String] a string with a reference to the file to be opened
66
- # @param [String] an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
76
+ # @param [String] filename a string with a reference to the file to be opened
77
+ # @param [String] extension an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
67
78
  # @return [Workbook::Book] A new instance, based on the filename
68
- def open filename, ext=nil
69
- ext = file_extension(filename) unless ext
70
- if ['txt','csv','xml'].include?(ext)
71
- open_text filename, ext
79
+ def open filename, extension=nil
80
+ extension = file_extension(filename) unless extension
81
+ if ['txt','csv','xml'].include?(extension)
82
+ open_text filename, extension
72
83
  else
73
- open_binary filename, ext
84
+ open_binary filename, extension
74
85
  end
75
86
  end
76
87
 
77
88
  # Open the file in binary, read-only mode, do not read it, but pas it throug to the extension determined loaded
78
89
  #
79
- # @param [String] a string with a reference to the file to be opened
80
- # @param [String] an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
90
+ # @param [String] filename a string with a reference to the file to be opened
91
+ # @param [String] extension an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
81
92
  # @return [Workbook::Book] A new instance, based on the filename
82
- def open_binary filename, ext=nil
83
- ext = file_extension(filename) unless ext
93
+ def open_binary filename, extension=nil
94
+ extension = file_extension(filename) unless extension
84
95
  f = File.open(filename,'rb')
85
- send("load_#{ext}".to_sym,f)
96
+ send("load_#{extension}".to_sym,f)
86
97
  end
87
98
 
88
99
  # Open the file in non-binary, read-only mode, read it and parse it to UTF-8
89
100
  #
90
- # @param [String] a string with a reference to the file to be opened
91
- # @param [String] an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
92
- def open_text filename, ext=nil
93
- ext = file_extension(filename) unless ext
101
+ # @param [String] filename a string with a reference to the file to be opened
102
+ # @param [String] extension an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
103
+ def open_text filename, extension=nil
104
+ extension = file_extension(filename) unless extension
94
105
  f = File.open(filename,'r')
95
106
  t = f.read
96
107
  detected_encoding = CharDet.detect(t)['encoding']
97
108
  t = Iconv.conv("UTF-8//TRANSLIT//IGNORE",detected_encoding,t)
98
- send("load_#{ext}".to_sym,t)
109
+ send("load_#{extension}".to_sym,t)
99
110
  end
100
111
 
101
- # @param [String] The full filename, or path
112
+ # @param [String] filename The full filename, or path
102
113
  #
103
114
  # @return [String] The file extension
104
115
  def file_extension(filename)
@@ -107,15 +118,18 @@ module Workbook
107
118
 
108
119
  # Create an instance from a file, using open.
109
120
  #
110
- # @param [String] the filename of the document
111
- # @param [String] (not required) enforce a certain extension, the parser is based on the extension of the file
121
+ # @param [String] filename of the document
122
+ # @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.
112
123
  # @return [Workbook::Book] A new instance, based on the filename
113
- def self.open filename, ext=nil
124
+ def self.open filename, extension=nil
114
125
  wb = self.new
115
- wb.open filename, ext
126
+ wb.open filename, extension
116
127
  return wb
117
128
  end
118
129
 
130
+ # Create or open the existing sheet at an index value
131
+ #
132
+ # @param [Integer] index the index of the sheet
119
133
  def create_or_open_sheet_at index
120
134
  s = self[index]
121
135
  s = self[index] = Workbook::Sheet.new if s == nil
@@ -123,10 +137,5 @@ module Workbook
123
137
  s
124
138
  end
125
139
 
126
- def sort
127
- raise Exception("Books can't be sorted")
128
- end
129
-
130
-
131
140
  end
132
141
  end
data/lib/workbook/cell.rb CHANGED
@@ -13,12 +13,18 @@ module Workbook
13
13
  # Note that these types are sorted by 'importance'
14
14
  VALID_TYPES = [Numeric,String,Time,Date,TrueClass,FalseClass,NilClass]
15
15
 
16
+ # Evaluates a value for class-validity
17
+ #
18
+ # @param [Numeric,String,Time,Date,TrueClass,FalseClass,NilClass,Object] value the value to evaluate
19
+ # @return [Boolean] returns true when the value is a valid cell value
16
20
  def valid_value? value
17
21
  valid_type = false
18
22
  VALID_TYPES.each {|t| return true if value.is_a? t}
19
23
  valid_type
20
24
  end
21
25
 
26
+ # @param [Numeric,String,Time,Date,TrueClass,FalseClass,NilClass] value a valid value
27
+ # @param [Hash] options a reference to :format (Workbook::Format) can be specified
22
28
  def initialize value=nil, options={}
23
29
  if valid_value? value
24
30
  format = options[:format]
@@ -28,6 +34,7 @@ module Workbook
28
34
  end
29
35
  end
30
36
 
37
+ # @param [Workbook::Format, Hash] f set the formatting properties of this Cell
31
38
  def format= f
32
39
  if f.is_a? Workbook::Format
33
40
  @format = f
@@ -42,6 +49,8 @@ module Workbook
42
49
  @format ||= Workbook::Format.new
43
50
  end
44
51
 
52
+ # @param [Workbook::Cell] other cell to compare against
53
+ # @return [Boolean]
45
54
  def ==(other)
46
55
  if other.is_a? Cell
47
56
  other.value == self.value
@@ -50,10 +59,17 @@ module Workbook
50
59
  end
51
60
  end
52
61
 
62
+ # returns true when the value of the cell is nil.
63
+ # @return [Boolean]
53
64
  def nil?
54
65
  return value.nil?
55
66
  end
56
67
 
68
+ # returns a symbol representation of the cell's value
69
+ # @return [Symbol] a symbol representation
70
+ # @example
71
+ #
72
+ # <Workbook::Cell value="yet another value">.to_sym # returns :yet_another_value
57
73
  def to_sym
58
74
  #mb_chars.normalize(:kd).
59
75
  v = nil
@@ -98,6 +114,7 @@ module Workbook
98
114
  v
99
115
  end
100
116
 
117
+ # @param [Workbook::Cell] other cell to compare against, can compare different value-types using #compare_on_class
101
118
  def <=> other
102
119
  rv = nil
103
120
  begin
@@ -112,6 +129,9 @@ module Workbook
112
129
 
113
130
  end
114
131
 
132
+ # Compare on class level
133
+ #
134
+ # @param [Workbook::Cell] other cell to compare against
115
135
  def compare_on_class other
116
136
  other_value = nil
117
137
  other_value = other.value if other
@@ -120,6 +140,9 @@ module Workbook
120
140
  self_value <=> other_value
121
141
  end
122
142
 
143
+ # Returns the importance of a value's class
144
+ #
145
+ # @param value a potential value for a cell
123
146
  def importance_of_class value
124
147
  VALID_TYPES.each_with_index do |c,i|
125
148
  return i if value.is_a? c
@@ -131,6 +154,8 @@ module Workbook
131
154
  "<Workbook::Cell @value=#{value}>"
132
155
  end
133
156
 
157
+ # convert value to string, and in case of a Date or Time value, apply formatting
158
+ # @return [String]
134
159
  def to_s
135
160
  if (value.is_a? Date or value.is_a? Time) and format[:number_format]
136
161
  value.strftime(format[:number_format])
data/lib/workbook/format.rb CHANGED
@@ -1,16 +1,20 @@
1
1
  require 'workbook/modules/raw_objects_storage'
2
2
 
3
3
  module Workbook
4
+ # Format is an object used for maintinaing a cell's formatting. It can belong to many cells. It maintains a relation to the raw template's equivalent, to preserve attributes Workbook cannot modify/access.
4
5
  class Format < Hash
5
6
  include Workbook::Modules::RawObjectsStorage
6
7
  alias_method :merge_hash, :merge
7
8
 
8
9
  attr_accessor :name
9
10
 
11
+ # Initialize
12
+ # @param [Workbook::Format, Hash] options (e.g. :background, :color
10
13
  def initialize options={}
11
14
  options.each {|k,v| self[k]=v}
12
15
  end
13
16
 
17
+ # Does the current format feature a background *color*? (not black or white or transparant).
14
18
  def has_background_color? color=:any
15
19
  if self[:background_color]
16
20
  return (self[:background_color].downcase==color.to_s.downcase or (!(self[:background_color]==nil or (self[:background_color].is_a? String and (self[:background_color].downcase=='#ffffff' or self[:background_color]=='#000000'))) and color==:any))
@@ -20,6 +24,7 @@ module Workbook
20
24
  end
21
25
 
22
26
  # Returns a string that can be used as inline cell styling (e.g. `<td style="<%=cell.format.to_css%>"><%=cell%></td>`)
27
+ # @return [String] very basic CSS styling string
23
28
  def to_css
24
29
  css_parts = []
25
30
  css_parts.push("background: #{self[:background_color].to_s} #{self[:background].to_s}".strip) if self[:background] or self[:background_color]
@@ -27,9 +32,11 @@ module Workbook
27
32
  css_parts.join("; ")
28
33
  end
29
34
 
30
- def merge(a)
35
+ # Combines the formatting options of one with another, removes as a consequence the reference to the raw object's equivalent.
36
+ # @param [Workbook::Format] other_format
37
+ def merge(other_format)
31
38
  self.remove_all_raws!
32
- self.merge_hash(a)
39
+ self.merge_hash(other_format)
33
40
  end
34
41
  end
35
42
  end
data/lib/workbook/modules/raw_objects_storage.rb CHANGED
@@ -1,5 +1,6 @@
1
1
  module Workbook
2
2
  module Modules
3
+ # Adds support for storing raw objects, used in e.g. Format and Template
3
4
  module RawObjectsStorage
4
5
 
5
6
  # A raw is a 'raw' object, representing a workbook, or cell, or whatever... in a particular format (defined by its class)
@@ -13,15 +14,19 @@ module Workbook
13
14
  return false
14
15
  end
15
16
 
17
+ # Returns raw data stored for a type of raw object (if available)
18
+ # @param [Class] raw_object_class (e.g. Spreadsheet::Format for the Spreadsheet-gem)
16
19
  def return_raw_for raw_object_class
17
20
  raws.each { |tc,t| return t if tc == raw_object_class}
18
21
  return nil
19
22
  end
20
23
 
24
+ # Remove all raw data references
21
25
  def remove_all_raws!
22
26
  @raws = {}
23
27
  end
24
28
 
29
+ # Return all raw data references
25
30
  def raws
26
31
  @raws = {} unless defined? @raws
27
32
  @raws
data/lib/workbook/modules/table_diff_sort.rb CHANGED
@@ -1,8 +1,10 @@
1
- # Adds diffing and sorting functions
2
1
  module Workbook
3
2
  module Modules
3
+ # Adds diffing and sorting functions
4
4
  module TableDiffSort
5
- # create an overview of the differences between itself with another table, returns a book with a single sheet and table (containing the diffs)
5
+ # create an overview of the differences between itself with another 'previous' table, returns a book with a single sheet and table (containing the diffs)
6
+ #
7
+ # @return [Workbook::Book] (note should and will become Workbook::Table as diffing occurs on table level...)
6
8
  def diff other, options={:sort=>true,:ignore_headers=>false}
7
9
 
8
10
  aligned = align(other, options)
@@ -14,7 +16,7 @@ module Workbook
14
16
  else
15
17
  iteration_cols = (aother.header.to_symbols+aother.header.to_symbols).uniq
16
18
  end
17
- diff_table = diff_template.sheet.table
19
+ diff_table = diff_template
18
20
  maxri = (aself.count-1)
19
21
  for ri in 0..maxri do
20
22
  row = diff_table[ri]
@@ -50,7 +52,7 @@ module Workbook
50
52
  diff_table[0].format = diff_template.template.create_or_find_format_by 'header'
51
53
  end
52
54
 
53
- diff_template
55
+ diff_table
54
56
  end
55
57
 
56
58
  def diff_template
@@ -69,7 +71,7 @@ module Workbook
69
71
  f[:font_weight] = :bold
70
72
  f[:height] = 80
71
73
  @diff_template = diffbook
72
- return diffbook
74
+ return difftable
73
75
  end
74
76
 
75
77
  # aligns itself with another table, used by diff
@@ -80,7 +82,7 @@ module Workbook
80
82
  iteration_cols = nil
81
83
  sother = other.clone.remove_empty_lines!
82
84
  sself = self.clone.remove_empty_lines!
83
-
85
+
84
86
  if options[:ignore_headers]
85
87
  sother.header = false
86
88
  sself.header = false