edtf-humanize 2.3.0 → 2.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d37dd3663889a9bcaa2a00392525eca76c61691705591c6c50f0ee8eacf9d8f
-  data.tar.gz: de92c0782ba2cfa57b62d55a214ede47c8a6fa152cc14b7d38f6bde0c4bfc66b
+  metadata.gz: 1b98fb2e21907b61cc2ff0eb7d0176696b207234485a2d0ecd6bbfb6aef5b1c5
+  data.tar.gz: 25767f922e7197afb6fdb37a91e4f96cc570f3e1c445ee1fd3458331feee7222
 SHA512:
-  metadata.gz: 47f4afa9029965ed3a620067218a4594559717f6eeae2ae42c5fe4ba985c6eae9d6be81fd06a150deabf8997c9d5fb10564d4915c0f725c3e0743c636df407cd
-  data.tar.gz: 3180b6b54cc2b9011cfdef70259a4196721cc6894d0eab0258962020b0918e8bcfa2dc8b6744b6ba6f2f90f3f6a065039f214e39075490700597a70a6f3d372d
+  metadata.gz: e61cc357e93d6c9319fb79e759129e3a5bcdc3191201e22bd7aedf856d03ad46eed49ce8ae3dab5b28e948fc757992de02882d3b97022cd86b7400a21d406fe6
+  data.tar.gz: 8c86aca686a9e629e215c095ea2ed293593c337f6a681bcf8eb300694bdbdbf607f4a1ca734fe9ba739bda542e009035e57787755b50c3c176dbe45355580f1e

data/README.md

