README
¶
What is csv package?
The csv package is a library for performing validation when reading CSV or TSV files. Validation rules are specified using struct tags. The csv package read returns which columns of which rows do not adhere to the specified rules.
Why need csv package?
I was frustrated with error-filled CSV files written by non-engineers.
I encountered a use case of "importing one CSV file into multiple DB tables". Unfortunately, I couldn't directly import the CSV file into the DB tables. So, I attempted to import the CSV file through a Go-based application.
What frustrated me was not knowing where the errors in the CSV file were. Existing libraries didn't provide output like "The value in the Mth column of the Nth row is incorrect". I attempted to import multiple times and processed error messages one by one. Eventually, I started writing code to parse each column, which wasted a considerable amount of time.
Based on the above experience, I decided to create a generic CSV validation tool.
How to use
Please attach the "validate:" tag to your structure and write the validation rules after it. It's crucial that the "order of columns" matches the "order of field definitions" in the structure. The csv package does not automatically adjust the order.
When using csv.Decode, please pass a pointer to a slice of structures tagged with struct tags. The csv package will perform validation based on the struct tags and save the read results to the slice of structures if there are no errors. If there are errors, it will return them as []error.
package main
import (
"bytes"
"fmt"
"github.com/nao1215/csv"
)
func main() {
input := `id,name,age
1,Gina,23
a,Yulia,25
3,Den1s,30
`
buf := bytes.NewBufferString(input)
c, err := csv.NewCSV(buf)
if err != nil {
panic(err)
}
type person struct {
ID int `validate:"numeric"`
Name string `validate:"alpha"`
Age int `validate:"gt=24"`
}
people := make([]person, 0)
errs := c.Decode(&people)
if len(errs) != 0 {
for _, err := range errs {
fmt.Println(err.Error())
}
}
// Output:
// line:2 column age: target is not greater than the threshold value: threshold=24.000000, value=23.000000
// line:3 column id: target is not a numeric character: value=a
// line:4 column name: target is not an alphabetic character: value=Den1s
}
Struct tags
You set the validation rules following the "validate:" tag according to the rules in the table below. If you need to set multiple rules, please enumerate them separated by commas.
Validation rule without arguments
| Tag Name | Description |
|---|---|
| boolean | Check whether value is boolean or not. |
| alpha | Check whether value is alphabetic or not |
| numeric | Check whether value is numeric or not |
| alphanumeric | Check whether value is alphanumeric or not |
| required | Check whether value is empty or not |
Validation rule with numeric argument
| Tag Name | Description |
|---|---|
| eq | Check whether value is equal to the specified value. e.g. validate:"eq=1" |
| ne | Check whether value is not equal to the specified value e.g. validate:"ne=1" |
| gt | Check whether value is greater than the specified value e.g. validate:"gt=1" |
| gte | Check whether value is greater than or equal to the specified value e.g. validate:"gte=1" |
| lt | Check whether value is less than the specified value e.g. validate:"lt=1" |
| lte | Check whether value is less than or equal to the specified value e.g. validate:"lte=1" |
| min | Check whether value is greater than or equal to the specified value e.g. validate:"min=1" |
| max | Check whether value is less than or equal to the specified value e.g. validate:"max=100" |
| len | Check whether the length of the value is equal to the specified value e.g. validate:"len=10" |
| oneof | Check whether value is included in the specified values e.g. validate:"oneof=male female prefer_not_to" |
License
Contribution
First off, thanks for taking the time to contribute! Contributions are not only related to development. For example, GitHub Star motivates me to develop! Please feel free to contribute to this project.
Special Thanks
I was inspired by the following OSS. Thank you for your great work!
Contributors ✨
Thanks goes to these wonderful people (emoji key):
 CHIKAMATSU Naohiro 📖 |
