query-stream 1.2.2 → 1.5.0

data/lib/query_stream/command.rb

@@ -2,8 +2,6 @@
 
 require 'samovar'
 
-# ================================================================
-# File: lib/query_stream/command.rb
 # ================================================================
 # 責務:
 #   QueryStream の CLI コマンド。--version のみ提供する。
@@ -17,6 +15,7 @@ module QueryStream
 
       options do
         option '--version', 'Print version and exit'
+        option '--help', 'Print this message and exit'
       end
 
       # コマンド実行
@@ -28,12 +27,16 @@ module QueryStream
         end
       end
 
-      private
-
-      def print_usage
-        puts self.class.description
-        puts "Usage: query-stream [options]"
-        puts "  --version  Print version and exit"
+      # 使い方を表示する。
+      #
+      # public かつ `output:` を受ける形にする。Samovar は引数の解析に失敗すると、外から
+      # `error.command.print_usage(output: output)` を呼ぶ。
+      # @param output [IO] 出力先（Samovar からはエラー出力が渡される）
+      def print_usage(output: $stdout)
+        output.puts self.class.description
+        output.puts 'Usage: query-stream [options]'
+        output.puts '  --version  Print version and exit'
+        output.puts '  --help     Print this message and exit'
       end
     end
   end

data/lib/query_stream/configuration.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-require 'logger'
-
-# ================================================================
-# File: lib/query_stream/configuration.rb
 # ================================================================
 # 責務:
 #   QueryStream のグローバル設定を管理する。
-#   data_dir, templates_dir, default_format, logger の4項目。
+#   data_dir, templates_dir, default_format, post_render の4項目。
+#
+# ログ出力の設定は持たない。gem 自身がログを出さないためである
+# （失敗はすべて構造化例外として on_error / on_warning へ渡す）。
 # ================================================================
 
 module QueryStream
@@ -22,14 +21,16 @@ module QueryStream
     # @return [Symbol] スタイル省略時のデフォルト出力形式（:md / :html / :json）
     attr_accessor :default_format
 
-    # @return [Logger] ログ出力先
-    attr_accessor :logger
+    # 1 記法の展開結果を、コンテキスト付きで呼び出し元へ通す後段フィルタ。
+    # gem 自身は用途を規定しない（画像パス解決など呼び出し元固有の後処理を担わせる）。
+    # @return [Proc, nil] (text, context) -> String。String 以外を返した場合は元の展開結果を採用する
+    attr_accessor :post_render
 
     def initialize
       @data_dir       = 'data'
       @templates_dir  = 'templates'
       @default_format = :md
-      @logger         = Logger.new($stdout)
+      @post_render    = nil
     end
   end
 end

data/lib/query_stream/data_resolver.rb

@@ -3,8 +3,6 @@
 require 'yaml'
 require 'json'
 
-# ================================================================
-# File: lib/query_stream/data_resolver.rb
 # ================================================================
 # 責務:
 #   データファイルの探索・単数形/複数形の自動解決を行う。
@@ -77,8 +75,7 @@ module QueryStream
                                       symbolize_names: true)
                 end
 
-      records = [records] if records.is_a?(Hash)
-      records
+      normalize_records(records, file_path)
     rescue Psych::DisallowedClass => e
       raise DataLoadError.new(
         "データファイルに許可されていないクラス/タグが含まれています: #{e.message} (#{file_path})",
@@ -96,6 +93,28 @@ module QueryStream
       )
     end
 
+    # 読み込み結果をレコード配列へ正規化する。
+    #
+    # **常に配列を返す。** 空のデータファイルは YAML が `nil` を返すので、空配列に変換する
+    # （呼び出し先の TemplateCompiler は配列を前提にしている）。
+    #
+    # 配列でもハッシュでもない中身（先頭が文字列や数値だけの YAML）は、
+    # レコード群として解釈しようがないので DataLoadError で理由を伝える。
+    # @return [Array<Hash>]
+    def normalize_records(records, file_path)
+      case records
+      when nil then []
+      when Hash then [records]
+      when Array then records
+      else
+        raise DataLoadError.new(
+          "データファイルはレコードの配列（またはハッシュ 1 件）である必要があります" \
+          "（#{records.class} が入っています）: #{file_path}",
+          file_path: file_path
+        )
+      end
+    end
+
     # 指定名ですべての拡張子を試行する
     # @param base_name [String] 拡張子なしファイル名
     # @param data_dir [String] データディレクトリ

