Documentation ¶
Overview ¶
Package gocnab implements encoding and decoding of CNAB (Centro Nacional de Automação Bancária) as defined by FEBRABAN (Federação Brasileira de Bancos).
Index ¶
- Constants
- Variables
- func Marshal150(vs ...interface{}) ([]byte, error)
- func Marshal240(vs ...interface{}) ([]byte, error)
- func Marshal400(vs ...interface{}) ([]byte, error)
- func Marshal500(vs ...interface{}) ([]byte, error)
- func Unmarshal(data []byte, v interface{}) error
- type FieldError
- type MarshalOptionFunc
- type MarshalOptions
- type Marshaler
- type UnmarshalFieldError
- type Unmarshaler
Examples ¶
Constants ¶
const FinalControlCharacter = "\x1A"
FinalControlCharacter defines the control character of the last registry entry. It should be the hex encoded 1A.
const LineBreak = "\r\n"
LineBreak defines the control characters at the end of each registry entry. It should be the hex encoded 0D0A except for the last one.
Variables ¶
var ( // ErrUnsupportedType raised when trying to marshal something different from a // struct or a slice. ErrUnsupportedType = errors.New("gocnab: unsupported type") // ErrInvalidFieldTagFormat CNAB field tag doesn't follow the expected format. ErrInvalidFieldTagFormat = errors.New("invalid field tag format") // ErrInvalidFieldTagBeginRange begin range isn't a valid number in the CNAB // tag. ErrInvalidFieldTagBeginRange = errors.New("invalid begin range in cnab tag") // ErrInvalidFieldTagEndRange end range isn't a valid number in the CNAB tag. ErrInvalidFieldTagEndRange = errors.New("invalid end range in cnab tag") // ErrInvalidFieldTagRange ranges don't have consistency with the desired // encoding in the CNAB tag. ErrInvalidFieldTagRange = errors.New("invalid range in cnab tag") )
Functions ¶
func Marshal150 ¶
func Marshal240 ¶
Marshal240 returns the CNAB 240 encoding of vs. The accepted types are struct and slice of struct, where only the exported struct fields with the tag "cnab" are going to be used. Invalid cnab tag ranges will generate errors.
The following struct field types are supported: string, bool, int, int8, int16, int32, int64, uint, uint8, uint16, uint23, uint64, float32, float64, gocnab.Marshaler and encoding.TextMarshaler. Where string are transformed to uppercase and are left aligned in the CNAB space, booleans are represented as 1 or 0, numbers are right aligned with zeros and float decimal separators are removed.
When only one parameter is given the generated CNAB line will only have break line symbols if the input is a slice of struct. When using multiple parameters the library determinate that you are trying to build the full CNAB file, so it add the breaking lines and the final control symbol.
Example ¶
package main import ( "fmt" "github.com/ammeg/gocnab" ) func main() { e := struct { FieldA int `cnab:"0,20"` FieldB string `cnab:"20,50"` FieldC float64 `cnab:"50,60"` FieldD uint `cnab:"60,70"` FieldE bool `cnab:"70,71"` }{ FieldA: 123, FieldB: "This is a text", FieldC: 50.30, FieldD: 445, FieldE: true, } data, _ := gocnab.Marshal240(e) fmt.Println(string(data)) }
Output: 00000000000000000123THIS IS A TEXT 000000503000000004451
Example (FullFile) ¶
package main import ( "fmt" "github.com/ammeg/gocnab" ) func main() { header := struct { Identifier string `cnab:"0,1"` HeaderA int `cnab:"1,5"` }{ HeaderA: 2, } content := []struct { Identifier string `cnab:"0,1"` FieldA int `cnab:"1,20"` FieldB string `cnab:"20,50"` FieldC float64 `cnab:"50,60"` FieldD uint `cnab:"60,70"` FieldE bool `cnab:"70,71"` }{ { FieldA: 123, FieldB: "This is a text", FieldC: 50.30, FieldD: 445, FieldE: true, }, { FieldA: 321, FieldB: "This is another text", FieldC: 30.50, FieldD: 544, FieldE: false, }, } footer := struct { Identifier string `cnab:"0,1"` FooterA string `cnab:"5,30"` }{ FooterA: "Final text", } data, _ := gocnab.Marshal240(header, content, footer) fmt.Println(string(data)) }
Output:
func Marshal400 ¶
Marshal400 returns the CNAB 400 encoding of vs. The accepted types are struct and slice of struct, where only the exported struct fields with the tag "cnab" are going to be used. Invalid cnab tag ranges will generate errors.
The following struct field types are supported: string, bool, int, int8, int16, int32, int64, uint, uint8, uint16, uint23, uint64, float32, float64, gocnab.Marshaler and encoding.TextMarshaler. Where string are transformed to uppercase and are left aligned in the CNAB space, booleans are represented as 1 or 0, numbers are right aligned with zeros and float decimal separators are removed.
When only one parameter is given the generated CNAB line will only have break line symbols if the input is a slice of struct. When using multiple parameters the library determinate that you are trying to build the full CNAB file, so it add the breaking lines and the final control symbol.
Example ¶
package main import ( "fmt" "github.com/ammeg/gocnab" ) func main() { e := struct { FieldA int `cnab:"0,20"` FieldB string `cnab:"20,50"` FieldC float64 `cnab:"50,60"` FieldD uint `cnab:"60,70"` FieldE bool `cnab:"70,71"` }{ FieldA: 123, FieldB: "This is a text", FieldC: 50.30, FieldD: 445, FieldE: true, } data, _ := gocnab.Marshal400(e) fmt.Println(string(data)) }
Output: 00000000000000000123THIS IS A TEXT 000000503000000004451
Example (FullFile) ¶
package main import ( "fmt" "github.com/ammeg/gocnab" ) func main() { header := struct { Identifier string `cnab:"0,1"` HeaderA int `cnab:"1,5"` }{ HeaderA: 2, } content := []struct { Identifier string `cnab:"0,1"` FieldA int `cnab:"1,20"` FieldB string `cnab:"20,50"` FieldC float64 `cnab:"50,60"` FieldD uint `cnab:"60,70"` FieldE bool `cnab:"70,71"` }{ { FieldA: 123, FieldB: "This is a text", FieldC: 50.30, FieldD: 445, FieldE: true, }, { FieldA: 321, FieldB: "This is another text", FieldC: 30.50, FieldD: 544, FieldE: false, }, } footer := struct { Identifier string `cnab:"0,1"` FooterA string `cnab:"5,30"` }{ FooterA: "Final text", } data, _ := gocnab.Marshal400(header, content, footer) fmt.Println(string(data)) }
Output:
func Marshal500 ¶
Marshal500 returns the CNAB 500 encoding of vs. The accepted types are struct and slice of struct, where only the exported struct fields with the tag "cnab" are going to be used. Invalid cnab tag ranges will generate errors.
The following struct field types are supported: string, bool, int, int8, int16, int32, int64, uint, uint8, uint16, uint23, uint64, float32, float64, gocnab.Marshaler and encoding.TextMarshaler. Where string are transformed to uppercase and are left aligned in the CNAB space, booleans are represented as 1 or 0, numbers are right aligned with zeros and float decimal separators are removed.
When only one parameter is given the generated CNAB line will only have break line symbols if the input is a slice of struct. When using multiple parameters the library determinate that you are trying to build the full CNAB file, so it add the breaking lines and the final control symbol.
func Unmarshal ¶
Unmarshal parses the CNAB-encoded data and stores the result in the value pointed to by v. Accepted types of v are: *struct, *[]struct or map[string]interface{}.
The following struct field types are supported: string, bool, int, int8, int16, int32, int64, uint, uint8, uint16, uint23, uint64, float32, float64, gocnab.Unmarshaler and encoding.TextUnmarshaler.
When parsing a full CNAB file we recommend using the map type (mapper) to fill different lines into the correct types. Usually the CNAB prefix determinate the type used, so the mapper key will be the prefix, and the mapper value is the pointer to the type that you're filling. For example, if we have a CNAB file where the starter character determinate the type, and for "0" is header, "1" is the content line (can repeat many times) and "2" is the footer, we could have the following code to unmarshal:
header := struct{ A int `cnab:1,10` }{} content := []struct{ B string `cnab:1,10` }{} footer := struct{ C bool `cnab:1,2` }{} cnab.Unmarshal(data, map[string]interface{}{ "0": &header, "1": &content, "2": &footer, })
Example ¶
package main import ( "fmt" "github.com/ammeg/gocnab" ) func main() { var e struct { FieldA int `cnab:"0,20"` FieldB string `cnab:"20,50"` FieldC float64 `cnab:"50,60"` FieldD uint `cnab:"60,70"` FieldE bool `cnab:"70,71"` } data := []byte("00000000000000000123THIS IS A TEXT 000000503000000004451") if err := gocnab.Unmarshal(data, &e); err != nil { fmt.Println(err) return } fmt.Printf("%v\n", e) }
Output: {123 THIS IS A TEXT 50.3 445 true}
Example (FullFile) ¶
package main import ( "fmt" "github.com/ammeg/gocnab" ) func main() { header := struct { Identifier int `cnab:"0,1"` HeaderA int `cnab:"1,5"` }{} content := []struct { Identifier int `cnab:"0,1"` FieldA int `cnab:"1,20"` FieldB string `cnab:"20,50"` FieldC float64 `cnab:"50,60"` FieldD uint `cnab:"60,70"` FieldE bool `cnab:"70,71"` }{} footer := struct { Identifier int `cnab:"0,1"` FooterA string `cnab:"5,30"` }{} data := []byte("00005" + gocnab.LineBreak + "10000000000000000123THIS IS A TEXT 1 000000503000000004451" + gocnab.LineBreak + "10000000000000000321THIS IS A TEXT 2 000000305000000005440" + gocnab.LineBreak + "2 THIS IS THE FOOTER " + gocnab.FinalControlCharacter) err := gocnab.Unmarshal(data, map[string]interface{}{ "0": &header, "1": &content, "2": &footer, }) if err != nil { fmt.Println(err) return } fmt.Printf("%v\n%v\n%v\n", header, content, footer) }
Output: {0 5} [{1 123 THIS IS A TEXT 1 50.3 445 true} {1 321 THIS IS A TEXT 2 30.5 544 false}] {2 THIS IS THE FOOTER}
Types ¶
type FieldError ¶
FieldError problem detected in a field tag containing CNAB options or when marshalling the field itself.
func (FieldError) Error ¶
func (f FieldError) Error() string
Error return a human readable representation of the field error.
type MarshalOptionFunc ¶
type MarshalOptionFunc func(*MarshalOptions)
MarshalOptionFunc helper type alias to handle options.
func WithFinalControlCharacter ¶
func WithFinalControlCharacter(enabled bool) MarshalOptionFunc
WithFinalControlCharacter allows to enable or disable the final control character. The first version of this library was designed to build valid CNAB files for Bradesco bank, and one of Bradesco's requirements was to contain the final control hexadecimal character 1A. But as this library started being used by other integrations, the final control character became an issue, as it doesn't comply with other specifications. By default, the final control character is added to keep backward compatibility.
type MarshalOptions ¶
type MarshalOptions struct {
// contains filtered or unexported fields
}
MarshalOptions contains available options when marshaling. The properties can be modified using auxiliary functions directly into the marshal calls.
Example:
Marshal240(myCNABType, gocnab.WithFinalControlCharacter(false))
type Marshaler ¶
Marshaler is the interface implemented by types that can marshal themselves into valid string representation.
type UnmarshalFieldError ¶
UnmarshalFieldError stores the error that occurred while decoding the CNAB data into a field.
func (UnmarshalFieldError) Error ¶
func (u UnmarshalFieldError) Error() string
Error return a human readable representation of the unmarshal error.
type Unmarshaler ¶
Unmarshaler is the interface implemented by types that can unmarshal a string representation description of themselves. UnmarshalCNAB must copy the CNAB data if it wishes to retain the data after returning.