rundoc 5.0.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85fbfa9f84b4e98eb72d487721e7f35001f7820404e30a138de4b4505d788f53
-  data.tar.gz: 1ff08ba1cdd468b190fc54eef124b7ab434d700ffe87ba2b4c8e676d03fb515e
+  metadata.gz: 498d5109daa7abb733fc5c27cf583bb1c84cc7b92bbccaaf9e005a51a6ec0555
+  data.tar.gz: fc72016241033a945486b5fa893b3f2cad0c8b3c7a2c44eab3f964adb7308f9e
 SHA512:
-  metadata.gz: 8e87c610bcd8c8589407e68b503eee0578a1dc23b959baa138258185f7d08e6daa3ee17097e4b66b02fea896ee9e5be2bde936e2a601a2b18d1b1a2fc24b36a2
-  data.tar.gz: 9c9f4d7446beaedc74d61354794327cd30f372f7e5e16500678247f7bc549bb7b04992d0875c06c1fa06ae894a36c35902e07930cf55ab4e9fc01bb8b29c44d3
+  metadata.gz: 5af654672de3e6051ec46377052c55b55207ce13eb29cf977d1cf793291e953d28e842fd79b0f0972f8eb83a98c6671c1834a5ac75f20da795eb686a99a02c52
+  data.tar.gz: b2acdf08759aa0c6f73410a00a4ad387da198f1f4497228c69d27dd799799e12107cc421c8f3fd5242f9517dbfd2565e71b56e2b3a6ffd77ffd879906c902d65

data/.github/workflows/ci.yml

@@ -13,6 +13,7 @@ jobs:
         ruby:
           - 3.2
           - 3.3
+          - 3.4
           - "4.0"
           - head
     steps:

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## HEAD
 
+## 6.0.0
+
+- Added: `rundoc.ensure_later(dir: :cwd)` command to register cleanup blocks that run on every build (success and failure). Useful for guaranteed resource teardown (e.g., destroying Heroku apps). Multiple blocks execute in order; failures in one block do not stop the rest.
+- Changed: The ruby context in `rundoc` and `rundoc.configure` commands is now the same binding as the default ERB evaluation. This means that methods can be defined in one and used in both.
+
 ## 5.0.0
 
 - Added comment syntax. Use an octothorpe (`#`) after the visibility markers to comment out any commands and make them a no-op.

data/README.md

@@ -98,6 +98,8 @@ This will generate a project folder with your project in it, and a markdown `REA
   - [website.screenshot](#screenshots)
 - Configure RunDOC
   - [rundoc.configure](#configure)
+  - [rundoc.ensure_later](#ensure_later)
+  - [rundoc](#configure) an alias for `rundoc.configure`
 - Import and compose documents
   - [rundoc.require](#compose-multiple-rundoc-documents)
 
@@ -616,7 +618,7 @@ If you need to specify project specific environment variables create a file call
 
 ## Configure
 
-You can configure your docs in your docs use the `RunDOC` command
+You can configure your docs in your docs use the `RunDOC` command via `rundoc.configure` (or alias `rundoc`):
 
     ```
     :::-- rundoc.configure
@@ -624,6 +626,30 @@ You can configure your docs in your docs use the `RunDOC` command
 
 Note: Make sure you run this as a hidden command (with `-`).
 
