br

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: MIT Imports: 9 Imported by: 0

README

Arandu

Arandu BR

The Brazilian values an Arandu application takes from a form and prints on a page: the CPF, the CNPJ (numeric and alphanumeric), the CEP, an amount in reais, a date, and the federative unit.

It is a library. It registers no route, owns no table and decides no authorization, so there is nothing to wire in bootstrap/app.go, nothing to construct, and no aru migrate to run. An application imports it and calls it.

Install

go get github.com/hyz-is/arandu-br
import br "github.com/hyz-is/arandu-br"

The module requires Hesape and nothing else. arandu.mod.toml declares no capability: no network, no filesystem, no process, no migration.

Validate a form

The package registers four rules with hesape/validation when it is initialized. Name them by their constants:

var StoreCustomer = validation.MustCompile(validation.Rules{
	"cpf":      "required|" + br.RuleCPF,
	"cnpj":     "nullable|" + br.RuleCNPJ,
	"document": "required|" + br.RuleCPFOrCNPJ,
	"postcode": "required|" + br.RuleCEP,
})
constant rule accepts
br.RuleCPF cpf a CPF, 00000000000 or 000.000.000-00
br.RuleCNPJ cnpj a CNPJ, 00000000000000 or 00.000.000/0000-00, letters allowed in the first twelve positions
br.RuleCPFOrCNPJ cpf_or_cnpj either of the two
br.RuleCEP cep a CEP, 00000000 or 00000-000

Write the constant, not the word it holds. A rule name exists once it is in the catalogue, and a rule set is compiled in a package-level variable, before main. Naming br.RuleCPF imports this package into the file that declares the set, and Go initializes an imported package before the variables of the one importing it, so the rules are registered before the set is compiled. The word "cpf" in a package that does not import this one may be compiled first, and then the application refuses to boot with an unknown rule.

Each rule checks what the matching Parse function checks, takes no argument (cpf:anything refuses every value) and only a string: a CPF sent as a JSON number has already lost its leading zeros. A blank value is left to required or nullable.

A failure reads is not a valid CPF (CNPJ, CPF or CNPJ, CEP). An application that speaks Portuguese names its own sentence under validation.cpf, validation.cnpj, validation.cpf_or_cnpj and validation.cep in its translations, which hesape/validation reads before the default.

Take a value in

cpf, err := br.ParseCPF(in.String("cpf"))    // eleven digits, bare
cnpj, err := br.ParseCNPJ(in.String("cnpj")) // fourteen characters, bare, letters in capitals
cep, err := br.ParseCEP(in.String("postcode"))

Each Parse function returns the bare spelling, which is the one to store, or ErrInvalidCPF, ErrInvalidCNPJ or ErrInvalidCEP. ValidCPF, ValidCNPJ and ValidCEP answer the same question with a bool.

What is accepted is deliberately narrow: the value bare, or in its one conventional punctuation, and nothing else. No other separator, no separator out of place, no whitespace around it — a form that trimmed or re-punctuated input would accept a value the person did not type.

  • CPF — the two check digits the Receita Federal computes. The eleven repetitions of one digit compute too and belong to nobody, so they are refused by name.
  • CNPJ — the alphanumeric scheme: twelve digits or capital letters, each worth its ASCII code minus 48, then two numeric check digits. The numeric CNPJ is the all-digit case and is checked by the same computation. A lower-case letter is read as its capital. Fourteen repetitions of one character are refused.
  • CEP — eight digits, and not below 01000-000, where the Correios ranges begin. There is no check digit, so a CEP that passes may still address nothing.

None of them says whether a document was issued, is regular or exists: that is a question for the Receita Federal or the Correios, and this package makes no call.

CPFCheckDigits and CNPJCheckDigits compute the check digits of a base, which is what a seeder or a factory needs to write a valid document without borrowing somebody's.

Print a value

br.CPF("11122233344")      // "111.222.333-44", check digits or not
br.CNPJ("12abc34501de35")  // "12.ABC.345/01DE-35"
br.CEP("70040010")         // "70040-010"
br.BRL(123456)             // "R$ 1.234,56"
br.BRL(-99)                // "-R$ 0,99"
br.Date(t.In(saoPaulo))    // "31/12/2026"

CPF, CNPJ and CEP punctuate a value of the right shape and return anything else unchanged: they format and do not validate, so a page that prints a stored value shows what is stored.

BRL takes centavos as an int64 — an amount that has to add up is held as an integer — and writes every one, the most negative included. It writes the same string as number.CurrencyFromCents(cents, "BRL") with the process-wide locale set to pt-BR, and depends on no process-wide setting.

