query-stream 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cde26fe750e8ad95270ff7d757ace2e9401fffa40d1d4bfaef36e090dcff9e5c
+  data.tar.gz: 47628d365441535243d08a4ac109ce8e102e1401a5c14e6d31519f39948d1707
+SHA512:
+  metadata.gz: 6b795dcb38ab09d478ebab374e129d7121ff7a15e7fabba554629278cd94b2f47dda90af400f8b9a42eb87df99aa632af01edf92b3238fc1efeebe0f9ade3a3e
+  data.tar.gz: fb34d776cde2a2f7665c22bb22c446687543ee104591bee2e712dabe572c0f4b3652b8a215ce5f7890ca581705e452317510c6f256c42c2d69e65c2efd359ae8

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,41 @@
+MIT License
+
+Copyright (c) 2025 Atelier Mirai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+# 日本語訳（参考）
+
+MIT ライセンス
+
+Copyright (c) 2025 Atelier Mirai
+
+本ソフトウェアおよび関連ドキュメントファイル（以下「ソフトウェア」）の複製を取得したすべての人に対して、
+ソフトウェアを制限なく扱うことを無償で許可します。これには、ソフトウェアの複製を使用、複製、変更、
+結合、公表、頒布、サブライセンス、および/または販売する権利、およびソフトウェアを提供された人が
+そうすることを許可する権利も含まれますが、それらに限定されません。
+
+上記の著作権表示およびこの許可表示を、ソフトウェアのすべての複製または重要な部分に含めるものとします。
+
+本ソフトウェアは「現状のまま」提供され、明示または黙示を問わず、商品性、特定目的への適合性、
+および権利の非侵害を含むがそれらに限定されないいかなる保証もありません。
+著作権者または権利者は、ソフトウェアに関して、契約、不法行為、またはその他の方法で
+発生するいかなる請求、損害、責任についても責任を負いません。

data/README.md

@@ -0,0 +1,115 @@
+# QueryStream
+
+YAML/JSON データファイルとテンプレートファイルを組み合わせて、テキストコンテンツ内の QueryStream 記法を展開する汎用 Ruby ライブラリ。
+
+## インストール
+
+```ruby
+# Gemfile
+gem 'query-stream'
+```
+
+```bash
+bundle install
+```
+
+## 基本的な使い方
+
+```ruby
+require 'query_stream'
+
+# テキスト内の QueryStream 記法を展開
+source = File.read('contents/05-references.md')
+result = QueryStream.render(source)
+```
+
+## QueryStream 記法
+
+```
+= [源泉] | [抽出条件] | [ソート] | [件数] | [スタイル]
+```
+
+### 例
+
+```
+= books                           # 全件展開
+= books | tags=ruby               # タグで絞り込み
+= books | tags=ruby | -title | 5  # 絞り込み＋降順ソート＋5件
+= book | 楽しいRuby               # 主キーで一件検索
+= books | :full                   # fullスタイルで展開
+```
+
+### 具体例：vivlio-style での書籍データ展開
+
+#### データファイル例 (`data/books.yml`)
+
+```yaml
+- title: 楽しいRuby
+  author: 
+    name: 高橋征義
+  desc: Rubyを楽しく学べる入門書。
+  cover: ruby.webp
+
+- title: はじめてのC
+  author: 
+    name: 柴田望洋
+  desc: C言語の定番入門書。
+  cover: c.webp
+```
+
+#### テンプレートファイル例 (`templates/_book.md`)
+
+```markdown
+:::{.book-card}
+![](cover)
+**=title**
+=desc
+:::
+```
+
+#### Markdown記述
+
+```markdown
+## 参考書籍
+
+= books
+
+---
+```
+
+#### 展開結果
+
+```markdown
+## 参考書籍
+
+:::{.book-card}
+![](ruby.webp)
+**楽しいRuby**
+Rubyを楽しく学べる入門書。
+:::
+
+:::{.book-card}
+![](c.webp)
+**はじめてのC**
+C言語の定番入門書。
+:::
+
+---
+```
+
+VFMフェンス記法（`:::{.book-card}`）にも対応しており、各レコードが個別のフェンスで囲まれて展開されます。
+
+## 設定
+
+```ruby
+QueryStream.configure do |config|
+  config.data_dir       = 'data'
+  config.templates_dir  = 'templates'
+  config.default_format = :md
+  config.logger         = Logger.new($stdout)
+end
+```
+
+## ライセンス
+
+MIT License

data/bin/query-stream

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'query_stream'
+require 'query_stream/command'
+
+QueryStream::Command::Top.call(ARGV)

data/lib/query_stream/command.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'samovar'
+
+# ================================================================
+# File: lib/query_stream/command.rb
+# ================================================================
+# 責務:
+#   QueryStream の CLI コマンド。--version のみ提供する。
+# ================================================================
+
+module QueryStream
+  module Command
+    # トップレベルコマンド
+    class Top < Samovar::Command
+      self.description = 'QueryStream - YAML/JSON data renderer'
+
+      options do
+        option '--version', 'Print version and exit'
+      end
+
+      # コマンド実行
+      def call
+        if @options[:version]
+          puts "query-stream #{QueryStream::VERSION}"
+        else
+          print_usage
+        end
+      end
+
+      private
+
+      def print_usage
+        puts self.class.description
+        puts "Usage: query-stream [options]"
+        puts "  --version  Print version and exit"
+      end
+    end
+  end
+end

data/lib/query_stream/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# ================================================================
+# File: lib/query_stream/configuration.rb
+# ================================================================
+# 責務:
+#   QueryStream のグローバル設定を管理する。
+#   data_dir, templates_dir, default_format, logger の4項目。
+# ================================================================
+
+module QueryStream
+  # グローバル設定クラス
+  class Configuration
+    # @return [String] データファイルのディレクトリ
+    attr_accessor :data_dir
+
+    # @return [String] テンプレートファイルのディレクトリ
+    attr_accessor :templates_dir
+
+    # @return [Symbol] スタイル省略時のデフォルト出力形式（:md / :html / :json）
+    attr_accessor :default_format
+
+    # @return [Logger] ログ出力先
+    attr_accessor :logger
+
+    def initialize
+      @data_dir       = 'data'
+      @templates_dir  = 'templates'
+      @default_format = :md
+      @logger         = Logger.new($stdout)
+    end
+  end
+end

data/lib/query_stream/data_resolver.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'json'
+
+# ================================================================
+# File: lib/query_stream/data_resolver.rb
+# ================================================================
+# 責務:
+#   データファイルの探索・単数形/複数形の自動解決を行う。
+#   YAML (.yml, .yaml) と JSON (.json) をサポートする。
+# ================================================================
+
+module QueryStream
+  # データファイル探索・読み込みモジュール
+  module DataResolver
+    # サポートする拡張子（優先順位順）
+    EXTENSIONS = %w[.yml .yaml .json].freeze
+
+    module_function
+
+    # データファイルのパスを解決する
+    # 指定名そのまま → 複数形（末尾に s を付与）→ 単数形の順で探索する
+    # @param source_name [String] データ名（単数形または複数形）
+    # @param data_dir [String] データディレクトリ
+    # @return [String, nil] 見つかったファイルパス、または nil
+    def resolve(source_name, data_dir)
+      # そのまま試行
+      found = find_with_extensions(source_name, data_dir)
+      return found if found
+
+      # 複数形を試行（単数形→複数形: book → books）
+      found = find_with_extensions("#{source_name}s", data_dir)
+      return found if found
+
+      # 単数形を試行（複数形→単数形: books → book）
+      singular = Singularize.call(source_name)
+      if singular != source_name
+        found = find_with_extensions(singular, data_dir)
+        return found if found
+      end
+
+      nil
+    end
+
+    # レコード群をファイルから読み込む
+    # @param file_path [String] データファイルパス
+    # @return [Array<Hash>] レコード群（シンボルキー）
+    def load_records(file_path)
+      records = case File.extname(file_path).downcase
+                when '.json'
+                  JSON.parse(File.read(file_path, encoding: 'utf-8'), symbolize_names: true)
+                else
+                  YAML.load_file(file_path, symbolize_names: true)
+                end
+
+      records = [records] if records.is_a?(Hash)
+      records
+    end
+
+    # 指定名ですべての拡張子を試行する
+    # @param base_name [String] 拡張子なしファイル名
+    # @param data_dir [String] データディレクトリ
+    # @return [String, nil] 見つかったファイルパス、または nil
+    def find_with_extensions(base_name, data_dir)
+      EXTENSIONS.each do |ext|
+        path = File.join(data_dir, "#{base_name}#{ext}")
+        return path if File.exist?(path)
+      end
+      nil
+    end
+  end
+end

data/lib/query_stream/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# ================================================================
+# File: lib/query_stream/errors.rb
+# ================================================================
+# 責務:
+#   QueryStream の例外クラス体系を定義する。
+#   ERROR系は処理を中断し、WARNING系は処理を続行する。
+# ================================================================
+
+module QueryStream
+  # 基底クラス
+  class Error   < StandardError; end
+  class Warning < StandardError; end
+
+  # ERROR系（処理を中断）
+  class TemplateNotFoundError < Error; end   # テンプレートファイルが存在しない
+  class DataNotFoundError    < Error; end    # データファイルが存在しない
+  class UnknownKeyError      < Error; end    # テンプレート内に存在しないキー
+  class InvalidDateError     < Error; end    # 無効な日付
+
+  # WARNING系（処理を続行）
+  class AmbiguousQueryWarning < Warning; end # 一件検索で複数件ヒット
+  class NoResultWarning       < Warning; end # 一件検索で0件ヒット
+end

data/lib/query_stream/filter_engine.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'date'
+
+# ================================================================
+# File: lib/query_stream/filter_engine.rb
+# ================================================================
+# 責務:
+#   AND/OR/比較/Range によるフィルタリングとソート処理を行う。
+#   日付の自動正規化にも対応する。
+# ================================================================
+
+module QueryStream
+  # フィルタリング＆ソートエンジンモジュール
+  module FilterEngine
+    module_function
+
+    # フィルタ条件をレコード群に適用する
+    # @param records [Array<Hash>] レコード群
+    # @param filters [Array<Hash>] フィルタ条件の配列
+    # @return [Array<Hash>] フィルタ後のレコード群
+    def apply_filters(records, filters)
+      return records if filters.nil? || filters.empty?
+
+      records.select do |record|
+        filters.all? { evaluate_filter(record, it) }
+      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
+    end
+
+    # 単一フィルタ条件をレコードに対して評価する
+    # @param record [Hash] 単一レコード
+    # @param filter [Hash] フィルタ条件 { field:, op:, value: }
+    # @return [Boolean] 条件に合致するか
+    def evaluate_filter(record, filter)
+      # 主キー検索（_primary_key）の特別処理
+      if filter[:field] == :_primary_key
+        return evaluate_primary_key_lookup(record, filter[:value])
+      end
+
+      field_value = 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 :range
+        range = filter[:value]
+        range.cover?(to_comparable(field_value))
+      else
+        false
+      end
+    end
+
+    # 主キー候補フィールドを順番に走査して一致するものを探す
+    # @param record [Hash] 単一レコード
+    # @param query_value [Object] 検索値
+    # @return [Boolean] いずれかの主キー候補と一致するか
+    def evaluate_primary_key_lookup(record, query_value)
+      QueryStreamParser::PRIMARY_KEY_FIELDS.any? do |key|
+        record[key]&.to_s == query_value.to_s
+      end
+    end
+
+    # 等値比較（配列・カンマ区切り文字列を透過的に扱う）
+    # データ側が配列/カンマ区切りの場合、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 }
+
+      # フィールド側の値リストと条件値リストに交差があれば一致
+      (field_list & value_list).any?
+    end
+
+    # フィールド値をリスト化する（配列/カンマ区切り/単値を統一）
+    def normalize_to_list(value)
+      case value
+      when Array
+        value.map { it.to_s.strip }
+      when String
+        value.split(',').map { it.strip }
+      when nil
+        []
+      else
+        [value.to_s.strip]
+      end
+    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
+        # 数値変換を試みる
+        case value
+        when /\A-?\d+\z/
+          value.to_i
+        when /\A-?\d+\.\d+\z/
+          value.to_f
+        else
+          value
+        end
+      when Integer, Float
+        value
+      else
+        value.to_s
+      end
+    end
+  end
+end