prompter-ruby 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62d43dac53307b79d18f84fcf1c40fd88dbf19a5c337b9e914c13fa010b73dbe
+  data.tar.gz: 7e2c23ca40c7178b0821bf105bd4389a33b2f293ca4ae76551b762262b17e9d2
+SHA512:
+  metadata.gz: 630c8c261d232440ac6335e0d479a8933b9e2c8f57379d63a5a94da0af59aabc9cabd1c32e549b07663c14902d8f70dcf3d9cc211832900a6b6f81b61f4e3ff6
+  data.tar.gz: 170c646d22cd2e94a1f63772f1772660acd4f33e9cc0215ba5432d29766df0560c9be3114b904cdf1b3c8116fe30226adacb7318a8f95cf749b4265a7da71f89

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (2026-03-09)
+
+- Initial release
+- Template parser with variables, conditionals, and loops
+- Dot notation for nested variables
+- If/else/endif blocks with truthiness evaluation
+- For/endfor loops over collections
+- Negation support
+- File-based prompt library with versioning
+- Template caching

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johannes Dwi Cahyo
+
+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 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.

data/README.md

@@ -0,0 +1,37 @@
+# prompter-ruby
+
+Prompt template engine for Ruby with variables, conditionals, loops, and versioning.
+
+## Installation
+
+```ruby
+gem "prompter-ruby", "~> 0.1"
+```
+
+## Usage
+
+```ruby
+require "prompter_ruby"
+
+result = PrompterRuby.render("Hello {{name}}!", name: "World")
+
+template = PrompterRuby::Template.new(<<~PROMPT)
+  You are {{bot_name}}.
+  {% if context %}Context: {{context}}{% endif %}
+  {% for rule in rules %}- {{rule}}
+  {% endfor %}
+PROMPT
+
+result = template.render(
+  bot_name: "Max",
+  context: "Some info",
+  rules: ["Be concise", "Be helpful"]
+)
+
+library = PrompterRuby::Library.new("./prompts/")
+template = library.get("rag_answer", version: "v2")
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: :test

data/lib/prompter_ruby/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class RenderError < Error; end
+  class UndefinedVariableError < RenderError; end
+  class TemplateNotFoundError < Error; end
+end

data/lib/prompter_ruby/library.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  class Library
+    def initialize(path)
+      @path = path
+      @cache = {}
+    end
+
+    def get(name, version: nil)
+      cache_key = "#{name}:#{version || "latest"}"
+      @cache[cache_key] ||= load_template(name, version: version)
+    end
+
+    def list
+      Dir.glob(File.join(@path, "**/*.{txt,prompt,md}")).map do |f|
+        relative = f.sub("#{@path}/", "")
+        relative.sub(/\.[^.]+$/, "")
+      end.sort
+    end
+
+    def clear_cache
+      @cache = {}
+    end
+
+    private
+
+    def load_template(name, version: nil)
+      file_path = find_template_file(name, version: version)
+      raise TemplateNotFoundError, "Template not found: #{name}" unless file_path
+
+      source = File.read(file_path)
+      Template.new(source)
+    end
+
+    def find_template_file(name, version: nil)
+      extensions = %w[.txt .prompt .md]
+
+      if version
+        extensions.each do |ext|
+          path = File.join(@path, "#{name}.#{version}#{ext}")
+          return path if File.exist?(path)
+        end
+
+        extensions.each do |ext|
+          path = File.join(@path, name, "#{version}#{ext}")
+          return path if File.exist?(path)
+        end
+      end
+
+      extensions.each do |ext|
+        path = File.join(@path, "#{name}#{ext}")
+        return path if File.exist?(path)
+      end
+
+      nil
+    end
+  end
+end

data/lib/prompter_ruby/nodes/for_node.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  module Nodes
+    class ForNode
+      def initialize(item_name, collection_name, body_nodes)
+        @item_name = item_name.strip
+        @collection_name = collection_name.strip
+        @body_nodes = body_nodes
+      end
+
+      def render(context)
+        collection = resolve_collection(context)
+        return "" unless collection.is_a?(Enumerable)
+
+        collection.map do |item|
+          loop_context = context.merge(@item_name.to_sym => item)
+          @body_nodes.map { |n| n.render(loop_context) }.join
+        end.join
+      end
+
+      private
+
+      def resolve_collection(context)
+        parts = @collection_name.split(".")
+        value = context
+
+        parts.each do |part|
+          if value.is_a?(Hash)
+            key = value.key?(part.to_sym) ? part.to_sym : part
+            value = value[key]
+          else
+            return []
+          end
+        end
+
+        value
+      end
+    end
+  end
+end

data/lib/prompter_ruby/nodes/if_node.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  module Nodes
+    class IfNode
+      def initialize(condition, true_nodes, false_nodes = [])
+        @condition = condition.strip
+        @true_nodes = true_nodes
+        @false_nodes = false_nodes
+      end
+
+      def render(context)
+        if evaluate_condition(context)
+          @true_nodes.map { |n| n.render(context) }.join
+        else
+          @false_nodes.map { |n| n.render(context) }.join
+        end
+      end
+
+      private
+
+      def evaluate_condition(context)
+        negate = false
+        condition = @condition
+
+        if condition.start_with?("not ")
+          negate = true
+          condition = condition.sub("not ", "").strip
+        end
+
+        value = resolve_value(condition, context)
+        result = truthy?(value)
+        negate ? !result : result
+      end
+
+      def resolve_value(name, context)
+        parts = name.split(".")
+        value = context
+
+        parts.each do |part|
+          if value.is_a?(Hash)
+            key = value.key?(part.to_sym) ? part.to_sym : part
+            value = value[key]
+          elsif value.respond_to?(part)
+            value = value.send(part)
+          else
+            return nil
+          end
+        end
+
+        value
+      end
+
+      def truthy?(value)
+        return false if value.nil?
+        return false if value == false
+        return false if value.respond_to?(:empty?) && value.empty?
+
+        true
+      end
+    end
+  end
+end

data/lib/prompter_ruby/nodes/text_node.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  module Nodes
+    class TextNode
+      attr_reader :text
+
+      def initialize(text)
+        @text = text
+      end
+
+      def render(_context)
+        @text
+      end
+    end
+  end
+end

data/lib/prompter_ruby/nodes/variable_node.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  module Nodes
+    class VariableNode
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.strip
+      end
+
+      def render(context)
+        value = resolve(context)
+
+        if value.nil? && context[:__strict__]
+          raise UndefinedVariableError, "Undefined variable: '#{@name}'"
+        end
+
+        value.to_s
+      end
+
+      private
+
+      def resolve(context)
+        parts = @name.split(".")
+        value = context
+
+        parts.each do |part|
+          next if part == "__strict__"
+
+          if value.is_a?(Hash)
+            key = value.key?(part.to_sym) ? part.to_sym : part
+            if value.key?(key)
+              value = value[key]
+            else
+              return nil
+            end
+          elsif value.respond_to?(part)
+            value = value.send(part)
+          else
+            return nil
+          end
+        end
+
+        value
+      end
+    end
+  end
+end

data/lib/prompter_ruby/parser.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  class Parser
+    VARIABLE_PATTERN = /\{\{(.*?)\}\}/
+    TAG_PATTERN = /\{%(.*?)%\}/
+
+    def parse(source)
+      tokens = tokenize(source)
+      tokens = strip_tag_whitespace(tokens)
+      parse_nodes(tokens, stop_tags: [], open_tag: nil, open_line: nil)
+    end
+
+    private
+
+    def tokenize(source)
+      tokens = []
+      scanner = source
+      offset = 0
+
+      while scanner.length > 0
+        var_match = scanner.match(VARIABLE_PATTERN)
+        tag_match = scanner.match(TAG_PATTERN)
+
+        next_match = nil
+        next_pos = scanner.length
+
+        if var_match && var_match.begin(0) < next_pos
+          next_match = :variable
+          next_pos = var_match.begin(0)
+        end
+
+        if tag_match && tag_match.begin(0) < next_pos
+          next_match = :tag
+          next_pos = tag_match.begin(0)
+        end
+
+        if next_pos > 0
+          tokens << [:text, scanner[0...next_pos], line_number(source, offset)]
+        end
+
+        case next_match
+        when :variable
+          tokens << [:variable, var_match[1], line_number(source, offset + var_match.begin(0))]
+          offset += var_match.end(0)
+          scanner = scanner[var_match.end(0)..]
+        when :tag
+          tokens << [:tag, tag_match[1].strip, line_number(source, offset + tag_match.begin(0))]
+          offset += tag_match.end(0)
+          scanner = scanner[tag_match.end(0)..]
+        else
+          break
+        end
+      end
+
+      tokens
+    end
+
+    def line_number(source, offset)
+      source[0...offset].count("\n") + 1
+    end
+
+    # Strip whitespace around tag-only lines.
+    # If a tag sits alone on a line (only whitespace before/after it on that line),
+    # remove that whitespace and the trailing newline so the tag line vanishes.
+    def strip_tag_whitespace(tokens)
+      result = []
+
+      tokens.each_with_index do |token, i|
+        if token[0] == :tag
+          # Check if preceding text ends with only whitespace since last newline
+          # and following text starts with only a newline (possibly preceded by whitespace)
+          prev_idx = result.length - 1
+          next_idx = i + 1
+
+          prev_is_blank_tail = false
+          next_is_blank_head = false
+
+          # Check text before tag: ends with \n followed by only spaces/tabs (or is start of string with only spaces/tabs)
+          if prev_idx >= 0 && result[prev_idx][0] == :text
+            text = result[prev_idx][1]
+            prev_is_blank_tail = text.match?(/(?:\A|(?<=\n))[ \t]*\z/)
+          elsif prev_idx < 0
+            # Tag is at the very start
+            prev_is_blank_tail = true
+          end
+
+          # Check text after tag: starts with optional spaces/tabs then \n (or is end of string)
+          if next_idx < tokens.length && tokens[next_idx][0] == :text
+            text = tokens[next_idx][1]
+            next_is_blank_head = text.match?(/\A[ \t]*\n/) || text.match?(/\A[ \t]*\z/)
+          elsif next_idx >= tokens.length
+            # Tag is at the very end
+            next_is_blank_head = true
+          end
+
+          if prev_is_blank_tail && next_is_blank_head
+            # Trim trailing whitespace from previous text node (after last newline)
+            if prev_idx >= 0 && result[prev_idx][0] == :text
+              text = result[prev_idx][1]
+              trimmed = text.sub(/(?:(?<=\n)|(?:\A))[ \t]*\z/, "")
+              if trimmed.empty?
+                result.pop
+              else
+                result[prev_idx] = [:text, trimmed, result[prev_idx][2]]
+              end
+            end
+
+            result << token
+
+            # Mark next text token for trimming (leading whitespace + first newline)
+            if next_idx < tokens.length && tokens[next_idx][0] == :text
+              text = tokens[next_idx][1]
+              trimmed = text.sub(/\A[ \t]*\n/, "")
+              if trimmed.empty?
+                # Skip this text token entirely - will be handled by replacing in tokens
+                tokens[next_idx] = [:text_skip, "", tokens[next_idx][2]]
+              else
+                tokens[next_idx] = [:text, trimmed, tokens[next_idx][2]]
+              end
+            end
+          else
+            result << token
+          end
+        elsif token[0] == :text_skip
+          # Skip tokens marked for removal
+          next
+        else
+          result << token
+        end
+      end
+
+      result
+    end
+
+    def parse_nodes(tokens, stop_tags:, open_tag:, open_line:)
+      nodes = []
+      index = 0
+
+      while index < tokens.length
+        type, value, line = tokens[index]
+
+        case type
+        when :text
+          nodes << Nodes::TextNode.new(value)
+          index += 1
+        when :variable
+          nodes << Nodes::VariableNode.new(value)
+          index += 1
+        when :tag
+          if stop_tags.any? { |tag| value.start_with?(tag) }
+            return [nodes, index]
+          end
+
+          if value.start_with?("if ")
+            condition = value.sub("if ", "").strip
+            result = parse_nodes(tokens[(index + 1)..], stop_tags: ["else", "elsif", "endif"], open_tag: "if", open_line: line)
+
+            if result.is_a?(Array) && result.length == 2
+              true_nodes, end_index = result
+            else
+              raise ParseError, "Unclosed 'if' block starting at line #{line}"
+            end
+
+            index = index + 1 + end_index
+
+            false_nodes = []
+            if tokens[index] && tokens[index][1]&.start_with?("else")
+              else_line = tokens[index][2]
+              result = parse_nodes(tokens[(index + 1)..], stop_tags: ["endif"], open_tag: "else", open_line: else_line)
+
+              if result.is_a?(Array) && result.length == 2
+                false_nodes, end_index = result
+              else
+                raise ParseError, "Unclosed 'else' block starting at line #{else_line}"
+              end
+
+              index = index + 1 + end_index
+            end
+
+            # Verify we actually landed on endif
+            unless tokens[index] && tokens[index][1]&.start_with?("endif")
+              raise ParseError, "Unclosed 'if' block starting at line #{line}"
+            end
+
+            index += 1
+
+            nodes << Nodes::IfNode.new(condition, true_nodes, false_nodes)
+          elsif value.start_with?("for ")
+            match = value.match(/for\s+(\w+)\s+in\s+(\S+)/)
+            raise ParseError, "Invalid for syntax: #{value}" unless match
+
+            item_name = match[1]
+            collection_name = match[2]
+
+            result = parse_nodes(tokens[(index + 1)..], stop_tags: ["endfor"], open_tag: "for", open_line: line)
+
+            if result.is_a?(Array) && result.length == 2
+              body_nodes, end_index = result
+            else
+              raise ParseError, "Unclosed 'for' block starting at line #{line}"
+            end
+
+            # Verify we actually landed on endfor
+            unless tokens[index + 1 + end_index] && tokens[index + 1 + end_index][1]&.start_with?("endfor")
+              raise ParseError, "Unclosed 'for' block starting at line #{line}"
+            end
+
+            index = index + 1 + end_index + 1
+
+            nodes << Nodes::ForNode.new(item_name, collection_name, body_nodes)
+          else
+            nodes << Nodes::TextNode.new("{%#{value}%}")
+            index += 1
+          end
+        end
+      end
+
+      if stop_tags.any?
+        raise ParseError, "Unclosed '#{open_tag}' block starting at line #{open_line}"
+      end
+
+      nodes
+    end
+  end
+end

data/lib/prompter_ruby/template.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  class Template
+    attr_reader :source
+
+    def initialize(source)
+      raise ArgumentError, "Template source cannot be nil" if source.nil?
+
+      @source = source
+      @parser = Parser.new
+      @nodes = @parser.parse(source)
+    end
+
+    def render(variables = {})
+      raise ArgumentError, "Variables must be a Hash" unless variables.is_a?(Hash)
+
+      context = normalize_keys(variables)
+
+      if context.delete(:strict)
+        context[:__strict__] = true
+      end
+
+      @nodes.map { |node| node.render(context) }.join
+    end
+
+    def valid?
+      validate!
+      true
+    rescue ParseError
+      false
+    end
+
+    def validate!
+      @parser.parse(@source)
+      true
+    end
+
+    private
+
+    def normalize_keys(hash)
+      hash.transform_keys(&:to_sym)
+    end
+  end
+end

data/lib/prompter_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PrompterRuby
+  VERSION = "0.1.1"
+end

data/lib/prompter_ruby.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "prompter_ruby/version"
+require_relative "prompter_ruby/errors"
+require_relative "prompter_ruby/nodes/text_node"
+require_relative "prompter_ruby/nodes/variable_node"
+require_relative "prompter_ruby/nodes/if_node"
+require_relative "prompter_ruby/nodes/for_node"
+require_relative "prompter_ruby/parser"
+require_relative "prompter_ruby/template"
+require_relative "prompter_ruby/library"
+
+module PrompterRuby
+  class << self
+    def render(source, variables = {})
+      Template.new(source).render(variables)
+    end
+
+    def library(path)
+      Library.new(path)
+    end
+  end
+end

data/prompter-ruby.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/prompter_ruby/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "prompter-ruby"
+  spec.version = PrompterRuby::VERSION
+  spec.authors = ["Johannes Dwi Cahyo"]
+  spec.email = ["johannes@example.com"]
+  spec.summary = "Prompt template engine for Ruby"
+  spec.description = "Shared prompt template engine with variables, conditionals, loops, and prompt versioning. Replaces ad-hoc templating across LLM gems."
+  spec.homepage = "https://github.com/johannesdwicahyo/prompter-ruby"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "Rakefile",
+    "prompter-ruby.gemspec"
+  ]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: prompter-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Johannes Dwi Cahyo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Shared prompt template engine with variables, conditionals, loops, and
+  prompt versioning. Replaces ad-hoc templating across LLM gems.
+email:
+- johannes@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/prompter_ruby.rb
+- lib/prompter_ruby/errors.rb
+- lib/prompter_ruby/library.rb
+- lib/prompter_ruby/nodes/for_node.rb
+- lib/prompter_ruby/nodes/if_node.rb
+- lib/prompter_ruby/nodes/text_node.rb
+- lib/prompter_ruby/nodes/variable_node.rb
+- lib/prompter_ruby/parser.rb
+- lib/prompter_ruby/template.rb
+- lib/prompter_ruby/version.rb
+- prompter-ruby.gemspec
+homepage: https://github.com/johannesdwicahyo/prompter-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/johannesdwicahyo/prompter-ruby
+  source_code_uri: https://github.com/johannesdwicahyo/prompter-ruby
+  changelog_uri: https://github.com/johannesdwicahyo/prompter-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Prompt template engine for Ruby
+test_files: []