data/lib/query_stream/errors.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/errors.rb
 # ================================================================
 # 責務:
 #   QueryStream の例外クラス体系を定義する。
@@ -51,7 +49,30 @@ module QueryStream
     end
   end
 
-  class UnknownKeyError  < Error; end    # テンプレート内に存在しないキー
+  # テンプレートに、データレコードが持たないキーが書かれている
+  #
+  # 「どのキーが無いか」だけでなく「代わりに何が使えるか」「どのファイルを直すか」まで
+  # 属性で渡す。呼び出し元はこれを使って「もしかして =author?」のような案内を組み立てられる。
+  #
+  # location（記法の位置）と template_path（雛形の位置）は別物である。
+  # 直すのは雛形なので、記法の位置だけでは著者はファイルを開けない。
+  #
+  # @attr_reader key_path [String] テンプレートに書かれていたキー（"author.name" 等）
+  # @attr_reader available_keys [Array<Symbol>] レコードが実際に持つキー
+  # @attr_reader template_path [String, nil] 打ち間違いがあるテンプレートのパス
+  # @attr_reader location [String] 記法が書かれていたソースファイル名と行番号
+  class UnknownKeyError < Error
+    attr_reader :key_path, :available_keys, :template_path, :location
+
+    def initialize(msg = nil, key_path: nil, available_keys: [], template_path: nil, location: nil)
+      super(msg || "テンプレートに存在しないキーが記述されています: #{key_path}")
+      @key_path       = key_path
+      @available_keys = Array(available_keys)
+      @template_path  = template_path
+      @location       = location
+    end
+  end
+
   class InvalidDateError < Error; end    # 無効な日付
 
   # データファイルの読み込みに失敗した

data/lib/query_stream/filter_engine.rb

@@ -2,8 +2,6 @@
 
 require 'date'
 
-# ================================================================
-# File: lib/query_stream/filter_engine.rb
 # ================================================================
 # 責務:
 #   AND/OR/比較/Range によるフィルタリングとソート処理を行う。
@@ -13,6 +11,21 @@ require 'date'
 module QueryStream
   # フィルタリング＆ソートエンジンモジュール
   module FilterEngine
+    # 西暦の日付（2024-01-01）
+    SEIREKI_DATE = /\A\d{4}-\d{2}-\d{2}\z/
+
+    # 和暦の日付（R06-01-01）。元号は頭文字で書く（M 明治・T 大正・S 昭和・H 平成・R 令和）。
+    # 年は 1 桁でもよい（R6-01-01）。
+    WAREKI_DATE = /\A(?<era>[MTSHR])(?<year>\d{1,2})-(?<month>\d{2})-(?<day>\d{2})\z/
+
+    # 大小の条件と、<=> の結果の判定
+    ORDER_TESTS = {
+      gt:  ->(order) { order.positive? },
+      gte: ->(order) { order >= 0 },
+      lt:  ->(order) { order.negative? },
+      lte: ->(order) { order <= 0 }
+    }.freeze
+
     module_function
 
     # フィルタ条件をレコード群に適用する
@@ -27,13 +40,21 @@ module QueryStream
       end
     end
 
-    # ソート条件を適用する
+    # ソート条件を適用する。
+    # 比べるのは最も多い種類の値で、それ以外の値と、値が無いレコードは、向きによらず末尾に置く。
     # @param records [Array<Hash>] レコード群
     # @param sort [Hash] ソート条件 { field:, direction: }
     # @return [Array<Hash>] ソート後のレコード群
     def apply_sort(records, sort)
