markdown-run 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d87607302aa1e1f4b95d1da2b1857f792d34b3d3d7985299db1a6730d7f49b57
-  data.tar.gz: d10dd3193558ce3c59770bd5b9ba7f73e8a5f3459cea9482deeff7bfc21333a1
+  metadata.gz: 7e078472cf91253d16b3341865954ead4ce1d6539d509c5ed6d54302c5a3147d
+  data.tar.gz: 76f40572409ed01a1797c4902896b783d3a0403783031fca8c8dff04a1499acf
 SHA512:
-  metadata.gz: 1bbf13073d892d85165b1396a78ec6f274cb75a941fd8dc50f21b4c9636572966c2983f001851286fcb14531eed0a3d2177df42f8d1851e98f62175c5b83c78e
-  data.tar.gz: 97f9f35734c1440d8b21cc62176a65458bce898cb223368c65af4e0888f4bbd986dc6e403a382f982561dc6ad572f4f9c24c3f2f41d8c0aa6186cc6d5d25f656
+  metadata.gz: ea3ecacb94cbe3e52dacb9fdb4ea447790990cee631fd890f5389d483157d7e16621eda6dba68dddf13d1e1f5f499b8bc2ac3952e2ca1752f133f5aa496403b1
+  data.tar.gz: 8ae64565dc336f5158a877c54a02520bc6a0e6923c6bbdd705c2cff8c848ff832f0a0683f30c2e86df883a356d89e60269cebb219d9a9732212fc5edfd27fea6

data/CHANGELOG.md

@@ -1,42 +1,53 @@
 ## [Unreleased]
 
+## [0.1.11] - 2025-06-04
+
+-   options are customizable with the yaml frontmatter
+
+## [0.1.10] - 2025-06-03
+
+-   standalone options for codeblocks (run instead of run=true)
+-   explain option for psql code blocks with Dalibo visualization links
+-   Fixed Dalibo URL generation to properly submit plans via HTTP POST
+-   Added result option to control result block visibility (result=false hides result blocks while still executing code)
+
 ## [0.1.9] - 2025-06-02
 
-- mermaid codeblocks
+-   mermaid codeblocks
 
 ## [0.1.8] - 2025-06-01
 
-- Added run option
+-   Added run option
 
 ## [0.1.7] - 2025-06-01
 
-- Added rerun functionality
+-   Added rerun functionality
 
 ## [0.1.6] - 2025-06-01
 
-- Refactor code to state pattern
-- Add yaml frontmatter to support aliases for code blocks
+-   Refactor code to state pattern
+-   Add yaml frontmatter to support aliases for code blocks
 
 ## [0.1.5] - 2025-05-19
 
-- Remove gif files from release
+-   Remove gif files from release
 
 ## [0.1.4] - 2025-05-18
 
-- Add support for zsh, bash, sh
+-   Add support for zsh, bash, sh
 
 ## [0.1.3] - 2025-05-14
 
-- Fix missing minitest dep
+-   Fix missing minitest dep
 
 ## [0.1.2] - 2025-05-14
 
-- Gemfile update
+-   Gemfile update
 
 ## [0.1.1] - 2025-05-14
 
-- Added checks for missing dependencies
+-   Added checks for missing dependencies
 
 ## [0.1.0] - 2025-05-13
 
-- Initial release
+-   Initial release

data/README.md

@@ -57,8 +57,21 @@ example vscode keybinding
 
 - `run=true` or `run=false` to control whether a code block should be executed at all. `run=true` is the default if not specified
 - `rerun=true` or `rerun=false` to control whether a code block should be re-executed if a result block already exists. `rerun=false` is the default if not specified
+- `result=true` or `result=false` to control whether the result block should be displayed after execution. `result=true` is the default if not specified. When `result=false`, the code still executes but the result block is hidden
+- `explain=true` or `explain=false` for psql code blocks to generate query execution plans with Dalibo visualization links. `explain=false` is the default if not specified
 
-Options can be combined. If `run=false` is specified, the code block will not execute regardless of the `rerun` setting.
+Options can be combined. If `run=false` is specified, the code block will not execute regardless of the `rerun` setting. The `result` option only affects display of the result block, not code execution.
+
+### Standalone Option Syntax
+
+Options can also be specified using standalone syntax without explicit `=true`:
+
+- `run` is equivalent to `run=true`
+- `rerun` is equivalent to `rerun=true`
+- `result` is equivalent to `result=true`
+- `explain` is equivalent to `explain=true`
+
+Explicit assignments (e.g., `run=false`) take precedence over standalone options.
 
 Examples:
 
@@ -66,7 +79,7 @@ Examples:
 console.log("This will not execute at all");
 ```
 
-```js rerun=true
+```js rerun
 console.log("This will re-execute even if result exists");
 ```
 
@@ -74,6 +87,23 @@ console.log("This will re-execute even if result exists");
 console.log("This will execute only if no result exists");
 ```
 
+```ruby result=false run
+puts "This executes but the result block is hidden"
+```
+
+```psql explain
+SELECT * FROM users WHERE id = 1;
+```
+
+```psql explain=true
+EXPLAIN (ANALYZE) SELECT * FROM large_table;
+```
+
+```psql result=false explain
+SELECT * FROM large_table;
+-- This will execute the explain query and show the Dalibo link but hide the result block
+```
+
 ### Mermaid diagrams
 
 Mermaid blocks generate SVG files and insert markdown image tags:
@@ -105,6 +135,65 @@ markdown-run:
     - sql: psql
 ```
 
