japanese_calendar 0.4.1 → 0.4.2

data/README.md

@@ -40,6 +40,16 @@ Time.new(1912,  7, 30).era_name(:romaji) # => "Taisho"
 Time.new(1873,  1,  1).era_name(:romaji) # => "Meiji"
 ```
 
+The following examples show how to check the Japanese era:
+
+```
+Time.new(2019,  5,  1).reiwa?  # => true
+Time.new(1989,  1,  8).heisei? # => true
+Time.new(1926, 12, 25).showa?  # => true
+Time.new(1912,  7, 30).taisho? # => true
+Time.new(1873,  1,  1).meiji?  # => true
+```
+
 You can convert to a Japanese year with the `era_year` method:
 
 ```
@@ -57,6 +67,7 @@ time = Time.new(2019, 5, 1)
 
 # Japanese era
 time.strftime("%JN")  # => "令和"
+time.strftime("%Jn")  # => "令"
 time.strftime("%JR")  # => "Reiwa"
 time.strftime("%^JR") # => "REIWA"
 time.strftime("%Jr")  # => "R"

data/lib/japanese_calendar/core_ext/date.rb

@@ -4,7 +4,7 @@ require 'date'
 require 'japanese_calendar/era'
 require 'japanese_calendar/weekday'
 
-class Date
+class Date #:nodoc:
   prepend JapaneseCalendar::Era
   prepend JapaneseCalendar::Weekday
 end

data/lib/japanese_calendar/core_ext/date_time.rb

@@ -4,7 +4,7 @@ require 'date'
 require 'japanese_calendar/era'
 require 'japanese_calendar/weekday'
 
-class DateTime
+class DateTime #:nodoc:
   prepend JapaneseCalendar::Era
   prepend JapaneseCalendar::Weekday
 end

data/lib/japanese_calendar/core_ext/time.rb

@@ -3,7 +3,7 @@
 require 'japanese_calendar/era'
 require 'japanese_calendar/weekday'
 
-class Time
+class Time #:nodoc:
   prepend JapaneseCalendar::Era
   prepend JapaneseCalendar::Weekday
 end

data/lib/japanese_calendar/deprecation/era_wrapper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'japanese_calendar/deprecation/reporting'
+
+module JapaneseCalendar
+  module Deprecation #:nodoc: all
+    ERA_DIRECTIVES = {
+      '%K' => '%JN',
+      '%O' => '%JR',
+      '%^O' => '%^JR',
+      '%o' => '%Jr',
+      '%J' => '%Jy',
+      '%-J' => '%-Jy',
+      '%_J' => '%_Jy'
+    }.freeze
+
+    ERA_PATTERN = Regexp.union(ERA_DIRECTIVES.keys)
+
+    private_constant :ERA_DIRECTIVES, :ERA_PATTERN
+
+    # Prepend wrapper for Era module
+    module EraWrapper
+      include JapaneseCalendar::Deprecation::Reporting
+
+      def strftime(format)
+        string = super(format)
+        deprecations = collect_era_deprecations(string)
+        deprecations.each { |deprecation| deprecate_directive(*deprecation) }
+        string.gsub(deprecated_era_pattern, deprecated_era_conversion)
+      end
+
+      private
+
+      def collect_era_deprecations(format)
+        deprecated_directives = format.scan(ERA_PATTERN).uniq
+        ERA_DIRECTIVES.select do |directive, _|
+          deprecated_directives.include?(directive)
+        end
+      end
+
+      def deprecated_era_conversion
+        {
+          '%K' => era_kanji_name,
+          '%O' => era_romaji_name,
+          '%^O' => era_romaji_uppercased_name,
+          '%o' => era_romaji_abbreviation,
+          '%J' => era_year_zero_padded_string,
+          '%-J' => era_year_string,
+          '%_J' => era_year_blank_padded_string
+        }
+      end
+
+      def deprecated_era_pattern
+        Regexp.union(deprecated_era_conversion.keys)
+      end
+    end
+  end
+end

data/lib/japanese_calendar/deprecation/reporting.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module JapaneseCalendar
+  module Deprecation
+    module Reporting #:nodoc:
+      private
+
+      def deprecate_directive(directive, replacement)
+        deprecate(directive, "Please use #{replacement} instead.")
+      end
+
+      def deprecate(directive, message)
+        warn "#{directive} is deprecated. #{message}"
+      end
+    end
+  end
+end

