rundoc 1.1.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64447cf981514498089c30f81d5a9885059db08ac2120b8bb700eed4089d0105
-  data.tar.gz: b46c802f280388c043adddcdfbe0a385fcf2bee8aa4c1fd76563452c7d24698c
+  metadata.gz: 45657dd48e87b08e841e90a828d026a9248b0c52667824b77eb799c5d2afc6f5
+  data.tar.gz: 03b6a8b17ba747ae9952398772edf2cbff4b2ac0710a8a52e20055b46aafd657
 SHA512:
-  metadata.gz: cf89810f545312fd23e6759015473f5d64e9991f7348344649a4b672a3e97e774702ec04d5d3b91f64b8ebb14caecf78ac0f2d583d423b1c3f25c1915eaa1e5a
-  data.tar.gz: 9b7f288a0b23806729f07690faf8ec1b295c45652e7db07253aba38019c50d0e30a1cfb4b9973cc97ef36ac78bb8a1139228ed9b9fc5cbf15658770817a13e5e
+  metadata.gz: c717ac8241f4d4b4028c0ecb2e5391705112e00001abee2385af7ece74bcef546064fc09377eec41d0e4aab1323d3c5856cbbac772ca78237681110d9e82d472
+  data.tar.gz: c7736d871a79f584f7bb6ed9bfa50447ced0a6dd1a923578a0f5d8df28e8b1d36350715f38435959f7de2770112080005b79f7a4cbfdd27a8c87a6b906fe02b2

data/.github/workflows/check_changelog.yml

@@ -1,13 +1,22 @@
 name: Check Changelog
 
 on:
- pull_request:
-  types: [opened, reopened, edited, synchronize]
+  pull_request:
+    types: [opened, reopened, edited, labeled, unlabeled, synchronize]
+
 jobs:
-  build:
+  check-changelog:
     runs-on: ubuntu-latest
+    if: |
+      !contains(github.event.pull_request.body, '[skip changelog]') &&
+      !contains(github.event.pull_request.body, '[changelog skip]') &&
+      !contains(github.event.pull_request.body, '[skip ci]') &&
+      !contains(github.event.pull_request.labels.*.name, 'skip changelog') &&
+      !contains(github.event.pull_request.labels.*.name, 'dependencies') &&
+      !contains(github.event.pull_request.labels.*.name, 'automation')
     steps:
-    - uses: actions/checkout@v1
-    - name: Check that CHANGELOG is touched
-      run: |
-        cat $GITHUB_EVENT_PATH | jq .pull_request.title |  grep -i '\[\(\(changelog skip\)\|\(ci skip\)\)\]' ||  git diff remotes/origin/${{ github.base_ref }} --name-only | grep CHANGELOG.md
+      - uses: actions/checkout@v3
+      - name: Check that CHANGELOG is touched
+        run: |
+          git fetch origin ${{ github.base_ref }} --depth 1 && \
+          git diff remotes/origin/${{ github.base_ref }} --name-only | grep CHANGELOG.md

data/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 3.1
+          - 3.2
+          - 3.3
+          - head
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: test
+        run: bundle exec rake test
+        continue-on-error: ${{ matrix.ruby == 'head' }}
+
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - 3.3
+          - head
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: lint
+        run: bundle exec standardrb --no-fix
+        continue-on-error: ${{ matrix.ruby == 'head' }}

data/.standard.yml

@@ -0,0 +1,6 @@
+fix: true               # default: false
+parallel: true          # default: false
+format: progress        # default: Standard::Formatter
+ruby_version: 3.1       # default: RUBY_VERSION
+ignore:                 # default: []
+  - 'test/fixtures/**/*'

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## HEAD
 
