dialing_sorcerer 1.0.1-x86_64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f117fe11c90ff4dd3e2b8ac00e7bf80ecaffa84255009827730f16ffc19deb17
+  data.tar.gz: 77099ace1146cdd9c1bdbababf7bc10e64d50604efaed8df9d9d37742605de8c
+SHA512:
+  metadata.gz: 28b0a188646c9058f95adecefea4b770b07899eef65e9fa4263588b5849cf2e12ebbb2aa813d888ecdf32d42ac38a0553bc788ba7efa54c8889775daaf6c553c
+  data.tar.gz: 0b9383cb8d809385922fc6efc909a9413b7677c776d7cff1732c1bb946dcbf3f82a7f35ad9b67cf0c8e87e9cef29b2dbd65b2411f56fcfd9b230a02651bd3208

data/.rubocop_todo.yml

@@ -0,0 +1,65 @@
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 350
+
+Metrics/ModuleLength:
+  Max: 400
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 15
+
+#---------------------------------------------------------
+
+# Allow adding Gems to Gemfile without descriptive comment
+Bundler/GemComment:
+  Enabled: false
+
+# Ignore missing Copyright notice
+Style/Copyright:
+  Enabled: false
+
+# Do not complain about missing else clauses
+Style/MissingElse:
+  Enabled: false
+
+# Allow non symbol hash keys
+Style/StringHashKeys:
+  Enabled: false
+
+# False positive for save_screenshot method of appium used in Yealink driver
+Lint/Debugger:
+  Enabled: false
+
+# Disabled to allow rubocop disable directives in source code
+Style/DisableCopsWithinSourceCodeDirective:
+  Enabled: false
+
+# Disabled to allow passing an option hash instead of keyword parameters
+Style/OptionHash:
+  Enabled: false
+
+# Disabled to allow OpenStruct conversion of hashes
+Style/OpenStructUse:
+  Enabled: false
+
+# Disabled to allow formated printout of SIP messagesS
+Style/RedundantFormat:
+  Enabled: false
+
+# Disabled to allow symbols with numbers for KEYCODE's
+Naming/VariableNumber:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Style/EmptyStringInsideInterpolation:
+  Enabled: false

data/.yardopts

@@ -0,0 +1,6 @@
+--type-name-tag generic:Generic
+--default-return void
+--markup markdown
+--markup-provider redcarpet
+--exclude /rbi
+--exclude /sig