Date writes the day t holds in its own location. A time read from the database is usually in UTC, where a late evening in Brasília is already the next day, so convert it with t.In(location) first.

The federative units

br.UF is the closed set of the twenty-seven units, shaped like an enum aru make:enum writes:

br.UFSP.String()  // "SP"
br.UFSP.Label()   // "São Paulo"
uf, err := br.ParseUF(in.String("uf")) // exact code, in capitals, or ErrInvalidUF

br.UFValues() lists them in the alphabetical order of their names. The type satisfies enum.Enum, so the rest of the collection reads it without a second list:

enum.Options(br.UFValues()...)        // the options of a select
validation.EnumOf(br.UFValues()...)   // the rule

As a column, Value and Scan refuse a code outside the set.

What this package does not do

reached for why not
New, a Module, a line in k.Register there is nothing to register: no route, no table, no policy
a lookup at the Receita Federal or the Correios a validator that calls out is a validator that fails when the network does, and the manifest declares network = false
accepting 123.456.789 09, 01000-000 or full-width digits the caller would store a value the person did not type
a float64 amount BRL takes centavos; a float has already rounded
reading the process locale the same call would print differently depending on what another part of the application set

Layout

cpf.go, cnpj.go, cep.go   parsing, check digits and punctuation
shape.go                  the masks the three share
rules.go                  the hesape/validation rules
money.go, date.go         BRL and Date
uf.go                     the UF enum

Tests

GOWORK=off go test -race ./...

Every valid document in the suite is generated from a fixed seed by an oracle written apart from the package, from the Receita Federal's weight tables; none is copied from anywhere. The parsers are fuzzed against that oracle:

GOWORK=off go test -run='^$' -fuzz='^FuzzParseCNPJ$' -fuzztime=30s ./tests/Unit

Licence

MIT. See LICENSE.md. Copyright Paulo R. Lima.

Documentation

Overview

Package br validates and formats the Brazilian values an application takes from a form and prints on a page: the CPF, the CNPJ, the CEP, an amount in reais, a date, and the federative unit.

It is a library. It registers no route, owns no table and decides no authorization, so nothing about it goes in bootstrap/app.go: a caller imports it and calls it.

Taking a value in

ParseCPF, ParseCNPJ and ParseCEP read a value written bare or in its one conventional punctuation, and return the bare spelling to store. ValidCPF, ValidCNPJ and ValidCEP are the same question answered with a bool. The CPF and the CNPJ are checked against the check digits the Receita Federal computes; the CNPJ may be alphanumeric.

The same checks are rules of hesape/validation, registered when this package is initialized and named by RuleCPF, RuleCNPJ, RuleCPFOrCNPJ and RuleCEP:

var StoreCustomer = validation.MustCompile(validation.Rules{
	"document": "required|" + br.RuleCPFOrCNPJ,
	"postcode": "required|" + br.RuleCEP,
})

Printing a value

CPF, CNPJ and CEP punctuate a stored value; BRL writes centavos as reais, R$ 1.234,56; Date writes a day as 31/12/2026. Each is a function of its argument alone.

UF is the closed set of the twenty-seven units, in the shape hesape/enum reads: UFValues, Label for the name a form shows, and Value and Scan for a column.

The files are laid out by subject:

cpf.go, cnpj.go, cep.go  -> parsing, check digits and punctuation
shape.go                 -> the masks the three share
rules.go                 -> the hesape/validation rules
money.go, date.go        -> BRL and Date
uf.go                    -> the UF enum

Index

Constants

View Source
const (
	// RuleCPF is a CPF, as ParseCPF accepts it.
	RuleCPF = "cpf"
	// RuleCNPJ is a CNPJ, numeric or alphanumeric, as ParseCNPJ accepts it.
	RuleCNPJ = "cnpj"
	// RuleCPFOrCNPJ is a value either ParseCPF or ParseCNPJ accepts: the
	// document field of a form a person or a company fills in.
	RuleCPFOrCNPJ = "cpf_or_cnpj"
	// RuleCEP is a CEP, as ParseCEP accepts it.
	RuleCEP = "cep"
)

The names this package registers with hesape/validation, for a rule string:

var StoreCustomer = validation.MustCompile(validation.Rules{
	"document": "required|" + br.RuleCPFOrCNPJ,
	"postcode": "required|" + br.RuleCEP,
})

