{"id":13463320,"url":"https://github.com/rsl/stringex","last_synced_at":"2025-03-25T06:31:47.717Z","repository":{"id":383588,"uuid":"765","full_name":"rsl/stringex","owner":"rsl","description":"Some [hopefully] useful extensions to Ruby’s String class. It is made up of three libraries: ActsAsUrl [permalink solution with better character translation], Unidecoder [Unicode to Ascii transliteration], and StringExtensions [miscellaneous helper methods for the String class].","archived":false,"fork":false,"pushed_at":"2023-08-29T09:48:30.000Z","size":674,"stargazers_count":984,"open_issues_count":19,"forks_count":158,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-10-29T13:50:50.193Z","etag":null,"topics":[],"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/rsl.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}},"created_at":"2008-02-19T15:31:07.000Z","updated_at":"2024-08-31T01:42:36.000Z","dependencies_parsed_at":"2024-01-13T03:01:33.961Z","dependency_job_id":"581f1179-e630-45d7-8dc2-3fc3bb22a314","html_url":"https://github.com/rsl/stringex","commit_stats":{"total_commits":558,"total_committers":71,"mean_commits":7.859154929577465,"dds":0.510752688172043,"last_synced_commit":"85bc93e817060de13531ff1a4e4f3a5c00aa3280"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsl%2Fstringex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsl%2Fstringex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsl%2Fstringex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rsl%2Fstringex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rsl","download_url":"https://codeload.github.com/rsl/stringex/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244924928,"owners_count":20532898,"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":[],"created_at":"2024-07-31T13:00:50.837Z","updated_at":"2025-03-25T06:31:47.142Z","avatar_url":"https://github.com/rsl.png","language":"Ruby","readme":"# Stringex [\u003cimg src=\"https://codeclimate.com/github/rsl/stringex.svg\" /\u003e](https://codeclimate.com/github/rsl/stringex) [\u003cimg src=\"https://travis-ci.org/rsl/stringex.svg?branch=master\" alt=\"Build Status\" /\u003e](https://travis-ci.org/rsl/stringex) [\u003cimg src=\"https://badge.fury.io/rb/stringex.svg\" alt=\"Gem Version\" /\u003e](http://badge.fury.io/rb/stringex)\n\nSome [hopefully] useful extensions to Ruby's String class. It is made up of three libraries: ActsAsUrl, Unidecoder, and StringExtensions.\n\n*NOTE: Stringex 2.0 [and beyond] drops support for Rails 2. If you need support for that version, use 1.5.1 instead.*\n\n## ActsAsUrl\n\n*NOTE: You can now require 'stringex_lite' instead of 'stringex' and skip loading ActsAsUrl functionality if you don't need it.*\n\nThis library is designed to create URI-friendly representations of an attribute, for use in generating urls from your attributes. Basic usage is just calling the method:\n\n```ruby\n# Inside your model\nacts_as_url :title\n```\n\nwhich will populate the `url` attribute on the object with the converted contents of the `title` attribute. `acts_as_url` takes the following options:\n\n| | |\n|---|---|\n| `:url_attribute` | The name of the attribute to use for storing the generated url string. Default is `:url` |\n| `:scope` | The name of model attribute to scope unique urls to. There is no default here. |\n| `:only_when_blank` | If set to true, the url generation will only happen when `:url_attribute` is blank. Default is false (meaning url generation will happen always). |\n| `:sync_url` | If set to true, the url field will be updated when changes are made to the attribute it is based on. Default is false. |\n| `:allow_slash` | If set to true, the url field will not convert slashes. Default is false. |\n| `:allow_duplicates` | If set to true, unique urls will not be enforced. Default is false. *NOTE: This is strongly not recommended if you are routing solely on the generated slug as you will no longer be guaranteed to lookup the expected record based on a duplicate slug.* |\n| `:limit` | If set, will limit length of url generated. Default is nil. |\n| `:truncate_words` | Used with :limit. If set to false, the url will be truncated to the last whole word before the limit was reached. Default is true. |\n| `:blacklist` | List of urls that should not be allowed. Default is `%w{new}` [which avoids confusion on urls like `/documents/new`]. |\n| `:blacklist_policy` | Proc or lambda defining new naming behavior when blacklisted urls are encountered. Default converts `/documents/new` to `/documents/new-document`. |\n\nIn order to use the generated url attribute, you will probably want to\noverride `to_param` like so, in your Model:\n\n```ruby\n# Inside your model\ndef to_param\n  url # or whatever you set :url_attribute to\nend\n```\n\nRouting called via named routes like `foo_path(@foo)` will automatically use the url. In your controllers you will need to call\n`Foo.find_by_url(params[:id])` instead of the regular find. Don't look for `params[:url]` unless you set it explicitly in the routing, `to_param` will generate `params[:id]`.\n\nNote that if you add `acts_as_url` to an existing model, the `url` database column will initially be blank. To set this column for your existing instances, you can use the `initialize_urls` method. So if your class is `Post`, just say `Post.initialize_urls`.\n\nUnlike other permalink solutions, ActsAsUrl doesn't rely on Iconv (which is inconsistent across platforms and doesn't provide great transliteration as is) but instead uses a transliteration scheme (see the code for Unidecoder) which produces much better results for Unicode characters. It also mixes in some custom helpers to translate common characters into a more URI-friendly format rather than just dump them completely. Examples:\n\n```ruby\n# A simple prelude\n\"simple English\".to_url =\u003e \"simple-english\"\n\"it's nothing at all\".to_url =\u003e \"its-nothing-at-all\"\n\"rock \u0026 roll\".to_url =\u003e \"rock-and-roll\"\n\n# Let's show off\n\"$12 worth of Ruby power\".to_url =\u003e \"12-dollars-worth-of-ruby-power\"\n\"10% off if you act now\".to_url =\u003e \"10-percent-off-if-you-act-now\"\n\n# You dont EVEN wanna rely on Iconv for this next part\n\"kick it en Français\".to_url =\u003e \"kick-it-en-francais\"\n\"rock it Español style\".to_url =\u003e \"rock-it-espanol-style\"\n\"tell your readers 你好\".to_url =\u003e \"tell-your-readers-ni-hao\"\n```\n\nCompare those results with the ones produced on my Intel Mac by a leading permalink plugin:\n\n```ruby\n\"simple English\" # =\u003e \"simple-english\"\n\"it's nothing at all\" # =\u003e \"it-s-nothing-at-all\"\n\"rock \u0026 roll\" # =\u003e \"rock-roll\"\n\n\"$12 worth of Ruby power\" # =\u003e \"12-worth-of-ruby-power\"\n\"10% off if you act now\" # =\u003e \"10-off-if-you-act-now\"\n\n\"kick it en Français\" # =\u003e \"kick-it-en-francais\"\n\"rock it Español style\" # =\u003e \"rock-it-espan-ol-style\"\n\"tell your readers 你好\" # =\u003e \"tell-your-readers\"\n```\n\nNot so great, actually.\n\nNote: No offense is intended to the author(s) of whatever plugins might produce such results. It's not your faults Iconv sucks.\n\n## Unidecoder\n\nThis library converts Unicode [and accented ASCII] characters to their plain-text ASCII equivalents. This is a port of Perl's Unidecode and provides eminently superior and more reliable results than Iconv. (Seriously, Iconv... A plague on both your houses! [sic])\n\nYou may require only the unidecoder (and its dependent localization) via\n\n```ruby\nrequire \"stringex/unidecoder\"\n```\n\nYou probably won't ever need to run Unidecoder by itself. Thus, you probably would want to add String#to_ascii which wraps all of Unidecoder's functionality, by requiring:\n\n```ruby\nrequire \"stringex/core_ext\"\n```\n\nFor anyone interested, details of the implementation can be read about in the original implementation of [Text::Unidecode](http://interglacial.com/~sburke/tpj/as_html/tpj22.html). Extensive examples can be found in the tests.\n\n## StringExtensions\n\nA small collection of extensions on Ruby's String class. Please see the documentation for StringExtensions module for more information. There's not much to explain about them really.\n\n## Localization\n\nWith Stringex version 2.0 and higher, you can localize the different conversions in Stringex. Read more [here](https://github.com/rsl/stringex/wiki/Localization-of-Stringex-conversions). If you add a new language, please submit a pull request so we can make it available to other users also.\n\n## Ruby on Rails Usage\n\nWhen using Stringex with Ruby on Rails, you automatically get built-in translations for miscellaneous characters, HTML entities, and vulgar fractions. You can see Stringex's standard translations [here](https://github.com/rsl/stringex/tree/master/locales).\n\nCurrently, built-in translations are available for the following languages:\n\n* English (en)\n* Danish (da)\n* Swedish (sv)\n* Dutch (nl)\n* German (de)\n* Polish (pl)\n* Portuguese Brazilian (pt-BR)\n* Russian (ru)\n\nYou can easily add your own or customize the built-in translations - read [here](https://github.com/rsl/stringex/wiki/Localization-of-Stringex-conversions). If you add a new language, please submit a pull request so we can make it available to other users also.\n\nIf you don't want to use the Stringex built-in translations, you can force Stringex to use English (or another language), regardless what is in your `I18n.locale`. In an initializer, e.g. `config/initializers/stringex.rb`:\n\n```ruby\nStringex::Localization.locale = :en\n```\n\n## CanCan Usage Note\n\nYou'll need to add a `:find_by =\u003e :url` to your `load_and_authorize_resource`. Here's an example:\n\n```ruby\nload_and_authorize_resource :class =\u003e \"Whatever\", :message =\u003e \"Not authorized\", :find_by =\u003e :url\n```\n\n## Semantic Versioning\n\nThis project conforms to [semver](http://semver.org/). As a result of this policy, you can (and should) specify a dependency on this gem using the [Pessimistic Version Constraint](http://guides.rubygems.org/patterns/) with two digits of precision. For example:\n\n```ruby\nspec.add_dependency 'stringex', '~\u003e 1.0'\n```\n\nThis means your project is compatible with licensee 1.0 up until 2.0. You can also set a higher minimum version:\n\n```ruby\nspec.add_dependency 'stringex', '~\u003e 1.1'\n```\n\n## Thanks \u0026 Acknowledgements\n\nIf it's not obvious, some of the code for ActsAsUrl is based on Rick Olsen's [permalink_fu](http://svn.techno-weenie.net/projects/plugins/permalink_fu/) plugin. Unidecoder is a Ruby port of Sean Burke's [Text::Unidecode](http://interglacial.com/~sburke/tpj/as_html/tpj22.html) module for Perl. And, finally, the bulk of [strip_html_tags](classes/Stringex/StringExtensions.html#M000005) in StringExtensions was stolen from Tobias Lütke's Regex in [Typo](http://typosphere.org/).\n\nGIANT thanks to the many contributors who have helped make Stringex better and better: http://github.com/rsl/stringex/contributors\n\nCopyright (c) 2008-2018 Lucky Sneaks, released under the MIT license\n","funding_links":[],"categories":["Rails Plugins","Ruby"],"sub_categories":["Rails Permalinks \u0026 Slugs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsl%2Fstringex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frsl%2Fstringex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frsl%2Fstringex/lists"}