-      sorted = records.sort_by { to_comparable(it[sort[:field]]) }
-      sort[:direction] == :desc ? sorted.reverse : sorted
+      keyed = records.map do |record|
+        value = record[sort[:field]]
+        [record, missing_value?(value) ? nil : to_comparable(value)]
+      end
+      kind = keyed.filter_map { |_, key| sort_kind(key) }.tally.max_by { |_, count| count }&.first
+
+      sortable, others = keyed.partition { |_, key| sort_kind(key) == kind }
+      sorted = sortable.sort_by(&:last).map(&:first)
+      (sort[:direction] == :desc ? sorted.reverse : sorted) + others.map(&:first)
     end
 
     # 単一フィルタ条件をレコードに対して評価する
@@ -53,22 +74,55 @@ module QueryStream
         match_eq(field_value, filter[:value])
       when :neq
         !match_eq(field_value, filter[:value])
-      when :gt
-        to_comparable(field_value) > to_comparable(filter[:value])
-      when :gte
-        to_comparable(field_value) >= to_comparable(filter[:value])
-      when :lt
-        to_comparable(field_value) < to_comparable(filter[:value])
-      when :lte
-        to_comparable(field_value) <= to_comparable(filter[:value])
+      when :gt, :gte, :lt, :lte
+        satisfies_order?(field_value, filter)
       when :range
-        range = filter[:value]
-        range.cover?(to_comparable(field_value))
+        within_range?(field_value, filter[:value])
+      when :or
+        filter[:branches].any? { |branch| branch.all? { evaluate_filter(record, it) } }
       else
         false
       end
     end
 
+    # 大小の条件を満たすか。値が無いレコードと、比較できない値のレコードは満たさない
+    # @param field_value [Object] レコードの値
+    # @param filter [Hash] フィルタ条件 { op:, value: }
+    # @return [Boolean]
+    def satisfies_order?(field_value, filter)
+      return false if missing_value?(field_value)
+
+      order = to_comparable(field_value) <=> to_comparable(filter[:value])
+      !order.nil? && ORDER_TESTS.fetch(filter[:op]).call(order)
+    end
+
+    # 範囲に含まれるか。両端も比較用にそろえる。パーサーは "2024-06-01".."2024-06-30" のような
+    # 文字列の範囲を返すので、そのままでは Date の値を含まない。
+    # @param field_value [Object] レコードの値
+    # @param range [Range] 範囲
+    # @return [Boolean]
+    def within_range?(field_value, range)
+      Range.new(to_comparable(range.begin), to_comparable(range.end), range.exclude_end?)
+           .cover?(to_comparable(field_value))
+    rescue ArgumentError
+      # 両端を比較できない範囲（Range.new が受け付けない）
+      false
+    end
+
+    # 値が無いか（キーが無い・nil・空文字列）
+    def missing_value?(value) = value.nil? || value == ''
+
+    # ソートで比べられる値の種類。値が無いときは nil
+    def sort_kind(key)
+      case key
+      when nil then nil
+      when Numeric then :number
+      when Date then :date
+      when Time then :time
+      else :string
+      end
+    end
+
     # 主キー候補フィールドを順番に走査して一致するものを探す
     # @param record [Hash] 単一レコード
     # @param query_value [Object] 検索値
@@ -82,13 +136,25 @@ module QueryStream
     # 等値比較（配列・カンマ区切り文字列を透過的に扱う）
     # データ側が配列/カンマ区切りの場合、ORの値リストと交差判定する
     def match_eq(field_value, filter_values)
-      field_list = normalize_to_list(field_value)
-      value_list = Array(filter_values).map { it.to_s.strip }
+      # 綴りの揺れは両側でそろえる。条件側だけそろえると、データに "2024_01" や
+      # "R06-01-01" のような文字列があるとき、同じ綴りの条件で一致しなくなる。
+      field_list = normalize_to_list(field_value).map { canonical_token(it) }
+      value_list = Array(filter_values).map { canonical_token(it.to_s.strip) }
 
       # フィールド側の値リストと条件値リストに交差があれば一致
       (field_list & value_list).any?
     end
 
+    # 等値比較のため、値を綴りの揺れのない形へそろえる。
+    # 数は桁区切りを外し（9_000_000 → 9000000）、日付は西暦にする（R06-01-01 → 2024-01-01）。
+    # 存在しない日付は、等値比較では文字列のまま比べる。
+    def canonical_token(str)
+      date = parse_date(str)
+      date ? date.iso8601 : QueryStreamParser.strip_digit_separators(str)
+    rescue InvalidDateError
+      str
+    end
+
     # フィールド値をリスト化する（配列/カンマ区切り/単値を統一）
     def normalize_to_list(value)
       case value
@@ -103,20 +169,31 @@ module QueryStream
       end
     end
 
+    # 西暦・和暦の日付を Date に直す。日付の形でなければ nil を返す。
+    # 和暦は Date.jisx0301 に任せる。Date.parse は "R06-01-01" を 2006-01-01 と
+    # 読み違えるので使えない。jisx0301 の区切りはドットで、年は 2 桁が要る。
+    # 元号の境目は検査しない（H31-05-01 も 2019-05-01 として読む）。
+    # @raise [InvalidDateError] 日付の形だが存在しない日（2024-02-30 など）
+    def parse_date(value)
+      if value.match?(SEIREKI_DATE)
+        Date.parse(value)
+      elsif (m = value.match(WAREKI_DATE))
+        Date.jisx0301("#{m[:era]}#{m[:year].rjust(2, '0')}.#{m[:month]}.#{m[:day]}")
+      end
+    rescue Date::Error
+      raise InvalidDateError, "無効な日付: #{value}"
+    end
+
     # 比較用に値を正規化する（数値変換・日付変換を試みる）
     def to_comparable(value)
       case value
       when Date, Time
         value
       when String
-        # 日付形式（YYYY-MM-DD）を検出して Date に変換
-        if value.match?(/\A\d{4}-\d{2}-\d{2}\z/)
-          begin
-            return Date.parse(value)
-          rescue Date::Error
-            raise InvalidDateError, "無効な日付: #{value}"
-          end
-        end
+        # 日付形式（西暦・和暦）を検出して Date に変換
+        date = parse_date(value)
+        return date if date
+
         # 数値変換を試みる
         case value
         when /\A-?\d+\z/

data/lib/query_stream/query_stream_parser.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/query_stream_parser.rb
 # ================================================================
 # 責務:
 #   QueryStream 記法（= books | tags=ruby | -title | 5 | :full）を
@@ -27,6 +25,14 @@ module QueryStream
     # AND 条件の区切りパターン
     AND_PATTERN = /\s+(?:AND|and|&&)\s+/
 
+    # OR 条件の区切りパターン。`||` は記法の区切りの `|` と衝突するので使わない
+    OR_PATTERN = /\s+(?:OR|or)\s+/
+
+    # 桁をアンダースコアで区切った数（9_000_000 / 900_0000 / 1_234.5）。
+    # Ruby の数値リテラルと同じく、区切りは数字と数字のあいだにだけ置ける。
+    # 区切り方は問わないので、万の位で区切る 900_0000 も書ける。
+    NUMBER_WITH_SEPARATORS = /\A-?\d+(?:_\d+)*(?:\.\d+(?:_\d+)*)?\z/
+
     module_function
 
     # QueryStream 記法をパースして構造化ハッシュを返す
@@ -137,16 +143,15 @@ module QueryStream
       tokens
     end
 
-    # ソート指定をパースする
-    # @param token [String] "-title" / "+title" / "title"
+    # ソート指定をパースする。
+    #
+    # **符号は必須である。** 呼び出し側（parse_segment）が `+` か `-` で始まることを確かめてから渡す。
+    # 符号なしの `title` は、`= book | 楽しいRuby` と区別できないので主キー検索として扱う。
+    #
+    # @param token [String] "-title" / "+title"
     # @return [Hash] { field:, direction: }
     def parse_sort(token)
-      case token
-      in /\A-(.+)\z/
-        { field: $1.to_sym, direction: :desc }
-      in /\A\+?(.+)\z/
-        { field: $1.to_sym, direction: :asc }
-      end
+      { field: token[1..].to_sym, direction: token.start_with?('-') ? :desc : :asc }
     end
 
     # 直前フィールドを引き継いで値のみの条件をパースする
@@ -157,37 +162,35 @@ module QueryStream
       parse_eq_condition(field, value_str)
     end
 