data/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.1] - 2025-09-25
+
+### 🚀 Features
+
+- 05063d0 - Added rspec matcher for string input [@armando]
+
+
+### 🌀 Miscellaneous Tasks
+
+- 9222b90 - Added changelog [@armando]
+
+- c7b95e6 - Bump version 1.0.1 [@armando]
+
+
+## [1.0.0] - 2025-09-25
+
+### 🚀 Features
+
+- 0da4e74 - Added initial setup [@armando]
+
+- *(release)* ac150b9 - Pre release preparation [@armando]
+
+
+### 🐛 Bug Fixes
+
+- *(doc)* 044cf53 - Fixed doc generation with addition of git [@armando]
+
+- 7a0b720 - Project url [@armando]
+
+
+### 📝 Documentation
+
+- 61ef7ab - Added yard docs as gitlab pac [@armando]
+
+- dc65f38 - Improved docs [@armando]
+
+- 1018107 - Added link to documentation [@armando]
+
+- 9e82246 - Url docs documentation [@armando]
+
+
+### ⚙️ Testing
+
+- 63d05ef - Added benchmarks for parsing [@armando]
+
+
+### 🌀 Miscellaneous Tasks
+
+- *(rspec)* 966fe95 - Added rspec to pipeline [@armando]
+
+- *(testing)* 2e340fa - Added additional test coverage [@armando]
+
+- cac73ba - Cleared uneeded file [@armando]
+
+- 0cb5d51 - Improved error type to use internal only [@armando]
+
+
+<!-- generated by git-cliff -->

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 armando
+
+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,255 @@
+# DialSorcerer
+
+A Ruby gem for parsing and formatting phone numbers with international support, powered by Rust.
+
+DialSorcerer provides comprehensive phone number parsing, validation, and formatting capabilities. It supports international phone number formats, validation of phone number types (mobile, fixed-line, VOIP, etc.), and conversion between different formatting standards including E.164, national, international, and RFC 3966 formats.
+
+## Features
+
+- ✨ **International Support**: Parse and format phone numbers from any country
+- 🔍 **Validation**: Validate phone number types (mobile, fixed-line, VOIP, etc.)
+- 📱 **Multiple Formats**: Support for E.164, national, international, and RFC 3966 formats
+- 🚀 **High Performance**: Rust-powered backend for fast processing
+- 🧪 **RSpec Matchers**: Convenient matchers for testing phone number functionality
+- 🛡️ **Type Safety**: Comprehensive error handling and type classification
+- 🌍 **Carrier Information**: Get carrier details when available
+- 📖 **Documentation**: [https://avengers.pages.its-telekom.eu/dial-sorcerer](https://avengers.pages.its-telekom.eu/dial-sorcerer)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dialing_sorcerer'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install dialing_sorcerer
+```
+
+## Usage
+
+### Basic Parsing
+
+```ruby
+require 'dialing_sorcerer'
+
+# Parse an international number
+phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+puts phone.to_e164        # => "+493012345678"
+puts phone.to_national    # => "030 12345678"
+puts phone.to_international # => "+49 30 12345678"
+puts phone.country        # => "DE"
+puts phone.type          # => "FixedLine"
+
+# Parse a national number with country code
+phone = DialSorcerer::PhoneNumber.parse("030 12345678", "DE")
+puts phone.country_code  # => 49
+```
+
+### Safe Parsing
+
+Use `try_parse` for error handling without exceptions:
+
+```ruby
+result = DialSorcerer::PhoneNumber.try_parse("invalid number")
+
+if result.success?
+  puts result.phone_number.to_e164
+else
+  puts "Error: #{result.error} (#{result.error_type})"
+end
+```
+
+### Phone Number Types
+
+DialSorcerer can identify various phone number types:
+
+```ruby
+mobile = DialSorcerer::PhoneNumber.parse("+49 151 12345678")
+puts mobile.type  # => "Mobile"
+
+landline = DialSorcerer::PhoneNumber.parse("+49 30 12345678")  
+puts landline.type  # => "FixedLine"
+
+voip = DialSorcerer::PhoneNumber.parse("+49 32 12345678")
+puts voip.type  # => "Voip"
+```
+
+### Formatting Options
+
+```ruby
+phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+
+# Different output formats
+puts phone.to_e164                    # => "+493012345678"
+puts phone.to_e164(zero_leading: true) # => "00493012345678"
+puts phone.to_national               # => "030 12345678"
+puts phone.to_international          # => "+49 30 12345678"
+puts phone.to_rfc3966               # => "tel:+49-30-12345678"
+puts phone.national_number          # => "3012345678"
+```
+
+### Phone Number Comparison
+
+```ruby
+phone1 = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+phone2 = DialSorcerer::PhoneNumber.parse("030 12345678", "DE")
+
+# Strict equality
+puts phone1 == phone2  # => true
+
+# Flexible matching (matches various formats)
+puts phone1.equal?("+493012345678")  # => true
+puts phone1.equal?("030 12345678")   # => true
+puts phone1.equal?("+49 30 12345678") # => true
+```
+
+### Error Handling
+
+```ruby
+begin
+  phone = DialSorcerer::PhoneNumber.parse("123")
+rescue DialSorcerer::ParseError => e
+  puts "Failed to parse: #{e.message}"
+end
+
+# Or use safe parsing
+result = DialSorcerer::PhoneNumber.try_parse("123")
+puts result.error_type if !result.success?  # => :too_short, :too_long, :invalid_country, or :invalid_format
+```
+
+## Testing with RSpec
+
+DialSorcerer includes convenient RSpec matchers:
+
+```ruby
+require 'dialing_sorcerer/rspec_matchers'
+
+RSpec.describe "Phone number validation" do
+  include DialSorcerer::PhoneNumberMatchers
+
+  it "validates mobile numbers" do
+    phone = DialSorcerer::PhoneNumber.parse("+49 151 12345678")
+    expect(phone).to be_mobile
+  end
+
+  it "validates VOIP numbers" do
+    voip = DialSorcerer::PhoneNumber.parse("+49 32 12345678")
+    expect(voip).to be_voip
+  end
+
+  it "matches MSISDN strings" do
+    phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    expect(phone).to match_msisdn("+493012345678")
+    expect(phone).to match_msisdn("030 12345678")
+  end
+end
+```
+
+## API Reference
+
+### DialSorcerer::PhoneNumber
+
+#### Class Methods
+
+- `parse(number, country = nil, default_country: 'DE')` - Parse a phone number, raises ParseError on failure
+- `try_parse(number, country = nil, default_country: nil)` - Safe parsing, returns ParseResult object
+
+#### Instance Methods
+
+- `valid?` - Check if phone number is valid
+- `to_e164(zero_leading: false)` - Format as E.164
+- `to_national` - Format as national number  
+- `to_international` - Format as international number
+- `to_rfc3966` - Format according to RFC 3966
+- `national_number` - Get national number without country code
+- `country_code` - Get numeric country calling code
+- `country` - Get ISO country code (2-letter)
+- `type` - Get phone number type
+- `carrier` - Get carrier name (when available)
+- `==(other)` - Strict equality comparison
+- `equal?(other)` - Flexible format matching
+
+### Phone Number Types
+
+Supported phone number types:
+- `FixedLine` - Traditional landline numbers
+- `Mobile` - Mobile/cellular numbers
+- `FixedLineOrMobile` - Numbers that could be either
+- `TollFree` - Toll-free numbers
+- `PremiumRate` - Premium rate numbers
+- `SharedCost` - Shared cost numbers
+- `PersonalNumber` - Personal numbers
+- `Voip` - Voice over IP numbers
+- `Pager` - Pager numbers
+- `Uan` - Universal Access Numbers
+- `Emergency` - Emergency numbers
+- `Voicemail` - Voicemail access numbers
+- `ShortCode` - Short code numbers
+- `StandardRate` - Standard rate numbers
+- `Carrier` - Carrier-specific numbers
+- `NoInternational` - Numbers not available internationally
+- `Unknown` - Unknown type
+
+## Development
+
+Run `rake spec` to run the tests. You can also run `bundle exec irb` for an interactive prompt that will allow you to experiment.
+
+### Requirements
+
+- Ruby >= 3.4.0
+- RubyGems >= 3.3.11
+- Rust toolchain (for building the native extension)
+
+### Building
+
+The gem includes a Rust extension that provides the core phone number parsing functionality. The extension is built automatically during installation using `rb_sys`.
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake spec
+
+# Run specific test file
+bundle exec rspec spec/phone_number_spec.rb
+```
+
+### Linting
+
+```bash
+# Check code style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -A
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitLab at https://gitlab01.its-telekom.eu/avengers/dial_sorcerer.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Make your changes and add tests
+4. Ensure all tests pass and code follows style guidelines
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin feature/my-new-feature`)
+7. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and changes.

