escort 0.0.1 → 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NWYwMTA5MzIxMTE3MjU2YzJhNmE0MTA5NzViNTQwZWMyNmU0YzM5Nw==
+  data.tar.gz: !binary |-
+    ZTgyNDA0NDU4OTllYTk2NGNkYTJmNGIzODk2NDQ4ZjVhOGVmZjllMQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ZTU3Y2FkZWE2YjVjMTVjMDE4ZDI0OTA2YTRhZmFhMzdhN2Q4YzhhNTRkNDlh
+    ZDdlODcyZjUzOTEzNzliM2QzMmEyOGE2OTEzYjJjZmViMGNjNjA0MzBjMDBh
+    ODQ0MzA0NTU2ZGViMWY2ZWNkZWIyMWZiN2U0Y2ViY2IwNjc1MDg=
+  data.tar.gz: !binary |-
+    NDIxMjk4N2M4ZTZjMzBmNjFmOWVmYzQxMzI4Zjk5OTRlNjU1NTA0OTc2MzFj
+    MjMxOWZhNTliYmJjNmMzYzI2NDQ0MDExMDc5ZDdkNDA4NGU1YmUwOWQxNzI0
+    Y2NmMGEwYmJjNjAwYmU2MDFlNmY5OTU2ZTJkYTIxZGFlMWFiYTE=

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+tags

data/.irbrc

@@ -0,0 +1 @@
+require './lib/escort'

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format doc
+--require spec_helper

data/.rvmrc

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+failed=1
+gemset=escort
+rubies="ruby-1.9.3-p362 ruby-1.9.3-p194 ruby-1.9.2-p290 "
+
+for ruby in $rubies; do
+  rvm use $ruby@$gemset --create 1>/dev/null 2>&1
+  if [ $? == 0 ]; then
+    echo
+    echo ">>" rvm is using $ruby@$gemset
+    echo
+    failed=0
+    break
+  fi
+done
+
+if [ $failed == 1 ]; then
+  echo ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+  echo cannot find a ruby runtime in the set: $rubies, please install one
+  echo ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+fi

data/README.md

@@ -1,16 +1,20 @@
 # Escort
 
