query-stream 1.2.2 → 1.5.0

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
 
     # テンプレートにレコード群を流し込んでテキストを生成する
@@ -51,10 +66,11 @@ module QueryStream
     # @param records [Array<Hash>] データレコード群
     # @param source_filename [String, nil] エラー報告用ファイル名
     # @param line_number [Integer, nil] エラー報告用行番号
+    # @param template_path [String, nil] エラー報告用テンプレートパス（キーの打ち間違いはここを直す）
     # @return [String] 展開後のテキスト
-    def render(template, records, source_filename: nil, line_number: nil)
+    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:) 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?
@@ -218,7 +234,7 @@ module QueryStream
     end
 
     # テンプレート行をレコードデータで展開する
-    # nil/空文字のキーがあれば行ごとスキップ（nil を返す）
+    # 行ごと消すときは nil を返す
     # @param line [String] テンプレート行
     # @param record [Hash] データレコード
     # @return [String, nil] 展開後の行、またはスキップ時 nil
@@ -269,10 +285,72 @@ 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|
@@ -302,15 +380,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] エラー報告用行番号
-    def validate_template_keys!(lines, sample_record, source_filename: nil, line_number: nil)
-      return unless sample_record
+    # @param template_path [String, nil] エラー報告用テンプレートパス
+    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|
@@ -327,10 +409,7 @@ module QueryStream
         line.scan(VARIABLE_PATTERN).each do |(key_path)|
           root_key = key_path.split('.').first.to_sym
           unless available_keys.include?(root_key)
-            msg = "テンプレートに存在しないキーが記述されています: #{key_path}"
-            QueryStream.logger.error("#{msg}(#{location})")
-            QueryStream.logger.error("  利用可能なキー: #{available_keys.join(', ')}")
-            raise UnknownKeyError, msg
+            raise UnknownKeyError.new(key_path:, available_keys:, template_path:, location:)
           end
         end
 
@@ -341,10 +420,7 @@ module QueryStream
 
           root_key = src.split('.').first.to_sym
           unless available_keys.include?(root_key)
-            msg = "テンプレートに存在しないキーが記述されています: #{src}"
-            QueryStream.logger.error("#{msg}(#{location})")
-            QueryStream.logger.error("  利用可能なキー: #{available_keys.join(', ')}")
-            raise UnknownKeyError, msg
+            raise UnknownKeyError.new(key_path: src, available_keys:, template_path:, location:)
           end
         end
       end

data/lib/query_stream/version.rb

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

data/lib/query_stream.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# ================================================================
-# File: lib/query_stream.rb
 # ================================================================
 # 責務:
 #   QueryStream gem のエントリポイント。
@@ -29,6 +27,10 @@ module QueryStream
   # 行頭 = の直後に英数字/ハイフン/アンダースコアのデータ名（スペースは任意）
   QUERY_STREAM_PATTERN = /^=\s*([a-zA-Z][a-zA-Z0-9_-]*)(?:\s*\|.*)?$/
 
+  # これを超える長さの引数はパスとみなさず本文として扱う（scan の path/content 判定）。
+  # 主要な OS の PATH_MAX は 4096 前後で、それより長い「パス」は実在しない。
+  MAX_PATH_BYTES = 4096
+
   class << self
     # グローバル設定を返す
     # @return [Configuration]
@@ -42,12 +44,6 @@ module QueryStream
       yield(configuration)
     end
 
-    # ロガーへのショートカット
-    # @return [Logger]
-    def logger
-      configuration.logger
-    end
-
     # テキストコンテンツ内の QueryStream 記法をすべて展開する
     # 1行の展開に失敗しても残りの行の処理を継続する。
     # エラー情報は例外の属性として呼び出し元に委ねる（gem 内ではログ出力しない）。
@@ -57,10 +53,13 @@ module QueryStream
     # @param templates_dir [String, nil] テンプレートディレクトリ（nil時はconfigを使用）
     # @param on_error [Proc, nil] エラー時コールバック。|exception| を受け取る。省略時は何もしない。
     # @param on_warning [Proc, nil] 警告時コールバック。|warning| を受け取る。省略時は何もしない。
+    # @param post_render [Proc, nil] 展開結果の後段フィルタ。(text, context) -> String。省略時は configuration.post_render を使う。
     # @return [String] 展開後のテキストコンテンツ
-    def render(content, source_filename: nil, data_dir: nil, templates_dir: nil, on_error: nil, on_warning: nil)
+    def render(content, source_filename: nil, data_dir: nil, templates_dir: nil, on_error: nil, on_warning: nil,
+               post_render: nil)
       data_dir      ||= configuration.data_dir
       templates_dir ||= configuration.templates_dir
+      post_render   ||= configuration.post_render
 
       lines = content.lines
       result = []
@@ -70,7 +69,7 @@ module QueryStream
         line_number = idx + 1
 
         # コードブロック内はスキップ
-        if line.lstrip.start_with?('```')
+        if code_fence?(line)
           in_code_block = !in_code_block
           result << line
           next
@@ -82,10 +81,10 @@ module QueryStream
         end
 
         # QueryStream 記法の検出
-        if line.match?(QUERY_STREAM_PATTERN)
+        if query_line?(line)
           begin
             expanded = render_query(
-              line.chomp, line_number:, source_filename:, data_dir:, templates_dir:, on_warning:
+              line.chomp, line_number:, source_filename:, data_dir:, templates_dir:, on_warning:, post_render:
             )
             result << expanded << "\n"
           rescue Error => e
@@ -107,8 +106,10 @@ module QueryStream
     # @param source_filename [String, nil] ソースファイル名
     # @param data_dir [String, nil] データディレクトリ
     # @param templates_dir [String, nil] テンプレートディレクトリ
+    # @param post_render [Proc, nil] 展開結果の後段フィルタ。(text, context) -> String
     # @return [String] 展開後のテキスト
-    def render_query(query, line_number: nil, source_filename: nil, data_dir: nil, templates_dir: nil, on_warning: nil)
+    def render_query(query, line_number: nil, source_filename: nil, data_dir: nil, templates_dir: nil, on_warning: nil,
+                     post_render: nil)
       data_dir      ||= configuration.data_dir
       templates_dir ||= configuration.templates_dir
       location = source_filename ? "#{source_filename}:#{line_number}" : "行#{line_number}"
@@ -117,8 +118,6 @@ module QueryStream
       parsed = QueryStreamParser.parse(query)
 
       # --- Phase: Load Data ---
-      # gem 内でログ出力せず、構造化された属性を持つ例外を raise する。
-      # メッセージの構成・ログ出力・i18n は呼び出し元の責務とする。
       data_file = DataResolver.resolve(parsed[:source], data_dir)
       unless data_file
         expected = File.join(data_dir, "#{parsed[:source]}.yml")
@@ -144,13 +143,11 @@ module QueryStream
       if parsed[:single_lookup]
         case records.size
         when 0
-          # gem 内でログ出力せず、構造化された属性を持つ警告を呼び出し元に委ねる。
           on_warning&.call(NoResultWarning.new(query: query, location: location))
           return ''
         when 1
           # 正常
         else
-          # gem 内でログ出力せず、構造化された属性を持つ警告を呼び出し元に委ねる。
           on_warning&.call(
             AmbiguousQueryWarning.new(query: query, location: location, count: records.size)
           )
@@ -165,8 +162,6 @@ module QueryStream
 
       unless File.exist?(template_path)
         hint = build_template_hint(singular, style, format, templates_dir)
-        # gem 内でログ出力せず、構造化された属性を持つ例外を raise する。
-        # メッセージの構成・ログ出力・i18n は呼び出し元の責務とする。
         raise TemplateNotFoundError.new(
           template_path: template_path,
           query:         query,
@@ -178,26 +173,42 @@ module QueryStream
       template_content = File.read(template_path, encoding: 'utf-8')
 
       # --- Phase: Render ---
-      TemplateCompiler.render(template_content, records, source_filename:, line_number:)
+      rendered = TemplateCompiler.render(template_content, records, source_filename:, line_number:, template_path:)
+
+      # --- Phase: Post-render filter ---
+      # 展開結果を呼び出し元の後段フィルタへ通す（画像パス解決など gem 外の後処理）。
+      # コールバックが String 以外を返した場合は、元の展開結果を採用する。
+      return rendered unless post_render
+
+      context = {
+        source:        parsed[:source],   # 記法に書かれた論理名（例: "physics_book"）
+        data_file:     data_file,          # 単複解決後の実パス（例: "data/physics_books.yml"）
+        data_dir:      data_dir,
+        template_path: template_path,
+        query:         query,
+        location:      location            # "filename:line" 形式
+      }
+      result = post_render.call(rendered, context)
+      result.is_a?(String) ? result : rendered
     end
 
     # テキスト内の QueryStream 記法を検出してリストを返す
     # @param path_or_content [String] ファイルパスまたはテキストコンテンツ
     # @return [Array<String>] 検出された QueryStream 記法のリスト
     def scan(path_or_content)
-      content = File.exist?(path_or_content) ? File.read(path_or_content, encoding: 'utf-8') : path_or_content
+      content = readable_file?(path_or_content) ? File.read(path_or_content, encoding: 'utf-8') : path_or_content
       lines = content.lines
       queries = []
       in_code_block = false
 
       lines.each do |line|
-        if line.lstrip.start_with?('```')
+        if code_fence?(line)
           in_code_block = !in_code_block
           next
         end
         next if in_code_block
 
-        queries << line.chomp if line.match?(QUERY_STREAM_PATTERN)
+        queries << line.chomp if query_line?(line)
       end
 
       queries
@@ -205,6 +216,43 @@ module QueryStream
 
     private
 
+    # その行を QueryStream 記法として扱うか。
+    #
+    # 不正な UTF-8 を含む行は記法として解釈せず、本文としてそのまま返す。`match?` はそういう行に
+    # `ArgumentError` を投げるので、捕まえないと展開全体が止まる。scrub しないのは、原稿のバイト列を
+    # 変えないため。
+    #
+    # EncodingError と ArgumentError の両方を捕まえる。壊れたバイト列に Ruby が投げる例外はメソッドで
+    # 異なる（match? / 先頭破損の lstrip は ArgumentError、strip は Encoding::CompatibilityError）。
+    def query_line?(line)
+      line.match?(QUERY_STREAM_PATTERN)
+    rescue EncodingError, ArgumentError
+      false
+    end
+
+    # コードフェンスの開始/終了行か。
+    # `lstrip` も不正な UTF-8 で ArgumentError を投げるので、query_line? と同じく本文として扱う。
+    def code_fence?(line)
+      line.lstrip.start_with?('```')
+    rescue EncodingError, ArgumentError
+      false
+    end
+
+    # 引数をファイルパスとして読むべきか。
+    #
+    # `scan` はパスと本文のどちらも受け取る。本文を `File.exist?` へ渡すと、NUL バイトを含む場合は
+    # `ArgumentError` になり、ディレクトリは `File.read` が `Errno::EISDIR` を出す。
+    # パスとして成立する形だけを先に選び、判定の失敗も本文として扱う。
+    def readable_file?(str)
+      s = str.to_s
+      return false if s.empty? || s.include?("\0") || s.include?("\n")
+      return false if s.bytesize > MAX_PATH_BYTES
+
+      File.file?(s)
+    rescue ArgumentError, SystemCallError
+      false
+    end
+
     # テンプレートファイルパスを解決する
     # @param singular_name [String] 単数形のデータ名
     # @param style [String, nil] スタイル名

data/query-stream.gemspec

@@ -8,29 +8,29 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Atelier Mirai']
   spec.email         = ['contact@atelier-mirai.net']
 
-  spec.summary       = 'QueryStream - YAML/JSON data renderer with template expansion'
-  spec.description   = 'A generic Ruby library that expands QueryStream notation in text content ' \
-                        'by combining YAML/JSON data files with template files.'
+  spec.summary       = 'YAML / JSON のデータとテンプレートから、文章中の 1 行の記法を展開する Ruby ライブラリ'
+  spec.description   = 'QueryStream は、文章中に書いた `= books | tags=ruby | -year | 5` のような 1 行の記法を、' \
+                       'YAML / JSON のデータファイルとテンプレートを組み合わせて展開する汎用の Ruby ライブラリです。' \
+                       '抽出条件、並べ替え、件数、スタイルを指定できます。'
   spec.homepage      = 'https://github.com/Atelier-Mirai/query-stream'
   spec.license       = 'MIT'
 
   spec.metadata['source_code_uri'] = 'https://github.com/Atelier-Mirai/query-stream'
   spec.metadata['changelog_uri']   = 'https://github.com/Atelier-Mirai/query-stream/blob/master/CHANGELOG.md'
 
-  spec.required_ruby_version = '>= 4.0'
+  spec.required_ruby_version = '>= 3.4'
 
-  spec.files = Dir.glob('{lib,bin}/**/*') + %w[README.md LICENSE Gemfile query-stream.gemspec]
+  spec.files = Dir.glob('{lib,bin}/**/*') +
+               %w[README.md CHANGELOG.md RELEASE_NOTE.md LICENSE query-stream.gemspec]
   spec.bindir        = 'bin'
   spec.executables   = ['query-stream']
   spec.require_paths = ['lib']
 
-  # Runtime dependencies
-  spec.add_dependency 'logger'
   spec.add_dependency 'samovar', '~> 2.1'
 
-  # Development dependencies
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake', '~> 13.2'
-  spec.add_development_dependency 'minitest', '~> 5.22'
+  spec.add_development_dependency 'minitest', '>= 5.22'
+  spec.add_development_dependency 'rubocop', '~> 1.81'
   spec.metadata['rubygems_mfa_required'] = 'false'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: query-stream
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.5.0
 platform: ruby
 authors:
 - Atelier Mirai
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: logger
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: samovar
   requirement: !ruby/object:Gem::Requirement
@@ -69,18 +55,32 @@ dependencies:
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.22'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.22'
-description: A generic Ruby library that expands QueryStream notation in text content
-  by combining YAML/JSON data files with template files.
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.81'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.81'
+description: QueryStream は、文章中に書いた `= books | tags=ruby | -year | 5` のような 1 行の記法を、YAML
+  / JSON のデータファイルとテンプレートを組み合わせて展開する汎用の Ruby ライブラリです。抽出条件、並べ替え、件数、スタイルを指定できます。
 email:
 - contact@atelier-mirai.net
 executables:
@@ -88,9 +88,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- Gemfile
+- CHANGELOG.md
 - LICENSE
 - README.md
+- RELEASE_NOTE.md
 - bin/query-stream
 - lib/query_stream.rb
 - lib/query_stream/command.rb
@@ -117,14 +118,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '4.0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
-summary: QueryStream - YAML/JSON data renderer with template expansion
+summary: YAML / JSON のデータとテンプレートから、文章中の 1 行の記法を展開する Ruby ライブラリ
 test_files: []

data/Gemfile

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-gemspec