DigitCheckSum

Hi there, I'm glad you're looking in this gem! The aim of this gem is to allow any kind of document to be validated e generated through calculation of Check Digit/Digit Checksum.

What this mean? This mean that you can validate and generate fake numbers of any kind of documents such: Passport numbers, Federal ID number, Books ISBN, or even create your own document number, check examples/ for more details. One of the greatest abilitys of this library is allowing to check digit checksum of digits in ANY POSITION of the document, not only for the last digits.

Tip: Check examples/h4ck.rb to see h4ck document specification, this is a sample document who can be manipulated using this library!

Installation

Add this line to your application's Gemfile:

gem 'digit_checksum', '~> 0.2.3'

And then execute:

$ bundle

Or install it yourself as:

$ gem install digit_checksum

Usage

This gem by yourself don't do anything unless you create a class that inherit from DigitChecksum::BaseDocument class, but when properly inherited and configured, believe me, you gain awesomeness!

Don't you believe me? See for yourself an example:

require 'digit_checksum'

class CNPJ < DigitChecksum::BaseDocument
  set_verify_digits_weights first:  %w(5 4 3 2 9 8 7 6 5 4 3 2),
                            second: %w(6 5 4 3 2 9 8 7 6 5 4 3 2)

  # MOD 11
  set_division_modulo 11

  # remove any non digit from document number
  set_clear_number_regexp %r{[^(\d+)]}

  # match format such as: 99.999.999/9999-99 | 99-999-999/9999-99 | 99999999/999999 | 99999999999999
  set_format_regexp %r{(\d{2})[-.]?(\d{3})[-.]?(\d{3})[\/]?(\d{4})[-.]?(\d{2})}

  set_pretty_format_mask %(%s.%s.%s/%s-%s)

  # numbers sampled to generate new document numbers
  set_generator_numbers (0..9).to_a
end

The example below it's intent to validated brazilian CNPJ documents, equivalent to Corporate Taxpayer Registry Number, so this can be used to:

Generate fake document numbers

CNPJ.generate # "79.552.921/0786-55"

# without pretty formating
CNPJ.generate(false)  # 85215313606778

# You can generate only random root numbers
root_numbers = CNPJ.generate_root_numbers
# => [3, 8, 9, 3, 2, 5, 9, 5, 0, 2, 6, 6]

CNPJ.calculate_verify_digits(root_numbers) # [6,7]

# To insert the verify digits in the CORRECT positions
# Remember: The correct position MAY NOT be the last positions
# So use `append_verify_digits` to handle this

CNPJ.pretty(CNPJ.append_verify_digits!(root_numbers))
=> "38.932.595/0266-67"

Calculate check digits

# valid format
CNPJ.calculate_verify_digits("123.456.78/0001") # [9,5]

# invalid format
CNPJ.calculate_verify_digits("123.456.78/00001") # []

CNPJ.pretty(CNPJ.append_verify_digits!("12.345.678/0001")) # "12.345.678/0001-95

document = "123.456.78/0001-95"
CNPJ.remove_verify_digits!(document) => # [9,5]
document # => 123456780001

CNPJ.pretty(CNPJ.append_verify_digits!(document)) # => "12.345.678/0001-95"

Validate documents numbers

# convenience methods to check if document is valid

# invalid format
CNPJ.valid?("123.456.78/0001") # => false
CNPJ.invalid?("123.456.78/0001") # => true

# valid format
CNPJ.valid?("123.456.78/0001-95") # => true
CNPJ.valid?(12345678000195) # => true

Normalize and format documents number

# Get a array representation of document number
CNPJ.normalize("123.456.78/0001-95")
# => [1, 2, 3, 4, 5, 6, 7, 8, 0, 0, 0, 1, 9, 5]

# also aliased as CNPJ.pretty_formatted(number) or CNPJ.formatted(number)
CNPJ.pretty("12345678000195") # "123.456.78/0001-95"

# also aliased as CNPJ.clear_number(number)
CNPJ.strip("123.456.78/0001-95") # => "12345678000195"

See examples/for more detailed samples.

Custom verify digits positions

In most(but not necessarily all) documents formats the check digits positions are the last characters, but this library also allow you to calculate check digits in any position in the middle of the document number, see an example:

class MyDocument < DigitChecksum::BaseDocument

  set_division_modulo 11

  set_clear_number_regexp %r{[^(\d+)]}

  set_root_digits_count 10

  set_verify_digits_positions [8, 11]

  set_verify_digits_weights first: %w(1 3 4 5 6 7 8 10),
                            last:  %w(3 2 10 9 8 7 6 5 4 3 2)

  set_format_regexp %r{(\d{3})[-.]?(\d{3})[-.]?(\d{3})[-.]?(\d{3})}

  set_pretty_format_mask %(%s.%s.%s.%s)

  set_generator_numbers (0..9).to_a
end


MyDocument.get_verify_digits_positions # [8, 11]

# document number without check digits
MyDocument.calculate_verify_digits("110.042.49.11") # => [1, 3]

document = MyDocument.append_verify_digits!("110.042.49.11")
# => "110042491113"

MyDocument.pretty(document) # => "110.042.491.113"

MyDocument.remove_verify_digits!(document) # => [1, 3]

document # => "1100424911"
document = MyDocument.append_verify_digits!(document)

# => "110042491113"
MyDocument.pretty(document) # => "110.042.491.113"

# document number with check digits in the right positions(8, 11)
MyDocument.valid?("110.042.491.113") # => true

# document number with wrong check digits in the right positions
MyDocument.valid?("110.042.492.113") # => false

MyDocument.pretty(MyDocument.append_verify_digits!("110.042.49.11"))
# => "110.042.491.113"

doc = MyDocument.generate # => "286.670.374.780"

MyDocument.valid?(doc) # =: true

PORO - Plain Old Ruby Objects API

All API demonstrated in this documentation (mostly class methods call) are simple instance methods delegations to a Ruby object instance, you can work directly with objects in this way:

object = CNPJ.new("53.091.177/2847-09")

object.valid? # true

# Try to get verify digits without calculating
# Just search in the right positions in number
object.current_verify_digits # [0, 9]

# Permanently remove verify digits from number
object.remove_verify_digits! # [0, 9]

# Try to get verify digits without calculating
object.current_verify_digits # []

object.number # object.to_s => "530911772847"

object.valid? # false

# Just calculate the verify digits, dont append to number
object.calculate_verify_digits # [0, 9]

# Use the `calculate_verify_digits` methods and append the digits in the RIGHT positions
object.append_verify_digits! # "53091177284709"

object.pretty # => "53.091.177/2847-09"

object.normalize
# => [5, 3, 0, 9, 1, 1, 7, 7, 2, 8, 4, 7, 0, 9]

object.strip # "53091177284709"

object.size # 14

object.root_digits_count # 12

object.verify_digits_count # 2

# root_digits_count + verify_digits_count
object.full_size # 14

object.verify_digits_positions # [12, 13]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fidelisrafael/digit_checksum. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.