data/lib/japanese_calendar/deprecation/weekday_wrapper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'japanese_calendar/deprecation/reporting'
+
+module JapaneseCalendar
+  module Deprecation #:nodoc: all
+    WEEKDAY_DIRECTIVES = {
+      '%Q' => '%JA',
+      '%q' => '%Ja'
+    }.freeze
+
+    WEEKDAY_PATTERN = Regexp.union(WEEKDAY_DIRECTIVES.keys)
+
+    private_constant :WEEKDAY_DIRECTIVES, :WEEKDAY_PATTERN
+
+    # Prepend wrapper for Weekday module
+    module WeekdayWrapper
+      include JapaneseCalendar::Deprecation::Reporting
+
+      def strftime(format)
+        string = super(format)
+        deprecations = collect_weekday_deprecations(string)
+        deprecations.each { |deprecation| deprecate_directive(*deprecation) }
+        string.gsub(deprecated_weekday_pattern, deprecated_weekday_conversion)
+      end
+
+      private
+
+      def collect_weekday_deprecations(format)
+        deprecated_directives = format.scan(WEEKDAY_PATTERN).uniq
+        WEEKDAY_DIRECTIVES.select do |directive, _|
+          deprecated_directives.include?(directive)
+        end
+      end
+
+      def deprecated_weekday_conversion
+        {
+          '%Q' => weekday_name,
+          '%q' => weekday_abbreviation
+        }
+      end
+
+      def deprecated_weekday_pattern
+        Regexp.union(deprecated_weekday_conversion.keys)
+      end
+    end
+  end
+end

data/lib/japanese_calendar/era.rb

@@ -1,30 +1,35 @@
 # frozen_string_literal: true
 
-require 'japanese_calendar/era/deprecator'
+require 'japanese_calendar/deprecation/era_wrapper'
+require 'japanese_calendar/era/calculations'
+require 'japanese_calendar/era/reflection'
 
 module JapaneseCalendar
+  # Era extensions to <tt>Date</tt>, <tt>DateTime</tt> and
+  # <tt>Time</tt>.
   module Era
-    prepend Era::Deprecator
+    include Era::Calculations
+    include Era::Reflection
+    prepend Deprecation::EraWrapper
 
-    Period = Struct.new(:beginning_of_period, :kanji_name, :romaji_name)
-
-    MEIJI_6 = Date.new(1873, 1, 1)
-
-    PERIODS = [
-      Period.new(Date.new(2019,  5,  1), '令和', 'Reiwa').freeze,
-      Period.new(Date.new(1989,  1,  8), '平成', 'Heisei').freeze,
-      Period.new(Date.new(1926, 12, 25), '昭和', 'Showa').freeze,
-      Period.new(Date.new(1912,  7, 30), '大正', 'Taisho').freeze,
-      Period.new(Date.new(1868,  1, 25), '明治', 'Meiji').freeze
-    ].freeze
-
-    private_constant :Period, :MEIJI_6, :PERIODS
-
-    # Formats time according to the directives in the given format string.
+    # Formats the year of the Japanese era according to the directives in the
+    # given format string.
+    #
+    # Format directives:
+    #   %JN - The full Japanese era name in Kanji ("令和")
+    #   %Jn - The abbreviated Japanese era name in Kanji ("令")
+    #   %JR - The full Japanese era name in Romaji ("Reiwa")
+    #           %^JR  uppercased ("REIWA")
+    #   %Jr - The abbreviated Japanese era name in Romaji ("R")
+    #   %Jy - year of the Japanese era, zero-padded (01)
+    #           %_Jy  blank-padded ( 1)
+    #           %-Jy  no-padded (1)
     #
+    # Examples:
     #   date_of_birth = Time.new(1978, 7, 19)
     #
     #   date_of_birth.strftime("%JN")  # => "昭和"
+    #   date_of_birth.strftime("%Jn")  # => "昭"
     #   date_of_birth.strftime("%JR")  # => "Showa"
     #   date_of_birth.strftime("%^JR") # => "SHOWA"
     #   date_of_birth.strftime("%Jr")  # => "S"
@@ -36,115 +41,29 @@ module JapaneseCalendar
     #
     #   Time.new(1872, 12, 31).strftime("%JN%-Jy年") # => RuntimeError
     def strftime(format)
