markdown_exec 0.1.3 → 0.2.3

data/lib/markdown_exec.rb

@@ -3,18 +3,79 @@
 
 # encoding=utf-8
 
-# rubocop:disable Style/GlobalVars
-$pdebug = !(ENV['MARKDOWN_EXEC_DEBUG'] || '').empty?
-
 require 'open3'
 require 'optparse'
-# require 'pathname'
 require 'tty-prompt'
 require 'yaml'
+
+##
+# default if nil
+# false if empty or '0'
+# else true
+
+def env_bool(name, default: false)
+  return default if (val = ENV[name]).nil?
+  return false if val.empty? || val == '0'
+
+  true
+end
+
+def env_int(name, default: 0)
+  return default if (val = ENV[name]).nil?
+  return default if val.empty?
+
+  val.to_i
+end
+
+def env_str(name, default: '')
+  ENV[name] || default
+end
+
+$pdebug = env_bool 'MDE_DEBUG'
+
 require_relative 'markdown_exec/version'
 
+$stderr.sync = true
+$stdout.sync = true
+
 BLOCK_SIZE = 1024
-SELECT_PAGE_HEIGHT = 12
+
+class Object # rubocop:disable Style/Documentation
+  def present?
+    self && !blank?
+  end
+end
+
+class String # rubocop:disable Style/Documentation
+  BLANK_RE = /\A[[:space:]]*\z/.freeze
+  def blank?
+    empty? || BLANK_RE.match?(self)
+  end
+end
+
+public
+
+# debug output
+#
+def tap_inspect(format: nil, name: 'return')
+  return self unless $pdebug
+
+  fn = case format
+       when :json
+         :to_json
+       when :string
+         :to_s
+       when :yaml
+         :to_yaml
+       else
+         :inspect
+       end
+
+  puts "-> #{caller[0].scan(/in `?(\S+)'$/)[0][0]}()" \
+       " #{name}: #{method(fn).call}"
+
+  self
+end
 
 module MarkdownExec
   class Error < StandardError; end
@@ -26,494 +87,574 @@ module MarkdownExec
 
     def initialize(options = {})
       @options = options
+      @prompt = TTY::Prompt.new(interrupt: :exit)
+    end
+
+    ##
+    # options necessary to start, parse input, defaults for cli options
+
+    def base_options
+      {
+        # commands
+        list_blocks: false, # command
+        list_docs: false, # command
+
+        # command options
+        filename: env_str('MDE_FILENAME', default: nil), # option Filename to open
+        output_execution_summary: env_bool('MDE_OUTPUT_EXECUTION_SUMMARY', default: false), # option
+        output_script: env_bool('MDE_OUTPUT_SCRIPT', default: false), # option
+        output_stdout: env_bool('MDE_OUTPUT_STDOUT', default: true), # option
+        path: env_str('MDE_PATH', default: nil), # option Folder to search for files
+        save_executed_script: env_bool('MDE_SAVE_EXECUTED_SCRIPT', default: false), # option
+        saved_script_folder: env_str('MDE_SAVED_SCRIPT_FOLDER', default: 'logs'), # option
+        user_must_approve: env_bool('MDE_USER_MUST_APPROVE', default: true), # option Pause for user to approve script
+
+        # configuration options
+        block_name_excluded_match: env_str('MDE_BLOCK_NAME_EXCLUDED_MATCH', default: '^\(.+\)$'),
+        block_name_match: env_str('MDE_BLOCK_NAME_MATCH', default: ':(?<title>\S+)( |$)'),
+        block_required_scan: env_str('MDE_BLOCK_REQUIRED_SCAN', default: '\+\S+'),
+        fenced_start_and_end_match: env_str('MDE_FENCED_START_AND_END_MATCH', default: '^`{3,}'),
+        fenced_start_ex_match: env_str('MDE_FENCED_START_EX_MATCH', default: '^`{3,}(?<shell>[^`\s]*) *(?<name>.*)$'),
+        heading1_match: env_str('MDE_HEADING1_MATCH', default: '^# *(?<name>[^#]*?) *$'),
+        heading2_match: env_str('MDE_HEADING2_MATCH', default: '^## *(?<name>[^#]*?) *$'),
+        heading3_match: env_str('MDE_HEADING3_MATCH', default: '^### *(?<name>.+?) *$'),
+        md_filename_glob: env_str('MDE_MD_FILENAME_GLOB', default: '*.[Mm][Dd]'),
+        md_filename_match: env_str('MDE_MD_FILENAME_MATCH', default: '.+\\.md'),
+        mdheadings: true, # use headings (levels 1,2,3) in block lable
+        select_page_height: env_int('MDE_SELECT_PAGE_HEIGHT', default: 12)
+      }
+    end
+
+    def default_options
+      {
+        bash: true, # bash block parsing in get_block_summary()
+        exclude_expect_blocks: true,
+        exclude_matching_block_names: true, # exclude hidden blocks
+        output_saved_script_filename: false,
+        prompt_select_block: 'Choose a block:', # in select_and_approve_block()
+        prompt_select_md: 'Choose a file:', # in select_md_file()
+        saved_script_filename: nil, # calculated
+        struct: true # allow get_block_summary()
+      }
     end
 
-    def count_blocks
+    # Returns true if all files are EOF
+    #
+    def all_at_eof(files)
+      files.find { |f| !f.eof }.nil?
+    end
+
+    def approve_block(opts, blocks_in_file)
+      required_blocks = list_recursively_required_blocks(blocks_in_file, opts[:block_name])
+      display_command(opts, required_blocks) if opts[:output_script] || opts[:user_must_approve]
+
+      allow = true
+      allow = @prompt.yes? 'Process?' if opts[:user_must_approve]
+      opts[:ir_approve] = allow
+      selected = get_block_by_name blocks_in_file, opts[:block_name]
+
+      if opts[:ir_approve]
+        write_command_file(opts, required_blocks) if opts[:save_executed_script]
+        command_execute opts, required_blocks.flatten.join("\n")
+      end
+
+      selected[:name]
+    end
+
+    def code(table, block)
+      all = [block[:name]] + recursively_required(table, block[:reqs])
+      all.reverse.map do |req|
+        get_block_by_name(table, req).fetch(:body, '')
+      end
+         .flatten(1)
+         .tap_inspect
+    end
+
+    def command_execute(opts, cmd2)
+      @execute_options = opts
+      @execute_started_at = Time.now.utc
+      Open3.popen3(cmd2) do |stdin, stdout, stderr|
+        stdin.close_write
+        begin
+          files = [stdout, stderr]
+
+          until all_at_eof(files)
+            ready = IO.select(files)
+
+            next unless ready
+
+            # readable = ready[0]
+            # # writable = ready[1]
+            # # exceptions = ready[2]
+            @execute_files = Hash.new([])
+            ready.each.with_index do |readable, ind|
+              readable.each do |f|
+                block = f.read_nonblock(BLOCK_SIZE)
+                @execute_files[ind] = @execute_files[ind] + [block]
+                print block if opts[:output_stdout]
+              rescue EOFError #=> e
+                # do nothing at EOF
+              end
+            end
+          end
+        rescue IOError => e
+          fout "IOError: #{e}"
+        end
+        @execute_completed_at = Time.now.utc
+      end
+    rescue Errno::ENOENT => e
+      @execute_aborted_at = Time.now.utc
+      @execute_error_message = e.message
+      @execute_error = e
+      fout "Error ENOENT: #{e.inspect}"
+    end
+
+    def count_blocks_in_filename
+      fenced_start_and_end_match = Regexp.new @options[:fenced_start_and_end_match]
       cnt = 0
-      File.readlines(options[:mdfilename]).each do |line|
-        cnt += 1 if line.match(/^```/)
+      File.readlines(@options[:filename]).each do |line|
+        cnt += 1 if line.match(fenced_start_and_end_match)
       end
       cnt / 2
     end
 
-    def find_files
-      puts "pwd: #{`pwd`}" if $pdebug
-      # `ls -1 *.md`.split("\n").tap { |ret| puts "find_files() ret: #{ret.inspect}" if $pdebug }
-      `ls -1 #{File.join options[:mdfolder], '*.md'}`.split("\n").tap do |ret|
-        puts "find_files() ret: #{ret.inspect}" if $pdebug
+    def display_command(_opts, required_blocks)
+      required_blocks.each { |cb| fout cb }
+    end
+
+    def exec_block(options, block_name = '')
+      options = default_options.merge options
+      update_options options, over: false
+
+      # document and block reports
+      #
+      files = list_files_per_options(options)
+      if @options[:list_docs]
+        fout_list files
+        return
+      end
+
+      if @options[:list_blocks]
+        fout_list (files.map do |file|
+                     make_block_labels(filename: file, struct: true)
+                   end).flatten(1)
+        return
       end
+
+      # process
+      #
+      select_and_approve_block(
+        bash: true,
+        block_name: block_name,
+        filename: select_md_file(files),
+        struct: true
+      )
+
+      fout "saved_filespec: #{@execute_script_filespec}" if @options[:output_saved_script_filename]
+
+      output_execution_summary if @options[:output_execution_summary]
     end
 
+    # standard output; not for debug
+    #
     def fout(str)
-      puts str # to stdout
+      puts str
     end
 
-    def copts(call_options = {}, options_block = nil)
-      class_call_options = options.merge(call_options || {})
-      if options_block
-        options_block.call class_call_options
-      else
-        class_call_options
-      end.tap { |ret| puts "copts() ret: #{ret.inspect}" if $pdebug }
+    def fout_list(str)
+      puts str
     end
 
-    def bsr(headings, title)
-      # puts "bsr() headings: #{headings.inspect}"
-      { headings: headings, name: title, title: title }
+    def fout_section(name, data)
+      puts "# #{name}"
+      puts data.to_yaml
     end
 
-    def block_summary(opts, headings, block_title, current)
-      puts "block_summary() block_title: #{block_title.inspect}" if $pdebug
+    def get_block_by_name(table, name, default = {})
+      table.select { |block| block[:name] == name }.fetch(0, default)
+    end
+
+    def get_block_summary(opts, headings, block_title, current)
       return [current] unless opts[:struct]
 
-      # return [{ body: current, name: block_title, title: block_title }] unless opts[:bash]
-      return [bsr(headings, block_title).merge({ body: current })] unless opts[:bash]
+      return [summarize_block(headings, block_title).merge({ body: current })] unless opts[:bash]
 
-      bm = block_title.match(/:(\S+)( |$)/)
-      reqs = block_title.scan(/\+\S+/).map { |s| s[1..] }
-
-      if $pdebug
-        puts ["block_summary() bm: #{bm.inspect}",
-              "block_summary() reqs: #{reqs.inspect}"]
-      end
+      bm = block_title.match(Regexp.new(opts[:block_name_match]))
+      reqs = block_title.scan(Regexp.new(opts[:block_required_scan])).map { |s| s[1..] }
 
       if bm && bm[1]
-        # [{ body: current, name: bm[1], reqs: reqs, title: bm[1] }]
-        [bsr(headings, bm[1]).merge({ body: current, reqs: reqs })]
+        [summarize_block(headings, bm[:title]).merge({ body: current, reqs: reqs })]
       else
-        # [{ body: current, name: block_title, reqs: reqs, title: block_title }]
-        [bsr(headings, block_title).merge({ body: current, reqs: reqs })]
+        [summarize_block(headings, block_title).merge({ body: current, reqs: reqs })]
       end
     end
 
-    def get_blocks(call_options = {}, &options_block)
-      opts = copts call_options, options_block
+    def list_blocks_in_file(call_options = {}, &options_block)
+      opts = optsmerge call_options, options_block
+
+      unless opts[:filename]&.present?
+        fout 'No blocks found.'
+        exit 1
+      end
 
+      fenced_start_and_end_match = Regexp.new opts[:fenced_start_and_end_match]
+      fenced_start_ex = Regexp.new opts[:fenced_start_ex_match]
+      block_title = ''
       blocks = []
       current = nil
-      in_block = false
-      block_title = ''
-
       headings = []
-      File.readlines(opts[:mdfilename]).each do |line|
-        puts "get_blocks() line: #{line.inspect}" if $pdebug
+      in_block = false
+      File.readlines(opts[:filename]).each do |line|
         continue unless line
 
         if opts[:mdheadings]
-          if (lm = line.match(/^### *(.+?) *$/))
-            headings = [headings[0], headings[1], lm[1]]
-          elsif (lm = line.match(/^## *([^#]*?) *$/))
-            headings = [headings[0], lm[1]]
-          elsif (lm = line.match(/^# *([^#]*?) *$/))
-            headings = [lm[1]]
+          if (lm = line.match(Regexp.new(opts[:heading3_match])))
+            headings = [headings[0], headings[1], lm[:name]]
+          elsif (lm = line.match(Regexp.new(opts[:heading2_match])))
+            headings = [headings[0], lm[:name]]
+          elsif (lm = line.match(Regexp.new(opts[:heading1_match])))
+            headings = [lm[:name]]
           end
-          puts "get_blocks() headings: #{headings.inspect}" if $pdebug
         end
 
-        if line.match(/^`{3,}/)
+        if line.match(fenced_start_and_end_match)
           if in_block
-            puts 'get_blocks() in_block' if $pdebug
             if current
-
-              # block_title ||= current.join(' ').gsub(/  +/, ' ')[0..64]
               block_title = current.join(' ').gsub(/  +/, ' ')[0..64] if block_title.nil? || block_title.empty?
-
-              blocks += block_summary opts, headings, block_title, current
+              blocks += get_block_summary opts, headings, block_title, current
               current = nil
             end
             in_block = false
             block_title = ''
           else
-            ## new block
+            # new block
             #
-
-            # lm = line.match(/^`{3,}([^`\s]+)( .+)?$/)
-            lm = line.match(/^`{3,}([^`\s]*) *(.*)$/)
-
+            lm = line.match(fenced_start_ex)
             do1 = false
             if opts[:bash_only]
-              do1 = true if lm && (lm[1] == 'bash')
-            elsif opts[:exclude_expect_blocks]
-              do1 = true unless lm && (lm[1] == 'expect')
+              do1 = true if lm && (lm[:shell] == 'bash')
             else
               do1 = true
-            end
-            if $pdebug
-              puts ["get_blocks() lm: #{lm.inspect}",
-                    "get_blocks() opts: #{opts.inspect}",
-                    "get_blocks() do1: #{do1}"]
+              do1 = !(lm && (lm[:shell] == 'expect')) if opts[:exclude_expect_blocks]
             end
 
-            if do1 && (!opts[:title_match] || (lm && lm[2] && lm[2].match(opts[:title_match])))
+            in_block = true
+            if do1 && (!opts[:title_match] || (lm && lm[:name] && lm[:name].match(opts[:title_match])))
               current = []
-              in_block = true
-              block_title = (lm && lm[2])
+              block_title = (lm && lm[:name])
             end
-
           end
         elsif current
           current += [line.chomp]
         end
       end
-      blocks.tap { |ret| puts "get_blocks() ret: #{ret.inspect}" if $pdebug }
-    end # get_blocks
-
-    def make_block_label(block, call_options = {})
-      opts = options.merge(call_options)
-      puts "make_block_label() opts: #{opts.inspect}" if $pdebug
-      puts "make_block_label() block: #{block.inspect}" if $pdebug
-      if opts[:mdheadings]
-        heads = block.fetch(:headings, []).compact.join(' # ')
-        "#{block[:title]} [#{heads}] (#{opts[:mdfilename]})"
-      else
-        "#{block[:title]} (#{opts[:mdfilename]})"
-      end
+      blocks.tap_inspect
     end
 
-    def make_block_labels(call_options = {})
-      opts = options.merge(call_options)
-      get_blocks(opts).map do |block|
-        make_block_label block, opts
-      end
+    def list_files_per_options(options)
+      default_filename = 'README.md'
+      default_folder = '.'
+      if options[:filename]&.present?
+        list_files_specified(options[:filename], options[:path], default_filename, default_folder)
+      else
+        list_files_specified(nil, options[:path], default_filename, default_folder)
+      end.tap_inspect
     end
 
-    def select_block(call_options = {}, &options_block)
-      opts = copts call_options, options_block
-
-      blocks = get_blocks(opts.merge(struct: true))
-      puts "select_block() blocks: #{blocks.to_yaml}" if $pdebug
-
-      prompt = TTY::Prompt.new(interrupt: :exit)
-      pt = "#{opts.fetch(:prompt, nil) || 'Pick one'}:"
-      puts "select_block() pt: #{pt.inspect}" if $pdebug
-
-      blocks.each { |block| block.merge! label: make_block_label(block, opts) }
-      block_labels = blocks.map { |block| block[:label] }
-      puts "select_block() block_labels: #{block_labels.inspect}" if $pdebug
-
-      if opts[:preview_options]
-        select_per_page = 3
-        block_labels.each do |bn|
-          fout " - #{bn}"
-        end
+    def list_files_specified(specified_filename, specified_folder, default_filename, default_folder, filetree = nil)
+      fn = File.join(if specified_filename&.present?
+                       if specified_folder&.present?
+                         [specified_folder, specified_filename]
+                       elsif specified_filename.start_with? '/'
+                         [specified_filename]
+                       else
+                         [default_folder, specified_filename]
+                       end
+                     elsif specified_folder&.present?
+                       if filetree
+                         [specified_folder, @options[:md_filename_match]]
+                       else
+                         [specified_folder, @options[:md_filename_glob]]
+                       end
+                     else
+                       [default_folder, default_filename]
+                     end)
+      if filetree
+        filetree.select { |filename| filename == fn || filename.match(/^#{fn}$/) || filename.match(%r{^#{fn}/.+$}) }
       else
-        select_per_page = SELECT_PAGE_HEIGHT
-      end
-
-      return nil if block_labels.count.zero?
+        Dir.glob(fn)
+      end.tap_inspect
+    end
 
-      sel = prompt.select(pt, block_labels, per_page: select_per_page)
-      puts "select_block() sel: #{sel.inspect}" if $pdebug
-      # catch
-      # # catch TTY::Reader::InputInterrupt
-      #   puts "InputInterrupt"
-      # end
+    def list_markdown_files_in_path
+      Dir.glob(File.join(@options[:path], @options[:md_filename_glob])).tap_inspect
+    end
 
-      label_block = blocks.select { |block| block[:label] == sel }.fetch(0, nil)
-      puts "select_block() label_block: #{label_block.inspect}" if $pdebug
-      sel = label_block[:name]
-      puts "select_block() sel: #{sel.inspect}" if $pdebug
+    def list_named_blocks_in_file(call_options = {}, &options_block)
+      opts = optsmerge call_options, options_block
+      block_name_excluded_match = Regexp.new opts[:block_name_excluded_match]
+      list_blocks_in_file(opts).map do |block|
+        next if opts[:exclude_matching_block_names] && block[:name].match(block_name_excluded_match)
 
-      cbs = code_blocks(blocks, sel)
-      puts "select_block() cbs: #{cbs.inspect}" if $pdebug
+        block
+      end.compact.tap_inspect
+    end
 
-      ## display code blocks for approval
-      #
-      cbs.each { |cb| fout cb } if opts[:display] || opts[:approve]
+    def list_recursively_required_blocks(table, name)
+      name_block = get_block_by_name(table, name)
+      raise "Named code block `#{name}` not found." if name_block.nil? || name_block.keys.empty?
 
-      allow = true
-      allow = prompt.yes? 'Process?' if opts[:approve]
-
-      selected = block_by_name blocks, sel
-      puts "select_block() selected: #{selected.inspect}" if $pdebug
-      if allow && opts[:execute]
-
-        ## process in script, to handle line continuations
-        #
-        cmd2 = cbs.flatten.join("\n")
-        fout "$ #{cmd2.to_yaml}"
-
-        # Open3.popen3(cmd2) do |stdin, stdout, stderr, wait_thr|
-        #   cnt += 1
-        #   # stdin.puts "This is sent to the command"
-        #   # stdin.close                # we're done
-        #   stdout_str = stdout.read   # read stdout to string. note that this will block until the command is done!
-        #   stderr_str = stderr.read   # read stderr to string
-        #   status = wait_thr.value    # will block until the command finishes; returns status that responds to .success?
-        #   fout "#{stdout_str}"
-        #   fout "#{cnt}: err: #{stderr_str}" if stderr_str != ''
-        #   # fout "#{cnt}: stt: #{status}"
-        # end
-
-        Open3.popen3(cmd2) do |stdin, stdout, stderr|
-          stdin.close_write
-          begin
-            files = [stdout, stderr]
-
-            until all_eof(files)
-              ready = IO.select(files)
-
-              next unless ready
-
-              readable = ready[0]
-              # writable = ready[1]
-              # exceptions = ready[2]
+      all = [name_block[:name]] + recursively_required(table, name_block[:reqs])
 
-              readable.each do |f|
-                # fileno = f.fileno
+      # in order of appearance in document
+      table.select { |block| all.include? block[:name] }
+           .map { |block| block.fetch(:body, '') }
+           .flatten(1)
+           .tap_inspect
+    end
 
-                data = f.read_nonblock(BLOCK_SIZE)
-                # fout "- fileno: #{fileno}\n#{data}"
-                fout data
-              rescue EOFError #=> e
-                # fout "fileno: #{fileno} EOF"
-              end
-            end
-          rescue IOError => e
-            fout "IOError: #{e}"
-          end
-        end
+    def make_block_label(block, call_options = {})
+      opts = options.merge(call_options)
+      if opts[:mdheadings]
+        heads = block.fetch(:headings, []).compact.join(' # ')
+        "#{block[:title]}  [#{heads}]  (#{opts[:filename]})"
+      else
+        "#{block[:title]}  (#{opts[:filename]})"
       end
+    end
 
-      selected[:name]
-    end # select_block
-
-    def select_md_file
-      opts = options
-      files = find_files
-      if files.count == 1
-        sel = files[0]
-      elsif files.count >= 2
-
-        if opts[:preview_options]
-          select_per_page = 3
-          files.each do |file|
-            fout " - #{file}"
-          end
-        else
-          select_per_page = SELECT_PAGE_HEIGHT
-        end
-
-        prompt = TTY::Prompt.new
-        sel = prompt.select("#{opts.fetch(:prompt, 'Pick one')}:", files, per_page: select_per_page)
-      end
+    def make_block_labels(call_options = {})
+      opts = options.merge(call_options)
+      list_blocks_in_file(opts).map do |block|
+        # next if opts[:exclude_matching_block_names] && block[:name].match(%r{^:\(.+\)$})
 
-      sel
+        make_block_label block, opts
+      end.compact.tap_inspect
     end
 
-    # Returns true if all files are EOF
-    #
-    def all_eof(files)
-      files.find { |f| !f.eof }.nil?
+    def option_exclude_blocks(opts, blocks)
+      block_name_excluded_match = Regexp.new opts[:block_name_excluded_match]
+      if opts[:exclude_matching_block_names]
+        blocks.reject { |block| block[:name].match(block_name_excluded_match) }
+      else
+        blocks
+      end
     end
 
-    def code(table, block)
-      puts "code() table: #{table.inspect}" if $pdebug
-      puts "code() block: #{block.inspect}" if $pdebug
-      all = [block[:name]] + unroll(table, block[:reqs])
-      puts "code() all: #{all.inspect}" if $pdebug
-      all.reverse.map do |req|
-        puts "code() req: #{req.inspect}" if $pdebug
-        block_by_name(table, req).fetch(:body, '')
-      end
-         .flatten(1)
-         .tap { |ret| puts "code() ret: #{ret.inspect}" if $pdebug }
+    def optsmerge(call_options = {}, options_block = nil)
+      class_call_options = @options.merge(call_options || {})
+      if options_block
+        options_block.call class_call_options
+      else
+        class_call_options
+      end.tap_inspect
     end
 
-    def block_by_name(table, name, default = {})
-      table.select { |block| block[:name] == name }.fetch(0, default)
+    def output_execution_summary
+      fout_section 'summary', {
+        execute_aborted_at: @execute_aborted_at,
+        execute_completed_at: @execute_completed_at,
+        execute_error: @execute_error,
+        execute_error_message: @execute_error_message,
+        execute_files: @execute_files,
+        execute_options: @execute_options,
+        execute_started_at: @execute_started_at,
+        execute_script_filespec: @execute_script_filespec
+      }
     end
 
-    def code_blocks(table, name)
-      puts "code_blocks() table: #{table.inspect}" if $pdebug
-      puts "code_blocks() name: #{name.inspect}" if $pdebug
-      name_block = block_by_name(table, name)
-      puts "code_blocks() name_block: #{name_block.inspect}" if $pdebug
-      all = [name_block[:name]] + unroll(table, name_block[:reqs])
-      puts "code_blocks() all: #{all.inspect}" if $pdebug
+    def read_configuration_file!(options, configuration_path)
+      return unless File.exist?(configuration_path)
 
-      # in order of appearance in document
-      table.select { |block| all.include? block[:name] }
-           .map { |block| block.fetch(:body, '') }
-           .flatten(1)
-           .tap { |ret| puts "code_blocks() ret: #{ret.inspect}" if $pdebug }
+      # rubocop:disable Security/YAMLLoad
+      options.merge!((YAML.load(File.open(configuration_path)) || {})
+        .transform_keys(&:to_sym))
+      # rubocop:enable Security/YAMLLoad
     end
 
-    def unroll(table, reqs)
-      puts "unroll() table: #{table.inspect}" if $pdebug
-      puts "unroll() reqs: #{reqs.inspect}" if $pdebug
+    def recursively_required(table, reqs)
       all = []
       rem = reqs
       while rem.count.positive?
-        puts "unrol() rem: #{rem.inspect}" if $pdebug
         rem = rem.map do |req|
-          puts "unrol() req: #{req.inspect}" if $pdebug
           next if all.include? req
 
           all += [req]
-          puts "unrol() all: #{all.inspect}" if $pdebug
-          block_by_name(table, req).fetch(:reqs, [])
+          get_block_by_name(table, req).fetch(:reqs, [])
         end
                  .compact
                  .flatten(1)
-                 .tap { |_ret| puts "unroll() rem: #{rem.inspect}" if $pdebug }
+                 .tap_inspect(name: 'rem')
       end
-      all.tap { |ret| puts "unroll() ret: #{ret.inspect}" if $pdebug }
-    end
-
-    # $stderr.sync = true
-    # $stdout.sync = true
-
-    ## configuration file
-    #
-    def read_configuration!(options, configuration_path)
-      if File.exist?(configuration_path)
-        # rubocop:disable Security/YAMLLoad
-        options.merge!((YAML.load(File.open(configuration_path)) || {})
-          .transform_keys(&:to_sym))
-        # rubocop:enable Security/YAMLLoad
-      end
-      options
+      all.tap_inspect
     end
 
     def run
       ## default configuration
       #
-      options = {
-        mdheadings: true,
-        list_blocks: false,
-        list_docs: false,
-        mdfilename: 'README.md',
-        mdfolder: '.'
-      }
+      @options = base_options
 
-      def options_finalize!(options); end
+      ## post-parse options configuration
+      #
+      options_finalize = ->(_options) {}
 
-      # puts "MDE run() ARGV: #{ARGV.inspect}"
+      proc_self = ->(value) { value }
+      proc_to_i = ->(value) { value.to_i != 0 }
+      proc_true = ->(_) { true }
 
       # read local configuration file
       #
-      read_configuration! options, ".#{MarkdownExec::APP_NAME.downcase}.yml"
+      read_configuration_file! @options, ".#{MarkdownExec::APP_NAME.downcase}.yml"
 
-      ## read current details for aws resources from app_data_file
-      #
-      # load_resources! options
-      # puts "q31 options: #{options.to_yaml}" if $pdebug
-
-      # rubocop:disable Metrics/BlockLength
       option_parser = OptionParser.new do |opts|
         executable_name = File.basename($PROGRAM_NAME)
         opts.banner = [
-          "#{MarkdownExec::APP_NAME} - #{MarkdownExec::APP_DESC} (#{MarkdownExec::VERSION})",
-          "Usage: #{executable_name} [options]"
+          "#{MarkdownExec::APP_NAME}" \
+          " - #{MarkdownExec::APP_DESC} (#{MarkdownExec::VERSION})",
+          "Usage: #{executable_name} [path] [filename] [options]"
         ].join("\n")
 
-        ## menu top: on_head appear in reverse order added
-        #
-        opts.on('--config PATH', 'Read configuration file') do |value|
-          read_configuration! options, value
-        end
-
-        ## menu body: items appear in order added
-        #
-        opts.on('-f RELATIVE', '--mdfilename', 'Name of document') do |value|
-          options[:mdfilename] = value
-        end
-
-        opts.on('-p PATH', '--mdfolder', 'Path to documents') do |value|
-          options[:mdfolder] = value
-        end
-
-        opts.on('--list-blocks', 'List blocks') do |_value|
-          options[:list_blocks] = true
-        end
-
-        opts.on('--list-docs', 'List docs in current folder') do |_value|
-          options[:list_docs] = true
+        summary_head = [
+          ['config', nil, nil, 'PATH', 'Read configuration file',
+           nil, ->(value) { read_configuration_file! options, value }],
+          ['debug', 'd', 'MDE_DEBUG', 'BOOL', 'Debug output',
+           nil, ->(value) { $pdebug = value.to_i != 0 }]
+        ]
+
+        summary_body = [
+          ['filename', 'f', 'MDE_FILENAME', 'RELATIVE', 'Name of document',
+           :filename, proc_self],
+          ['list-blocks', nil, nil, nil, 'List blocks',
+           :list_blocks, proc_true],
+          ['list-docs', nil, nil, nil, 'List docs in current folder',
+           :list_docs, proc_true],
+          ['output-execution-summary', nil, 'MDE_OUTPUT_EXECUTION_SUMMARY', 'BOOL', 'Display summary for execution',
+           :output_execution_summary, proc_to_i],
+          ['output-script', nil, 'MDE_OUTPUT_SCRIPT', 'BOOL', 'Display script',
+           :output_script, proc_to_i],
+          ['output-stdout', nil, 'MDE_OUTPUT_STDOUT', 'BOOL', 'Display standard output from execution',
+           :output_stdout, proc_to_i],
+          ['path', 'p', 'MDE_PATH', 'PATH', 'Path to documents',
+           :path, proc_self],
+          ['save-executed-script', nil, 'MDE_SAVE_EXECUTED_SCRIPT', 'BOOL', 'Save executed script',
+           :save_executed_script, proc_to_i],
+          ['saved-script-folder', nil, 'MDE_SAVED_SCRIPT_FOLDER', 'SPEC', 'Saved script folder',
+           :saved_script_folder, proc_self],
+          ['user-must-approve', nil, 'MDE_USER_MUST_APPROVE', 'BOOL', 'Pause to approve execution',
+           :user_must_approve, proc_to_i]
+        ]
+
+        # rubocop:disable Style/Semicolon
+        summary_tail = [
+          [nil, '0', nil, nil, 'Show configuration',
+           nil, ->(_) { options_finalize.call options; fout options.to_yaml }],
+          ['help', 'h', nil, nil, 'App help',
+           nil, ->(_) { fout option_parser.help; exit }],
+          ['version', 'v', nil, nil, 'App version',
+           nil, ->(_) { fout MarkdownExec::VERSION; exit }],
+          ['exit', 'x', nil, nil, 'Exit app',
+           nil, ->(_) { exit }]
+        ]
+        # rubocop:enable Style/Semicolon
+
+        (summary_head + summary_body + summary_tail)
+          .map do |long_name, short_name, env_var, arg_name, description, opt_name, proc1| # rubocop:disable Metrics/ParameterLists
+          opts.on(*[long_name.present? ? "--#{long_name}#{arg_name.present? ? (' ' + arg_name) : ''}" : nil,
+                    short_name.present? ? "-#{short_name}" : nil,
+                    [description,
+                     env_var.present? ? "env: #{env_var}" : nil].compact.join(' - '),
+                    lambda { |value|
+                      ret = proc1.call(value)
+                      options[opt_name] = ret if opt_name
+                      ret
+                    }].compact)
         end
+      end
+      option_parser.load # filename defaults to basename of the program without suffix in a directory ~/.options
+      option_parser.environment # env defaults to the basename of the program.
+      rest = option_parser.parse! # (into: options)
 
-        ## menu bottom: items appear in order added
-        #
-        opts.on_tail('-h', '--help', 'App help') do |_value|
-          puts option_parser.help
-          exit
-        end
+      ## finalize configuration
+      #
+      options_finalize.call options
 
-        opts.on_tail('-v', '--version', 'App version') do |_value|
-          puts MarkdownExec::VERSION
-          exit
+      ## position 0: file or folder (optional)
+      #
+      if (pos = rest.fetch(0, nil))&.present?
+        if Dir.exist?(pos)
+          options[:path] = pos
+        elsif File.exist?(pos)
+          options[:filename] = pos
+        else
+          raise "Invalid parameter: #{pos}"
         end
+      end
 
-        opts.on_tail('-x', '--exit', 'Exit app') do |_value|
-          exit
-        end
+      ## position 1: block name (optional)
+      #
+      block_name = rest.fetch(1, nil)
 
-        opts.on_tail('-0', 'Show configuration') do |_v|
-          options_finalize! options
-          puts options.to_yaml
-        end
-      end # OptionParser
-      # rubocop:enable Metrics/BlockLength
+      exec_block options, block_name
+    end
 
-      option_parser.load # filename defaults to basename of the program without suffix in a directory ~/.options
-      option_parser.environment # env defaults to the basename of the program.
-      option_parser.parse! # (into: options)
-      options_finalize! options
+    def select_and_approve_block(call_options = {}, &options_block)
+      opts = optsmerge call_options, options_block
+      blocks_in_file = list_blocks_in_file(opts.merge(struct: true))
 
-      ## process
-      #
-      # rubocop:disable Metrics/BlockLength
-      loop do # once
-        mp = MarkParse.new options
-        options.merge!(
-          {
-            approve: true,
-            bash: true,
-            display: true,
-            exclude_expect_blocks: true,
-            execute: true,
-            prompt: 'Execute',
-            struct: true
-          }
-        )
-
-        ## show
-        #
-        if options[:list_docs]
-          fout mp.find_files
-          break
-        end
+      unless opts[:block_name].present?
+        pt = (opts[:prompt_select_block]).to_s
+        blocks_in_file.each { |block| block.merge! label: make_block_label(block, opts) }
+        block_labels = option_exclude_blocks(opts, blocks_in_file).map { |block| block[:label] }
 
-        if options[:list_blocks]
-          fout (mp.find_files.map do |file|
-                  mp.make_block_labels(mdfilename: file, struct: true)
-                end).flatten(1).to_yaml
-          break
-        end
+        return nil if block_labels.count.zero?
 
-        ## process
-        #
-        mp.select_block(bash: true, struct: true) if options[:mdfilename]
+        sel = @prompt.select(pt, block_labels, per_page: opts[:select_page_height])
+        label_block = blocks_in_file.select { |block| block[:label] == sel }.fetch(0, nil)
+        opts[:block_name] = label_block[:name]
+      end
 
-# rubocop:disable Style/BlockComments
-=begin
-  # rescue ArgumentError => e
-  #   puts "User abort: #{e}"
+      approve_block opts, blocks_in_file
+    end
 
-  # rescue StandardError => e
-  #   puts "ERROR: #{e}"
-  #   raise StandardError, e
+    def select_md_file(files_ = nil)
+      opts = options
+      files = files_ || list_markdown_files_in_path
+      if files.count == 1
+        files[0]
+      elsif files.count >= 2
+        @prompt.select(opts[:prompt_select_md].to_s, files, per_page: opts[:select_page_height])
+      end
+    end
 
-  # ensure
-  #   exit
-=end
-        # rubocop:enable Style/BlockComments
+    def summarize_block(headings, title)
+      { headings: headings, name: title, title: title }
+    end
 
-        break unless false # rubocop:disable Lint/LiteralAsCondition
-      end # loop
-    end # run
-  end # class MarkParse
+    def update_options(opts = {}, over: true)
+      if over
+        @options = @options.merge opts
+      else
+        @options.merge! opts
+      end
+      @options
+    end
 
-  # rubocop:enable Metrics/BlockLength
-  # rubocop:enable Style/GlobalVars
-end # module MarkdownExec
+    def write_command_file(opts, required_blocks)
+      return unless opts[:saved_script_filename].present?
+
+      fne = File.basename(opts[:filename], '.*').gsub(/[^a-z0-9]/i, '-') # scan(/[a-z0-9]/i).join
+      bne = opts[:block_name].gsub(/[^a-z0-9]/i, '-') # scan(/[a-z0-9]/i).join
+      opts[:saved_script_filename] = "mde_#{Time.now.utc.strftime '%F-%H-%M-%S'}_#{fne}_#{bne}.sh"
+
+      @options[:saved_filespec] = File.join opts[:saved_script_folder], opts[:saved_script_filename]
+      @execute_script_filespec = @options[:saved_filespec]
+      dirname = File.dirname(@options[:saved_filespec])
+      Dir.mkdir dirname unless File.exist?(dirname)
+      File.write(@options[:saved_filespec], "#!/usr/bin/env bash\n" \
+                                            "# file_name: #{opts[:filename]}\n" \
+                                            "# block_name: #{opts[:block_name]}\n" \
+                                            "# time: #{Time.now.utc}\n" \
+                                            "#{required_blocks.flatten.join("\n")}\n")
+    end
+  end
+end