+## 2.0.0
+
+- Change: Ruby 2.7 and 3.0 are no longer supported
+- Add: `print.text` and `print.erb` see README for usage details
+- Add: Output documents include more frequent warnings that the document was autogenerated and should not be modified
+- Breaking: Remove repl_runner support.
+- Fix `file.write` do not prepend "In file x ..." when the command is hidden i.e. `:::-> file.write`
+
+## 1.1.3
+
+- Bugfix: Bash commands that output to stderr and use `||` are now captured (https://github.com/schneems/rundoc/pull/29)
+
 ## 1.1.2
 
 - Fix pipe support (https://github.com/schneems/rundoc/pull/28)

data/Gemfile

@@ -1,4 +1,4 @@
 source "http://rubygems.org"
-gem 'm'
+gem "m"
 
 gemspec

data/README.md

@@ -47,7 +47,7 @@ gem 'rundoc'
 Run the `rundoc build` command on any markdown file
 
 ```sh
-$ rundoc build --path my/path/to/run_doc.md
+$ bin/rundoc build --path <test/fixtures/rails_7/rundoc.md>
 ```
 
 > Note: This command will create and manipulate directories in the working directory of your source markdown file. Best practice is to have your source markdown file in its own empty directory.
@@ -65,6 +65,9 @@ This will generate a project folder with your project in it, and a markdown READ
 - Execute Bash Commands
   - [$](#shell-commands)
   - [fail.$](#shell-commands)
+- Printing
+  - [print.text](#print)
+  - [print.erb](#print)
 - Chain commands
   - [pipe](#pipe)
   - [|](#pipe)
@@ -146,7 +149,7 @@ Would output:
    bahz
    ```
 
-This STDIN feature could be useful if you are running an interactive command such as `play new` which requires user input. For more fine grained input you'll need to use a custom repl object (will be covered later).
+This STDIN feature could be useful if you are running an interactive command such as `play new` which requires user input.
 
 Different commands will do different things with this input. For example the `rundoc` command executes Ruby configuration code:
 
@@ -181,7 +184,7 @@ RunDOC only cares about things that come after a `:::` section. If you have a "r
 You can mix non-command code and commands, as long as the things that aren't rendering come first. This can be used to "fake" a command, for example:
 
 ```
-$ rails new myapp # Not a command since it's missing the ":::>>""
+$ rails new myapp # Not a command since it's missing the ":::>>"
 :::-> $ rails new myapp --skip-test --skip-yarn --skip-sprockets
 :::>> | $ head -n 5
 ```
@@ -197,13 +200,12 @@ $ rails new myapp # Not a command since it's missing the ":::>>""
       create  config.ru
 ```
 
-It looks like the command was run without any flags, but in reality `rails new myapp --skip-test --skip-yarn --skip-sprockets | head -n 5` was executed.
+In this example it looks like the command was run without any flags, but in reality `rails new myapp --skip-test --skip-yarn --skip-sprockets | head -n 5` was executed. Though it's more explicit to use a `print.text` block, see [#print.text](#print) for more info.
 
 ## Rendering Cheat Sheet
 
 An arrow `>` is shorthand for "render this" and a dash `-` is shorthand for skip this section. The two positions are **command** first and **result** second.
 
-
 - `:::>-` (YES command output, not result output)
 - `:::>>` (YES command output, YES result output)
 - `:::--` (not command output, not result output)
@@ -250,6 +252,64 @@ These custom commands are kept to a minimum, and for the most part behave as you
 
 Running shell commands like this can be very powerful, you'll likely want more control of how you manipulate files in your project. To do this you can use the `file.` namespace:
 
+## Print
+
+Current commands:
+
+- `print.text`
+- `print.erb`
+
+Behaves slightly differently than other commands. The "command" portion of the control character i.e. `:::>` controls whether the contents will be rendered inside the block or before the block (versus usually this is used to control if the command such as `$ cd` is shown).
+
+- `:::>>` Print inside the code block
+- `:::->` Print BEFORE the code block, if multiple calls are made, they will be displayed in order.
+- `:::--` Nothing will be rendered, can be used to pass data to another rundoc command via the pipe operator.
+- `:::>-` Same behavior as `:::--`.
+
+This functionality is present to allow body text to be generated (versus only allowing generated text in code blocks).
+
+Use the `print.text` keyword followed by what you want to print:
+
+    ```
+    :::-> print.text
+    I will render BEFORE the code block, use :::>> to render in it.
+
+    It was the best of times, it was the worst of times, it was the age of wisdom, it was the age of foolishness,
+    it was the epoch of belief, it was the epoch ...
+    ```
+
+Specifying `:::->` with `print.text` will render text without a code block (or before the code block if there are other rundoc commands). If you want to render text with a code block you can do it via `:::>>`.
+
+To dynamically change the contents of the thing you're printing you can use `print.erb`:
+
+    ```
+    :::-> print.erb
+    I will render BEFORE the code block, use :::>> to render in it.
+
+    What a week!
+    Captain it's only <%= Time.now.strftime("%A") %>!
+    ```
+
+This will evaluate the context of ERB and write it to the file. Like `print.text` use `:::->` to write the contents without a code block (or before the code block if there are other rundoc commands). If you want to render text with a code block you can do it via `:::>>`.
+
+ERB commands share a default context. That means you can set a value in one `print.erb` section and view it from another. If you want to isolate your erb blocks you can provide a custom name via the `binding:` keyword:
+
+    ```
+    :::>> print.erb(binding: "mc_hammer")
+    I will render IN a code block, use `:::->` to render before.
+
+    <%= @stop = true %>
+
+    :::>> print.erb(binding: "different")
+    <% if @stop %>
+    Hammer time
+    <% else %>
+    Can't touch this
+    <% end %>
+    ```
+
+In this example setting `@stop` in one `print.erb` will have no effect on the other.
+
 ## File Commands
 
 Current Commands:
@@ -504,6 +564,39 @@ 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
 
+## Writing a new command
+
+Rundoc does not have a stable internal command interface. You can define your own commands, but unless it is committed in this repo, it may break on a minor version change.
+
+To add a new command it needs to be parsed and called. Examples of commands being implemented are seen in `lib/rundoc/code_command`.
+
+A new command needs to be registered:
+
+```
+Rundoc.register_code_command(:lol, Rundoc::CodeCommand::Lol)
+```
+
+They should inherit from Rundoc::CodeCommand:
+
+```
+class Rundoc::CodeCommand::Lol < Rundoc::CodeCommand
+  def initialize(line)
+  end
+end
+```
+
+The initialize method is called with input from the document. The command is rendered (`:::>-`) by the output of the `def call` method. The contents produced by the command (`:::->`) are rendered by the `def to_md` method.
+
+The syntax for commands is ruby-ish but it is a custom grammar implemented in `lib/peg_parser.rb` for more info on manipulating the grammar see this tutorial on how I added keword-like/hash-like syntax https://github.com/schneems/implement_ruby_hash_syntax_with_parslet_example.
+
+Command initialize methods natively support:
+
+- Barewords as a single string input
+- Keyword arguments
+- A combination of the two
+
+Anything that is passed to the command via "stdin" is available via a method `self.contents`. The interplay between the input and `self.contents` is not strongly defined.
+
 ## Copyright
 
 All content Copyright Richard Schneeman © 2020

data/Rakefile

@@ -1,16 +1,15 @@
-# encoding: UTF-8
-require 'bundler/gem_tasks'
+require "bundler/gem_tasks"
 
-require 'rundoc'
+require "rundoc"
 
-require 'rake'
-require 'rake/testtask'
+require "rake"
+require "rake/testtask"
 
-task :default => [:test]
+task default: [:test]
 
-test_task = Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/rundoc/**/*_test.rb'
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/rundoc/**/*_test.rb"
   t.verbose = false
 end

data/lib/rundoc/cli.rb

@@ -1,24 +1,23 @@
 module Rundoc
   class CLI
-    def build(path: )
+    def build(path:)
       @path = Pathname.new(path).expand_path
       raise "#{@path} does not exist" unless File.exist?(@path)
       raise "Expecting #{@path} to be a rundoc markdown file" unless File.file?(@path)
-      @working_dir  = Pathname.new(File.expand_path("../", @path))
-
+      @working_dir = Pathname.new(File.expand_path("../", @path))
 
       dot_env_path = File.expand_path("../.env", @path)
       if File.exist?(dot_env_path)
-        require 'dotenv'
+        require "dotenv"
         Dotenv.load(dot_env_path)
-        ENV['AWS_ACCESS_KEY_ID']     ||= ENV['BUCKETEER_AWS_ACCESS_KEY_ID']
-        ENV['AWS_REGION']            ||= ENV['BUCKETEER_AWS_REGION']
-        ENV['AWS_SECRET_ACCESS_KEY'] ||= ENV['BUCKETEER_AWS_SECRET_ACCESS_KEY']
-        ENV['AWS_BUCKET_NAME']       ||= ENV['BUCKETEER_BUCKET_NAME']
+        ENV["AWS_ACCESS_KEY_ID"] ||= ENV["BUCKETEER_AWS_ACCESS_KEY_ID"]
+        ENV["AWS_REGION"] ||= ENV["BUCKETEER_AWS_REGION"]
+        ENV["AWS_SECRET_ACCESS_KEY"] ||= ENV["BUCKETEER_AWS_SECRET_ACCESS_KEY"]
+        ENV["AWS_BUCKET_NAME"] ||= ENV["BUCKETEER_BUCKET_NAME"]
       end
 
       source_contents = File.read(@path)
-      tmp_dir         = @working_dir.join("tmp")
+      tmp_dir = @working_dir.join("tmp")
 
       FileUtils.remove_entry_secure(tmp_dir) if tmp_dir.exist?
       tmp_dir.mkdir
@@ -28,7 +27,7 @@ module Rundoc
 
           Instead modify the rundoc script and re-run it.
 
-          Command: #{ $0 } #{$*.join(' ')}
+          Command: #{$0} #{$*.join(" ")}
         STOP -->
       HEREDOC
 
@@ -41,12 +40,12 @@ module Rundoc
 
       puts "== Done, run was successful"
       project_name = if Rundoc.project_root
-        Rundoc.project_root.split('/').last
+        Rundoc.project_root.split("/").last
       else
-        'project'
+        "project"
       end
 
-      project_dir  = @working_dir.join(project_name)
+      project_dir = @working_dir.join(project_name)
 
       FileUtils.remove_entry_secure(project_dir) if project_dir.exist?
 
@@ -62,16 +61,15 @@ module Rundoc
 
       source_path = project_dir.join("README.md")
       puts "== Done, writing original source to #{source_path}"
-      File.open(source_path, "w") { |f| f.write @output }
+      File.write(source_path, @output)
 
       puts "== Copying source"
-      source_path = project_dir.join("coppied-#{@path.to_s.split('/').last}")
-      File.open(source_path, "w") { |f| f.write source_contents }
+      source_path = project_dir.join("copied-#{@path.to_s.split("/").last}")
+      File.write(source_path, source_contents)
 
       Dir.chdir(project_dir) do
         Rundoc.run_after_build
       end
-
     ensure
       Rundoc::CodeCommand::Background::ProcessSpawn.tasks.each do |name, task|
         next unless task.alive?

data/lib/rundoc/code_command/background/log/clear.rb

@@ -1,6 +1,6 @@
 class Rundoc::CodeCommand::Background::Log
   class Clear < Rundoc::CodeCommand
-    def initialize(name: )
+    def initialize(name:)
       @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
     end
 

data/lib/rundoc/code_command/background/log/read.rb

@@ -1,6 +1,6 @@
 class Rundoc::CodeCommand::Background::Log
   class Read < Rundoc::CodeCommand
-    def initialize(name: )
+    def initialize(name:)
       @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
     end
 

data/lib/rundoc/code_command/background/process_spawn.rb

@@ -1,6 +1,6 @@
-require 'shellwords'
-require 'timeout'
-require 'fileutils'
+require "shellwords"
+require "timeout"
+require "fileutils"
 
 class Rundoc::CodeCommand::Background
   # This class is responsible for running processes in the background
@@ -28,8 +28,8 @@ class Rundoc::CodeCommand::Background
   #   ProcessSpawn.find("muh_server") # => <# ProcessSpawn instance >
   #   ProcessSpawn.find("foo") # => RuntimeError "Could not find task with name 'foo', ..."
   class ProcessSpawn
-    def self.tasks
-      @tasks
+    class << self
+      attr_reader :tasks
     end
 
     @tasks = {}
@@ -45,7 +45,7 @@ class Rundoc::CodeCommand::Background
 
     attr_reader :log, :pid
 
-    def initialize(command , timeout: 5, log: Tempfile.new("log"), out: "2>&1")
+    def initialize(command, timeout: 5, log: Tempfile.new("log"), out: "2>&1")
       @command = command
       @timeout_value = timeout
       @log_reference = log # https://twitter.com/schneems/status/1285289971083907075
@@ -68,8 +68,7 @@ class Rundoc::CodeCommand::Background
         end
       end
     rescue Timeout::Error
-      raise "Timeout waiting for #{@command.inspect} to find a match using #{ wait_value.inspect } in \n'#{ log.read }'"
-      false
+      raise "Timeout waiting for #{@command.inspect} to find a match using #{wait_value.inspect} in \n'#{log.read}'"
     end
 
     def alive?
@@ -81,7 +80,7 @@ class Rundoc::CodeCommand::Background
 
     def stop
       return unless alive?
-      Process.kill('TERM', -Process.getpgid(@pid))
+      Process.kill("TERM", -Process.getpgid(@pid))
       Process.wait(@pid)
     end
 

data/lib/rundoc/code_command/background/start.rb

@@ -1,25 +1,25 @@
-require 'tempfile'
+require "tempfile"
 
 class Rundoc::CodeCommand::Background
   class Start < Rundoc::CodeCommand
-    def initialize(command, name: , wait: nil, timeout: 5, log: Tempfile.new("log"), out: "2>&1", allow_fail: false)
+    def initialize(command, name:, wait: nil, timeout: 5, log: Tempfile.new("log"), out: "2>&1", allow_fail: false)
       @command = command
-      @name    = name
-      @wait    = wait
+      @name = name
+      @wait = wait
       @allow_fail = allow_fail
       FileUtils.touch(log)
 
       @spawn = ProcessSpawn.new(
         @command,
         timeout: timeout,
-        log:     log,
-        out:     out
+        log: log,
+        out: out
       )
       ProcessSpawn.add(@name, @spawn)
     end
 
     def to_md(env = {})
-      return "$ #{@command}"
+      "$ #{@command}"
     end
 
     def call(env = {})

data/lib/rundoc/code_command/background/stop.rb

@@ -1,6 +1,6 @@
 class Rundoc::CodeCommand::Background
   class Stop < Rundoc::CodeCommand
-    def initialize(name: )
+    def initialize(name:)
       @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
     end
 

data/lib/rundoc/code_command/background/wait.rb

@@ -1,8 +1,8 @@
 class Rundoc::CodeCommand::Background
   class Wait < Rundoc::CodeCommand
-    def initialize(name: , wait:, timeout: 5)
+    def initialize(name:, wait:, timeout: 5)
       @spawn = Rundoc::CodeCommand::Background::ProcessSpawn.find(name)
-      @wait  = wait
+      @wait = wait
       @timeout_value = Integer(timeout)
     end
 

data/lib/rundoc/code_command/background.rb

@@ -1,9 +1,9 @@
 class Rundoc::CodeCommand::Background
 end
 
-require 'rundoc/code_command/background/process_spawn'
-require 'rundoc/code_command/background/start'
-require 'rundoc/code_command/background/stop'
-require 'rundoc/code_command/background/wait'
-require 'rundoc/code_command/background/log/clear'
-require 'rundoc/code_command/background/log/read'
+require "rundoc/code_command/background/process_spawn"
+require "rundoc/code_command/background/start"
+require "rundoc/code_command/background/stop"
+require "rundoc/code_command/background/wait"
+require "rundoc/code_command/background/log/clear"
+require "rundoc/code_command/background/log/read"

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

@@ -3,34 +3,33 @@ class Rundoc::CodeCommand::Bash
   # we change the directory of the parent program (rundoc) rather than
   # changing the directory of a spawned child (via exec, ``, system, etc.)
   class Cd < Rundoc::CodeCommand::Bash
-
     def initialize(line)
       @line = line
     end
 
     # Ignore duplicate chdir warnings "warning: conflicting chdir during another chdir block"
     def supress_chdir_warning
-      old_stderr     = $stderr
+      old_stderr = $stderr
       capture_stderr = StringIO.new
-      $stderr        = capture_stderr
-      return yield
+      $stderr = capture_stderr
+      yield
     ensure
       if old_stderr
         $stderr = old_stderr
         capture_string = capture_stderr.string
-        $stderr.puts capture_string if capture_string.each_line.count > 1 || !capture_string.include?("conflicting chdir")
+        warn capture_string if capture_string.each_line.count > 1 || !capture_string.include?("conflicting chdir")
       end
     end
 
     def call(env)
-      line = @line.sub('cd', '').strip
+      line = @line.sub("cd", "").strip
       puts "running $ cd #{line}"
 
       supress_chdir_warning do
         Dir.chdir(line)
       end
 
-      return nil
+      nil
     end
   end
 end

data/lib/rundoc/code_command/bash.rb

@@ -1,13 +1,12 @@
 class Rundoc::CodeCommand::Bash < Rundoc::CodeCommand
-
   # line = "cd ..""
   # line = "pwd"
   # line = "ls"
   def initialize(line)
-    @line     = line
+    @line = line
     @contents = ""
-    @delegate = case @line.split(' ').first.downcase
-    when 'cd'
+    @delegate = case @line.split(" ").first.downcase
+    when "cd"
       Cd.new(@line)
     else
       false
@@ -28,16 +27,17 @@ class Rundoc::CodeCommand::Bash < Rundoc::CodeCommand
 
   # markdown doesn't understand bash color codes
   def sanitize_escape_chars(input)
-    input.gsub(/\e\[(\d+)m/, '')
+    input.gsub(/\e\[(\d+)m/, "")
   end
 
   def shell(cmd, stdin = nil)
-    msg  = "Running: $ '#{cmd}'"
-    msg  << " with stdin: '#{stdin.inspect}'" if stdin && !stdin.empty?
+    cmd = "(#{cmd}) 2>&1"
+    msg = "Running: $ '#{cmd}'"
+    msg << " with stdin: '#{stdin.inspect}'" if stdin && !stdin.empty?
     puts msg
 
     result = ""
-    IO.popen("#{cmd} 2>&1", "w+") do |io|
+    IO.popen(cmd, "w+") do |io|
       io << stdin if stdin
       io.close_write
       result = sanitize_escape_chars io.read
@@ -45,13 +45,12 @@ class Rundoc::CodeCommand::Bash < Rundoc::CodeCommand
     unless $?.success?
       raise "Command `#{@line}` exited with non zero status: #{result}" unless keyword.to_s.include?("fail")
     end
-    return result
+    result
   end
 end
 
-
 Rundoc.register_code_command(:bash, Rundoc::CodeCommand::Bash)
-Rundoc.register_code_command(:'$',  Rundoc::CodeCommand::Bash)
-Rundoc.register_code_command(:'fail.$',  Rundoc::CodeCommand::Bash)
+Rundoc.register_code_command(:"$", Rundoc::CodeCommand::Bash)
+Rundoc.register_code_command(:"fail.$", Rundoc::CodeCommand::Bash)
 
-require 'rundoc/code_command/bash/cd'
+require "rundoc/code_command/bash/cd"