strings-case 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bec785e9ba89be06265c1bc10dc3e9523aedd7381f318439251f7100ff03d4f4
-  data.tar.gz: 7d3291105499505fcc5782e18f9c278b687a1b2dbd88b4342e5641601757dd3e
+  metadata.gz: 321f95c3ae804e7b64eddc3566fcec63b3be6e5f81804cc236cc4187ff1fcc59
+  data.tar.gz: 7aee26f0af7f322b9c54b3c7e672849e050290de91c3b604be512a5ed7a839ac
 SHA512:
-  metadata.gz: 7bee902c8bd54279c1d70e8592117eaf173f2c2920b0b7caa4d0e5006faf795771e82f834078bc1022b581d16df4b0fb9e60af928395c03bceb2265bac323d07
-  data.tar.gz: c533aaf5d4f0cbe6f88a18f66aef6f25254dac9ee753c2e4941a02c8cb4456a82b7bc09e68f05d9f7fcc26063fbef9ffd91366bfd76c489b7cf28e5bc34215ae
+  metadata.gz: f1e29519c62ae22f61797bf59f65c76fef22e7b6050db7a6bdec4c74c13495b9d61d2fcc4b9f51710c089a0923dc9c6ca10e6bdd52d56ca34075aca730be508f
+  data.tar.gz: bc754e29be3e76326de7da906d214abe7299e20a51ef5837996bf0cd8a1e20f03b127900e2e3de9fccae6ca546ae83bde277c6b9bf9e474597602a2efd7c668f

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change log
 
+## [v0.4.0] - 2023-11-19
+
+### Added
+* Add the ability to configure acronyms on an instance
+
+### Changed
+* Change Strings::Case to be a class to allow instantiation
+* Change all conversions to apply acronyms configured on an instance
+* Change all conversions to preserve non-alphanumeric characters
+* Change all conversions to allow for one-letter words
+* Change gemspec to only package the source files and documentation
+* Change parsecase method to improve performance
+* Change extensions to require core library when loaded
+* Change Strings::Case class to hide constants
+* Change Strings::Case class to hide instance method
+
 ## [v0.3.0] - 2019-12-07
 
 ### Added
@@ -17,6 +33,7 @@
 
 * Initial implementation and release
 
-[v0.3.0]: https://github.com/piotrmurach/strings-case/compare/v0.1.0...v0.3.0
+[v0.4.0]: https://github.com/piotrmurach/strings-case/compare/v0.3.0...v0.4.0
+[v0.3.0]: https://github.com/piotrmurach/strings-case/compare/v0.2.0...v0.3.0
 [v0.2.0]: https://github.com/piotrmurach/strings-case/compare/v0.1.0...v0.2.0
-[v0.1.0]: https://github.com/piotrmurach/strings-case/compare/v0.1.0
+[v0.1.0]: https://github.com/piotrmurach/strings-case/compare/03679ef...v0.1.0

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Piotr Murach
+Copyright (c) 2019 Piotr Murach (piotrmurach.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

data/README.md

@@ -5,45 +5,35 @@
 # Strings::Case
 
 [![Gem Version](https://badge.fury.io/rb/strings-case.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/piotrmurach/strings-case.svg?branch=master)][travis]
+[![Actions CI](https://github.com/piotrmurach/strings-case/actions/workflows/ci.yml/badge.svg)][gh_actions_ci]
 [![Build status](https://ci.appveyor.com/api/projects/status/yr87c96wxp1cw2ep?svg=true)][appveyor]
 [![Maintainability](https://api.codeclimate.com/v1/badges/7938258c4af196a19843/maintainability)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/strings-case/badge.svg?branch=master)][coverage]
-[![Inline docs](http://inch-ci.org/github/piotrmurach/strings-case.svg?branch=master)][inchpages]
 
 [gem]: http://badge.fury.io/rb/strings-case
-[travis]: http://travis-ci.org/piotrmurach/strings-case
+[gh_actions_ci]: https://github.com/piotrmurach/strings-case/actions/workflows/ci.yml
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/strings-case
 [codeclimate]: https://codeclimate.com/github/piotrmurach/strings-case/maintainability
 [coverage]: https://coveralls.io/github/piotrmurach/strings-case?branch=master
-[inchpages]: http://inch-ci.org/github/piotrmurach/strings-case
 
 > Convert strings to different cases.
 
-**Strings::Case** provides string case conversions for [Strings](https://github.com/piotrmurach/strings) utilities.
+**Strings::Case** provides string case conversions for
+[Strings](https://github.com/piotrmurach/strings) utilities.
 
-## Motivation
-
-Popular solutions that deal with transforming string cases work well in simple cases.(Sorry ;-) With more complex strings you may get unexpected results:
-
-```ruby
-ActiveSupport::Inflector.underscore("supports IPv6 on iOS?")
-# => "supports i_pv6 on i_os?"
-```
-
-In contrast, `Strings::Case` aims to be able to transform any string to expected case:
+## Features
 
-```ruby
-Strings::Case.underscore("supports IPv6 on iOS?")
-# => "supports_ipv6_on_ios"
-```
+* No monkey-patching String class
+* Convert strings to many common cases
+* Support for Unicode characters
+* Preserve acronyms
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'strings-case'
+gem "strings-case"
 ```
 
 And then execute:
@@ -54,218 +44,307 @@ Or install it yourself as:
 
     $ gem install strings-case
 
-
-## Features
-
-* No monkey-patching String class
-* Converts any string to specified case
-* Supports Unicode characters
-* Provides many common case transformations
-* Allows to preserve casing of acronyms
-
 ## Contents
 
 * [1. Usage](#1-usage)
 * [2. API](#2-api)
-  * [2.1 camelcase](#21-camelcase)
-  * [2.2 constcase](#22-constcase)
-  * [2.3 headercase](#23-headercase)
-  * [2.4 kebabcase | dashcase](#24-kebabcase--dashcase)
-  * [2.5 pascalcase](#25-pascalcase)
-  * [2.6 pathcase](#26-pathcase)
-  * [2.7 sentencecase](#27-sentencecase)
-  * [2.8 snakecase | underscore](#28-snakecase--underscore)
-  * [2.9 titlecase](#29-titlecase)
+  * [2.1 configure](#21-configure)
+  * [2.2 camelcase](#22-camelcase)
+  * [2.3 constcase](#23-constcase)
+  * [2.4 headercase](#24-headercase)
+  * [2.5 kebabcase \| dashcase](#25-kebabcase--dashcase)
+  * [2.6 pascalcase](#26-pascalcase)
+  * [2.7 pathcase](#27-pathcase)
+  * [2.8 sentencecase](#28-sentencecase)
+  * [2.9 snakecase \| underscore](#29-snakecase--underscore)
+  * [2.10 titlecase](#210-titlecase)
 * [3. Extending String class](#3-extending-string-class)
 
 ## 1. Usage
 
-The `Strings::Case` is a module with functions for transforming between string cases:
+Start by creating an instance of the `Strings::Case` class:
 
 ```ruby
-Strings::Case.snakecase("foo bar baz")
+strings = Strings::Case.new
+```
+
+Then, use one of many case conversion methods, for example,
+the `snakecase` method:
+
+```ruby
+strings.snakecase("FooBarBaz")
 # => "foo_bar_baz"
-````
+```
 
-It will transform any string into expected case:
+As a convenience, case conversion methods are also available on class:
 
 ```ruby
-Strings::Case.snakecase("supports IPv6 on iOS?")
-# => "supports_ipv6_on_ios"
+Strings::Case.snakecase("FooBarBaz")
+# => "foo_bar_baz"
 ```
 
-You can apply case transformations to Unicode characters:
+Case conversion methods will transform any string into an expected case:
 
 ```ruby
-Strings::Case.snakecase("ЗдравствуйтеПривет")
+strings.snakecase("supports IPv6 on iOS?")
+# => "supports_i_pv6_on_i_os"
+```
+
+The methods also support converting Unicode characters:
+
+```ruby
+strings.snakecase("ЗдравствуйтеПривет")
 # => "здравствуйте_привет"
 ```
 
-Here is a quick summary of available transformations:
+To preserve acronyms for all case conversions, configure them once
+on an instance:
+
+```ruby
+strings.configure do |config|
+  config.acronym "IPv6"
+  config.acronym "iOS"
+end
+```
+
+This will preserve acronyms for any case conversion method:
+
+```ruby
+strings.snakecase("supports IPv6 on iOS?")
+# => "supports_ipv6_on_ios"
+```
+
+Or, use the `acronyms` keyword in a case conversion method:
+
+```ruby
+strings.snakecase("supports IPv6 on iOS?", acronyms: %w[IPv6 iOS])
+# => "supports_ipv6_on_ios"
+```
 
-| Case Type | Result |
-| --------- | ------- |
-| ```Strings::Case.camelcase("foo bar baz")``` | `"fooBarBaz"` |
-| ```Strings::Case.constcase("foo bar baz")``` | `"FOO_BAR_BAZ"` |
-| ```Strings::Case.headercase("foo bar baz")``` | `"Foo-Bar-Baz"` |
-| ```Strings::Case.kebabcase("foo bar baz")``` | `"foo-bar-baz"` |
-| ```Strings::Case.pascalcase("foo bar baz")``` | `"FooBarBaz"` |
-| ```Strings::Case.pathcase("foo bar baz")``` | `"foo/bar/baz"` |
-| ```Strings::Case.sentencecase("foo bar baz")``` | `"Foo bar baz"` |
-| ```Strings::Case.snakecase("foo bar baz")``` | `"foo_bar_baz"` |
-| ```Strings::Case.titlecase("foo bar baz")``` | `"Foo Bar Baz"` |
+Here is a quick summary of available case conversions:
+
+| Case Type                     | Result          |
+| ----------------------------- | --------------- |
+| `camelcase("foo bar baz")`    | `"fooBarBaz"`   |
+| `constcase("foo bar baz")`    | `"FOO_BAR_BAZ"` |
+| `headercase("foo bar baz")`   | `"Foo-Bar-Baz"` |
+| `kebabcase("foo bar baz")`    | `"foo-bar-baz"` |
+| `pascalcase("foo bar baz")`   | `"FooBarBaz"`   |
+| `pathcase("foo bar baz")`     | `"foo/bar/baz"` |
+| `sentencecase("foo bar baz")` | `"Foo bar baz"` |
+| `snakecase("foo bar baz")`    | `"foo_bar_baz"` |
+| `titlecase("foo bar baz")`    | `"Foo Bar Baz"` |
 
 ## 2. API
 
-### 2.1 camelcase
+### 2.1 configure
+
+Use the `acronyms` keyword at initialization to add acronyms for all
+case conversions.
 
-To convert a string into a camel case, that is, a case with all the words capitilized apart from the first one and compouned together without any space use `camelase` method. For example:
+For example, to add `HTTP` and `XML` acronyms:
 
 ```ruby
-Strings::Case.camelcase("HTTP Response Code")
-# => "httpResponseCode"
+strings = Strings::Case.new(acronyms: %w[HTTP XML])
 ```
 
-To preserve the acronyms use the `:acronyms` option:
+After initialization, use the `configure` method to add acronyms
+in a block with the `acronym` method:
 
 ```ruby
-Strings::Case.camelcase("HTTP Response Code", acronyms: ["HTTP"])
-# => "HTTPResponseCode"
+strings.configure do |config|
+  config.acronym "HTTP"
+  config.acronym "XML"
+
+  # or config.acronym "HTTP", "XML"
+end
 ```
 
-### 2.2 constcase
+Or, use the `configure` method with the `acronyms` keyword:
 
-To convert a string into a constant case, that is, a case with all the words uppercased and separated by underscore character use `constcase`. For example:
+```ruby
+strings.configure(acronyms: %w[HTTP XML])
+```
+
+This will result in a conversion preserving acronyms:
 
 ```ruby
-Strings::Case.constcase("HTTP Response Code")
-# => "HTTP_RESPONSE_CODE"
+strings.camelcase("xml_http_request")
+# => "XMLHTTPRequest"
 ```
 
-### 2.3 headercase
+### 2.2 camelcase
 
-To covert a string into a header case, that is, a case with all the words capitalized and separated by a hypen use `headercase`. For example:
+Use the `camelcase` method to convert a string into a camel case. It will
+lowercase first and capitalise all remaining words, joining them by
+removing any space. For example:
 
 ```ruby
-Strings::Case.headercase("HTTP Response Code")
-# => "Http-Response-Code"
+strings.camelcase("PostgreSQL adapter")
+# => "postgreSqlAdapter"
 ```
 
-To preserve the acronyms use the `:acronyms` option:
+Use the `acronyms` keyword to preserve acronyms:
 
 ```ruby
-Strings::Case.headercase("HTTP Response Code", acronyms: ["HTTP"])
-# => "HTTP-Response-Code"
+strings.camelcase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "PostgreSQLAdapter"
 ```
-### 2.4 kebabcase | dashcase
 
-To convert a string into a kebab case, that is, a case with all the words lowercased and separted by a dash, like a words kebabab on a skewer, use `kebabcase` or `dashcase` methods. For example:
+### 2.3 constcase
+
+Use the `constcase` method to convert a string into a constant case. It will
+uppercase all words and separate them with an underscore `_`. For example:
 
 ```ruby
-Strings::Case.kebabcase("HTTP Response Code")
-# => "http-response-code"
+strings.constcase("PostgreSQL adapter")
+# => "POSTGRE_SQL_ADAPTER"
 ```
 
-To preserve the acronyms use the `:acronyms` option:
+Use the `acronyms` keyword to preserve acronyms:
 
 ```ruby
-Strings::Case.dashcase("HTTP Response Code", acronyms: ["HTTP"])
+strings.constcase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "POSTGRESQL_ADAPTER"
+```
 
-expect(dashed).to eq("HTTP-response-code")
+### 2.4 headercase
+
+Use the `headercase` method to convert a string into a header case. It will
+capitalise all words and separate them with a hyphen `-`. For example:
+
+```ruby
+strings.headercase("PostgreSQL adapter")
+# => "Postgre-Sql-Adapter"
 ```
 
-### 2.5 pascalcase
+Use the `acronyms` keyword to preserve acronyms:
 
-To convert a string into a pascal case, that is, a case with all the words capitilized and compounded together without a space, use `pascalcase` method. For example:
+```ruby
+strings.headercase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "PostgreSQL-Adapter"
+```
+
+### 2.5 kebabcase | dashcase
+
+Use the `kebabcase` or `dashcase` method to convert a string into a kebab case.
+It will lowercase all words and separate them with a dash `-` like a words
+kebab on a skewer. For example:
 
 ```ruby
-Strings::Case.pascalcase("HTTP Response Code")
-# => "HttpResponseCode"
+strings.kebabcase("PostgreSQL adapter")
+# => "postgre-sql-adapter"
 ```
 
-To preserve the acronyms use the `:acronyms` option:
+Use the `acronyms` keyword to preserve acronyms:
 
 ```ruby
-Strings::Case.pascalcase("HTTP Response Code")
-# => "HTTPResponseCode"
+strings.dashcase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "postgresql-adapter"
 ```
 
-### 2.6 pathcase
+### 2.6 pascalcase
 
-To convert a string into a file path use `pathcase`:
+Use the `pascalcase` method to convert a string into a Pascal case. It will
+capitalise all words and join them by removing any space. For example:
 
 ```ruby
-Strings::Case.pathcase("HTTP Response Code")
-# => "http/response/code"
-````
+strings.pascalcase("PostgreSQL adapter")
+# => "PostgreSqlAdapter"
+```
 
-To preserve the acronyms use the `:acronyms` option:
+Use the `acronyms` keyword to preserve acronyms:
 
 ```ruby
-Strings::Case.pathcase("HTTP Response Code", acronyms: ["HTTP"])
-# => "HTTP/response/code"
+strings.pascalcase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "PostgreSQLAdapter"
 ```
 
-By default the `/` is used as a path separator. To change this use a `:sep` option. For example, on Windows the file path separator is `\`:
+### 2.7 pathcase
+
+Use the `pathcase` to convert a string into a path case. It will lowercase
+all words and join them with a forward slash `/`. For example:
 
 ```ruby
-Strings::Case.pathcase("HTTP Response Code", separator: "\\")
-# => "http\response\code"
+strings.pathcase("PostgreSQL adapter")
+# => "postgre/sql/adapter"
 ```
 
-### 2.7 `sentencecase`
+Use the `acronyms` keyword to preserve acronyms:
 
-To turn a string into a sentence use `sentencecase`:
+```ruby
+strings.pathcase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "postgresql/adapter"
+```
+
+Use the `separator` keyword to change the default forward slash `/` path
+separator. For example, to use backslash `\` as a path separator:
 
 ```ruby
-Strings::Case.sentencecase("HTTP Response Code")
-# => "Http response code"
+strings.pathcase("PostgreSQL adapter", separator: "\\")
+# => "postgre\\sql\\adapter"
 ```
 
-To preserve the `HTTP` acronym use the `:acronyms` option:
+### 2.8 sentencecase
+
+Use the `sentencecase` to convert a string into a sentence case. It will
+capitalise first and lowercase all remaining words, separating them with
+space. For example:
 
 ```ruby
-Strings::Case.sentencecase("HTTP Response Code", acronyms: ["HTTP"])
-# => "HTTP response code"
+strings.sentencecase("PostgreSQL adapter")
+# => "Postgre sql adapter"
 ```
 
-### 2.8 `snakecase` | `underscore`
+Use the `acronyms` keyword to preserve acronyms:
 
-To convert a string into a snake case by lowercasing all the characters and separating them with an `_` use `snakecase` or `underscore` methods. For example:
+```ruby
+strings.sentencecase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "PostgreSQL adapter"
+```
+
+### 2.9 snakecase | underscore
+
+Use the `snakecase` or `underscore` method to convert a string into
+a snake case. It will lowercase all words and separate them with
+an underscore `_`. For example:
 
 ```ruby
-Strings::Case.snakecase("HTTP Response Code")
-# => "http_response_code"
+strings.snakecase("PostgreSQL adapter")
+# => "postgre_sql_adapter"
 ```
 
-To preserve acronyms in your string use the `:acronyms` option. For example:
+Use the `acronyms` keyword to preserve acronyms:
 
 ```ruby
-Strings::Case.snakecase("HTTP Response Code", acronyms: ["HTTP"])
-# => "HTTP_response_code"
+strings.underscore("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "postgresql_adapter"
 ```
 
-### 2.9 `titlecase`
+### 2.10 titlecase
 
-To convert a string into a space delimited words that have their first letter capitalized use `titlecase`. For example:
+Use `titlecase` to convert a string into a title case. It will capitalise all
+words and separate them with space. For example:
 
 ```ruby
-Strings::Case.titlecase("HTTPResponseCode")
-# => "Http Response Code"
+strings.titlecase("PostgreSQL adapter")
+# => "Postgre Sql Adapter"
 ```
 
-To preserve the `HTTP` acronym use the `:acronyms` option:
+Use the `acronyms` keyword to preserve acronyms:
 
 ```ruby
-Strings::Case.titlecase("HTTP response code", acronyms: ["HTTP"])
-# => "HTTP Response Code"
+strings.titlecase("PostgreSQL adapter", acronyms: ["PostgreSQL"])
+# => "PostgreSQL Adapter"
 ```
 
 ## 3. Extending String class
 
-Though it is highly discouraged to pollute core Ruby classes, you can add the required methods to `String` class by using refinements.
+Polluting core Ruby classes globally may have unintended consequences.
+Instead, consider adding the required methods to the `String` class
+using refinements.
 
-For example, if you wish to only extend strings with `snakecase` method do:
+For example, to extend the `String` class with only the `snakecase` method:
 
 ```ruby
 module MyStringExt
@@ -277,7 +356,8 @@ module MyStringExt
 end
 ```
 
-Then `snakecase` method will be available for any strings where refinement is applied:
+Then using refinement will make the `snakecase` method available
+for any string:
 
 ```ruby
 using MyStringExt
@@ -286,31 +366,51 @@ using MyStringExt
 # => "foo_bar_baz"
 ```
 
-However, if you want to include all the **Strings::Case** methods, you can use provided extensions file:
+Load `Strings::Case::Extensions` refinement to extend the `String` class
+with all case conversion methods:
 
 ```ruby
 require "strings/case/extensions"
 
 using Strings::Case::Extensions
+
+"foo bar baz".camelcase
+# => "fooBarBaz"
+
+"foo bar baz".snakecase
+# => "foo_bar_baz"
 ```
 
 ## 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.
+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](https://rubygems.org).
+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](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/strings-case. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/piotrmurach/strings-case. This project is intended to be
+a safe, welcoming space for collaboration, and contributors are expected
+to adhere to the [Contributor Covenant](http://contributor-covenant.org)
+code of conduct.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the Strings::Case project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/strings-case/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Strings::Case project’s codebases, issue trackers,
+chat rooms and mailing lists is expected to follow the
+[code of conduct](https://github.com/piotrmurach/strings-case/blob/master/CODE_OF_CONDUCT.md).
 
 ## Copyright