data/Rakefile

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rb_sys/extensiontask'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.pattern = Dir.glob('spec/**/*_spec.rb')
+  t.rspec_opts = '--format RspecSonarqubeFormatter --out test-report.xml --format documentation'
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task build: :compile
+
+GEMSPEC = Gem::Specification.load('dialing_sorcerer.gemspec')
+exttask =
+  RbSys::ExtensionTask.new('dialing_sorcerer', GEMSPEC) do |ext|
+    ext.lib_dir = 'lib/dialing_sorcerer'
+    ext.cross_compile = true
+    ext.cross_platform = %w[x64-mingw-ucrt x86_64-linux x86_64-linux-musl x86_64-darwin arm64-darwin]
+  end
+
+namespace :cargo do
+  # Define a Rake task with a description
+  desc 'Run cargo fmt to format rust code'
+  task :fmt do
+    sh 'cargo', 'fmt'
+  end
+
+  desc 'Run cargo test on rust code'
+  task :test do
+    sh 'cargo test'
+  end
+end
+
+namespace :compile do
+  exttask.cross_platform.each do |plat|
+    desc "Build native extension for #{plat} platform (cross compile)"
+
+    multitask across: plat
+    task plat do
+      sh 'rb-sys-dock', '-p', plat, '--ruby-versions', '3.4 3.5', '--build'
+    end
+  end
+end
+
+desc 'Build gem but before cross compile rust code'
+task build: :'compile:across'
+
+desc 'compile but before run spec and rubocop'
+task default: [:compile, :spec, :rubocop]

