Primeiros passos

🚀 Suporte total ao novo formato alfanumérico de CNPJ.

Kit em Ruby para as principais operações com dados brasileiros: CPF (Cadastro de Pessoa Física) e CNPJ (Cadastro Nacional da Pessoa Jurídica). Envolve cpf-utilities e cnpj-utilities em uma única classe fachada (BrUtils).

Suporte a Ruby


Passing ✔	Passing ✔	Passing ✔	Passing ✔	Passing ✔

Requer Ruby ≥ 3.1 (veja required_ruby_version no gemspec).

Recursos

✅ API unificada de alto nível: Helpers de classe BrUtils.cpf / .cnpj encaminham para BrUtils::DEFAULT.cpf / .cnpj; cada domínio oferece format, generate e is_valid
✅ Domínios empacotados: cpf-utilities e cnpj-utilities instalados juntos
✅ CNPJ alfanumérico: Suporte completo ao novo formato alfanumérico de CNPJ (a partir de 2026)
✅ Instância reutilizável: Classe BrUtils com configurações padrão opcionais de CPF e CNPJ (mapeamentos aninhados, kwargs planos de componentes ou instâncias prontas de utils)
✅ Acesso em dois níveis: Prefira atalhos de classes principais na raiz da fachada (BrUtils::CpfFormatter, BrUtils::CnpjValidator, …); Options, helpers e erros ficam nos módulos aninhados (BrUtils::CpfFmt, BrUtils::CnpjUtils, …). Os irmãos na raiz (CpfUtils, CnpjUtils, CpfFmt, …) continuam funcionando
✅ Sobrescritas por chamada: Configure padrões na fachada / utils de domínio; sobrescreva opções em uma única chamada de format / generate / is_valid
✅ Tratamento de erros: Erros de domínio propagam inalterados dos pacotes incluídos; esta gem define BrUtils::TypeMismatchError e BrUtils::InvalidArgumentCombinationError para uso indevido da API

Instalação

Instale a gem diretamente:

gem install br-utilities

Ou adicione ao seu Gemfile e execute bundle install:

gem 'br-utilities'

Isso instala br-utilities junto com cpf-utilities e cnpj-utilities (que por sua vez trazem os pacotes componentes de CPF e CNPJ). Você não precisa de gem install / linhas gem separados para os pacotes de domínio ao usar br-utilities.

Require

require 'br-utilities'

Início rápido

Prefira os helpers de classe do agregador (BrUtils.cpf / BrUtils.cnpj) para chamadas pontuais — eles encaminham para BrUtils::DEFAULT:

require 'br-utilities'

cpf = '12345678909'
cnpj = '03603568000195'

# CPF (pessoa física)
BrUtils.cpf.format(cpf)              # => "123.456.789-09"
BrUtils.cpf.generate(format: true)   # => ex.: "478.442.410-55"
BrUtils.cpf.is_valid('123.456.789-09') # => true

# CNPJ (pessoa jurídica)
BrUtils.cnpj.format(cnpj)            # => "03.603.568/0001-95"
BrUtils.cnpj.generate(format: true)  # => ex.: "AB.123.CDE/0001-55"
BrUtils.cnpj.is_valid('98765432000198') # => true

Com agregadores de domínio:

require 'br-utilities'

cpf = '12345678909'
cnpj = '03603568000195'

CpfUtils.format(cpf)      # => "123.456.789-09"
CnpjUtils.format(cnpj)    # => "03.603.568/0001-95"
CpfUtils.is_valid(cpf)    # => true
CnpjUtils.is_valid(cnpj)  # => true

Com helpers funcionais (módulos irmãos na raiz, carregados por esta gem):

require 'br-utilities'

cpf = '12345678909'
cnpj = '03603568000195'

CpfFmt.cpf_fmt(cpf)     # => "123.456.789-09"
CpfVal.cpf_val(cpf)     # => true
CnpjFmt.cnpj_fmt(cnpj)  # => "03.603.568/0001-95"
CnpjVal.cnpj_val(cnpj)  # => true

Utilização

Você pode trabalhar destas formas equivalentes:

BrUtils.cpf / .cnpj — helpers de classe para chamadas rápidas (encaminham para DEFAULT).
BrUtils::DEFAULT — singleton compartilhado mutável (o mesmo objeto usado pelos helpers de classe; em todo o processo / não isolado por thread).
BrUtils.new — instância configurável com padrões compartilhados entre os domínios CPF e CNPJ.
Agregadores de domínio — CpfUtils / CnpjUtils (ou BrUtils::CpfUtils / BrUtils::CnpjUtils) diretamente.
Classes principais sob BrUtils — BrUtils::CpfFormatter, BrUtils::CnpjGenerator e atalhos relacionados.
Módulos aninhados do pacote — Options, helpers, erros e tipos via BrUtils::CpfFmt / CpfGen / CpfVal / CnpjFmt / CnpjGen / CnpjVal / CpfUtils / CnpjUtils.
Módulos irmãos na raiz (ainda suportados) — CpfFmt, CnpjUtils e demais inalterados.

Todas as abordagens expõem as mesmas opções e comportamento dentro de cada domínio. Para tabelas de opções exaustivas e detalhes específicos de cada componente, consulte o README de cada pacote incluído.

Helpers de classe (`BrUtils.cpf` / `.cnpj`)

Esses métodos de classe retornam as mesmas instâncias de utils de domínio que BrUtils::DEFAULT. Prefira-os para chamadas pontuais:

BrUtils.cpf.format('12345678909')
BrUtils.cpf.generate(format: true)
BrUtils.cpf.is_valid('12345678909')

BrUtils.cnpj.format('03603568000195')
BrUtils.cnpj.generate(type: 'numeric')
BrUtils.cnpj.is_valid('98765432000198')

`BrUtils::DEFAULT` (instância padrão)

BrUtils::DEFAULT é o singleton pré-construído e mutável por trás dos helpers de classe (paridade com a exportação padrão do JS / br_utils do Python). Sua configuração é em todo o processo e compartilhada entre threads: mutá-lo (ex.: DEFAULT.cpf = …) afeta chamadas subsequentes de BrUtils.cpf / .cnpj para todos os callers no processo. Prefira BrUtils.new ou opções por chamada para trabalho concorrente ou isolado; instâncias customizadas permanecem independentes de DEFAULT:

BrUtils::DEFAULT.cpf = CpfUtils.new(formatter: { dash_key: '|' })
BrUtils.cpf.format('12345678909')   # => "123.456.789|09"

custom = BrUtils.new
custom.cpf.format('12345678909')    # => "123.456.789-09" (não afetado)

`BrUtils` (classe)

Para utils de CPF ou CNPJ padrão customizados, crie sua própria instância:

require 'br-utilities'

utils = BrUtils.new(
  cpf: {
    formatter: { hidden: true, hidden_key: '#' },
    generator: { format: true }
  },
  cnpj: {
    formatter: { hidden: true },
    generator: { type: 'numeric', format: true },
    validator: { type: 'numeric' }
  }
)

utils.cpf.format('12345678909')        # => "123.###.###-##"
utils.cpf.generate                     # => ex.: "005.265.352-88"
utils.cnpj.format('03603568000195')    # => "03.603.***/****-**"
utils.cnpj.generate                    # => ex.: "73.008.535/0005-06"

# Acessar ou substituir instâncias internas de domínio
utils.cpf    # => CpfUtils
utils.cnpj   # => CnpjUtils

BrUtils.new(settings = nil, **keywords): Configurações opcionais. Passe um Hash de settings com chaves :cpf e/ou :cnpj, ou as mesmas chaves (mais kwargs planos de componentes) como argumentos nomeados — não ambos (passar ambos lança BrUtils::InvalidArgumentCombinationError).
- :cpf / :cnpj: Uma instância pronta de CpfUtils / CnpjUtils ou um Hash de configuração repassado ao construtor do utils correspondente. Dentro desse Hash, cada chave de recurso (:formatter, :generator e :validator para CNPJ) aceita um objeto de opções ou um mapeamento de valores de opção.
- :cpf_formatter, :cpf_generator, :cnpj_formatter, :cnpj_generator, :cnpj_validator: Argumentos planos de conveniência quando apenas componentes individuais precisam de customização. São ignorados quando o argumento :cpf ou :cnpj correspondente é fornecido.
#cpf, #cnpj: Acessores (getters e setters) das instâncias de utils de domínio. Os setters aceitam uma instância de utils, um Hash de configuração ou nil para voltar aos padrões (substitui a instância inteira; não faz merge).

Opções planas no construtor (alternativa aos mapeamentos aninhados :cpf / :cnpj):

require 'br-utilities'

utils = BrUtils.new(
  cpf_formatter: CpfFmt::CpfFormatterOptions.new(hidden: true, hidden_key: '#'),
  cpf_generator: CpfGen::CpfGeneratorOptions.new(format: true),
  cnpj_formatter: CnpjFmt::CnpjFormatterOptions.new(hidden: true, hidden_key: '#'),
  cnpj_generator: CnpjGen::CnpjGeneratorOptions.new(format: true, type: 'numeric'),
  cnpj_validator: CnpjVal::CnpjValidatorOptions.new(type: 'numeric')
)

Passar um Hash de settings posicional junto com qualquer palavra-chave lança:

BrUtils.new({ cpf: {} }, cnpj: CnpjUtils.new)
# lança BrUtils::InvalidArgumentCombinationError

Padrões da instância e sobrescritas por chamada

require 'br-utilities'

utils = BrUtils.new(
  cpf: {
    formatter: { hidden: true, hidden_key: '#' },
    generator: { format: true }
  },
  cnpj: {
    formatter: { hidden: true, hidden_key: '#' },
    generator: { format: true },
    validator: { type: 'numeric' }
  }
)

cpf = '12345678909'
cnpj = '03603568000195'

utils.cpf.format(cpf)                  # => "123.###.###-##"
utils.cpf.format(cpf, hidden: false)   # só nesta chamada: sem máscara
utils.cpf.generate(format: false)      # só nesta chamada: saída compacta

utils.cnpj.format(cnpj)                  # => "03.603.###/####-##"
utils.cnpj.format(cnpj, hidden: false)   # só nesta chamada: sem máscara
utils.cnpj.is_valid('1QB5UKALPYFP59')    # => false (validador da instância é só numérico)
utils.cnpj.is_valid(                     # => true nesta chamada
  '1QB5UKALPYFP59',
  type: 'alphanumeric'
)

Passar uma instância de CnpjFmt::CnpjFormatterOptions, CnpjGen::CnpjGeneratorOptions ou CnpjVal::CnpjValidatorOptions ao construtor de BrUtils armazena esse objeto por referência — mutá-lo depois afeta chamadas subsequentes sem sobrescrita por chamada.

Para alterar uma única opção aninhada sem substituir o utils de domínio inteiro, mute via os acessores de domínio (ex.: utils.cpf.formatter.options.hidden = true).

Operações de CPF

Os métodos de CPF são acessados via BrUtils.cpf, utils.cpf, CpfUtils ou os helpers CpfFmt / CpfGen / CpfVal. O CPF usa a API de cpf-utilities.

Formatação (`#format` / `CpfFmt.cpf_fmt`)

Opção	Tipo	Padrão	Descrição
`hidden`	`Boolean`	`false`	Se `true`, mascara dígitos entre `hidden_start` e `hidden_end` com `hidden_key`
`hidden_key`	`String`	`'*'`	Caractere(s) usados para substituir dígitos mascarados
`hidden_start`	`Integer`	`3`	Índice inicial (0–10, inclusivo) do intervalo a ocultar
`hidden_end`	`Integer`	`10`	Índice final (0–10, inclusivo) do intervalo a ocultar
`dot_key`	`String`	`'.'`	Delimitador de ponto (ex.: em `123.456.789`)
`dash_key`	`String`	`'-'`	Delimitador de hífen (ex.: antes dos dígitos verificadores `…-09`)
`escape`	`Boolean`	`false`	Se `true`, escapa caracteres especiais HTML no resultado
`encode`	`Boolean`	`false`	Se `true`, codifica o resultado para URL (similar ao `encodeURIComponent` do JavaScript)
`on_fail`	`Proc` / invocável	retorna `''`	Callback quando o tamanho da entrada sanitizada ≠ 11; o retorno é usado como resultado

O on_fail padrão retorna uma string vazia. Comprimento inválido não lança exceção em #format.

require 'br-utilities'

cpf = '12345678909'

BrUtils.cpf.format(cpf)                              # => "123.456.789-09"
BrUtils.cpf.format(cpf, hidden: true, hidden_key: '#') # => "123.###.###-##"
BrUtils.cpf.format(cpf, dot_key: '', dash_key: '_')  # => "123456789_09"

CpfFmt.cpf_fmt(cpf, hidden: true)                    # => "123.***.***-**"

Geração (`#generate` / `CpfGen.cpf_gen`)

Opção	Tipo	Padrão	Descrição
`format`	`Boolean`	`false`	Se `true`, retorna o CPF gerado no formato padrão (`000.000.000-00`)
`prefix`	`String`	`''`	String parcial inicial (0–9 dígitos). Não dígitos são removidos; caracteres faltantes são gerados e os dígitos verificadores calculados. Prefixos com mais de 9 dígitos são truncados silenciosamente.

Regras de prefixo: a base (primeiros 9 dígitos) não pode ser toda zeros; 9 dígitos repetidos (ex.: 999999999) não são permitidos.

require 'br-utilities'

BrUtils.cpf.generate                       # => ex.: "11508890048"
BrUtils.cpf.generate(format: true)         # => ex.: "661.134.831-00"
BrUtils.cpf.generate(prefix: '123456789')  # => "12345678909"
CpfGen.cpf_gen(prefix: '123456789', format: true) # => "123.456.789-09"

Validação (`#is_valid` / `CpfVal.cpf_val`)

Aceita CPF formatado ou não (ou um Array de strings). Retorna true ou false sem lançar exceção para CPF inválido. Não há opções de validador.

require 'br-utilities'

BrUtils.cpf.is_valid('12345678909')      # => true
BrUtils.cpf.is_valid('123.456.789-09')   # => true
BrUtils.cpf.is_valid('12345678900')      # => false
CpfVal.cpf_val('12345678909')            # => true

Operações de CNPJ

Os métodos de CNPJ são acessados via BrUtils.cnpj, utils.cnpj, CnpjUtils ou os helpers CnpjFmt / CnpjGen / CnpjVal. O CNPJ usa a API de cnpj-utilities.

Formatação (`#format` / `CnpjFmt.cnpj_fmt`)

Opção	Tipo	Padrão	Descrição
`hidden`	`Boolean`	`false`	Se `true`, mascara caracteres entre `hidden_start` e `hidden_end` com `hidden_key`
`hidden_key`	`String`	`'*'`	Caractere(s) usados para substituir caracteres mascarados
`hidden_start`	`Integer`	`5`	Índice inicial (0–13, inclusivo) do intervalo a ocultar
`hidden_end`	`Integer`	`13`	Índice final (0–13, inclusivo) do intervalo a ocultar
`dot_key`	`String`	`'.'`	Delimitador de ponto (ex.: em `12.345.678`)
`slash_key`	`String`	`'/'`	Delimitador de barra (ex.: antes da filial `…/0001-90`)
`dash_key`	`String`	`'-'`	Delimitador de hífen (ex.: antes dos dígitos verificadores `…-90`)
`escape`	`Boolean`	`false`	Se `true`, escapa caracteres especiais HTML no resultado
`encode`	`Boolean`	`false`	Se `true`, codifica o resultado para URL (similar ao `encodeURIComponent` do JavaScript)
`on_fail`	`Proc` / invocável	retorna `''`	Callback quando o tamanho da entrada sanitizada ≠ 14; o retorno é usado como resultado

O on_fail padrão retorna uma string vazia. Tipos de entrada incorretos lançam CnpjFmt::TypeMismatchError.

require 'br-utilities'

cnpj = '03603568000195'

BrUtils.cnpj.format(cnpj)              # => "03.603.568/0001-95"
BrUtils.cnpj.format('12ABC34500DE99')  # => "12.ABC.345/00DE-99"
BrUtils.cnpj.format(                   # => "03.603.###/####-##"
  cnpj,
  hidden: true,
  hidden_key: '#'
)
BrUtils.cnpj.format(                   # => "03603568|0001_95"
  cnpj,
  dot_key: '',
  slash_key: '|',
  dash_key: '_'
)

CnpjFmt.cnpj_fmt(cnpj)                 # => "03.603.568/0001-95"

Geração (`#generate` / `CnpjGen.cnpj_gen`)

Opção	Tipo	Padrão	Descrição
`format`	`Boolean`	`false`	Se `true`, retorna o CNPJ gerado no formato padrão (`00.000.000/0000-00`)
`prefix`	`String`	`''`	String parcial inicial (0–12 caracteres alfanuméricos). Caracteres faltantes são gerados e os dígitos verificadores calculados.
`type`	`String`	`'alphanumeric'`	Conjunto de caracteres para a parte gerada aleatoriamente: `'numeric'`, `'alphabetic'` ou `'alphanumeric'`. Os dígitos verificadores são sempre numéricos.

Regras de prefixo: o ID base (primeiros 8 caracteres) e o ID da filial (caracteres 9–12) não podem ser todos zeros; 12 dígitos repetidos (ex.: 111111111111) também não são permitidos.

require 'br-utilities'

BrUtils.cnpj.generate               # => ex.: "1GJTR3J3XSSA96"
BrUtils.cnpj.generate(format: true) # => ex.: "V1.J0V.8WE/DVZ7-50"
BrUtils.cnpj.generate(              # => ex.: "12345678855883"
  prefix: '12345678',
  type: 'numeric'
)
CnpjGen.cnpj_gen(type: 'numeric')   # => ex.: "65453043000178"

Validação (`#is_valid` / `CnpjVal.cnpj_val`)

Opção	Tipo	Padrão	Descrição
`case_sensitive`	`Boolean`	`true`	Se `false`, letras minúsculas são aceitas para CNPJ alfanumérico (a entrada é convertida para maiúsculas antes da validação).
`type`	`String`	`'alphanumeric'`	`'numeric'`: apenas dígitos (0–9); `'alphanumeric'`: dígitos e letras (0–9, A–Z).

require 'br-utilities'

BrUtils.cnpj.is_valid('98765432000198')   # => true
BrUtils.cnpj.is_valid('98765432000199')   # => false
BrUtils.cnpj.is_valid('1QB5UKALPYFP59')   # => true
BrUtils.cnpj.is_valid('1QB5UKALpyfp59')   # => false
BrUtils.cnpj.is_valid(                     # => true
  '1QB5UKALpyfp59',
  case_sensitive: false
)
BrUtils.cnpj.is_valid(                     # => false
  '1QB5UKALPYFP59',
  type: 'numeric'
)

CnpjVal.cnpj_val('98765432000198')                         # => true
CnpjVal.cnpj_val('1QB5UKALpyfp59', case_sensitive: false)  # => true
CnpjVal.cnpj_val('1QB5UKALPYFP59', type: 'numeric')        # => false

CNPJ inválido retorna false sem lançar exceção. Tipos de entrada incorretos lançam CnpjVal::TypeMismatchError.

Agregadores de domínio (isolados)

Use CpfUtils ou CnpjUtils diretamente quando precisar de apenas um domínio:

require 'br-utilities'

cpf_utils = CpfUtils.new(
  formatter: { hidden: true },
  generator: { format: true }
)

cnpj_utils = CnpjUtils.new(
  formatter: { hidden: true },
  generator: { format: true },
  validator: { type: 'numeric' }
)

cpf_utils.format('12345678909')       # => "123.***.***-**"
cnpj_utils.format('03603568000195')   # => "03.603.***/****-**"

Acessando componentes

Cada agregador de domínio expõe seu formatador, gerador e validador internos:

require 'br-utilities'

utils = BrUtils.new

utils.cpf.formatter.format('12345678909', hidden: true)  # => "123.***.***-**"
utils.cpf.generator.generate(format: true)               # => ex.: "545.507.690-68"
utils.cpf.validator.is_valid('12345678909')              # => true

utils.cnpj.formatter.format('12ABC34500DE99')            # => "12.ABC.345/00DE-99"
utils.cnpj.generator.generate(format: true)              # => ex.: "8O.BE5.2KL/UI0Y-06"
utils.cnpj.validator.is_valid('03603568000195')          # => true

Usando classes componentes e módulos aninhados

Caminhos preferidos após require 'br-utilities':

require 'br-utilities'

# Classes principais na raiz da fachada
formatter = BrUtils::CpfFormatter.new(hidden: true)
generator = BrUtils::CnpjGenerator.new(type: 'numeric')
validator = BrUtils::CnpjValidator.new

formatter.format('12345678909')   # => "123.***.***-**"

# Options, helpers e erros nos módulos aninhados do pacote
options = BrUtils::CpfFmt::CpfFormatterOptions.new(dash_key: '|')
BrUtils::CpfFmt.cpf_fmt('12345678909')   # => "123.456.789-09"

begin
  BrUtils::CnpjFmt.cnpj_fmt(12_345)
rescue BrUtils::CnpjFmt::TypeMismatchError
  # tipo de entrada incorreto
end

Os irmãos na raiz continuam suportados (os mesmos objetos dos nests):

CpfFmt.cpf_fmt('12345678909', dash_key: '|')   # => "123.456.789|09"
CpfGen.cpf_gen(format: true)                   # => ex.: "478.442.410-55"
CpfVal.cpf_val('12345678909')                  # => true
CnpjFmt.cnpj_fmt('01ABC234000X56', slash_key: '|') # => "01.ABC.234|000X-56"
CnpjGen.cnpj_gen(type: 'numeric')              # => ex.: "65453043000178"
CnpjVal.cnpj_val('9JN7MGLJZXIO50')             # => true

Consulte cpf-utilities e cnpj-utilities para detalhes completos de opções e erros.

Misturando estilos

Use BrUtils onde uma configuração compartilhada ajuda, e componentes ou helpers isolados em outros pontos — são as mesmas classes subjacentes:

require 'br-utilities'

utils = BrUtils.new(cnpj: { validator: { type: 'numeric' } })

# Via fachada
utils.cpf.format('12345678909')   # => "123.456.789-09"

# Via componente retornado pela fachada
utils.cnpj.formatter.format('12ABC34500DE99')   # => "12.ABC.345/00DE-99"

# Via instância de componente separada
BrUtils::CnpjFormatter.new.format('03603568000195')   # => "03.603.568/0001-95"

# Via helpers funcionais
CpfFmt.cpf_fmt('12345678909')           # => "123.456.789-09"
CnpjVal.cnpj_val('98.765.432/0001-98')  # => true

API

Exportações

Após require 'br-utilities':

BrUtils: Classe fachada para criar uma instância com configurações opcionais dos utils de CPF e CNPJ.
BrUtils.cpf / .cnpj: Helpers de classe que encaminham para os acessores de domínio de BrUtils::DEFAULT.
BrUtils::DEFAULT: Instância pré-construída e mutável de BrUtils (o mesmo objeto usado pelos helpers de classe). Em todo o processo / compartilhada entre threads — prefira BrUtils.new ou opções por chamada sob concorrência.
BrUtils::VERSION: String da versão da gem.
Atalhos de classes principais: BrUtils::CpfFormatter, BrUtils::CpfFormatterOptions, BrUtils::CpfGenerator, BrUtils::CpfGeneratorOptions, BrUtils::CpfValidator, BrUtils::CnpjFormatter, BrUtils::CnpjFormatterOptions, BrUtils::CnpjGenerator, BrUtils::CnpjGeneratorOptions, BrUtils::CnpjValidator, BrUtils::CnpjValidatorOptions (os mesmos objetos das classes irmãs). Atalhos de marcadores de erro: BrUtils::CpfFormatterError, BrUtils::CpfGeneratorError, BrUtils::CpfValidatorError, BrUtils::CnpjFormatterError, BrUtils::CnpjGeneratorError, BrUtils::CnpjValidatorError.
Módulos aninhados do pacote: BrUtils::CpfUtils, BrUtils::CnpjUtils, BrUtils::CpfFmt, BrUtils::CpfGen, BrUtils::CpfVal, BrUtils::CnpjFmt, BrUtils::CnpjGen, BrUtils::CnpjVal — superfície completa dos irmãos (Options, helpers, erros, tipos).
Módulos irmãos na raiz (ainda suportados): CpfUtils, CnpjUtils, CpfFmt, CpfGen, CpfVal, CnpjFmt, CnpjGen, CnpjVal — os mesmos objetos dos nests.

Erros e exceções

BrUtils define apenas erros de uso indevido da API para as regras de argumentos desta gem. Erros de domínio são lançados pelos pacotes incluídos e propagam inalterados.

Definidos por `br-utilities`

Os erros definidos por esta gem são apenas uso indevido da API (tipo errado ou combinação inválida de argumentos). Todo erro customizado inclui o módulo marcador BrUtils::Error. Esta gem não define BrUtils::DomainError nem folhas de domínio — falhas de domínio vêm apenas dos pacotes incluídos e mantêm os namespaces desses pacotes (CpfFmt::…, CnpjGen::…, …).

rescue BrUtils::Error captura apenas erros que esta gem lança. Não captura erros de componentes que propagam inalterados.

Resumo

Classe	Herda de	Categoria	Condição de disparo
`BrUtils::InvalidArgumentCombinationError`	`BrUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include BrUtils::Error`)	Uso indevido da API	`Hash` de settings não-`nil` passado junto com qualquer argumento nomeado não-`nil`
`BrUtils::TypeMismatchError`	`BrUtils::TypeMismatchError < TypeError < StandardError` (+ `include BrUtils::Error`)	Uso indevido da API	Argumento `settings` não-`nil` em `BrUtils.new` não é um `Hash`

`BrUtils::Error` (módulo marcador)

Herança: módulo marcador misturado em todo erro customizado que esta gem lança via include (não é uma classe).
Categoria: N/A (apenas alvo de rescue) — não é um modo de falha por si só.
Quando é lançado: Nunca lançado diretamente; incluído por todo erro customizado que esta gem lança.
Exemplo: N/A
Como resgatar:

rescue BrUtils::Error
  # TypeMismatchError, InvalidArgumentCombinationError apenas desta gem
  # (não CpfFmt::*, CnpjGen::* ou outros erros dos pacotes incluídos)

`BrUtils::TypeMismatchError`

Herança: BrUtils::TypeMismatchError < TypeError < StandardError (inclui BrUtils::Error)
Categoria: Uso indevido da API — o caller passou um valor do tipo errado.
Quando é lançado: Quando BrUtils.new recebe um argumento settings não-nil que não é um Hash.
Exemplo:

BrUtils.new('not-a-hash')   # lança BrUtils::TypeMismatchError
BrUtils.new(false)          # lança BrUtils::TypeMismatchError (false é não-nil)

Como resgatar:

rescue BrUtils::TypeMismatchError
  # violação de contrato de tipo desta gem

rescue TypeError
  # erros nativos de tipo, incluindo TypeMismatchError desta gem

`BrUtils::InvalidArgumentCombinationError`

Herança: BrUtils::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui BrUtils::Error)
Categoria: Uso indevido da API — o caller misturou padrões de argumentos mutuamente exclusivos.
Quando é lançado: Quando BrUtils.new recebe um Hash de settings não-nil e qualquer argumento nomeado não-nil (cpf:, cnpj:, cpf_formatter:, …) ao mesmo tempo.
Exemplo:

BrUtils.new({ cpf: { formatter: { hidden: true } } }, cnpj: { formatter: { hidden: true } })
# lança BrUtils::InvalidArgumentCombinationError

Como resgatar:

rescue BrUtils::InvalidArgumentCombinationError
  # combinação inválida de assinatura desta gem

rescue ArgumentError
  # erros nativos de argumento, incluindo InvalidArgumentCombinationError desta gem

Granularidade de rescue

Cada nível é mostrado como seu próprio exemplo isolado (não os una em uma única escada de rescue — um handler nativo amplo tornaria cláusulas mais estreitas inalcançáveis).

require 'br-utilities'

# 1) Classe nativa única — captura erros de uso indevido desse tipo,
#    incluindo os não-biblioteca já tratados em outro ponto do código do consumidor.
begin
  BrUtils.new('not-a-hash')
rescue TypeError
  # BrUtils::TypeMismatchError e qualquer outro TypeError (biblioteca ou não)
end

begin
  BrUtils.new({ cpf: {} }, cnpj: CnpjUtils.new)
rescue ArgumentError
  # BrUtils::InvalidArgumentCombinationError e qualquer outro ArgumentError (biblioteca ou não)
end

require 'br-utilities'

# 2) DomainError dos pacotes — esta gem não define DomainError; falhas de domínio
#    vêm dos pacotes incluídos e mantêm esses namespaces (ex.: CpfFmt, CnpjFmt).
begin
  BrUtils.new.cpf.format('12345678909', hidden_start: -1)
rescue CpfFmt::DomainError
  # CpfFmt::OutOfRangeError, CpfFmt::ValidationError e outras subclasses de DomainError
end

begin
  BrUtils.new.cnpj.format('91415732000793', hidden_start: -1)
rescue CnpjFmt::DomainError
  # CnpjFmt::OutOfRangeError, CnpjFmt::ValidationError e outras subclasses de DomainError
end

require 'br-utilities'

# 3) BrUtils::Error — captura tudo que esta gem lança, independentemente da ancestralidade nativa.
#    Não captura CpfFmt::*, CnpjGen::* ou outros erros dos pacotes incluídos.
begin
  BrUtils.new('not-a-hash')
rescue BrUtils::Error
  # todo erro customizado que inclui BrUtils::Error
end

require 'br-utilities'

# 4) Classe folha específica — captura apenas aquele modo de falha exato.
begin
  BrUtils.new('not-a-hash')
rescue BrUtils::TypeMismatchError
  # apenas BrUtils::TypeMismatchError
end

Propagados dos pacotes incluídos

Os erros dos componentes mantêm os namespaces dos pacotes e se propagam inalterados pela fachada (e pelas APIs aninhadas / irmãs na raiz). Cada pacote também expõe um módulo marcador *::Error para rescue em toda a biblioteca. Dados inválidos de CPF/CNPJ em #is_valid retornam false (sem raise de domínio). Falha de comprimento na formatação não é lançada por #format — é entregue a on_fail como CpfFmt::InvalidLengthError ou CnpjFmt::InvalidLengthError (on_fail padrão retorna '').

CpfUtils::* / CnpjUtils::* de uso indevido também se propagam quando agregadores aninhados são construídos ou chamados via BrUtils. Para tabelas de opções e casos extremos, veja cpf-utilities e cnpj-utilities.

Resumo

Classe	Herda de	Categoria	Condição de disparo
`CnpjFmt::InvalidArgumentCombinationError`	`CnpjFmt::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjFmt::Error`)	Uso indevido da API	Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CnpjFormatter` / `cnpj_fmt`
`CnpjFmt::TypeMismatchError`	`CnpjFmt::TypeMismatchError < TypeError < StandardError` (+ `include CnpjFmt::Error`)	Uso indevido da API	Entrada de CNPJ ou opção do formatador tem o tipo errado (ou o retorno de `on_fail` não é `String`)
`CnpjGen::InvalidArgumentCombinationError`	`CnpjGen::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjGen::Error`)	Uso indevido da API	Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CnpjGenerator` / `cnpj_gen`
`CnpjGen::TypeMismatchError`	`CnpjGen::TypeMismatchError < TypeError < StandardError` (+ `include CnpjGen::Error`)	Uso indevido da API	Opção do gerador (`format` / `prefix` / `type`) tem o tipo errado
`CnpjUtils::InvalidArgumentCombinationError`	`CnpjUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjUtils::Error`)	Uso indevido da API	Construtor/`#format`/`#generate`/`#is_valid`/helpers de classe: `Hash`/instância de settings/options não-`nil` com qualquer argumento nomeado não-`nil`
`CnpjUtils::TypeMismatchError`	`CnpjUtils::TypeMismatchError < TypeError < StandardError` (+ `include CnpjUtils::Error`)	Uso indevido da API	Argumento `settings` não-`nil` de `CnpjUtils.new` não é um `Hash`
`CnpjVal::InvalidArgumentCombinationError`	`CnpjVal::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CnpjVal::Error`)	Uso indevido da API	Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CnpjValidator` / `cnpj_val`
`CnpjVal::TypeMismatchError`	`CnpjVal::TypeMismatchError < TypeError < StandardError` (+ `include CnpjVal::Error`)	Uso indevido da API	Entrada de CNPJ ou opção do validador tem o tipo errado
`CpfFmt::InvalidArgumentCombinationError`	`CpfFmt::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CpfFmt::Error`)	Uso indevido da API	Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CpfFormatter` / `cpf_fmt`
`CpfFmt::TypeMismatchError`	`CpfFmt::TypeMismatchError < TypeError < StandardError` (+ `include CpfFmt::Error`)	Uso indevido da API	Entrada de CPF ou opção do formatador tem o tipo errado (ou o retorno de `on_fail` não é `String`)
`CpfGen::InvalidArgumentCombinationError`	`CpfGen::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CpfGen::Error`)	Uso indevido da API	Instância/`Hash` de `options` e qualquer argumento nomeado não-`nil` em `CpfGenerator` / `cpf_gen`
`CpfGen::TypeMismatchError`	`CpfGen::TypeMismatchError < TypeError < StandardError` (+ `include CpfGen::Error`)	Uso indevido da API	Opção do gerador (`format` / `prefix`) tem o tipo errado
`CpfUtils::InvalidArgumentCombinationError`	`CpfUtils::InvalidArgumentCombinationError < ArgumentError < StandardError` (+ `include CpfUtils::Error`)	Uso indevido da API	Construtor: `Hash` de settings não-`nil` com qualquer argumento nomeado não-`nil`; ou `#format`/`#generate`/helpers de classe: `Hash`/instância `*Options` de options não-`nil` com qualquer argumento nomeado não-`nil`
`CpfUtils::TypeMismatchError`	`CpfUtils::TypeMismatchError < TypeError < StandardError` (+ `include CpfUtils::Error`)	Uso indevido da API	Argumento `settings` não-`nil` de `CpfUtils.new` não é um `Hash`
`CpfVal::TypeMismatchError`	`CpfVal::TypeMismatchError < TypeError < StandardError` (+ `include CpfVal::Error`)	Uso indevido da API	Entrada de CPF não é `String` nem `Array` de strings
`CnpjFmt::InvalidLengthError`	`CnpjFmt::InvalidLengthError < CnpjFmt::DomainError < RangeError < StandardError` (+ `include CnpjFmt::Error`)	Erro de domínio	Comprimento sanitizado ≠ 14 — passado a `on_fail`, não lançado por `#format`
`CnpjFmt::OutOfRangeError`	`CnpjFmt::OutOfRangeError < CnpjFmt::DomainError < RangeError < StandardError` (+ `include CnpjFmt::Error`)	Erro de domínio	`hidden_start` / `hidden_end` fora de `0`–`13`
`CnpjFmt::ValidationError`	`CnpjFmt::ValidationError < CnpjFmt::DomainError < RangeError < StandardError` (+ `include CnpjFmt::Error`)	Erro de domínio	`hidden_key` / `dot_key` / `slash_key` / `dash_key` contém caractere proibido
`CnpjGen::ValidationError`	`CnpjGen::ValidationError < CnpjGen::DomainError < RangeError < StandardError` (+ `include CnpjGen::Error`)	Erro de domínio	`prefix` inelegível, ou `type` fora de `'alphabetic'` / `'alphanumeric'` / `'numeric'`
`CnpjVal::ValidationError`	`CnpjVal::ValidationError < CnpjVal::DomainError < RangeError < StandardError` (+ `include CnpjVal::Error`)	Erro de domínio	`type` do validador não é `'alphanumeric'` nem `'numeric'`
`CpfFmt::InvalidLengthError`	`CpfFmt::InvalidLengthError < CpfFmt::DomainError < RangeError < StandardError` (+ `include CpfFmt::Error`)	Erro de domínio	Comprimento sanitizado ≠ 11 — passado a `on_fail`, não lançado por `#format`
`CpfFmt::OutOfRangeError`	`CpfFmt::OutOfRangeError < CpfFmt::DomainError < RangeError < StandardError` (+ `include CpfFmt::Error`)	Erro de domínio	`hidden_start` / `hidden_end` fora de `0`–`10`
`CpfFmt::ValidationError`	`CpfFmt::ValidationError < CpfFmt::DomainError < RangeError < StandardError` (+ `include CpfFmt::Error`)	Erro de domínio	`hidden_key` / `dot_key` / `dash_key` contém caractere proibido
`CpfGen::ValidationError`	`CpfGen::ValidationError < CpfGen::DomainError < RangeError < StandardError` (+ `include CpfGen::Error`)	Erro de domínio	`prefix` inelegível (base zerada ou 9 dígitos repetidos)

`CpfFmt::DomainError`

Herança: CpfFmt::DomainError < RangeError < StandardError (inclui CpfFmt::Error)
Categoria: Erro de domínio — ancestral das folhas de domínio do formatador.
Quando é lançado: Não é lançado diretamente; alvo de rescue para OutOfRangeError, ValidationError e InvalidLengthError relançado.
Exemplo: Prefira resgatar uma folha, ou CpfFmt::DomainError para todas as falhas de domínio do formatador de CPF.
Como resgatar:

rescue CpfFmt::DomainError
  # OutOfRangeError, ValidationError, InvalidLengthError (se relançado a partir de on_fail)

`CpfFmt::TypeMismatchError`

Herança: CpfFmt::TypeMismatchError < TypeError < StandardError (inclui CpfFmt::Error)
Categoria: Uso indevido da API — tipo errado para entrada de CPF ou opção do formatador.
Quando é lançado: Lançado quando #format / cpf_fmt recebe entrada que não é String / Array<String>, uma opção tem o tipo errado, ou on_fail não retorna String.
Exemplo:

BrUtils.new.cpf.format(12_345)   # lança CpfFmt::TypeMismatchError

Como resgatar:

rescue CpfFmt::TypeMismatchError
  # violação de contrato de tipo do formatador

rescue TypeError
  # erros nativos de tipo, incluindo CpfFmt::TypeMismatchError

`CpfFmt::InvalidArgumentCombinationError`

Herança: CpfFmt::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui CpfFmt::Error)
Categoria: Uso indevido da API — options e argumentos nomeados misturados na API do formatador.
Quando é lançado: Lançado por CpfFmt::CpfFormatter / CpfFmt.cpf_fmt quando uma instância/Hash de options e qualquer argumento nomeado não-nil são passados juntos. (O agregador de CPF lança CpfUtils::InvalidArgumentCombinationError para o mesmo padrão em CpfUtils#format.)
Exemplo:

CpfFmt::CpfFormatter.new({ dash_key: '_' }, hidden: true)
# lança CpfFmt::InvalidArgumentCombinationError

Como resgatar:

rescue CpfFmt::InvalidArgumentCombinationError
  # combinação inválida de assinatura do formatador

rescue ArgumentError
  # erros nativos de argumento, incluindo este

`CpfFmt::InvalidLengthError` (entregue via callback)

Herança: CpfFmt::InvalidLengthError < CpfFmt::DomainError < RangeError < StandardError (inclui CpfFmt::Error)
Categoria: Erro de domínio — o comprimento sanitizado do CPF não é exatamente 11.
Quando é lançado: Não é lançado por #format / cpf_fmt; construído e passado como segundo argumento a on_fail.
Exemplo:

custom_fail = ->(value, error) {
  error   # => #<CpfFmt::InvalidLengthError ...>
  "Invalid CPF: #{value}"
}

BrUtils.new.cpf.format('123', on_fail: custom_fail)   # => "Invalid CPF: 123"
BrUtils.new.cpf.format('123')                         # => "" (on_fail padrão)

Como resgatar: Trate dentro de on_fail (típico), ou faça rescue se relançar:

rescue CpfFmt::InvalidLengthError
  # esta violação exata de comprimento

rescue CpfFmt::DomainError
  # falhas de domínio com raiz em RangeError de cpf-fmt

`CpfFmt::OutOfRangeError`

Herança: CpfFmt::OutOfRangeError < CpfFmt::DomainError < RangeError < StandardError (inclui CpfFmt::Error)
Categoria: Erro de domínio — hidden_start / hidden_end fora de 0–10.
Quando é lançado: Lançado ao construir ou aplicar opções do formatador com índice de ocultação fora do intervalo.
Exemplo:

BrUtils.new.cpf.format('12345678909', hidden_start: -1)   # lança CpfFmt::OutOfRangeError

Como resgatar:

rescue CpfFmt::OutOfRangeError
  # esta violação exata de intervalo

rescue CpfFmt::DomainError
  # falhas de domínio com raiz em RangeError de cpf-fmt

`CpfFmt::ValidationError`

Herança: CpfFmt::ValidationError < CpfFmt::DomainError < RangeError < StandardError (inclui CpfFmt::Error)
Categoria: Erro de domínio — uma opção de chave contém um caractere proibido.
Quando é lançado: Lançado quando hidden_key, dot_key ou dash_key contém um caractere proibido.
Exemplo:

BrUtils.new(cpf: { formatter: { dot_key: 'å' } })   # lança CpfFmt::ValidationError

Como resgatar:

rescue CpfFmt::ValidationError
  # esta falha exata de validação de domínio

rescue CpfFmt::DomainError
  # falhas de domínio com raiz em RangeError de cpf-fmt

`CpfGen::DomainError`

Herança: CpfGen::DomainError < RangeError < StandardError (inclui CpfGen::Error)
Categoria: Erro de domínio — ancestral das folhas de domínio do gerador.
Quando é lançado: Não é lançado diretamente; alvo de rescue para CpfGen::ValidationError.
Exemplo: Prefira rescue CpfGen::ValidationError ou CpfGen::DomainError.
Como resgatar:

rescue CpfGen::DomainError
  # ValidationError e outras subclasses de DomainError de cpf-gen

`CpfGen::TypeMismatchError`

Herança: CpfGen::TypeMismatchError < TypeError < StandardError (inclui CpfGen::Error)
Categoria: Uso indevido da API — tipo errado para uma opção do gerador.
Quando é lançado: Lançado quando format ou prefix tem o tipo de runtime errado.
Exemplo:

BrUtils.new.cpf.generate(prefix: 123)   # lança CpfGen::TypeMismatchError

Como resgatar:

rescue CpfGen::TypeMismatchError
  # violação de contrato de tipo do gerador

rescue TypeError
  # erros nativos de tipo, incluindo CpfGen::TypeMismatchError

`CpfGen::InvalidArgumentCombinationError`

Herança: CpfGen::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui CpfGen::Error)
Categoria: Uso indevido da API — options e argumentos nomeados misturados na API do gerador.
Quando é lançado: Lançado por CpfGen::CpfGenerator / CpfGen.cpf_gen quando uma instância/Hash de options e qualquer argumento nomeado não-nil são passados juntos. (O agregador de CPF lança CpfUtils::InvalidArgumentCombinationError para o mesmo padrão em CpfUtils#generate.)
Exemplo:

CpfGen::CpfGenerator.new({ format: true }, prefix: '123')
# lança CpfGen::InvalidArgumentCombinationError

Como resgatar:

rescue CpfGen::InvalidArgumentCombinationError
  # combinação inválida de assinatura do gerador

rescue ArgumentError
  # erros nativos de argumento, incluindo este

`CpfGen::ValidationError`

Herança: CpfGen::ValidationError < CpfGen::DomainError < RangeError < StandardError (inclui CpfGen::Error)
Categoria: Erro de domínio — prefix inelegível.
Quando é lançado: Lançado quando prefix é uma base zerada ('000000000') ou 9 dígitos repetidos (ex.: '999999999').
Exemplo:

BrUtils.new.cpf.generate(prefix: '000000000')   # lança CpfGen::ValidationError

Como resgatar:

rescue CpfGen::ValidationError
  # esta falha exata de validação de domínio

rescue CpfGen::DomainError
  # falhas de domínio com raiz em RangeError de cpf-gen

`CpfVal::TypeMismatchError`

Herança: CpfVal::TypeMismatchError < TypeError < StandardError (inclui CpfVal::Error)
Categoria: Uso indevido da API — tipo errado para entrada de CPF.
Quando é lançado: Lançado quando #is_valid / cpf_val recebe um valor que não é String nem Array de strings (incluindo elemento de array que não é string). Dados de CPF inválidos retornam false e não lançam.
Exemplo:

BrUtils.new.cpf.is_valid(12_345_678_909)   # lança CpfVal::TypeMismatchError
BrUtils.new.cpf.is_valid('12345678900')    # => false (dados inválidos, sem raise)

Como resgatar:

rescue CpfVal::TypeMismatchError
  # violação de contrato de tipo do validador

rescue TypeError
  # erros nativos de tipo, incluindo CpfVal::TypeMismatchError

`CnpjFmt::DomainError`

Herança: CnpjFmt::DomainError < RangeError < StandardError (inclui CnpjFmt::Error)
Categoria: Erro de domínio — ancestral das folhas de domínio do formatador.
Quando é lançado: Não é lançado diretamente; alvo de rescue para OutOfRangeError, ValidationError e InvalidLengthError relançado.
Exemplo: Prefira resgatar uma folha, ou CnpjFmt::DomainError para todas as falhas de domínio do formatador de CNPJ.
Como resgatar:

rescue CnpjFmt::DomainError
  # OutOfRangeError, ValidationError, InvalidLengthError (se relançado a partir de on_fail)

`CnpjFmt::TypeMismatchError`

Herança: CnpjFmt::TypeMismatchError < TypeError < StandardError (inclui CnpjFmt::Error)
Categoria: Uso indevido da API — tipo errado para entrada de CNPJ ou opção do formatador.
Quando é lançado: Lançado quando #format / cnpj_fmt recebe entrada que não é String / Array<String>, uma opção tem o tipo errado, ou on_fail não retorna String.
Exemplo:

BrUtils.new.cnpj.format(12_345)   # lança CnpjFmt::TypeMismatchError

Como resgatar:

rescue CnpjFmt::TypeMismatchError
  # violação de contrato de tipo do formatador

rescue TypeError
  # erros nativos de tipo, incluindo CnpjFmt::TypeMismatchError

`CnpjFmt::InvalidArgumentCombinationError`

Herança: CnpjFmt::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui CnpjFmt::Error)
Categoria: Uso indevido da API — options e argumentos nomeados misturados na API do formatador.
Quando é lançado: Lançado por CnpjFmt::CnpjFormatter / CnpjFmt.cnpj_fmt quando uma instância/Hash de options e qualquer argumento nomeado não-nil são passados juntos. (O agregador de CNPJ lança CnpjUtils::InvalidArgumentCombinationError para o mesmo padrão em CnpjUtils#format.)
Exemplo:

CnpjFmt::CnpjFormatter.new({ slash_key: '|' }, hidden: true)
# lança CnpjFmt::InvalidArgumentCombinationError

Como resgatar:

rescue CnpjFmt::InvalidArgumentCombinationError
  # combinação inválida de assinatura do formatador

rescue ArgumentError
  # erros nativos de argumento, incluindo este

`CnpjFmt::InvalidLengthError` (entregue via callback)

Herança: CnpjFmt::InvalidLengthError < CnpjFmt::DomainError < RangeError < StandardError (inclui CnpjFmt::Error)
Categoria: Erro de domínio — o comprimento sanitizado do CNPJ não é exatamente 14.
Quando é lançado: Não é lançado por #format / cnpj_fmt; construído e passado como segundo argumento a on_fail.
Exemplo:

custom_fail = ->(value, error) {
  error   # => #<CnpjFmt::InvalidLengthError ...>
  "Invalid CNPJ: #{value}"
}

BrUtils.new.cnpj.format('123', on_fail: custom_fail)   # => "Invalid CNPJ: 123"
BrUtils.new.cnpj.format('123')                         # => "" (on_fail padrão)

Como resgatar: Trate dentro de on_fail (típico), ou faça rescue se relançar:

rescue CnpjFmt::InvalidLengthError
  # esta violação exata de comprimento

rescue CnpjFmt::DomainError
  # falhas de domínio com raiz em RangeError de cnpj-fmt

`CnpjFmt::OutOfRangeError`

Herança: CnpjFmt::OutOfRangeError < CnpjFmt::DomainError < RangeError < StandardError (inclui CnpjFmt::Error)
Categoria: Erro de domínio — hidden_start / hidden_end fora de 0–13.
Quando é lançado: Lançado ao construir ou aplicar opções do formatador com índice de ocultação fora do intervalo.
Exemplo:

BrUtils.new.cnpj.format('91415732000793', hidden_start: -1)   # lança CnpjFmt::OutOfRangeError

Como resgatar:

rescue CnpjFmt::OutOfRangeError
  # esta violação exata de intervalo

rescue CnpjFmt::DomainError
  # falhas de domínio com raiz em RangeError de cnpj-fmt

`CnpjFmt::ValidationError`

Herança: CnpjFmt::ValidationError < CnpjFmt::DomainError < RangeError < StandardError (inclui CnpjFmt::Error)
Categoria: Erro de domínio — uma opção de chave contém um caractere proibido.
Quando é lançado: Lançado quando hidden_key, dot_key, slash_key ou dash_key contém um caractere proibido.
Exemplo:

BrUtils.new(cnpj: { formatter: { slash_key: 'å' } })   # lança CnpjFmt::ValidationError

Como resgatar:

rescue CnpjFmt::ValidationError
  # esta falha exata de validação de domínio

rescue CnpjFmt::DomainError
  # falhas de domínio com raiz em RangeError de cnpj-fmt

`CnpjGen::DomainError`

Herança: CnpjGen::DomainError < RangeError < StandardError (inclui CnpjGen::Error)
Categoria: Erro de domínio — ancestral das folhas de domínio do gerador.
Quando é lançado: Não é lançado diretamente; alvo de rescue para CnpjGen::ValidationError.
Exemplo: Prefira rescue CnpjGen::ValidationError ou CnpjGen::DomainError.
Como resgatar:

rescue CnpjGen::DomainError
  # ValidationError e outras subclasses de DomainError de cnpj-gen

`CnpjGen::TypeMismatchError`

Herança: CnpjGen::TypeMismatchError < TypeError < StandardError (inclui CnpjGen::Error)
Categoria: Uso indevido da API — tipo errado para uma opção do gerador.
Quando é lançado: Lançado quando format, prefix ou type tem o tipo de runtime errado.
Exemplo:

BrUtils.new.cnpj.generate(prefix: 123)   # lança CnpjGen::TypeMismatchError

Como resgatar:

rescue CnpjGen::TypeMismatchError
  # violação de contrato de tipo do gerador

rescue TypeError
  # erros nativos de tipo, incluindo CnpjGen::TypeMismatchError

`CnpjGen::InvalidArgumentCombinationError`

Herança: CnpjGen::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui CnpjGen::Error)
Categoria: Uso indevido da API — options e argumentos nomeados misturados na API do gerador.
Quando é lançado: Lançado por CnpjGen::CnpjGenerator / CnpjGen.cnpj_gen quando uma instância/Hash de options e qualquer argumento nomeado não-nil são passados juntos. (O agregador de CNPJ lança CnpjUtils::InvalidArgumentCombinationError para o mesmo padrão em CnpjUtils#generate.)
Exemplo:

CnpjGen::CnpjGenerator.new({ format: true }, prefix: '123')
# lança CnpjGen::InvalidArgumentCombinationError

Como resgatar:

rescue CnpjGen::InvalidArgumentCombinationError
  # combinação inválida de assinatura do gerador

rescue ArgumentError
  # erros nativos de argumento, incluindo este

`CnpjGen::ValidationError`

Herança: CnpjGen::ValidationError < CnpjGen::DomainError < RangeError < StandardError (inclui CnpjGen::Error)
Categoria: Erro de domínio — prefix inelegível ou type não permitido.
Quando é lançado: Lançado quando prefix é base/filial zerada ou 12 dígitos repetidos, ou quando type não é 'alphabetic', 'alphanumeric' ou 'numeric'.
Exemplo:

BrUtils.new.cnpj.generate(type: 'boolean')   # lança CnpjGen::ValidationError

Como resgatar:

rescue CnpjGen::ValidationError
  # esta falha exata de validação de domínio

rescue CnpjGen::DomainError
  # falhas de domínio com raiz em RangeError de cnpj-gen

`CnpjVal::DomainError`

Herança: CnpjVal::DomainError < RangeError < StandardError (inclui CnpjVal::Error)
Categoria: Erro de domínio — ancestral das folhas de domínio do validador.
Quando é lançado: Não é lançado diretamente; alvo de rescue para CnpjVal::ValidationError.
Exemplo: Prefira rescue CnpjVal::ValidationError ou CnpjVal::DomainError.
Como resgatar:

rescue CnpjVal::DomainError
  # ValidationError e outras subclasses de DomainError de cnpj-val

`CnpjVal::TypeMismatchError`

Herança: CnpjVal::TypeMismatchError < TypeError < StandardError (inclui CnpjVal::Error)
Categoria: Uso indevido da API — tipo errado para entrada de CNPJ ou opção do validador.
Quando é lançado: Lançado quando #is_valid / cnpj_val recebe um valor que não é String nem Array de strings, ou uma opção do validador tem o tipo errado. Dados de CNPJ inválidos retornam false e não lançam.
Exemplo:

BrUtils.new.cnpj.is_valid(12_345_678_000_198)   # lança CnpjVal::TypeMismatchError
BrUtils.new.cnpj.is_valid('00000000000000')     # => false (dados inválidos, sem raise)

Como resgatar:

rescue CnpjVal::TypeMismatchError
  # violação de contrato de tipo do validador

rescue TypeError
  # erros nativos de tipo, incluindo CnpjVal::TypeMismatchError

`CnpjVal::InvalidArgumentCombinationError`

Herança: CnpjVal::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui CnpjVal::Error)
Categoria: Uso indevido da API — options e argumentos nomeados misturados na API do validador.
Quando é lançado: Lançado por CnpjVal::CnpjValidator / CnpjVal.cnpj_val quando uma instância/Hash de options e qualquer argumento nomeado não-nil são passados juntos. (O agregador de CNPJ lança CnpjUtils::InvalidArgumentCombinationError para o mesmo padrão em CnpjUtils#is_valid.)
Exemplo:

CnpjVal.cnpj_val('98765432000198', { type: 'numeric' }, case_sensitive: false)
# lança CnpjVal::InvalidArgumentCombinationError

Como resgatar:

rescue CnpjVal::InvalidArgumentCombinationError
  # combinação inválida de assinatura do validador

rescue ArgumentError
  # erros nativos de argumento, incluindo este

`CnpjVal::ValidationError`

Herança: CnpjVal::ValidationError < CnpjVal::DomainError < RangeError < StandardError (inclui CnpjVal::Error)
Categoria: Erro de domínio — type do validador não permitido.
Quando é lançado: Lançado quando type não é 'alphanumeric' nem 'numeric'.
Exemplo:

BrUtils.new.cnpj.is_valid('91415732000793', type: 'boolean')   # lança CnpjVal::ValidationError

Como resgatar:

rescue CnpjVal::ValidationError
  # esta falha exata de validação de domínio

rescue CnpjVal::DomainError
  # falhas de domínio com raiz em RangeError de cnpj-val

`CpfUtils::TypeMismatchError`

Herança: CpfUtils::TypeMismatchError < TypeError < StandardError (inclui CpfUtils::Error)
Categoria: Uso indevido da API — o caller passou um valor do tipo errado.
Quando é lançado: Quando CpfUtils.new recebe um argumento settings não-nil que não é um Hash.
Exemplo:

CpfUtils.new('not-a-hash')   # lança CpfUtils::TypeMismatchError
CpfUtils.new(false)          # lança CpfUtils::TypeMismatchError (false é não-nil)

Como resgatar:

rescue CpfUtils::TypeMismatchError
  # violação de contrato de tipo do agregador de CPF (não BrUtils::Error)

rescue TypeError
  # erros nativos de tipo, incluindo CpfUtils::TypeMismatchError

`CpfUtils::InvalidArgumentCombinationError`

Herança: CpfUtils::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui CpfUtils::Error)
Categoria: Uso indevido da API — o caller misturou padrões de argumentos mutuamente exclusivos.
Quando é lançado: Quando CpfUtils.new recebe um Hash de settings não-nil e qualquer argumento nomeado não-nil, ou quando #format / #generate misturam um Hash/*Options de options não-nil com qualquer argumento nomeado não-nil. #is_valid não tem caminho de options e não lança este erro.
Exemplo:

BrUtils.new.cpf.format({ hidden: true }, dash_key: '|')
# lança CpfUtils::InvalidArgumentCombinationError

Como resgatar:

rescue CpfUtils::InvalidArgumentCombinationError
  # combinação inválida de assinatura do agregador de CPF (não BrUtils::Error)

rescue ArgumentError
  # erros nativos de argumento, incluindo CpfUtils::InvalidArgumentCombinationError

`CnpjUtils::TypeMismatchError`

Herança: CnpjUtils::TypeMismatchError < TypeError < StandardError (inclui CnpjUtils::Error)
Categoria: Uso indevido da API — o caller passou um valor do tipo errado.
Quando é lançado: Quando CnpjUtils.new recebe um argumento settings não-nil que não é um Hash.
Exemplo:

CnpjUtils.new('not-a-hash')   # lança CnpjUtils::TypeMismatchError
CnpjUtils.new(false)          # lança CnpjUtils::TypeMismatchError (false é não-nil)

Como resgatar:

rescue CnpjUtils::TypeMismatchError
  # violação de contrato de tipo do agregador de CNPJ (não BrUtils::Error)

rescue TypeError
  # erros nativos de tipo, incluindo CnpjUtils::TypeMismatchError

`CnpjUtils::InvalidArgumentCombinationError`