-      string = format.gsub(era_pattern, era_conversion)
-      super(string)
-    end
-
-    # Returns the Japanese era name (nengo) since 1 January 1873 (Meiji 6).
-    #
-    #   reiwa = Time.new(2019, 5, 1)   # => 2019-05-01 00:00:00 +0900
-    #   reiwa.era_name                 # => "令和"
-    #   reiwa.era_name(:romaji)        # => "Reiwa"
-    #
-    #   heisei = Time.new(1989, 1, 8)  # => 1989-01-08 00:00:00 +0900
-    #   heisei.era_name                # => "平成"
-    #   heisei.era_name(:romaji)       # => "Heisei"
-    #
-    #   showa = Time.new(1926, 12, 25) # => 1926-12-25 00:00:00 +0900
-    #   showa.era_name                 # => "昭和"
-    #   showa.era_name(:romaji)        # => "Showa"
-    #
-    #   taisho = Time.new(1912, 7, 30) # => 1912-07-30 00:00:00 +0900
-    #   taisho.era_name                # => "大正"
-    #   taisho.era_name(:romaji)       # => "Taisho"
-    #
-    #   meiji = Time.new(1873, 1, 1)   # => 1873-01-01 00:00:00 +0900
-    #   meiji.era_name                 # => "明治"
-    #   meiji.era_name(:romaji)        # => "Meiji"
-    #
-    # Raises an error when the Japanese era name cannot be found.
-    #
-    #   Time.new(1872, 12, 31).era_name # => RuntimeError
-    def era_name(character = :kanji)
-      unless %i[kanji romaji].include?(character)
-        raise ArgumentError, 'invalid character'
-      end
-
-      current_era.send("#{character}_name")
-    end
-
-    # Returns the Japanese year since 1 January 1873 (Meiji 6).
-    #
-    #   Time.new(2019,  5,  1).era_year # => 1
-    #   Time.new(2019,  4, 30).era_year # => 31
-    #   Time.new(1989,  1,  7).era_year # => 64
-    #   Time.new(1926, 12, 24).era_year # => 15
-    #   Time.new(1912,  7, 29).era_year # => 45
-    #
-    # Raises an error when the Japanese year cannot be found.
-    #
-    #   Time.new(1872, 12, 31).era_year # => RuntimeError
-    def era_year
-      year - current_era.beginning_of_period.year + 1
+      string = super(format)
+      string.gsub(era_pattern, era_conversion)
     end
 
     private
 
-    def current_era
-      error_proc = proc { raise "#{self.class.name.downcase} out of range" }
-      error_proc.call if self.to_date < MEIJI_6
-      PERIODS.find(error_proc) do |period|
-        period.beginning_of_period <= self.to_date
-      end
-    end
-
-    def era_kanji_name
-      era_name(:kanji)
-    end
-
-    def era_romaji_name
-      era_name(:romaji)
-    end
-
-    def era_romaji_upcase_name
-      era_romaji_name.upcase
-    end
-
-    def era_romaji_abbreviation
-      era_romaji_name[0]
-    end
-
-    def era_year_string
-      '%-d' % era_year
-    end
-
-    def era_year_zero_padded_string
-      '%02d' % era_year
-    end
-
-    def era_year_blank_padded_string
-      '%2d' % era_year
-    end
-
+    # Returns a hash representing the format directives of the Japanese era.
     def era_conversion
       {
         '%JN' => era_kanji_name,
+        '%Jn' => era_kanji_abbreviation,
         '%JR' => era_romaji_name,
-        '%^JR' => era_romaji_upcase_name,
+        '%^JR' => era_romaji_uppercased_name,
         '%Jr' => era_romaji_abbreviation,
         '%Jy' => era_year_zero_padded_string,
         '%-Jy' => era_year_string,
-        '%_Jy' => era_year_blank_padded_string,
-        '%K' => era_kanji_name,
-        '%O' => era_romaji_name,
-        '%^O' => era_romaji_upcase_name,
-        '%o' => era_romaji_abbreviation,
-        '%J' => era_year_zero_padded_string,
-        '%-J' => era_year_string,
-        '%_J' => era_year_blank_padded_string
+        '%_Jy' => era_year_blank_padded_string
       }
     end
 
+    # Returns a Regexp object representing the format directives of
+    # the day of the week
+    # (/%JN|%Jn|%JR|%^JR|%Jr|%Jy|%-Jy|%_Jy/).
     def era_pattern
       Regexp.union(era_conversion.keys)
     end

