simple_csv 0.2.1 → 0.2.2
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.
- checksums.yaml +4 -4
- data/README.md +2 -227
- data/lib/simple_csv/version.rb +1 -1
- data/simple_csv.gemspec +1 -1
- metadata +3 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 00ca4ef7b136f13cf68ada6db2d5eef9b1f37d97
|
|
4
|
+
data.tar.gz: a7330cea3184fad6d2c44c9c2237b89a433ea8eb
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 96c993bbe4a663dc0ce36226ba8928836f26a6918526cca40e818b8a26b3906a79af5e8da1445d1c5903ec47f50468c7321d9c2a19edaef7b33ec5c3f5b378a3
|
|
7
|
+
data.tar.gz: 084054a3e03682f0f4ef418f74e47f6b1e7e9ef72c87d7189374c9189b7ee1c4ab139ea1b9ffa7e71701c67ed89d3ebc47c1b7b09f8bc96ac07444a2cd588030
|
data/README.md
CHANGED
|
@@ -1,228 +1,3 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Readme
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
See the examples given below for more details :)
|
|
5
|
-
|
|
6
|
-
## Status
|
|
7
|
-
|
|
8
|
-
[](http://badge.fury.io/rb/simple_csv)
|
|
9
|
-
[](https://travis-ci.org/SidOfc/simple_csv)
|
|
10
|
-
[](https://coveralls.io/github/SidOfc/simple_csv?branch=master)
|
|
11
|
-
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
## Installation
|
|
15
|
-
|
|
16
|
-
Add this line to your application's Gemfile:
|
|
17
|
-
|
|
18
|
-
```ruby
|
|
19
|
-
gem 'simple_csv'
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
And then execute:
|
|
23
|
-
|
|
24
|
-
$ bundle
|
|
25
|
-
|
|
26
|
-
Or install it yourself as:
|
|
27
|
-
|
|
28
|
-
$ gem install simple_csv
|
|
29
|
-
|
|
30
|
-
## Usage
|
|
31
|
-
|
|
32
|
-
### General
|
|
33
|
-
|
|
34
|
-
By default, the settings used will be those of `CSV::DEFAULT_OPTIONS` generally.
|
|
35
|
-
`SimpleCsv` sets the `:headers` property to true by default, this is due to the nature of `SimpleCsv`.
|
|
36
|
-
|
|
37
|
-
Headers have to be defined either before reading or generating a CSV.
|
|
38
|
-
Since `:headers` is now `true` by default, `SimpleCsv` will allow `CSV` to parse the first line as headers.
|
|
39
|
-
These headers are then converted in method calls to use within an `SimpleCsv::Reader#each_row` loop.
|
|
40
|
-
|
|
41
|
-
If however, your file lacks headers, you have the ability to set `:has_headers` to false and supply headers manually before calling `SimpleCsv::Reader#each_row`.
|
|
42
|
-
The headers will be picked up and used instead of the first line.
|
|
43
|
-
|
|
44
|
-
#### SimpleCsv default settings
|
|
45
|
-
|
|
46
|
-
These are the settings that will be merged with settings passed through either `SimpleCsv#generate` or `SimpleCsv#read`
|
|
47
|
-
|
|
48
|
-
| setting | value |
|
|
49
|
-
|----------------------|---------------------------------------|
|
|
50
|
-
|`:col_sep` | `","` |
|
|
51
|
-
|`:row_sep` | `:auto` |
|
|
52
|
-
|`:quote_char` | `"\"` |
|
|
53
|
-
|`:field_size_limit` | `nil` |
|
|
54
|
-
|`:converters` | `[:all, :blank_to_nil, :null_to_nil]` |
|
|
55
|
-
|`:unconverted_fields` | `nil` |
|
|
56
|
-
|`:headers` | `true` |
|
|
57
|
-
|`:return_headers` | `false` |
|
|
58
|
-
|`:header_converters` | `nil` |
|
|
59
|
-
|`:skip_blanks` | `false` |
|
|
60
|
-
|`:force_quotes` | `true` |
|
|
61
|
-
|`:skip_lines` | `nil` |
|
|
62
|
-
|
|
63
|
-
The following settings differ from the `CSV::DEFAULT_OPTIONS`
|
|
64
|
-
|
|
65
|
-
* `:converters` is set to `[:all, :blank_to_nil, :null_to_nil]`
|
|
66
|
-
* `:headers` is `true` by default
|
|
67
|
-
* `:force_quotes` is `true` by default
|
|
68
|
-
|
|
69
|
-
This essentially means that when reading a CSV file, headers are required otherwise a `SimpleCsv::HeadersNotSet` exception will be thrown.
|
|
70
|
-
Also, when reading a CSV, all values will be parsed to their respective types, so `"1"` would become `1` as end value.
|
|
71
|
-
|
|
72
|
-
#### SimpleCsv::Writer additional default settings
|
|
73
|
-
|
|
74
|
-
Additionally, `SimpleCsv::Writer` has one additional default setting that ensures an entire row is written before being able to write another one.
|
|
75
|
-
This setting enforces you to call each method once before calling one of them again, if this condition is not met a `SimpleCsv::RowNotComplete` exception will be thrown
|
|
76
|
-
|
|
77
|
-
| setting | value |
|
|
78
|
-
|------------------------|---------------------------------------|
|
|
79
|
-
|`:force_row_completion` | `true` |
|
|
80
|
-
|
|
81
|
-
#### Setting aliasses
|
|
82
|
-
|
|
83
|
-
An _alias_ can be used instead of it's respective _setting_.
|
|
84
|
-
|
|
85
|
-
| setting | alias |
|
|
86
|
-
|---------------|---------------|
|
|
87
|
-
| `:col_sep` | `:seperator` |
|
|
88
|
-
| `headers` | `has_headers` |
|
|
89
|
-
|
|
90
|
-
#### Converters
|
|
91
|
-
|
|
92
|
-
The above `:converters` option is set to include `:all` converters and additionally, `:blank_to_nil` and `:null_to_nil`
|
|
93
|
-
The code for these two can be summed up in two lines:
|
|
94
|
-
|
|
95
|
-
```ruby
|
|
96
|
-
CSV::Converters[:blank_to_nil] = ->(f) { f && f.empty? ? nil : f }
|
|
97
|
-
CSV::Converters[:null_to_nil] = ->(f) { f && f == 'NULL' ? nil : f }
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
What they do replace empty values or the string `'NULL'` by nil within a column when it's being parsed.
|
|
101
|
-
For now, these are the default two and they are always used unless the `:converters` option is set to `nil` within `SimpleCsv#generate` or `SimpleCsv#read`
|
|
102
|
-
|
|
103
|
-
### Generating a CSV file
|
|
104
|
-
|
|
105
|
-
```ruby
|
|
106
|
-
SimpleCsv.generate path, options = { ... }, &block
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
The `SimpleCsv#generate` method takes a (required) path, an (optional) hash of options and a (required) block to start building a CSV file.
|
|
110
|
-
To generate a CSV file we use `SimpleCsv#generate` (using the [faker](https://github.com/stympy/faker) gem to provide fake data)
|
|
111
|
-
|
|
112
|
-
While writing a row to a CSV, the value of a set property can be accessed by calling that property method again without arguments. (See the "inspect a value" comment in the following example)
|
|
113
|
-
|
|
114
|
-
```ruby
|
|
115
|
-
require 'faker'
|
|
116
|
-
|
|
117
|
-
# use SimpleCsv.generate('output.csv', seperator: '|') to generate a CSV with a pipe character as seperator
|
|
118
|
-
SimpleCsv.generate('output.csv') do
|
|
119
|
-
# first define the headers
|
|
120
|
-
headers :first_name, :last_name, :birth_date, :employed_at
|
|
121
|
-
|
|
122
|
-
# loop something
|
|
123
|
-
100.times do
|
|
124
|
-
# insert data in each field defined in headers to insert a row.
|
|
125
|
-
first_name Faker::Name.first_name
|
|
126
|
-
# inspect a value
|
|
127
|
-
p first_name
|
|
128
|
-
last_name Faker::Name.last_name
|
|
129
|
-
birth_date Faker::Date.between(Date.today << 900, Date.today << 200)
|
|
130
|
-
employed_at [Faker::Company.name, nil].sample
|
|
131
|
-
end
|
|
132
|
-
end
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
### Reading a CSV file
|
|
136
|
-
|
|
137
|
-
```ruby
|
|
138
|
-
SimpleCsv.read path, options = { ... }, &block
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
The `SimpleCsv#generate` method takes a (required) path, an (optional) hash of options and a (required) block to start building a CSV file.
|
|
142
|
-
|
|
143
|
-
To read a CSV file we use `SimpleCsv#read`, we will pass it a file path and a block as arguments.
|
|
144
|
-
Within the block we define the headers present in the file, these will be transformed into methods you can call within `SimpleCsv::Reader#each_row` to get that property's current value
|
|
145
|
-
|
|
146
|
-
```ruby
|
|
147
|
-
SimpleCsv.read('input.csv') do
|
|
148
|
-
# assumes headers are set, they will be read and callable within each_row
|
|
149
|
-
|
|
150
|
-
each_row do
|
|
151
|
-
puts [first_name, last_name, birth_date, employed_at].compact.join ', '
|
|
152
|
-
end
|
|
153
|
-
end
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
### Reading a CSV file without headers
|
|
157
|
-
|
|
158
|
-
Last but not least, if we have a CSV file that does not contain headers we can use the following setup.
|
|
159
|
-
Setting `:has_headers` to `false` means we do not expect the first line to be headers.
|
|
160
|
-
Therefore we have to explicitly define the headers before looping the CSV.
|
|
161
|
-
|
|
162
|
-
```ruby
|
|
163
|
-
SimpleCsv.read('headerless.csv', has_headers: false) do
|
|
164
|
-
# first define the headers in the file manually if the file does not have them
|
|
165
|
-
headers :first_name, :last_name, :birth_date, :employed_at
|
|
166
|
-
|
|
167
|
-
each_row do
|
|
168
|
-
# print each field defined in headers (that is not nil)
|
|
169
|
-
puts [first_name, last_name, birth_date, employed_at].compact.join ', '
|
|
170
|
-
end
|
|
171
|
-
end
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
### Batch operations
|
|
175
|
-
|
|
176
|
-
If we have a large CSV we might want to batch operations (say, if we are inserting this data into a database or through an API).
|
|
177
|
-
For this we can use `SimpleCsv::Reader#in_groups_of` and pass the size of the group.
|
|
178
|
-
Within that we call `SimpleCsv::Reader#each_row` as usual
|
|
179
|
-
|
|
180
|
-
```ruby
|
|
181
|
-
SimpleCsv.read('input.csv') do
|
|
182
|
-
# assumes headers are set, they will be read and callable within each_row
|
|
183
|
-
|
|
184
|
-
in_groups_of(100) do
|
|
185
|
-
each_row do
|
|
186
|
-
puts [first_name, last_name, birth_date, employed_at].compact.join ', '
|
|
187
|
-
end
|
|
188
|
-
# execute after every 100 rows
|
|
189
|
-
sleep 2
|
|
190
|
-
end
|
|
191
|
-
end
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
### Aliassing existing headers
|
|
195
|
-
|
|
196
|
-
Should you want to map existing headers to different names, this is possible by passing a hash at the end with key value pairs.
|
|
197
|
-
When generating a CSV file, aliasses are ignored and therefore should not be passed.
|
|
198
|
-
|
|
199
|
-
When defining columns manually using `headers` for a file without headers, ALL columns must be named before defining aliasses.
|
|
200
|
-
This means that if your CSV exists of 3 columns, 3 headers must be defined before aliassing any of those to something shorter or more concise.
|
|
201
|
-
|
|
202
|
-
To create an alias `date_of_birth` of `birth_date` *(In a CSV file without headers)* we would write *(notice `:birth_date` is present twice, once as column entry, and once more as key for an alias)*:
|
|
203
|
-
|
|
204
|
-
```ruby
|
|
205
|
-
headers :first_name, :last_name, :employed_at, :birth_date, birth_date: :date_of_birth
|
|
206
|
-
```
|
|
207
|
-
|
|
208
|
-
## Development
|
|
209
|
-
|
|
210
|
-
After checking out the repo, run `bundle` to install dependencies. Then, run `rspec` to run the tests. You can also use the `bin/console` file to play around and debug.
|
|
211
|
-
|
|
212
|
-
To install this gem onto your local machine, run `rake install`.
|
|
213
|
-
|
|
214
|
-
To release a new version:
|
|
215
|
-
|
|
216
|
-
* Run CI in dev branch, if tests pass, merge into master
|
|
217
|
-
* Update version number in _lib/simple_csv/version.rb_ according to [symver](http://semver.org/)
|
|
218
|
-
* Update _README.md_ to reflect your changes
|
|
219
|
-
* run `rake release` to push commits, create a tag for the current commit and push the `.gem` file to RubyGems
|
|
220
|
-
|
|
221
|
-
## Contributing
|
|
222
|
-
|
|
223
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/sidofc/simple_csv. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
## License
|
|
227
|
-
|
|
228
|
-
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
|
|
3
|
+
The documentation has been moved here: [https://sidofc.github.io/projects/simple-csv/](https://sidofc.github.io/projects/simple-csv/)
|
data/lib/simple_csv/version.rb
CHANGED
data/simple_csv.gemspec
CHANGED
|
@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
|
|
|
11
11
|
|
|
12
12
|
spec.summary = 'CSV DSL'
|
|
13
13
|
spec.description = 'A simple DSL for reading and generating CSV files'
|
|
14
|
-
spec.homepage = 'https://github.
|
|
14
|
+
spec.homepage = 'https://sidofc.github.io/projects/simple-csv/'
|
|
15
15
|
spec.license = 'MIT'
|
|
16
16
|
|
|
17
17
|
spec.files = `git ls-files -z`.split("\x0").reject do |f|
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: simple_csv
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.2.
|
|
4
|
+
version: 0.2.2
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Sidney Liebrand
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2016-12-
|
|
11
|
+
date: 2016-12-31 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: bundler
|
|
@@ -133,7 +133,7 @@ files:
|
|
|
133
133
|
- lib/simple_csv/version.rb
|
|
134
134
|
- lib/simple_csv/writer.rb
|
|
135
135
|
- simple_csv.gemspec
|
|
136
|
-
homepage: https://github.
|
|
136
|
+
homepage: https://sidofc.github.io/projects/simple-csv/
|
|
137
137
|
licenses:
|
|
138
138
|
- MIT
|
|
139
139
|
metadata: {}
|