escort 0.1.0 → 0.2.0

data/TODO.md

@@ -1,62 +1,107 @@
 ROADMAP
 
-v0.1.0
-- some spec infrastructure                                                          DONE
-- a couple of basic specs                                                           DONE
-- some integration test infrastructure                                              DONE
-- a couple of basic integration tests                                               DONE
-- pull classes for formatting out into files                                        DONE
-- summary and description for commands                                              DONE
-- include command summary and description in help formatter                         DONE
-- rework how help is displayed for commands with summary and description            DONE
-- the sub commands for command should use summary instead of description            DONE
-- do for validation and action what I did for option within the dsl                 DONE
-- look again at conflicts support in dsl, we can probably do better naming for it   DONE
-- up the version to 0.1.0
+v0.2.0
+- up the version to 0.2.0
 - tag and release
 
-v0.9.0
-- a few more tests
-- a few more integration tests
-- refactor the formatting code some more
-- pull some formatting code into separate classes
-- test some of the utility formatting code
-- up the version to 0.9.0
+
+- test conflicts for non-exstant options (integration) DONE
+- test all the new help stuff on option, for conflicts, dependencies, validations DONE
+- fix up readme for conflicts block    DONE
+- rework validations to be part of the options block rather than in their own block  DONE
+- fix example, fix tests, fix readme DONE
+- need to rework conflicts as currently not really very good   DONE
+- add dependencies to help text  DONE
+- add conflicts to help text     DONE
+- add validation texts to help text so that people can see what kind of values are valid  DONE
+- make sure we check conflicts for non-existant options   DONE
+- refactor the formatting code some more DONE
+- pull some formatting code into separate classes DONE
+- test some of the utility formatting code DONE
+- fix up help text so that if arguments are mandatory they are shown as mandatory not optional DONE
+- basic example with validations       DONE
+- integration test for validations     DONE
+- readme for validations               DONE
+- test the shell command executor, and the terminal class for width command DONE
+- improve the readme to explain
+  - a basic app with no options                                 DONE
+  - a basic app with options                                    DONE
+    - supplying multiple of the same parameter using multi      DONE
+  - a basic app with require arguments                          DONE
+  - a basic app specifying version, description and summary     DONE
+  - test the readme for flags to make sure it works as expected DONE
+  - a basic app with dependant options (mention that a deadlock situation can occur if you're not careful)  DONE
+- example for conflicting options                            DONE
+- integration test for conflicting options                   DONE
+- readme for conflicting options                             DONE
+- for print stacktrace, change it to print in INFO mode so that stacktrace not printed by default DONE
+- BUG when a script requires arguments and user doesn't supply any escort treats this as an internal error and asks you to report it, this shouldn't be the case DONE
+- depends_on support
+  - option depends on flag                                                                      DONE
+  - flag depends on another flag                                                                DONE
+  - one option depends on another (the other must be not false not nil and not empty)           DONE
+  - one option depends on specific value of another (the other must be of a specific values)    DONE
+  - one option depends on several others (where are must be not false not nil and not empty)    DONE
+  - one option depends on several others where some must have a specific value (some options have specific value, others are not false not nil and not empty)  DONE
+  - error if option for which dependecy is being defined does not exist                         DONE
+  - error if depends on non-existant option                                                     DONE
+  - error if depends on itself                                                                  DONE
+  - error if dependency not satisfied                                                           DONE
+  - error if missing on condition when specifying dependency                                    DONE
+  - refactor the options dsl class dependency code                                              DONE
+  - refactor the option_dependency_validator class to be nicer                                          DONE
+  - integration test all the permutations of dependency specification with error and success cases etc  DONE
+  - create a shortcut for dependency specification on the opt method options hash itself                DONE
+  - fix up example for basic app with dependencies for options                                          DONE
+
+v0.4.0
+- readme a basic app with config file (don't worry about explaining all the helper stuff that gets created)
+- readme implementing and action for a basic app
+- refactor terminal formatter and test it
+- refactor borderless table and test it
+- BUG parent_options when parent of command is global context doesn't seem to work???
+- test the base command for actions well
+- fix ppjson so that dependency suport feature is actually used
+- readme a command app with options, validations, description, summary, require arguments and config file, integration tests for commands, example
+- readme a sub command app with options, validations, description, summary, require arguments and config file
+- extract all the dsl command stuff into a helper module so that global and command can be handled by the same code
+- delete the stuff from the attic once it is no longer needed
+- get rid of shell command executor new shell stuff (doesn't work in Jruby and not really needed anyway)
+- up the version to 0.4.0
 - tag and release
 
+
 v1.0.0
-- rewrite the readme to explain:
-  - a basic app with no options
-  - a basic app with options
-    - supplying multiple of the same parameter using multi
-  - a basic app with require arguments
-  - a basic app specifying version, description and summary
-  - a basic app with options and validations
-  - implementing and action for a basic app
-  - a basic app with config file (don't worry about explaining all the helper stuff that gets created)
-  - a basic app with conflicting options
-  - a basic app with dependent options
-  - a command app with options, validations, description, summary, require arguments and config file
-  - a sub command app with options, validations, description, summary, require arguments and config file
-- rework the examples again to show of some/most of the features (along the lines of the integration tests and readme)
-- extract all the dsl command stuff into a helper module so that global and command can be handled by the same code
+- perhaps rework actions with passing a class and having it being auto called
+- implement servants for dealing with clumps of functionality, and action commands have access to all servants that were executed before them
+- a few more tests (setup accessor, all the dsl classes)
+- for borderless table, should be able to create another borderless table within a cell of an existing table
+- have a think about how to make the integration tests a bit more robust, so that failures don't get swallowed (test for specific exit codes instead of non-zero exit code), fix the existing integration tests
+- in trollop when errors are raised they should be wrapped as escort errors and propagate rather than being caught by trollop itself
+- a few more integration tests (test that basic app automatically gets help and other automatic options)
 - up the version to 1.0.0
 - tag and release
 - get the blog updated with a new theme
 - put a new subscriber count widget on blog
 - blog Build Command-Line Apps Like a Pro Using Ruby and Escort
 
+- rework the examples again to show of some/most of the features (along the lines of the integration tests and readme)  DONE
+- errors coming straigh out of configuration should still be caught by error handlers to only display stack trace when needed (refactor app create method) DONE
+- readme for a basic app with conflicting options    DONE
+- readme for a basic app with dependent options      DONE
+
 v1.0.1
-- more specs (setup accessor etc)
+- more specs
 - more integration specs (more specs for the different types of options)
-- rework the integration specs and matchers so there are less moving parts (perhaps push some stuff down into a base class etc.)
 - lots more logging at different levels for debug purposes
-- add validation messages to help text
 - a way have helpers available when you don't want to have to create a command
 - the config auto option should not be included in the config file, same with other auto options
 - readme about how to actually pass the user config through to action and the fact that regardless if you have a config file or not, you can have a config var or not as part of the block variables
-- rewrite the help formatter to be a bit easier to understand (more like man output for output)
-- add depends support to dsl
+- ability to specify a different command based on options declaratively or a convention for how to do different things for the same action based on options (bunch of options that are flags, options that are a clump of values etc)
+
+- rework the integration specs and matchers so there are less moving parts (perhaps push some stuff down into a base class etc.) DONE
+- rewrite the help formatter to be a bit easier to understand (more like man output for output) DONE
+- add depends support to dsl   DONE
 
 v1.0.2
 - more specs
@@ -68,7 +113,7 @@ v1.0.3
 - an option for setup that indicates it is a project specific CLI app
 - an options for setup that indicates it is an environment aware CLI app
 - make the configuration environment aware
-- make escort environment aware
+- make escort environment aware (app.environment_aware)
 - json configuration should support defaults config
 - much better documentation and usage patterns
 - pull the terminal formatting stuff into separate gem
@@ -77,6 +122,33 @@ v1.0.3
 
 
 BUCKET
+- dependencies for command options on options from parent commands or global
+- a better way of executing action and servants for the actions
+
+  - specify the options via classes
+    #command.action StreamProvider::Commands::StopServer
+  - define servants for actions within context
+    #app.before_action :stop, :start, :restart do |action|
+      #action.servant :configatron, StreamProvider::Servants::ConfigatronServant
+    #end
+
+    #app.before_action :restart do |action|
+      #action.servant :blah, StreamProvider::Servants::BlahServant
+    #end
+  - a before action without command names in context
+    app.before :actions => :this - only action in current context
+    app.before :actions => :child - only child action in current context
+    app.before :actions => [:this, :child] - this action and child actions
+    app.before :actions => :descendant - all actions that descend from this one, but not this one
+
+- can split out the shell command executor into a tiny gem for later use
+- get the build working on ruby 1.8.7
+- formatting code should support colours and styles for output
+- formatting code should support a table with borders and stuff
+- formatting code should support a simple progress bar for showing progress
+- formatting code should be more well factored
+- highline support should be added so that values can be asked for
+- values should be asked for before validations are executed, since entered values should be validated
 - instead of before and after blocks, add before, after filters for commands, maybe
 - when no action found in the context we want to execute, it should error or at least print an error
 - can we flatten the configuration (as an option)
@@ -97,9 +169,9 @@ BUCKET
 - blog about dependencies with bundler, the spermy operator and what version will be chosen
 - blog about ppjson and how to use it
 
-- improve the terminal formatter, allowing wrapping text to anywhere, and tabular like output without an actual table, allowing configuring terminal of any size not just 80, spin it off a little separate project, with an example of how to possibly build a menu in it or something
-- BUG the help formatting is still not quite right as far as respecting the char limits and wrapping properly when doing tabular output!!!!
-- do a readme for how trollop was slightly modified to accept a formatter DONE
+- improve the terminal formatter, allowing wrapping text to anywhere, and tabular like output without an actual table, allowing configuring terminal of any size not just 80, spin it off a little separate project, with an example of how to possibly build a menu in it or something DONE
+- BUG the help formatting is still not quite right as far as respecting the char limits and wrapping properly when doing tabular output!!!! DONE
+- do a readme for how trollop was slightly modified to accept a formatter
 - gemspec summary and description should be taken from the app definition/maybe
 - perhaps add a copyright with license to readme
 - via method missing we can make the dsl classes more robust by printing errors and exting when non-dsl methods are attempted
@@ -112,6 +184,32 @@ BUCKET
 PIE IN SKY
 - choosing default output format based on where the output is going STDOUT.tty?
 - look at ruby curses support a bit more closely and maybe use that for terminal stuff instead as it would be much better at it
+- a library for specifying conditions and matching on those conditions
+- possible syntax for conditions library:
+  Conditions.new do
+   _and do
+      _= a, 1
+      _not do
+        _or do
+          _nil :b
+          _empty :b
+          _false :b
+        end
+      end
+      _present :b
+      _present [:c, :d]
+      _nil :e
+      _empty :f
+      _false :g
+      _or do
+        _= :h, 5
+        _and do
+          _= :i, 7
+          _empty :j
+        end
+      end
+    end
+  end
 
 
 
@@ -150,3 +248,18 @@ DONE
 - better support for on_error blocks with explanations and examples of usage (roll exit code support into here), default handling of errors in block N/A
 - a convention for how to actually do the code that will handle the commands etc. DONE
 - support for infinitely nesting sub commands (is this really necessary) DONE
+
+v0.1.0
+- some spec infrastructure                                                          DONE
+- a couple of basic specs                                                           DONE
+- some integration test infrastructure                                              DONE
+- a couple of basic integration tests                                               DONE
+- pull classes for formatting out into files                                        DONE
+- summary and description for commands                                              DONE
+- include command summary and description in help formatter                         DONE
+- rework how help is displayed for commands with summary and description            DONE
+- the sub commands for command should use summary instead of description            DONE
+- do for validation and action what I did for option within the dsl                 DONE
+- look again at conflicts support in dsl, we can probably do better naming for it   DONE
+- up the version to 0.1.0                                                           DONE
+- tag and release                                                                   DONE

data/escort.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency('rspec')
   gem.add_development_dependency('fakefs')
   gem.add_development_dependency('rake')
+  gem.add_development_dependency('travis-lint')
 
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }

data/examples/basic

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_conflicts

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :flag1, "Flag 1", :short => '-f', :long => '--flag1', :type => :boolean
+    opts.opt :flag2, "Flag 2", :short => :none, :long => '--flag2', :type => :boolean
+
+    opts.conflict :flag1, :flag2, :flag3
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_depends_on

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :flag1, "Flag 1", :short => '-f', :long => '--flag1', :type => :boolean
+    opts.opt :flag2, "Flag 2", :short => :none, :long => '--flag2', :type => :boolean, :default => true
+    opts.opt :option1, "Option1", :short => '-o', :long => '--option1', :type => :string
+    opts.opt :option2, "Option2", :short => :none, :long => '--option2', :type => :string, :multi => true
+    opts.opt :option3, "Option3", :short => :none, :long => '--option3', :type => :string
+    opts.opt :option4, "Option4", :short => :none, :long => '--option4', :type => :string
+
+    opts.dependency :option1, :on => :flag1
+    opts.dependency :option2, :on => [:flag1, :option1]
+    opts.dependency :option3, :on => {:option1 => 'foo'}
+    #opts.dependency :option4, :on => [{:flag1 => false}, :option1] #This will get you into big trouble as it can never be fulfilled
+    opts.dependency :option4, :on => [{:flag2 => false}, :option1]
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_flags

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :flag1, "Flag 1", :short => '-f', :long => '--flag1', :type => :boolean, :default => true
+    opts.opt :flag2, "Flag 2", :short => :none, :long => '--flag2', :type => :boolean
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_options

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :option1, "Option1", :short => '-o', :long => '--option1', :type => :string, :default => "option 1"
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_options_multi

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :option1, "Option1", :short => '-o', :long => '--option1', :type => :string, :default => "option 1"
+    opts.opt :option2, "Option2", :short => :none, :long => '--option2', :type => :string, :multi => true
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_require_arguments

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.requires_arguments
+
+  app.options do |opts|
+    opts.opt :option1, "Option1", :short => '-o', :long => '--option1', :type => :string, :default => "option 1"
+    opts.opt :option2, "Option2", :short => :none, :long => '--option2', :type => :string, :multi => true
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_texts

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.version "0.1.1"
+  app.summary "Summary 1"
+  app.description "Description 1"
+
+  app.requires_arguments
+
+  app.options do |opts|
+    opts.opt :option1, "Option1", :short => '-o', :long => '--option1', :type => :string, :default => "option 1"
+    opts.opt :option2, "Option2", :short => :none, :long => '--option2', :type => :string, :multi => true
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/basic_validations

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :option1, "Option 1", :short => '-o', :long => '--option1', :type => :string
+    opts.opt :int1, "Int 1", :short => '-i', :long => '--int1', :type => :int
+    opts.opt :option2, "Option 2", :short => :none, :long => '--option2', :type => :string
+
+    opts.validate(:option1, "must be either 'foo' or 'bar'") { |option| ["foo", "bar"].include?(option) }
+    opts.validate(:int1, "must be between 10 and 20 exclusive") { |option| option > 10 && option < 20 }
+    opts.validate(:option2, "must be two words") {|option| option =~ /\w\s\w/}
+    opts.validate(:option2, "must be at least 20 characters long") {|option| option.length >= 20}
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/command

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+require File.join(File.expand_path(__FILE__), "..", "commands", "example_command")
+
+Escort::App.create do |app|
+  app.command :command1, :aliases => [:c1, :com1]  do |command|
+    command.summary "Command summary 1"
+    command.description "Command description 1"
+
+    command.action do |options, arguments|
+      Escort::ExampleCommand.new(options, arguments).execute
+    end
+  end
+
+  app.action do |options, arguments|
+    Escort::ExampleCommand.new(options, arguments).execute
+  end
+end

data/examples/commands/example_command.rb

@@ -0,0 +1,13 @@
+module Escort
+  class ExampleCommand < ::Escort::ActionCommand::Base
+    def execute
+      Escort::Logger.output.puts "Command: #{command_name}"
+      Escort::Logger.output.puts "Options: #{options}"
+      Escort::Logger.output.puts "Command options: #{command_options}"
+      Escort::Logger.output.puts "Arguments: #{arguments}"
+      if config
+        Escort::Logger.output.puts "User config: #{config}"
+      end
+    end
+  end
+end

data/lib/escort/action_command/base.rb

@@ -28,6 +28,10 @@ module Escort
         @command_context
       end
 
+      def command_name
+        command_context.first || :global
+      end
+
       def command_options
         @command_options ||= context_hash(command_context)[:options] || {}
       end

data/lib/escort/app.rb

@@ -2,20 +2,40 @@ module Escort
   class App
     #TODO ensure that every command must have an action
     class << self
+      #def create(option_string = '', &block)
+        #cli_app_configuration = Escort::Setup::Dsl::Global.new(&block)
+        #setup = Escort::SetupAccessor.new(cli_app_configuration)
+        #app = self.new(option_string, setup)
+        #app.execute
+        #exit(0)
+      #end
+
       def create(option_string = '', &block)
-        cli_app_configuration = Escort::Setup::Dsl::Global.new(&block)
-        setup = Escort::SetupAccessor.new(cli_app_configuration)
-        app = self.new(option_string, setup)
-        app.execute
+        self.new(option_string, &block).setup_application.execute
         exit(0)
       end
     end
 
     attr_reader :setup, :option_string
 
-    def initialize(option_string, setup)
-      @setup = setup
+    def initialize(option_string, &block)
       @option_string = option_string
+      @setup = nil
+      @block = block
+    end
+
+    def setup_application
+      old_error_sev_threshold = error_logger.sev_threshold
+      begin
+        error_logger.sev_threshold = ::Logger::DEBUG
+        cli_app_configuration = Escort::Setup::Dsl::Global.new(&@block)
+        @setup = Escort::SetupAccessor.new(cli_app_configuration)
+        self
+      rescue => e
+        handle_escort_error(e)
+      ensure
+        error_logger.sev_threshold = old_error_sev_threshold
+      end
     end
 
     def execute
@@ -50,7 +70,9 @@ module Escort
 
     def execute_action(action, options, arguments, user_config)
       begin
+        #execute before servants here
         action.call(options, arguments, user_config)
+        #execute after servants here
       rescue => e
         handle_action_error(e)
       end
@@ -72,11 +94,11 @@ module Escort
 
     def handle_escort_error(e)
       if e.kind_of?(Escort::UserError)
-        print_escort_error_message(e)
+        print_stacktrace(e)
         error_logger.debug{ "Escort app failed to execute successfully, due to user error" }
         exit(Escort::USER_ERROR_EXIT_CODE)
       elsif e.kind_of?(Escort::ClientError)
-        print_escort_error_message(e)
+        print_stacktrace(e)
         error_logger.debug{ "Escort app failed to execute successfully, due to client setup error" }
         exit(Escort::CLIENT_ERROR_EXIT_CODE)
       else
@@ -99,13 +121,13 @@ module Escort
     end
 
     def print_stacktrace(e)
-      error_logger.error{ e }
+      error_logger.error{ e.message }
+      error_logger.debug{ e }
     end
 
     def print_escort_error_message(e)
       print_stacktrace(e)
-      error_logger.warn{ "\n\n" }
-      error_logger.warn{ "An internal Escort error has occurred, you should probably report it by creating an issue on github!" }
+      error_logger.warn{ "An internal Escort error has occurred, you should probably report it by creating an issue on github! To get a stacktrace, up the verbosity level to DEBUG and execute your command again. Use --help for details." }
     end
   end
 end

data/lib/escort/formatter/borderless_table.rb

@@ -1,3 +1,7 @@
+#TODO needs some serious testing stuffs
+#split out into many classes VirtuaRow, PhysicalRow, FormatterRow
+#needs method each_formatted_row
+#the printing out should only happen in the outputter class not in the table intself
 module Escort
   module Formatter
     class BorderlessTable