data/lib/japanese_calendar/era/calculations.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module JapaneseCalendar
+  module Era #:nodoc:
+    Period = Struct.new(:beginning_of_period, :kanji_name, :romaji_name)
+
+    PERIODS = [
+      Period.new(Date.new(2019,  5,  1), '令和', 'Reiwa').freeze,
+      Period.new(Date.new(1989,  1,  8), '平成', 'Heisei').freeze,
+      Period.new(Date.new(1926, 12, 25), '昭和', 'Showa').freeze,
+      Period.new(Date.new(1912,  7, 30), '大正', 'Taisho').freeze,
+      Period.new(Date.new(1868,  1, 25), '明治', 'Meiji').freeze
+    ].freeze
+
+    private_constant :Period, :PERIODS
+
+    # Calculations module.
+    module Calculations
+      MEIJI_6 = Date.new(1873, 1, 1)
+
+      private_constant :MEIJI_6
+
+      # Returns the Japanese era name (nengo) since 1 January 1873 (Meiji 6).
+      #
+      #   reiwa = Time.new(2019, 5, 1)   # => 2019-05-01 00:00:00 +0900
+      #   reiwa.era_name                 # => "令和"
+      #   reiwa.era_name(:romaji)        # => "Reiwa"
+      #
+      #   heisei = Time.new(1989, 1, 8)  # => 1989-01-08 00:00:00 +0900
+      #   heisei.era_name                # => "平成"
+      #   heisei.era_name(:romaji)       # => "Heisei"
+      #
+      #   showa = Time.new(1926, 12, 25) # => 1926-12-25 00:00:00 +0900
+      #   showa.era_name                 # => "昭和"
+      #   showa.era_name(:romaji)        # => "Showa"
+      #
+      #   taisho = Time.new(1912, 7, 30) # => 1912-07-30 00:00:00 +0900
+      #   taisho.era_name                # => "大正"
+      #   taisho.era_name(:romaji)       # => "Taisho"
+      #
+      #   meiji = Time.new(1873, 1, 1)   # => 1873-01-01 00:00:00 +0900
+      #   meiji.era_name                 # => "明治"
+      #   meiji.era_name(:romaji)        # => "Meiji"
+      #
+      # Raises an error when the Japanese era name cannot be found.
+      #
+      #   Time.new(1872, 12, 31).era_name # => RuntimeError
+      def era_name(character = :kanji)
+        unless %i[kanji romaji].include?(character)
+          raise ArgumentError, 'invalid character'
+        end
+
+        current_era.send("#{character}_name")
+      end
+
+      # Returns the year of the Japanese era since 1 January 1873 (Meiji 6).
+      #
+      #   Time.new(2019,  5,  1).era_year # => 1
+      #   Time.new(2019,  4, 30).era_year # => 31
+      #   Time.new(1989,  1,  7).era_year # => 64
+      #   Time.new(1926, 12, 24).era_year # => 15
+      #   Time.new(1912,  7, 29).era_year # => 45
+      #
+      # Raises an error when the year of the Japanese era cannot be found.
+      #
+      #   Time.new(1872, 12, 31).era_year # => RuntimeError
+      def era_year
+        year - current_era.beginning_of_period.year + 1
+      end
+
+      private
+
+      def current_era
+        error_proc = proc { raise "#{self.class.name.downcase} out of range" }
+        error_proc.call if to_date < MEIJI_6
+        PERIODS.find(error_proc) do |period|
+          period.beginning_of_period <= to_date
+        end
+      end
+
+      # Returns a string representing the full name of the Japanese era in
+      # Kanji ("令和").
+      def era_kanji_name
+        era_name(:kanji)
+      end
+
+      # Returns a string representing the abbreviated name of the Japanese era
+      # in Kanji ("令").
+      def era_kanji_abbreviation
+        era_kanji_name[0]
+      end
+
+      # Returns a string representing the full name of the Japanese era in
+      # Romaji ("Reiwa").
+      def era_romaji_name
+        era_name(:romaji)
+      end
+
+      # Returns a string representing the uppercased full name of the Japanese
+      # era in Romaji ("REIWA").
+      def era_romaji_uppercased_name
+        era_romaji_name.upcase
+      end
+
+      # Returns a string representing the abbreviated name of the Japanese era
+      # in Romaji ("R").
+      def era_romaji_abbreviation
+        era_romaji_name[0]
+      end
+
+      # Returns a string representing the year of the Japanese era ("1")
+      def era_year_string
+        format('%-d', era_year)
+      end
+
+      # Returns a string representing the zero-padded year of the Japanese era
+      # ("01").
+      def era_year_zero_padded_string
+        format('%02d', era_year)
+      end
+
+      # Returns a string representing the blank-padded year of the Japanese era
+      # (" 1").
+      def era_year_blank_padded_string
+        format('%2d', era_year)
+      end
+    end
+  end
+end