comma 4.1.0 → 4.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (39) hide show
  1. checksums.yaml +5 -5
  2. data/.travis.yml +26 -7
  3. data/Appraisals +1 -1
  4. data/Gemfile.lock +3 -3
  5. data/README.md +59 -0
  6. data/comma.gemspec +3 -5
  7. data/gemfiles/active4.1.16.gemfile.lock +4 -4
  8. data/gemfiles/active4.2.8.gemfile.lock +3 -3
  9. data/gemfiles/active5.0.1.gemfile.lock +3 -3
  10. data/gemfiles/active5.1.0.gemfile.lock +3 -3
  11. data/gemfiles/active5.2.0.gemfile +10 -0
  12. data/gemfiles/active5.2.0.gemfile.lock +106 -0
  13. data/gemfiles/rails4.1.16.gemfile.lock +16 -17
  14. data/gemfiles/rails4.2.8.gemfile.lock +3 -3
  15. data/gemfiles/rails5.0.1.gemfile.lock +3 -3
  16. data/gemfiles/rails5.1.0.gemfile.lock +3 -3
  17. data/gemfiles/rails5.2.0.gemfile +11 -0
  18. data/gemfiles/rails5.2.0.gemfile.lock +204 -0
  19. data/lib/comma.rb +2 -3
  20. data/lib/comma/data_extractor.rb +2 -4
  21. data/lib/comma/data_mapper_collection.rb +0 -2
  22. data/lib/comma/extractor.rb +0 -2
  23. data/lib/comma/generator.rb +2 -3
  24. data/lib/comma/header_extractor.rb +0 -1
  25. data/lib/comma/object.rb +0 -1
  26. data/lib/comma/version.rb +1 -1
  27. data/spec/comma/data_extractor_spec.rb +0 -1
  28. data/spec/comma/header_extractor_spec.rb +1 -2
  29. data/spec/comma/rails/active_record_spec.rb +0 -1
  30. data/spec/comma/rails/data_mapper_collection_spec.rb +0 -1
  31. data/spec/comma/rails/mongoid_spec.rb +0 -1
  32. data/spec/rails_app/active_record/config.rb +0 -2
  33. data/spec/rails_app/active_record/models.rb +0 -2
  34. data/spec/rails_app/data_mapper/config.rb +0 -2
  35. data/spec/rails_app/mongoid/config.rb +0 -2
  36. data/spec/rails_app/rails_app.rb +1 -2
  37. data/spec/spec_helper.rb +1 -2
  38. metadata +11 -7
  39. data/README.markdown +0 -353