Write the constant rather than the name it holds. A rule name is real only once it is in the catalogue, and the catalogue is filled when this package is initialized: a rule set that names the constant imports the package, and Go initializes an imported package before the importer's own variables, so the set is compiled after the rules exist. A rule set that spells "cpf" in a package that does not import this one may be compiled first, and then it fails at boot with an unknown rule.

Each rule takes no argument; one written after a colon refuses every value, because an argument this package would ignore is a typo nothing reports. Each accepts what the matching Parse function accepts, and only a string: a CPF sent as a JSON number has already lost its leading zeros. A blank value is not checked -- write required, or nullable, beside the rule for that.

Variables

View Source
var ErrInvalidCEP = errors.New("br: not a valid CEP")

ErrInvalidCEP is what ParseCEP returns for a value that is not a CEP.

View Source
var ErrInvalidCNPJ = errors.New("br: not a valid CNPJ")

ErrInvalidCNPJ is what ParseCNPJ and CNPJCheckDigits return for a value that is not a CNPJ.

View Source
var ErrInvalidCPF = errors.New("br: not a valid CPF")

ErrInvalidCPF is what ParseCPF and CPFCheckDigits return for a value that is not a CPF. It says nothing about which part was wrong, because the person who typed the value is the only one who can tell a typo from a wrong number.

View Source
var ErrInvalidUF = errors.New("br: not a UF")

ErrInvalidUF is what ParseUF, Value and Scan return for a code outside the set.

Functions

func BRL

func BRL(cents int64) string

BRL writes an amount of reais held as a count of centavos, the way a Brazilian page prints money: R$ 1.234,56.

A dot separates each three digits of the reais, a comma stands before the two digits of the centavos, and the symbol leads with a space after it. A negative amount leads with the sign, before the symbol -- -R$ 1.234,56 -- because a sign written after the symbol reads as part of the amount. Zero is R$ 0,00, and every int64 is written, its most negative value included.

The amount is an integer because an amount that has to add up is held as one; no float64 appears on the way from it to the page. The result depends on nothing but the argument: hesape/number writes the same string from CurrencyFromCents(cents, "BRL") only while the process-wide locale is pt-BR, and a library cannot set that locale without setting it for everything else the application formats.

func CEP

func CEP(s string) string

CEP writes a CEP punctuated, as 00000-000.

It takes the eight digits bare or already punctuated, and returns anything else unchanged: it formats, and does not validate. Validate with ParseCEP where the value is taken in.

func CNPJ

func CNPJ(s string) string

CNPJ writes a CNPJ punctuated, as 00.000.000/0000-00, with its letters in capitals.

It takes the fourteen characters bare or already punctuated, and returns anything else unchanged: it formats, and does not validate. Validate with ParseCNPJ where the value is taken in.

func CNPJCheckDigits

func CNPJCheckDigits(base string) (string, error)

CNPJCheckDigits returns the two check digits of a CNPJ whose first twelve characters are base, and ErrInvalidCNPJ when base is not twelve digits or letters. A lower-case letter is read as its capital.

Each character is worth its ASCII code minus 48 -- a digit its own value, A seventeen, Z forty-two. A check digit is the sum of the characters before it, weighted from the right by 2 to 9 and again from 2, taken modulo eleven: a remainder below two gives zero, and any other gives eleven minus it.

func CPF

func CPF(s string) string

CPF writes a CPF punctuated, as 000.000.000-00.

It takes the eleven digits bare or already punctuated, and returns anything else unchanged: it formats, and does not validate, so a page that prints a stored value shows what is stored rather than an empty cell. Validate with ParseCPF where the value is taken in.

func CPFCheckDigits

func CPFCheckDigits(base string) (string, error)

CPFCheckDigits returns the two check digits of a CPF whose first nine digits are base, and ErrInvalidCPF when base is not nine digits.

Each check digit is the sum of the digits before it, weighted from 10 (or 11) down to 2, times ten, modulo eleven -- with ten written as zero. It is what a seeder or a factory needs to write a CPF that passes, without borrowing one that belongs to somebody.

func Date

func Date(t time.Time) string

Date writes the calendar day of t as a Brazilian page prints it: 31/12/2026, day, month and four-digit year.

The day is the one t holds in its own location. An instant read from a database is usually in UTC, where a late evening in Brasília is already the next day, so convert it first -- br.Date(t.In(location)) -- with the location the reader lives in.

func ParseCEP

func ParseCEP(s string) (string, error)

ParseCEP returns the eight digits of a CEP, written bare (00000000) or punctuated (00000-000), and ErrInvalidCEP for anything else or for a code below 01000-000, where no range begins.

A CEP carries no check digit, so a code that passes may still address nothing: only a lookup in the Correios base can say it exists.

