br-utils 0.1.0

data/examples/cep_usage_example.rb

@@ -0,0 +1,148 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Exemplo de uso do BrazilianUtils::CEPUtils
+# Este arquivo demonstra todas as funcionalidades implementadas
+
+require_relative 'lib/brazilian-utils/cep-utils'
+
+puts '=' * 80
+puts 'BrazilianUtils::CEPUtils - Exemplos de Uso'
+puts '=' * 80
+puts
+
+# 1. Formatação de CEP
+puts '1. FORMATAÇÃO DE CEP'
+puts '-' * 80
+
+cep_raw = '01310100'
+cep_formatted = BrazilianUtils::CEPUtils.format_cep(cep_raw)
+puts "CEP bruto: #{cep_raw}"
+puts "CEP formatado: #{cep_formatted}"
+puts
+
+# 2. Validação de CEP
+puts '2. VALIDAÇÃO DE CEP'
+puts '-' * 80
+
+test_ceps = ['01310100', '12345', 'abcdefgh', '12345-678']
+test_ceps.each do |cep|
+  is_valid = BrazilianUtils::CEPUtils.valid?(cep)
+  puts "CEP '#{cep}' é válido? #{is_valid}"
+end
+puts
+
+# 3. Remover símbolos
+puts '3. REMOVER SÍMBOLOS'
+puts '-' * 80
+
+dirty_cep = '01310-100'
+clean_cep = BrazilianUtils::CEPUtils.remove_symbols(dirty_cep)
+puts "CEP com símbolos: #{dirty_cep}"
+puts "CEP limpo: #{clean_cep}"
+puts
+
+# 4. Gerar CEP aleatório
+puts '4. GERAR CEP ALEATÓRIO'
+puts '-' * 80
+
+5.times do |i|
+  random_cep = BrazilianUtils::CEPUtils.generate
+  formatted_random = BrazilianUtils::CEPUtils.format_cep(random_cep)
+  puts "#{i + 1}. CEP aleatório: #{formatted_random}"
+end
+puts
+
+# 5. Validação de UF
+puts '5. VALIDAÇÃO E INFORMAÇÕES DE UF (ESTADO)'
+puts '-' * 80
+
+puts "UF 'SP' é válida? #{BrazilianUtils::UF.valid?('SP')}"
+puts "UF 'XX' é válida? #{BrazilianUtils::UF.valid?('XX')}"
+puts "Nome do estado 'SP': #{BrazilianUtils::UF.name_from_code('SP')}"
+puts "Código do estado 'Rio de Janeiro': #{BrazilianUtils::UF.code_from_name('Rio de Janeiro')}"
+puts
+
+# 6. Buscar endereço por CEP (requer conexão com internet)
+puts '6. BUSCAR ENDEREÇO POR CEP (Requer Internet)'
+puts '-' * 80
+
+test_cep = '01310100' # Avenida Paulista, São Paulo
+puts "Buscando endereço para CEP: #{test_cep}..."
+
+begin
+  address = BrazilianUtils::CEPUtils.get_address_from_cep(test_cep)
+  
+  if address
+    puts "✓ Endereço encontrado!"
+    puts "  CEP: #{address.cep}"
+    puts "  Logradouro: #{address.logradouro}"
+    puts "  Bairro: #{address.bairro}"
+    puts "  Cidade: #{address.localidade}"
+    puts "  UF: #{address.uf}"
+    puts "  IBGE: #{address.ibge}"
+    puts "  DDD: #{address.ddd}"
+  else
+    puts "✗ Endereço não encontrado ou API indisponível"
+  end
+rescue StandardError => e
+  puts "✗ Erro ao buscar endereço: #{e.message}"
+  puts "  (Isso é normal se não houver conexão com a internet)"
+end
+puts
+
+# 7. Buscar CEPs por endereço (requer conexão com internet)
+puts '7. BUSCAR CEPs POR ENDEREÇO (Requer Internet)'
+puts '-' * 80
+
+puts "Buscando CEPs para: SP / São Paulo / Paulista..."
+
+begin
+  addresses = BrazilianUtils::CEPUtils.get_cep_information_from_address('SP', 'São Paulo', 'Paulista')
+  
+  if addresses && addresses.any?
+    puts "✓ Encontrados #{addresses.length} resultados:"
+    addresses.first(5).each_with_index do |addr, idx|
+      puts "  #{idx + 1}. #{addr.cep} - #{addr.logradouro}, #{addr.bairro}"
+    end
+    puts "  ... (mostrando apenas os primeiros 5 resultados)" if addresses.length > 5
+  else
+    puts "✗ Nenhum resultado encontrado ou API indisponível"
+  end
+rescue StandardError => e
+  puts "✗ Erro ao buscar CEPs: #{e.message}"
+  puts "  (Isso é normal se não houver conexão com a internet)"
+end
+puts
+
+# 8. Tratamento de exceções
+puts '8. TRATAMENTO DE EXCEÇÕES'
+puts '-' * 80
+
+puts "Testando CEP inválido com raise_exceptions: true"
+begin
+  BrazilianUtils::CEPUtils.get_address_from_cep('invalid', raise_exceptions: true)
+rescue BrazilianUtils::InvalidCEP => e
+  puts "✓ Exceção capturada: #{e.class} - #{e.message}"
+end
+
+puts "\nTestando UF inválida com raise_exceptions: true"
+begin
+  BrazilianUtils::CEPUtils.get_cep_information_from_address('XX', 'City', 'Street', raise_exceptions: true)
+rescue ArgumentError => e
+  puts "✓ Exceção capturada: #{e.class} - #{e.message}"
+end
+puts
+
+# 9. Listando todos os estados brasileiros
+puts '9. TODOS OS ESTADOS BRASILEIROS'
+puts '-' * 80
+
+BrazilianUtils::UF::STATES.each do |code, name|
+  puts "#{code} - #{name}"
+end
+puts
+
+puts '=' * 80
+puts 'Exemplos concluídos!'
+puts '=' * 80

