dm_ruby_extensions 1.0.9 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: faf35d14eb0e9a4fd037b1e3b3aed616141a0cb4
-  data.tar.gz: 3419c2d7b07edcc1dcf0c5c5a3bcd0abb1d6a4c7
+SHA256:
+  metadata.gz: 36e22b14857c9ce862d6610260ebf28c314982649a0a69e6e04cf37bd74fad25
+  data.tar.gz: 1002cd447ad89971c298c3eeb3f21069302491667781546c82de05b28beb3521
 SHA512:
-  metadata.gz: ff6026e4c21a2adc2238854c7ac1623bd6d8931ff9ecbab07bb7b4b535b28885bca80f568b1d2445f313c3ec29a3a46cce147f85143db802b274f0b02eddd54c
-  data.tar.gz: b2ff730e615af076f516718e68ad5f6f2a08467f327146c7b446c6e76c99be09b7652c79162c13df645463d735bcddf070727d115aa6f71ca3984beca6f6f230
+  metadata.gz: 60992cd05bf21a44458666b8bdd8d6e6e91360c53f259f930421b05ed1701b0e9f6b028c28842793007be1312e9c28a6036de6b5484ccae3a967b0a692b311bf
+  data.tar.gz: 52bf4954ecfcd7a36f1efb02a4b5fd72e671242ce5df1c95ae96b2150915b3b61abfbd4aec5fc53df9af512ec80d4a031b6c4d6cb90168590f6dfba5c8c6886f

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.6.0
+
+- Support Ruby 4.0: `required_ruby_version` is now `>= 3.2` (was `~> 3.0`, which
+  excluded Ruby 4).
+- Drop support for Ruby 3.0 and 3.1, which have reached end of life.
+- Limit ActiveSupport to `>= 6.0, < 9`.
+- Gemspec: package files with `Dir` instead of `git ls-files`, remove the
+  deprecated `test_files`, require MFA for publishing, and add source, changelog
+  and bug tracker links.
+- Replace the Travis build, which no longer ran, with GitHub Actions on Ruby 3.2
+  through 4.0.
+- Update RuboCop to 1.92 and rubocop-rspec to 3.10.
+- Fix a spec for `nil + other` that didn't actually test it.
+
+## 1.5.0
+
+- Drop support for Ruby 2.

data/README.md

@@ -1,92 +1,146 @@
 # DmRubyExtensions
 
 [![Gem Version](https://badge.fury.io/rb/dm_ruby_extensions.svg)](http://badge.fury.io/rb/dm_ruby_extensions)
-[![Build Status](https://travis-ci.com/digitalmoksha/dm_ruby_extensions.svg?branch=master)](https://travis-ci.com/digitalmoksha/dm_ruby_extensions)
+[![Build status](https://github.com/digitalmoksha/dm_ruby_extensions/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/digitalmoksha/dm_ruby_extensions/actions/workflows/ci.yml)
 
-Adds some simple convienence methods to some Ruby classes, for use in the digitalMoksha gems.  Although some of these can be found in other libraries, this includes a small handful and removes the dependency on another large library.
+A small set of convenience methods added to Ruby's core classes (`String`, `Hash`,
+`Array`, `Date` and others). It's used by the digitalMoksha gems, such as
+[moksha_cms](https://gitlab.com/moksha_cms/moksha_cms), for formatting names and
+titles, building CSS and URLs, reading Rails date params, and similar everyday jobs.
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'dm_ruby_extensions'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install dm_ruby_extensions
-
-## Usage
-
-#### Array
-
-* extract_options!
-* closest_max
-* xss_aware_join
-* css_join
-
-#### Date
-
-* to_age
-* localize
+## Requirements
 
-#### DateTime
+- Ruby 3.2 or later (CI covers 3.2 through 4.0)
+- ActiveSupport 6.0 or later
 
-* to_age
-* localize
+Requiring the gem also loads `active_support/core_ext`. The `localize` methods use
+`I18n`, which comes with ActiveSupport.
 
-#### Fixnum
-
-* factorial
-* as_boolean
-
-#### Hash
-
-* convert_date
-* convert_datetime
-* url_query_string
-* rekey
-* rekey!
-
-#### Nil
-
-* to_s_default
-* as_boolean
-* to_age
-* sql_wildcard
-
-#### Numeric
-
-* percent_of
-
-#### String
-
-* to_s_default
-* as_boolean
-* as_css_size
-* sql_wildcard
-* replace_non_alphanumeric
-* expand_url
-* absolute_url?
-* smart_titlecase
-* smart_capitalize
-* smart_capitalize!
-* smart_truncate
-* name_case
-* name_case!
+## Installation
 
-#### Time
+Add it to your Gemfile:
+
+```ruby
+gem 'dm_ruby_extensions'
+```
+
+and run `bundle install`. In a Rails app it's loaded by Bundler; elsewhere, add
+`require 'dm_ruby_extensions'`.
+
+## What it adds
+
+### String
+
+| Method | Description |
+|---|---|
+| `to_s_default(default = 'n/a')` | The string, or `default` if it's empty or only whitespace |
+| `as_boolean` | `true` for `'true'`, `'yes'` or `'1'`, otherwise `false` |
+| `as_css_size` | Adds `px` unless the value already has `px`, `%` or `em`, or is `auto`/`inherit` |
+| `sql_wildcard` | Wraps the string in `%` for a SQL `LIKE` |
+| `replace_non_alphanumeric(replacement = '')` | Replaces everything except letters, digits, `_`, `.` and `-` |
+| `sanitize_filename` | Strips any path (Unix or Windows) and replaces unsafe characters with `_` |
+| `expand_url(path = '')` | Prefixes a relative URL with `path`; absolute URLs are returned unchanged |
+| `absolute_url?` | `true` if the string contains `://` or starts with `/` |
+| `smart_titlecase` | Title case that keeps small words lowercase (Ruby port of John Gruber's TitleCase) |
+| `smart_capitalize` / `smart_capitalize!` | Capitalizes the first real letter, leaving words like `iPhone` alone |
+| `smart_truncate(words: 12)` / `smart_truncate(sentences: n)` | Truncates by words or sentences and appends `...` |
+| `name_case` / `name_case!` | Properly cases names, e.g. `McDonald`, `O'Brien` (port of Lingua::EN::NameCase) |
+
+```ruby
+'300'.as_css_size                            #=> "300px"
+'images/logo.png'.expand_url('/assets')      #=> "/assets/images/logo.png"
+'C:\docs\my report.pdf'.sanitize_filename    #=> "my_report.pdf"
+'the lord of the rings'.smart_titlecase      #=> "The Lord of the Rings"
+'one two three four five'.smart_truncate(words: 3)  #=> "one two three..."
+'MCDONALD'.name_case                         #=> "McDonald"
+```
+
+### Hash
+
+| Method | Description |
+|---|---|
+| `convert_date(attribute)` | Builds a `Date` from Rails date-select params (`attr(1i)`–`attr(3i)`), or `nil` |
+| `convert_datetime(attribute)` | Builds a local `Time` from Rails datetime-select params (`attr(1i)`–`attr(5i)`), or `nil` |
+| `url_query_string(leading_slash = true)` | Turns the hash into a query string, e.g. `"/?page=2&q=yoga"` |
+| `rekey` / `rekey!` | Renames keys with a key map or a block; with neither, symbolizes all keys (from [Facets](https://github.com/rubyworks/facets)) |
+
+```ruby
+params = { 'start_date(1i)' => '2026', 'start_date(2i)' => '11', 'start_date(3i)' => '8' }
+params.convert_date(:start_date)   #=> Sun, 08 Nov 2026
+{ page: 2, q: 'yoga' }.url_query_string   #=> "/?page=2&q=yoga"
+{ a: 1, b: 2 }.rekey(a: 'x')       # 'x' => 1, :b => 2
+```
+
+### Array
+
+| Method | Description |
+|---|---|
+| `extract_options!` | Removes and returns a trailing options hash, or `{}` |
+| `closest_max(value)` | The largest element that is less than or equal to `value` |
+| `xss_aware_join(delimiter = '')` | Joins into an `html_safe` string, escaping elements that aren't already safe |
+| `css_join` | Joins CSS class names, skipping `nil` and empty strings; returns `nil` if nothing is left, so Rails leaves the attribute out |
+
+```ruby
+[0, 5, 7, 8, 11, 16].closest_max(6)          #=> 5
+['btn', nil, '', 'btn-primary'].css_join     #=> "btn btn-primary"
+[nil, ''].css_join                           #=> nil
+```
+
+### Date, DateTime and Time
+
+| Method | Description |
+|---|---|
+| `Date#to_age`, `DateTime#to_age` | Age in whole years, e.g. from a birth date |
+| `Date#to_index`, `DateTime#to_index` | A sortable integer for the day: day of year + (year − 2000) × 1000 |
+| `localize(options = {})` | `I18n.localize(self, ...)`; a string argument is taken as the `format` |
+
+### Numbers and booleans
+
+| Method | Description |
+|---|---|
+| `Integer#factorial` | `5.factorial #=> 120` |
+| `Integer#as_boolean` | `true` for positive numbers, otherwise `false` |
+| `Numeric#percent_of(total, precision = 0)` | `25.percent_of(80) #=> 31`; returns `0` when `total` is zero |
+| `TrueClass#as_boolean`, `FalseClass#as_boolean` | Return themselves, so `as_boolean` works on any of these values |
+
+### nil
+
+`nil` gets the same helpers, so you don't have to check for it first:
+
+| Method | Returns |
+|---|---|
+| `to_s_default(default = 'n/a')` | `default` |
+| `as_boolean` | `false` |
+| `to_age` | `0` |
+| `sql_wildcard` | `'%'` (matches everything) |
+| `utc` | `''` |
+| `+(other)` | `other`, so `nil + 5 #=> 5` |
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+CI runs the specs on Ruby 3.2 through 4.0 (plus ruby-head) on Linux and macOS, and
+runs RuboCop, for every pull request and push to `master`.
+
+To release a new version, update `lib/dm_ruby_extensions/version.rb` and
+`CHANGELOG.md`, then:
+
+```
+gem build dm_ruby_extensions.gemspec
+gem push dm_ruby_extensions-<version>.gem
+```
 
-* localize
+## Contributing
 
+Bug reports and pull requests are welcome at
+<https://github.com/digitalmoksha/dm_ruby_extensions>. Please include specs for any
+change.
 
-## Contributing
+## License
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+MIT. See [LICENSE](LICENSE).

data/lib/dm_ruby_extensions/extend_array.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 #------------------------------------------------------------------------------
 class Array
-
-  # Extract options from a set of arguments. Removes and returns the last element in the array if it's a hash, otherwise returns a blank hash.
+  # Extract options from a set of arguments. Removes and returns the last element
+  # in the array if it's a hash, otherwise returns a blank hash.
   #
   #   def options(*args)
   #     args.extract_options!
@@ -19,7 +21,7 @@ class Array
   # [0,5,7,8,11,16].closest_max(7) => 7
   #------------------------------------------------------------------------------
   def closest_max(value)
-    self.select{|item| item <= value}.max
+    self.select { |item| item <= value }.max
   end
 
   # able to join safe and unsafe strings
@@ -27,7 +29,7 @@ class Array
   def xss_aware_join(delimiter = '')
     ''.html_safe.tap do |str|
       each_with_index do |element, i|
-        str << delimiter if i > 0
+        str << delimiter if i.positive?
         str << element
       end
     end
@@ -38,8 +40,8 @@ class Array
   # is an empty string (rails tag methods will not include the
   # attribute if it is nil, which is desirable for cleaner html)
   #------------------------------------------------------------------------------
-  def css_join(delimiter = '')
-    str = self.flatten.delete_if {|x| x.nil? || x == ''}.join(' ')
+  def css_join(_delimiter = '')
+    str = flatten.delete_if { |x| x.nil? || x == '' }.join(' ')
     str == '' ? nil : str
   end
 end

data/lib/dm_ruby_extensions/extend_date.rb

@@ -1,23 +1,22 @@
-class Date
+# frozen_string_literal: true
 
+class Date
   # http://stackoverflow.com/questions/819263/get-persons-age-in-ruby
   #------------------------------------------------------------------------------
   def to_age
     now = Time.now.utc.to_date
-    now.year - self.year - ((now.month > self.month || (now.month == self.month && now.day >= self.day)) ? 0 : 1)
+    now.year - year - (now.month > month || (now.month == month && now.day >= day) ? 0 : 1)
   end
-  
+
   #------------------------------------------------------------------------------
   def localize(options = {})
-    options = {:format => options} if options.class == String      
-    I18n.localize(self, options)
+    options = { format: options } if options.instance_of?(String)
+    I18n.localize(self, **options)
   end
 
   # Create a unique sortable index for this date
   #------------------------------------------------------------------------------
   def to_index
-    yday + (year-2000) * 1000
+    yday + ((year - 2000) * 1000)
   end
-
 end
-

data/lib/dm_ruby_extensions/extend_datetime.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
+
 #------------------------------------------------------------------------------
 class DateTime
-
   #------------------------------------------------------------------------------
   def to_age
     (DateTime.now - self).to_i / 365
@@ -8,15 +9,13 @@ class DateTime
 
   #------------------------------------------------------------------------------
   def localize(options = {})
-    options = {:format => options} if options.class == String      
-    I18n.localize(self, options)
+    options = { format: options } if options.instance_of?(String)
+    I18n.localize(self, **options)
   end
-  
+
   # Create a unique sortable index for this date
   #------------------------------------------------------------------------------
   def to_index
-    yday + (year-2000) * 1000
+    yday + ((year - 2000) * 1000)
   end
-
 end
-

data/lib/dm_ruby_extensions/extend_false.rb

@@ -1,8 +1,7 @@
-class FalseClass  #:nodoc:
+# frozen_string_literal: true
 
+class FalseClass # :nodoc:
   def as_boolean
     false
   end
-
 end
-

data/lib/dm_ruby_extensions/extend_hash.rb

@@ -1,29 +1,37 @@
+# frozen_string_literal: true
+
 #------------------------------------------------------------------------------
 class Hash
-  
-  # takes a Hash (like the params hash), and converts the Rails date attributes 
+  # takes a Hash (like the params hash), and converts the Rails date attributes
   # to a real Date object.
-  # {'start_date(1i)' => 2012, 'start_date(2i)' => 11, 'start_date(3i)' => 23}.convert_date(:start_date)   
+  # {'start_date(1i)' => 2012, 'start_date(2i)' => 11, 'start_date(3i)' => 23}.convert_date(:start_date)
   #------------------------------------------------------------------------------
   def convert_date(date_symbol_or_string)
     attribute = date_symbol_or_string.to_s
-    return nil if self[attribute + '(1i)'].nil? || self[attribute + '(2i)'].nil? || self[attribute + '(3i)'].nil? 
-    return Date.new(self[attribute + '(1i)'].to_i, self[attribute + '(2i)'].to_i, self[attribute + '(3i)'].to_i)   
+    return nil if self["#{attribute}(1i)"].nil? || self["#{attribute}(2i)"].nil? || self["#{attribute}(3i)"].nil?
+
+    Date.new(self["#{attribute}(1i)"].to_i, self["#{attribute}(2i)"].to_i, self["#{attribute}(3i)"].to_i)
   end
 
-  # takes a Hash (like the params hash), and converts the Rails datetime attributes 
+  # takes a Hash (like the params hash), and converts the Rails datetime attributes
   # to a real Date object.
   #------------------------------------------------------------------------------
   def convert_datetime(date_symbol_or_string)
     attribute = date_symbol_or_string.to_s
-    return nil if self[attribute + '(1i)'].nil? || self[attribute + '(2i)'].nil? || self[attribute + '(3i)'].nil? || self[attribute + '(4i)'].nil? || self[attribute + '(5i)'].nil? 
-    return Time.local(self[attribute + '(1i)'].to_i, self[attribute + '(2i)'].to_i, self[attribute + '(3i)'].to_i, self[attribute + '(4i)'].to_i, self[attribute + '(5i)'].to_i)   
+    if self["#{attribute}(1i)"].nil? || self["#{attribute}(2i)"].nil? ||
+       self["#{attribute}(3i)"].nil? || self["#{attribute}(4i)"].nil? ||
+       self["#{attribute}(5i)"].nil?
+      return nil
+    end
+
+    Time.local(self["#{attribute}(1i)"].to_i, self["#{attribute}(2i)"].to_i, self["#{attribute}(3i)"].to_i,
+               self["#{attribute}(4i)"].to_i, self["#{attribute}(5i)"].to_i)
   end
 
   # Convert hash of parameters to a query string
   #------------------------------------------------------------------------------
-  def url_query_string(leading_slash = true)
-    (leading_slash ? "/?" : "?") << URI.escape(self.collect{|k,v| "#{k}=#{v}"}.join('&'))
+  def url_query_string(leading_slash = true) # rubocop:disable Style/OptionalBooleanParameter
+    "#{leading_slash ? '/?' : '?'}#{to_query}"
   end
 
   # Borrowed from https://github.com/rubyworks/facets
@@ -42,7 +50,7 @@ class Hash
   #   foo.rekey(:b=>:x)        #=> { :a =>1, :x=>2 }
   #   foo.rekey('foo'=>'bar')  #=> { :a =>1, :b=>2 }
   #
-  # If a block is given, converts all keys in the Hash accroding to the
+  # If a block is given, converts all keys in the Hash according to the
   # given block procedure.
   #
   #   foo = { :name=>'Gavin', :wife=>:Lisa }
@@ -55,37 +63,36 @@ class Hash
   # Raises an ArgumentError if both a +key_map+ and a block are given.
   # If both are needed just call #rekey twice.
   #
-  # TODO: If `nil` is returned by block should the key be set to `nil` or the orignal key?
+  # TODO: If `nil` is returned by block should the key be set to `nil` or the original key?
   #
   # CREDIT: Trans, Gavin Kistner
+  def rekey(key_map = nil, &block)
+    raise ArgumentError, 'argument or block' if key_map && block
 
-  def rekey(key_map=nil, &block)
-    raise ArgumentError, "argument or block" if key_map && block
-
-    if !(key_map or block)
-      block = lambda{|k| k.to_sym}
+    unless key_map || block
+      block = lambda { |k| k.to_sym } # rubocop:disable Style/SymbolProc, Style/Lambda
     end
 
     if block
       hash = dup.clear
       if block.arity.abs == 1
         each_pair do |k, v|
-          hash[block[k]] = v     #hash[block[k] || k] = v
+          hash[block[k]] = v # hash[block[k] || k] = v
         end
       else
         each_pair do |k, v|
-          hash[block[k,v]] = v   #hash[block[k,v] || k] = v
+          hash[block[k, v]] = v # hash[block[k,v] || k] = v
         end
       end
     else
-      #hash = dup.clear  # to keep default_proc
-      #(keys - key_map.keys).each do |key|
-      #  hash[key] = self[key]
-      #end
-      #key_map.each do |from, to|
-      #  hash[to] = self[from] if key?(from)
-      #end
-      hash = dup  # to keep default_proc
+      # hash = dup.clear  # to keep default_proc
+      # (keys - key_map.keys).each do |key|
+      #   hash[key] = self[key]
+      # end
+      # key_map.each do |from, to|
+      #   hash[to] = self[from] if key?(from)
+      # end
+      hash = dup # to keep default_proc
       key_map.each_pair do |from, to|
         hash[to] = hash.delete(from) if hash.key?(from)
       end
@@ -102,8 +109,7 @@ class Hash
   #
   # CREDIT: Trans, Gavin Kistner
 
-  def rekey!(key_map=nil, &block)
-    replace(rekey(key_map, &block))
+  def rekey!(key_map = nil, &)
+    replace(rekey(key_map, &))
   end
-
 end

data/lib/dm_ruby_extensions/extend_integer.rb

@@ -1,16 +1,17 @@
-class Integer
+# frozen_string_literal: true
 
+class Integer
   # Factorial of number
   # 5.factorial == 5 x 4 x 3 x 2 x 1 == 120
   #------------------------------------------------------------------------------
   def factorial
-    return 1 if self.zero?
+    return 1 if zero?
+
     (1..self).inject(:*)
   end
 
   #------------------------------------------------------------------------------
   def as_boolean
-    (self > 0) ? true : false
+    positive?
   end
-
 end

data/lib/dm_ruby_extensions/extend_nil.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
+
 # If nil, then return a default string
 #------------------------------------------------------------------------------
-class NilClass #:nodoc:
-
+class NilClass # :nodoc:
   #------------------------------------------------------------------------------
   def to_s_default(default_str = 'n/a')
     default_str
@@ -11,7 +12,7 @@ class NilClass #:nodoc:
   def as_boolean
     false
   end
-  
+
   #------------------------------------------------------------------------------
   def to_age
     0
@@ -19,18 +20,17 @@ class NilClass #:nodoc:
 
   #------------------------------------------------------------------------------
   def sql_wildcard
-    "%"	  
+    '%'
   end
-  
+
   #------------------------------------------------------------------------------
   def utc
-    ""
+    ''
   end
-  
+
   # if nil + something, just return something
   #------------------------------------------------------------------------------
-  def +(y)
-    y
+  def +(other)
+    other
   end
-
-end
+end

data/lib/dm_ruby_extensions/extend_numeric.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 class Numeric
   #------------------------------------------------------------------------------
-  def percent_of(n, precision = 0)
-    n == 0 ? 0 : (self.to_f / n.to_f * 100.0).round(precision)
+  def percent_of(num, precision = 0)
+    num.zero? ? 0 : (to_f / num * 100.0).round(precision)
   end
 end