+### Setting Defaults
+
+You can override the default behavior for code block options using frontmatter:
+
+```yaml
+markdown-run:
+  defaults:
+    rerun: true
+    result: false
+  psql:
+    explain: true
+  ruby:
+    rerun: false
+```
+
+**Priority order (highest to lowest):**
+
+1. Explicit options in code blocks (e.g., `rerun=true`)
+2. Language-specific defaults (e.g., `psql: { explain: true }`)
+3. Global defaults (e.g., `defaults: { rerun: true }`)
+4. Built-in application defaults
+
+**Available options for defaults:**
+
+- `run`: Control whether code blocks execute (default: `true`)
+- `rerun`: Control whether to re-execute if result exists (default: `false`)
+- `result`: Control whether to show result blocks (default: `true`)
+- `explain`: For psql blocks, generate explain plans (default: `false`)
+
+**Examples:**
+
+Make all code blocks rerun by default:
+
+```yaml
+markdown-run:
+  defaults:
+    rerun: true
+```
+
+Hide result blocks by default but enable explain for psql:
+
+```yaml
+markdown-run:
+  defaults:
+    result: false
+  psql:
+    explain: true
+```
+
+Language-specific settings override global defaults:
+
+```yaml
+markdown-run:
+  defaults:
+    rerun: false # Global default
+  ruby:
+    rerun: true # Ruby blocks will rerun, others won't
+```
+
 ## Demo
 
 ![VSCode Usage](docs/markdown-run-vscode.gif)

data/lib/code_block_helper.rb

@@ -0,0 +1,62 @@
+module CodeBlockHelper
+  private
+
+  def reset_code_block_state
+    @state = :outside_code_block
+    @current_code_content = ""
+    @current_block_lang = ""
+
+
+    @current_block_rerun = false
+    @current_block_run = true
+    @current_block_explain = false
+    @current_block_result = true
+  end
+
+
+  def start_code_block(current_line, lang, options_string = nil)
+    @output_lines << current_line
+    @current_block_lang = resolve_language(lang)
+    @current_block_rerun = @code_block_parser.parse_rerun_option(options_string, @current_block_lang)
+    @current_block_run = @code_block_parser.parse_run_option(options_string, @current_block_lang)
+    @current_block_explain = @code_block_parser.parse_explain_option(options_string, @current_block_lang)
+    @current_block_result = @code_block_parser.parse_result_option(options_string, @current_block_lang)
+    @state = :inside_code_block
+    @current_code_content = ""
+  end
+
+  def accumulate_code_content(current_line)
+    @current_code_content += current_line
+    @output_lines << current_line
+  end
+
+  def end_code_block(current_line, file_enum)
+    @output_lines << current_line
+
+    decision = decide_execution(file_enum)
+
+    if decision[:execute]
+      # If we consumed lines for rerun, don't add them to output (they'll be replaced)
+      execute_and_add_result(decision[:blank_line])
+    else
+      skip_and_pass_through_result(decision[:lines_to_pass_through], file_enum, decision)
+    end
+
+    reset_code_block_state
+  end
+
+  def decide_execution(file_enum)
+    decider = ExecutionDecider.new(@current_block_run, @current_block_rerun, @current_block_lang, @current_block_explain, @current_block_result)
+    decision = decider.decide(file_enum, method(:result_block_regex))
+
+    # Handle the consume_existing flag for rerun scenarios
+    if decision[:consume_existing]
+      consume_existing_result_block(file_enum, decision[:consumed_lines])
+    elsif decision[:consume_existing_dalibo]
+      # Dalibo links are already consumed in the decision process
+      # Just acknowledge they were consumed
+    end
+
+    decision
+  end
+end

data/lib/code_block_parser.rb

@@ -34,12 +34,24 @@ class CodeBlockParser
     line.strip == BLOCK_END_PATTERN
   end
 
-  def parse_run_option(options_string)
-    parse_boolean_option(options_string, "run", true)
+  def parse_run_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("run", language, true)
+    parse_boolean_option(options_string, "run", default_value)
   end
 
-  def parse_rerun_option(options_string)
-    parse_boolean_option(options_string, "rerun", false)
+  def parse_rerun_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("rerun", language, false)
+    parse_boolean_option(options_string, "rerun", default_value)
+  end
+
+  def parse_explain_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("explain", language, false)
+    parse_boolean_option(options_string, "explain", default_value)
+  end
+
+  def parse_result_option(options_string, language = nil)
+    default_value = @frontmatter_parser.get_default_value("result", language, true)
+    parse_boolean_option(options_string, "result", default_value)
   end
 
   private
@@ -51,10 +63,19 @@ class CodeBlockParser
   def parse_boolean_option(options_string, option_name, default_value)
     return default_value unless options_string
 
-    # Match option=true or option=false
-    match = options_string.match(/#{option_name}\s*=\s*(true|false)/i)
-    return default_value unless match
+    # First, check for explicit option=true/false assignments (highest priority)
+    explicit_match = options_string.match(/#{option_name}\s*=\s*(true|false)/i)
+    if explicit_match
+      return explicit_match[1].downcase == "true"
+    end
+
+    # If no explicit assignment, check for standalone option (e.g., "rerun")
+    standalone_match = options_string.match(/\b#{option_name}\b(?!\s*=)/i)
+    if standalone_match
+      return true
+    end
 
-    match[1].downcase == "true"
+    # If neither found, return default value
+    default_value
   end
 end

data/lib/code_executor.rb

@@ -3,11 +3,11 @@ require "open3"
 require_relative "language_configs"
 
 class CodeExecutor
-  def self.execute(code_content, lang, temp_dir, input_file_path = nil)
-    new.execute(code_content, lang, temp_dir, input_file_path)
+  def self.execute(code_content, lang, temp_dir, input_file_path = nil, explain = false)
+    new.execute(code_content, lang, temp_dir, input_file_path, explain)
   end
 
-  def execute(code_content, lang, temp_dir, input_file_path = nil)
+  def execute(code_content, lang, temp_dir, input_file_path = nil, explain = false)
     lang_key = lang.downcase
     lang_config = SUPPORTED_LANGUAGES[lang_key]
 
@@ -15,34 +15,40 @@ class CodeExecutor
 
     warn "Executing #{lang_key} code block..."
 
-    result = execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path)
-    process_execution_result(result, lang_config, lang_key)
+    result = execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path, explain)
+    process_execution_result(result, lang_config, lang_key, explain)
   end
 
   private
 
+
+
+  def stderr_has_content?(stderr_output)
+    stderr_output && !stderr_output.strip.empty?
+  end
+
   def handle_unsupported_language(lang)
     warn "Unsupported language: #{lang}"
     "ERROR: Unsupported language: #{lang}"
   end
 
-  def execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path = nil)
+  def execute_with_config(code_content, lang_config, temp_dir, lang_key, input_file_path = nil, explain = false)
     cmd_lambda = lang_config[:command]
     temp_file_suffix = lang_config[:temp_file_suffix]
 
     if temp_file_suffix