-Basically we take the excellent Trollop command line options parser and dress it up a little with some DSL to make writing CLI apps a bit nicer, but still retain the full power of the awesome Trollop.
+Writing even complex command-line apps should be quick, easy and fun. Escort takes the excellent [Trollop](http://trollop.rubyforge.org/) option parser and adds a whole bunch of awesome features to produce a library you will always want to turn to when a 'quick script' is in order.
 
 ## Why Write Another CLI Tool
 
-A lot of the existing CLI making libraries delegate to OptionParser for actually parsing the option string, while OptionParser is nice it doesn't allow things like specifying the same option multiple times (e.g. like CURL -H parameter) which I like and use quite often. Trollop handles this case nicely.
+A lot of the existing CLI making libraries delegate to OptionParser for actually parsing the option string, while OptionParser is nice it doesn't allow things like specifying the same option multiple times (e.g. like CURL -H parameter) which I like and use quite often. Trollop handles this case nicely, so a Trollop-based CLI tool is slightly superior.
 
-Also a lot of the other CLI libraries in an attempt to be extra terse and DRY make their syntax a little obtuse, Trollop on the other hand, is not overly DRY, the syntax is simple and easy to understand, it just needed a little DSL to make a command line app built with it nice looking.
+Also a lot of the other CLI libraries in an attempt to be extra terse and DRY make their syntax a little obtuse. Escort tries to create a DSL that strikes a balance between being terse and being easy to understand.
 
-Also I find that I end up with a similar structure for the CLI apps that I write and I want to capture that as a bit of a convention. An app doesn't stop at the option parsing, how do you actually structure the code that executes the work.
+I find that I end up with a similar structure for the CLI apps that I write and I want to capture that as a bit of a convention. An app doesn't stop at the option parsing, how do you actually structure the code that executes the work?
 
-There is a bunch of other minor reasons, so there you have it.
+In general, some liraries give you great option parsing, but no infinitely nesting sub command, others have sub commands, but the option parsing is inferior. I want everything out of my CLI library, without having to dig through feature lists trying to figure out what will give me the biggest bang for my buck.
+
+## Features
+
+TODO
 
 ## Installation
 
@@ -28,58 +32,48 @@ Or install it yourself as:
 
 ## Usage
 
-Really easy, here is an example:
+Let's say you want to do a basic app. As long as `escort` is installed as a gem, you might do something like this:
 
 ```ruby
 #!/usr/bin/env ruby
+
 require 'escort'
 
 Escort::App.create do |app|
-  app.options do
-    banner "my script banner"
-    opt :global_option, "Global option", :short => '-g', :long => '--global', :type => :string, :default => "global"
-  end
-
-  app.command :my_command do |command|
-    command.options do
-      banner "Sub command"
-      opt :do_stuff, "Do stuff", :short => :none, :long => '--do-stuff', :type => :boolean, :default => true
-    end
+  app.version "0.2.5"
 
-    command.action do |global_options, command_options, arguments|
-      #actually do the work for this command here
-    end
+  app.options do |opts|
+    opts.opt :global_option, "Global option", :short => '-g', :long => '--global', :type => :string, :default => "global"
+    opts.opt :multi_option, "Option that can be specified multiple times alksjdfh lakjdfh adf alksdfh alkdfjh alsdfjhaskdjfh alsdkfjh alksfdjh akdfjh alkdsjf alksdjfh alksdfjh asdfjklh aslkdfhj aslkdfjh adfjkhl", :short => '-m', :long => '--multi', :type => :string, :multi => true
   end
 
-  app.before do |command_name, global_options, command_options, arguments|
-    #executes before each command
-  end
-
-  app.on_error do |error|
-    #handle all errors here
+  app.action do |options, arguments|
+    puts "Action \nglobal options: #{options} \narguments: #{arguments}"
   end
 end
 ```
 
-That's all there is to it, now if your script is named `my_script` you'll be able to do things like:
+If your file is called `app.rb` you is executable, you can then call it like this:
 
 ```
-my_script my_command
-my_script my_command foobar
-my_script my_command --no-do-stuff foobar
-my_script -g "blah" my_command --do-stuff foobar
+./app.rb
+./app.rb -h
+./app.rb -g "hello" foobar
+./app.rb -m "foo" -m "bar" --global="yadda" foobar
 ```
 
-That is all for now, just some DSL around Trollop to make your script look nice (hopefully more nice things to come).
+### Sub Commands
+
+TODO
 
 ## Alternatives
 
-* [GLI](https://github.com/davetron5000/gli)
-* [Commander](https:/github.com/visionmedia/commander)
-* [CRI](https:/github.com/ddfreyne/cri)
-* [main](https:/github.com/ahoward/main)
-* [thor](https:/github.com/wycats/thor)
-* [slop](https:/github.com/injekt/slop)
+* https://github.com/davetron5000/gli
+* https://github.com/visionmedia/commander
+* https://github.com/ddfreyne/cri
+* https://github.com/ahoward/main
+* https://github.com/wycats/thor
+* https://github.com/injekt/slop
 
 ## Contributing
 
@@ -88,22 +82,3 @@ That is all for now, just some DSL around Trollop to make your script look nice
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
-
-### TODO
-
-- should be able to support command line apps without sub commands, just a plain vanilla command line app
-- should have the ability to generate a skeleton command line app according to my conventions
-- should be more config file aware but can live without it
-- work out if it needs to be involved in better logging support
-- should have better ability to create better help text
-- should have deal better with exit codes and stuff (read the book section about it)
-- maybe add some specs for it if needed
-- maybe add some cukes for it if needed
-- blog about what makes a good command line app (this and the one below are possibly one post)
-- blog about how to use escort and why the other libraries fall short
-- blog about how escort is constructed
-- should have ability to ask for user input for some commands, using highline or something like that
-- should have a clean structure convention of where code that executes the commands should live so that command line apps are easy
-- use escort to build a command line version of my markov chains name generator from ages ago
-- blog about using escort to build my name generator
-- ability to have a default command when you didn't specify one??? (what would this mean for sub command and non sub command apps)

data/TODO.md

@@ -0,0 +1,152 @@
+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
+- 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
+- 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
+- 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
+
+v1.0.1
+- more specs (setup accessor etc)
+- 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
+
+v1.0.2
+- more specs
+- scaffold for app with no sub commands
+- scaffold for app with one level of commands
+- scaffold for app with nested sub commands
+
+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
+- json configuration should support defaults config
+- much better documentation and usage patterns
+- pull the terminal formatting stuff into separate gem
+
+
+
+
+BUCKET
+- 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)
+- can we extract the json configuration stuff into a separate gem
+- json configuration should support having environment configs in multiple files
+- blog the crap out of all aspects of how to use it, how it is constructed, some fancy things you can do with it etc.
+- ability to ask for user input for a command (e.g. for passwords, this can possibly be done via validations)
+
+- blog about what makes a good command line app (this and the one below are possibly one post)
+- blog about how to use escort and why the other libraries possibly fall short
+- blog about how escort is constructed
+- blog about using escort to build a markov chains based name generator
+- blog about creating a sub command based app using escort
+- blog about creating an app with user input using escort
+- blog about instance_eval and the fact that it doesn't do closure properly (why), and the trick from trollop for how to get it to accept arguments
+- blog about exception hierarchy for apps, what exceptions to have, when to raise exceptions, touch on throw/catch and why they are bad/good, touch on exit codes for command line apps in the context of exception throwing
+- blog about nested exceptions and how to make them nice in your app, also metion exceptional ruby book as well as nestegg gem
+- 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
+- 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
+- configuring multi of multi
+- how do we describe what the arguments should be??
+- blog about the convention for implementing the escort actions
+- ability to provide some default command line arguments via an environment variable
+
+
+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
+
+
+
+DONE
+- create a tool to pretty print json (ppjson) using escort
+- global config param if config file
+- if app has a config, then give another param to control the extras creation, which will be an 'escort' sub command to allow manually creating and updating the config file etc.
+- do all the other config file bits such as creating default, non-default and updating etc.
+- catching all exceptions and dealing with them in a better way
+- global verbose param always
+- a global logger for escort which is accessible to commands etc.
+- support an on_error block to allow user to control what happens when errors occur
+- default option values via env variables (if necessary)
+- instead of exiting and printing errors all over the place, just raise specific errors, and handle the printing and exiting in the handle block in app.rb
+- options that are added by the system and not by the user should come at the end of the options list not sprinkled everywhere in help
+- test the configuration loading and writing again
+- get the coniguration updating working (two hashes should be merged, values both in hash1 and hash2 should be left alone, values in hash1, but not in hash2 should be deleted from hash1, values in hash2 but not in hash1 should be added to hash1)
+- support for configuration files for your command line apps DONE
+- the ability to set the config file name DONE
+- ability to switch on and off default creation of config file DONE
+- the ability to by default read a config file by walking up the directory tree DONE
+- ability to configure global options and command specific options (through the file) DONE
+- ability to configure extra user data that may be needed (through the file) DONE
+- an option to read specific config file instead of the default DONE
+- a flag to create a default config in a specific directory DONE
+- config file options should be validated just like the command line options DONE
+- configuring array :multi data via the configuration file DONE
+- exception hierarchy for gem and better exit codes (better exception handling for the whole gem, UserError, LogicErrors(InternalError, ClientError), TransientError, no raise library api, tagging exceptions) DONE
+- do a readme entry on exception handling and exit codes DONE
+- provide version via configuration DONE
+- automatically include version (not just version, automatically include commands in general) DONE
+- better ways to create help text to override default trollop behaviour (use below as a default) DONE
+- add default values to help text DONE
+- refactor so that objects passed into the dsl only have dsl methods available to call DONE
+- better support for before and after blocks with explanations and examples of usage N/A
+- 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

data/escort.gemspec

@@ -8,10 +8,14 @@ Gem::Specification.new do |gem|
   gem.version       = Escort::VERSION
   gem.authors       = ["Alan Skorkin"]
   gem.email         = ["alan@skorks.com"]
-  gem.summary       = %q{An escort is still a trollop just dressed up}
-  gem.description   = %q{Basically we take the excellent Trollop command line options parser and dress it up a little with some DSL to make writing CLI apps a bit nicer, but still retain the full power of the awesome Trollop.}
+  gem.summary       = %q{A library that makes building command line apps in ruby so easy, you'll feel like an expert is guiding you through it}
+  gem.description   = %q{Writing even complex command-line apps should be quick, easy and fun. Escort takes the excellent Trollop option parser and adds a whole bunch of awesome features to produce a library you will always want to turn to when a 'quick script' is in order.}
   gem.homepage      = "https://github.com/skorks/escort"
 
+  gem.add_development_dependency('rspec')
+  gem.add_development_dependency('fakefs')
+  gem.add_development_dependency('rake')
+
   gem.files         = `git ls-files`.split($/)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})

data/examples/1_1_basic.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+
+Escort::App.create do |app|
+  app.version "0.2.5"
+
+  app.options do |opts|
+    opts.opt :global_option, "Global option", :short => '-g', :long => '--global', :type => :string, :default => "global"
+    opts.opt :multi_option, "Option that can be specified multiple times alksjdfh lakjdfh adf alksdfh alkdfjh alsdfjhaskdjfh alsdkfjh alksfdjh akdfjh alkdsjf alksdjfh alksdfjh asdfjklh aslkdfhj aslkdfjh adfjkhl", :short => '-m', :long => '--multi', :type => :string, :multi => true
+  end
+
+  app.action do |options, arguments|
+    puts "Action \nglobal options: #{options} \narguments: #{arguments}"
+  end
+end

data/examples/1_2_basic_requires_arguments.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+
+Escort::App.create do |app|
+  app.requires_arguments
+
+  app.options do |opts|
+    opts.opt :global_option, "Global option", :short => '-g', :long => '--global', :type => :string, :default => "global"
+    opts.opt :multi_option, "Option that can be specified multiple times alksjdfh lakjdfh adf alksdfh alkdfjh alsdfjhaskdjfh alsdkfjh alksfdjh akdfjh alkdsjf alksdjfh alksdfjh asdfjklh aslkdfhj aslkdfjh adfjkhl", :short => '-m', :long => '--multi', :type => :string, :multi => true
+  end
+
+  app.action do |options, arguments|
+    puts "Action \nglobal options: #{options} \narguments: #{arguments}"
+  end
+end

data/examples/2_2_command.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :global_option, "Global option", :short => '-g', :long => '--global', :type => :string, :default => "global"
+  end
+
+  app.command :my_command, :description => "KJHLKJH askj aldkjfhakldfjh akdjfh alkdfhj alkdjhf alkjsdhf alkjsdhf aklsjdhf aklsjdhf akljdhf alkdjfh" do |command|
+    command.options do |opts|
+      opts.opt :do_stuff, "Do stuff", :short => :none, :long => '--do-stuff', :type => :boolean, :default => true
+    end
+
+    command.action do |options, arguments|
+      puts "Action for my_command\noptions: #{options} \narguments: #{arguments}"
+    end
+  end
+end

data/examples/2_2_command_requires_arguments.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :global_option, "Global option", :short => '-g', :long => '--global', :type => :string, :default => "global"
+  end
+
+  app.command :my_command, :description => "KJHLKJH askj aldkjfhakldfjh akdjfh alkdfhj alkdjhf alkjsdhf alkjsdhf aklsjdhf aklsjdhf akljdhf alkdjfh" do |command|
+    command.requires_arguments
+
+    command.options do |opts|
+      opts.opt :do_stuff, "Do stuff", :short => :none, :long => '--do-stuff', :type => :boolean, :default => true
+    end
+
+    command.action do |options, arguments|
+      puts "Action for my_command\noptions: #{options} \narguments: #{arguments}"
+    end
+  end
+end

data/examples/2_3_nested_commands.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+require File.expand_path(File.join(File.expand_path(__FILE__), "..", "..", "lib", "escort"))
+
+Escort::App.create do |app|
+  app.options do |opts|
+    opts.opt :global_option, "Global option", :short => '-g', :long => '--global', :type => :string, :default => "global"
+  end
+
+  app.command :my_command, :description => "KJHLKJH askj aldkjfhakldfjh akdjfh alkdfhj alkdjhf alkjsdhf alkjsdhf aklsjdhf aklsjdhf akljdhf alkdjfh" do |command|
+    command.requires_arguments
+
+    command.options do |opts|
+      opts.opt :do_stuff, "Do stuff", :short => :none, :long => '--do-stuff', :type => :boolean, :default => true
+    end
+
+    command.action do |options, arguments|
+      puts "Action for my_command\noptions: #{options} \narguments: #{arguments}"
+    end
+
+    command.command :nested_command, :description => "A nested sub command" do |command|
+      command.action do |options, arguments|
+        puts "Action for my_command nested_command\noptions: #{options} \narguments: #{arguments}"
+      end
+    end
+  end
+end