luban-cli 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ad584f0174c5361200ed88f252387ac294ff8768
-  data.tar.gz: 9af48be33bc18fa6d049780354d0a6dc3abb34fd
+  metadata.gz: 2cef4bc2d5883cf60fc715d577ce581b4b99a37d
+  data.tar.gz: f9621b3ad7ef039ff84595cc6dc5950059519019
 SHA512:
-  metadata.gz: 932c919d74edc1e23cc4a45fe10240913603864aa25cf71a24b76e0a542da0a54296d20348fb5f7dc5c645b1b143e3557d897a6fbaf36df2ae88b5a0ba1bd400
-  data.tar.gz: 889e415204354c2c6db2440e1297fb52a85e4f59a0d662707c3bc404066eeb835c592b156fc3594bb35562c9db64f463504b2ab3bb1ebd97934de4a0e0b465b1
+  metadata.gz: 1e7ccbaef417438934e5d2a49d587c138d7c230122d0b96241935e3cc211b38e3a755f9c7302268229ccc110ae1d9712b5d08ec7b4e271eb616947020488808a
+  data.tar.gz: cebee1212f04f353fefb7457e0fcd65abd89cf8d4c008139684e497862ba26309fdfbea473c060773ce1865451d6767b33f71c09cf083565efbe4ce0409b70d5

data/CHANGELOG.md

@@ -39,3 +39,13 @@ Bug fixes:
   * Apply the correct method creator when defining action method
   * Dispatch command under the right class context
   * Show correct command chain between program name and synopsis when composing parser banner
+
+## Version 0.3.1 (Apr 15, 2015)
+
+Minor enhancements:
+  * Simplify keyword arguments for dispatch_command and action handler
+  * Include command chain as part of action method name for commands
+  * Enrich README with more documentation
+
+Bug fixes:
+  * Handle validation for multiple values correctly

data/README.md

@@ -6,21 +6,454 @@ Luban::CLI requires Ruby 2.1 or later.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add this line to your application Gemfile:
 