data/lib/dialing_sorcerer/phone_number.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require_relative 'dialing_sorcerer'
+
+module DialSorcerer
+
+  # Result object returned by PhoneNumber.try_parse method
+  #
+  # @example Successful parse
+  #   result = DialSorcerer::PhoneNumber.try_parse("+49 30 12345678")
+  #   if result.success?
+  #     puts result.phone_number.to_e164
+  #   end
+  #
+  # @example Failed parse
+  #   result = DialSorcerer::PhoneNumber.try_parse("invalid")
+  #   unless result.success?
+  #     puts "Error: #{result.error} (#{result.error_type})"
+  #   end
+  #
+  # @attr [Boolean] success? whether the parsing was successful
+  # @attr [PhoneNumber, nil] phone_number the parsed phone number object (nil if parsing failed)
+  # @attr [String, nil] error the error message (nil if parsing succeeded)
+  # @attr [Symbol, nil] error_type the classified error type (nil if parsing succeeded)
+  ParseResult =
+    Struct.new(:success?, :phone_number, :error, :error_type) do
+      alias_method :success?, :success?
+    end
+
+  # Represents a parsed and validated phone number with various formatting options.
+  # This class provides methods to parse, validate, and format phone numbers
+  # according to international standards.
+  #
+  # @example Basic parsing
+  #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+  #   puts phone.to_e164 # => "+493012345678"
+  #
+  # @example Parsing with country
+  #   phone = DialSorcerer::PhoneNumber.parse("030 12345678", "DE")
+  #   puts phone.country # => "DE"
+  #
+  # @example Safe parsing
+  #   result = DialSorcerer::PhoneNumber.try_parse("invalid number")
+  #   puts result.error if !result.success?
+  class PhoneNumber
+
+    # Parses a phone number string and returns a PhoneNumber object.
+    # Raises ParseError if the number is invalid.
+    #
+    # @param number [String] the phone number to parse
+    # @param country [String, nil] the country code for the number (optional)
+    # @param default_country [String] the default country code to use ("DE" by default)
+    # @return [DialSorcerer::PhoneNumber] the parsed phone number
+    # @raise [DialSorcerer::ParseError] if the number cannot be parsed
+    #
+    # @example Parse international number
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #
+    # @example Parse national number with country
+    #   phone = DialSorcerer::PhoneNumber.parse("030 12345678", "DE")
+    def self.parse(number, country = nil, default_country: 'DE')
+      country ||= default_country
+      new(DialSorcerer::Internal.parse(number, country&.upcase))
+    rescue ArgumentError => e
+      raise(DialSorcerer::ParseError, e.message)
+    end
+
+    # Attempts to parse a phone number without raising exceptions.
+    # Returns a ParseResult object that indicates success or failure.
+    #
+    # @param number [String] the phone number to parse
+    # @param country [String, nil] the country code for the number (optional)
+    # @param default_country [String, nil] the default country code to use
+    # @return [ParseResult] result object containing the phone number or error information
+    #
+    # @example Successful parsing
+    #   result = DialSorcerer::PhoneNumber.try_parse("+49 30 12345678")
+    #   puts result.phone_number.to_e164 if result.success?
+    #
+    # @example Failed parsing
+    #   result = DialSorcerer::PhoneNumber.try_parse("123")
+    #   puts result.error unless result.success?
+    def self.try_parse(number, country = nil, default_country: nil)
+      country ||= default_country
+      internal = DialSorcerer::Internal.parse(number, country&.upcase)
+      phone = new(internal)
+      DialSorcerer::ParseResult.new(true, phone, nil, nil)
+    rescue ::ArgumentError => e
+      error_type = classify_error(e.message)
+      DialSorcerer::ParseResult.new(false, nil, e.message, error_type)
+    end
+
+    # Classifies error messages into specific error types
+    # This method analyzes error messages and returns a symbol representing
+    # the type of parsing error that occurred.
+    #
+    # @param message [String] the error message to classify
+    # @return [Symbol] the classified error type (:invalid_country, :too_short, :too_long, or :invalid_format)
+    #
+    # @example Classifying country error
+    #   DialSorcerer::PhoneNumber.classify_error("Invalid country code") # => :invalid_country
+    #
+    # @example Classifying length errors
+    #   DialSorcerer::PhoneNumber.classify_error("Number too short") # => :too_short
+    #   DialSorcerer::PhoneNumber.classify_error("Number too long") # => :too_long
+    #
+    # @example Default classification
+    #   DialSorcerer::PhoneNumber.classify_error("Invalid format") # => :invalid_format
+    #
+    # @api private
+    def self.classify_error(message)
+      case message
+      when /invalid country/i then :invalid_country
+      when /too short/i then :too_short
+      when /too long/i then :too_long
+      else :invalid_format
+      end
+    end
+
+    # Creates a new DialSorcerer::PhoneNumber instance with internal representation
+    # @param internal [DialSorcerer::Internal] the internal phone number representation
+    # @api private
+    def initialize(internal)
+      @internal = internal
+    end
+
+    # Checks if the phone number is valid
+    #
+    # @return [Boolean] true if the phone number is valid
+    # @example
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.valid? # => true
+    def valid?
+      @internal.valid?
+    end
+
+    # Formats the phone number in E.164 format
+    # E.164 formatting has no spaces or decorations, just the country code and number.
+    #
+    # @param zero_leading [Boolean] whether to use "00" instead of "+" prefix
+    # @return [String] the phone number in E.164 format
+    #
+    # @example Standard E.164 format
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.to_e164 # => "+493012345678"
+    #
+    # @example With zero leading
+    #   phone.to_e164(zero_leading: true) # => "00493012345678"
+    def to_e164(zero_leading: false)
+      value = @internal.to_e164
+      zero_leading ? value.gsub('+', '00') : value
+    end
+
+    # Formats the phone number in national format
+    # National formatting has no country code and uses country-dependent formatting.
+    #
+    # @return [String] the phone number in national format
+    # @example
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.to_national # => "030 12345678"
+    def to_national
+      @internal.to_national
+    end
+
+    # Formats the phone number in international format
+    # International formatting contains country code and uses country-dependent formatting.
+    #
+    # @return [String] the phone number in international format
+    # @example
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.to_international # => "+49 30 12345678"
+    def to_international
+      @internal.to_international
+    end
+
+    # Returns the national number without country code
+    #
+    # @return [String] the national number
+    # @example
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.national_number # => "3012345678"
+    def national_number
+      @internal.national_number
+    end
+
+    # Formats the phone number according to RFC 3966
+    #
+    # @return [String] the phone number in RFC 3966 format
+    # @example
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.to_rfc3966 # => "tel:+49-30-12345678"
+    def to_rfc3966
+      @internal.to_rfc3966
+    end
+
+    # Returns the country calling code
+    #
+    # @return [Integer] the country calling code
+    # @example
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.country_code # => 49
+    def country_code
+      @internal.country_code
+    end
+
+    # Returns the ISO country code
+    #
+    # @return [String] the two-letter ISO country code
+    # @example
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.country # => "DE"
+    def country
+      @internal.country
+    end
+
+    # Returns the E.164 representation for debugging
+    #
+    # @return [String] the phone number in E.164 format
+    def inspect
+      to_e164
+    end
+
+    # Returns the E.164 representation as string
+    #
+    # @return [String] the phone number in E.164 format
+    def to_s
+      to_e164
+    end
+
+    # Returns the type of the phone number
+    # Types include: FixedLine, Mobile, FixedLineOrMobile, TollFree, PremiumRate,
+    # SharedCost, PersonalNumber, Voip, Pager, Uan, Emergency, Voicemail,
+    # ShortCode, StandardRate, Carrier, NoInternational, Unknown
+    #
+    # @return [String] the phone number type
+    #
+    # @example Getting phone number type
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.type # => "FixedLine"
+    #
+    # @example Mobile number
+    #   mobile = DialSorcerer::PhoneNumber.parse("+49 170 1234567")
+    #   mobile.type # => "Mobile"
+    def type
+      @internal.number_type
+    end
+
+    # Compares two phone numbers for equality based on their national number and country
+    # Two phone numbers are considered equal if they have the same national number
+    # and the same country code.
+    #
+    # @param other [PhoneNumber] the phone number to compare with
+    # @return [Boolean] true if the phone numbers are equal, false otherwise
+    #
+    # @example Equal phone numbers
+    #   phone1 = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone2 = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone1 == phone2 # => true
+    #
+    # @example Different phone numbers
+    #   phone1 = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone2 = DialSorcerer::PhoneNumber.parse("+49 30 87654321")
+    #   phone1 == phone2 # => false
+    #
+    # @example Different countries
+    #   phone1 = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone2 = DialSorcerer::PhoneNumber.parse("+43 30 12345678")
+    #   phone1 == phone2 # => false
+    def ==(other)
+      return false unless other.is_a?(self.class)
+
+      national_number == other.national_number && country == other.country
+    end
+
+    # Checks if this phone number matches the given input in any supported format
+    # This method is more flexible than == as it compares against various formatted
+    # representations of the phone number, ignoring whitespace differences.
+    #
+    # @param other [PhoneNumber, String, #to_s] the phone number or string to compare with
+    # @return [Boolean] true if the input matches any format of this phone number
+    #
+    # @example Matching E.164 format
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.equal?("+493012345678") # => true
+    #
+    # @example Matching national format
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.equal?("030 12345678") # => true
+    #
+    # @example Matching with spaces
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.equal?("+49 30 12345678") # => true
+    #
+    # @example Non-matching number
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.equal?("+49 30 87654321") # => false
+    def equal?(other)
+      return false unless other.is_a?(self.class) || other.respond_to?(:to_s)
+
+      other = other.to_s unless other.is_a?(self.class)
+      [to_rfc3966, national_number, to_international, to_national, to_e164, to_e164(zero_leading: true)].any? do |v|
+        v.gsub(/\s/, '') == other.to_s.gsub(/\s/, '')
+      end
+    end
+
+    # Returns the carrier name for the phone number, if available
+    # Carrier information may not be available for all phone numbers or regions.
+    #
+    # @return [String, nil] the carrier name, or nil if not available
+    #
+    # @example Getting carrier information
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 170 1234567")
+    #   phone.carrier # => "T-Mobile"
+    #
+    # @example When carrier is not available
+    #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+    #   phone.carrier # => nil
+    def carrier
+      @internal.carrier
+    end
+
+  end
+
+end

