Home

Awesome

wareki - ruby 和暦ライブラリ

<img src="https://badge.fury.io/rb/wareki.svg" alt="Gem Version" /> <img src="https://travis-ci.org/sugi/wareki.svg?branch=master" alt="Build Status" /> <img src="https://coveralls.io/repos/sugi/wareki/badge.svg?branch=master&service=github" alt="Coverage Status" /> <img src="https://api.codeclimate.com/v1/badges/c9209422700b526d2b45/maintainability" /> Codacy Badge

概要

日本の和暦をサポートするライブラリです。 旧暦は445年から、元号は大化から全て処理できます。 元号はWikipedia、暦は日本暦日原典由来のデータを元にしています。

機能

インストール

Gemfile に以下のようにするか、

gem 'wareki'

もしくは、直接 gem install して下さい。

gem install wareki

使い方の例

ありそうな例

require 'wareki'

d = Date.parse("平成二七年 08月 ２２日")
d.strftime("%F")   # => "2015-08-22"
d.strftime("%JF")  # => "平成二十七年八月二十二日"
d.strftime("%Jf")  # => "平成27年8月22日"

パース

旧暦を含むの日本語の日付文字列パースして、組み込み Date オブジェクトに変換できます。この時、慣例的に使われていたい色々な表記も解釈できます。(標準では Date::ITALY な Date オブジェクトに変換しますが、必要であれば第3引数の start に改暦日を渡せます。)

# 和暦のパース (標準 Date インスタンス)
Date.parse("㍻一〇年 肆月 晦日")       # => #<Date: 1998-04-30 ...
Date.parse("安政七年 弥生")           # => #<Date: 1860-03-22 ...
Date.parse("元仁元年閏七月朔日")       # => #<Date: 1224-08-17 ...
Date.parse("萬延三年 ５月 廿一日")     # => #<Date: 1862-06-18 ...
Date.parse("皇紀二千皕卌年")          # => #<Date: 1580-01-17 ...
Date.parse("正嘉元年 うるう3月 １２日") # => #<Date: 1257-04-27 ...

# Wareki::Date を直接扱う場合
Date.today.to_wareki_date # => Wareki::Date インスタンス
Wareki::Date.parse("正嘉元年 うるう3月 １２日") # => Wareki::Date インスタンス
Wareki::Date.new("明治", 8, 2, 1).to_date   # => 標準 Date インスタンス 1875-02-01

和暦・旧暦へのフォーマット

日本では明治5年まで、グレゴリオ暦でもユリウス歴でもない旧暦が使われていました。これもフォーマット文字列経由で透過的に扱えます。

Date.today.strftime("%JF")              # => "平成二十七年八月二十二日"
Date.civil(1311, 7, 20).strftime("%JF") # => "応長元年閏六月四日"

旧暦の場合の月日 (%Jm, %Jd) と、グレゴリオ暦やユリウス暦での月日 (%m, %d)は違うものを出力します。

d = Date.civil(1860, 4, 7)
dj = d.new_start(Date::JULIAN)
d.strftime                     # => "1860-04-07" (グレゴリオ暦)
dj.strftime                    # => "1860-03-26" (ユリウス暦)
d.strftime("%Jf")              # => "安政7年3月17日" (日本の旧暦)
d.strftime("皇紀%Ji年%Jm月%Jd日") # => "皇紀2520年3月17日" (日本の旧暦で神武天皇即位紀元年)

Rails I18n から使う場合

strftime が拡張されるので、 config/locale/ja.yml にそのままフォーマット文字列が指定できます。例えば

  ja:
    date:
      formats:
        default: "%JF"

の様にすると、 I18n.l (I18n.localize) の出力が標準で和暦日本語になります。 標準は変更せず、特定の箇所で使い分けたい場合は、例えば、

  ja:
    date:
      formats:
        ja_kan: "%JF"

の様に別のフォーマットキーを設定して、以下のように呼び出し時に format に指定します。

  <%= I18n.l Date.today, format: :ja_kan %>

追加フォーマット文字列一覧

通常の strftime のフォーマット文字列に 加えて、 以下が使用できます。これ以外のフォーマット文字列に関しては、そのまま strftime へ引き渡され、プラットフォーム依存で解決されます。

仕様、限界、制限など

参照元データ

作成には以下のデータを参照しました。

ライセンス

The BSD 2-Clause License

作者

Tatsuki Sugiura sugi@nemui.org