br-utils 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 23f897e35167135baa4eeb00f625bdd6f69656b86ce6ca62229f2dcd4a718f94
+  data.tar.gz: 1737c2f0bc7a3799ee6a3c87d8bf065a27b992eefe4fe4907be0c0f92536bc5e
+SHA512:
+  metadata.gz: d8e78d62b1b1c5173d2eed7088c55dfe3e7934d3faf0d6f527e654242228900fcebb29ac6fe84d5023a779292453d57a22f1ba954aa979c768b515ba5ac94c4e
+  data.tar.gz: 6978c693525a310ec21fac4a00c76128fe374bc0aed83c5a897f2a62dabc57578be80dafee3be11cab72bcd106749cc966d53518caa26477568c229ebcdde994

data/.gitignore

@@ -0,0 +1,120 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+
+# Created by https://www.gitignore.io/api/ruby,rubymine
+
+### Ruby ###
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+
+### RubyMine ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff:
+.idea/workspace.xml
+.idea/tasks.xml
+.idea/dictionaries
+.idea/vcs.xml
+.idea/jsLibraryMappings.xml
+*.idea
+
+# Sensitive or high-churn files:
+.idea/dataSources.ids
+.idea/dataSources.xml
+.idea/dataSources.local.xml
+.idea/sqlDataSources.xml
+.idea/dynamic.xml
+.idea/uiDesigner.xml
+
+# Gradle:
+.idea/gradle.xml
+.idea/libraries
+
+# Mongo Explorer plugin:
+.idea/mongoSettings.xml
+
+## File-based project format:
+*.iws
+
+## Plugin-specific files:
+
+# IntelliJ
+/out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+### RubyMine Patch ###
+# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
+
+# *.iml
+# modules.xml
+# .idea/misc.xml 
+# *.ipr

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.12.5

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Alex Rocha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,348 @@
+# :brazil: Brazilian Utils
+
+> Biblioteca de utilitários para dados específicos do Brasil / Utils library for Brazilian-specific data
+
+[![Gem Version](https://badge.fury.io/rb/pipeme.svg)](https://badge.fury.io/rb/br-utils)
+![](http://ruby-gem-downloads-badge.herokuapp.com/br-utils)
+
+[🇧🇷 Português](#português) | [🇺🇸 English](#english)
+
+---
+
+## Português
+
+### 📋 Recursos
+
+Utilitários para trabalhar com formatos de dados brasileiros:
+
+- **CPF** - Validação, formatação e geração
+- **CNH** - Validação de Carteira Nacional de Habilitação
+- **CNPJ** - Validação, formatação e geração
+- **CEP** - Validação, formatação e busca via API ViaCEP
+- **Moeda** - Formatação de Real (R$) e conversão para extenso
+- **Data** - Verificação de feriados e conversão para texto
+- **Email** - Validação (RFC 5322)
+- **Natureza Jurídica** - Validação de códigos oficiais
+- **Processos Judiciais** - Validação, formatação e geração
+- **Placas de Veículos** - Validação e conversão (antigo/Mercosul)
+- **Telefone** - Validação e formatação (móvel/fixo)
+- **PIS** - Validação, formatação e geração (PIS/PASEP)
+- **RENAVAM** - Validação de registro de veículos
+- **Título de Eleitor** - Validação, formatação e geração
+
+### 💾 Instalação
+
+```ruby
+gem 'br-utils'
+```
+
+```bash
+bundle install
+```
+
+### 🚀 Uso Rápido
+
+```ruby
+# CPF
+require 'brazilian-utils/cpf-utils'
+BrazilianUtils::CPFUtils.is_valid('11144477735')  # => true
+BrazilianUtils::CPFUtils.format_cpf('11144477735')  # => "111.444.777-35"
+BrazilianUtils::CPFUtils.generate  # => "12345678901"
+
+# CNPJ
+require 'brazilian-utils/cnpj-utils'
+BrazilianUtils::CNPJUtils.is_valid('34665388000161')  # => true
+BrazilianUtils::CNPJUtils.format_cnpj('34665388000161')  # => "34.665.388/0001-61"
+
+# CEP
+require 'brazilian-utils/cep-utils'
+BrazilianUtils::CEPUtils.format_cep('01310100')  # => "01310-100"
+BrazilianUtils::CEPUtils.get_address('01310100')  # => {...endereço completo...}
+
+# Telefone
+require 'brazilian-utils/phone-utils'
+BrazilianUtils::PhoneUtils.is_valid('11987654321')  # => true
+BrazilianUtils::PhoneUtils.format('11987654321')  # => "(11)98765-4321"
+
+# Placa de Veículo
+require 'brazilian-utils/license-plate-utils'
+BrazilianUtils::LicensePlateUtils.is_valid('ABC1234')  # => true
+BrazilianUtils::LicensePlateUtils.convert_to_mercosul('ABC1234')  # => "ABC1C34"
+
+# Título de Eleitor
+require 'brazilian-utils/voter-id-utils'
+BrazilianUtils::VoterIdUtils.is_valid_voter_id('690847092828')  # => true
+BrazilianUtils::VoterIdUtils.format('690847092828')  # => "6908 4709 28 28"
+BrazilianUtils::VoterIdUtils.generate('SP')  # => "123456780140"
+
+# Moeda
+require 'brazilian-utils/currency-utils'
+BrazilianUtils::CurrencyUtils.format_currency(1234.56)  # => "R$ 1.234,56"
+BrazilianUtils::CurrencyUtils.number_to_text(1234.56)  # => "mil duzentos e trinta e quatro reais..."
+```
+
+### 📚 Documentação Detalhada
+
+Para exemplos completos de cada utilitário, consulte a pasta [`examples/`](examples/).
+
+**Principais Módulos:**
+- [`CPFUtils`](lib/brazilian-utils/cpf-utils.rb) - Validação e formatação de CPF
+- [`CNPJUtils`](lib/brazilian-utils/cnpj-utils.rb) - Validação e formatação de CNPJ
+- [`CEPUtils`](lib/brazilian-utils/cep-utils.rb) - Validação de CEP e busca de endereços
+- [`PhoneUtils`](lib/brazilian-utils/phone-utils.rb) - Validação de telefones
+- [`LicensePlateUtils`](lib/brazilian-utils/license-plate-utils.rb) - Placas de veículos
+- [`VoterIdUtils`](lib/brazilian-utils/voter-id-utils.rb) - Títulos de eleitor
+- [`CurrencyUtils`](lib/brazilian-utils/currency-utils.rb) - Formatação de moeda
+- [`DateUtils`](lib/brazilian-utils/date-utils.rb) - Feriados e datas por extenso
+- [`EmailUtils`](lib/brazilian-utils/email-utils.rb) - Validação de email
+- [`LegalNatureUtils`](lib/brazilian-utils/legal-nature-utils.rb) - Natureza jurídica
+- [`LegalProcessUtils`](lib/brazilian-utils/legal-process-utils.rb) - Processos judiciais
+- [`PISUtils`](lib/brazilian-utils/pis-utils.rb) - PIS/PASEP
+- [`RENAVAMUtils`](lib/brazilian-utils/renavam-utils.rb) - RENAVAM
+- [`CNHUtils`](lib/brazilian-utils/cnh-utils.rb) - CNH
+
+---
+
+## English
+
+### 📋 Features
+
+Utilities for working with Brazilian data formats:
+
+- **CPF** - Validation, formatting, and generation
+- **CNH** - Driver's license validation
+- **CNPJ** - Company tax ID validation, formatting, and generation
+- **CEP** - Postal code validation, formatting, and address lookup (ViaCEP API)
+- **Currency** - Brazilian Real (R$) formatting and text conversion
+- **Date** - Holiday checking and date-to-text conversion
+- **Email** - Email validation (RFC 5322)
+- **Legal Nature** - Official business entity code validation
+- **Legal Process** - Judicial process ID validation, formatting, and generation
+- **License Plate** - Vehicle plate validation and format conversion (old/Mercosul)
+- **Phone** - Mobile and landline validation and formatting
+- **PIS** - Social security number validation, formatting, and generation
+- **RENAVAM** - Vehicle registration validation
+- **Voter ID** - Voter registration validation, formatting, and generation
+
+### 💾 Installation
+
+```ruby
+gem 'br-utils'
+```
+
+```bash
+bundle install
+```
+
+### 🚀 Quick Start
+
+```ruby
+# CPF
+require 'brazilian-utils/cpf-utils'
+BrazilianUtils::CPFUtils.is_valid('11144477735')  # => true
+BrazilianUtils::CPFUtils.format_cpf('11144477735')  # => "111.444.777-35"
+BrazilianUtils::CPFUtils.generate  # => "12345678901"
+
+# CNPJ
+require 'brazilian-utils/cnpj-utils'
+BrazilianUtils::CNPJUtils.is_valid('34665388000161')  # => true
+BrazilianUtils::CNPJUtils.format_cnpj('34665388000161')  # => "34.665.388/0001-61"
+
+# CEP (Postal Code)
+require 'brazilian-utils/cep-utils'
+BrazilianUtils::CEPUtils.format_cep('01310100')  # => "01310-100"
+BrazilianUtils::CEPUtils.get_address('01310100')  # => {...complete address...}
+
+# Phone
+require 'brazilian-utils/phone-utils'
+BrazilianUtils::PhoneUtils.is_valid('11987654321')  # => true
+BrazilianUtils::PhoneUtils.format('11987654321')  # => "(11)98765-4321"
+
+# License Plate
+require 'brazilian-utils/license-plate-utils'
+BrazilianUtils::LicensePlateUtils.is_valid('ABC1234')  # => true
+BrazilianUtils::LicensePlateUtils.convert_to_mercosul('ABC1234')  # => "ABC1C34"
+
+# Voter ID
+require 'brazilian-utils/voter-id-utils'
+BrazilianUtils::VoterIdUtils.is_valid_voter_id('690847092828')  # => true
+BrazilianUtils::VoterIdUtils.format('690847092828')  # => "6908 4709 28 28"
+BrazilianUtils::VoterIdUtils.generate('SP')  # => "123456780140"
+
+# Currency
+require 'brazilian-utils/currency-utils'
+BrazilianUtils::CurrencyUtils.format_currency(1234.56)  # => "R$ 1.234,56"
+BrazilianUtils::CurrencyUtils.number_to_text(1234.56)  # => "mil duzentos e trinta e quatro reais..."
+```
+
+### 📚 Full Documentation
+
+For detailed examples of each utility, check the [`examples/`](examples/) folder.
+
+**Main Modules:**
+- [`CPFUtils`](lib/brazilian-utils/cpf-utils.rb) - CPF validation and formatting
+- [`CNPJUtils`](lib/brazilian-utils/cnpj-utils.rb) - CNPJ validation and formatting
+- [`CEPUtils`](lib/brazilian-utils/cep-utils.rb) - CEP validation and address lookup
+- [`PhoneUtils`](lib/brazilian-utils/phone-utils.rb) - Phone validation
+- [`LicensePlateUtils`](lib/brazilian-utils/license-plate-utils.rb) - Vehicle plates
+- [`VoterIdUtils`](lib/brazilian-utils/voter-id-utils.rb) - Voter IDs
+- [`CurrencyUtils`](lib/brazilian-utils/currency-utils.rb) - Currency formatting
+- [`DateUtils`](lib/brazilian-utils/date-utils.rb) - Holidays and date text
+- [`EmailUtils`](lib/brazilian-utils/email-utils.rb) - Email validation
+- [`LegalNatureUtils`](lib/brazilian-utils/legal-nature-utils.rb) - Legal nature codes
+- [`LegalProcessUtils`](lib/brazilian-utils/legal-process-utils.rb) - Legal process IDs
+- [`PISUtils`](lib/brazilian-utils/pis-utils.rb) - PIS/PASEP
+- [`RENAVAMUtils`](lib/brazilian-utils/renavam-utils.rb) - Vehicle registration
+- [`CNHUtils`](lib/brazilian-utils/cnh-utils.rb) - Driver's license
+
+---
+
+## 🧪 Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run specific test
+bundle exec rspec spec/cpf_utils_spec.rb
+```
+
+## 📖 API Reference
+
+### Common Patterns
+
+Most utilities follow these patterns:
+
+**Validation:**
+```ruby
+.is_valid(value)      # Main validation method
+.valid?(value)        # Alias for is_valid
+```
+
+**Formatting:**
+```ruby
+.format(value)        # Format with standard symbols
+.remove_symbols(value) # Remove formatting symbols
+```
+
+**Generation:**
+```ruby
+.generate             # Generate random valid value
+```
+
+### Utility-Specific Methods
+
+**CEP:**
+- `get_address(cep)` - Fetch address from CEP
+- `get_cep_information_from_address(uf, city, street)` - Find CEPs
+
+**Phone:**
+- `is_valid(phone, type:)` - Validate with type (:mobile or :landline)
+- `remove_international_dialing_code(phone)` - Remove +55/55
+
+**License Plate:**
+- `convert_to_mercosul(plate)` - Convert old format to Mercosul
+- `get_format(plate)` - Detect format ("LLLNNNN" or "LLLNLNN")
+
+**Voter ID:**
+- `generate(uf)` - Generate for specific state
+
+**Currency:**
+- `format_currency(value)` - Format as R$ X.XXX,XX
+- `number_to_text(value)` - Convert to Brazilian Portuguese text
+
+**Date:**
+- `is_holiday(date, uf)` - Check if date is holiday
+- `convert_date_to_text(date)` - Convert to Portuguese text
+
+**Legal Nature:**
+- `get_description(code)` - Get description for code
+- `list_by_category(category)` - List codes by category (1-5)
+
+**Legal Process:**
+- `generate(year, orgao)` - Generate for specific year and judicial segment
+
+## 📊 Examples by Use Case
+
+### Form Validation
+
+```ruby
+# Validate user input
+cpf = params[:cpf]
+if BrazilianUtils::CPFUtils.valid?(cpf)
+  # Process valid CPF
+else
+  errors.add(:cpf, "inválido")
+end
+```
+
+### Display Formatting
+
+```ruby
+# Format for display
+cpf = "11144477735"
+formatted = BrazilianUtils::CPFUtils.format_cpf(cpf)
+puts formatted  # => "111.444.777-35"
+```
+
+### Test Data Generation
+
+```ruby
+# Generate test data
+10.times do
+  cpf = BrazilianUtils::CPFUtils.generate
+  puts BrazilianUtils::CPFUtils.format_cpf(cpf)
+end
+```
+
+### API Integration
+
+```ruby
+# Lookup address from CEP
+address = BrazilianUtils::CEPUtils.get_address('01310100')
+if address
+  puts "#{address.logradouro}, #{address.bairro}"
+  puts "#{address.localidade} - #{address.uf}"
+end
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit pull requests.
+
+**Como contribuir / How to contribute:**
+
+1. Fork o projeto / Fork the project
+2. Crie seu branch (`git checkout -b feature/AmazingFeature`)
+3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
+4. Push para o branch (`git push origin feature/AmazingFeature`)
+5. Abra um Pull Request / Open a Pull Request
+
+## 📄 License
+
+Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE.txt](LICENSE.txt) para detalhes.
+
+This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
+
+## 🙏 Acknowledgments
+
+Baseado na implementação Python: [brazilian-utils/python](https://github.com/brazilian-utils/python)
+
+Based on the Python implementation: [brazilian-utils/python](https://github.com/brazilian-utils/python)
+
+## 📞 Support
+
+- 🐛 **Issues:** [GitHub Issues](https://github.com/brazilian-utils/ruby/issues)
+- 📖 **Documentation:** [examples/](examples/) folder
+- 💬 **Discussions:** [GitHub Discussions](https://github.com/brazilian-utils/ruby/discussions)
+
+---
+
+<div align="center">
+Made with ❤️ for the Brazilian Ruby community
+</div>

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/examples/boleto_usage_example.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative '../lib/brazilian-utils/boleto-utils'
+
+# Examples of using BoletoUtils module
+
+puts '=' * 80
+puts 'Boleto Utils - Usage Examples'
+puts '=' * 80
+puts
+
+# Example 1: Validating a correct boleto digitable line
+puts '1. Validating a correct boleto digitable line (47 digits):'
+valid_boleto = '00190000090114971860168524522114675860000102656'
+puts "   Boleto: #{valid_boleto}"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.is_valid(valid_boleto)}"
+puts
+
+# Example 2: Validating a formatted boleto digitable line (with spaces and dots)
+puts '2. Validating a formatted boleto digitable line:'
+formatted_boleto = '0019000009 01149.718601 68524.522114 6 75860000102656'
+puts "   Boleto: #{formatted_boleto}"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.is_valid(formatted_boleto)}"
+puts
+
+# Example 3: Validating an invalid boleto (wrong first partial check digit)
+puts '3. Validating an invalid boleto (wrong first partial check digit):'
+invalid_boleto_1 = '00190000020114971860168524522114675860000102656'
+puts "   Boleto: #{invalid_boleto_1}"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.is_valid(invalid_boleto_1)}"
+puts
+
+# Example 4: Validating an invalid boleto (wrong mod11 check digit)
+puts '4. Validating an invalid boleto (wrong mod11 check digit):'
+invalid_boleto_2 = '00190000090114971860168524522114975860000102656'
+puts "   Boleto: #{invalid_boleto_2}"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.is_valid(invalid_boleto_2)}"
+puts
+
+# Example 5: Validating with empty string
+puts '5. Validating with empty string:'
+puts "   Boleto: ''"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.is_valid('')}"
+puts
+
+# Example 6: Validating with insufficient length
+puts '6. Validating with insufficient length:'
+short_boleto = '000111'
+puts "   Boleto: #{short_boleto}"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.is_valid(short_boleto)}"
+puts
+
+# Example 7: Using the alias method 'valid?'
+puts '7. Using the alias method `valid?`:'
+puts "   Boleto: #{valid_boleto}"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.valid?(valid_boleto)}"
+puts
+
+# Example 8: Validating boleto with various formatting
+puts '8. Validating boleto with dots in different positions:'
+formatted_with_dots = '00190.00009 01149.718601 68524.522114 6 75860000102656'
+puts "   Boleto: #{formatted_with_dots}"
+puts "   Is valid? #{BrazilianUtils::BoletoUtils.is_valid(formatted_with_dots)}"
+puts
+
+puts '=' * 80
+puts 'What is a Boleto Digitable Line?'
+puts '=' * 80
+puts
+puts 'A boleto digitable line (linha digitável) is a 47-digit number that represents'
+puts 'a Brazilian payment slip (boleto bancário). It contains:'
+puts '  - Bank code'
+puts '  - Currency code'
+puts '  - Check digits (mod10 for partials, mod11 for general validation)'
+puts '  - Amount and due date information'
+puts
+puts 'The digitable line is typically formatted with spaces and dots for readability,'
+puts 'but the validation works with the numeric-only version.'
+puts '=' * 80