-      execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path)
+      execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path, explain)
     else
-      execute_direct_command(code_content, cmd_lambda)
+      execute_direct_command(code_content, cmd_lambda, explain)
     end
   end
 
-  def execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path = nil)
+  def execute_with_temp_file(code_content, cmd_lambda, temp_file_suffix, temp_dir, lang_key, input_file_path = nil, explain = false)
     result = nil
     Tempfile.create([lang_key, temp_file_suffix], temp_dir) do |temp_file|
       temp_file.write(code_content)
       temp_file.close
-      command_to_run, exec_options = cmd_lambda.call(code_content, temp_file.path, input_file_path)
+      command_to_run, exec_options = cmd_lambda.call(code_content, temp_file.path, input_file_path, explain)
 
       # Extract output_path if present (for mermaid)
       output_path = exec_options.delete(:output_path) if exec_options.is_a?(Hash)
@@ -58,19 +64,21 @@ class CodeExecutor
     result
   end
 
-  def execute_direct_command(code_content, cmd_lambda)
-    command_to_run, exec_options = cmd_lambda.call(code_content, nil)
+  def execute_direct_command(code_content, cmd_lambda, explain = false)
+    command_to_run, exec_options = cmd_lambda.call(code_content, nil, nil, explain)
     captured_stdout, captured_stderr, captured_status_obj = Open3.capture3(command_to_run, **exec_options)
     { stdout: captured_stdout, stderr: captured_stderr, status: captured_status_obj }
   end
 
-  def process_execution_result(result, lang_config, lang_key)
+  def process_execution_result(result, lang_config, lang_key, explain = false)
     exit_status, result_output, stderr_output = format_captured_output(result, lang_config)
 
     if exit_status != 0
       result_output = add_error_to_output(exit_status, lang_config, lang_key, result_output, stderr_output)
     elsif lang_config && lang_config[:result_handling] == :mermaid_svg
       result_output = handle_mermaid_svg_result(result, lang_key)
+    elsif explain && lang_key == "psql"
+      result_output = handle_psql_explain_result(result_output)
     end
 
     result_output
@@ -118,7 +126,7 @@ class CodeExecutor
     # If the SVG is in a subdirectory, include the directory in the path
     output_dir = File.dirname(output_path)
     svg_filename = File.basename(output_path)
-    
+
     # Check if SVG is in a subdirectory (new behavior) or same directory (fallback)
     parent_dir = File.dirname(output_dir)
     if File.basename(output_dir) != File.basename(parent_dir)
@@ -128,10 +136,77 @@ class CodeExecutor
       # SVG is in same directory (fallback behavior)
       relative_path = svg_filename
     end
-    
+
     warn "Generated Mermaid SVG: #{relative_path}"
 
     # Return markdown image tag instead of typical result content
     "![Mermaid Diagram](#{relative_path})"
   end
+
+  def handle_psql_explain_result(result_output)
+    require 'json'
+    require 'net/http'
+    require 'uri'
+
+    # Try to parse the result as JSON (EXPLAIN output)
+    begin
+      # Clean up the result output and try to parse as JSON
+      json_data = JSON.parse(result_output.strip)
+
+      # Submit plan to Dalibo via POST request
+      dalibo_url = submit_plan_to_dalibo(JSON.generate(json_data))
+
+      if dalibo_url
+        # Return a special format that the markdown processor can parse
+        "DALIBO_LINK:#{dalibo_url}\n#{result_output.strip}"
+      else
+        # If submission failed, just return the original output
+        result_output
+      end
+    rescue JSON::ParserError
+      # If it's not valid JSON, just return the original output
+      result_output
+    end
+  end
+
+  private
+
+  def submit_plan_to_dalibo(plan_json)
+    begin
+      uri = URI('https://explain.dalibo.com/new')
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = 10
+
+      payload = {
+        'plan' => plan_json,
+        'title' => "Query Plan - #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}",
+        'query' => ''
+      }
+
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      request.body = JSON.generate(payload)
+
+      response = http.request(request)
+
+      if response.is_a?(Net::HTTPRedirection)
+        location = response['location']
+        if location
+          if location.start_with?('/')
+            location = "https://explain.dalibo.com#{location}"
+          end
+          location
+        else
+          nil
+        end
+      else
+        warn "Failed to submit plan to Dalibo: #{response.code} #{response.message}"
+        nil
+      end
+    rescue => e
+      warn "Error submitting plan to Dalibo: #{e.message}"
+      nil
+    end
+  end
 end

data/lib/dalibo_helper.rb

@@ -0,0 +1,39 @@
+module DaliboHelper
+  private
+
+  DALIBO_LINK_PREFIX = "DALIBO_LINK:"
+
+  def extract_dalibo_link(result_output)
+    # Check if the result contains a Dalibo link marker
+    if result_output.start_with?(DALIBO_LINK_PREFIX)
+      lines = result_output.split("\n", 2)
+      dalibo_url = lines[0].sub(DALIBO_LINK_PREFIX, "")
+      clean_result = lines[1] || ""
+      dalibo_link = "**Dalibo Visualization:** [View Query Plan](#{dalibo_url})"
+      [dalibo_link, clean_result]
+    else
+      [nil, result_output]
+    end
+  end
+
+  def consume_dalibo_link_if_present(file_enum, consumed_lines)
+    # Look ahead to see if there are Dalibo links after the result block
+    begin
+      # Keep consuming blank lines and Dalibo links until we hit something else
+      loop do
+        next_line = peek_next_line(file_enum)
+
+        if is_blank_line?(next_line)
+          consumed_lines << file_enum.next
+        elsif next_line&.start_with?("**Dalibo Visualization:**")
+          consumed_lines << file_enum.next
+        else
+          # Hit something that's not a blank line or Dalibo link, stop consuming
+          break
+        end
+      end
+    rescue StopIteration
+      # End of file reached, nothing more to consume
+    end
+  end
+end

data/lib/execution_decider.rb

@@ -3,10 +3,12 @@ require_relative "enum_helper"
 class ExecutionDecider
   include EnumHelper
 
-  def initialize(current_block_run, current_block_rerun, current_block_lang)
+  def initialize(current_block_run, current_block_rerun, current_block_lang, current_block_explain = false, current_block_result = true)
     @current_block_run = current_block_run
     @current_block_rerun = current_block_rerun
     @current_block_lang = current_block_lang
+    @current_block_explain = current_block_explain
+    @current_block_result = current_block_result
   end
 
   def decide(file_enum, result_block_regex_method)
@@ -19,6 +21,8 @@ class ExecutionDecider
       handle_immediate_result_block(file_enum)
     elsif is_blank_line?(peek1)
       handle_blank_line_scenario(file_enum, expected_header_regex)
+    elsif @current_block_explain && is_dalibo_link?(peek1)
+      handle_immediate_dalibo_link(file_enum)
     else
       execute_without_existing_result
     end
@@ -44,12 +48,23 @@ class ExecutionDecider
 
   def handle_blank_line_scenario(file_enum, expected_header_regex)
     consumed_blank_line = file_enum.next
+    
+    # Look ahead past multiple blank lines to find actual content
     peek2 = peek_next_line(file_enum)
+    additional_blanks = []
+    
+    # Consume consecutive blank lines
+    while is_blank_line?(peek2)
+      additional_blanks << file_enum.next
+      peek2 = peek_next_line(file_enum)
+    end
 
     if line_matches_pattern?(peek2, expected_header_regex)
-      handle_result_after_blank_line(file_enum, consumed_blank_line)
+      handle_result_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    elsif @current_block_explain && is_dalibo_link?(peek2)
+      handle_dalibo_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
     else
-      execute_with_blank_line(consumed_blank_line)
+      execute_with_blank_lines(consumed_blank_line, additional_blanks)
     end
   end
 
@@ -61,6 +76,24 @@ class ExecutionDecider
     end
   end
 
+  def handle_result_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    if @current_block_rerun
+      execute_with_consumed_result_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    else
+      skip_with_blanks_and_result(file_enum, consumed_blank_line, additional_blanks)
+    end
+  end
+
+  def handle_dalibo_after_blank_lines(file_enum, consumed_blank_line, additional_blanks)
+    # For explain result=false, always replace existing Dalibo links
+    # For explain result=true, follow normal rerun logic
+    if should_auto_replace_dalibo_link? || @current_block_rerun
+      execute_with_consumed_dalibo_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    else
+      skip_with_blanks_and_dalibo(file_enum, consumed_blank_line, additional_blanks)
+    end
+  end
+
   def execute_with_consumed_result(file_enum)
     consumed_lines = [file_enum.next]
     { execute: true, consumed_lines: consumed_lines, consume_existing: true }
@@ -83,10 +116,98 @@ class ExecutionDecider
     { execute: true, blank_line: consumed_blank_line }
   end
 
+  def execute_with_blank_lines(consumed_blank_line, additional_blanks)
+    { execute: true, blank_line: consumed_blank_line, additional_blanks: additional_blanks }
+  end
+
+  def execute_with_consumed_result_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks + [file_enum.next]
+    { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line, consume_existing: true }
+  end
+
+  def skip_with_blanks_and_result(file_enum, consumed_blank_line, additional_blanks)
+    lines_to_pass = [consumed_blank_line] + additional_blanks + [file_enum.next]
+    { execute: false, lines_to_pass_through: lines_to_pass }
+  end
+
+  def execute_with_consumed_dalibo_and_blanks(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line, consume_existing_dalibo: true }
+  end
+
+  def skip_with_blanks_and_dalibo(file_enum, consumed_blank_line, additional_blanks)
+    consumed_lines = [consumed_blank_line] + additional_blanks
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, dalibo_content: true }
+  end
+
   def execute_without_existing_result
     { execute: true }
   end
 
