query-stream 1.4.0 → 1.6.0

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,56 @@ 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 = value_at(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
+
+    # 抽出条件と並べ替えの項目が、どれか 1 件のレコードにあるかを確かめる。
+    # 無い項目（`tag=ruby` の打ち間違い）で絞ると 0 件になり、並べ替えは定義順のままになる。
+    # どちらも展開自体は成功するので、書いた本人は気づけない。テンプレートのキーと同じく、
+    # 見るのは一番上の階層のキーだけで、どれか 1 件にあれば正しい項目とみなす。
+    # @param records [Array<Hash>] 絞り込む前のレコード群
+    # @param parsed [Hash] QueryStreamParser.parse の結果
+    # @raise [InvalidQueryError] どのレコードにも無い項目を指している
+    def validate_fields!(records, parsed)
+      available_keys = records.flat_map(&:keys).uniq
+      return if available_keys.empty?
+
+      fields = condition_fields(parsed[:filters])
+      fields << parsed[:sort][:field] if parsed[:sort]
+      unknown = fields.find { !available_keys.include?(it.to_s.split('.').first.to_sym) }
+      return unless unknown
+
+      raise InvalidQueryError.new(reason: :unknown_field, condition: unknown.to_s, available_keys:)
+    end
+
+    # 条件が指す項目名を集める。OR の枝の中も見る。主キー検索は項目名を持たないので除く。
+    def condition_fields(filters)
+      filters.flat_map do |filter|
+        case filter
+        in { op: :or, branches: } then branches.flat_map { condition_fields(it) }
+        in { field: :_primary_key } then []
+        in { field: } then [field]
+        end
+      end
+    end
+
+    # ドットでつないだ項目名（:"author.name"）をたどって値を返す。途中で途切れたら nil。
+    def value_at(record, field)
+      field.to_s.split('.').reduce(record) { |value, key| value.is_a?(Hash) ? value[key.to_sym] : nil }
     end
 
     # 単一フィルタ条件をレコードに対して評価する
@@ -46,29 +102,62 @@ module QueryStream
         return evaluate_primary_key_lookup(record, filter[:value])
       end
 
-      field_value = record[filter[:field]]
+      field_value = value_at(record, filter[:field])
 
       case filter[:op]
       when :eq
         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 +171,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 +204,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,20 @@ 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/
+
+    # 抽出条件・並べ替えの項目名。テンプレートの `= author.name` と同じく、ドットでネストした値を指せる。
+    FIELD = /[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*/
+
+    # 演算子の文字。値だけの節（項目名を省いた `beginner`）に含まれていれば、読み損ねた条件である。
+    OPERATOR_CHARS = /[=!<>]/
+
     module_function
 
     # QueryStream 記法をパースして構造化ハッシュを返す
@@ -137,16 +149,20 @@ module QueryStream
       tokens
     end
 
-    # ソート指定をパースする
-    # @param token [String] "-title" / "+title" / "title"
+    # ソート指定をパースする。
+    #
+    # **符号は必須である。** 呼び出し側（classify_tokens）が `+` か `-` で始まることを確かめてから渡す。
+    # 符号なしの `title` は、`= book | たのしいRuby` と区別できないので主キー検索として扱う。
+    # 項目名として読めない綴り（`-title foo`）は、並べ替えずに出すと気づけないのでエラーにする。
+    #
+    # @param token [String] "-title" / "+author.name"
     # @return [Hash] { field:, direction: }
+    # @raise [InvalidQueryError] 項目名として読めない
     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..].strip
+      raise InvalidQueryError.new(condition: token) unless field.match?(/\A#{FIELD}\z/o)
+
+      { field: field.to_sym, direction: token.start_with?('-') ? :desc : :asc }
     end
 
     # 直前フィールドを引き継いで値のみの条件をパースする
@@ -157,37 +173,39 @@ 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 節をパースする。
+    # 読めない節を空の条件として捨てると、全件が出て絞り込みが黙って外れるので、エラーにする。
+    # 値だけの節は、直前の項目があり、演算子を含まないときだけ受け付ける（`年=2019` を値にしない）。
+    # @param clause [String] "tags=ruby" / "beginner"
+    # @param previous_field [Symbol, nil] 項目名を省いたときに引き継ぐ項目
+    # @return [Array<Hash>] フィルタ条件
+    # @raise [InvalidQueryError] 条件として読めない
+    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?
+      return parse_value_only_condition(previous_field, clause) if previous_field && !clause.match?(OPERATOR_CHARS)
 
-        parsed
-      end
+      raise InvalidQueryError.new(condition: clause)
     end
 
     # 単一条件をパースする（OR はカンマ区切りで表現）
@@ -196,17 +214,17 @@ module QueryStream
     def parse_single_condition(condition)
       # 比較演算子の検出（!=, >=, <=, >, <, ==, = の順で試行）
       case condition.strip
-      in /\A([a-zA-Z_]+)\s*!=\s*(.+)\z/
+      in /\A(#{FIELD})\s*!=\s*(.+)\z/
         [{ field: $1.to_sym, op: :neq, value: parse_values($2) }]
-      in /\A([a-zA-Z_]+)\s*>=\s*(.+)\z/
+      in /\A(#{FIELD})\s*>=\s*(.+)\z/
         [{ field: $1.to_sym, op: :gte, value: parse_numeric($2.strip) }]
-      in /\A([a-zA-Z_]+)\s*<=\s*(.+)\z/
+      in /\A(#{FIELD})\s*<=\s*(.+)\z/
         [{ field: $1.to_sym, op: :lte, value: parse_numeric($2.strip) }]
-      in /\A([a-zA-Z_]+)\s*>\s*(.+)\z/
+      in /\A(#{FIELD})\s*>\s*(.+)\z/
         [{ field: $1.to_sym, op: :gt, value: parse_numeric($2.strip) }]
-      in /\A([a-zA-Z_]+)\s*<\s*(.+)\z/
+      in /\A(#{FIELD})\s*<\s*(.+)\z/
         [{ field: $1.to_sym, op: :lt, value: parse_numeric($2.strip) }]
-      in /\A([a-zA-Z_]+)\s*={1,2}\s*(.+)\z/
+      in /\A(#{FIELD})\s*={1,2}\s*(.+)\z/
         parse_eq_condition($1.strip, $2.strip)
       else
         # パースできない場合は空で返す
@@ -242,6 +260,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 +276,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 +284,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
 # ================================================================
 # 責務:
 #   英単語の複数形を単数形に変換する軽量ヘルパー。

data/lib/query_stream/template_compiler.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream/template_compiler.rb
 # ================================================================
 # 責務:
 #   テンプレートファイル（_book.md 等）にデータを流し込み、
@@ -9,6 +7,8 @@
 #
 # 変換ルール:
 #   - `= key` のみの行 → key の値を展開（nil/空文字なら行スキップ）
+#   - `= key` が 2 つ以上ある行 → 区切り（／・、，,）と括弧で部品に分け、
+#     空のキーを含む部品だけを消す（部品が全部消えたら行スキップ。表の行は対象外）
 #   - `prefix = key` → prefix を残してkey の値を展開
 #   - `![](key)` → 変数展開（拡張子なし → 変数、拡張子あり → リテラル）
 #   - `= key` を含まない行 → リテラル出力（ヘッダー等は一度だけ出力）
@@ -44,6 +44,21 @@ module QueryStream
     # VFM フェンス終了行: 単独の :::
     FENCE_CLOSE_PATTERN = /\A:::\s*\z/
 
+    # 部品の区切り: 全角の斜線・中黒・読点・コンマと半角のコンマ（前後の空白ごと）、
+    # 前後に空白のある半角の斜線。空白なしの半角の斜線を区切りにしないのは、
+    # URL（https://example.com/books/= id）を割らないため。
+    PART_SEPARATOR = %r{\s*[／・、，,]\s*|\s+/\s+}
+
+    # 変数を含みうる括弧（全角・半角）。中身ごと 1 つの部品として扱う（直前の空白も含める）。
+    # `]` の直後の括弧は Markdown のリンク先（`[= title](= url)`）なので含めない。
+    OPTIONAL_GROUP = /\s*(?<!\])[（(][^（）()]*[）)]/
+
+    # 行頭の Markdown の目印（箇条書き・番号・引用・見出し）。部品が消えても残す。
+    LINE_MARKER = /\A\s*(?:(?:[-*+]|\d+\.)\s+|>\s?|\#{1,6}\s+)*/
+
+    # 括弧を部品として退避するときの目印（テンプレートに現れない制御文字で挟む）
+    GROUP_PLACEHOLDER = /\u0000(\d+)\u0000/
+
     module_function
 
     # テンプレートにレコード群を流し込んでテキストを生成する
@@ -55,7 +70,7 @@ module QueryStream
     # @return [String] 展開後のテキスト
     def render(template, records, source_filename: nil, line_number: nil, template_path: nil)
       lines = template.lines
-      validate_template_keys!(lines, records.first, source_filename:, line_number:, template_path:) if records.any?
+      validate_template_keys!(lines, records, source_filename:, line_number:, template_path:) if records.any?
 
       parts = classify_lines(lines)
       return '' if records.empty?
@@ -124,6 +139,9 @@ module QueryStream
       end
 
       output.join
+    rescue NestedValueError => e
+      # 値を表示するときに見つかるので、ここで直すテンプレートと記法の位置を付け足す
+      raise e.with_context(template_path:, location: source_filename ? "#{source_filename}:#{line_number}" : '')
     end
 
     # テンプレート行を分類する
@@ -219,7 +237,7 @@ module QueryStream
     end
 
     # テンプレート行をレコードデータで展開する
-    # nil/空文字のキーがあれば行ごとスキップ（nil を返す）
+    # 行ごと消すときは nil を返す
     # @param line [String] テンプレート行
     # @param record [Hash] データレコード
     # @return [String, nil] 展開後の行、またはスキップ時 nil
@@ -256,12 +274,12 @@ module QueryStream
           match
         else
           # 変数として展開（ドット記法対応）
-          value = resolve_nested_value(record, src)
-          if value.nil? || value.to_s.strip.empty?
+          text = display_text(resolve_nested_value(record, src), src)
+          if text.strip.empty?
             skip = true
             match # gsub のブロックからは文字列を返す必要がある
           else
-            "![#{alt}](#{value})#{attr}"
+            "![#{alt}](#{text})#{attr}"
           end
         end
       end
@@ -270,24 +288,108 @@ module QueryStream
     end
 
     # = key パターンの変数を展開する（ドット記法対応）
+    #
+    # 変数が 2 つ以上ある行は、空のキーを含む部品だけを消す（expand_parts）。
+    # `= author.name 著／= publisher／= year 年` で発行年だけが無い本でも、著者と出版社は出る。
+    # 変数が 1 つの行と表の行（セルを消すと列がずれる）は、空なら行ごと消す。
     # @param line [String] テンプレート行
     # @param record [Hash] データレコード
     # @return [String, nil] 展開後の行、またはスキップ時 nil
     def expand_variables(line, record)
+      return expand_parts(line, record) if partial_line?(line)
+
+      expand_whole(line, record)
+    end
+
+    # 部品ごとに消せる行か。変数が 2 つ以上あり、表の行でないもの。
+    def partial_line?(line)
+      !line.lstrip.start_with?('|') && line.scan(VARIABLE_PATTERN).size >= 2
+    end
+
+    # 区切りと括弧で行を部品に分け、空のキーを含む部品だけを消す。
+    #
+    # - 変数を含む括弧（`（= year 年）`）は 1 つの部品。空なら直前の空白ごと消す。
+    # - 括弧の外は PART_SEPARATOR で分ける。残った部品は、前の部品の後ろにあった区切りでつなぐ。
+    # - 行頭の Markdown の目印（`- ` など）と行末の改行は、部品が消えても残す。
+    # - 変数を含む部品が 1 つも残らなければ nil（行ごと消す）。
+    # キーがすべて埋まっていれば、区切りも括弧も元のまま戻るので、出力は expand_whole と同じになる。
+    # @param line [String] テンプレート行
+    # @param record [Hash] データレコード
+    # @return [String, nil] 展開後の行、またはスキップ時 nil
+    def expand_parts(line, record)
+      newline = line[/\R\z/].to_s
+      body = line.chomp
+      marker = body[LINE_MARKER]
+      body = body.delete_prefix(marker)
+
+      groups = []
+      masked = body.gsub(OPTIONAL_GROUP) do |group|
+        next group unless group.match?(VARIABLE_PATTERN)
+
+        groups << group
+        "\u0000#{groups.size - 1}\u0000"
+      end
+
+      kept = masked.split(/(#{PART_SEPARATOR})/).each_slice(2).filter_map do |part, separator|
+        text = expand_part(part, groups, record)
+        text && [text, separator.to_s, variable_part?(part)]
+      end
+      return nil unless kept.any? { |_, _, variable| variable }
+
+      joined = kept.each_with_index.map { |(text, separator, _), i| i == kept.size - 1 ? text : text + separator }.join
+      "#{marker}#{joined}#{newline}"
+    end
+
+    # 部品 1 つを展開する。空のキーを含めば nil。括弧は中のキーが空ならそこだけ消す。
+    # 括弧の外を先に展開するのは、値の中の `= …` をもう一度展開しないため（括弧は退避中）。
+    def expand_part(part, groups, record)
+      outer = expand_whole(part, record)
+      return nil unless outer
+
+      text = outer.gsub(GROUP_PLACEHOLDER) { expand_whole(groups[::Regexp.last_match(1).to_i], record).to_s }
+      text.strip.empty? ? nil : text
+    end
+
+    def variable_part?(part) = part.match?(VARIABLE_PATTERN) || part.match?(GROUP_PLACEHOLDER)
+
+    # 行の変数をすべて展開する。空のキーが 1 つでもあれば nil（行ごと消す）。
+    def expand_whole(line, record)
       result = line.dup
 
       result.gsub!(VARIABLE_PATTERN) do |_match|
         key_path = $1
-        value = resolve_nested_value(record, key_path)
-        if value.nil? || value.to_s.strip.empty?
-          return nil # 行ごとスキップ
-        end
-        value.to_s
+        text = display_text(resolve_nested_value(record, key_path), key_path)
+        return nil if text.strip.empty? # 行ごとスキップ
+
+        text
       end
 
       result
     end
 
+    # 値を、テンプレートに埋め込む文字列にする。値が無いときは空文字列（呼び出し側が行・部品を消す）。
+    #
+    # 配列（tags: [ruby, beginner]）は、抽出条件と同じく複数の値として扱い、list_separator でつなぐ。
+    # 空の要素は落とし、全部空なら値が無いのと同じにする。
+    # ハッシュと、ハッシュや配列を含む配列は、どう並べて出すかを gem が決められない。
+    # 黙って Ruby の表記（{name: "…"}）を出さず、NestedValueError で書き方を直してもらう。
+    # `= author` は `= author.name` の書き間違いであることがほとんどなので、中のキーを渡す。
+    # @param value [Object, nil] resolve_nested_value の結果
+    # @param key_path [String] テンプレートに書かれたキー（エラーの報告用）
+    # @return [String]
+    # @raise [NestedValueError] ハッシュ、またはハッシュや配列を含む配列
+    def display_text(value, key_path)
+      case value
+      in nil then ''
+      in Hash then raise NestedValueError.new(key_path:, available_keys: value.keys)
+      in Array if value.any? { it.is_a?(Hash) || it.is_a?(Array) }
+        raise NestedValueError.new(key_path:, available_keys: [], list: true)
+      in Array
+        value.map { it.to_s.strip }.reject(&:empty?).join(QueryStream.configuration.list_separator)
+      else value.to_s
+      end
+    end
+
     # ドット記法のキーパスをたどってネストされた値を取得する
     # @param record [Hash] データレコード
     # @param key_path [String] キーパス（例: "author.name"）
@@ -303,16 +405,19 @@ module QueryStream
     end
 
     # テンプレート内のキーがデータに存在するかを検証する
+    #
+    # どれか 1 件にでもあるキーは正しいキーとみなす。省ける項目（発行年など）が最初の 1 件に
+    # 無いだけで、打ち間違いとして止めないため。値の無い件では、その行・部品を消す（expand_variables）。
     # @param lines [Array<String>] テンプレートの行リスト
-    # @param sample_record [Hash] サンプルレコード（最初の1件）
+    # @param records [Array<Hash>] レコード群
     # @param source_filename [String, nil] エラー報告用ファイル名
     # @param line_number [Integer, nil] エラー報告用行番号
     # @param template_path [String, nil] エラー報告用テンプレートパス
-    def validate_template_keys!(lines, sample_record, source_filename: nil, line_number: nil, template_path: nil)
-      return unless sample_record
+    def validate_template_keys!(lines, records, source_filename: nil, line_number: nil, template_path: nil)
+      available_keys = records.flat_map(&:keys).uniq
+      return if available_keys.empty?
 
       location = source_filename ? "#{source_filename}:#{line_number}" : ''
-      available_keys = sample_record.keys
       in_code_block = false
 
       lines.each do |line|

data/lib/query_stream/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module QueryStream
-  VERSION = '1.4.0'
+  VERSION = '1.6.0'
 end