Herança: CnpjUtils::InvalidArgumentCombinationError < ArgumentError < StandardError (inclui CnpjUtils::Error)
Categoria: Uso indevido da API — o caller misturou padrões de argumentos mutuamente exclusivos.
Quando é lançado: Quando CnpjUtils.new, #format, #generate, #is_valid ou os helpers de classe recebem um Hash/instância de settings/options não-nil e qualquer argumento nomeado não-nil ao mesmo tempo.
Exemplo:

BrUtils.new.cnpj.format({ hidden: true }, slash_key: '|')
# lança CnpjUtils::InvalidArgumentCombinationError

Como resgatar:

rescue CnpjUtils::InvalidArgumentCombinationError
  # combinação inválida de assinatura do agregador de CNPJ (não BrUtils::Error)

rescue ArgumentError
  # erros nativos de argumento, incluindo CnpjUtils::InvalidArgumentCombinationError

Pacotes incluídos

Pacote	Principais recursos	README
`cpf-utilities`	`CpfUtils`, `CpfFormatter`, `CpfGenerator`, `CpfValidator`, `CpfFmt.cpf_fmt`, `CpfGen.cpf_gen`, `CpfVal.cpf_val`	docs
`cnpj-utilities`	`CnpjUtils`, `CnpjFormatter`, `CnpjGenerator`, `CnpjValidator`, `CnpjFmt.cnpj_fmt`, `CnpjGen.cnpj_gen`, `CnpjVal.cnpj_val`	docs

Todos os acima são puxados como dependências de br-utilities. Demos interativas: CPF e CNPJ.

Contribuição e suporte

Contribuições são bem-vindas! Consulte as Diretrizes de contribuição. Se o projeto for útil para você, considere:

⭐ Dar uma estrela no repositório
🤝 Contribuir com código
💡 Sugerir novas funcionalidades
🐛 Reportar bugs

Licença

Este projeto está sob a licença MIT — veja o arquivo LICENSE.

Changelog

Veja o CHANGELOG para alterações e histórico de versões.

Feito com ❤️ por Lacus Solutions

Suporte a Ruby​

Recursos​

Instalação​

Require​

Início rápido​

Utilização​

Helpers de classe (BrUtils.cpf / .cnpj)​

BrUtils::DEFAULT (instância padrão)​

BrUtils (classe)​

Padrões da instância e sobrescritas por chamada​

Operações de CPF​

Formatação (#format / CpfFmt.cpf_fmt)​

Geração (#generate / CpfGen.cpf_gen)​

Validação (#is_valid / CpfVal.cpf_val)​

Operações de CNPJ​

Formatação (#format / CnpjFmt.cnpj_fmt)​

Geração (#generate / CnpjGen.cnpj_gen)​

Validação (#is_valid / CnpjVal.cnpj_val)​

Agregadores de domínio (isolados)​

Acessando componentes​

Usando classes componentes e módulos aninhados​

Misturando estilos​

API​

Exportações​

Erros e exceções​

Definidos por br-utilities​

Resumo​

BrUtils::Error (módulo marcador)​

BrUtils::TypeMismatchError​

BrUtils::InvalidArgumentCombinationError​

Granularidade de rescue​

Propagados dos pacotes incluídos​

Resumo​

CpfFmt::DomainError​

CpfFmt::TypeMismatchError​

CpfFmt::InvalidArgumentCombinationError​

CpfFmt::InvalidLengthError (entregue via callback)​

CpfFmt::OutOfRangeError​

CpfFmt::ValidationError​

CpfGen::DomainError​

CpfGen::TypeMismatchError​

CpfGen::InvalidArgumentCombinationError​

CpfGen::ValidationError​

CpfVal::TypeMismatchError​

CnpjFmt::DomainError​

CnpjFmt::TypeMismatchError​

CnpjFmt::InvalidArgumentCombinationError​

CnpjFmt::InvalidLengthError (entregue via callback)​

CnpjFmt::OutOfRangeError​

CnpjFmt::ValidationError​

CnpjGen::DomainError​

CnpjGen::TypeMismatchError​

CnpjGen::InvalidArgumentCombinationError​

CnpjGen::ValidationError​

CnpjVal::DomainError​

CnpjVal::TypeMismatchError​

CnpjVal::InvalidArgumentCombinationError​

CnpjVal::ValidationError​

CpfUtils::TypeMismatchError​

CpfUtils::InvalidArgumentCombinationError​

CnpjUtils::TypeMismatchError​

CnpjUtils::InvalidArgumentCombinationError​

Pacotes incluídos​

Contribuição e suporte​

Licença​

Changelog​

Suporte a Ruby

Recursos

Instalação

Require

Início rápido

Utilização

Helpers de classe (`BrUtils.cpf` / `.cnpj`)

`BrUtils::DEFAULT` (instância padrão)

`BrUtils` (classe)

Padrões da instância e sobrescritas por chamada

Operações de CPF

Formatação (`#format` / `CpfFmt.cpf_fmt`)

Geração (`#generate` / `CpfGen.cpf_gen`)

Validação (`#is_valid` / `CpfVal.cpf_val`)

Operações de CNPJ

Formatação (`#format` / `CnpjFmt.cnpj_fmt`)

Geração (`#generate` / `CnpjGen.cnpj_gen`)

Validação (`#is_valid` / `CnpjVal.cnpj_val`)

Agregadores de domínio (isolados)

Acessando componentes

Usando classes componentes e módulos aninhados

Misturando estilos

API

Exportações

Erros e exceções

Definidos por `br-utilities`

Resumo

`BrUtils::Error` (módulo marcador)

`BrUtils::TypeMismatchError`

`BrUtils::InvalidArgumentCombinationError`

Granularidade de rescue

Propagados dos pacotes incluídos

Resumo

`CpfFmt::DomainError`

`CpfFmt::TypeMismatchError`

`CpfFmt::InvalidArgumentCombinationError`

`CpfFmt::InvalidLengthError` (entregue via callback)

`CpfFmt::OutOfRangeError`

`CpfFmt::ValidationError`

`CpfGen::DomainError`

`CpfGen::TypeMismatchError`

`CpfGen::InvalidArgumentCombinationError`

`CpfGen::ValidationError`

`CpfVal::TypeMismatchError`

`CnpjFmt::DomainError`

`CnpjFmt::TypeMismatchError`

`CnpjFmt::InvalidArgumentCombinationError`

`CnpjFmt::InvalidLengthError` (entregue via callback)

`CnpjFmt::OutOfRangeError`

`CnpjFmt::ValidationError`

`CnpjGen::DomainError`

`CnpjGen::TypeMismatchError`

`CnpjGen::InvalidArgumentCombinationError`

`CnpjGen::ValidationError`

`CnpjVal::DomainError`

`CnpjVal::TypeMismatchError`

`CnpjVal::InvalidArgumentCombinationError`

`CnpjVal::ValidationError`

`CpfUtils::TypeMismatchError`

`CpfUtils::InvalidArgumentCombinationError`

`CnpjUtils::TypeMismatchError`

`CnpjUtils::InvalidArgumentCombinationError`

Pacotes incluídos

Contribuição e suporte

Licença

Changelog