workbook 0.2.0 → 0.2.1

Sign up to get free protection for your applications and to get access to all the features.
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