runfile 1.0.0.rc2 → 1.0.0.rc3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ae2a7aefd3a25703d232d70e6857aeafe467772582a96202d371bfca748e1f7
-  data.tar.gz: 32f39514ba7ffb8318c305278f55a397d2e686c7179cec0ff5899c5e6fd62871
+  metadata.gz: 87fc70007827b06c5dc191a36501383e7cbbff057ab8b237e4fd1c6ecc1cc359
+  data.tar.gz: 63a028d2937711589b69f73003ddc367326fd0dc2d4decfad10e29e3b1d44078
 SHA512:
-  metadata.gz: 289c29cf9119ce944bc46c1c6067299454396b143721b5b5b0b6b03553bca3c805743656a13cb8f4757a77022e4294152254124d7f6dfea4803879ac4289690d
-  data.tar.gz: 61afd4733813f4f3082765eae107295af324a446da8ccc5bc70959504c81aba0a161e286fc25ff0095b2fbff0c50b3a9fb76a8a21f992c6f5c620b1abd15b111
+  metadata.gz: ebdb28b94a76ad187975256fb7e3ab9d423e3b86af833f20b52d91e74886b4b03fd2a8849bdf1f50cd97c26978742f42a3522f375bd3d6567f5bb46c675b9ac2
+  data.tar.gz: fd87911f07745dff40c82bb8c4245cf309eae294799dbee320521c7d38b50a0c9575d9ad15fde44974c18639c05c3223712cf517389c149e6a9bd97020344b02

data/README.md