@@ -0,0 +1,184 @@
+# edtf-humanize
+
+[![CI](https://github.com/corylown/edtf-humanize/actions/workflows/ci.yml/badge.svg)](https://github.com/corylown/edtf-humanize/actions/workflows/ci.yml)
+
+The EDTF-humanize gem adds a humanize method to EDTF::Decade, EDTF::Century, EDTF::Interval, EDTF::Set, EDTF::Season, EDTF::Unknown, and Date (ISO 8601 compliant) objects. It uses the [edtf-ruby](https://github.com/inukshuk/edtf-ruby) gem for parsing EDTF date strings into Date and EDTF objects.
+
+See the [edtf-ruby project's documentation](https://github.com/inukshuk/edtf-ruby) for details about supported EDTF string formats and other implementation details.
+
+This gem is used in production by Duke University Library's [digital repository](https://gitlab.oit.duke.edu/ddr/ddr-xenon/) to transform date metadata stored as Extended Date Time Format (EDTF) strings into human readable strings for display.
+
+
+## Installation
+
+In a Rails application using Bundler
+
+Add the following to your Gemfile:
+
+```
+gem 'edtf-humanize'
+```
+
+Then run:
+
+```
+> bundle install
+```
+
+To use in other contexts install the gem and require it:
+
+```
+> gem install edtf-humanize
+```
+
+```
+require 'edtf-humanize'
+```
+
+
+## Examples
+
+
+### Date (ISO 8601)
+
+```
+> d = Date.edtf('1975-07-01')
+ => Tue, 01 Jul 1975
+> d.humanize
+ => "July 1, 1975"
+> d = Date.edtf('1981~')
+ => Thu, 01 Jan 1981
+> d.humanize
+ => "circa 1981"
+> d = Date.edtf('198u')
+ => Tue, 01 Jan 1980
+> d.humanize
+ => "198x"
+ ```
+
+### EDTF::Season
+
+```
+> d = Date.edtf('1975-22')
+ => #<EDTF::Season:0x0000000b6dd980 @year=1975, @season=:summer, @qualifier=nil>
+> d.humanize
+ => "summer 1975"
+ ```
+
+### EDTF::Decade
+
+ ```
+> d = Date.edtf('197x')
+ => #<EDTF::Decade:0x0000000b6fe798 @year=1970>
+> d.humanize
+ => "1970s"
+ ```
+
+### EDTF::Century
+
+ ```
+> d = Date.edtf('19xx')
+ => #<EDTF::Century:0x0000000b6fe798 @year=1900>
+> d.humanize
+ => "1900s"
+ ```
+
+### EDTF::Interval
+
+ ```
+> d = Date.edtf('1981/1985')
+ => #<EDTF::Interval:0x0000000ceeab18 @from=Thu, 01 Jan 1981, @to=Tue, 01 Jan 1985>
+> d.humanize
+ => "1981 to 1985"
+ ```
+
+### EDTF::Set
+
+ ```
+> d = Date.edtf('[1888, 1889, 1891]')
+ => #<EDTF::Set:0x0000000cef5450 @dates=#<Set: {Sun, 01 Jan 1888, Tue, 01 Jan 1889, Thu, 01 Jan 1891}>, @choice=true, @later=false, @earlier=false>
+> d.humanize
+ => "1888, 1889 or 1891"
+ ```
+
+### EDTF::Unknown
+
+```
+> d = Date.edtf('uuuu')
+ => #<EDTF::Unknown:0x0000000c04c688 @d=1>
+> d.humanize
+ => "unknown"
+```
+
+## Internationalization
+
+EDTF-humanize supports the use of I18n as well as language specific module overrides for more nuanced control. English, French, German, and Italian are supported.
+
+Examples with current locale `:fr`:
+
+```
+> Date.edtf('1975-24').humanize
+ => "hiver 1975"
+ > Date.edtf('20xx').humanize
+ => "XXIe siècle"
+```
+
+### Setting the locale
+
+`humanize` uses the current `I18n.locale`. Set it globally or for a block:
+
+```ruby
+I18n.locale = :de
+Date.edtf('1975-07-01').humanize # => "1. Juli 1975"
+
+I18n.with_locale(:fr) { Date.edtf('1975-07-01').humanize } # => "1 Juillet 1975"
+```
+
+The supported locales are `:en`, `:fr`, `:de` and `:it`. Setting any other locale raises `I18n::InvalidLocale` unless you provide translations for it (see below).
+
+### Using outside Rails
+
+No extra setup is needed beyond requiring the gem. `require 'edtf-humanize'` adds the gem's locale files to `I18n.load_path`:
+
+```ruby
+require 'edtf-humanize'
+
+I18n.locale = :it
+Date.edtf('1975-22').humanize # => "estate 1975"
+```
+
+Require `edtf-humanize`, not `edtf/humanize`. The latter loads the code without the locale files, so setting a non-English locale raises `I18n::InvalidLocale: :fr is not a valid locale`.
+
+### Customizing terms
+
+All wording comes from the I18n keys in [`config/locales`](config/locales). To change a term, add your own locale file to `I18n.load_path` after requiring the gem; later files take precedence:
+
+```yaml
+# config/locales/my_overrides.en.yml
+en:
+  edtf:
+    terms:
+      approximate_date_prefix_year: "about "
+```
+
+```ruby
+I18n.load_path << 'config/locales/my_overrides.en.yml'
+I18n.reload! # only needed if translations were already used
+
+Date.edtf('1981~').humanize # => "about 1981"
+```
+
+Pull requests to add support for additional languages are welcome. You must add a new language module for the language and include the Default language module. A locales file with translations is also needed. The supporting files for French may be used as a reference for adding support for additional languages.:
+
+```
+edtf-humanize/lib/edtf/humanize.rb
+edtf-humanize/config/locales/fr.edtf.yml
+edtf-humanize/lib/edtf/humanize/language/french.rb
+edtf-humanize/spec/edtf/humanize_fr_spec.rb
+```
+
+## Contributions
+
+Contributions, especially to add support for additional languages are welcome. Tests are expected and written using RSpec. Code style is enforced with Rubocop.
+
+

data/lib/edtf/humanize/language/default/formats.rb

@@ -108,7 +108,9 @@ module Edtf
                   I18n.t('edtf.terms.unspecified_digit_substitute',
                          default: 'x')
                 )
-              display.gsub!(date.year.to_s, year_substitute)
+              # Match the zero-padded year as formatted, not year.to_s, which
+              # mismatches for years 0-999 and negative years ('00XX', '-01XX')
+              display.sub!(date.strftime('%Y'), year_substitute)
             end
             display
           end

data/lib/edtf/humanize/language/default/season.rb

@@ -19,6 +19,21 @@ module Edtf
 
           private
 
+          # EDTF::Season has no precision, so use the year-precision terms
+          # '1999-21~' => circa spring 1999
+          def apply_prefix_if_approximate(date)
+            return '' unless date.approximate?
+
+            I18n.t('edtf.terms.approximate_date_prefix_year', default: 'circa ')
+          end
+
+          # '1999-21~' => printemps 1999 environ
+          def apply_suffix_if_approximate(date)
+            return '' unless date.approximate?
+
+            I18n.t('edtf.terms.approximate_date_suffix_year', default: '')
+          end
+
           def translate_season(season)
             I18n.translate!("date.seasons.#{season}")
           rescue I18n::MissingTranslationData

data/lib/edtf/humanize/language/default/set.rb

@@ -35,7 +35,7 @@ module Edtf
                 "#{apply_if_later(dates, index)}" \
                 "#{apply_prefix_if_approximate(date)}" \
                 "#{date_format(date)}" \
-                "#{apply_suffix_if_approximate(date)}" \
+                "#{apply_suffix_if_approximate(date)}"
             end
           end
 

data/lib/edtf/humanize/language/german.rb

@@ -11,7 +11,8 @@ module Edtf
 
           def humanizer(date)
             "#{(date.year.abs / 100) + 1}." \
-              "#{century_number_suffix}"
+              "#{century_number_suffix}" \
+              "#{century_sign_suffix(date)}"
           end
 
           private

data/lib/edtf/humanize/version.rb

@@ -2,6 +2,6 @@
 
 module Edtf
   module Humanize
-    VERSION = '2.3.0'
+    VERSION = '2.3.2'
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: edtf-humanize
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.3.2
 platform: ruby
 authors:
 - Cory Lown
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -48,16 +47,22 @@ dependencies:
   name: roman
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 description: This gem adds a humanize method to EDTF::Decade, EDTF::Interval, EDTF::Set,
   EDTF::Season, EDTF::Unknown, and Date (ISO 8601 compliant) objects.
 email:
@@ -67,6 +72,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
+- README.md
 - config/locales/de.edtf.yml
 - config/locales/en.edtf.yml
 - config/locales/fr.edtf.yml
@@ -99,8 +105,9 @@ homepage: https://github.com/corylown/edtf-humanize
 licenses:
 - BSD-3-Clause
 metadata:
+  changelog_uri: https://github.com/corylown/edtf-humanize/releases
   rubygems_mfa_required: 'true'
-post_install_message:
+  source_code_uri: https://github.com/corylown/edtf-humanize
 rdoc_options: []
 require_paths:
 - lib
@@ -109,17 +116,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ">="
     - !ruby/object:Gem::Version
       version: '2.4'
-  - - "<"
-    - !ruby/object:Gem::Version
-      version: '4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: This gem adds a humanize method to EDTF dates.
 test_files: []