-    # AND で接続されたフィルタ式をパースする
-    # @param expression [String] "tags=ruby && category=web"
-    # @return [Array<Hash>] フィルタ条件のリスト
+    # AND / OR で接続されたフィルタ式をパースする。AND は OR より強く結び付く。
+    # 項目名を省いた値は、直前の条件の項目を引き継ぐ（tags=ruby AND beginner）。
+    # @param expression [String] "tags=ruby && category=web" / "tags=ruby OR tags=go"
+    # @return [Array<Hash>] すべて満たすフィルタ条件のリスト。OR は { op: :or, branches: } の 1 条件にまとめる
     def parse_filter_expression(expression)
-      # AND で分割
-      clauses = expression.split(AND_PATTERN)
       previous_field = nil
-      previous_filter = nil
 
-      clauses.flat_map do |clause|
-        clause = clause.strip
-        next [] if clause.empty?
+      branches = expression.split(OR_PATTERN).map do |branch|
+        branch.split(AND_PATTERN).flat_map do |clause|
+          parsed = parse_clause(clause.strip, previous_field)
+          previous_field = parsed.last&.[](:field) || previous_field
+          parsed
+        end
+      end.reject(&:empty?)
 
-        parsed = parse_single_condition(clause)
+      branches.size > 1 ? [{ op: :or, branches: }] : branches.flatten
+    end
 
-        if parsed.empty? && previous_field
-          if previous_filter && previous_filter[:field] == previous_field && previous_filter[:op] == :eq
-            additional = parse_values(clause)
-            previous_filter[:value] = Array(previous_filter[:value]) + additional
-            next []
-          else
-            parsed = parse_value_only_condition(previous_field, clause)
-          end
-        end
+    # AND / OR で区切られた 1 節をパースする
+    # @param clause [String] "tags=ruby" / "beginner"
+    # @param previous_field [Symbol, nil] 項目名を省いたときに引き継ぐ項目
+    # @return [Array<Hash>] フィルタ条件
+    def parse_clause(clause, previous_field)
+      return [] if clause.empty?
 
-        last_filter = parsed.last
-        previous_field = last_filter&.[](:field)
-        previous_filter = last_filter if last_filter&.[](:op) == :eq
+      parsed = parse_single_condition(clause)
+      return parsed unless parsed.empty? && previous_field
 
-        parsed
-      end
+      parse_value_only_condition(previous_field, clause)
     end
 
     # 単一条件をパースする（OR はカンマ区切りで表現）
@@ -242,6 +245,9 @@ module QueryStream
         # 通常の等値条件（カンマ区切りでOR）
         [{ field: field_sym, op: :eq, value: parse_values(value_str) }]
       end
+    rescue ArgumentError
+      # 両端を比較できない範囲（2020..abc）は Range を作れないので、文字列の値として扱う
+      [{ field: field_sym, op: :eq, value: parse_values(value_str) }]
     end
 
     # カンマ区切りの値をリストとしてパースする
@@ -255,7 +261,7 @@ module QueryStream
     # @param str [String] "20" / "3.14" / "東京"
     # @return [Integer, Float, String] 変換後の値
     def parse_numeric(str)
-      s = str.strip
+      s = strip_digit_separators(str.strip)
       case s
       when /\A-?\d+\z/    then s.to_i
       when /\A-?\d+\.\d+\z/ then s.to_f
@@ -263,6 +269,13 @@ module QueryStream
       end
     end
 
+    # 数の桁区切り（アンダースコア）を外す。数でない値（tag_name など）はそのまま返す。
+    # @param str [String] "9_000_000" / "ruby"
+    # @return [String] "9000000" / "ruby"
+    def strip_digit_separators(str)
+      str.match?(NUMBER_WITH_SEPARATORS) ? str.delete('_') : str
+    end
+
     # 主キー候補フィールドによる一件検索フィルタを構築する
     # すべての主キー候補に対して OR 的に検索する
     # @param value [String] 検索値

data/lib/query_stream/singularize.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/singularize.rb
 # ================================================================
 # 責務:
 #   英単語の複数形を単数形に変換する軽量ヘルパー。