name_formatter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6037e2a676981c2ef2026b3387a0e21a7e36db146449d51ba4710068e316473e
+  data.tar.gz: cbc2fd01074904d6d1225f0901b16adc941aa41a2c64f6f6b49e743a17b8c3fd
+SHA512:
+  metadata.gz: a748dfe1cb4cb20fae52eb78a741281ba946f153b38acd35e520d2c5b858104f59701566dd7cedbaa2bdbbcec7201ac858b05463d9d09a5285481324cf510057
+  data.tar.gz: 266a1de96fd71ba93d85677eb694d6ebcbcf23744ac1c2d6030b20fde0ab3ff0a6c7ca784ca857810960abb13bca41866c8f9da77fbfcce3f53069291774c854

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-06-28
+Initial realase
+
+### Added
+
+- Support for parsing complex names with prefixes, suffixes, particles and beyond.
+
+[0.1.0]: https://github.com/kylewelsby/name_formatter/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2024 Kyle Welsby, https://mekyle.com <kyle@mekyle.com>
+
+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,135 @@
+![Status Badge](https://github.com/kylewelsby/name_formatter/actions/workflows/main.yml/badge.svg)
+
+# NameFormatter
+
+NameFormatter is a Ruby gem that provides robust name parsing and formatting capabilities. It handles a wide variety of name formats, including personal names from different cultures, company names, and names with prefixes and suffixes.
+
+## ✨ Features
+
+- Handles personal names from various cultures (Western, Spanish, German, etc.)
+- Supports company names and legal entities
+- Correctly formats prefixes, suffixes, and particles (e.g., "van", "de", "von")
+- Preserves capitalization for names like "McDonald" or "DeVito"
+- Unicode-aware, handling names with non-ASCII characters
+
+## 🎲 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'name_formatter'
+```
+
+and then execute:
+
+```bash
+bundle install
+```
+
+or install it yourself as:
+
+```bash
+gem install name_formatter
+```
+
+## 🛠️ Usage
+
+```ruby
+require 'name_formatter'
+
+formatter = NameFormatter.new
+
+# Format a name
+formatted = formatter.format("JOHN DOE")
+puts formatted  # Output: "John Doe"
+
+# Parse and Format a name
+parsed = formatter.parse_formatted("Dr. Jane Smith Jr.")
+puts parsed
+# Output: {
+#   prefix: "Dr.",
+#   first_name: "Jane",
+#   last_name: "Smith",
+#   suffix: "Jr."
+# }
+
+# Parse skip formatting a name
+parsed = formatter.parse("Dr. Jane Smith Jr.")
+puts parsed
+# Output: {
+#   prefix: "Dr.",
+#   first_name: "Jane",
+#   last_name: "Smith",
+#   suffix: "Jr."
+# }
+
+# Handle complex names
+puts formatter.format("MARÍA DEL CARMEN MARTÍNEZ-VILLASEÑOR")
+# Output: "María del Carmen Martínez-Villaseñor"
+
+# Handle company names
+puts formatter.format("ACME CORPORATION, INC.")
+# Output: "Acme Corporation, Inc."
+```
+
+
+## 👨‍💻 Development
+
+1. Run the tests to ensure everything is setup correctly:
+
+```ruby
+ruby -Ilib test/*.rb
+```
+
+2. To run an interactive prompt that will allow you to expriement with the code, you can use:
+
+```ruby
+irb -Ilib -rname_formatter
+```
+
+Remember to add tests for new features or bugs fixes.
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on GitHub at [github.com/kylewelsby/name_formatter](https://github.com/kylewelsby/name_formatter).
+
+## 🚀 Releasing
+
+To release a new version:
+
+1. Update the version number in `lib/name_formatter/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit changes
+4. Create a new tag with `git tag -a vX.X.X -m "Release X.X.X"`
+5. Push the tag with `git push origin vX.X.X`
+
+GitHub Actions will automatically build and publish the gem oto RubyGems.org when the tag is pushed.
+
+
+### If the release fails
+
+If the tests fail during the release process:
+
+1. Fix the failing tests
+2. Commit your changes
+3. Update the tag
+```
+git tag -fa vX.X.X -M "Update release X.X.X"
+```
+4. Force-push the update tag:
+```
+git push origin vX.X.X --force
+```
+
+This will trigger the release process again with the updated code.
+
+Remember, force-pushing a tag can cause issues if others have already pulled that tag, so it's generally best to use this approach only for fixing issues with releases that haven't been widely distributed yet.
+
+For more significant changes, it might be better to increment the version number (e.g., from 0.1.0 to 0.1.1) and create a new tag instead of updating the existing one.
+
+## 🎓 License
+
+This gem is available as open source under ther terms of the MIT License.
+
+https://kylewelsby.mit-license.org
+

data/lib/name_formatter/version.rb

@@ -0,0 +1,3 @@
+module NameFormatterModule
+  VERSION = "0.1.0"
+end

data/lib/name_formatter.rb

@@ -0,0 +1,159 @@
+require "name_formatter/version"
+class NameFormatter
+  VERSION = NameFormatterModule::VERSION
+  PREFIXES = Set.new(["Mr", "Mrs", "Ms", "Miss", "The Hon", "Rev", "Dr", "Fr", "Pres", "Prof", "Msgr", "Sen", "Gov", "Rep", "Amb"]).freeze
+  SUFFIXES = Set.new([
+    "Esq", "Jr", "Sr", "III", "II", "I", "V", "IV", "MD", "DC", "DO", "DVM", "LLD", "VM", "DDS", "Ret", "CPA", "JD", "PhD",
+    "LLC", "Inc", "Corp", "Ltd", "Co", "LLC", "PLC", "GmbH", "AG", "SA", "SARL", "SRL", "BV", "CV", "NV", "SE", "SC", "SL", "SLL", "SLLC", "SCS", "SCA", "SCRL", "SCA"
+  ]).freeze
+
+  NAME_REGEX = /^(?<prefix>(#{PREFIXES.join("|")}?)\.?)?\s*(?<first_name>[\w-]+)\s+(?<last_name>[\w\s'-]+)\s*(?<suffix>(#{SUFFIXES.join("|")})\.?)?$/ix
+
+  COMPANY_SUFFIX_REGEX = /^(.+)\s+(Inc\.?|Corp\.?|Ltd\.?|LLC|LLP|LP|Limited|Corporation|Company)$/i
+  FAMILY_BUSINESS_REGEX = /^(.+)\s+(?:and|&)\s+Sons$/i
+  MULTIPLE_FAMILY_NAMES_REGEX = /^[\w']+,\s+[\w']+\s+(?:and|&)\s+[\w']+$/i
+  DOUBLE_BARRELLED_NAME_REGEX = /^[\w']+-[\w']+$/
+  LAW_FIRM_REGEX = /^(?:[A-Z][a-z]+\s+){2,}(?:LLP|LLC|PC|PLLC)?$/
+  COMPANY_CO_REGEX = /^(.+)\s+(?:Company|Co\.)$/i
+  GROUP_HOLDINGS_REGEX = /^(.+)\s+(?:Group|Holdings)$/i
+  GEOGRAPHIC_COMPANY_REGEX = /^(.+)\s+of\s+[A-Z][a-z]+$/i
+  TRADING_ENTERPRISES_REGEX = /^(.+)\s+(?:Trading|Enterprises)$/i
+
+  DUNAME_REGEX = /^Du[b](?=[aeiou])/i
+  DENAME_REGEX = /^De[bfghjlmnpvw][aeioulr](?!(?:sik|a)(?:[-,])?$)/i
+
+  MCNAME_REGEX = /^Mc[a-z]+/i
+  MACNAME_REGEX = /^Mac(?:[aà][bdilmnors]|b[eh]|c[aeioruò]|d[h]|e[aò]|f[hiru]|g[ahilouy]|i[alo]|l[aeiouù]|m[hiua]|n[aeèiìo]|p[h]|r[aiìou]|s[hipu]|t[hiu]|u[airs])+/i
+  PARTICLE_REGEX = /^(de[rsl]|d[aiu]|v[oa]n|te[nr]|la|les|y|and|zu|dell[ao])$/i
+
+  def parse(name)
+    return parse_company_name(name) if company_name?(name)
+
+    parts = name.strip.split(/\s+/)
+
+    prefix = extract_prefix_or_suffix(parts, PREFIXES)
+    suffix = extract_prefix_or_suffix(parts.reverse, SUFFIXES)
+
+    if parts.size > 1
+      first_name = parts.shift
+      last_name = parts.reject { |part| part == suffix }.join(" ")
+      last_name = nil if last_name.empty?
+    elsif prefix && parts.size == 1
+      first_name = nil
+      last_name = parts.first
+    else
+      first_name = parts.first
+      last_name = nil
+    end
+
+    {
+      prefix: prefix,
+      first_name: first_name,
+      last_name: last_name,
+      suffix: suffix
+    }
+  end
+
+  def parse_formatted(name)
+    parsed = parse(name)
+    {
+      prefix: format_prefix(parsed[:prefix]),
+      first_name: format_first_name(parsed[:first_name]),
+      last_name: format_last_name(parsed[:last_name]),
+      suffix: format_suffix(parsed[:suffix])
+    }
+  end
+
+  def format(name)
+    parse_formatted(name).values.compact.join(" ")
+  end
+
+  private
+
+  def company_name?(name)
+    [COMPANY_SUFFIX_REGEX, FAMILY_BUSINESS_REGEX, MULTIPLE_FAMILY_NAMES_REGEX,
+      LAW_FIRM_REGEX, COMPANY_CO_REGEX, GROUP_HOLDINGS_REGEX,
+      GEOGRAPHIC_COMPANY_REGEX, TRADING_ENTERPRISES_REGEX, DOUBLE_BARRELLED_NAME_REGEX].any? { |regex| name.match?(regex) }
+  end
+
+  def parse_company_name(name)
+    parts = name.strip.split(/\s+/)
+    suffix = extract_prefix_or_suffix(parts.reverse, SUFFIXES)
+    {
+      prefix: nil,
+      first_name: nil,
+      last_name: parts.reject { |part| part == suffix }.join(" "),
+      suffix: suffix
+    }
+  end
+
+  def extract_prefix_or_suffix(parts, list)
+    list.each do |item|
+      item_parts = item.split
+      if item_parts.length <= parts.length
+        potential_match = parts.take(item_parts.length).join(" ").delete(".")
+        return parts.shift(item_parts.length).join(" ") if item.casecmp?(potential_match)
+      end
+    end
+    nil
+  end
+
+  def format_first_name(name)
+    return if name.nil?
+    parts = name.split(/\s+|(?<=-)/)
+    parts.map do |part|
+      format_first_name_part(part)
+    end.join(" ").gsub("- ", "-")
+  end
+
+  def format_first_name_part(part)
+    case part.downcase
+    when /^[od]'\w+/i
+      part[0..1].capitalize + part[2..].capitalize
+    else
+      part.capitalize
+    end
+  end
+
+  def format_last_name(name)
+    return if name.nil?
+    parts = name.split(/\s+|(?<=-)/)
+    formatted_parts = []
+    parts.each_with_index do |part, index|
+      next_part = parts[index + 1]
+      formatted_parts << format_last_name_part(part, next_part)
+    end
+    formatted_parts.join(" ").gsub("- ", "-")
+  end
+
+  def format_last_name_part(part, next_part)
+    case part.downcase
+    when /^(v[ao]n|te|ter|de)$/i
+      next_part&.match?(/der/i) ? part.downcase : part.capitalize
+    when PARTICLE_REGEX
+      next_part ? part.downcase : part.capitalize
+    when /^dell'\w+/i
+      part[0..4].capitalize + part[5..].capitalize
+    when MCNAME_REGEX, DUNAME_REGEX, DENAME_REGEX, /^[od]'\w+/i
+      part[0..1].capitalize + part[2..].capitalize
+    when /^von[r]+/i, MACNAME_REGEX
+      part[0..2].capitalize + part[3..].capitalize
+    else
+      part.capitalize
+    end
+  end
+
+  def format_prefix(part)
+    return if part.nil?
+    part.split.map(&:capitalize).join(" ")
+  end
+
+  def format_suffix(part)
+    return if part.nil?
+    matched = SUFFIXES.find { |suffix| suffix.casecmp?(part.gsub(/\.$/, "")) }
+    if matched
+      return matched + (part.end_with?(".") ? "." : "")
+    end
+    part.end_with?(".") ? part.capitalize : part.upcase
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: name_formatter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kyle Welsby
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-06-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: |-
+  NameFormatter provides advanced name parsing and formatting capabilities,
+                            handling personal names from various cultures, company names, and names
+                            with prefixes and suffixes. It correctly formats particles, preserves
+                            appropriate capitalization, and is Unicode-aware.
+email:
+- kyle@mekyle.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/name_formatter.rb
+- lib/name_formatter/version.rb
+homepage: https://github.com/kylewelsby/name_formatter
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  changelog_uri: https://github.com/kylewelsby/name_formatter/blob/main/CHANGELOG.md
+  funding_uri: https://github.com/sponsors/kylewelsby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key: 
+specification_version: 4
+summary: A robust name parsing and formatting library for Ruby
+test_files: []