README.md in csv2hash-0.6.0 vs README.md in csv2hash-0.6.1
- old
+ new
@@ -24,38 +24,40 @@
$ gem install csv2hash
## Usage
-Parsing is based on rules, you must defined rules of parsing
+Parsing is based on rules, you should defined rule for each cells
### DSL
-Csv2hash::Main.generate_definition :name do
- set_type { Definition::MAPPING }
- set_header_size { 2 } # 0 by default
- set_structure_rules {{ 'MaxColumns' => 2 }}
- mapping do
- cell position: [0,0], key: 'gender'
- cell position: [1,0], key: 'name'
+```
+ Csv2hash::Main.generate_definition :name do
+ set_type { Definition::MAPPING }
+ set_header_size { 2 } # 0 by default
+ set_structure_rules {{ 'MaxColumns' => 2 }}
+ mapping do
+ cell position: [0,0], key: 'gender'
+ cell position: [1,0], key: 'name'
+ end
end
-end
-Csv2hash::Main[:name] # Access anywhere
+ Csv2hash::Main[:name] # Access anywhere
+```
### Rules
-You should declared a definition for you CSV, and then define for each cell what you would expect.
+You should declared a definition of your CSV file, and then define for each cell what you would expect.
Example :
If you want the very first cell, located on the first line and on the first column to be a string with values are either 'yes' either 'no', you can write the following validation rule:
```
cell name: 'aswering', type: 'string', values: ['yes', 'no'], position: [0,0]
```
-:type attribute has 'string' for default value, therefore you can just write this:
+`:type` attribute has `String` for default value, therefore you can just write this:
```
cell name: 'aswering', values: ['yes', 'no'], position: [0,0]
```
@@ -107,11 +109,11 @@
* search for data at a precise position in the table: `y,x`
* or search for data in a column of rows, where all the rows are the same: `x` (column index)
## Samples
-### Validation of cells with defined precision
+### [MAPPING] Validation of cells with defined precision
Consider the following CSV:
| Fields | Person Informations | Optional |
|-------------|----------------------|----------|
@@ -136,25 +138,25 @@
end
private
def definition
- Main.generate_definition :my_defintion do
- set_type { Definition::MAPPING }
- set_header_size { 1 }
- mapping do
- cell position: [2,1], key: 'first_name'
- cell position: [3,1], key: 'last_name'
- end
- end
- end
+ Main.generate_definition :my_defintion do
+ set_type { Definition::MAPPING }
+ set_header_size { 1 }
+ mapping do
+ cell position: [2,1], key: 'first_name'
+ cell position: [3,1], key: 'last_name'
+ end
+ end
+ end
end
end
```
-### Validation of a collection (Regular CSV)
+### [COLLECTION] Validation of a collection (Regular CSV)
Consider the following CSV:
| Nickname | First Name | Last Name |
|----------|------------|-----------|
@@ -180,30 +182,30 @@
def definition
Csv2Hash::Definition.new(rules, type = Csv2Hash::Definition::COLLECTION, header_size: 1)
end
- def definition
- Main.generate_definition :my_defintion do
- set_type { Definition::COLLECTION }
- set_header_size { 1 }
- mapping do
- cell position: 0, key: 'nickname'
- cell position: 1, key: 'first_name'
- cell position: 2, key: 'last_name'
- end
- end
- end
- end
+ def definition
+ Main.generate_definition :my_defintion do
+ set_type { Definition::COLLECTION }
+ set_header_size { 1 }
+ mapping do
+ cell position: 0, key: 'nickname'
+ cell position: 1, key: 'first_name'
+ cell position: 2, key: 'last_name'
+ end
+ end
+ end
+ end
end
```
### Structure validation rules
You may want to validate some structure, like min or max number of columns, definition accepts structure_rules as a key for the third parameter.
-Current validations are: MinColumn, MaxColumn
+Current validations are: :min_columns, :max_columns
```
class MyParser
attr_accessor :file_path_or_data
@@ -220,11 +222,11 @@
def definition
Main.generate_definition :my_defintion do
set_type { Definition::COLLECTION }
set_header_size { 1 }
- set_structure_rules {{ 'MinColumns' => 2, 'MaxColumns' => 3 }}
+ set_structure_rules {{ min_columns: 2, max_columns: 3 }}
mapping do
cell position: 0, key: 'nickname'
cell position: 1, key: 'first_name'
cell position: 2, key: 'last_name'
end
@@ -248,22 +250,22 @@
```
definition, file_path_or_data, ignore_blank_line: false
```
-in file_path_or_data attribute you can pass directly an Array of data (Array with 2 dimensions) really useful for testing, if you don't care about blank lines in your CSV you can ignore them.
+in `file_path_or_data` attribute you can pass directly an `Array` of data (`Array` with 2 dimensions) really useful for testing, if you don't care about blank lines in your CSV you can ignore them.
### Response
-The parser return values wrapper into DataWrapper Object, you can call ```.valid?``` method on this Object and grab either data or errors like that :
+The parser return values wrapper into `DataWrapper Object`, you can call ```.valid?``` method on this Object and grab either data or errors like that :
```
response = parser.parse
if response.valid?
response.data
else
- response.errors
+ response.errors
end
```
data or errors are Array, but errors can be formatted on csv format with .to_csv call
@@ -271,11 +273,11 @@
response.errors.to_csv
```
## Exception or Not !
-You can choose into 2 different modes of parsing, either **break_on_failure mode** for raise exception in first breaking rules or **csv mode** for get csv original data + errors throwing into added columns.
+You can choose into 2 differents modes of parsing, either **break_on_failure mode** for throw an exception when rule fail or **csv mode** for get csv original data + errors throwing into added extra column.
### On **BREAK_ON_FAILURE MODE**
You need call ```.parse()``` with bang ```!```
@@ -335,11 +337,11 @@
| Nickname | nil |
### Rule
```
- { position: [1,1], key: 'nickname', allow_blank: false }
+ cell position: [1,1], key: 'nickname', allow_blank: false
```
### Error
```
@@ -371,103 +373,16 @@
```
[ [ 'Foo' ] ]
```
-# Upgrading
+# Changes
-# Upgrading from 0.5 to 0.6
+please refere to [CHANGELOG.md](https://github.com/FinalCAD/csv2hash/blob/master/CHANGELOG.md) doc
-Introduce DSL
+# Upgrading
-Prior to 0.6 :
-
-```
- rules = [{ position: [0,0], key: 'name' }]
- Csv2hash::Definition.new(rules, Definition::MAPPING, options={})
-
-```
-
-Starting from 0.6 :
-
-```
- Csv2hash::Main.generate_definition :foo do
- set_type { Definition::MAPPING }
- mapping { cell position: [0,0], key: 'name' }
- end
- Csv2hash::Main[:foo] # Access anywhere
-```
-
-# Upgrading from 0.4 to 0.5
-
-Signature of ```Csv2hash::Main#new``` has changed too
-
-Prior to 0.5 :
-
-```
- Csv2Hash::Main.new(definition, file_path_or_data, ignore_blank_line=false)
-```
-
-Starting from 0.5 :
-
-```
- Csv2Hash::Main.new(definition, file_path_or_data, ignore_blank_line: false)
-```
-
-# Upgrading from 0.3 to 0.4
-
-Signature of ```Csv2hash::Main#new``` has changed too
-
-Prior to 0.4 :
-
-```
- Csv2Hash::Main.new(definition, file_path_or_data, break_on_failure=true, ignore_blank_line=false)
-```
-
-call ```.parse!``` for same result
-
-Starting from 0.4 :
-
-```
- Csv2Hash::Main.new(definition, file_path_or_data, ignore_blank_line=false)
-```
-
-call ```.parse``` for same result
-
-# Upgrading from 0.2 to 0.3
-
-```Csv2hash``` become an ```Module```, ```Csv2hash.new``` no longer works, please use ```Csv2hash::Main.new``` instead.
-Signature of ```Csv2hash::Main#new``` has changed too
-
-Prior to 0.3 :
-
-```
- Csv2Hash.new(definition, file_path, break_on_failure=true, data_source=nil, ignore_blank_line=false)
-```
-
-Starting from 0.3 :
-
-```
- Csv2Hash::Main.new(definition, file_path_or_data, break_on_failure=true, ignore_blank_line=false)
-```
-
-# Upgrading from 0.1 to 0.2
-
-The signature of Definition#new has changed, the last parameter is a configuration hash, while in versions prior to 0.2 it was an integer (header_size) consider upgrading your code :
-
-Prior to 0.2 :
-
-```
- Csv2Hash::Definition.new(rules, type = Csv2Hash::Definition::COLLECTION, 1)
-```
-
-Starting from 0.2 :
-
-```
- Csv2Hash::Definition.new(rules, type = Csv2Hash::Definition::COLLECTION, header_size: 1)
-```
-
-If no configuration is passed, header_size defaults remains to 0
+please refere to [UPGRADE.md](https://github.com/FinalCAD/csv2hash/blob/master/UPGRADE.md) doc
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)