+  def handle_immediate_dalibo_link(file_enum)
+    # For explain result=false, always replace existing Dalibo links
+    # For explain result=true, follow normal rerun logic
+    if should_auto_replace_dalibo_link? || @current_block_rerun
+      execute_with_consumed_dalibo(file_enum)
+    else
+      skip_with_existing_dalibo(file_enum)
+    end
+  end
+
+  def handle_dalibo_after_blank_line(file_enum, consumed_blank_line)
+    # For explain result=false, always replace existing Dalibo links
+    # For explain result=true, follow normal rerun logic
+    if should_auto_replace_dalibo_link? || @current_block_rerun
+      execute_with_consumed_dalibo_and_blank(file_enum, consumed_blank_line)
+    else
+      skip_with_blank_and_dalibo(file_enum, consumed_blank_line)
+    end
+  end
+
+  def execute_with_consumed_dalibo(file_enum)
+    consumed_lines = []
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, consume_existing_dalibo: true }
+  end
+
+  def skip_with_existing_dalibo(file_enum)
+    consumed_lines = []
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, dalibo_content: true }
+  end
+
+  def execute_with_consumed_dalibo_and_blank(file_enum, consumed_blank_line)
+    consumed_lines = [consumed_blank_line]
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: true, consumed_lines: consumed_lines, blank_line: consumed_blank_line, consume_existing_dalibo: true }
+  end
+
+  def skip_with_blank_and_dalibo(file_enum, consumed_blank_line)
+    consumed_lines = [consumed_blank_line]
+    consume_dalibo_links(file_enum, consumed_lines)
+    { execute: false, lines_to_pass_through: consumed_lines, dalibo_content: true }
+  end
+
+  def consume_dalibo_links(file_enum, consumed_lines)
+    # Consume all consecutive Dalibo links and blank lines
+    loop do
+      next_line = peek_next_line(file_enum)
+      
+      if is_blank_line?(next_line) || is_dalibo_link?(next_line)
+        consumed_line = file_enum.next
+        consumed_lines << consumed_line
+      else
+        break
+      end
+    end
+  end
+
+  def is_dalibo_link?(line)
+    line&.start_with?("**Dalibo Visualization:**")
+  end
+
   def line_matches_pattern?(line, pattern)
     line && line.match?(pattern)
   end
@@ -94,4 +215,11 @@ class ExecutionDecider
   def is_blank_line?(line)
     line && line.strip == ""
   end
+
+  def should_auto_replace_dalibo_link?
+    # Auto-replace Dalibo links when using explain with result=false
+    # This makes sense because with result=false, there's only a Dalibo link,
+    # so it should be updated on each run
+    @current_block_explain && !@current_block_result
+  end
 end

data/lib/frontmatter_parser.rb

@@ -6,9 +6,11 @@ class FrontmatterParser
 
   def initialize
     @aliases = {}
+    @defaults = {}
+    @language_defaults = {}
   end
 
-  attr_reader :aliases
+  attr_reader :aliases, :defaults, :language_defaults
 
   def parse_frontmatter(file_enum, output_lines)
     first_line = peek_next_line(file_enum)
@@ -22,6 +24,26 @@ class FrontmatterParser
     @aliases[lang] || lang
   end
 
+  def get_default_value(option_name, language, fallback_default)
+    # Priority order:
+    # 1. Language-specific defaults (e.g., psql: { explain: true })
+    # 2. Global defaults (e.g., defaults: { rerun: true })
+    # 3. Fallback default (hardcoded in the application)
+
+    # Check language-specific defaults first
+    if @language_defaults[language] && @language_defaults[language].key?(option_name)
+      return @language_defaults[language][option_name]
+    end
+
+    # Check global defaults
+    if @defaults.key?(option_name)
+      return @defaults[option_name]
+    end
+
+    # Return fallback default
+    fallback_default
+  end
+
   private
 
   def collect_frontmatter_lines(file_enum, output_lines)
@@ -58,14 +80,34 @@ class FrontmatterParser
     markdown_run_config = frontmatter["markdown-run"]
     return unless markdown_run_config.is_a?(Hash)
 
+    # Extract aliases
     aliases = markdown_run_config["alias"]
-    return unless aliases.is_a?(Array)
+    if aliases.is_a?(Array)
+      aliases.each do |alias_config|
+        next unless alias_config.is_a?(Hash)
+
+        alias_config.each do |alias_name, target_lang|
+          @aliases[alias_name.to_s] = target_lang.to_s
+        end
+      end
+    end
+
+    # Extract defaults
+    defaults = markdown_run_config["defaults"]
+    if defaults.is_a?(Hash)
+      defaults.each do |option_name, option_value|
+        @defaults[option_name.to_s] = option_value
+      end
+    end
 
-    aliases.each do |alias_config|
-      next unless alias_config.is_a?(Hash)
+    # Extract language-specific defaults
+    markdown_run_config.each do |key, value|
+      next if ["alias", "defaults"].include?(key)
+      next unless value.is_a?(Hash)
 
-      alias_config.each do |alias_name, target_lang|
-        @aliases[alias_name.to_s] = target_lang.to_s
+      @language_defaults[key.to_s] = {}
+      value.each do |option_name, option_value|
+        @language_defaults[key.to_s][option_name.to_s] = option_value
       end
     end
   end

data/lib/language_configs.rb

@@ -1,7 +1,7 @@
 require 'securerandom'
 
 JS_CONFIG = {
-  command: ->(_code_content, temp_file_path, input_file_path = nil) {
+  command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
     # Check if bun is available
     bun_exists = system("command -v bun > /dev/null 2>&1")
     if bun_exists
@@ -16,22 +16,32 @@ JS_CONFIG = {
 }.freeze
 
 SQLITE_CONFIG = {
-  command: ->(code_content, temp_file_path, input_file_path = nil) { [ "sqlite3 #{temp_file_path}", { stdin_data: code_content } ] },
+  command: ->(code_content, temp_file_path, input_file_path = nil, explain = false) { [ "sqlite3 #{temp_file_path}", { stdin_data: code_content } ] },
   temp_file_suffix: ".db" # Temp file is the database
 }.freeze
 
 SUPPORTED_LANGUAGES = {
   "psql" => {
-    command: ->(code_content, _temp_file_path, input_file_path = nil) {
+    command: ->(code_content, _temp_file_path, input_file_path = nil, explain = false) {
       psql_exists = system("command -v psql > /dev/null 2>&1")
       unless psql_exists
         abort "Error: psql command not found. Please install PostgreSQL or ensure psql is in your PATH."
       end
-      [ "psql -A -t -X", { stdin_data: code_content } ]
+
+      # Modify the SQL query if explain option is enabled
+      if explain
+        # Wrap the query with EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)
+        # Remove any trailing semicolons and whitespace, then add our EXPLAIN wrapper
+        clean_query = code_content.strip.gsub(/;\s*$/, '')
+        explained_query = "EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) #{clean_query};"
+        [ "psql -A -t -X", { stdin_data: explained_query } ]
+      else
+        [ "psql -A -t -X", { stdin_data: code_content } ]
+      end
     }
   },
   "ruby" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
       xmpfilter_exists = system("command -v xmpfilter > /dev/null 2>&1")
       unless xmpfilter_exists
         abort "Error: xmpfilter command not found. Please install xmpfilter or ensure it is in your PATH."
@@ -47,7 +57,7 @@ SUPPORTED_LANGUAGES = {
   "sqlite" => SQLITE_CONFIG,
   "sqlite3" => SQLITE_CONFIG, # Alias for sqlite
   "bash" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
       bash_exists = system("command -v bash > /dev/null 2>&1")
       unless bash_exists
         abort "Error: bash command not found. Please ensure bash is in your PATH."
@@ -57,7 +67,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".sh"
   },
   "zsh" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
       zsh_exists = system("command -v zsh > /dev/null 2>&1")
       unless zsh_exists
         abort "Error: zsh command not found. Please ensure zsh is in your PATH."
@@ -67,7 +77,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".zsh"
   },
   "sh" => {
-    command: ->(_code_content, temp_file_path, input_file_path = nil) {
+    command: ->(_code_content, temp_file_path, input_file_path = nil, explain = false) {
       sh_exists = system("command -v sh > /dev/null 2>&1")
       unless sh_exists
         abort "Error: sh command not found. Please ensure sh is in your PATH."
@@ -77,7 +87,7 @@ SUPPORTED_LANGUAGES = {
     temp_file_suffix: ".sh"
   },
   "mermaid" => {
-    command: ->(code_content, temp_file_path, input_file_path = nil) {
+    command: ->(code_content, temp_file_path, input_file_path = nil, explain = false) {
       mmdc_exists = system("command -v mmdc > /dev/null 2>&1")
       unless mmdc_exists
         abort "Error: mmdc command not found. Please install @mermaid-js/mermaid-cli: npm install -g @mermaid-js/mermaid-cli"
@@ -87,11 +97,11 @@ SUPPORTED_LANGUAGES = {
       if input_file_path
         # Extract markdown file basename without extension
         md_basename = File.basename(input_file_path, ".*")
-        
+
         # Create directory named after the markdown file
         output_dir = File.join(File.dirname(input_file_path), md_basename)
         Dir.mkdir(output_dir) unless Dir.exist?(output_dir)
-        
+
         # Generate unique filename with markdown basename prefix
         timestamp = Time.now.strftime("%Y%m%d-%H%M%S")
         random_suffix = SecureRandom.hex(6)

data/lib/markdown/run/version.rb

@@ -2,6 +2,6 @@
 
 module Markdown
   module Run
-    VERSION = "0.1.9"
+    VERSION = "0.1.11"
   end
 end

data/lib/markdown_processor.rb

@@ -4,18 +4,22 @@ require_relative "code_block_parser"
 require_relative "code_executor"
 require_relative "execution_decider"
 require_relative "enum_helper"
+require_relative "dalibo_helper"
+require_relative "code_block_helper"
+require_relative "result_helper"
 
 class MarkdownProcessor
   include EnumHelper
+  include DaliboHelper
+  include CodeBlockHelper
+  include ResultHelper
+
   def initialize(temp_dir, input_file_path = nil)
     @temp_dir = temp_dir
     @input_file_path = input_file_path
     @output_lines = []
-    @state = :outside_code_block
-    @current_block_lang = ""
-    @current_code_content = ""
-    @current_block_rerun = false
-    @current_block_run = true
+    reset_code_block_state
+
     @frontmatter_parser = FrontmatterParser.new
     @code_block_parser = CodeBlockParser.new(@frontmatter_parser)
   end
@@ -38,31 +42,6 @@ class MarkdownProcessor
     @frontmatter_parser.resolve_language(lang)
   end
 
-  def ruby_style_result?(lang)
-    lang_config = SUPPORTED_LANGUAGES[lang]
-    lang_config && lang_config[:result_block_type] == "ruby"
-  end
-
-  def mermaid_style_result?(lang)
-    lang_config = SUPPORTED_LANGUAGES[lang]
-    lang_config && lang_config[:result_handling] == :mermaid_svg
-  end
-
-  def result_block_header(lang)
-    ruby_style_result?(lang) ? "```ruby RESULT\n" : "```RESULT\n"
-  end
-
-  def result_block_regex(lang)
-    if mermaid_style_result?(lang)
-      # For mermaid, look for existing image tags with .svg extension
-      /^!\[.*\]\(.*\.svg\)$/i
-    elsif ruby_style_result?(lang)
-      /^```ruby\s+RESULT$/i
-    else
-      /^```RESULT$/i
-    end
-  end
-
   def is_block_end?(line)
     @code_block_parser.is_block_end?(line)
   end
@@ -71,22 +50,6 @@ class MarkdownProcessor
     !content.strip.empty?
   end
 
-  def add_result_block(result_output, blank_line_before_new_result)
-    if mermaid_style_result?(@current_block_lang)
-      # For mermaid, add the image tag directly without a result block
-      @output_lines << "\n" if blank_line_before_new_result.nil?
-      @output_lines << result_output
-      @output_lines << "\n" unless result_output.empty? || result_output.end_with?("\n")
-      @output_lines << "\n"
-    else
-      @output_lines << "\n" if blank_line_before_new_result.nil?
-      @output_lines << result_block_header(@current_block_lang)
-      @output_lines << result_output
-      @output_lines << "\n" unless result_output.empty? || result_output.end_with?("\n")
-      @output_lines << "```\n\n"
-    end
-  end
-
   def line_matches_pattern?(line, pattern)
     line && line.match?(pattern)
   end
@@ -95,14 +58,6 @@ class MarkdownProcessor
     line && line.strip == ""
   end
 
-  def parse_rerun_option(options_string)
-    @code_block_parser.parse_rerun_option(options_string)
-  end
-
-  def parse_run_option(options_string)
-    @code_block_parser.parse_run_option(options_string)
-  end
-
   def handle_line(current_line, file_enum)
     case @state
     when :outside_code_block
@@ -134,129 +89,4 @@ class MarkdownProcessor
       accumulate_code_content(current_line)
     end
   end
-
-  def handle_inside_result_block(current_line, file_enum)
-    @output_lines << current_line
-    if is_block_end?(current_line)
-      @state = :outside_code_block
-    end
-  end
-
-  def handle_existing_ruby_result_block(current_line, file_enum)
-    warn "Found existing '```ruby RESULT' block, passing through."
-    @output_lines << current_line
-    @state = :inside_result_block
-  end
-
-  def start_code_block(current_line, lang, options_string = nil)
-    @output_lines << current_line
-    @current_block_lang = resolve_language(lang)
-    @current_block_rerun = parse_rerun_option(options_string)
-    @current_block_run = parse_run_option(options_string)
-    @state = :inside_code_block
-    @current_code_content = ""
-  end
-
-  def accumulate_code_content(current_line)
-    @current_code_content += current_line
-    @output_lines << current_line
-  end
-
-  def end_code_block(current_line, file_enum)
-    @output_lines << current_line
-
-    decision = decide_execution(file_enum)
-
-    if decision[:execute]
-      # If we consumed lines for rerun, don't add them to output (they'll be replaced)
-      execute_and_add_result(decision[:blank_line])
-    else
-      skip_and_pass_through_result(decision[:lines_to_pass_through], file_enum)
-    end
-
-    reset_code_block_state
-  end
-
-  def decide_execution(file_enum)
-    decider = ExecutionDecider.new(@current_block_run, @current_block_rerun, @current_block_lang)
-    decision = decider.decide(file_enum, method(:result_block_regex))
-
-    # Handle the consume_existing flag for rerun scenarios
-    if decision[:consume_existing]
-      consume_existing_result_block(file_enum, decision[:consumed_lines])
-    end
-
-    decision
-  end
-
-  def execute_and_add_result(blank_line_before_new_result)
-    @output_lines << blank_line_before_new_result if blank_line_before_new_result
-
-    if has_content?(@current_code_content)
-      result_output = CodeExecutor.execute(@current_code_content, @current_block_lang, @temp_dir, @input_file_path)
-      add_result_block(result_output, blank_line_before_new_result)
-    else
-      warn "Skipping empty code block for language '#{@current_block_lang}'."
-    end
-  end
-
-  def skip_and_pass_through_result(lines_to_pass_through, file_enum)
-    # Handle run=false case where there are no lines to pass through
-    if lines_to_pass_through.empty?
-      warn "Skipping execution due to run=false option."
-      return
-    end
-
-    if mermaid_style_result?(@current_block_lang)
-      warn "Found existing mermaid SVG image for current #{@current_block_lang} block, skipping execution."
-      @output_lines.concat(lines_to_pass_through)
-      # For mermaid, no additional consumption needed since it's just an image line
-    else
-      lang_specific_result_type = ruby_style_result?(@current_block_lang) ? "```ruby RESULT" : "```RESULT"
-      warn "Found existing '#{lang_specific_result_type}' block for current #{@current_block_lang} block, skipping execution."
-      @output_lines.concat(lines_to_pass_through)
-      consume_result_block_content(file_enum)
-    end
-  end
-
-  def consume_result_block_content(file_enum)
-    consume_block_lines(file_enum) do |line|
-      @output_lines << line
-    end
-  end
-
-  def consume_existing_result_block(file_enum, consumed_lines)
-    if mermaid_style_result?(@current_block_lang)
-      # For mermaid, there's no result block to consume, just the image line
-      # The image line should already be in consumed_lines from ExecutionDecider
-      return
-    end
-
-    consume_block_lines(file_enum) do |line|
-      consumed_lines << line
-    end
-  end
-
-  def consume_block_lines(file_enum)
-    begin
-      loop do
-        result_block_line = file_enum.next
-        yield result_block_line
-        break if is_block_end?(result_block_line)
-      end
-    rescue StopIteration
-      warn "Warning: End of file reached while consuming result block."
-    end
-  end
-
-  def reset_code_block_state
-    @state = :outside_code_block
-    @current_code_content = ""
-    @current_block_rerun = false
-    @current_block_run = true
-  end
-
-  def stderr_has_content?(stderr_output)
-    stderr_output && !stderr_output.strip.empty?
-  end
 end

data/lib/result_helper.rb

@@ -0,0 +1,141 @@
+module ResultHelper
+  private
+
+  def ruby_style_result?(lang)
+    lang_config = SUPPORTED_LANGUAGES[lang]
+    lang_config && lang_config[:result_block_type] == "ruby"
+  end
+
+  def mermaid_style_result?(lang)
+    lang_config = SUPPORTED_LANGUAGES[lang]
+    lang_config && lang_config[:result_handling] == :mermaid_svg
+  end
+
+  def result_block_header(lang)
+    ruby_style_result?(lang) ? "```ruby RESULT\n" : "```RESULT\n"
+  end
+
+  def result_block_regex(lang)
+    if mermaid_style_result?(lang)
+      # For mermaid, look for existing image tags with .svg extension
+      /^!\[.*\]\(.*\.svg\)$/i
+    elsif ruby_style_result?(lang)
+      /^```ruby\s+RESULT$/i
+    else
+      /^```RESULT$/i
+    end
+  end
+
+  def add_result_block(result_output, blank_line_before_new_result)
+    if mermaid_style_result?(@current_block_lang)
+      # For mermaid, add the image tag directly without a result block
+      @output_lines << "\n" if blank_line_before_new_result.nil?
+      @output_lines << result_output
+      @output_lines << "\n" unless result_output.empty? || result_output.end_with?("\n")
+      @output_lines << "\n"
+    else
+      @output_lines << "\n" if blank_line_before_new_result.nil?
+      @output_lines << result_block_header(@current_block_lang)
+      @output_lines << result_output
+      @output_lines << "\n" unless result_output.empty? || result_output.end_with?("\n")
+      @output_lines << "```\n\n"
+    end
+  end
+
+
+  def handle_inside_result_block(current_line, file_enum)
+    @output_lines << current_line
+    if is_block_end?(current_line)
+      @state = :outside_code_block
+    end
+  end
+
+  def handle_existing_ruby_result_block(current_line, file_enum)
+    warn "Found existing '```ruby RESULT' block, passing through."
+    @output_lines << current_line
+    @state = :inside_result_block
+  end
+
+
+  def execute_and_add_result(blank_line_before_new_result)
+      warn "Skipping empty code block for language '#{@current_block_lang}'." && return unless has_content?(@current_code_content)
+
+    @output_lines << blank_line_before_new_result if blank_line_before_new_result
+
+    result_output = CodeExecutor.execute(@current_code_content, @current_block_lang, @temp_dir, @input_file_path, @current_block_explain)
+
+    # Check if result contains a Dalibo link for psql explain queries
+    dalibo_link, clean_result = extract_dalibo_link(result_output)
+
+    # Add the result block only if result=true (default)
+    if @current_block_result
+      add_result_block(clean_result || result_output, blank_line_before_new_result)
+    end
+
+    # Always add Dalibo link if it exists, even when result=false
+    if dalibo_link
+      # Add appropriate spacing based on whether result block was shown
+      if @current_block_result
+        @output_lines << "#{dalibo_link}\n\n"
+      else
+        @output_lines << "\n#{dalibo_link}\n\n"
+      end
+    end
+  end
+
+  def skip_and_pass_through_result(lines_to_pass_through, file_enum, decision = nil)
+    # Handle run=false case where there are no lines to pass through
+    if lines_to_pass_through.empty?
+      warn "Skipping execution due to run=false option."
+      return
+    end
+
+    # Check if this is Dalibo content
+    if decision && decision[:dalibo_content]
+      warn "Found existing Dalibo link for current #{@current_block_lang} block, skipping execution."
+      @output_lines.concat(lines_to_pass_through)
+      # No additional consumption needed for Dalibo links
+      return
+    end
+
+    if mermaid_style_result?(@current_block_lang)
+      warn "Found existing mermaid SVG image for current #{@current_block_lang} block, skipping execution."
+      @output_lines.concat(lines_to_pass_through)
+      # For mermaid, no additional consumption needed since it's just an image line
+    else
+      lang_specific_result_type = ruby_style_result?(@current_block_lang) ? "```ruby RESULT" : "```RESULT"
+      warn "Found existing '#{lang_specific_result_type}' block for current #{@current_block_lang} block, skipping execution."
+      @output_lines.concat(lines_to_pass_through)
+      consume_result_block_content(file_enum)
+    end
+  end
+
+  def consume_result_block_content(file_enum)
+    consume_block_lines(file_enum) do |line|
+      @output_lines << line
+    end
+  end
+
+  def consume_existing_result_block(file_enum, consumed_lines)
+    return if mermaid_style_result?(@current_block_lang)
+
+    consume_block_lines(file_enum) do |line|
+      consumed_lines << line
+    end
+
+    consume_dalibo_link_if_present(file_enum, consumed_lines)
+  end
+
+
+  def consume_block_lines(file_enum)
+    begin
+      loop do
+        result_block_line = file_enum.next
+        yield result_block_line
+        break if is_block_end?(result_block_line)
+      end
+    rescue StopIteration
+      warn "Warning: End of file reached while consuming result block."
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown-run
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.11
 platform: ruby
 authors:
 - Aurélien Bottazini
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-02 00:00:00.000000000 Z
+date: 2025-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rcodetools
@@ -24,6 +24,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.8.5
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -84,8 +98,10 @@ files:
 - README.md
 - Rakefile
 - exe/markdown-run
+- lib/code_block_helper.rb
 - lib/code_block_parser.rb
 - lib/code_executor.rb
+- lib/dalibo_helper.rb
 - lib/enum_helper.rb
 - lib/execution_decider.rb
 - lib/frontmatter_parser.rb
@@ -94,6 +110,7 @@ files:
 - lib/markdown_file_writer.rb
 - lib/markdown_processor.rb
 - lib/markdown_run.rb
+- lib/result_helper.rb
 - markdown-run-sample.md
 homepage: https://github.com/aurelienbottazini/markdown-run
 licenses: