runfile 0.12.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79a1c61423d09207b687d93f98035c5ca6b5e9d36f7b4acc12d93ccaa817c873
-  data.tar.gz: 0d870a0f93a9add25113e8030a02ce99dd2ecb0ed8f42d5eddb69b520b998da0
+  metadata.gz: b399f5dddc730408a835c29507af0b23d80be1ce6452c90d0c26d0d0acc577e7
+  data.tar.gz: 27211f7110e22ca49317d893952d7af82bdd774879782335185f0421e74f864b
 SHA512:
-  metadata.gz: 387383e744bac9dbd8ab89598df2a3217a4fa58f120b60ab7c31bbbfec074ae3fee0512cdee002b740af3aa85a6cd930ddfeefbe1d14deec182ebf77d57c8ab6
-  data.tar.gz: ca1b2962b157454842a0050cd3bf70826509362e7b18b9ebd2c1cc863480b0ac7f7556ad9e4fed27bad22b9c11238cf6b063e57e8b1d0459607fdb791c4ea1ae
+  metadata.gz: eaf0546be8eed23eeb6af18789a83e4b4eaa5514b044b41efb7a7a401da8465986a05bfcc5ec0930b0292edf4ea1830d2c78d0014808b59d5cf2f7c25fd3eb6d
+  data.tar.gz: 7eb9ba751139e0a83106cf7a5c0ff933b51ebba6cdbd63ee32f7ddf34be249b9804f6fb007e303cb3e225cb3cedf04ed9418a7e6856cb94165208ee3e5e672c2

data/README.md

@@ -20,85 +20,156 @@ Rake-inspired - Docopt inside
 to [Rake](https://github.com/ruby/rake), but with the full power of 
 [Docopt](http://docopt.org/) command line options.
 
-You create a `Runfile`, and execute commands with 
+You create a `runfile`, and execute commands with 
 `run command arguments -and --flags`.
 
+Runfile is designed primarily for Ruby developers, but if you need to add a 
+command line "toolbelt" for your projects, you can use it regardless.
+
+## Pre-release Notice
+
+Note that this README describes the not yet released 1.0.0 version.  
+See https://bashly.dannyb.co/ for the stable release documentation.
+
+During the pre-release phase, the `run` executable is called `runn` instead, 
+to allow running both the stable and pre-release version side by side.
+
+## Demo
+
 ![Runfile Demo](demo.svg "Runfile Demo")
 
+## Install
+
+```shell
+$ gem install runfile --pre
+```
+
 ## Quick Start
 
 ```shell
-$ run new        # create a new Runfile
+$ run new        # create a new runfile
 $ run --help     # show the usage patterns
-$ vi Runfile     # edit the Runfile
+$ vi runfile     # edit the runfile
 ```
 
-
 ## Example
 
-The most minimal `Runfile` looks like this:
+A simple `runfile` looks like this. You can get this template by running `run
+new` ()in a directory without other runfiles).
 
 ```ruby
-usage  "greet <name>"
-action :greet do |args|
-  puts "Hello #{args['<name>']}" 
+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
 ```
 
 You can then run it by executing this command:
 
 ```shell
-$ run greet Luke
+$ run hello Luke
 Hello Luke
 ```
 
-Executing `run` without parameters, will show the usage patterns:
+It will behave in the same way you expect any standard command line interface to
+behave, 
 
 ```shell
+# Show usage summary
 $ run
 Usage:
-  run greet <name>
-  run (-h|--help|--version)
-```
+  run hello [NAME --shout]
+  run (--help | -h)
 
-Executing `run --help` will show the full help document (docopt)
-
-```shell
+# Show detailed help
 $ run --help
-Runfile 0.0.0
+Greeter
+
+  A sample runfile
 
 Usage:
-  run greet <name>
-  run (-h|--help|--version)
+  run hello [NAME --shout]
+  run (--help | -h)
+
+Commands:
+  hello
+    Say hello
 
 Options:
-  -h --help
-      Show this screen
+  --shout, -s
+    Greet louder
+
+  --help, -h
+    Show this message
+```
 
-  --version
-      Show version
+## Examples
+
+You can learn almost everything there is to know about runfile from the
+[examples](https://github.com/DannyBen/runfile/tree/master/examples#readme).
+
+You can get any of these examples directly in your terminal by running:
+
+```shell
+$ run example --help
 ```
 
 ## Documentation
 
-- [User Guide](https://runfile.dannyb.co/)
-- [Learn by Example](https://github.com/DannyBen/runfile/tree/master/examples#readme)
+For a more formal documentation, see the [User Guide](https://runfile.dannyb.co/).
 
-## Breaking changes in 0.12.0
+Note that the current user guide is for the stable version 0.12.0.
 
-Note that version 0.12.0 removes several commands from the DSL. 
-If you were using any of the Colsole commands (`say`, `resay`, etc.), or any of
-the `run`, `run_bg` commands, you will have to adjust your Runfile since they are
-no longer available.
+## Breaking Changes in 1.0.0
 
-For convenience, you can simply `require runfile/compatibility` at the top of 
-your Runfile, to still have this functionality included.
+If you are using a version earlier than 1.0, note that the upcoming release
+1.0.0 includes some breaking changes. You can read more about them in[this Pull
+Request](https://github.com/DannyBen/runfile/pull/50).
 
-More info and alternative solutions in
-[this pull request](https://github.com/DannyBen/runfile/pull/46).
+### Upgrading to 1.0.0
 
-## Contributing / Support
+### No more `.runfile.yml` config
+
+If you have used the multi-runfile config file, this no longer exists.
+Use a standard `runfile` instead, along with the `import` directive.
+
+### No more `action :global`
+
+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 need for `trap(:INT)`
 
-If you experience any issue, have a question or a suggestion, or if you wish
-to contribute, feel free to [open an issue](https://github.com/DannyBen/runfile/issues).
+If your old runfiles trap the `Interrupt` signal, there i no longer a need to
+do so, as it is trapped by default.
+
+### Colsole is included
+
+If your runfiles `required` and `include` Colsole, there is no longer a need to 
+do it. Colsole is bundled and available in actions.
+
+### Long flags before short flags
+
+This is a cosmetic change for consistency. All generated output shows long flags
+before short flags `--force, -f` instead of `-f, --force`. Update your custom
+`usage` directives accordingly.
+
+### RunfileTasks
+
+The `RunfileTasks` gem is not yet compatible. It will be later on.
+
+## Contributing / Support
 
+If you experience any issue, have a question or a suggestion, or if you wish to
+contribute, feel free to
+[open an issue](https://github.com/DannyBen/runfile/issues).

data/bin/runn

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require 'runfile'
+
+exit_code = Runfile::Entrypoint.new.run!
+exit exit_code if exit_code.is_a? Integer

data/examples/default-action/runfile

@@ -0,0 +1,9 @@
+title 'Default action'
+summary 'Defining an action without a name will execute immediately'
+
+# $ run Hello : will execute this block instead of showing usage
+# $ run       : will still show usage since MESSAGE is a required argument
+usage 'MESSAGE'
+action do |args|
+  say "Action executed with #{args['MESSAGE']}"
+end

data/examples/default-action-2/runfile

@@ -0,0 +1,11 @@
+title 'Default action and other actions'
+
+# $ run : will execute this block instead of showing usage
+action do
+  say 'Running DEFAULT action'
+end
+
+# $ run test
+action :test do
+  say 'Running TEST action'
+end

data/examples/default-action-2/server.runfile

@@ -0,0 +1,6 @@
+title 'Default action in a named file'
+
+# $ run server
+action do
+  say 'Starting server'
+end

data/examples/different-name/runfile.rb

@@ -0,0 +1,8 @@
+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/example/runfile

@@ -0,0 +1,10 @@
+title 'Example with example'
+summary 'Showing examples with --help'
+
+usage 'build [--install]'
+example 'run build'
+example 'run build --install'
+action 'build' do |args|
+  say 'Building'
+  say 'Installing' if args['--install']
+end

data/examples/example-multiline/runfile

@@ -0,0 +1,16 @@
+title 'Example with a multiline examples'
+summary 'Showing examples with --help'
+
+example <<~EXAMPLES
+  nb`Build only`
+  $ run build
+
+  nb`Build and install`
+  $ run build --install
+EXAMPLES
+
+usage 'build [--install]'
+action 'build' do |args|
+  say 'Building'
+  say 'Installing' if args['--install']
+end

data/examples/execute/runfile

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

@@ -0,0 +1,11 @@
+# $ 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/full/runfile

@@ -0,0 +1,24 @@
+title 'Complete Runfile'
+summary 'A runfile with all (most) features'
+version '0.2.0'
+
+help    'Say something'
+usage   '(say|s) MESSAGE [options]'
+option  '--color, -c CODE', 'One letter color code [default: g]'
+option  '--bold, -b', 'Show in bold'
+param   'MESSAGE', 'Message to say'
+env_var 'COLOR', 'Set color code (same as --color)'
+example 'run say hello'
+example 'run say hello -cr --bold'
+action :say, :s do |args|
+  color = args['--color']
+  color += 'b' if args['--bold']
+  say "#{color}`Hello #{args['MESSAGE']}`"
+end
+
+usage  'ping [--red]'
+help   'Respond with PONG'
+option '--red, -r', 'PONG in red'
+action :ping do |args|
+  say args['--red'] ? 'r`PONG`' : 'g`PONG`'
+end

data/examples/import/more_tasks/spec.runfile

@@ -0,0 +1,7 @@
+usage '[--continue --failed]'
+option '--continue, -c', 'Continue testing'
+option '--failed, -f', 'Retest failed specs'
+action do |args|
+  say 'spec action'
+  p args
+end

data/examples/import/runfile

@@ -0,0 +1,10 @@
+title 'Importing other funfiles'
+summary 'Reference other runfiles to blend them seamlessly as one command line interface'
+
+import 'tasks/*'
+import 'more_tasks/spec'
+
+usage 'say MESSAGE'
+action 'say' do |args|
+  say "in main runfile, with #{args['MESSAGE']}"
+end

data/examples/import/tasks/server.runfile

@@ -0,0 +1,13 @@
+summary 'Server management commands'
+
+action 'start' do |_args|
+  say 'g`Starting server`'
+end
+
+usage 'stop [--force]'
+help  'Stop the server, with optional hard quit'
+option '--force, -f', 'Force quit'
+action 'stop' do |args|
+  say 'r`Stopping server`'
+  say 'rib` FORCE QUIT `' if args['--force']
+end

data/examples/minimal/runfile

@@ -0,0 +1,4 @@
+# $ run greet : execute this block
+action :greet do
+  say 'g`Hello World`'
+end

data/examples/multiple-runfiles/runfile

@@ -0,0 +1,11 @@
+title 'Multiple runfiles'
+summary 'Named runfiles in this directory will be blended seamlessly'
+
+help   'Say something'
+usage  'say MESSAGE [options]'
+option '--color, -c CODE', 'One letter color code [default: g]'
+param  'MESSAGE', 'Message to say'
+action :say do |args|
+  color = args['--color']
+  say "#{color}`Hello #{args['MESSAGE']}`"
+end

data/examples/multiple-runfiles/server.runfile

@@ -0,0 +1,13 @@
+summary 'Server management commands'
+
+action 'start' do |_args|
+  say 'g`Starting server`'
+end
+
+usage 'stop [--force]'
+help  'Stop the server, with optional hard quit'
+option '--force, -f', 'Force quit'
+action 'stop' do |args|
+  say 'r`Stopping server`'
+  say 'rib` FORCE QUIT `' if args['--force']
+end

data/examples/named-only/deploy.runfile

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

data/examples/named-only/server.runfile

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

data/examples/naval-fate/runfile

@@ -0,0 +1,47 @@
+title 'Naval Fate'
+version '1.2.1'
+summary <<~SUMMARY
+  Command line example adapted from Docopt's Naval Fate
+  Source bu`http://docopt.org/`
+SUMMARY
+
+usage 'new SHIPS...'
+help  'Deploy one or more ships'
+param 'SHIPS', 'One ore more ship names'
+action :new do |args|
+  args['SHIPS'].each do |ship|
+    say "Deployed g`#{ship}`"
+  end
+end
+
+usage  'move SHIP X Y [--speed KN]'
+help   'Move the given ship'
+param  'SHIP', 'Ship name'
+option '--speed, -s KN', 'Speed in knots [default: 20]'
+action :move do |args|
+  ship = args['SHIP']
+  x = args['X']
+  y = args['Y']
+  speed = args['--speed']
+
+  say "Moving g`#{ship}` to b`#{x},#{y}` at m`#{speed}kn`"
+end
+
+usage  'mine (set | remove) X Y  [--moored | --drifting]'
+help   'Set or remove a mine'
+option '--moored', 'Moored (anchored) mine'
+option '--drifting', 'Drifting mine'
+action :mine do |args|
+  action = args['set'] ? 'Setting' : 'Removing'
+  x = args['X']
+  y = args['Y']
+  type = if args['--moored']
+    'moored'
+  elsif args['--drifting']
+    'drifting'
+  else
+    'bottom'
+  end
+
+  say "#{action} a #{type} mine at #{x},#{y}"
+end

data/examples/shortcut/runfile

@@ -0,0 +1,31 @@
+title 'Shortcut for an action'
+summary 'Providing an alias shortcut for actions can be done in one of two ways'
+
+# $ run greet :
+# $ run g     : will both execute this block
+shortcut :g
+action :greet do
+  say 'r`Greetings`'
+end
+
+# $ run salute
+# $ run s --red
+#
+# Notice the explicit `usage` which is required when when parameters (--red)
+# are needed. In this case, to support the shortcut you need to provide it
+# as (salute | s)
+usage '(salute | s) [--red]'
+option '--red', 'In red'
+shortcut :s
+action :salute do |args|
+  color = args['--red'] ? 'r' : 'b'
+  say "#{color}`Salutations`"
+end
+
+# $ run toast
+# $ run t
+#
+# Shortcut may also be provided as a second argument to the `action` directive
+action :toast, :t do
+  say 'Toasts'
+end

data/lib/runfile/action.rb

@@ -1,21 +1,47 @@
 module Runfile
-
-  # The Action class represents a single Runfile action.
-  # This object holds all the information needed to execute it and
-  # show its help text (excluding the options, as they are considered
-  # global throughout the application)
+  # Represents a single action inside a {Userfile} and executes its block
+  # on demand. Properties of this class are populated by the {DSL} module when
+  # running a {Userfile}.
   class Action
-    attr :usage, :help
+    include Inspectable
+
+    attr_reader :name, :shortcut
+    attr_accessor :block, :help, :prefix
+
+    def run(args = {})
+      block.call args
+    end
+
+    def inspectable
+      { name: name, prefix: prefix, shortcut: shortcut }
+    end
+
+    def name=(value)
+      @name = value&.to_s
+    end
+
+    def shortcut=(value)
+      @shortcut = value&.to_s
+    end
+
+    def full_name
+      @full_name ||= if shortcut
+        "#{prefix} (#{name} | #{shortcut})".strip
+      else
+        "#{prefix} #{name}".strip
+      end
+    end
+
+    def names
+      name ? [name, shortcut].compact : ['(default)']
+    end
 
-    def initialize(block, usage, help)
-      @usage = usage
-      @help  = help
-      @block = block
+    def implicit_usages
+      usages.empty? ? [full_name] : usages
     end
 
-    # Call the provided block
-    def execute(args)
-      @block.yield args
+    def usages
+      @usages ||= []
     end
   end
-end
+end