sql_beautifier 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae905b6c37cef236a53ae510743055f7c5fb5c184a1513152920aeaa23b6f79b
-  data.tar.gz: ed5e4c3e0207d1cdf9f600852661fca974bd4f435d1e6c32fd3d471ab46e6288
+  metadata.gz: 189e4fb1ebb3e61fa40afa896d3ac83897714fb3236f3ef27a1a97da03c82fea
+  data.tar.gz: 9143a35ed8be4d33372d1d82bb05ec52d8acf3eb2ce34ea5880e0b7e5e53b2f9
 SHA512:
-  metadata.gz: ef28e0c0853fb740d677be87061c284aeae9c8e5f0ed62f4d34417577d58c5ac87bcc0072c88a6f8bcfdac52a4cae3ff335cf8f1de07a9d1c7b3ba67533ed820
-  data.tar.gz: 3f8f35358960a0c0015026251799621ee0a775aaa066a4dc53de36c4a973920f0f76052cfced812a861e4b372e88ca22430c432f77c1537642d6303c0468501a
+  metadata.gz: 991c1470b7beb1db6c405b709d5ee96f9d7562c27882e5a4f8269a2f3680d50a3787c326df87bd04c7331cab0b87f7c5b87867f03a094f5628f39cfaf0376bd9
+  data.tar.gz: a8cc4f9eed82b92905be0961adea425731ad5741e941b5eb6aa669341dbc1bb97ba6540721f9734497009823075769257fccae7ae4416b84ba76fa172b5d6694

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [X.X.X] - YYYY-MM-DD
 
+## [0.7.0] - 2026-03-29
+
+- Introduce `Query` entity encapsulating parsed clauses, depth, table registry, compact detection, and subquery formatting — `Formatter` delegates clause assembly and rendering to `Query`, and `SubqueryFormatter` is eliminated
+- Introduce `CteQuery` and `CteDefinition` entities replacing `CteFormatter` — CTE parsing produces structured objects that render themselves
+- Introduce `CreateTableAs` entity replacing `CreateTableAsFormatter` — structured object with modifier, if-not-exists, table name, body query, and suffix
+- Introduce `Condition` tree model replacing flat `[conjunction, text]` pairs — parsed into leaf and group nodes with recursive rendering; eliminates `ConditionFormatter`
+- Extract `Scanner` class consolidating duplicated character-by-character scanning logic across seven modules
+- Consolidate `CommentStripper` and `CommentRestorer` into `CommentParser`
+- Introduce `TableReference` and `Join` entities — `Clauses::From` delegates join rendering to `Join#render`; `TableRegistry` holds `TableReference` objects instead of raw hashes
+- Introduce `Expression` entity for SELECT list items and `SortExpression` entity for ORDER BY items
+- Introduce `Comment` entity with `content`, `type`, and `renderable` attributes
+
 ## [0.6.0] - 2026-03-28
 
 - **Breaking**: comments are now preserved by default. Set `removable_comment_types = :all` to restore previous behavior of stripping all comments

data/README.md

@@ -445,12 +445,12 @@ end
 Controls which SQL comment types are stripped during formatting. Default: `:none`.
 
 - `:none` — preserves all comments in the formatted output
-- `:all` — strips all comments (equivalent to `[:inline, :separate_line, :blocks]`)
+- `:all` — strips all comments (equivalent to `[:inline, :line, :blocks]`)
 - Array of specific types — strips only the listed types, preserving the rest
 
 The three comment types:
 
-- `:separate_line` — `--` comments on their own line (only whitespace before `--`), including banner-style dividers
+- `:line` — `--` comments on their own line (only whitespace before `--`), including banner-style dividers
 - `:inline` — `--` comments at the end of a line that contains SQL
 - `:blocks` — `/* ... */` block comments (single or multi-line)
 

data/lib/sql_beautifier/base.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module SqlBeautifier
+  class Base
+    extend Dry::Initializer
+  end
+end

data/lib/sql_beautifier/clauses/base.rb

@@ -3,8 +3,8 @@
 module SqlBeautifier
   module Clauses
     class Base
-      def self.call(value)
-        new(value).call
+      def self.call(...)
+        new(...).call
       end
 
       def initialize(value)

data/lib/sql_beautifier/clauses/condition_clause.rb

@@ -6,7 +6,7 @@ module SqlBeautifier
       def call
         return "#{keyword_prefix}#{@value.strip}" unless multiple_conditions?
 
-        formatted_conditions = ConditionFormatter.format(@value, indent_width: SqlBeautifier.config_for(:keyword_column_width))
+        formatted_conditions = Condition.format(@value, indent_width: SqlBeautifier.config_for(:keyword_column_width))
         formatted_conditions.sub(continuation_indent, keyword_prefix)
       end
 

data/lib/sql_beautifier/clauses/from.rb

@@ -5,66 +5,41 @@ module SqlBeautifier
     class From < Base
       KEYWORD = "from"
 
-      def self.call(value, table_registry:)
-        new(value, table_registry: table_registry).call
+      def self.call(...)
+        new(...).call
       end
 
       def initialize(value, table_registry:)
         super(value)
+
         @table_registry = table_registry
       end
 
       def call
-        @lines = []
-
         join_parts = split_join_parts
         primary_table_text = join_parts.shift.strip
-        formatted_primary_table_name = format_table_with_alias(primary_table_text)
-        add_line!("#{keyword_prefix}#{formatted_primary_table_name}")
+        primary_reference = @table_registry.reference_for(Util.first_word(primary_table_text))
+        trailing_sentinels = Join.extract_trailing_sentinels(primary_table_text)
 
-        join_parts.each { |join_part| format_join_part(join_part) }
+        lines = []
+        lines << "#{keyword_prefix}#{primary_reference.render(trailing_sentinels: trailing_sentinels)}"
 
-        @lines.join("\n")
-      end
+        join_parts.each do |join_text|
+          join = Join.parse(join_text, table_registry: @table_registry)
+          next unless join
 
-      private
+          lines << join.render(continuation_indent: continuation_indent, condition_indent: join_condition_indentation)
+        end
 
-      def add_line!(line)
-        @lines << line
+        lines.join("\n")
       end
 
+      private
+
       def join_condition_indentation
         Util.whitespace(SqlBeautifier.config_for(:keyword_column_width) + 4)
       end
 
-      def format_join_part(join_part)
-        join_keyword, remaining_join_content = extract_join_keyword(join_part)
-        return unless join_keyword && remaining_join_content
-
-        on_keyword_position = Tokenizer.find_top_level_keyword(remaining_join_content, "on")
-
-        if on_keyword_position
-          format_join_with_conditions(join_keyword, remaining_join_content, on_keyword_position)
-        else
-          formatted_table_name = format_table_with_alias(remaining_join_content)
-          add_line!("#{continuation_indent}#{join_keyword} #{formatted_table_name}")
-        end
-      end
-
-      def format_join_with_conditions(join_keyword, join_content, on_keyword_position)
-        table_text = join_content[0...on_keyword_position].strip
-        condition_text = join_content[on_keyword_position..].delete_prefix("on").strip
-        on_conditions = Tokenizer.split_top_level_conditions(condition_text)
-
-        formatted_table_name = format_table_with_alias(table_text)
-        first_condition = on_conditions.first[1]
-        add_line!("#{continuation_indent}#{join_keyword} #{formatted_table_name} on #{first_condition}")
-
-        on_conditions.drop(1).each do |conjunction, additional_condition|
-          add_line!("#{join_condition_indentation}#{conjunction} #{additional_condition}")
-        end
-      end
-
       def split_join_parts
         from_content = @value.strip
         join_keyword_positions = find_all_join_keyword_positions(from_content)
@@ -122,35 +97,6 @@ module SqlBeautifier
 
         earliest_match
       end
-
-      def extract_join_keyword(join_part)
-        trimmed_join_text = join_part.strip
-
-        Constants::JOIN_KEYWORDS_BY_LENGTH.each do |keyword|
-          next unless trimmed_join_text.downcase.start_with?(keyword)
-
-          remaining_join_content = trimmed_join_text[keyword.length..].strip
-
-          return [keyword, remaining_join_content]
-        end
-
-        [nil, nil]
-      end
-
-      def format_table_with_alias(table_text)
-        table_name = Util.first_word(table_text)
-        formatted_table_name = Util.format_table_name(table_name)
-        table_alias = @table_registry.alias_for(table_name)
-        trailing_sentinels = extract_trailing_sentinels(table_text)
-
-        formatted = table_alias ? "#{formatted_table_name} #{table_alias}" : formatted_table_name
-        trailing_sentinels.empty? ? formatted : "#{formatted} #{trailing_sentinels}"
-      end
-
-      def extract_trailing_sentinels(text)
-        sentinels = text.scan(CommentStripper::SENTINEL_PATTERN).map { |match| "#{CommentStripper::SENTINEL_PREFIX}#{match[0]}#{CommentStripper::SENTINEL_SUFFIX}" }
-        sentinels.join(" ")
-      end
     end
   end
 end

data/lib/sql_beautifier/clauses/order_by.rb

@@ -6,7 +6,18 @@ module SqlBeautifier
       KEYWORD = "order by"
 
       def call
-        "#{keyword_prefix}#{@value.strip}"
+        expressions = parse_expressions(@value)
+        expressions_output = expressions.map(&:render).join(", ")
+
+        "#{keyword_prefix}#{expressions_output}"
+      end
+
+      private
+
+      def parse_expressions(value)
+        Tokenizer.split_by_top_level_commas(value).map do |item|
+          SortExpression.parse(item)
+        end
       end
     end
   end

data/lib/sql_beautifier/clauses/select.rb

@@ -10,34 +10,45 @@ module SqlBeautifier
 
       def call
         prefix, remaining_columns = extract_prefix
-        columns = Tokenizer.split_by_top_level_commas(remaining_columns)
+        @expressions = parse_expressions(remaining_columns)
 
-        return format_with_prefix(prefix, columns) if prefix
-        return keyword_line(columns.first) if columns.length == 1
+        return format_with_prefix(prefix) if prefix
+        return keyword_line(@expressions.first.render) if @expressions.length == 1
 
-        format_columns_list(columns)
+        format_columns_list
       end
 
       private
 
-      def keyword_line(column)
-        "#{keyword_prefix}#{column.strip}"
+      def parse_expressions(value)
+        Tokenizer.split_by_top_level_commas(value).map do |column|
+          Expression.parse(column)
+        end
+      end
+
+      def keyword_line(text)
+        "#{keyword_prefix}#{text.strip}"
       end
 
-      def continuation_line(column)
-        "#{continuation_indent}#{column.strip}"
+      def continuation_line(text)
+        "#{continuation_indent}#{text.strip}"
       end
 
-      def format_with_prefix(prefix, columns)
+      def format_with_prefix(prefix)
         first_line = "#{keyword_prefix}#{prefix}"
-        column_lines = columns.map { |column| continuation_line(column) }
+        column_lines = @expressions.map do |expression|
+          continuation_line(expression.render)
+        end
 
         "#{first_line}\n#{column_lines.join(",\n")}"
       end
 
-      def format_columns_list(columns)
-        column_lines = columns.map { |column| continuation_line(column) }
-        column_lines[0] = keyword_line(columns.first)
+      def format_columns_list
+        column_lines = @expressions.map do |expression|
+          continuation_line(expression.render)
+        end
+
+        column_lines[0] = keyword_line(@expressions.first.render)
 
         column_lines.join(",\n")
       end
@@ -61,11 +72,13 @@ module SqlBeautifier
         opening_parenthesis_position = stripped_value.index(Constants::OPEN_PARENTHESIS, distinct_on_position)
         return [nil, stripped_value] unless opening_parenthesis_position
 
-        closing_parenthesis_position = Tokenizer.find_matching_parenthesis(stripped_value, opening_parenthesis_position)
+        closing_parenthesis_position = Scanner.new(stripped_value).find_matching_parenthesis(opening_parenthesis_position)
         return [nil, stripped_value] unless closing_parenthesis_position
 
         prefix = stripped_value[0..closing_parenthesis_position]
-        remaining_columns = stripped_value[(closing_parenthesis_position + 1)..].strip.sub(LEADING_COMMA_PATTERN, "")
+        columns_text = stripped_value[(closing_parenthesis_position + 1)..]
+        stripped_columns_text = columns_text.strip
+        remaining_columns = stripped_columns_text.sub(LEADING_COMMA_PATTERN, "")
 
         [prefix, remaining_columns]
       end

data/lib/sql_beautifier/comment.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  class Comment < Base
+    TYPES = %i[
+      inline
+      line
+      blocks
+    ].freeze
+
+    param :content
+    option :type, type: Types::Coercible::Symbol.enum(*TYPES), default: -> { :line }
+    option :renderable, type: Types::Bool, optional: true, default: -> { true }
+
+    def renderable?
+      @renderable
+    end
+
+    def render
+      @content
+    end
+  end
+end

data/lib/sql_beautifier/{comment_stripper.rb → comment_parser.rb}

@@ -1,25 +1,64 @@
 # frozen_string_literal: true
 
 module SqlBeautifier
-  class CommentStripper
+  class CommentParser
     SENTINEL_PREFIX = "/*__sqlb_"
     SENTINEL_SUFFIX = "__*/"
     SENTINEL_PATTERN = %r{/\*__sqlb_(\d+)__\*/}
 
-    Result = Struct.new(:stripped_sql, :comment_map)
+    Result = Struct.new(:stripped_sql, :comment_map, :comments)
 
     def self.call(sql, removable_types)
       new(sql, removable_types).call
     end
 
+    def self.restore(formatted_sql, comment_map)
+      return formatted_sql if comment_map.empty?
+
+      result = formatted_sql
+
+      comment_map.each do |index, entry|
+        sentinel = "#{SENTINEL_PREFIX}#{index}#{SENTINEL_SUFFIX}"
+
+        result = begin
+          case entry[:type]
+          when :blocks
+            result.sub(sentinel, entry[:text])
+          when :line
+            result.sub(%r{#{Regexp.escape(sentinel)}[ \n]?}, "#{entry[:text]}\n")
+          when :inline
+            restore_inline_comment(result, sentinel, entry[:text])
+          else
+            result
+          end
+        end
+      end
+
+      result
+    end
+
+    def self.restore_inline_comment(sql, sentinel, comment_text)
+      pattern = %r{ ?#{Regexp.escape(sentinel)}([^\n]*)}
+      sql.sub(pattern) do
+        trailing_content = Regexp.last_match(1)
+
+        if trailing_content.strip.empty?
+          " #{comment_text}"
+        else
+          "#{trailing_content.strip} #{comment_text}"
+        end
+      end
+    end
+
     def initialize(sql, removable_types)
       @sql = sql
       @removal_set = resolve_removal_set(removable_types)
       @output = +""
       @comment_map = {}
+      @comments = []
       @sentinel_index = 0
       @position = 0
-      @pending_separate_line_comments = []
+      @pending_line_comments = []
     end
 
     def call
@@ -31,30 +70,30 @@ module SqlBeautifier
         elsif @in_double_quoted_identifier
           consume_double_quoted_character!(character)
         elsif character == Constants::SINGLE_QUOTE
-          flush_pending_separate_line_comments!
+          flush_pending_line_comments!
           @in_single_quoted_string = true
           @output << character
           @position += 1
         elsif character == Constants::DOUBLE_QUOTE
-          flush_pending_separate_line_comments!
+          flush_pending_line_comments!
           @in_double_quoted_identifier = true
           @output << character
           @position += 1
         elsif line_comment_start?
           handle_line_comment!
         elsif block_comment_start?
-          flush_pending_separate_line_comments!
+          flush_pending_line_comments!
           handle_block_comment!
         else
-          flush_pending_separate_line_comments! unless character == "\n"
+          flush_pending_line_comments! unless character == "\n"
           @output << character
           @position += 1
         end
       end
 
-      flush_pending_separate_line_comments!
+      flush_pending_line_comments!
 
-      Result.new(@output, @comment_map)
+      Result.new(@output, @comment_map, @comments)
     end
 
     private
@@ -64,16 +103,16 @@ module SqlBeautifier
       when :none
         []
       when :all
-        Configuration::COMMENT_TYPES.dup
+        Comment::TYPES.dup
       when Array
-        invalid_types = removable_types - Configuration::COMMENT_TYPES
-        raise ArgumentError, "Unsupported removable_types entries: #{invalid_types.inspect}. Expected elements of #{Configuration::COMMENT_TYPES.inspect}" if invalid_types.any?
+        invalid_types = removable_types - Comment::TYPES
+        raise ArgumentError, "Unsupported removable_types entries: #{invalid_types.inspect}. Expected elements of #{Comment::TYPES.inspect}" if invalid_types.any?
 
         removable_types
-      when *Configuration::COMMENT_TYPES
+      when *Comment::TYPES
         [removable_types]
       else
-        raise ArgumentError, "Unsupported removable_types: #{removable_types.inspect}. Expected :none, :all, an Array, or one of #{Configuration::COMMENT_TYPES.inspect}"
+        raise ArgumentError, "Unsupported removable_types: #{removable_types.inspect}. Expected :none, :all, an Array, or one of #{Comment::TYPES.inspect}"
       end
     end
 
@@ -112,9 +151,11 @@ module SqlBeautifier
     end
 
     def handle_line_comment!
-      comment_type = separate_line_comment? ? :separate_line : :inline
+      comment_type = line_comment? ? :line : :inline
       comment_text = extract_line_comment_text
 
+      @comments << Comment.new(comment_text, type: comment_type, renderable: !removable?(comment_type))
+
       if removable?(comment_type)
         strip_line_comment!
       else
@@ -122,7 +163,7 @@ module SqlBeautifier
       end
     end
 
-    def separate_line_comment?
+    def line_comment?
       line_start = @output.rindex("\n")
       preceding_content = begin
         if line_start
@@ -147,11 +188,11 @@ module SqlBeautifier
     def strip_line_comment!; end
 
     def preserve_line_comment!(comment_type, comment_text)
-      if comment_type == :separate_line
-        @pending_separate_line_comments << comment_text
+      if comment_type == :line
+        @pending_line_comments << comment_text
         @position += 1 if @position < @sql.length && @sql[@position] == "\n"
       else
-        flush_pending_separate_line_comments!
+        flush_pending_line_comments!
         sentinel = build_sentinel(comment_type, comment_text)
         @output << sentinel
       end
@@ -160,6 +201,8 @@ module SqlBeautifier
     def handle_block_comment!
       comment_text = extract_block_comment_text
 
+      @comments << Comment.new(comment_text, type: :blocks, renderable: !removable?(:blocks))
+
       if removable?(:blocks)
         strip_block_comment!
       else
@@ -192,16 +235,16 @@ module SqlBeautifier
       @output << " " unless @output.empty? || @output[-1] =~ Constants::WHITESPACE_CHARACTER_REGEX
     end
 
-    def flush_pending_separate_line_comments!
-      return if @pending_separate_line_comments.empty?
+    def flush_pending_line_comments!
+      return if @pending_line_comments.empty?
 
-      grouped_text = @pending_separate_line_comments.join("\n")
-      sentinel = build_sentinel(:separate_line, grouped_text)
+      grouped_text = @pending_line_comments.join("\n")
+      sentinel = build_sentinel(:line, grouped_text)
 
       @output << sentinel
       @output << "\n"
 
-      @pending_separate_line_comments.clear
+      @pending_line_comments.clear
     end
 
     def build_sentinel(comment_type, comment_text)

data/lib/sql_beautifier/condition.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module SqlBeautifier
+  class Condition < Base
+    option :conjunction, default: -> {}
+    option :expression, default: -> {}
+    option :children, default: -> {}
+
+    def self.format(text, indent_width: 0)
+      conditions = parse_all(text)
+      return text.strip if conditions.length <= 1 && conditions.first&.leaf?
+
+      render_all(conditions, indent_width: indent_width)
+    end
+
+    def self.parse_all(text)
+      raw_pairs = Tokenizer.split_top_level_conditions(text)
+      conditions = raw_pairs.map do |conjunction, condition_text|
+        build(conjunction, condition_text)
+      end
+
+      flatten_same_conjunction_groups(conditions)
+    end
+
+    def self.render_all(conditions, indent_width:)
+      indentation = Util.whitespace(indent_width)
+      lines = []
+
+      conditions.each_with_index do |condition, index|
+        rendered = condition.render(indent_width: indent_width)
+
+        line = begin
+          if index.zero?
+            "#{indentation}#{rendered}"
+          else
+            "#{indentation}#{condition.conjunction} #{rendered}"
+          end
+        end
+
+        lines << line
+      end
+
+      lines.join("\n")
+    end
+
+    def leaf?
+      @children.nil?
+    end
+
+    def group?
+      !leaf?
+    end
+
+    def render(indent_width:)
+      return @expression if leaf?
+
+      inline_version = render_inline
+      return inline_version if inline_version.length <= SqlBeautifier.config_for(:inline_group_threshold)
+
+      inner_output = self.class.render_all(@children, indent_width: indent_width + 4)
+      closing_indentation = Util.whitespace(indent_width)
+
+      "(\n#{inner_output}\n#{closing_indentation})"
+    end
+
+    def self.build(conjunction, condition_text)
+      unwrapped = unwrap_single_condition(condition_text)
+      inner_conditions = parse_condition_group(unwrapped)
+
+      if inner_conditions
+        children = inner_conditions.map do |inner_conjunction, inner_text|
+          build(inner_conjunction, inner_text)
+        end
+
+        new(conjunction: conjunction, children: children)
+      else
+        new(conjunction: conjunction, expression: unwrapped)
+      end
+    end
+
+    def self.unwrap_single_condition(condition_text)
+      output = condition_text.strip
+
+      while Tokenizer.outer_parentheses_wrap_all?(output)
+        inner_content = Util.strip_outer_parentheses(output)
+        inner_conditions = Tokenizer.split_top_level_conditions(inner_content)
+        break if inner_conditions.length > 1
+
+        output = inner_content
+      end
+
+      output
+    end
+
+    def self.parse_condition_group(condition_text)
+      return unless condition_text
+
+      trimmed = condition_text.strip
+      return unless Tokenizer.outer_parentheses_wrap_all?(trimmed)
+
+      inner_content = Util.strip_outer_parentheses(trimmed)
+      inner_conditions = Tokenizer.split_top_level_conditions(inner_content)
+      return unless inner_conditions.length > 1
+
+      inner_conditions
+    end
+
+    def self.flatten_same_conjunction_groups(conditions)
+      return conditions if conditions.length <= 1
+
+      outer_conjunction = conditions[1]&.conjunction
+      return conditions unless outer_conjunction
+      return conditions unless conditions.drop(1).all? { |condition| condition.conjunction == outer_conjunction }
+
+      flattened = []
+
+      conditions.each do |condition|
+        if condition.group? && flattenable_into_conjunction?(condition, outer_conjunction)
+          flatten_group_into!(flattened, condition, outer_conjunction)
+        else
+          flattened << condition
+        end
+      end
+
+      flattened
+    end
+
+    def self.flattenable_into_conjunction?(condition, outer_conjunction)
+      return false unless condition.group?
+
+      inner_conjunction = condition.children[1]&.conjunction
+      inner_conjunction == outer_conjunction && condition.children.drop(1).all? { |child| child.conjunction == outer_conjunction }
+    end
+
+    def self.flatten_group_into!(flattened, group_condition, outer_conjunction)
+      group_condition.children.each_with_index do |child, inner_index|
+        new_conjunction = begin
+          if flattened.empty?
+            nil
+          elsif inner_index.zero?
+            group_condition.conjunction || outer_conjunction
+          else
+            outer_conjunction
+          end
+        end
+
+        flattened << new(conjunction: new_conjunction, expression: child.expression, children: child.children)
+      end
+    end
+
+    protected
+
+    def render_inline
+      parts = @children.map.with_index do |child, index|
+        rendered = child.leaf? ? child.expression : child.render_inline
+        index.zero? ? rendered : "#{child.conjunction} #{rendered}"
+      end
+
+      "(#{parts.join(' ')})"
+    end
+  end
+end