+This will give you a Ruby codeblock that executes and gives you access to `Rundoc.configure do |config|` to configure things about your build (such as modifying your markdown document after successful builds).
+
+**Define and Re-use logic**
+
+Since it's **just ruby** :tm: you can also use it to define shared logic that can be re-used in ERB templates. For example:
+
+      ```
+      :::-- rundoc
+      def run!(command, quiet: false, error_on_fail: true)
+        puts "Running `#{command}`" unless quiet
+        output = `#{command}`
+        puts "Command `#{command}` output:\n#{output}" unless quiet
+        if error_on_fail && !$?.success?
+          raise "Error running #{command}. Output:\n#{output}"
+        end
+        output
+      end
+      ```
+
+      ```
+      :::-> print.erb
+      Hello <%= run!("heroku whoami") %>!
+      ```
+
 **After Build**
 
 This will eval any code you put under that line (in Ruby) when the build was successful but before the contents are finalized on disk. If you want to run some code after you're done building your docs you could use `Rundoc.configure` block and call the `after_build` method like this:
@@ -658,6 +684,41 @@ Sometimes sensitive info like usernames, email addresses, or passwords may be in
 
 This command `filter_sensitive` can be called multiple times with different values. Since the config is in Ruby you could iterate over an array of sensitive data
 
+## Ensure Later
+
+Run a script on EVERY build (success and failure). Used to guarantee resources are cleaned up.
+
+- Arguments
+  - `dir:` The directory where the script will be run. Must be one of these values:
+    - `:cwd` The directory where the command is first invoked. If this directory does not exist when the `rundoc.ensure_later` is invoked, it will raise an error.
+    - `:rundoc_root` The tmp directory where the script is being executed. Useful if the directory where the `rundoc.ensure_later` is defined, is deleted by the rundoc script.
+
+For example:
+
+    ```
+    :::>> $ heroku create
+    :::-- rundoc
+    @app_name = run!("heroku info --json | jq -r '.app.name'").strip
+
+    def app_name
+      @app_name
+    end
+    ```
+
+    ```ruby
+    :::-- rundoc.ensure_later(dir: :cwd)
+    if run!("heroku apps").include?(app_name)
+      puts "Cleaning up web app #{app_name}"
+      run!("heroku apps:destroy #{app_name} --confirm #{app_name}")
+    else
+      puts "App `#{app_name}` already cleaned, nothing to do"
+    end
+    ```
+
+The output of this will not be included in the document. Multiple ensure blocks can be defined and will execute in the order of their definition. Since they'll be executed EVERY time, logic must handle both success and failure cases. This execution occurs before the temp directory is removed, and before any background task shutdown ensure blocks are triggered.
+
+If a build is successful, but an `ensure_later` block fails, the build will be considered a failure. A failure in one block will not stop the rest from executing.
+
 ## Writing a new command
 
 > Note: This is an advanced topic and this interface is unstable.

data/lib/rundoc/cli.rb

@@ -134,6 +134,9 @@ module Rundoc
     end
 
     def call
+      build_success = false
+      ensure_later_errors = []
+
       io.puts "## Running your docs"
       load_dotenv
       check_directories_empty!
@@ -165,7 +168,11 @@ module Rundoc
           io: io
         )
         output = begin
-          parser.to_md
+          begin
+            parser.to_md
+          ensure
+            ensure_later_errors = Rundoc.run_ensure_later(io: io)
+          end
         rescue StandardError, SignalException => e
           io.puts "Received exception: #{e.inspect}, cleaning up before re-raise"
           on_fail
@@ -174,6 +181,8 @@ module Rundoc
 
         on_success(output)
       end
+
+      build_success = true
     ensure
       # Stop any hanging background tasks
       Rundoc::CodeCommand::Background::ProcessSpawn.tasks.each do |name, task|
@@ -189,6 +198,10 @@ module Rundoc
           description: "tmp working directory"
         )
       end
+
+      if ensure_later_errors.any? && build_success
+        raise ensure_later_errors.first
+      end
     end
 
     private def clean_dir(dir:, description:)

data/lib/rundoc/code_command/bash/cd.rb

@@ -7,25 +7,19 @@ class Rundoc::CodeCommand::BashRunner
       @line = line
     end
 
-    # Ignore duplicate chdir warnings "warning: conflicting chdir during another chdir block"
-    def supress_chdir_warning
-      old_stderr = $stderr
-      capture_stderr = StringIO.new
-      $stderr = capture_stderr
+    def suppress_chdir_warning
+      old_verbose = $VERBOSE
+      $VERBOSE = nil
       yield
     ensure
-      if old_stderr
-        $stderr = old_stderr
-        capture_string = capture_stderr.string
-        warn capture_string if capture_string.each_line.count > 1 || !capture_string.include?("conflicting chdir")
-      end
+      $VERBOSE = old_verbose
     end
 
     def call(env)
       line = @line.sub("cd", "").strip
       @io.puts "running $ cd #{line}"
 
-      supress_chdir_warning do
+      suppress_chdir_warning do
         Dir.chdir(line)
       end
 

data/lib/rundoc/code_command/empty_binding.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "erb"
+
+class EmptyBinding
+  def self.create
+    new.empty_binding
+  end
+
+  def empty_binding
+    binding
+  end
+end
+
+module Rundoc::CodeCommand
+  RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
+  RUNDOC_DEFAULT_ERB_BINDING = "default"
+end

data/lib/rundoc/code_command/print/erb.rb

@@ -1,21 +1,8 @@
 # frozen_string_literal: true
 
-require "erb"
-
-class EmptyBinding
-  def self.create
-    new.empty_binding
-  end
-
-  def empty_binding
-    binding
-  end
-end
+require_relative "../empty_binding"
 
 module Rundoc::CodeCommand
-  RUNDOC_ERB_BINDINGS = Hash.new { |h, k| h[k] = EmptyBinding.create }
-  RUNDOC_DEFAULT_ERB_BINDING = "default"
-
   class PrintERBArgs
     attr_reader :line, :binding_name
 

data/lib/rundoc/code_command/rundoc/ensure_later.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ::Rundoc::CodeCommand
+  class RundocCommand
+    class EnsureLaterArgs
+      MAPPING = {
+        cwd: ->(context:) {
+          Dir.pwd
+        },
+        rundoc_root: ->(context:) {
+          context.output_dir.to_s
+        }
+      }.freeze
+
+      def initialize(dir:)
+        @dir = dir
+        @logic = MAPPING[dir] or raise ArgumentError, "Invalid argument dir: #{dir} must be one of #{MAPPING.keys}"
+      end
+
+      def call(context:)
+        @logic.call(context: context)
+      end
+
+      def to_s
+        @dir
+      end
+    end
+
+    class EnsureLaterRunner
+      attr_reader :io, :contents
+
+      def initialize(user_args:, render_command:, render_result:, io:, contents: nil)
+        @io = io
+        @contents = contents.dup if contents && !contents.empty?
+        @dir = user_args
+        @binding = RUNDOC_ERB_BINDINGS[RUNDOC_DEFAULT_ERB_BINDING]
+      end
+
+      def to_md(env = {})
+        ""
+      end
+
+      def call(env = {})
+        resolved_dir = @dir.call(context: env[:context])
+
+        io.puts "Registering ensure_later block (dir: #{@dir} => #{resolved_dir})"
+        Rundoc.add_ensure_later(dir: resolved_dir, code: @contents, binding: @binding)
+        ""
+      end
+    end
+  end
+end
+
+Rundoc.register_code_command(
+  keyword: :"rundoc.ensure_later",
+  args_klass: Rundoc::CodeCommand::RundocCommand::EnsureLaterArgs,
+  runner_klass: Rundoc::CodeCommand::RundocCommand::EnsureLaterRunner,
+  always_hidden: true
+)

data/lib/rundoc/code_command/rundoc_command.rb

@@ -17,6 +17,7 @@ module ::Rundoc
         @io = io
         @contents = contents.dup if contents && !contents.empty?
         @contents = user_args.code + (@contents || +"")
+        @binding = RUNDOC_ERB_BINDINGS[RUNDOC_DEFAULT_ERB_BINDING]
       end
 
       def to_md(env = {})
@@ -25,7 +26,9 @@ module ::Rundoc
 
       def call(env = {})
         io.puts "Running: #{contents}"
-        eval(contents) # rubocop:disable Security/Eval
+        Rundoc.capture_stdout_stderr(io) do
+          eval(contents, @binding) # rubocop:disable Security/Eval
+        end
         ""
       end
     end
@@ -36,3 +39,4 @@ Rundoc.register_code_command(keyword: :rundoc, args_klass: Rundoc::CodeCommand::
 Rundoc.register_code_command(keyword: :"rundoc.configure", args_klass: Rundoc::CodeCommand::RundocCommandArgs, runner_klass: Rundoc::CodeCommand::RundocCommandRunner)
 
 require "rundoc/code_command/rundoc/require"
+require "rundoc/code_command/rundoc/ensure_later"

data/lib/rundoc/code_command.rb

@@ -5,6 +5,7 @@ module Rundoc
   end
 end
 
+require "rundoc/code_command/empty_binding"
 require "rundoc/code_command/deferred"
 require "rundoc/code_command/bash"
 require "rundoc/code_command/pipe"

data/lib/rundoc/peg_parser.rb

@@ -39,9 +39,16 @@ module Rundoc
       ).as(:number)
     }
 
+    rule(:symbol) {
+      str(":") >> (
+        match("[a-zA-Z_]") >> match("[a-zA-Z0-9_]").repeat
+      ).as(:symbol)
+    }
+
     rule(:value) {
       string |
         number |
+        symbol |
         str("true").as(true) |
         str("false").as(false) |
         str("nil").as(:nil)
@@ -175,6 +182,7 @@ module Rundoc
     rule(true => simple(:tr)) { true }
     rule(false => simple(:fa)) { false }
     rule(string: simple(:st)) { st.to_s }
+    rule(symbol: simple(:sy)) { sy.to_s.to_sym }
 
     rule(number: simple(:nb)) {
       /[eE.]/.match?(nb) ? Float(nb) : Integer(nb)

data/lib/rundoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rundoc
-  VERSION = "5.0.0"
+  VERSION = "6.0.0"
 end

data/lib/rundoc.rb

@@ -97,6 +97,43 @@ module Rundoc
     yield self
   end
 
+  def ensure_later_blocks
+    @ensure_later_blocks ||= []
+  end
+
+  def add_ensure_later(dir:, code:, binding:)
+    ensure_later_blocks << {dir: dir, code: code, binding: binding}
+  end
+
+  def run_ensure_later(io:)
+    errors = []
+    ensure_later_blocks.each do |block|
+      io.puts "Running ensure_later block in #{block[:dir]}:\n#{block[:code]}"
+      Dir.chdir(block[:dir]) do
+        capture_stdout_stderr(io) do
+          eval(block[:code], block[:binding]) # rubocop:disable Security/Eval
+        end
+      end
+    rescue => e
+      io.puts "ensure_later block failed in #{block[:dir]}: #{e.message}"
+      io.puts e.backtrace.join("\n")
+      errors << e
+    end
+    ensure_later_blocks.clear
+    errors
+  end
+
+  def capture_stdout_stderr(io)
+    old_stdout = $stdout
+    old_stderr = $stderr
+    $stdout = io
+    $stderr = io
+    yield
+  ensure
+    $stdout = old_stdout
+    $stderr = old_stderr
+  end
+
   def filter_sensitive(sensitive)
     raise "Expecting #{sensitive} to be a hash" unless sensitive.is_a?(Hash)
     @sensitive ||= {}

data/rundoc.gemspec

@@ -26,6 +26,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "aws-sdk-s3", "~> 1"
   gem.add_dependency "dotenv"
+  gem.add_dependency "cgi", ">= 0.3.6"
 
   gem.add_development_dependency "rake"
   gem.add_development_dependency "mocha"

data/test/integration/ensure_later_test.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class IntegrationEnsureLaterTest < Minitest::Test
+  def test_runs_on_success
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "yes")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert marker.exist?, "ensure_later block should have run on success"
+        assert_equal "yes", marker.read
+      end
+    end
+  end
+
+  def test_runs_on_failure
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "cleaned")
+          ```
+
+          ```
+          :::>> $ exit 1
+          ```
+        EOF
+
+        assert_raises do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME),
+            on_failure_dir: dir.join(FAILURE_DIRNAME)
+          ).call
+        end
+
+        assert marker.exist?, "ensure_later block should have run on failure"
+        assert_equal "cleaned", marker.read
+      end
+    end
+  end
+
+  def test_multiple_blocks_run_in_order
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("order.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "first")
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", File.read("#{marker}") + ",second")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert_equal "first,second", marker.read
+      end
+    end
+  end
+
+  def test_one_failure_does_not_stop_others
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("second_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          raise "intentional failure"
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "yes")
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        error = assert_raises(RuntimeError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+        assert_match(/intentional failure/, error.message)
+
+        assert marker.exist?, "second ensure_later should still run after first fails"
+      end
+    end
+  end
+
+  def test_success_plus_ensure_failure_is_overall_failure
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          raise "cleanup failed"
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        error = assert_raises(RuntimeError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+
+        assert_match(/cleanup failed/, error.message)
+      end
+    end
+  end
+
+  def test_dir_rundoc_root
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("root_marker.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir subdir
+          :::>> $ cd subdir
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :rundoc_root)
+          File.write("#{marker}", Dir.pwd)
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        cli = Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        )
+        output_dir = cli.execution_context.output_dir.realpath.to_s
+
+        cli.call
+
+        assert marker.exist?, "ensure_later with dir: :rundoc_root should run"
+        assert_equal output_dir, marker.read
+      end
+    end
+  end
+
+  def test_output_not_in_document
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          puts "THIS SHOULD NOT APPEAR"
+          ```
+
+          ```
+          :::>> $ echo "visible"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        readme = dir.join(SUCCESS_DIRNAME).join("README.md").read
+        refute_match(/THIS SHOULD NOT APPEAR/, readme)
+        assert_match(/visible/, readme)
+      end
+    end
+  end
+
+  def test_invalid_dir_raises
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc.ensure_later(dir: :invalid)
+          puts "should not run"
+          ```
+        EOF
+
+        assert_raises(ArgumentError) do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME)
+          ).call
+        end
+      end
+    end
+  end
+
+  def test_shared_binding_with_rundoc
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("binding_test.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::-- rundoc
+          def my_helper
+            "from_rundoc"
+          end
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", my_helper)
+          ```
+
+          ```
+          :::>> $ echo "hello"
+          ```
+        EOF
+
+        Rundoc::CLI.new(
+          io: StringIO.new,
+          source_path: source_path,
+          on_success_dir: dir.join(SUCCESS_DIRNAME)
+        ).call
+
+        assert_equal "from_rundoc", marker.read
+      end
+    end
+  end
+
+  def test_runs_on_failure_from_subdirectory
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        dir = Pathname(dir)
+        marker = dir.join("ensure_ran.txt")
+
+        source_path = dir.join("RUNDOC.md")
+        source_path.write <<~EOF
+          ```
+          :::>> $ mkdir myapp
+          :::>> $ cd myapp
+          ```
+
+          ```
+          :::-- rundoc.ensure_later(dir: :cwd)
+          File.write("#{marker}", "cleaned")
+          ```
+
+          ```
+          :::>> $ exit 1
+          ```
+        EOF
+
+        assert_raises do
+          Rundoc::CLI.new(
+            io: StringIO.new,
+            source_path: source_path,
+            on_success_dir: dir.join(SUCCESS_DIRNAME),
+            on_failure_dir: dir.join(FAILURE_DIRNAME)
+          ).call
+        end
+
+        assert marker.exist?, "ensure_later from subdirectory should run even on failure"
+        assert_equal "cleaned", marker.read
+      end
+    end
+  end
+end

data/test/integration/print_test.rb

@@ -50,6 +50,57 @@ class IntegrationPrintTest < Minitest::Test
     end
   end
 
+  def test_rundoc_configure_defines_variable_accessible_from_erb
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::-- rundoc.configure
+      @shared_value = "#{key}"
+      ```
+
+      ```
+      :::-> print.erb
+      <%= @shared_value %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
+        assert_includes actual, key
+      end
+    end
+  end
+
+  def test_erb_defines_variable_accessible_from_rundoc_configure
+    key = SecureRandom.hex
+    contents = <<~RUBY
+      ```
+      :::-> print.erb
+      <% @from_erb = "#{key}" %>
+      ```
+
+      ```
+      :::-- rundoc.configure
+      @roundtripped = @from_erb + "_via_configure"
+      ```
+
+      ```
+      :::-> print.erb
+      <%= @roundtripped %>
+      ```
+    RUBY
+
+    Dir.mktmpdir do |dir|
+      Dir.chdir(dir) do
+        parsed = parse_contents(contents)
+        actual = parsed.to_md.gsub(Rundoc::FencedCodeBlock::AUTOGEN_WARNING, "")
+        assert_includes actual, "#{key}_via_configure"
+      end
+    end
+  end
+
   def test_erb_in_block
     contents = <<~RUBY
       ```

data/test/rundoc/peg_parser_test.rb

@@ -367,4 +367,29 @@ class PegParserTest < Minitest::Test
     assert_equal :rundoc, actual.keyword
     assert_equal "first = 1 # comment\nsecond = 2".strip, actual.contents.strip
   end
+
+  def test_symbol_value
+    input = %(:cwd)
+    parser = Rundoc::PegParser.new.symbol
+    tree = parser.parse_with_debug(input)
+    actual = @transformer.apply(tree)
+    assert_equal :cwd, actual
+  end
+
+  def test_symbol_in_named_args
+    input = %(dir: :cwd)
+    parser = Rundoc::PegParser.new.named_args
+    tree = parser.parse_with_debug(input)
+    actual = @transformer.apply(tree)
+    assert_equal({dir: :cwd}, actual)
+  end
+
+  def test_symbol_in_method_call
+    input = %(rundoc.ensure_later(dir: :cwd))
+    parser = Rundoc::PegParser.new.method_call
+    tree = parser.parse_with_debug(input)
+    actual = @transformer.apply(tree)
+    assert_equal :"rundoc.ensure_later", actual.keyword
+    assert_equal({dir: :cwd}, actual.original_args)
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rundoc
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 6.0.0
 platform: ruby
 authors:
 - Richard Schneeman
@@ -107,6 +107,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cgi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.6
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -212,6 +226,7 @@ files:
 - lib/rundoc/code_command/bash/cd.rb
 - lib/rundoc/code_command/comment.rb
 - lib/rundoc/code_command/deferred.rb
+- lib/rundoc/code_command/empty_binding.rb
 - lib/rundoc/code_command/file_command/append.rb
 - lib/rundoc/code_command/file_command/remove.rb
 - lib/rundoc/code_command/no_such_command.rb
@@ -220,6 +235,7 @@ files:
 - lib/rundoc/code_command/print/erb.rb
 - lib/rundoc/code_command/print/text.rb
 - lib/rundoc/code_command/raw.rb
+- lib/rundoc/code_command/rundoc/ensure_later.rb
 - lib/rundoc/code_command/rundoc/require.rb
 - lib/rundoc/code_command/rundoc_command.rb
 - lib/rundoc/code_command/website.rb
@@ -262,6 +278,7 @@ files:
 - test/fixtures/simple_git/rundoc.md
 - test/integration/after_build_test.rb
 - test/integration/background_stdin_test.rb
+- test/integration/ensure_later_test.rb
 - test/integration/failure_test.rb
 - test/integration/pre_erb_test.rb
 - test/integration/print_test.rb
@@ -301,7 +318,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: RunDOC generates runable code from docs
 test_files: []