Add methods to format, match and check verifying digits (#10)

* Add raw Format

* format as argument require to be in the list

* Formater.format requires a string as document number

* Add documentation for raw method

* Add matcher to match with CPF and CNPJ formats

* Add verification digit checker for CPF generator

* Add verification digit checker for CNPJ generator

* Rubocop issue: add empty line and avoit long line

* Add Changelog

* Add readme to help using

* Test just against ruby 3 versions

* Revert "Test just against ruby 3 versions"

This reverts commit 8b22575.

* Add Newer ruby versions

* Remove syntax using that works only in ruby 3.1

Author: bvicenzo

.travis.yml

@@ -6,5 +6,7 @@ rvm:
   - 2.6.6
   - 2.5.8
   - 2.4.10
+  - 3.0.3
+  - 3.1.1
 
 before_install: gem install bundler -v 2.1.4

CHANGELOG.md

@@ -1,16 +1,26 @@
 
 # Changelog
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- Add Formatter.raw method to make a document number to have only numbers;
+- Add Matcher.match? to check if a CPF or CNPJ has a valid format;
+- Add CPFGenerator.valid_verification_digit? to check if a CPF has a valid verification digit
+- Add CNPJGenerator.valid_verification_digit? to check if a CNPJ has a valid verification digit
+
 ## [1.0.0] - 2020-22-10
+
 ### Added
-  - CPF and CNPJ number formatter
-  - CPF number generator
-  - CNPJ number generator
-  - RSpec CPF matcher helpers
-  - RSpec CNPJ matcher helpers
+
+- CPF and CNPJ number formatter;
+- CPF number generator;
+- CNPJ number generator;
+- RSpec CPF matcher helpers;
+- RSpec CNPJ matcher helpers;

README.md

@@ -40,6 +40,19 @@ BraDocuments::CPFGenerator.generate(person_number: '123123123', formatted: true)
 #=> "123.123.123-87"
 ```
 
+### CPF digit verification
+
+```rb
+BraDocuments::CPFGenerator.valid_verification_digit?(document: '86027265892')
+#=> true
+
+BraDocuments::CPFGenerator.valid_verification_digit?(document: '123.123.123-87')
+#=> true
+
+BraDocuments::CPFGenerator.valid_verification_digit?(document: '123.123.123-88')
+#=> false
+```
+
 ### CNPJ Generation
 
 ```rb
@@ -62,6 +75,19 @@ BraDocuments::CNPJGenerator.generate(company_number: '53855973', matrix_subsidia
 #=> "53.855.973/0001-79"
 ```
 
+### CNPJ digit verification
+
+```rb
+BraDocuments::CNPJGenerator.valid_verification_digit?(document: '62885807804809')
+#=> true
+
+BraDocuments::CNPJGenerator.valid_verification_digit?(document: '53.855.973/0001-79')
+#=> true
+
+BraDocuments::CNPJGenerator.valid_verification_digit?(document: '53855973000177')
+#=> false
+```
+
 ### Formatting
 
 ```rb
@@ -70,6 +96,25 @@ BraDocuments::Formatter.format('86027265892', as: :cpf)
 
 BraDocuments::Formatter.format('53855973879456', as: :cnpj)
 #=> "53.855.973/8794-56"
+
+BraDocuments::Formatter.raw('53.855.973/8794-56')
+#=> "53855973879456"
+```
+
+### Matching
+
+```rb
+BraDocuments::Matcher.match?('11111111111', kind: :cpf, mode: :raw)
+#=> true
+
+BraDocuments::Matcher.match?('11111111111', kind: :cpf, mode: :formatted)
+#=> false
+
+BraDocuments::Matcher.match?('11111111111', kind: :cnpj, mode: :raw)
+#=> false
+
+BraDocuments::Matcher.match?('90.978.812/0001-07', kind: :cnpj, mode: :formatted)
+#=> true
 ```
 
 ### Tests Matching

lib/bra_documents.rb

@@ -4,8 +4,8 @@
 require 'bra_documents/cpf_generator'
 require 'bra_documents/cnpj_generator'
 require 'bra_documents/formatter'
-require "bra_documents/version"
-
+require 'bra_documents/matcher'
+require 'bra_documents/version'
 
 module BraDocuments
 end

lib/bra_documents/cnpj_generator.rb

@@ -12,12 +12,27 @@ class << self
       # Generates a random CNPJ document number or add verifying digits to one if it's given.
       # It can return only numbers or formatted with mask
       #
-      # BraDocuments::CNPJGenerator.generate # => "62885807804809"
-      # BraDocuments::CNPJGenerator.generate(formatted: true) # => "53.855.973/0664-39"
-      # BraDocuments::CNPJGenerator.generate(company_number: '53855973') # => "53855973879456"
-      # BraDocuments::CNPJGenerator.generate(company_number: '53855973', formatted: true) # => "53.855.973/8189-02"
-      # BraDocuments::CNPJGenerator.generate(company_number: '53855973', matrix_subsidiary_number: '0001') # => "53855973000179"
-      # BraDocuments::CNPJGenerator.generate(company_number: '53855973', matrix_subsidiary_number: '0001', formatted: true) # => "53.855.973/0001-79"
+      #  BraDocuments::CNPJGenerator.generate
+      #  # => "62885807804809"
+      #
+      #  BraDocuments::CNPJGenerator.generate(formatted: true)
+      #  # => "53.855.973/0664-39"
+      #
+      #  BraDocuments::CNPJGenerator.generate(company_number: '53855973')
+      #  # => "53855973879456"
+      #
+      #  BraDocuments::CNPJGenerator.generate(company_number: '53855973', formatted: true)
+      #  # => "53.855.973/8189-02"
+      #
+      #  BraDocuments::CNPJGenerator.generate(company_number: '53855973', matrix_subsidiary_number: '0001')
+      #  # => "53855973000179"
+      #
+      #  BraDocuments::CNPJGenerator.generate(
+      #    company_number: '53855973',
+      #    matrix_subsidiary_number: '0001',
+      #    formatted: true
+      #    )
+      #  # => "53.855.973/0001-79"
       def generate(company_number: nil, matrix_subsidiary_number: nil, formatted: false)
         company_number = number_for('Company', COMPANY_NUMBER_SIZE, company_number)
         matrix_subsidiary_number = number_for('Matrix or subsidiary', MATRIX_SUBSIDIARY_SIZE, matrix_subsidiary_number)
@@ -28,6 +43,29 @@ def generate(company_number: nil, matrix_subsidiary_number: nil, formatted: fals
         formatted ?  Formatter.format(full_number, as: :cnpj) : full_number
       end
 
+      # Returns if a CPF has a valid verification digit.
+      #
+      #   BraDocuments::CPFGenerator.valid_verification_digit?(document: '11.111.111/1111-11')
+      #   # => false
+      #
+      #   BraDocuments::CPFGenerator.valid_verification_digit?(document: '20.163.606/0001-55')
+      #   # => true
+      #
+      #   BraDocuments::CPFGenerator.valid_verification_digit?(document: '29432530000190')
+      #   # => true
+      def valid_verification_digit?(document:)
+        raw_document = Formatter.raw(document)
+        return false if raw_document.chars.uniq.size == 1
+
+        company_number = raw_document.slice(0..(COMPANY_NUMBER_SIZE - 1))
+        matrix_subsidiary_number = raw_document
+          .slice(COMPANY_NUMBER_SIZE..(COMPANY_NUMBER_SIZE + MATRIX_SUBSIDIARY_SIZE - 1))
+        verified_digit = raw_document.slice(-2..-1)
+
+        generate(company_number: company_number, matrix_subsidiary_number: matrix_subsidiary_number)
+          .end_with?(verified_digit)
+      end
+
       private
 
       def verification_digit_multiplicators_for(numbers)

lib/bra_documents/cpf_generator.rb

@@ -11,15 +11,42 @@ class << self
       # Generates a random CPF document number or add verifying digits to one if it's given.
       # It can return only numbers or formatted with mask
       #
-      # BraDocuments::CPFGenerator.generate # => "86027265892"
-      # BraDocuments::CPFGenerator.generate(formatted: true) # => "038.857.544-10"
-      # BraDocuments::CPFGenerator.generate(person_number: '123123123') # => "12312312387"
-      # BraDocuments::CPFGenerator.generate(person_number: '123123123', formatted: true) # => "123.123.123-87"
+      #   BraDocuments::CPFGenerator.generate
+      #   # => "86027265892"
+      #
+      #   BraDocuments::CPFGenerator.generate(formatted: true)
+      #   # => "038.857.544-10"
+      #
+      #   BraDocuments::CPFGenerator.generate(person_number: '123123123')
+      #   # => "12312312387"
+      #
+      #   BraDocuments::CPFGenerator.generate(person_number: '123123123', formatted: true)
+      #   # => "123.123.123-87"
       def generate(person_number: nil, formatted: false)
         numbers = number_for('Person', PERSON_NUMBER_SIZE, person_number)
         full_number = complete!(numbers)
 
-        formatted ?  Formatter.format(full_number, as: :cpf) : full_number
+        formatted ? Formatter.format(full_number, as: :cpf) : full_number
+      end
+
+      # Returns if a CPF has a valid verification digit.
+      #
+      #   BraDocuments::CPFGenerator.valid_verification_digit?(document: '111.111.111-11')
+      #   # => false
+      #
+      #   BraDocuments::CPFGenerator.valid_verification_digit?(document: '123.456.700-88')
+      #   # => true
+      #
+      #   BraDocuments::CPFGenerator.valid_verification_digit?(document: '12345670088')
+      #   # => true
+      def valid_verification_digit?(document:)
+        raw_document = Formatter.raw(document)
+        return false if raw_document.chars.uniq.size == 1
+
+        person_number = raw_document.slice(0..(PERSON_NUMBER_SIZE - 1))
+        verified_digit = raw_document.slice(PERSON_NUMBER_SIZE..(raw_document.size - 1))
+
+        generate(person_number: person_number).end_with?(verified_digit)
       end
 
       private

lib/bra_documents/formatter.rb

@@ -2,20 +2,47 @@
 
 module BraDocuments
   class Formatter
+    NOT_NUMBER = /\D/
     FORMATS = {
       cpf: { pattern: /\A(\d{3})(\d{3})(\d{3})(\d{2})\z/, mask: '%s.%s.%s-%s' },
-      cnpj: { pattern: /\A(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})\z/, mask: '%s.%s.%s/%s-%s'}
+      cnpj: { pattern: /\A(\d{2})(\d{3})(\d{3})(\d{4})(\d{2})\z/, mask: '%s.%s.%s/%s-%s' }
     }.freeze
 
-    # Formats a only numbers CPF or CNPJ in their own mask
-    #
-    # BraDocuments::Formatter.format('86027265892', as: :cpf) # => "860.272.658-92"
-    # BraDocuments::Formatter.format('53855973879456', as: :cnpj) # => "53.855.973/8794-56"
-    def self.format(number, as:)
-      format_data = FORMATS[as]
+    class << self
+      # Formats a only numbers CPF or CNPJ in their own mask
+      #
+      # BraDocuments::Formatter.format('86027265892', as: :cpf) # => "860.272.658-92"
+      # BraDocuments::Formatter.format('53855973879456', as: :cnpj) # => "53.855.973/8794-56"
+      def format(number, as:)
+        raise ArgumentError, "\"#{number.inspect}\" must be a String." unless number.is_a?(String)
+        unless known_format?(as)
+          raise ArgumentError, "Format \"#{as}\" is not know. Known formats: #{known_formats.join(', ')}."
+        end
 
-      Kernel.format(format_data[:mask], *format_data[:pattern].match(number).captures)
+        format_data = FORMATS[as]
+
+        Kernel.format(format_data[:mask], *format_data[:pattern].match(number).captures)
+      end
+
+      # Formats removing all not number caracters from string.
+      #
+      # BraDocuments::Formatter.raw('860.272.658-9') # => "286027265892"
+      # BraDocuments::Formatter.format('53.855.973/8794-56') # => "53855973879456"
+      def raw(number)
+        raise ArgumentError, "\"#{number.inspect}\" must be a String." unless number.is_a?(String)
+
+        number.gsub(NOT_NUMBER, '')
+      end
+
+      private
+
+      def known_formats
+        @known_formats ||= FORMATS.keys
+      end
+
+      def known_format?(format)
+        known_formats.include?(format)
+      end
     end
   end
 end
-

lib/bra_documents/matcher.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module BraDocuments
+  class Matcher
+    FORMATS = {
+      cpf: { formatted: /\A(\d{3}\.){2}\d{3}-\d{2}\z/, raw: /\A\d{11}\z/ },
+      cnpj: { formatted: /\A\d{2}.\d{3}\.\d{3}\/\d{4}-\d{2}\z/, raw: /\A\d{14}\z/ }
+    }.freeze
+
+    class << self
+      # Macthes with Brazilian CPF and CNPJ documents.
+      #
+      #   BraDocuments::Matcher.match?('11111111111', kind: :cpf, mode: :raw)
+      #   # => true
+      #
+      #   BraDocuments::Matcher.match?('11111111111', kind: :cpf, mode: :formatted)
+      #   # => false
+      #
+      #   BraDocuments::Matcher.match?('11111111111', kind: :cnpj, mode: :raw)
+      #   # => false
+      #
+      #   BraDocuments::Matcher.match?('90.978.812/0001-07', kind: :cnpj, mode: :formatted)
+      #   # => true
+      def match?(number, kind:, mode:)
+        raise ArgumentError, "\"#{number.inspect}\" must be a String." unless number.is_a?(String)
+
+        unless known_format?(kind)
+          raise ArgumentError, "Unknown document kind \"#{kind.inspect}\". Known documents: #{known_formats.join(', ')}."
+        end
+
+        unless known_mode?(mode)
+          raise ArgumentError, "Unknown document format mode \"#{mode.inspect}\". Known modes: #{known_modes.join(', ')}."
+        end
+
+        formats_to_match(kind, mode).any? { |format| format.match?(number) }
+      end
+
+      private
+
+      def known_formats
+        @known_formats ||= FORMATS.keys
+      end
+
+      def known_modes
+        @known_modes ||= FORMATS[known_formats.first].keys << :any
+      end
+
+      def known_format?(format)
+        known_formats.include?(format)
+      end
+
+      def known_mode?(mode)
+        known_modes.include?(mode)
+      end
+
+      def formats_to_match(kind, mode)
+        document_formats = FORMATS[kind]
+
+        mode == :any ? document_formats.values : [document_formats[mode]]
+      end
+    end
+  end
+end

lib/bra_documents/national_register_base.rb

@@ -3,7 +3,6 @@
 module BraDocuments
   class NationalRegisterBase
     class << self
-      NOT_NUMBER_PATTERN = /\D/.freeze
       BASE = 11
 
       private
@@ -14,9 +13,12 @@ def complete!(numbers)
       end
 
       def number_for(number_description, number_size, given_value)
-        given_value = only_digits_for(given_value)
+        given_value = Formatter.raw(given_value.to_s)
         if !given_value.to_s.empty?
-          raise ArgumentError, "#{number_description} number must be a number with #{number_size} digits." unless given_value.size == number_size
+          unless given_value.size == number_size
+            raise ArgumentError, "#{number_description} number must be a number with #{number_size} digits."
+          end
+
           given_value.split('').map(&:to_i)
         else
           number_with(number_size)
@@ -27,10 +29,6 @@ def number_with(size)
         size.times.map { rand(10) }
       end
 
-      def only_digits_for(number)
-        number.to_s.gsub(NOT_NUMBER_PATTERN, '')
-      end
-
       def verification_digit_for(numbers)
         verification_digit_multiplicators = verification_digit_multiplicators_for(numbers)
         sum_and_multiplication = sum_and_multiply(numbers, verification_digit_multiplicators)
@@ -43,7 +41,8 @@ def verified_digit(sum_and_multiplication)
       end
 
       def sum_and_multiply(numbers, multiplicators)
-        multiplicators.map
+        multiplicators
+          .map
           .with_index { |multiplicator, position| numbers[position] * multiplicator }
           .sum
       end