Skip to content
Newer
Older
100644 252 lines (172 sloc) 5.49 KB
1bf13f7 @paulspringett Added README docs
authored
1 # CSV Shaper
f40618f @paulspringett Created CSV Shaper gem
authored
2
c468114 @paulspringett Updated README with examples
authored
3 Beautiful DSL for creating CSV output in Ruby & Rails.
4
4251fee @msadouni Typos on README.md
msadouni authored
5 Creating CSV files in Ruby is painful! CSV Shaper makes life easier! It's ideal for converting database backed models with attributes into CSV output. It can be used without Rails, but works great with ActiveRecord models and even comes with support for its own template handling.
f40618f @paulspringett Created CSV Shaper gem
authored
6
b6b263d @paulspringett Travis CI build status
authored
7 [![Build Status](https://secure.travis-ci.org/paulspringett/csv_shaper.png?branch=master)](http://travis-ci.org/paulspringett/csv_shaper)
8
e2374ed @paulspringett Added source link
authored
9 Annotated source: http://paulspringett.github.com/csv_shaper/
10
1bf13f7 @paulspringett Added README docs
authored
11 ### Example Usage
f40618f @paulspringett Created CSV Shaper gem
authored
12
1bf13f7 @paulspringett Added README docs
authored
13 ```ruby
aa06ddf @paulspringett Add shortcut to the encode method on CsvShaper
authored
14 csv_string = CsvShaper.encode do |csv|
1bf13f7 @paulspringett Added README docs
authored
15 csv.header :name, :age, :gender, :pet_names
16
17 csv.rows @users do |csv, user|
18 csv.cells :name, :age, :gender
19
20 if user.pets.any?
21 csv.cell :pet_names
22 end
23 end
24 end
25 ```
f40618f @paulspringett Created CSV Shaper gem
authored
26
1bf13f7 @paulspringett Added README docs
authored
27 ### Install
f40618f @paulspringett Created CSV Shaper gem
authored
28
1bf13f7 @paulspringett Added README docs
authored
29 Install using Rubygems
f40618f @paulspringett Created CSV Shaper gem
authored
30
c468114 @paulspringett Updated README with examples
authored
31 ```bash
32 $ gem install csv_shaper
33 ```
f40618f @paulspringett Created CSV Shaper gem
authored
34
1bf13f7 @paulspringett Added README docs
authored
35 Or if you want to use it in your Rails app, add the following line to your Gemfile
f40618f @paulspringett Created CSV Shaper gem
authored
36
c468114 @paulspringett Updated README with examples
authored
37 ```ruby
38 gem 'csv_shaper'
39 ```
40
41 and then run
42
43 ```bash
44 $ bundle install
45 ```
46
47 ### Usage
48
49 Everything goes inside the `encode` block, like so
50
51 ```ruby
52 csv_string = CsvShaper::Shaper.encode do |csv|
53 ...
54 end
55 ```
56
beba111 @paulspringett Updated README
authored
57 ### Usage in Rails 3.0+
58
c8beb24 @paulspringett Added more detailed Rails usage guide
authored
59 When using it in Rails your view template is rendered inside the `encode` block so you can just call the `csv` object directly.
f40618f @paulspringett Created CSV Shaper gem
authored
60
c8beb24 @paulspringett Added more detailed Rails usage guide
authored
61 In Rails the example at the top of the README would simply be:
62
63 ```ruby
64 csv.headers :name, :age, :gender, :pet_names
65
66 csv.rows @users do |csv, user|
67 csv.cells :name, :age, :gender
68
69 if user.pets.any?
70 csv.cell :pet_names
71 end
72 end
73 ```
74
75 Create a Rails view, set the content-type to `csv` and the handler to `shaper`. For the view of the `index` action the filename would be:
312a109 @paulspringett Added gemspec details
authored
76
c468114 @paulspringett Updated README with examples
authored
77 index.csv.shaper
beba111 @paulspringett Updated README
authored
78
79 then just start defining your headers and rows as per the examples.
312a109 @paulspringett Added gemspec details
authored
80
c468114 @paulspringett Updated README with examples
authored
81 ### Headers
312a109 @paulspringett Added gemspec details
authored
82
c468114 @paulspringett Updated README with examples
authored
83 You must define the headers for your CSV output. This can be done in one of 3 ways.
312a109 @paulspringett Added gemspec details
authored
84
c468114 @paulspringett Updated README with examples
authored
85 #### Standard attribute list
312a109 @paulspringett Added gemspec details
authored
86
c468114 @paulspringett Updated README with examples
authored
87 ```ruby
88 csv.headers :name, :age, :location
89 ```
312a109 @paulspringett Added gemspec details
authored
90
c468114 @paulspringett Updated README with examples
authored
91 This would create headers like so:
312a109 @paulspringett Added gemspec details
authored
92
c468114 @paulspringett Updated README with examples
authored
93 ```csv
94 Name,Age,Location
95 ```
312a109 @paulspringett Added gemspec details
authored
96
c468114 @paulspringett Updated README with examples
authored
97 #### Using the attribute names of a Class
312a109 @paulspringett Added gemspec details
authored
98
c468114 @paulspringett Updated README with examples
authored
99 Say you have a User ActiveRecord class with attributes of `:name, :age, :location`. Simply pass the class to the headers method
312a109 @paulspringett Added gemspec details
authored
100
c468114 @paulspringett Updated README with examples
authored
101 ```ruby
102 csv.headers User
103 ```
312a109 @paulspringett Added gemspec details
authored
104
c468114 @paulspringett Updated README with examples
authored
105 #### Using a block to define headers and custom mappings
312a109 @paulspringett Added gemspec details
authored
106
c468114 @paulspringett Updated README with examples
authored
107 ```ruby
108 csv.headers do |csv|
109 csv.columns :name, :age, :location
110 csv.mappings name: 'Full name', location: 'Region'
111 end
112 ```
312a109 @paulspringett Added gemspec details
authored
113
c468114 @paulspringett Updated README with examples
authored
114 This would create headers like so:
312a109 @paulspringett Added gemspec details
authored
115
c468114 @paulspringett Updated README with examples
authored
116 ```csv
117 Full name,Age,Region
118 ```
312a109 @paulspringett Added gemspec details
authored
119
47bf212 @paulspringett Updated README
authored
120 The mappings are useful for pretty-ing up the names when creating the CSV. When creating cells below you should still use the column names, not the mapping names. eg. `:name` not `'Full name'`
121
c468114 @paulspringett Updated README with examples
authored
122 ### Rows & Cells
312a109 @paulspringett Added gemspec details
authored
123
c468114 @paulspringett Updated README with examples
authored
124 CSV Shaper allows you to define rows and cells in a variety of ways.
312a109 @paulspringett Added gemspec details
authored
125
c468114 @paulspringett Updated README with examples
authored
126 #### Basic row without a model
127
128 ```ruby
129 csv.row do |csv|
130 csv.cell :name, "Joe"
131 csv.cell :age, 24
132 end
133 ```
134
135 #### Passing a model and attributes
136
137 ```ruby
138 csv.row @user, :name, :age, :location
139 ```
140
309fbbc @paulspringett README changes
authored
141 This will call the column names (name, age...) on `@user` and assign them to the correct cells. The output from the above Ruby might look like:
47bf212 @paulspringett Updated README
authored
142
143 ```
144 Paul,27,United Kingdom
145 ```
c468114 @paulspringett Updated README with examples
authored
146
147 #### Passing a model to a block
148
149 ```ruby
7edcc28 @paulspringett Fix documented csv.row example
authored
150 csv.row @user do |csv, user|
c468114 @paulspringett Updated README with examples
authored
151 csv.cells :name, :age
152 if user.show_gender?
153 csv.cell :gender
154 end
155
47bf212 @paulspringett Updated README
authored
156 csv.cell :exported_at, Date.today.to_formatted_s(:db)
c468114 @paulspringett Updated README with examples
authored
157 end
158 ```
159
662d1af @paulspringett README changes
authored
160 Any calls here to `cell` without a second argument are called on the model (`user`), otherwise the second parameter is used as a static value.
309fbbc @paulspringett README changes
authored
161
162 The `cells` method only takes a list of Symbols that are called as methods on the model (`user`).
47bf212 @paulspringett Updated README
authored
163
662d1af @paulspringett README changes
authored
164 The output from the above Ruby might look like:
165
47bf212 @paulspringett Updated README
authored
166 ```
167 Paul,27,Male,2012-07-25
168 ```
c468114 @paulspringett Updated README with examples
authored
169
170 ### Multiple Rows
171
172 You can pass an Enumerable and a block to `csv.rows` like so
173
174 ```ruby
175 csv.rows @users do |csv, user|
176 csv.cells :name, :age, :location, :gender
177 csv.cell :exported_at, Time.now
178 end
179 ```
312a109 @paulspringett Added gemspec details
authored
180
122f4df @paulspringett Updated README
authored
181 ### Don't worry about missing cells
182
183 There's no need to pad missing cells with `nil`
184
185 This Ruby code will produce the CSV output below
186
187 ```ruby
188 csv.headers :name, :age, :gender
189
190 csv.row do |csv|
191 csv.cell :name, 'Paul'
c39ffb2 @paulspringett Updated README
authored
192 # no age cell
122f4df @paulspringett Updated README
authored
193 csv.cell :gender, 'M'
194 end
195
196 csv.row do |csv|
197 csv.cell :name 'Joe'
198 csv.cell :age, 34
c39ffb2 @paulspringett Updated README
authored
199 # no gender cell
122f4df @paulspringett Updated README
authored
200 end
201 ```
202
c39ffb2 @paulspringett Updated README
authored
203 ```
122f4df @paulspringett Updated README
authored
204 Name,Age,Gender
205 Paul,,M
206 Joe,34,
207 ```
208
8d9d1cd @paulspringett README additions
authored
209 ### Further Rails integration
210
211 Customise the filename of the CSV download by defining a `@filename` instance variable in your controller action.
212
213 ```ruby
214 respond_to :html, :csv
215
216 def index
217 @users = User.all
218 @filename = "All users - #{Date.today.to_formatted_s(:db)}.csv"
219 end
220 ```
221
1c0d213 @paulspringett Updated README with configure example
authored
222 ### CSV configuration
223
224 To configure how the CSV output is formatted you can define a configure block, like so:
225
226 ```ruby
227 CsvShaper.configure do |config|
228 config.col_sep = "\t"
229 config.write_headers = false
230 end
231 ```
232
952a3a8 @paulspringett Updated docs
authored
233 Inside the block you can pass any of the standard library [CSV DEFAULT_OPTIONS](http://ruby-doc.org/stdlib-1.9.2/libdoc/csv/rdoc/CSV.html#DEFAULT_OPTIONS), as well as a `write_headers` option (default: `true`).
234 Setting this to `false` will exclude the headers from the final CSV output.
235
b81f476 @paulspringett Rails instructions
authored
236 If you're using Rails you can put this in an initializer.
237
a0440be @paulspringett Added "Contributing" guide
authored
238 ### Contributing
239
240 1. Fork it
241 2. Create a semantically named feature branch
242 3. Write your feature
243 4. Add some tests for it
244 5. Commit your changes & push to GitHub (do not change the gem's version number)
245 6. Submit a pull request with relevant details
246
8d9d1cd @paulspringett README additions
authored
247 ##### Hat tips
248
122f4df @paulspringett Updated README
authored
249 * [Jbuilder](https://github.com/rails/jbuilder/) for inspiration for the DSL
250 * [CSV Builder](https://github.com/econsultancy/csv_builder) for headers and custom filenames
8d9d1cd @paulspringett README additions
authored
251
c468114 @paulspringett Updated README with examples
authored
252 Copyright (c) Paul Springett 2012
Something went wrong with that request. Please try again.