-    gem 'luban-cli'
+```ruby
+gem "luban-cli"
+```
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install luban-cli
+```
+$ gem install luban-cli
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Simple Example
+
+```ruby
+require 'luban/cli'
+
+class MyApp < Luban::CLI::Application
+  configure do
+    # program "my_app"
+    version "1.0.0"
+    long_desc "Demo app for Luban::CLI" 
+    option :prefix, "Prefix to a name, e.g., Mr, Ms, etc.", short: :p
+    option :suffix, "Suffix to a name, e.g., Jr, Sr, etc.", short: :s
+    switch :verbose, "Run in verbose mode", short: :V
+    argument :name, "Name to say hi"
+    action :say_hi
+  end
+
+  def say_hi(cmd:, argv:, args:, opts:)
+    name = compose_name(opts[:prefix], opts[:suffix], args[:name])
+    if opts[:verbose]
+      say_hi_verbosely(name, opts, args)
+    else
+      say_hi_concisely(name)
+    end
+  end
+
+  protected
+
+  def say_hi_verbosely(name, opts, args)
+    puts "Options: #{opts.inspect}"
+    puts "Arguments: #{args.inspect}"
+    say_hi_concisely(name)
+  end
+
+  def say_hi_concisely(name)
+    puts "Hi, #{name}!"
+  end
+
+  def compose_name(prefix, suffix, name)
+    name = name.capitalize
+    name = "#{prefix.capitalize}. #{name}" unless prefix.nil?
+    name = "#{name} #{suffix.capitalize}." unless suffix.nil?
+    name
+  end
+end
+
+MyApp.new.run
+```
+
+```
+$ ruby my_app.rb -h
+Usage: my_app [options] NAME
+
+  Options:
+    -v, --version                    Show hi version.
+    -p, --prefix PREFIX              Prefix to a name, e.g., Mr, Ms, etc.
+    -s, --suffix SUFFIX              Suffix to a name, e.g., Jr, Sr, etc.
+    -V, --verbose                    Run in verbose mode
+    -h, --help                       Show this help message.
+
+  Arguments:
+    NAME                             Name to say hi
+
+  Description:
+    Demo app for Luban::CLI
+
+$ ruby my_app.rb -v
+my_app 1.0.0
+
+$ ruby my_app.rb john -p mr -s jr
+Hi, Mr. John Jr.!
+
+ruby examples/hi.rb john -p mr -s jr -V
+Options: {:version=>false, :prefix=>"mr", :suffix=>"jr", :verbose=>true, :help=>false}
+Arguments: {:name=>"chi"}
+Hi, Mr. John Jr.!
+```
+
+Please refer to [examples](examples) for more sample usage.
+
+## DSL
+
+The following is an overview of the Luban::CLI DSL. 
+
+### program
+
+The name of the application. Default: $0.
+
+### desc
+
+A short description of what the application does.
+
+### long_desc
+
+A long description of what the application does.
+
+### argument
+
+An arguement is a positioned parameter passed from command-line. To declare an argument:
+
+```ruby
+argument :name, 'description', **modifiers, &blk
+```
+
+The modifiers below can be used:
+
+* :default - Default value for the argument.
+* :required - Flag to indicate if the argument is mandatory or not. Default: true.
+* :multiple - Flag to indicate argument is a list of values or a single value. Default: false.
+* :type - Value type for the argument. Default: :string.
+* :match - A regex for argument value matching.
+* :within - A range or a list of values the argument value to be within.
+* :assure - A code block for argument value validation.
+
+If required argument is not provided, Luban::CLI::Base::MissingRequiredArguments will be raised.
+
+If validation failed, Luban::CLI::Argument::InvalidArgumentValue will be raised.
+
+Note: An argument with multiple values needs to be positioned at the last argument. Furthermore, you cannot specify more than one arguements with multiple values.
+
+Here is an example how to use argument:
+
+```ruby
+class MyApp < Luban::CLI::Application
+  configure do
+    argument :name, 'Name for an employee'
+    argument :gender, 'Gender for an employee',
+             type: :symbol, within: [:male, :femal]
+    argument :age, 'Age for an employee',
+              type: :integer, assure: ->(age) { age < 60 }
+    argument :level, 'Level for an employee', 
+             type: :integer, within: 1..4
+    argument :email, 'Email for an employee', 
+              match: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i,
+              multiple: true, required: false
+    action do |**params|
+      puts params.inspect
+    end
+  end
+end
+
+MyApp.new.run
+```
+
+```
+$ ruby my_app.rb
+Missing required argument(s): NAME, GENDER, LEVEL (Luban::CLI::Base::MissingRequiredArguments)
+... ...
+    
+$ ruby my_app.rb john male 90
+Invalid value of argument AGE: 90 (Luban::CLI::Argument::InvalidArgumentValue)
+... ...
+
+$ ruby my_app.rb john male 30 2
+{:cmd=>nil, :argv=>[], :args=>{:name=>"john", :gender=>:male, :age=>30, :level=>2, :email=>nil}, :opts=>{:help=>false}}
+
+$ ruby my_app.rb john male 30 2 john@company.com
+{:cmd=>nil, :argv=>[], :args=>{:name=>"john", :gender=>:male, :age=>30, :level=>2, :email=>["john@company.com"]}, :opts=>{:help=>false}}
+
+$ ruby my_app.rb john male 30 2 john@company.com john@personal.com
+{:cmd=>nil, :argv=>[], :args=>{:name=>"john", :gender=>:male, :age=>30, :level=>2, :email=>["john@company.com", "john@personal.com"]}, :opts=>{:help=>false}}
+```
+
+### option
+
+An option usually takes an argument, e.g. --require LIBRARIES. To declare an option:
+
+```ruby
+option :name, 'description', **modifiers, &blk
+```
+
+The extra modifiers below can be used along with all modifiers applicable to arguments:
+
+* :long - Long style argument name.
+* :short - Short style argument alias.
+
+Note: modifier :required is turned off by default. Therefore, all options are not mandatory unless they are declared explicitly.
+
+Here is an example how to use option:
+
+```ruby
+class MyApp < Luban::CLI::Application
+  configure do
+    option :libraries, 'Require the LIBRARIES before executing your script', 
+           long: :require, short: :r, multiple: true
+    action do |**params|
+      puts params.inspect
+    end
+  end
+end
+
+MyApp.new.run
+```
+
+```
+$ ruby my_app.rb --require bundler
+{:cmd=>nil, :argv=>[], :args=>{}, :opts=>{:libraries=>["bundler"], :help=>false}}
+
+$ ruby my_app.rb -r bundler,rails
+{:cmd=>nil, :argv=>[], :args=>{}, :opts=>{:libraries=>["bundler", "rails"], :help=>false}}
+```
+
+Occassionally an option might take an optional argument, e.g. --inplace [EXTENSION]. This kind of option is called nullable option. The nullable option is set to true if the optional argument is not provided; otherwise, the value of the option is set to the value of the argument. To declare a nullable option, you can explicitly turn off nullable modifier which is off by default.
+
+Here is an example how to use nullable option:
+
+```ruby
+class MyApp < Luban::CLI::Application
+  configure do
+    option :inplace, 'Edit in place (make backup if EXTENSION supplied)', 
+            nullable: true # Turn the option into nullable
+    action do |**params|
+      puts params.inspect
+    end
+  end
+end
+
+MyApp.new.run
+```
+
+```
+$ ruby my_app.rb
+{:cmd=>nil, :argv=>[], :args=>{}, :opts=>{:inplace=>nil, :help=>false}}
+
+$ ruby my_app.rb --inplace
+{:cmd=>nil, :argv=>[], :args=>{}, :opts=>{:inplace=>true, :help=>false}}
+
+$ ruby my_app.rb --inplace .bak 
+{:cmd=>nil, :argv=>[], :args=>{}, :opts=>{:inplace=>".bak", :help=>false}}
+```
+
+### switch
+
+A switch is a special option that doesn't take any arguments, e.g., --verbose, --help, etc. To declare a switch:
+
+```ruby
+switch :name, 'description', **modifiers, &blk
+```
+
+All modifiers applied to an option can be used for a switch except the following:
+
+* :type - Type for switch is set to :bool (true/false) and it cannot be changed.
+* :multiple - Set to false to ensure to handle a single value and it cannot be changed.
+
+Negatable switch is also supported, e.g., --local, --no-local. To declare a negatable switch, you can explicitly turn on negatable modifier which is off by default. 
+
+Here is an example how to use negatable option:
+
+```ruby
+class MyApp < Luban::CLI::Application
+  configure do
+    switch :local, 'Check repository locally', 
+           negatable: true # Turn the switch into negatable: --local or --no-local
+  action do |**params|
+    puts params.inspect
+  end
+end
+
+MyApp.new.run
+```
+
+### help
+
+Add a switch for help message display. The modifiers below can be used:
+
+* :short - Short style switch for help display. Default: :h
+* :desc - Set a switch description for help display. Default: "Show this help message."
+
+DSL alias #auto_help is provided which applies default values for the above options.
+
+The switch of help display is turned on by default unless explicitly turning off when creating an application or a command.
+
+```ruby
+class MyApp < Luban::CLI::Application
+  ... ...
+end
+
+MyApp.new(auto_help: false)
+``` 
+
+### version
+
+Specify or retrieve the version of the application. 
+
+If calling without any parameters, version previously set is returned.
+
+If calling with a version, a switch for version display is added to the application. The modifiers below can be used:
+
+* :short - Set a short style switch for version display. Default: :v
+* :desc - Set a switch description for version disiplay. Default: "Show #{program_name} version."
+
+### action
+
+Specify handler for the CLI application or command.
+
+It accepts a code block or an instance method name from the application as the action handler. If a code block is given, the code block is executed in the binding of the application. If both a code block and an instance method name are provided, the instance method name is used and the code block is ignored.
+
+The handler accepts the following keyword arguments:
+
+* :args - arguments parsed from the command-line
+* :opts - options parsed from the command-line
+
+
+### action!
+
+Same as action, but removes command-line arguments destructively. 
+
+### configure
+
+This is used to configure CLI application during definition.
+
+Here is an example for how to configure CLI application:
+
+```ruby
+
+class MyApp < Luban::CLI::Application
+  configure do
+    program "my_app"
+    version "1.0.0"
+    long_desc "Demo app for Luban::CLI" 
+    option :opt1, "Description for opt1", short: :o
+    switch :swt1, "Description for swt1", short: :s
+    argument :arg1, "Description to arg1"
+    action :do_something
+  end
+
+  def do_something(args:, opts:)
+    ... ...
+  end
+end
+
+MyApp.new.run
+
+```
+
+However, it can be overriden if a configuration block is provided during application instance creation:
+
+```ruby
+MyApp.new.run do
+    program "my_app"
+    version "1.0.0"
+    long_desc "Demo app for Luban::CLI" 
+    option :opt2, "Description for opt2", short: :p
+    switch :swt2, "Description for swt2", short: :w
+    action :do_something_else
+end
+
+```
+
+## Commands
+
+Luban::CLI supports commands/subcommands. Commands can also be nested. However, all action handlers should be defined under the the application class, otherwise NoMethodError will be raised.
+
+```ruby
+class MyApp < Luban::CLI::Application
+  configure do
+    version '1.0.0'
+    desc 'Short description for the application'
+    long_desc 'Long description for the application'
+  end
+
+  # Define a help command to list all commands or help for one command.
+  auto_help_command
+
+  command :cmd1 do
+    desc 'Description for command 1'
+
+    command :task1 do
+      desc 'Description for task 1'
+      argument :arg1, 'Description for arg1', type: :string
+      action :exec_command1_task1
+    end
+
+    command :task2 do
+      desc 'Description for task 2'
+      option :opt1, 'Description for opt1', type: :integer
+      action :exec_command1_task2
+    end
+  end
+
+  command :cmd2 do
+    desc 'Description for command 1'
+    switch :swt1, 'Description for swt1'
+    action :exec_command2
+  end
+
+  def exec_command1_task1(args:, opts:); puts 'In command 1/task 1'; end
+  def exec_command1_task2(args:, opts:); puts 'In command 1/task 2'; end
+  def exec_command2(args:, opts:); puts 'In command 2'; end
+end
+
+MyApp.new.run
+```
+
+### Command method/handler
+
+By default, a new method will be defined for each command under the application class. Usually you don't need to call this method directly. Luban::CLI dispatches the specified command to the corresponding command method/handler properly.
+
+The command method name is composed of the following, concatenating with an underscore:
+
+* prefix - Default prefix is "__command_".
+* command chain
+  * For regular command, it is the command name itself
+  * For nested commands, it is the commands from the top to the bottom one
+
+In the example above, there are following command methods defined in MyApp:
+
+* __command_cmd1_task1
+* __command_cmd1_task2
+* __command_cmd2
+
+You can also change the prefix to your preferred one by setting the modifier :prefix when defining a command:
+
+```ruby
+command :cmd1, prefix: '__my_prefix_' do
+  ... ...
+end
+```
+
+### auto_help_command / help_command
+
+DSL method #auto_help_command is used to define a command to list all commands or help for one command. Under rare circumstances that you need to customize the help command (i.e., use a different command name like :manual), you can use DSL method #help_command which accepts the same parameters that for #command. 
+
+## Applications
+
+Luban::CLI provides a base class for cli application, Luban::CLI::Application. You can define your own cli application by inheriting it as examples shown in the previous sections. 
+
+In addition to command-line argument parsing capabilities, Luban::CLI::Application also supports a rc file. For example, if an application called "my_app.rb", it looks up rc file ".my_apprc" under user home when the application starts up. The rc file uses YML format. If rc file is found, the content will be loaded into the instance variable :rc; if rc file is not found, the instance variable :rc will be initialized as an empty hash.
 
 ## Contributing
 

data/lib/luban/cli/base/argument.rb

@@ -49,7 +49,9 @@ module Luban
       end
 
       def valid?(value = @value)
-        !missing?(value) and match?(value) and within?(value) and assured?(value)
+        (multiple? ? value : [value]).all? do |v| 
+          !missing?(v) and match?(v) and within?(v) and assured?(v)
+        end
       end
 
       def missing?(value = @value)
@@ -113,7 +115,7 @@ module Luban
         unless err_msg.nil?
           raise ArgumentError, "Default value for #{kind} #{display_name} #{err_msg}"
         end
-        unless (multiple? ? default : [default]).all? { |v| valid?(v) }
+        unless valid?(default)
           raise ArgumentError, "Invalid default value for #{kind} #{display_name}: #{default.inspect}"
         end
       end

data/lib/luban/cli/base/core.rb

@@ -21,7 +21,6 @@ module Luban
 
       attr_reader :app
       attr_reader :prefix
-      attr_reader :action_method
       attr_reader :program_name
       attr_reader :options
       attr_reader :arguments
@@ -39,7 +38,6 @@ module Luban
         @app = app
         @action_name = action_name
         @prefix = prefix
-        @action_method = "#{@prefix}#{@action_name}"
         @action_defined = false
 
         @program_name = default_program_name
@@ -62,6 +60,10 @@ module Luban
 
       def default_prefix; ''; end
 
+      def action_method
+        @action_method ||= "#{@prefix}#{@action_name}"
+      end
+
       def parser
         @parser ||= create_parser
       end
@@ -90,7 +92,7 @@ module Luban
         end
       end
 
-      def dispatch_command(context, cmd:, argv:, **params)
+      def dispatch_command(context, cmd:, argv:)
         validate_command(cmd)
         context.send(commands[cmd].action_method, argv)
       end

data/lib/luban/cli/base/dsl.rb

@@ -103,8 +103,8 @@ module Luban
         _base = self
         parse_method = preserve_argv ? :parse : :parse!
         define_action_method do |argv = _base.default_argv|
-          _base.send(:process, self, parse_method, argv) do |result|
-            instance_exec(**result, &handler)
+          _base.send(:process, self, parse_method, argv) do |params|
+            instance_exec(**params, &handler)
           end
         end
         @action_defined = true
@@ -126,11 +126,11 @@ module Luban
           show_version
         else
           if has_commands?
-            dispatch_command(context, **result)
+            dispatch_command(context, cmd: result[:cmd], argv: result[:argv])
           else
             validate_required_options
             validate_required_arguments
-            yield result
+            yield args: result[:args], opts: result[:opts]
           end
         end
       rescue OptionParser::ParseError, Error => e

data/lib/luban/cli/command.rb

@@ -12,6 +12,10 @@ module Luban
 
       def default_prefix; '__command_'; end
 
+      def action_method
+        @action_method ||= "#{@prefix}#{command_chain.map(&:to_s).join('_')}"
+      end
+
       protected
 
       def compose_banner

data/lib/luban/cli/version.rb

@@ -1,5 +1,5 @@
 module Luban
   module CLI
-    VERSION = "0.3.0"
+    VERSION = "0.3.1"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: luban-cli
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Rubyist Chi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-11 00:00:00.000000000 Z
+date: 2015-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler