hammer_cli 0.1.0 → 0.1.1

data/doc/installation_source.md

@@ -0,0 +1,31 @@
+### Installation from SOURCE
+
+If you can install hammer from git checkouts, you will just need `rake` installed on your system.
+
+#### Step 1: clone the sources
+Clone and install CLI core
+
+```bash
+$ git clone https://github.com/theforeman/hammer-cli.git
+$ cd hammer-cli
+$ rake install
+$ cd ..
+```
+
+clone plugin with foreman commands
+
+```bash
+$ git clone https://github.com/theforeman/hammer-cli-foreman.git
+$ cd hammer-cli-foreman
+$ rake install
+$ cd ..
+```
+
+and optionally other plugins.
+
+
+#### Step 2: enable and configure the plugins
+You'll have to copy configuration files to proper locations manually.
+Please check our [configuration instructions](installation.md#configuration)
+and see how to proceed.
+

data/doc/option_builders.md

@@ -0,0 +1,77 @@
+Option builders
+---------------
+
+Option builders offer a mechanism for dynamic option creation.
+This is useful in situations when there's a common pattern or options
+can be created automatically based on some data.
+
+The [builder's interface](https://github.com/theforeman/hammer-cli/blob/master/lib/hammer_cli/option_builder.rb)
+is very simple. It has to define the only method `build(builder_params={})` that returns
+array of `HammerCLI::Options::OptionDefinition` instances.
+
+Example of a simple option builder follows:
+```ruby
+class DimensionsOptionBuilder < AbstractOptionBuilder
+
+  def initialize(option_names)
+    @option_names = option_names
+  end
+
+  def build(builder_params={})
+    opts = []
+    @option_names.each do |name|
+      opts << option("--#{name}-height", "#{name.upcase}_HEIGHT", "Height of the #{name}")
+      opts << option("--#{name}-width", "#{name.upcase}_WIDTH", "Width of the #{name}")
+    end
+    opts
+  end
+
+end
+```
+
+Each command class has an option builder defined in method `option_builder`.
+It is executed by calling class method `build_options`.
+
+```ruby
+class HouseCommand < HammerCLI::AbstractCommand
+
+  # define your own option builder
+  def self.option_builder
+    DimensionsOptionBuilder.new(["door", "window"])
+  end
+
+  # create the options at class level
+  build_options
+end
+```
+
+```
+hammer house -h
+Usage:
+    hammer house [OPTIONS]
+
+    --door-height DOOR_HEIGHT     Height of the door
+    --door-width DOOR_WIDTH       Width of the door
+    --window-height WINDOW_HEIGHT Height of the window
+    --window-width WINDOW_WIDTH   Width of the window
+    -h, --help                    print help
+```
+
+The default option builder is `OptionBuilderContainer` that
+is useful for chaining multiple builders. Command's class
+method `custom_option_builders` is there exactly for this reason. It's output
+is passed to the container and can be used for defining custom builders.
+
+```ruby
+def self.custom_option_builders
+  [
+    DimensionsOptionBuilder.new(["door", "window"]),
+    IdentifierOptionBuilder.new,
+    SomeOtherCoolBuilder.new
+  ]
+end
+```
+
+If an option with the same `--flag` is already defined (either statically or from another builder)
+any other option with the same flag is ignored.
+

data/doc/option_normalizers.md

@@ -15,7 +15,7 @@ option "--enabled", "ENABLED", "Should the host be enabled?",
 ```
 
 #### Description of valid values
-There is method `description` that should return a help string. It's value is used in output of `-h`,
+There is a method `description` that should return a help string. It's value is used in the output of `-h`,
 which can then look for example like this:
 
 ```
@@ -23,15 +23,15 @@ which can then look for example like this:
                               One of true/false, yes/no, 1/0.
 ```
 
-Abstract normalizer returns empty string by default.
+Abstract normalizer returns an empty string by default.
 
 
 #### Check and format passed values
 
 Normalizer's method `format` is used for such checks. The method behaves as a filter taking
-string value as it's input and returning value of any type.
+a string value as it's input and returning a value of any type.
 
-If the value is not valid `ArgumentError` with an appropriate message should be risen.
+If the value is not valid, `ArgumentError` with an appropriate message should be risen.
 Implementation in `Bool` normalizer is a good example of such functionality:
 
 ```ruby
@@ -50,7 +50,7 @@ end
 
 #### Value completion
 
-Normalizers can also provide completion of option values via method `complete`. It takes one argument - current option value at the time the completion was requested. In the simplest cases the method returns array of all possible values. More complex completions can use the current value argument for building the return values.
+Normalizers can also provide completion of option values via method `complete`. It takes one argument - the current option value at the time the completion was requested. In the simplest cases the method returns array of all possible values. More complex completions can use the current value argument for building the return values.
 
 We distinguish two types of offered completion strings:
 

data/doc/writing_a_plugin.md

@@ -4,7 +4,7 @@ Writing your own Hammer plugin
 In this tutorial we will create a simple hello world plugin.
 
 Hammer plugins are nothing but gems. Details on how to build a gem can be found for example at [rubygems.org](http://guides.rubygems.org/make-your-own-gem/).
-In the first part of this tutorial we will briefly guide you through the process of creating a very simple gem. First of all you will need rubygems package installed on your system.
+In the first part of this tutorial we will briefly guide you through the process of creating a very simple gem. First of all you will need the rubygems package installed on your system.
 
 Create the basic gem structure in a project subdirectory of your choice:
 ```
@@ -44,7 +44,7 @@ end
 ```
 More details about the gemspec structure is again at [rubygems.org](http://guides.rubygems.org/specification-reference/).
 
-We'll have to specify the plugins version in `lib/hammer_cli_hello/version.rb`:
+We'll have to specify the plugin version in `lib/hammer_cli_hello/version.rb`:
 ```ruby
 module HammerCLIHello
   def self.version
@@ -59,12 +59,10 @@ $ gem build ./hammer_cli_hello.gemspec
 $ gem install hammer_cli_hello-0.0.1.gem
 ```
 
-Update the hammer config to enable your plugin.
+Place your module's config file into `~/.hammer/cli.modules.d/`.
 ```yaml
-:modules:
-  - hammer_cli_hello
-# - hammer_cli_foreman
-# - hammer_cli_katello_bridge
+:hello:
+  :enable_module: true
 ```
 
 
@@ -75,12 +73,14 @@ $ hammer -v > /dev/null
 
 You should see a message saying that your module was loaded (second line in the sample output).
 ```
-[ INFO 2013-10-16 11:19:06 Init] Configuration from the file /etc/foreman/cli_config.yml has been loaded
+[ INFO 2013-10-16 11:19:06 Init] Initialization of Hammer CLI (0.1.0) has started...
 [ INFO 2013-10-16 11:19:06 Init] Extension module hammer_cli_hello loaded
+[ INFO 2013-10-16 11:19:06 Init] Configuration from the file /root/.hammer/cli_config.yml has been loaded
+[ INFO 2013-10-16 11:19:06 Init] Configuration from the file /root/.hammer/cli.modiles.d/hello.yml has been loaded
 [ INFO 2013-10-16 11:19:06 HammerCLI::MainCommand] Called with options: {"verbose"=>true}
 ```
 
-Done. Your first hammer plugin is installed. Unfortunatelly it does not contain any commands yet. So let's start adding some to finally enjoy real results.
+Done. Your first hammer plugin is installed. Unfortunately it does not contain any commands yet. So let's start adding some to finally enjoy real results.
 
 Optionally you can add a Rakefile and build and install the gem with `rake install`
 ```ruby

data/lib/hammer_cli.rb

@@ -10,6 +10,7 @@ require 'hammer_cli/validator'
 require 'hammer_cli/output'
 require 'hammer_cli/options/normalizers'
 require 'hammer_cli/completer'
+require 'hammer_cli/option_builder'
 require 'hammer_cli/abstract'
 require 'hammer_cli/main'
 

data/lib/hammer_cli/abstract.rb

@@ -1,7 +1,7 @@
 require 'hammer_cli/exception_handler'
 require 'hammer_cli/logger_watch'
 require 'hammer_cli/options/option_definition'
-require 'clamp'
+require 'hammer_cli/clamp'
 require 'logging'
 
 module HammerCLI
@@ -134,6 +134,26 @@ module HammerCLI
       HammerCLI.interactive?
     end
 
+    def self.option_builder
+      @option_builder ||= OptionBuilderContainer.new
+      @option_builder.builders = custom_option_builders
+      @option_builder
+    end
+
+    def self.custom_option_builders
+      []
+    end
+
+    def self.build_options(builder_params={})
+      option_builder.build(builder_params).each do |option|
+        # skip switches that are already defined
+        next if option.nil? or option.switches.any? {|s| find_option(s) }
+
+        declared_options << option
+        block ||= option.default_conversion_block
+        define_accessors_for(option, &block)
+      end
+    end
 
     protected
 
@@ -207,16 +227,9 @@ module HammerCLI
     end
 
     def self.option(switches, type, description, opts = {}, &block)
-      formatter = opts.delete(:format)
-      context_target = opts.delete(:context_target)
-
       HammerCLI::Options::OptionDefinition.new(switches, type, description, opts).tap do |option|
         declared_options << option
-
-        option.value_formatter = formatter
-        option.context_target = context_target
         block ||= option.default_conversion_block
-
         define_accessors_for(option, &block)
       end
     end

data/lib/hammer_cli/apipie.rb

@@ -1,3 +1,2 @@
+require File.join(File.dirname(__FILE__), './apipie/option_builder')
 require File.join(File.dirname(__FILE__), './apipie/command')
-require File.join(File.dirname(__FILE__), './apipie/read_command')
-require File.join(File.dirname(__FILE__), './apipie/write_command')

data/lib/hammer_cli/apipie/command.rb

@@ -1,4 +1,5 @@
 require File.join(File.dirname(__FILE__), '../abstract')
+require File.join(File.dirname(__FILE__), '../messages')
 require File.join(File.dirname(__FILE__), 'options')
 require File.join(File.dirname(__FILE__), 'resource')
 
@@ -8,24 +9,7 @@ module HammerCLI::Apipie
 
     include HammerCLI::Apipie::Resource
     include HammerCLI::Apipie::Options
-
-    def self.identifiers(*keys)
-      @identifiers ||= {}
-      keys.each do |key|
-        if key.is_a? Hash
-          @identifiers.merge!(key)
-        else
-          @identifiers.update(key => HammerCLI.option_accessor_name(key))
-        end
-      end
-    end
-
-    def validate_options
-      super
-      if self.class.declared_identifiers
-        validator.any(*self.class.declared_identifiers.values).required
-      end
-    end
+    include HammerCLI::Messages
 
     def self.desc(desc=nil)
       super(desc) || resource.action(action).apidoc[:apis][0][:short_description] || " "
@@ -33,67 +17,56 @@ module HammerCLI::Apipie
       " "
     end
 
-    protected
+    def self.custom_option_builders
+      builders = super
+      builders += [
+        OptionBuilder.new(resource.action(action), :require_options => false)
+      ] if resource_defined?
+      builders
+    end
 
-    def get_identifier
-      self.class.declared_identifiers.keys.each do |identifier|
-        value = find_option("--"+identifier.to_s).of(self).read
-        return [value, identifier] if value
-      end
-      [nil, nil]
+    def self.apipie_options(*args)
+      self.build_options(*args)
     end
 
-    def self.identifier?(key)
-      if @identifiers
-        return true if @identifiers.keys.include? key
-      else
-        return true if superclass.respond_to?(:identifier?, true) and superclass.identifier?(key)
-      end
-      return false
+    def execute
+      d = send_request
+      print_data(d)
+      return HammerCLI::EX_OK
     end
 
-    def self.declared_identifiers
-      if @identifiers
-        return @identifiers
-      elsif superclass.respond_to?(:declared_identifiers, true)
-        superclass.declared_identifiers
+    protected
+
+    def send_request
+      if resource && resource.has_action?(action)
+        resource.call(action, request_params, request_headers)
       else
-        {}
+        raise HammerCLI::OperationNotSupportedError, "The server does not support such operation."
       end
     end
 
-    private
-
-    def self.setup_identifier_options
-      identifier_option(:id, _("resource id"), declared_identifiers[:id]) if identifier? :id
-      identifier_option(:name, _("resource name"), declared_identifiers[:name]) if identifier? :name
-      identifier_option(:label, _("resource label"), declared_identifiers[:label]) if identifier? :label
+    def request_headers
+      {}
     end
 
-    def self.identifier_option(name, desc, attr_name)
-      option_switch = '--'+name.to_s.gsub('_', '-')
+    def request_params
+      method_options
+    end
 
-      if name == :id
-        option option_switch, name.to_s.upcase, desc, :attribute_name => attr_name
-      else
-        option option_switch, name.to_s.upcase, desc, :attribute_name => attr_name do |value|
-          name_to_id(value, name, resource)
-        end
-      end
+    def print_data(data)
+      print_collection(output_definition, data) unless output_definition.empty?
+      print_success_message(data) unless success_message.nil?
     end
 
-    def name_to_id(name, option_name, resource)
-      results = resource.call(:index, :search => "#{option_name} = #{name}")
-      results = HammerCLIForeman.collection_to_common_format(results)
+    def success_message_params(response)
+      response
+    end
 
-      msg_opts = {
-        :resource => resource.name,
-        :option => option_name,
-        :value => name
-      }
-      raise _("%{resource} with %{option} '%{value}' not found") % msg_opts if results.empty?
-      raise _("%{resource} with %{option} '%{value}' found more than once") % msg_opts if results.count > 1
-      results[0]['id']
+    def print_success_message(response)
+      print_message(
+        success_message,
+        success_message_params(response)
+      )
     end
 
   end

data/lib/hammer_cli/apipie/option_builder.rb

@@ -0,0 +1,69 @@
+
+module HammerCLI::Apipie
+
+  class OptionBuilder
+
+    def initialize(action, options={})
+      @action = action
+      @require_options = options[:require_options].nil? ? true : options[:require_options]
+    end
+
+    def build(builder_params={})
+      filter = Array(builder_params[:without])
+
+      options_for_params(@action.params, filter)
+    end
+
+    attr_writer :require_options
+    def require_options?
+      @require_options
+    end
+
+    protected
+
+    def options_for_params(params, filter)
+      opts = []
+      params.each do |p|
+        next if filter.include?(p.name) || filter.include?(p.name.to_sym)
+        if p.expected_type == :hash
+          opts += options_for_params(p.params, filter)
+        else
+          opts << create_option(p)
+        end
+      end
+      opts
+    end
+
+    def create_option(param)
+      HammerCLI::Options::OptionDefinition.new(
+        option_switch(param),
+        option_type(param),
+        option_desc(param),
+        option_opts(param)
+      )
+    end
+
+    def option_switch(param)
+      '--' + param.name.gsub('_', '-')
+    end
+
+    def option_type(param)
+      param.name.upcase.gsub('-', '_')
+    end
+
+    def option_desc(param)
+      param.description || " "
+    end
+
+    def option_opts(param)
+      opts = {}
+      opts[:required] = true if (param.required? and require_options?)
+      # FIXME: There is a bug in apipie, it does not produce correct expected type for Arrays
+      # When it's fixed, we should test param["expected_type"] == "array"
+      opts[:format] = HammerCLI::Options::Normalizers::List.new if param.validator.include? "Array"
+      return opts
+    end
+
+
+  end
+end