The digits come back bare, which is the spelling to store.

func ParseCNPJ

func ParseCNPJ(s string) (string, error)

ParseCNPJ returns the fourteen characters of a CNPJ, written bare (00000000000000) or punctuated (00.000.000/0000-00), and ErrInvalidCNPJ for anything else.

The first twelve positions may hold letters as well as digits: that is the alphanumeric CNPJ the Receita Federal issues, and the numeric CNPJ is the case of it whose twelve positions are all digits, checked by the same computation. The last two positions are the check digits, and are always digits. A letter typed in lower case is read as the capital it stands for, and comes back as one.

It refuses fourteen repetitions of one character, which no CNPJ is. It does not say whether the CNPJ was issued or is active: only the Receita Federal can.

The characters come back bare, which is the spelling to store.

func ParseCPF

func ParseCPF(s string) (string, error)

ParseCPF returns the eleven digits of a CPF, written bare (00000000000) or punctuated (000.000.000-00), and ErrInvalidCPF for anything else.

It checks the shape and the two check digits the Receita Federal computes, and refuses the eleven repetitions of one digit, whose check digits compute but which belong to nobody. It does not say whether the CPF was issued or is regular: only the Receita Federal can.

The digits come back bare, which is the spelling to store: a column that holds both spellings cannot be searched for either.

func ValidCEP

func ValidCEP(s string) bool

ValidCEP reports whether ParseCEP accepts s.

func ValidCNPJ

func ValidCNPJ(s string) bool

ValidCNPJ reports whether ParseCNPJ accepts s.

func ValidCPF

func ValidCPF(s string) bool

ValidCPF reports whether ParseCPF accepts s.

Types

type UF

type UF string

UF is one of the twenty-seven federative units of Brazil -- the twenty-six states and the Federal District -- stored as its two-letter code.

It is a closed set in the shape a generated enum has: constants that are the only valid values, Valid to ask, Label for what a form shows, and a Value/Scan pair that refuses a code outside the set on the way to and from a column. So hesape/enum reads it like any other: enum.Options(br.UFValues()...) fills a select, and validation.EnumOf(br.UFValues()...) is the rule.

const (
	UFAC UF = "AC"
	UFAL UF = "AL"
	UFAP UF = "AP"
	UFAM UF = "AM"
	UFBA UF = "BA"
	UFCE UF = "CE"
	UFDF UF = "DF"
	UFES UF = "ES"
	UFGO UF = "GO"
	UFMA UF = "MA"
	UFMT UF = "MT"
	UFMS UF = "MS"
	UFMG UF = "MG"
	UFPA UF = "PA"
	UFPB UF = "PB"
	UFPR UF = "PR"
	UFPE UF = "PE"
	UFPI UF = "PI"
	UFRJ UF = "RJ"
	UFRN UF = "RN"
	UFRS UF = "RS"
	UFRO UF = "RO"
	UFRR UF = "RR"
	UFSC UF = "SC"
	UFSP UF = "SP"
	UFSE UF = "SE"
	UFTO UF = "TO"
)

The units, in the alphabetical order of their names, which is the order a list of them is read in. Stored exactly as written: the code is what the Correios, the Receita Federal and IBGE all print.

func ParseUF

func ParseUF(s string) (UF, error)

ParseUF turns request input into a UF, or wraps ErrInvalidUF.

It reads the code exactly as the set spells it, in capitals: the value a select sends back is the one Options gave it, and a value that differs from every option did not come from the form.

func UFValues

func UFValues() []UF

UFValues lists the twenty-seven units in declaration order.

It is what fills a select and what a rule is built from, so the set is written once, here, and every list of units derives from it.

func (UF) Label

func (v UF) Label() string

Label is the name of the unit, which is what a form shows: São Paulo for SP. It is empty for a code outside the set.

It is separate from String on purpose. The code is a contract with every column and every message that holds it; the name is a contract with nobody, and changing how one is spelled must not be able to change a row.

func (*UF) Scan

func (v *UF) Scan(src any) error

Scan implements sql.Scanner. A code the set does not hold is an error at the row that has it, rather than a value that behaves like a unit three layers up.

func (UF) String

func (v UF) String() string

String is the code, so fmt and a view print it unchanged.

func (UF) Valid

func (v UF) Valid() bool

Valid reports whether v is one of the units.

func (UF) Value

func (v UF) Value() (driver.Value, error)

Value implements driver.Valuer. It refuses a code outside the set, which is what keeps a zero-valued struct from putting an empty string in the column.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL