runfile 0.12.0 → 1.0.0.rc2

data/lib/runfile/concerns/dsl.rb

@@ -0,0 +1,116 @@
+module Runfile
+  module DSL
+    # Commands
+
+    attr_reader :default_action
+
+    def action(name = nil, shortcut = nil, &block)
+      current_action.block = block
+      current_action.name = name
+      current_action.shortcut = shortcut if shortcut
+      current_action.prefix = action_prefix if action_prefix
+
+      actions[name || :default] = current_action
+      @default_action = current_action unless name
+      @current_action = nil
+    end
+
+    def env_var(name, help)
+      env_vars[name] = help
+    end
+
+    def example(text)
+      examples.push text
+    end
+
+    def help(message)
+      current_action.help = message
+    end
+
+    def import(pathspec, context = nil)
+      imports[pathspec] = context
+    end
+
+    def import_gem(pathspec, context = nil)
+      gem_name, glob = pathspec.split('/', 2)
+      glob ||= '*'
+      path = GemFinder.find gem_name, glob
+      imports[path] = context
+    end
+
+    def option(name, help)
+      options[name] = help
+    end
+
+    def param(name, help)
+      params[name] = help
+    end
+
+    def shortcut(name)
+      current_action.shortcut = name
+    end
+
+    def summary(text = nil)
+      return @summary unless text
+
+      @summary = text
+    end
+
+    def title(text = nil)
+      return @title unless text
+
+      @title = text
+    end
+
+    def usage(message)
+      message = "#{action_prefix} #{message}" if action_prefix
+      current_action.usages.push message
+    end
+
+    def version(text = nil)
+      return @version unless text
+
+      @version = text
+    end
+
+    def execute(command_line)
+      run Shellwords.split(command_line)
+    end
+
+    # Evaluation Artifacts
+
+    def action_prefix
+      nil
+    end
+
+    def actions
+      @actions ||= {}
+    end
+
+    def params
+      @params ||= {}
+    end
+
+    def env_vars
+      @env_vars ||= {}
+    end
+
+    def examples
+      @examples ||= []
+    end
+
+    def options
+      @options ||= {}
+    end
+
+    def imports
+      @imports ||= {}
+    end
+
+  private
+
+    def current_action
+      @current_action ||= Action.new
+    end
+  end
+end

data/lib/runfile/concerns/inspectable.rb

@@ -0,0 +1,13 @@
+module Runfile
+  module Inspectable
+    def inspect
+      return %[#<#{self.class}>] unless inspectable
+
+      %[#<#{self.class} #{inspectable.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')}>]
+    end
+
+    def inspectable
+      nil
+    end
+  end
+end

data/lib/runfile/concerns/renderable.rb

@@ -0,0 +1,16 @@
+module Runfile
+  module Renderable
+    include Colsole
+
+    def render(view, context: nil)
+      path = "#{base_view_path}/#{view}.gtx"
+      GTX.render_file path, context: context, filename: path
+    end
+
+  private
+
+    def base_view_path
+      @base_view_path ||= ::File.expand_path '../views', __dir__
+    end
+  end
+end

data/lib/runfile/entrypoint.rb

@@ -0,0 +1,50 @@
+module Runfile
+  # Serves as the initial entrypoint when running +run+.
+  class Entrypoint
+    include Inspectable
+    include Renderable
+    include Colsole
+
+    attr_reader :argv
+
+    def initialize(argv = ARGV)
+      @argv = argv
+    end
+
+    def inspectable
+      { argv: argv }
+    end
+
+    def run
+      meta.handler(argv).run argv
+    end
+
+    def run!
+      run
+    rescue Runfile::ExitWithUsage => e
+      say e.message
+      1
+    rescue Runfile::UserError => e
+      puts e.backtrace.reverse if ENV['DEBUG']
+      say! "mib` #{e.class} `"
+      say! e.message
+      1
+    rescue Interrupt
+      say! 'm`Goodbye`', replace: true
+      1
+    rescue => e
+      puts e.backtrace.reverse if ENV['DEBUG']
+      origin = e.backtrace_locations.first
+      location = "#{origin.path}:#{origin.lineno}"
+      say! "rib` #{e.class} ` in nu`#{location}`"
+      say! e.message
+      1
+    end
+
+  private
+
+    def meta
+      @meta ||= Meta.new
+    end
+  end
+end

data/lib/runfile/exceptions.rb

@@ -0,0 +1,13 @@
+module Runfile
+  # All exceptions are rescued in bin/run, but using different styling
+  # Note that UserError types are displayed without location and are intended
+  # to be used when location is not important.
+
+  class Error < StandardError; end
+  class UserError < Error; end
+  class ExitWithUsage < Error; end
+
+  class ActionNotFound < UserError; end
+  class GemNotFound < UserError; end
+  class SyntaxError < UserError; end
+end

data/lib/runfile/gem_finder.rb

@@ -0,0 +1,29 @@
+module Runfile
+  # Finds the path of an installed or bundled gem
+  # Adapted from Rubocop <https://github.com/rubocop/rubocop/blob/master/lib/rubocop/config_loader_resolver.rb#L268>
+  class GemFinder
+    class << self
+      def find(gem_name, file = nil)
+        gem_path = find_gem_path gem_name
+        file ? File.join(gem_path, file) : gem_path
+      rescue Gem::LoadError
+        raise GemNotFound, "Cannot import gem nub`#{gem_name}`\nTry running g`gem install #{gem_name}`"
+      end
+
+    private
+
+      def find_gem_path(gem_name)
+        if bundler?
+          gem = Bundler.load.specs[gem_name].first
+          gem_path = gem.full_gem_path if gem
+        end
+
+        gem_path || Gem::Specification.find_by_name(gem_name).gem_dir
+      end
+
+      def bundler?
+        defined? Bundler
+      end
+    end
+  end
+end

data/lib/runfile/initiator.rb

@@ -0,0 +1,87 @@
+require 'fileutils'
+
+module Runfile
+  # Creates a new runfile when running +run new+ in a directory without
+  # runfiles.
+  class Initiator
+    include Inspectable
+    include Renderable
+
+    def run(argv = ARGV)
+      Runner.run docopt, argv: argv, version: VERSION do |args|
+        execute_command args
+      end
+    end
+
+  private
+
+    def execute_command(args)
+      return create_new_file if args['new']
+
+      if args['NAME']
+        create_example args['NAME']
+      else
+        list_examples
+      end
+    end
+
+    def create_new_file
+      template = File.expand_path 'templates/runfile', __dir__
+      FileUtils.cp template, '.'
+      say 'Created g`runfile`'
+      say_tip
+    end
+
+    def list_examples
+      say "nu`Available Examples`\n"
+      examples.each { |x| puts "  #{x}" }
+      say ''
+      say <<~TIP
+        Run g`run example EXAMPLE` with any of these examples to copy the files
+        to the current directory.
+
+        If you are not sure, try g`run example naval-fate`.
+      TIP
+    end
+
+    def create_example(name)
+      dir = "#{examples_dir}/#{name}"
+      files = Dir["#{dir}/{runfile,*.runfile,*.rb}"]
+      raise UserError, "No such example: nu`#{name}`" if files.empty?
+
+      files.each { |file| safe_copy file }
+      say_tip
+    end
+
+    def say_tip
+      say ''
+      say 'Run g`run` or g`run --help` to see your runfile'
+      say 'Delete the copied files to go back to the initial state'
+    end
+
+    def safe_copy(file)
+      target = File.basename file
+      # This will never happen since if there is a runfile, the initiator will
+      # not be called. Nonetheless, keep it for safety
+      return if File.exist? target
+
+      FileUtils.cp file, '.'
+      say "Copied g`#{target}`"
+    end
+
+    def examples
+      @examples ||= Dir["#{examples_dir}/*"]
+        .select { |f| File.directory?  f }
+        .map { |f| File.basename f }
+        .sort
+    end
+
+    def examples_dir
+      @examples_dir ||= File.expand_path '../../examples', __dir__
+    end
+
+    def docopt
+      @docopt ||= render('initiator', context: self)
+    end
+  end
+end

data/lib/runfile/meta.rb

@@ -0,0 +1,65 @@
+module Runfile
+  # Holds meta information about the state of runfiles in a given directory
+  class Meta
+    include Inspectable
+
+    MASTERFILE_NAMES = %w[runfile Runfile runfile.rb]
+
+    def masterfile_path
+      @masterfile_path ||= begin
+        result = nil
+
+        MASTERFILE_NAMES.each do |name|
+          if File.exist? name
+            result = name
+            break
+          end
+        end
+
+        result
+      end
+    end
+
+    def handler(_argv = ARGV)
+      masterfile || dummy || initiator
+    end
+
+    # If there are external files and no masterfile, we will use a dummy empty
+    # runfile as a masterfile to serve as the access point to the named
+    # runfiles
+    def dummy
+      return nil unless external_files.any?
+
+      Userfile.new
+    end
+
+    def initiator
+      Initiator.new
+    end
+
+    def masterfile
+      return nil unless masterfile_path
+
+      @masterfile ||= Userfile.load_file masterfile_path
+    end
+
+    def globs
+      @globs ||= (masterfile ? ['*'] + masterfile.imports.keys : ['*'])
+    end
+
+    def external_files
+      @external_files ||= begin
+        result = []
+        globs.each do |glob|
+          Dir["#{glob}.runfile"].sort.each do |file|
+            userfile = Userfile.load_file(file)
+            userfile.context = masterfile.imports[glob] if masterfile
+            result.push userfile
+          end
+        end
+        
+        result.to_h { |file| [file.name, file] }
+      end
+    end
+  end
+end

data/lib/runfile/runner.rb

@@ -1,183 +1,20 @@
-require 'singleton'
-require 'docopt'
-
 module Runfile
-
-  # The Runner class is the main workhorse behind Runfile.
-  # It handles all the Runfile DSL commands and executes the 
-  # Runfile with the help of two more specialized classes:
-  # 1. DocoptHelper - for deeper docopt related actions
-  # 2. RunfileHelper - for Runfile creation and system wide search
+  # Executes docopt.
   class Runner
-    include Singleton
-    include SettingsMixin
-
-    attr_accessor :last_usage, :last_help, :name, :version, 
-      :summary, :namespace, :superspace, :actions, :examples, :options, 
-      :params, :env_vars
-
-    # Initialize all variables to sensible defaults.
-    def initialize
-      @superspace = nil     # used when filename != Runfile
-      @last_usage = nil     # dsl: usage
-      @last_help  = nil     # dsl: help
-      @namespace  = nil     # dsl: command
-      @actions  = {}        # dsl: action
-      @options  = {}        # dsl: option
-      @params   = {}        # dsl: param
-      @examples = []        # dsl: example
-      @env_vars = {}        # dsl: env_var
-      @name     = "Runfile" # dsl: name
-      @version  = false     # dsl: version
-      @summary  = false     # dsl: summary
-    end
-
-    # Load and execute a Runfile call.
-    def execute(argv, filename='Runfile')
-      @ignore_settings = !filename
-      argv = expand_shortcuts argv
-      filename and File.file?(filename) or handle_no_runfile argv
-
-      begin
-        load settings.helper if settings.helper
-        load filename
-      rescue => ex
-        abort "Runfile error:\n#{ex.message}\n#{ex.backtrace[0]}"
-      end
-      run(*argv)
-    end
-
-    # Add an action to the @actions array, and use the last known
-    # usage and help messages sent by the DSL.
-    def add_action(name, altname = nil, &block)
-      if @last_usage.nil?
-        @last_usage = altname ? "(#{name}|#{altname})" : name 
-      end
-      [@namespace, @superspace].each do |prefix|
-        prefix or next
-        name = "#{prefix}_#{name}"
-        @last_usage = "#{prefix} #{last_usage}" unless @last_usage == false
-      end
-      name = name.to_sym
-      @actions[name] = Action.new(block, @last_usage, @last_help)
-      @last_usage = nil
-      @last_help = nil
-      if altname 
-        @last_usage = false
-        add_action(altname, nil, &block)
-      end
-    end
-
-    # Add an option flag and its help text.
-    def add_option(flag, text, scope = nil)
-      scope ||= 'Options'
-      @options[scope] ||= {}
-      @options[scope][flag] = text
-    end
-
-    # Add a patameter and its help text.
-    def add_param(name, text, scope = nil)
-      scope ||= 'Parameters'
-      @params[scope] ||= {}
-      @params[scope][name] = text
-    end
-
-    # Add env_var command.
-    def add_env_var(name, text, scope = nil)
-      scope ||= 'Environment Variables'
-      @env_vars[scope] ||= {}
-      @env_vars[scope][name] = text
-    end
-
-    # Add example command.
-    def add_example(command)
-      @examples << (@namespace ? "#{@namespace} #{command}" : command)
-    end
-
-    # Run the command. This is a wrapper around docopt. It will 
-    # generate the docopt document on the fly, using all the 
-    # information collected so far.
-    def run(*argv)
-      begin
-        docopt_exec argv
-      rescue Docopt::Exit => ex
-        puts ex.message
-        exit 2
+    class << self
+      def run(docopt, version: nil, argv: nil)
+        args = call_docopt docopt, argv: argv, version: version
+        yield args if block_given?
+        args
       end
-    end
-
-    # Invoke action from another action. Used by the DSL's #execute 
-    # function. Expects to get a single string that looks as if
-    # it was typed in the command prompt.
-    def cross_call(command_string) 
-      argv = command_string.split(/\s(?=(?:[^"]|"[^"]*")*$)/)
-      begin
-        docopt_exec argv
-      rescue Docopt::Exit => ex
-        puts "Cross call failed: #{command_string}"
-        abort ex.message
-      end
-    end
 
     private
 
-    # Call the docopt parser and execute the action with the 
-    # parsed arguments.
-    # This should always be called in a begin...rescue block and
-    # you should handle the Docopt::Exit exception.
-    def docopt_exec(argv)
-      helper = DocoptHelper.new(self)
-      args   = helper.args argv
-      action = find_action argv
-      action or abort "Runfile error: Action not found"
-      @actions[action].execute args
-    end
-
-    # Inspect the first three arguments in the argv and look for
-    # a matching action.
-    # We will first look for a_b_c action, then for a_b and 
-    # finally for a. This is intended to allow "overloading" of 
-    # the command as an action (e.g. also allow a global action 
-    # called 'a').
-    # if no command was found, but we have a :global command, 
-    # assume this is the requested one (since we will not reach 
-    # this point unless the usage pattern matches).
-    def find_action(argv)
-      3.downto(1).each do |count|
-        next unless argv.size >= count 
-        action = argv[0..count-1].join('_').to_sym
-        return action if @actions.has_key? action
-      end
-      return :global if @actions.has_key? :global 
-      return "#{superspace}_global".to_sym if @superspace and @actions.has_key? "#{superspace}_global".to_sym
-      return false
-    end
-
-    # When `run` is called without a Runfile (or runfile not 
-    # found), hand over handling to the RunfileHelper class.
-    # If will either return false if no further handling is needed
-    # on our part, or the name of a runfile to execute.
-    def handle_no_runfile(argv)
-      maker = RunfileHelper.new
-      maker.purge_settings if @ignore_settings
-      runfile = maker.handle argv
-
-      exit 3 unless runfile
-
-      @superspace = argv[0]
-      execute argv, runfile
-      exit
-    end
-
-    def expand_shortcuts(argv)
-      possible_candidate = argv[0]
-      if settings.shortcuts and settings.shortcuts[possible_candidate]
-        shortcut_value = settings.shortcuts[argv[0]]
-        expanded = shortcut_value.split ' '
-        argv.shift
-        argv = expanded + argv
+      def call_docopt(docopt, version: nil, argv: nil)
+        Docopt.docopt docopt, argv: argv, version: version
+      rescue Docopt::Exit => e
+        raise ExitWithUsage, e.message
       end
-      argv
     end
   end
 end

data/lib/runfile/templates/runfile

@@ -0,0 +1,13 @@
+title   'Greeter'
+summary 'A sample runfile'
+
+usage  'hello [NAME --shout]'
+help   'Say hello'
+option '--shout, -s', 'Greet louder'
+action 'hello' do |args|
+  name = args['NAME'] || 'You...'
+  message = "Hello #{name}"
+  message = "#{message.upcase}!" if args['--shout']
+
+  say "gu`#{message}`"
+end

data/lib/runfile/userfile.rb

@@ -0,0 +1,103 @@
+require 'shellwords'
+
+module Runfile
+  # Represents a single runfile.
+  class Userfile
+    include Renderable
+    include Inspectable
+    include DSL
+
+    attr_reader :code, :name, :path
+    attr_writer :context
+    alias action_prefix name
+
+    class << self
+      def load_file(path)
+        if masterfile? path
+          name = nil
+        else
+          name = File.basename path, '.runfile'
+          path = "#{path}.runfile" unless path.end_with? '.runfile'
+        end
+
+        code = File.read path
+        new code, name: name, path: path
+      end
+
+      def masterfile?(path)
+        Meta::MASTERFILE_NAMES.include? path
+      end
+    end
+
+    def initialize(code = nil, name: nil, path: nil)
+      @code = code
+      @name = name
+      @path = path
+
+      return unless @code
+
+      if path
+        instance_eval @code, @path
+      else
+        instance_eval @code
+      end
+    end
+
+    def inspectable
+      { name: name, path: path, context: context }
+    end
+
+    def run(argv = [])
+      found_delegate = delegates[argv[0]]
+      if found_delegate
+        found_delegate.run argv
+      else
+        run_local argv
+      end
+    end
+
+    def context
+      @context ||= {}
+    end
+
+    def implicit_title
+      title || name
+    end
+
+    # Returns an array of actions that have help defined
+    def commands
+      actions.values.select(&:help)
+    end
+
+    def delegates
+      @delegates ||= (name ? {} : meta.external_files)
+    end
+
+  private
+
+    def find_action(args)
+      acts = actions.values
+      acts.find { |a| args[a.name] } ||
+        acts.find { |a| args[a.shortcut] } ||
+        acts.find { |a| args[a.prefix] } ||
+        actions[:default]
+    end
+
+    def run_local(argv)
+      Runner.run docopt, argv: argv, version: version do |args|
+        action = find_action(args)
+        raise ActionNotFound, 'Cannot find action. Is it properly defined?' unless action
+
+        action.run args
+      end
+    end
+
+    def meta
+      @meta ||= Meta.new
+    end
+
+    def docopt
+      @docopt ||= render 'userfile', context: self
+    end
+  end
+end