{"id":17188670,"url":"https://github.com/cainlevy/snail","last_synced_at":"2025-04-07T20:09:12.056Z","repository":{"id":614070,"uuid":"252292","full_name":"cainlevy/snail","owner":"cainlevy","description":"A Ruby gem to assist with collecting and formatting international addresses","archived":false,"fork":false,"pushed_at":"2024-12-10T05:37:10.000Z","size":252,"stargazers_count":118,"open_issues_count":3,"forks_count":23,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T19:08:51.975Z","etag":null,"topics":["postal","ruby","usps"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cainlevy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2009-07-15T23:40:52.000Z","updated_at":"2025-01-24T16:40:07.000Z","dependencies_parsed_at":"2024-06-18T21:22:47.293Z","dependency_job_id":"1507c845-9a9c-43dc-9d76-516310fbdf14","html_url":"https://github.com/cainlevy/snail","commit_stats":{"total_commits":114,"total_committers":16,"mean_commits":7.125,"dds":"0.42105263157894735","last_synced_commit":"98871e8981ed42d4663ab7978bf1f5ccdb33fcab"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cainlevy%2Fsnail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cainlevy%2Fsnail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cainlevy%2Fsnail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cainlevy%2Fsnail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cainlevy","download_url":"https://codeload.github.com/cainlevy/snail/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247721898,"owners_count":20985084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["postal","ruby","usps"],"created_at":"2024-10-15T01:09:35.688Z","updated_at":"2025-04-07T20:09:12.013Z","avatar_url":"https://github.com/cainlevy.png","language":"Ruby","readme":"# Snail\n\nInternational snail mail addressing is a pain. This gem begins to make it easier.\n\n## Problems\n\nThe first problem when sending mail is getting it OUT of the originating country. This means writing the destination country in a manner that the originating country understands.\n\nThe second problem is getting it TO the correct address. This means writing the address lines in a manner that the destination country understands.\n\n## Solutions\n\nSnail relies on practical formatting guidelines gathered by [Frank's Compulsive Guide to Postal Addresses](http://www.columbia.edu/kermit/postal.html), plus internationalized country names from [The Unicode CLDR Project](http://cldr.unicode.org/index).\n\n## Getting Started\n\nTaking regular data and formatting it into an internationally mailable address:\n\n```ruby\nSnail.new(\n  :name =\u003e \"Jon Doe\",\n  :line_1 =\u003e \"12345 Somewhere Ln\",\n  :line_2 =\u003e nil,\n  :city =\u003e \"Bentley\",\n  :region =\u003e \"WA\",\n  :postal_code =\u003e \"6102\",\n  :country =\u003e \"AU\"\n).to_s\n\n=\u003e \"Jon Doe\\n12345 Somewhere Ln\\nBENTLEY WA  6102\\nAUSTRALIA\"\n```\n\nBy default addresses with a country of USA are considered domestic and the country will\nbe left off any output. To change the home country:\n\n```ruby\nSnail.home_country = \"Australia\"\nSnail.new(\n  :name =\u003e \"Jon Doe\",\n  :line_1 =\u003e \"12345 Somewhere Ln\",\n  :line_2 =\u003e nil,\n  :city =\u003e \"Bentley\",\n  :region =\u003e \"WA\",\n  :postal_code =\u003e \"6102\",\n  :country =\u003e \"AU\"\n).to_s\n\n=\u003e \"Jon Doe\\n12345 Somewhere Ln\\nBENTLEY WA  6102\"\n```\n\nYou can override this default behavior by specifying `with_country` as `true` or `false`:\n\n```ruby\nSnail.home_country = \"Australia\"\nSnail.new(\n  :name =\u003e \"Jon Doe\",\n  :line_1 =\u003e \"12345 Somewhere Ln\",\n  :line_2 =\u003e nil,\n  :city =\u003e \"Bentley\",\n  :region =\u003e \"WA\",\n  :postal_code =\u003e \"6102\",\n  :country =\u003e \"AU\"\n).to_s(with_country: true)\n\n=\u003e \"Jon Doe\\n12345 Somewhere Ln\\nBentley WA  6102\\nAUSTRALIA\"\n```\n\nSee the test cases for more.\n\n## Fun Times\n\nThe United States Postal Service (USPS) requires (strongly prefers?) a few things:\n\n* That the address be 5 lines long or less.\n* That the last address line be a country name recognized by the USPS, in all uppercase.\n* That the city line (comprising the city, state, and postal code as appropriate) immediately precede the country line.\n\nNearly all of the variation in formatting rules applies to the city line. Depending on the receiving country, the three component pieces (e.g. city, state, postal code) have different names, are pieced together in different order with different punctuation, and may or may not be required.\n\nAnd then there's Great Britain, which Frank's Compulsive Guide describes as \"where to find the most confusing addresses on earth\" (a description confirmed and further confused by a source from within Royal Mail).\n\nCopyright (c) 2009-2016 Lance Ivy, released under the MIT license\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcainlevy%2Fsnail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcainlevy%2Fsnail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcainlevy%2Fsnail/lists"}