data/examples/cnh_usage_example.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Exemplo de uso do BrazilianUtils::CNHUtils
+# Este arquivo demonstra todas as funcionalidades implementadas
+
+require_relative '../lib/brazilian-utils/cnh-utils'
+
+puts '=' * 80
+puts 'BrazilianUtils::CNHUtils - Exemplos de Uso'
+puts '=' * 80
+puts
+
+# 1. Validação de CNH válida
+puts '1. VALIDAÇÃO DE CNH VÁLIDA'
+puts '-' * 80
+
+valid_cnhs = [
+  '98765432100',
+  '987654321-00',
+  '987.654.321-00',
+  '987 654 321 00'
+]
+
+valid_cnhs.each do |cnh|
+  is_valid = BrazilianUtils::CNHUtils.valid?(cnh)
+  puts "CNH '#{cnh}' é válida? #{is_valid ? '✓ Sim' : '✗ Não'}"
+end
+puts
+
+# 2. Validação de CNH inválida
+puts '2. VALIDAÇÃO DE CNH INVÁLIDA'
+puts '-' * 80
+
+invalid_cnhs = [
+  { cnh: '12345678901', reason: 'Dígitos verificadores incorretos' },
+  { cnh: 'A2C45678901', reason: 'Contém letras' },
+  { cnh: '00000000000', reason: 'Todos os dígitos iguais' },
+  { cnh: '11111111111', reason: 'Todos os dígitos iguais' },
+  { cnh: '123456789', reason: 'Menos de 11 dígitos' },
+  { cnh: '123456789012', reason: 'Mais de 11 dígitos' },
+  { cnh: '', reason: 'String vazia' },
+  { cnh: '98765432199', reason: 'Segundo dígito verificador incorreto' },
+  { cnh: '98765432190', reason: 'Primeiro dígito verificador incorreto' }
+]
+
+invalid_cnhs.each do |item|
+  is_valid = BrazilianUtils::CNHUtils.valid?(item[:cnh])
+  status = is_valid ? '✗ Inesperadamente válida' : '✓ Corretamente inválida'
+  puts "CNH '#{item[:cnh]}' - #{item[:reason]}"
+  puts "  Resultado: #{status}"
+end
+puts
+
+# 3. Testando com diferentes formatos
+puts '3. TESTANDO DIFERENTES FORMATOS DE ENTRADA'
+puts '-' * 80
+
+test_formats = [
+  { input: '98765432100', description: 'Apenas números' },
+  { input: '987-654-321-00', description: 'Com hífens' },
+  { input: '987.654.321-00', description: 'Com pontos e hífen' },
+  { input: '987 654 321 00', description: 'Com espaços' },
+  { input: '987/654/321-00', description: 'Com barras e hífen' },
+  { input: 98765432100, description: 'Como número inteiro' }
+]
+
+test_formats.each do |format|
+  is_valid = BrazilianUtils::CNHUtils.valid?(format[:input])
+  puts "Formato: #{format[:description]}"
+  puts "  Entrada: #{format[:input]}"
+  puts "  Válido? #{is_valid ? '✓ Sim' : '✗ Não'}"
+end
+puts
+
+# 4. Testando sequências de dígitos iguais
+puts '4. TESTANDO SEQUÊNCIAS DE DÍGITOS IGUAIS (DEVEM SER INVÁLIDAS)'
+puts '-' * 80
+
+(0..9).each do |digit|
+  cnh = digit.to_s * 11
+  is_valid = BrazilianUtils::CNHUtils.valid?(cnh)
+  status = is_valid ? '✗ ERRO: Foi aceita!' : '✓ Corretamente rejeitada'
+  puts "CNH '#{cnh}' - #{status}"
+end
+puts
+
+# 5. Casos especiais
+puts '5. CASOS ESPECIAIS'
+puts '-' * 80
+
+special_cases = [
+  { input: nil, description: 'nil' },
+  { input: '', description: 'String vazia' },
+  { input: '---...', description: 'Apenas símbolos' },
+  { input: 'ABCDEFGHIJK', description: 'Apenas letras' },
+  { input: 'ABC12345678', description: 'Letras e números misturados' }
+]
+
+special_cases.each do |special|
+  is_valid = BrazilianUtils::CNHUtils.valid?(special[:input])
+  puts "#{special[:description]}: #{special[:input].inspect}"
+  puts "  Válido? #{is_valid ? '✗ Inesperadamente válido' : '✓ Corretamente inválido'}"
+end
+puts
+
+# 6. Resumo
+puts '6. RESUMO'
+puts '-' * 80
+puts 'A biblioteca CNHUtils valida CNHs brasileiras seguindo as regras:'
+puts '  1. Deve ter exatamente 11 dígitos (após remover símbolos)'
+puts '  2. Não pode ser uma sequência de dígitos iguais'
+puts '  3. Os dois últimos dígitos são verificadores calculados'
+puts '  4. Símbolos e espaços são automaticamente ignorados'
+puts '  5. Suporta apenas CNHs criadas a partir de 2022'
+puts
+
+puts '=' * 80
+puts 'Exemplos concluídos!'
+puts '=' * 80

data/examples/cnpj_usage_example.rb

@@ -0,0 +1,227 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Exemplo de uso do BrazilianUtils::CNPJUtils
+# Este arquivo demonstra todas as funcionalidades implementadas
+
+require_relative '../lib/brazilian-utils/cnpj-utils'
+
+puts '=' * 80
+puts 'BrazilianUtils::CNPJUtils - Exemplos de Uso'
+puts '=' * 80
+puts
+
+# 1. Remover símbolos
+puts '1. REMOVER SÍMBOLOS DE CNPJ'
+puts '-' * 80
+
+dirty_cnpjs = [
+  '12.345/6789-01',
+  '98/76.543-2101',
+  '03.560.714/0001-42'
+]
+
+dirty_cnpjs.each do |cnpj|
+  clean = BrazilianUtils::CNPJUtils.remove_symbols(cnpj)
+  puts "Original: #{cnpj.ljust(20)} → Limpo: #{clean}"
+end
+puts
+
+# 2. Formatação com display (legacy)
+puts '2. FORMATAÇÃO COM DISPLAY (LEGACY)'
+puts '-' * 80
+
+cnpjs_to_display = [
+  '12345678901234',
+  '98765432100100',
+  '00000000000000'
+]
+
+cnpjs_to_display.each do |cnpj|
+  formatted = BrazilianUtils::CNPJUtils.display(cnpj)
+  status = formatted ? "✓ #{formatted}" : '✗ nil (inválido)'
+  puts "CNPJ: #{cnpj} → #{status}"
+end
+puts
+
+# 3. Formatação com format_cnpj
+puts '3. FORMATAÇÃO COM FORMAT_CNPJ'
+puts '-' * 80
+
+cnpjs_to_format = [
+  { cnpj: '03560714000142', description: 'CNPJ válido' },
+  { cnpj: '98765432100100', description: 'CNPJ inválido' },
+  { cnpj: '11222333000181', description: 'CNPJ válido' }
+]
+
+cnpjs_to_format.each do |item|
+  formatted = BrazilianUtils::CNPJUtils.format_cnpj(item[:cnpj])
+  status = formatted ? "✓ #{formatted}" : '✗ nil (inválido)'
+  puts "#{item[:description]}: #{item[:cnpj]}"
+  puts "  Formatado: #{status}"
+end
+puts
+
+# 4. Validação de CNPJ
+puts '4. VALIDAÇÃO DE CNPJ'
+puts '-' * 80
+
+valid_cnpjs = [
+  '03560714000142',
+  '11222333000181',
+  '11444777000161'
+]
+
+puts 'CNPJs Válidos:'
+valid_cnpjs.each do |cnpj|
+  is_valid = BrazilianUtils::CNPJUtils.valid?(cnpj)
+  formatted = BrazilianUtils::CNPJUtils.format_cnpj(cnpj)
+  status = is_valid ? '✓ Válido' : '✗ Inválido'
+  puts "  #{formatted} - #{status}"
+end
+puts
+
+invalid_cnpjs = [
+  { cnpj: '00111222000133', reason: 'Dígitos verificadores incorretos' },
+  { cnpj: '11222333000180', reason: 'Último dígito incorreto' },
+  { cnpj: '00000000000000', reason: 'Todos os dígitos iguais' },
+  { cnpj: '12345678901234', reason: 'Dígitos aleatórios' }
+]
+
+puts 'CNPJs Inválidos:'
+invalid_cnpjs.each do |item|
+  is_valid = BrazilianUtils::CNPJUtils.valid?(item[:cnpj])
+  status = is_valid ? '✗ ERRO: Foi aceito!' : '✓ Corretamente rejeitado'
+  puts "  #{item[:cnpj]} - #{item[:reason]}"
+  puts "    #{status}"
+end
+puts
+
+# 5. Geração de CNPJ
+puts '5. GERAÇÃO DE CNPJ ALEATÓRIO'
+puts '-' * 80
+
+puts 'Gerando CNPJs com diferentes filiais:'
+branches = [1, 42, 100, 1234, 9999]
+
+branches.each do |branch|
+  cnpj = BrazilianUtils::CNPJUtils.generate(branch: branch)
+  formatted = BrazilianUtils::CNPJUtils.format_cnpj(cnpj)
+  puts "  Filial #{branch.to_s.rjust(4, '0')}: #{formatted}"
+end
+puts
+
+puts 'Gerando 5 CNPJs aleatórios com filial padrão (0001):'
+5.times do |i|
+  cnpj = BrazilianUtils::CNPJUtils.generate
+  formatted = BrazilianUtils::CNPJUtils.format_cnpj(cnpj)
+  is_valid = BrazilianUtils::CNPJUtils.valid?(cnpj)
+  status = is_valid ? '✓' : '✗'
+  puts "  #{i + 1}. #{formatted} #{status}"
+end
+puts
+
+# 6. Workflow completo
+puts '6. WORKFLOW COMPLETO: GERAR → FORMATAR → LIMPAR → VALIDAR'
+puts '-' * 80
+
+# Gerar
+cnpj = BrazilianUtils::CNPJUtils.generate(branch: 42)
+puts "1. Gerado: #{cnpj}"
+
+# Formatar
+formatted = BrazilianUtils::CNPJUtils.format_cnpj(cnpj)
+puts "2. Formatado: #{formatted}"
+
+# Simular recebimento de um CNPJ formatado
+puts "3. Simulando recebimento de CNPJ formatado: #{formatted}"
+
+# Limpar símbolos
+cleaned = BrazilianUtils::CNPJUtils.remove_symbols(formatted)
+puts "4. Limpo: #{cleaned}"
+
+# Validar
+is_valid = BrazilianUtils::CNPJUtils.valid?(cleaned)
+puts "5. Válido? #{is_valid ? '✓ Sim' : '✗ Não'}"
+
+# Verificar se é o mesmo CNPJ original
+puts "6. É o mesmo CNPJ? #{cleaned == cnpj ? '✓ Sim' : '✗ Não'}"
+puts
+
+# 7. Testando CNPJs com todos os dígitos iguais
+puts '7. TESTANDO CNPJs COM TODOS OS DÍGITOS IGUAIS (DEVEM SER INVÁLIDOS)'
+puts '-' * 80
+
+(0..9).each do |digit|
+  cnpj = digit.to_s * 14
+  is_valid = BrazilianUtils::CNPJUtils.valid?(cnpj)
+  status = is_valid ? '✗ ERRO: Foi aceito!' : '✓ Corretamente rejeitado'
+  puts "CNPJ #{cnpj} - #{status}"
+end
+puts
+
+# 8. Casos especiais
+puts '8. CASOS ESPECIAIS'
+puts '-' * 80
+
+special_cases = [
+  { input: '00000000000191', description: 'CNPJ com zeros à esquerda' },
+  { input: '03560714000143', description: 'CNPJ com último dígito errado' },
+  { input: '03560714000141', description: 'CNPJ com penúltimo dígito errado' },
+  { input: '123456789012', description: 'CNPJ com 12 dígitos (muito curto)' },
+  { input: '123456789012345', description: 'CNPJ com 15 dígitos (muito longo)' }
+]
+
+special_cases.each do |item|
+  is_valid = BrazilianUtils::CNPJUtils.valid?(item[:input])
+  status = is_valid ? '✓ Válido' : '✗ Inválido'
+  puts "#{item[:description]}:"
+  puts "  CNPJ: #{item[:input]}"
+  puts "  Status: #{status}"
+end
+puts
+
+# 9. Comparação entre métodos (valid? vs validate, format_cnpj vs display)
+puts '9. COMPARAÇÃO ENTRE MÉTODOS'
+puts '-' * 80
+
+test_cnpj = '03560714000142'
+puts "CNPJ de teste: #{test_cnpj}"
+puts
+puts 'valid? vs validate:'
+puts "  valid?(cnpj):    #{BrazilianUtils::CNPJUtils.valid?(test_cnpj)}"
+puts "  validate(cnpj):  #{BrazilianUtils::CNPJUtils.validate(test_cnpj)}"
+puts
+puts 'format_cnpj vs display:'
+puts "  format_cnpj(cnpj): #{BrazilianUtils::CNPJUtils.format_cnpj(test_cnpj)}"
+puts "  display(cnpj):     #{BrazilianUtils::CNPJUtils.display(test_cnpj)}"
+puts
+puts 'remove_symbols vs sieve:'
+formatted = BrazilianUtils::CNPJUtils.format_cnpj(test_cnpj)
+puts "  remove_symbols(formatted): #{BrazilianUtils::CNPJUtils.remove_symbols(formatted)}"
+puts "  sieve(formatted):          #{BrazilianUtils::CNPJUtils.sieve(formatted)}"
+puts
+
+# 10. Resumo
+puts '10. RESUMO'
+puts '-' * 80
+puts 'A biblioteca CNPJUtils oferece:'
+puts '  1. Remoção de símbolos: remove_symbols() / sieve()'
+puts '  2. Formatação: format_cnpj() / display()'
+puts '  3. Validação: valid?() / validate()'
+puts '  4. Geração: generate(branch:)'
+puts
+puts 'Regras de validação:'
+puts '  • Deve ter exatamente 14 dígitos'
+puts '  • Não pode ser uma sequência de dígitos iguais'
+puts '  • Os dois últimos dígitos são verificadores calculados'
+puts
+puts 'Estrutura do CNPJ: XX.XXX.XXX/FFFF-VV'
+puts '  XX.XXX.XXX = Base (8 dígitos)'
+puts '  FFFF       = Filial (4 dígitos)'
+puts '  VV         = Verificadores (2 dígitos)'
+puts
+
+puts '=' * 80
+puts 'Exemplos concluídos!'
+puts '=' * 80