data/lib/dialing_sorcerer/rspec_matchers.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module DialSorcerer
+  # RSpec matchers for testing phone numbers
+  # These matchers provide convenient ways to test phone number properties in RSpec tests.
+  #
+  # @example Using the matchers in RSpec
+  #   RSpec.describe "Phone number validation" do
+  #     include DialSorcerer::PhoneNumber::Matchers
+  #
+  #     it "validates mobile numbers" do
+  #       phone = DialSorcerer::PhoneNumber.parse("+49 151 12345678")
+  #       expect(phone).to be_mobile
+  #     end
+  #
+  #     it "validates VOIP numbers" do
+  #       voip = DialSorcerer::PhoneNumber.parse("+49 32 12345678")
+  #       expect(voip).to be_voip
+  #     end
+  #
+  #     it "matches MSISDN strings" do
+  #       phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+  #       expect(phone).to match_msisdn("+493012345678")
+  #     end
+  #   end
+  #
+  # @since 0.1.0
+  class PhoneNumber
+    # Provide rspec matchers for DialSorcerer::PhoneNumber
+    module Matchers
+
+      extend ::RSpec::Matchers::DSL
+
+      # Validates that the given object is a PhoneNumber instance
+      # Raises ArgumentError if the object is not a PhoneNumber
+      #
+      # @param number [Object] the object to validate
+      # @raise [ArgumentError] if the object is not a PhoneNumber
+      # @api private
+      #
+      # @example
+      #   validate(phone_number) # passes if phone_number is a PhoneNumber
+      #   validate("string")     # raises ArgumentError
+      def validate(number)
+        return number if number.is_a?(DialSorcerer::PhoneNumber)
+
+        return DialSorcerer::PhoneNumber.parse(number) if number.is_a?(String)
+
+        raise(
+          DialSorcerer::Error,
+          "Expected a DialSorcerer::PhoneNumber object or a compatible String, but got #{number.class} <#{number}>."
+        )
+      rescue DialSorcerer::ParseError
+        raise(
+          DialSorcerer::Error,
+          "Expected a DialSorcerer::PhoneNumber object or a compatible String, but got #{number.class} <#{number}>."
+        )
+      end
+
+      # RSpec matcher to test if a phone number is a VOIP number
+      #
+      # @example Positive assertion
+      #   expect(phone).to be_voip
+      #
+      # @example Negative assertion
+      #   expect(phone).not_to be_voip
+      #
+      # @example In a test
+      #   voip_number = DialSorcerer::PhoneNumber.parse("+49 32 12345678")
+      #   expect(voip_number).to be_voip
+      matcher :be_voip do
+        match do |number|
+          number = validate(number)
+          number.type == 'Voip'
+        end
+
+        failure_message do |number|
+          "expected MSISDN \"#{number}\" to be a\"VOIP\" number,\n\t\tbut is a \"#{number.type}\" number."
+        end
+
+        failure_message_when_negated do |number|
+          "expected MSISDN \"#{number}\" not to be a \"VOIP\" number,\n\t\tbut is a \"#{number.type}\" number."
+        end
+      end
+
+      # RSpec matcher to test if a phone number is a mobile number
+      #
+      # @example Positive assertion
+      #   expect(phone).to be_mobile
+      #
+      # @example Negative assertion
+      #   expect(phone).not_to be_mobile
+      #
+      # @example In a test
+      #   mobile_number = DialSorcerer::PhoneNumber.parse("+49 151 12345678")
+      #   expect(mobile_number).to be_mobile
+      matcher :be_mobile do
+        match do |number|
+          number = validate(number)
+          number.type == 'Mobile'
+        end
+
+        failure_message do |number|
+          "expected MSISDN \"#{number}\" to be mobile,\n\t\tbut got \"#{number.type}\"."
+        end
+
+        failure_message_when_negated do |number|
+          "expected MSISDN \"#{number}\" not to be mobile,\n\t\tbut got \"#{number.type}\"."
+        end
+      end
+
+      # RSpec matcher to test if a phone number matches a given MSISDN string
+      # Uses the flexible `equal?` method which checks multiple formats
+      #
+      # @param expected_number [String, PhoneNumber] the expected number to match against
+      #
+      # @example Positive assertion with E.164 format
+      #   expect(phone).to match_msisdn("+493012345678")
+      #
+      # @example Positive assertion with national format
+      #   expect(phone).to match_msisdn("030 12345678")
+      #
+      # @example Negative assertion
+      #   expect(phone).not_to match_msisdn("+441234567890")
+      #
+      # @example In a test
+      #   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+      #   expect(phone).to match_msisdn("+493012345678")
+      #   expect(phone).to match_msisdn("030 12345678")
+      matcher :match_msisdn do |expected_number|
+        match do |number|
+          number = validate(number)
+          number.equal?(expected_number)
+        end
+
+        failure_message do |number|
+          "expected MSISDN to match \"#{number}\",\n\t\tbut got \"#{expected_number}\"."
+        end
+
+        failure_message_when_negated do |number|
+          "expected MSISDN not to match \"#{number}\",\n\t\tbut got \"#{expected_number}\"."
+        end
+      end
+
+    end
+  end
+end