@@ -138,7 +138,7 @@ Request](https://github.com/DannyBen/runfile/pull/50).
 
 ### Upgrading to 1.0.0
 
-### No more `.runfile.yml` config
+### No more `.runfile` config
 
 If you have used the multi-runfile config file, this no longer exists.
 Use a standard `runfile` instead, along with the `import` directive.
@@ -149,6 +149,13 @@ If you have used the `action :global do` notation, this is replaced with the
 simpler use `action do` instead. Also, there is no more need for
 empty `usage ''`, just delete it if you have it in your runfiles.
 
+### No more `execute` directive
+
+If you have used it to cross-call other actions, it is no longer available. As
+an alternative, you can define common code in separate classes and `require`
+them, or use the new `helpers` directive to define functions that will be
+available to all actions.
+
 ### No more need for `trap(:INT)`
 
 If your old runfiles trap the `Interrupt` signal, there i no longer a need to
@@ -167,7 +174,8 @@ before short flags `--force, -f` instead of `-f, --force`. Update your custom
 
 ### RunfileTasks
 
-The `RunfileTasks` gem is not yet compatible. It will be later on.
+The `RunfileTasks` gem is also released as a pre-release, if you are using it
+make sure to install the latest release candidate.
 
 ## Contributing / Support
 

data/examples/default-action-2/runfile

@@ -1,5 +1,7 @@
 title 'Default action and other actions'
 
+import 'server'
+
 # $ run : will execute this block instead of showing usage
 action do
   say 'Running DEFAULT action'

data/examples/helpers/runfile

@@ -0,0 +1,20 @@
+require 'json'
+
+# Define helper methods
+helpers do
+  def files
+    Dir['*'].sort
+  end
+end
+
+# $ run ls : can call helper methods
+help   'Show files'
+usage  'ls [--json]'
+option '--json, -j', 'Output in JSON format'
+action :ls do |args|
+  if args['--json']
+    puts files.to_json
+  else
+    puts files.join("\n")
+  end
+end

data/examples/multiple-runfiles/runfile

@@ -1,6 +1,8 @@
 title 'Multiple runfiles'
 summary 'Named runfiles in this directory will be blended seamlessly'
 
+import 'server'
+
 help   'Say something'
 usage  'say MESSAGE [options]'
 option '--color, -c CODE', 'One letter color code [default: g]'

data/examples/nesting/deploy/deploy.runfile

@@ -0,0 +1,4 @@
+help   'Deploy to production'
+action 'production' do
+  say 'Deploying to production'
+end

data/examples/nesting/runfile

@@ -0,0 +1,9 @@
+title 'Primary Runfile (Rootfile)'
+
+# import server.runfile
+import 'server'
+
+help   'Say hello'
+action :welcome do
+  say 'Welcome to Runfile'
+end

data/examples/nesting/server.runfile

@@ -0,0 +1,15 @@
+title 'Server commands'
+summary 'Manage all the servers'
+
+# Import all the runfiles in the deploy folder
+import 'deploy/*'
+
+help   'Build server'
+action :build do
+  say 'Building...'
+end
+
+help   'Start server'
+action :start do
+  say 'Server starting...'
+end

data/examples/require-context/runfile

@@ -0,0 +1,7 @@
+title 'DevOps Toolbox'
+
+import 'server', image: 'my-rails-app', allow_deploy: true
+
+action 'ping' do
+  say 'PONG'
+end

data/examples/require-context/server.runfile

@@ -0,0 +1,25 @@
+title   'Server commands'
+summary 'Build and manage all the servers'
+
+# Declare that we need three variables in the `import` directive
+# One mandatory (:image) and two with a default fallback values
+require_context :image
+require_context :allow_deploy, default: false
+require_context :env,          default: 'development'
+
+# $ run server : default command
+action do |args|
+  say 'g`Context`:'
+  p context
+  say 'g`Args`:'
+  p args
+end
+
+help   'Deploy to production'
+action 'deploy' do
+  if context[:allow_deploy]
+    say 'DEPLOYING'
+  else
+    say! 'r`Deployment not allowed`'
+  end
+end

data/lib/runfile/action.rb

@@ -6,42 +6,60 @@ module Runfile
     include Inspectable
 
     attr_reader :name, :shortcut
-    attr_accessor :block, :help, :prefix
+    attr_accessor :block, :help, :host
 
-    def run(args = {})
-      block.call args
+    def full_name
+      @full_name ||= if shortcut
+        "#{prefix} (#{name} | #{shortcut})".strip
+      else
+        "#{prefix} #{name}".strip
+      end
     end
 
-    def inspectable
-      { name: name, prefix: prefix, shortcut: shortcut }
+    def implicit_usages
+      usages.empty? ? [full_name] : usages
     end
 
-    def name=(value)
-      @name = value&.to_s
+    def inspectable
+      { name: name, prefix: prefix, 'host.path': host&.path }
     end
 
-    def shortcut=(value)
-      @shortcut = value&.to_s
-    end
+    def run(args = {})
+      validate_context
 
-    def full_name
-      @full_name ||= if shortcut
-        "#{prefix} (#{name} | #{shortcut})".strip
-      else
-        "#{prefix} #{name}".strip
+      instance_eval do
+        host.helpers.each { |b| b.call args }
+        block.call args
       end
     end
 
+    def name=(value)
+      @name = value&.to_s
+    end
+
     def names
       name ? [name, shortcut].compact : ['(default)']
     end
 
-    def implicit_usages
-      usages.empty? ? [full_name] : usages
+    def prefix
+      host&.full_name
+    end
+
+    def shortcut=(value)
+      @shortcut = value&.to_s
     end
 
     def usages
       @usages ||= []
     end
+
+    def validate_context
+      host.required_contexts.each do |varname, default|
+        next if host.context[varname]
+        raise UserError, "Need #{varname}" if default.nil?
+
+        host.context[varname] = default
+      end
+    end
   end
 end

data/lib/runfile/concerns/dsl.rb

@@ -6,13 +6,10 @@ module Runfile
 
     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
+      current_action.name = name.to_s
+      current_action.shortcut = shortcut.to_s if shortcut
+      current_action.host = self
+      finalize_current_action name.to_s
     end
 
     def env_var(name, help)
@@ -27,6 +24,11 @@ module Runfile
       current_action.help = message
     end
 
+    def helpers(&block)
+      helper_blocks.push block if block
+      helper_blocks
+    end
+
     def import(pathspec, context = nil)
       imports[pathspec] = context
     end
@@ -46,8 +48,16 @@ module Runfile
       params[name] = help
     end
 
+    def require_context(varname, default: nil)
+      required_contexts[varname] = default
+    end
+
+    def required_contexts
+      @required_contexts ||= {}
+    end
+
     def shortcut(name)
-      current_action.shortcut = name
+      current_action.shortcut = name.to_s
     end
 
     def summary(text = nil)
@@ -63,7 +73,7 @@ module Runfile
     end
 
     def usage(message)
-      message = "#{action_prefix} #{message}" if action_prefix
+      message = "#{name} #{message}" if name
       current_action.usages.push message
     end
 
@@ -73,16 +83,8 @@ module Runfile
       @version = text
     end
 
-    def execute(command_line)
-      run Shellwords.split(command_line)
-    end
-
     # Evaluation Artifacts
 
-    def action_prefix
-      nil
-    end
-
     def actions
       @actions ||= {}
     end
@@ -99,6 +101,10 @@ module Runfile
       @examples ||= []
     end
 
+    def helper_blocks
+      @helper_blocks ||= []
+    end
+
     def options
       @options ||= {}
     end
@@ -109,6 +115,13 @@ module Runfile
 
   private
 
+    def finalize_current_action(name)
+      key = name.empty? ? :default : name
+      actions[key] = current_action
+      @default_action = current_action unless name
+      @current_action = nil
+    end
+
     def current_action
       @current_action ||= Action.new
     end

data/lib/runfile/entrypoint.rb

@@ -11,12 +11,16 @@ module Runfile
       @argv = argv
     end
 
+    def handler
+      rootfile || Initiator.new
+    end
+
     def inspectable
       { argv: argv }
     end
 
     def run
-      meta.handler(argv).run argv
+      handler.run argv
     end
 
     def run!
@@ -25,7 +29,7 @@ module Runfile
       say e.message
       1
     rescue Runfile::UserError => e
-      puts e.backtrace.reverse if ENV['DEBUG']
+      allow_debug e
       say! "mib` #{e.class} `"
       say! e.message
       1
@@ -33,18 +37,30 @@ module Runfile
       say! 'm`Goodbye`', replace: true
       1
     rescue => e
-      puts e.backtrace.reverse if ENV['DEBUG']
+      allow_debug e
       origin = e.backtrace_locations.first
       location = "#{origin.path}:#{origin.lineno}"
       say! "rib` #{e.class} ` in nu`#{location}`"
       say! e.message
+      say! "\nPrefix with nu`DEBUG=1` for full backtrace" unless ENV['DEBUG']
       1
     end
 
   private
 
-    def meta
-      @meta ||= Meta.new
+    def allow_debug(e)
+      return unless ENV['DEBUG']
+
+      say! e.backtrace.reverse.join("\n")
+      say! '---'
+    end
+
+    def rootfile
+      if File.exist? 'runfile'
+        Userfile.new 'runfile'
+      elsif File.exist? 'Runfile'
+        Userfile.new 'Runfile'
+      end
     end
   end
 end

data/lib/runfile/initiator.rb

@@ -46,10 +46,10 @@ module Runfile
 
     def create_example(name)
       dir = "#{examples_dir}/#{name}"
-      files = Dir["#{dir}/{runfile,*.runfile,*.rb}"]
-      raise UserError, "No such example: nu`#{name}`" if files.empty?
+      raise UserError, "No such example: nu`#{name}`" unless Dir.exist? dir
 
-      files.each { |file| safe_copy file }
+      files = Dir.chdir(dir) { Dir['**/{runfile,*.runfile,*.rb}'] }.sort
+      files.each { |file| safe_copy dir, file }
       say_tip
     end
 
@@ -59,19 +59,22 @@ module 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
+    def safe_copy(source_dir, target_file)
+      source_file = "#{source_dir}/#{target_file}"
 
-      FileUtils.cp file, '.'
-      say "Copied g`#{target}`"
+      if File.exist? target_file
+        say "r`Skipped  #{target_file}` (exists)"
+        return
+      end
+
+      FileUtils.mkdir_p File.dirname(target_file)
+      FileUtils.cp source_file, target_file
+      say "Copied   g`#{target_file}`"
     end
 
     def examples
       @examples ||= Dir["#{examples_dir}/*"]
-        .select { |f| File.directory?  f }
+        .select { |f| File.directory? f }
         .map { |f| File.basename f }
         .sort
     end

data/lib/runfile/userfile.rb

@@ -7,70 +7,82 @@ module Runfile
     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
+    attr_reader :path, :host
+    attr_accessor :context
 
-        code = File.read path
-        new code, name: name, path: path
-      end
+    def initialize(path, context: nil, host: nil)
+      @path = path
+      @host = host
+      @context = context || {}
+    end
 
-      def masterfile?(path)
-        Meta::MASTERFILE_NAMES.include? path
-      end
+    def basename
+      @basename ||= File.basename(path, '.runfile')
     end
 
-    def initialize(code = nil, name: nil, path: nil)
-      @code = code
-      @name = name
-      @path = path
+    def code
+      @code ||= File.read(path)
+    end
 
-      return unless @code
+    def eval_code
+      return if evaluated?
 
-      if path
-        instance_eval @code, @path
+      @evaluated = true
+      instance_eval code, path
+    end
+
+    def evaluated?
+      @evaluated
+    end
+
+    def full_name
+      id.join ' '
+    end
+
+    def id
+      if host
+        (host.id + [name]).compact
       else
-        instance_eval @code
+        [name].compact
       end
     end
 
     def inspectable
-      { name: name, path: path, context: context }
+      { name: name, path: path }
     end
 
-    def run(argv = [])
-      found_delegate = delegates[argv[0]]
-      if found_delegate
-        found_delegate.run argv
-      else
-        run_local argv
-      end
+    def name
+      @name ||= (rootfile? ? nil : basename.downcase)
     end
 
-    def context
-      @context ||= {}
+    def rootfile?
+      basename.casecmp? 'runfile'
     end
 
-    def implicit_title
-      title || name
+    def run(argv = [])
+      eval_code
+      found_guest = find_guest argv
+      if found_guest
+        found_guest.run argv
+      else
+        run_local argv
+      end
     end
 
-    # Returns an array of actions that have help defined
     def commands
       actions.values.select(&:help)
     end
 
-    def delegates
-      @delegates ||= (name ? {} : meta.external_files)
+    def guests
+      @guests ||= begin
+        result = imports.map do |glob, context|
+          Dir.glob("#{glob}.runfile").sort.map do |guest_path|
+            Userfile.new guest_path, context: context, host: self
+          end
+        end
+
+        result.flatten
+      end
     end
 
   private
@@ -83,17 +95,30 @@ module Runfile
         actions[:default]
     end
 
+    def find_guest(argv)
+      guests.find do |guest|
+        guest_id_size = guest.id.size
+        next if guest_id_size.zero?
+
+        argv.first(guest_id_size) == guest.id
+      end
+    end
+
     def run_local(argv)
+      exit_code = nil
+      # This is here to allow guests to provide their own title/summary as
+      # the help message for the Commands block.
+      # TODO: Relatively costly. Consider alternatives.
+      guests.each(&:eval_code)
+
       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
+        exit_code = action.run args
       end
-    end
 
-    def meta
-      @meta ||= Meta.new
+      exit_code if exit_code.is_a? Integer
     end
 
     def docopt

data/lib/runfile/version.rb

@@ -1,3 +1,3 @@
 module Runfile
-  VERSION = '1.0.0.rc2'
+  VERSION = '1.0.0.rc3'
 end

data/lib/runfile/views/userfile.gtx

@@ -1,10 +1,10 @@
-if implicit_title
-  = implicit_title
+if title
+  = title
   >
 end
 
 if summary
-  = implicit_title ? word_wrap("  #{summary}") : word_wrap(summary)
+  = title ? word_wrap("  #{summary}") : word_wrap(summary)
   >
 end
 
@@ -15,16 +15,15 @@ actions.each do |name, action|
   end
 end
 
-delegates.keys.each do |name|
-  = "  run #{name}"
-end
-
-if delegates.any?
->   run [COMMAND] (--help | -h)
-elsif name
->   run {{ name }} (--help | -h)
+if guests.any?
+  guests.each do |userfile|
+    = "  run #{userfile.full_name}"
+  end
+  >   run [COMMAND] (--help | -h)
+elsif full_name && !full_name.empty?
+  >   run {{ full_name }} (--help | -h)
 else
->   run (--help | -h)
+  >   run (--help | -h)
 end
 
 if version
@@ -32,7 +31,7 @@ if version
 end
 >
 
-if commands.any? || delegates.any?
+if commands.any? || guests.any?
   > Commands:
   commands.each do |action|
     = "  nb`#{action.names.join(', ')}`"
@@ -40,11 +39,11 @@ if commands.any? || delegates.any?
     >
   end
 
-  delegates.each do |name, userfile|
+  guests.each do |userfile|
     summary = userfile.summary || userfile.title ||
-      "Run nu`run #{name} --help` for more information"
+      "Run nu`run #{userfile.full_name} --help` for more information"
 
-    = "  nb`#{name}`"
+    = "  nb`#{userfile.name}`"
     = word_wrap "    #{summary}"
     >
   end
@@ -83,7 +82,6 @@ if env_vars.any?
   >
 end
 
-
 if examples.any?
   > Examples:
   examples.each do |text|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: runfile
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc2
+  version: 1.0.0.rc3
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-26 00:00:00.000000000 Z
+date: 2023-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -90,21 +90,22 @@ files:
 - examples/default-action-2/runfile
 - examples/default-action-2/server.runfile
 - examples/default-action/runfile
-- examples/different-name/runfile.rb
 - examples/example-multiline/runfile
 - examples/example/runfile
-- examples/execute/runfile
-- examples/execute/server.runfile
 - examples/full/runfile
+- examples/helpers/runfile
 - examples/import/more_tasks/spec.runfile
 - examples/import/runfile
 - examples/import/tasks/server.runfile
 - examples/minimal/runfile
 - examples/multiple-runfiles/runfile
 - examples/multiple-runfiles/server.runfile
-- examples/named-only/deploy.runfile
-- examples/named-only/server.runfile
 - examples/naval-fate/runfile
+- examples/nesting/deploy/deploy.runfile
+- examples/nesting/runfile
+- examples/nesting/server.runfile
+- examples/require-context/runfile
+- examples/require-context/server.runfile
 - examples/shortcut/runfile
 - lib/runfile.rb
 - lib/runfile/action.rb
@@ -115,7 +116,6 @@ files:
 - lib/runfile/exceptions.rb
 - lib/runfile/gem_finder.rb
 - lib/runfile/initiator.rb
-- lib/runfile/meta.rb
 - lib/runfile/runner.rb
 - lib/runfile/templates/runfile
 - lib/runfile/userfile.rb

data/examples/different-name/runfile.rb

@@ -1,8 +0,0 @@
-title 'Other name'
-summary 'The main runfile can be named "runfile", "Runfile" or "runfile.rb"'
-
-# $ run greet
-# $ run g
-action :greet, :g do
-  say 'GREET'
-end

data/examples/execute/runfile

@@ -1,14 +0,0 @@
-title 'Execute other actions'
-summary 'Shows how to call other actions from within an action'
-
-# $ run greet
-# $ run g
-action :greet, :g do |_args|
-  say 'GREET'
-end
-
-# $ run s
-help 'Shortcut to nu`server start`'
-action :s do
-  execute 'server start'
-end

data/examples/execute/server.runfile

@@ -1,11 +0,0 @@
-# $ run server start
-# $ run server s
-action :start, :s do
-  say 'START'
-end
-
-# $ run server stop
-# $ run server st
-action :stop, :st do
-  say 'STOP'
-end

data/examples/named-only/deploy.runfile

@@ -1,7 +0,0 @@
-title 'Deployment commands'
-summary 'With a default action'
-
-# $ run deploy
-action do
-  say 'deploy command'
-end

data/examples/named-only/server.runfile

@@ -1,11 +0,0 @@
-title 'Server commands'
-
-# $ run server stop
-action :stop do
-  say 'stop server'
-end
-
-# $ run server start
-action :start do
-  say 'start server'
-end

data/lib/runfile/meta.rb

@@ -1,65 +0,0 @@
-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