||||||
Add your contributions
|
||||||
This project follows the all-contributors specification. Contributions of any kind welcome!
Documentation
¶
Overview ¶
Package csv returns which columns have syntax errors on a per-line basis when reading CSV. It also has the capability to convert the character encoding to UTF-8 if the CSV character encoding is not UTF-8.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrStructSlicePointer is returned when the value is not a pointer to a struct slice. ErrStructSlicePointer = errors.New("value is not a pointer to a struct slice") // ErrInvalidOneOfFormat is returned when the target is not one of the values. ErrInvalidOneOfFormat = errors.New("target is not one of the values") // ErrInvalidThresholdFormat is returned when the threshold value is not an integer. ErrInvalidThresholdFormat = errors.New("threshold format is invalid") // ErrInvalidBoolean is returned when the target is not a boolean. ErrInvalidBoolean = errors.New("target is not a boolean") // ErrInvalidAlphabet is returned when the target is not an alphabetic character. ErrInvalidAlphabet = errors.New("target is not an alphabetic character") // ErrInvalidNumeric is returned when the target is not a numeric character. ErrInvalidNumeric = errors.New("target is not a numeric character") // ErrInvalidAlphanumeric is returned when the target is not an alphanumeric character. ErrInvalidAlphanumeric = errors.New("target is not an alphanumeric character") // ErrRequired is returned when the target is required but is empty. ErrRequired = errors.New("target is required but is empty") // ErrEqual is returned when the target is not equal to the value. ErrEqual = errors.New("target is not equal to the threshold value") // ErrInvalidThreshold is returned when the target is not greater than the value. ErrInvalidThreshold = errors.New("threshold value is invalid") // ErrNotEqual is returned when the target is equal to the value. ErrNotEqual = errors.New("target is equal to threshold the value") // ErrGreaterThan is returned when the target is not greater than the value. ErrGreaterThan = errors.New("target is not greater than the threshold value") // ErrGreaterThanEqual is returned when the target is not greater than or equal to the value. ErrGreaterThanEqual = errors.New("target is not greater than or equal to the threshold value") // ErrLessThan is returned when the target is not less than the value. ErrLessThan = errors.New("target is not less than the threshold value") // ErrLessThanEqual is returned when the target is not less than or equal to the value. ErrLessThanEqual = errors.New("target is not less than or equal to the threshold value") // ErrMin is returned when the target is less than the minimum value. ErrMin = errors.New("target is less than the minimum value") // ErrMax is returned when the target is greater than the maximum value. ErrMax = errors.New("target is greater than the maximum value") // ErrLength is returned when the target length is not equal to the value. ErrLength = errors.New("target length is not equal to the threshold value") // ErrOneOf is returned when the target is not one of the values. ErrOneOf = errors.New("target is not one of the values") )
Functions ¶
This section is empty.
Types ¶
type CSV ¶
type CSV struct {
// contains filtered or unexported fields
}
CSV is a struct that implements CSV Reader and Writer.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/nao1215/csv"
)
func main() {
input := `id,name,age
1,Gina,23
a,Yulia,25
3,Den1s,30
`
buf := bytes.NewBufferString(input)
c, err := csv.NewCSV(buf)
if err != nil {
panic(err)
}
type person struct {
ID int `validate:"numeric"`
Name string `validate:"alpha"`
Age int `validate:"gt=24"`
}
people := make([]person, 0)
errs := c.Decode(&people)
if len(errs) != 0 {
for _, err := range errs {
fmt.Println(err.Error())
}
}
}
Output: line:2 column age: target is not greater than the threshold value: threshold=24.000000, value=23.000000 line:3 column id: target is not a numeric character: value=a line:4 column name: target is not an alphabetic character: value=Den1s
type Option ¶
Option is a function that sets a configuration option for CSV struct.
func WithHeaderless ¶
func WithHeaderless() Option
WithHeaderless is an Option that sets the headerless flag to true.
func WithTabDelimiter ¶
func WithTabDelimiter() Option
WithTabDelimiter is an Option that sets the delimiter to a tab character.
Source Files