@@ -1,353 +0,0 @@
1
- #COMMA
2
-
3
- http://github.com/comma-csv/comma
4
-
5
- [![Gem Version](https://badge.fury.io/rb/comma.png)](http://badge.fury.io/rb/comma)
6
-
7
- ##COMPATIBILITY
8
- The mainline of this project builds gems to the 3.x version series, and is compatible and tested with :
9
-
10
- * Ruby 2.x
11
- * Rails 4.x, 5.0 (with ActiveRecord, DataMapper and Mongoid support)
12
-
13
- [![Build Status](https://travis-ci.org/comma-csv/comma.png?branch=master)](https://travis-ci.org/comma-csv/comma) [![Code Climate](https://codeclimate.com/github/comma-csv/comma.png)](https://codeclimate.com/github/comma-csv/comma)
14
-
15
- Comma is distributed as a gem, best installed via Bundler.
16
-
17
- Include the gem in your Gemfile:
18
-
19
- ```Ruby
20
- gem "comma", "~> 4.0.0"
21
- ```
22
-
23
- Or, if you want to live life on the edge, you can get master from the main comma repository:
24
-
25
- ```Ruby
26
- gem "comma", :git => "git://github.com/comma-csv/comma.git"
27
- ```
28
-
29
- ##DESCRIPTION:
30
-
31
- Comma is a CSV (i.e. comma separated values) generation extension for Ruby objects, that lets you seamlessly define a CSV output format via a small DSL. Comma works well on pure Ruby objects with attributes, as well as complex ones such as ActiveRecord objects with associations, extensions, etc. It doesn't distinguish between attributes, methods, associations, extensions, etc. - they all are considered equal and invoked identically via the Comma DSL description. Multiple different CSV output descriptions can also be defined.
32
-
33
- When multiple objects in an Array are converted to CSV, the output includes generation of a header row reflected from names of the properties requested, or specified via the DSL.
34
-
35
- CSV can be a bit of a boring format - the motivation behind Comma was to have a CSV extension that was simple, flexible, and would treat attributes, methods, associations, etc., all the same without the need for any complex configuration, and also work on Ruby objects, not just ActiveRecord or other base class derivatives.
36
-
37
- An example Comma CSV enabled ActiveRecord class:
38
-
39
- ```Ruby
40
-
41
- class Book < ActiveRecord::Base
42
-
43
- # ================
44
- # = Associations =
45
- # ================
46
- has_many :pages
47
- has_one :isbn
48
- belongs_to :publisher
49
-
50
- # ===============
51
- # = CSV support =
52
- # ===============
53
- comma do
54
-
55
- name
56
- description
57
-
58
- pages :size => 'Pages'
59
- publisher :name
60
- isbn :number_10 => 'ISBN-10', :number_13 => 'ISBN-13'
61
- blurb 'Summary'
62
-
63
- end
64
-
65
- end
66
-
67
- ```
68
-
69
- Annotated, the comma description is as follows:
70
-
71
- ```Ruby
72
- # starts a Comma description block, generating 2 methods #to_comma and
73
- # #to_comma_headers for this class.
74
- comma do
75
-
76
- # name, description are attributes of Book with the header being reflected as
77
- # 'Name', 'Description'
78
- name
79
- description
80
-
81
- # pages is an association returning an array, :size is called on the
82
- # association results, with the header name specified as 'Pages'
83
- pages :size => 'Pages'
84
-
85
- # publisher is an association returning an object, :name is called on the
86
- # associated object, with the reflected header 'Name'
87
- publisher :name
88
-
89
- # isbn is an association returning an object, :number_10 and :number_13 are
90
- # called on the object with the specified headers 'ISBN-10' and 'ISBN-13'
91
- isbn :number_10 => 'ISBN-10', :number_13 => 'ISBN-13'
92
-
93
- # blurb is an attribute of Book, with the header being specified directly
94
- # as 'Summary'
95
- blurb 'Summary'
96
-
97
- end
98
-
99
- ```
100
-
101
- In the above example, any of the declarations (name, description, pages, publisher, isbn, blurb, etc), could be methods, attributes, associations, etc - no distinction during configuration is required, as everything is invoked via Ruby's #send method.
102
-
103
- You can get the CSV representation of any object by calling the to_comma method, optionally providing a CSV description name to use.
104
-
105
- Object values are automatically converted to strings via to_s allowing you to reuse any existing to_s methods on your objects (instead of having to call particular properties or define CSV specific output methods). Header names are also automatically humanised when reflected (eg. Replacing _ characters with whitespace). The 'isbn' example above shows how multiple values can be added to the CSV output.
106
-
107
- Multiple CSV descriptions can also be specified for the same class, eg:
108
-
109
- ```Ruby
110
-
111
- class Book < ActiveRecord::Base
112
-
113
- # ================
114
- # = Associations =
115
- # ================
116
- has_many :pages
117
- has_one :isbn
118
- belongs_to :publisher
119
-
120
- # ===============
121
- # = CSV support =
122
- # ===============
123
- comma do
124
-
125
- name
126
- description
127
-
128
- pages :size => 'Pages'
129
- publisher :name
130
- isbn :number_10 => 'ISBN-10', :number_13 => 'ISBN-13'
131
- blurb 'Summary'
132
-
133
- end
134
-
135
- comma :brief do
136
-
137
- name
138
- description
139
- blurb 'Summary'
140
-
141
- end
142
-
143
- end
144
-
145
- ```
146
-
147
- You can specify which output format you would like to use via an optional parameter to to_comma:
148
-
149
- ```Ruby
150
- Book.limited(10).to_comma(:brief)
151
- ```
152
-
153
- Specifying no description name to to_comma is equivalent to specifying :default as the description name.
154
-
155
- You can pass all options for the CSV renderer (see : http://ruby-doc.org/stdlib-1.9.2/libdoc/csv/rdoc/CSV.html ), e.g.
156
-
157
- ```Ruby
158
- Book.limited(10).to_comma(:style => :brief,
159
- :col_sep => ';',
160
- :force_quotes => true)
161
- ```
162
-
163
- You can pass the :filename option and have Comma writes the CSV output to this file:
164
-
165
- ```Ruby
166
- Book.limited(10).to_comma(:filename => 'books.csv')
167
- ```
168
-
169
- You also can pass the :write_header option to hide the header line (true is default):
170
-
171
- ```Ruby
172
- Book.limited(10).to_comma(:write_headers => false)
173
- ```
174
-
175
- ##Using blocks
176
-
177
- For more complex relationships you can pass blocks for calculated values, or related values. Following the previous example here is a comma set using blocks (both with and without labels for your CSV headings):
178
-
179
- ```Ruby
180
-
181
- class Publisher < ActiveRecord::Base
182
- # ================
183
- # = Associations =
184
- # ================
185
- has_one :primary_contact, :class_name => "User" #(basic user with a name)
186
- has_many :users
187
- end
188
-
189
- class Book < ActiveRecord::Base
190
-
191
- # ================
192
- # = Associations =
193
- # ================
194
- has_many :pages
195
- has_one :isbn
196
- belongs_to :publisher
197
-
198
- # ===============
199
- # = CSV support =
200
- # ===============
201
- comma do
202
- name
203
- description
204
-
205
- pages :size => 'Pages'
206
- publisher :name
207
- publisher { |publisher| publisher.primary_contact.name.to_s.titleize }
208
- publisher 'Number of publisher users' do |publisher| publisher.users.size end
209
- isbn :number_10 => 'ISBN-10', :number_13 => 'ISBN-13'
210
- blurb 'Summary'
211
-
212
- end
213
-
214
- end
215
-
216
- ```
217
-
218
- In the preceding example, the 2 new fields added (both based on the publisher relationship) mean that the following will be added:
219
-
220
- * the first example 'publishers_contact' is loaded straight as a block. The value returned by the lambda is displayed with a header value of 'Publisher'
221
- * the second example 'total_publishers_users' is sent via a hash and a custom label is set, if used in the first examples method the header would be 'Publisher', but sent as a hash the header is 'Number of publisher users'.
222
-
223
- ##Using special fields
224
-
225
- ###\_\_use\_\_
226
-
227
- With `__use__` field, you can reuse output formats that are defined in
228
- the same class. In the example below, default format (`:default`)
229
- includes `:minimum` format when `#to_comma` is called.
230
-
231
- ```ruby
232
- class Book < ActiveRecord::Base
233
- comma do
234
- __use__ :minimum
235
-
236
- description
237
-
238
- isbn :number_10 => 'ISBN-10', :number_13 => 'ISBN-13'
239
- end
240
-
241
- comma :minimum do
242
- name
243
- end
244
- end
245
- ```
246
-
247
- ###\_\_static_column\_\_
248
-
249
- When you want to have static value in your CSV output, you can use
250
- `__static__` field. You can provide values to output to blocks.
251
- Without block, field will become empty.
252
-
253
- ```ruby
254
- class Book < ActiveRecord::Base
255
- comma do
256
- __static_column__ 'Check' do ' ' end
257
- name
258
- __static_column__ 'Spacer'
259
- description
260
- end
261
- end
262
- ```
263
-
264
- ##USING WITH RAILS
265
-
266
- When used with Rails (ie. add 'comma' as a gem dependency), Comma automatically adds support for rendering CSV output in your controllers:
267
-
268
- ```Ruby
269
-
270
- class BooksController < ApplicationController
271
-
272
- def index
273
- respond_to do |format|
274
- format.csv { render :csv => Book.limited(50) }
275
- end
276
- end
277
-
278
- end
279
-
280
- ```
281
-
282
- You can specify which output format you would like to use by specifying a style parameter or adding any available CSV option:
283
-
284
- ```Ruby
285
-
286
- class BooksController < ApplicationController
287
-
288
- def index
289
- respond_to do |format|
290
- format.csv { render :csv => Book.limited(50), :style => :brief }
291
- end
292
- end
293
-
294
- end
295
-
296
- ```
297
-
298
- You can also specify a different file extension ('csv' by default)
299
-
300
- ```Ruby
301
-
302
- class BooksController < ApplicationController
303
-
304
- def index
305
- respond_to do |format|
306
- format.csv { render :csv => Book.limited(50), :extension => 'txt' }
307
- end
308
- end
309
-
310
- end
311
-
312
- ```
313
-
314
- With the Rails renderer you can supply any of the regular parameters that you would use with to_comma such as :filename,
315
- :write_headers, :force_quotes, etc. The parameters just need to be supplied after you specify the collection for the csv as demonstrated
316
- above.
317
-
318
- When used with Rails 3.+, Comma also adds support for exporting scopes:
319
-
320
- ```Ruby
321
-
322
- class Book < ActiveRecord::Base
323
- scope :recent,
324
- lambda { { :conditions => ['created_at > ?', 1.month.ago] } }
325
-
326
- # ...
327
- end
328
-
329
- ```
330
-
331
- Calling the to_comma method on the scope will internally use Rails' find_each method, instantiating only 1,000 ActiveRecord objects at a time:
332
-
333
- ```Ruby
334
-
335
- Book.recent.to_comma
336
-
337
- ```
338
-
339
- ##DEPENDENCIES
340
-
341
- If you have any questions or suggestions for Comma, please feel free to contact me at tom@venombytes.com, all feedback welcome!
342
-
343
- ##TESTING
344
-
345
- To run the test suite across multiple gem file sets, we're using [Appraisal](https://github.com/thoughtbot/appraisal), use the following commands :
346
-
347
- ```Bash
348
-
349
- bundle install
350
- bundle exec appraisal install
351
- bundle exec appraisal rake spec
352
-
353
- ```