data/lib/dialing_sorcerer/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DialSorcerer
+
+  # The current version of the DialSorcerer gem
+  #
+  # @example Getting the version
+  #   puts DialSorcerer::VERSION # => "0.1.0"
+  #
+  # @return [String] the semantic version string
+  # @since 0.1.0
+  VERSION = '1.0.1'
+
+end

data/lib/dialing_sorcerer.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'dialing_sorcerer/phone_number'
+require_relative 'dialing_sorcerer/version'
+
+# DialSorcerer is a Ruby gem for parsing and formatting phone numbers.
+# It provides a simple API for validating phone numbers and converting
+# them between different formats.
+#
+# @example Basic usage
+#   phone = DialSorcerer::PhoneNumber.parse("+49 30 12345678")
+#   puts phone.to_e164 # => "+493012345678"
+#   puts phone.to_national # => "030 12345678"
+#
+# @example With country code
+#   phone = DialSorcerer::PhoneNumber.parse("030 12345678", "DE")
+#   puts phone.country # => "DE"
+#
+# @author DialSorcerer Team
+# @since 0.1.0
+module DialSorcerer
+
+  # Base error class for all DialSorcerer exceptions
+  #
+  # @example Rescuing DialSorcerer errors
+  #   begin
+  #     phone = DialSorcerer::PhoneNumber.parse("invalid")
+  #   rescue DialSorcerer::Error => e
+  #     puts "An error occurred: #{e.message}"
+  #   end
+  class Error < StandardError; end
+
+  # Error raised when phone number parsing fails
+  #
+  # @example Handling parse errors
+  #   begin
+  #     phone = DialSorcerer::PhoneNumber.parse("123")
+  #   rescue DialSorcerer::ParseError => e
+  #     puts "Failed to parse phone number: #{e.message}"
+  #   end
+  class ParseError < ArgumentError; end
+
+end

data/sig/dialing_sorcerer.rbs

@@ -0,0 +1,83 @@
+module DialSorcerer
+  VERSION: "0.1.0"
+
+  class Error < StandardError
+  end
+
+  class ParseError < StandardError
+  end
+
+  # Result object returned by PhoneNumber.try_parse method
+  class ParseResult < Struct[untyped]
+    attr_accessor success?: bool
+    attr_accessor phone_number: PhoneNumber?
+    attr_accessor error: String?
+    attr_accessor error_type: Symbol?
+
+    def initialize: (bool success?, PhoneNumber? phone_number, String? error, Symbol? error_type) -> void
+  end
+
+  # Represents a parsed and validated phone number with various formatting options
+  class PhoneNumber
+    # Parses a phone number string and returns a PhoneNumber object
+    def self.parse: (String number, ?String? country, ?default_country: String) -> PhoneNumber
+
+    # Attempts to parse a phone number without raising exceptions
+    def self.try_parse: (String number, ?String? country, ?default_country: String?) -> ParseResult
+
+    # Classifies error messages into specific error types
+    def self.classify_error: (String message) -> Symbol
+
+    def initialize: (untyped internal) -> void
+
+    # Checks if the phone number is valid
+    def valid?: () -> bool
+
+    # Formats the phone number in E.164 format
+    def to_e164: (?zero_leading: bool) -> String
+
+    # Formats the phone number in national format
+    def to_national: () -> String
+
+    # Formats the phone number in international format
+    def to_international: () -> String
+
+    # Returns the national number without country code
+    def national_number: () -> String
+
+    # Formats the phone number according to RFC 3966
+    def to_rfc3966: () -> String
+
+    # Returns the country calling code
+    def country_code: () -> Integer
+
+    # Returns the ISO country code
+    def country: () -> String
+
+    # Returns the E.164 representation for debugging
+    def inspect: () -> String
+
+    # Returns the E.164 representation as string
+    def to_s: () -> String
+
+    # Returns the phone number type
+    def type: () -> String
+
+    # Compares two phone numbers for equality
+    def ==: (untyped other) -> bool
+
+    # Checks if this phone number matches the given input in any supported format
+    def equal?: (untyped other) -> bool
+
+    # Returns the carrier name for the phone number
+    def carrier: () -> String?
+  end
+
+  # RSpec matchers for testing phone numbers
+  module PhoneNumberMatchers
+    extend RSpec::Matchers::DSL
+
+    # Validates that the given object is a PhoneNumber instance
+    def validate: (untyped number) -> void
+  end
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: dialing_sorcerer
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: x86_64-darwin
+authors:
+- Avengers
+- Mateus
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-10-31 00:00:00.000000000 Z
+dependencies: []
+description: |
+  DialSorcerer is a Ruby gem that provides comprehensive phone number parsing, validation,
+  and formatting capabilities. It supports international phone number formats, validation
+  of phone number types (mobile, fixed-line, VOIP, etc.), and conversion between different
+  formatting standards including E.164, national, international, and RFC 3966 formats.
+  The gem also includes RSpec matchers for convenient testing of phone number functionality.
+email:
+- mateus@moveaway.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop_todo.yml"
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/dialing_sorcerer.rb
+- lib/dialing_sorcerer/3.4/dialing_sorcerer.bundle
+- lib/dialing_sorcerer/phone_number.rb
+- lib/dialing_sorcerer/rspec_matchers.rb
+- lib/dialing_sorcerer/version.rb
+- sig/dialing_sorcerer.rbs
+homepage: https://gitlab.its/avengers/dial-sorcerer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gitlab.its/avengers/dial-sorcerer
+  source_code_uri: https://gitlab.its/avengers/dial-sorcerer.git
+  changelog_uri: https://gitlab.its/avengers/dial-sorcerer/main/CHANGELOG.md
+  documentation_uri: https://gitlab.its/dial-sorcerer
+  bug_tracker_uri: https://gitlab.its/avengers/dial-sorcerer/issues
+  rubygems_mfa_required: 'true'
+post_install_message: |
+  Thank you for installing DialSorcerer!
+
+  This gem provides powerful phone number parsing and formatting capabilities.
+  Check out the documentation at: https://rubydoc.info/gems/dialing_sorcerer
+
+  For examples and usage instructions, visit: https://github.com/armando/dialing_sorcerer
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: A Ruby gem for parsing and formatting phone numbers with international support.
+test_files: []