hammer_cli 0.0.7 → 0.0.8

data/README.md

@@ -1,129 +1,340 @@
-Hammer - the CLI tool for Foreman
-=================================
+Hammer - the CLI tool (not only) for Foreman
+============================================
 
-Hammer is a generic [clamp-based](https://github.com/mdub/clamp) CLI framework. Hammer-cli is just a core without any commands.
 
-The core can be extended with plugins and customized according to your application setup. Any Ruby script can be easily turned into a command so possibilities are wide.
+Hammer is a generic [clamp-based](https://github.com/mdub/clamp) CLI framework. 
+Hammer-cli provides just the core functionality. The core is extensible using plugins that contain application-specific commands.
 
-Currently available plugins are:
+This architecture allows for easy customization according to your application. Nearly any Ruby script can be turned into a Hammer command, so the possibilities are endless.
+
+Available plugins are currently:
   - [hammer-cli-foreman](https://github.com/theforeman/hammer-cli-foreman)  - commands corresponding to Foreman API
   - [hammer-cli-katello-bridge](https://github.com/theforeman/hammer-cli-katello-bridge) - set of commands provided by Katello CLI
 
-You also can easily add custom commands specific for your use, such as various bulk actions or admin tasks.
-
+You also can easily add custom commands for your specific use, such as bulk actions or admin tasks.
 
 
-Installation instructions
--------------------------
+Installation
+------------
 
 Hammer CLI is packaged for the following RPM based distributions:
 
  - RHEL and derivatives, version 6
  - Fedora 18, 19
+ - Debian Wheezy, Squeezy
+ - Ubuntu Precise
+
+### Installation from RPMs
+
+#### Step 1: setup yum repositories
+
+For Foreman 1.3 stable the hammer packages are part of your installation repo and you can skip this step.
+
+You can choose from stable or nightly repo. Nightly has more recent version of hammer packages, but it was subject to less testing so there is a higher risk of issues.
+Add the Foreman yum repository to your yum repo files. For Fedora installations replace 'el6' with 'f18' or 'f19' as appropriate.
 
 
-#### Step 1: setup rpm repositories
-Add the Foreman's nightly rpm repository to your yum repo files. For Fedora installations replace 'el6' with 'f18' or 'f19' as appropriate.
+Using stable
 
 ```bash
-http://yum.theforeman.org/nightly/el6/$basearch/
+yum -y install http://yum.theforeman.org/releases/1.3/el6/x86_64/foreman-release.rpm
+```
+
+or nightly
+
+```bash
+cat > /etc/yum.repos.d/foreman.repo << EOF
+[foreman]
+name=Foreman Nightly
+baseurl=http://yum.theforeman.org/nightly/el6/x86_64
+gpgcheck=0
+enabled=1
+EOF
 ```
 
 On RHEL systems you will also have to add [EPEL repository](https://fedoraproject.org/wiki/EPEL) as it contains some of the required dependencies.
 
 
 #### Step 2: install hammer core
+
+```bash
+yum install rubygem-hammer_cli
+```
+
+#### Step 3: install plugins
+Currently, there are two plugins, both available as rpm packages.
+
+ - commands for managing foreman
+
+```bash
+yum install rubygem-hammer_cli_foreman
 ```
-$ yum install rubygem-hammer_cli
+
+ - 1:1 bridge to [katello cli](https://github.com/Katello/katello)
+
+```bash
+yum install rubygem-hammer_cli_katello_bridge
 ```
 
+To install any other hammer plugin just make sure the appropriate gem is installed and follow with the configuration.
+
+
+### Installation from DEBs
+
+#### Step 1: setup apt repositories
+
+For Foreman 1.3 stable the hammer packages are part of your installation repo and you can skip this step.
+
+You can choose from stable or nightly repo. Nightly has more recent version of hammer packages, but it was subject to less testing so there is a highr risk of issues.
+
+Choose stable (don't forget to replace "squeeze" with version name of your system)
+
+```bash
+echo "deb http://deb.theforeman.org/ squeeze stable" > /etc/apt/sources.list.d/foreman.list
+```
+
+or nightly
+
+```bash
+echo "deb http://deb.theforeman.org/ squeeze nightly" > /etc/apt/sources.list.d/foreman.list
+```
+
+and update the keys
+
+```bash
+wget -q http://deb.theforeman.org/foreman.asc -O- | apt-key add -
+```
+
+#### Step 2: install hammer core
+
+```bash
+apt-get update && apt-get install ruby-hammer-cli
+```
 
 #### Step 3: install plugins
-Currently, there are two plugins, both available as rpm packages.
+Currently, there are two plugins, both available as deb packages.
 
  - commands for managing foreman
+
+```bash
+$ apt-get install ruby-hammer-cli-foreman
 ```
-$ yum install rubygem-hammer_cli_foreman
+
+ - 1:1 bridge to [katello cli](https://github.com/Katello/katello)
+
+```bash
+$ apt-get install ruby-hammer-cli-katello-bridge
+```
+
+To install any other hammer plugin just make sure the appropriate gem is installed and follow with the configuration.
+
+
+### Installation from GEMs
+
+Make sure you have ```gem``` command installed on your system
+
+#### Step 1: install hammer core
+
+```bash
+$ gem install hammer_cli
+```
+
+#### Step 2: install plugins
+Currently, there are two plugins, both available on rubygems.org
+
+ - commands for managing foreman
+
+```bash
+$ gem install hammer_cli_foreman
 ```
 
  - 1:1 bridge to [katello cli](https://github.com/Katello/katello)
+
+```bash
+$ gem install hammer_cli_katello_bridge
 ```
-$ yum install rubygem-hammer_cli_katello_bridge
+
+To install any other hammer plugin just install the appropriate gem and follow with the configuration.
+
+
+### Installation from SOURCE
+
+If you can install hammer from git checkouts, you will just need ```rake``` installed on your system.
+Clone and install CLI core
+
+```bash
+$ git clone https://github.com/theforeman/hammer-cli.git
+$ cd hammer-cli
+$ rake install
+$ cd ..
 ```
 
-Plugins are disabled after the installation. You have to edit the config file and enable them manually.
+clone plugin with foreman commands
 
+```bash
+$ git clone https://github.com/theforeman/hammer-cli-foreman.git
+$ cd hammer-cli-foreman
+$ rake install
+$ cd ..
+```
 
-#### Step 4: configuration
+and optionally other plugins via any of the methods mentioned above.
 
-Edit ```/etc/foreman/cli_config.yml``` or ```~/.foreman/cli_config.yml``` and uncomment lines with names of modules you've just installed to enable them:
 
-```yaml
-:modules:
-# - hammer_cli_foreman
-# - hammer_cli_katello_bridge
+Configuration
+-------------
+
+### Format and locations
+
+Configuration is set based on the following files, loaded in this order:
+
+ - ```/etc/foreman/cli_config.yml```.
+ - ```~/.foreman/cli_config.yml```
+ - ```./config/cli_config.yml``` (config dir in CWD)
+ - custom location specified on command line - ```-c CONF_FILE_PATH```
+
+Later files have precedence if they redefines the same option.
+
+Hammer uses yaml formatting for its configuration. The config file template is contained in the hammer_cli gem
+
+ ```bash
+gem contents hammer_cli|grep cli_config.template.yml
 ```
+and can be copied to one of the locations above and changed as needed. The packaged version of hammer copies the template to /etc for you.
+
 
-Confirm your setup by running ```$ hammer -h``` and see if the desired commands are listed.
+### Plugins
 
-You will also most likely want to change the url of the Foreman server.
+Plugins are disabled by default. You have to edit the config file and enable them manually under ```modules``` option, as can be seen in the sample config below.
+
+Plugin specific configuration should be nested under plugin's name.
+
+### Options
+
+ - ```:log_dir: <path>``` - directory where the logs are stored. The default is ```/var/log/foreman/``` and the log file is named ```hammer.log```
+ - ```:log_level: <level>``` - logging level. One of ```debug```, ```info```, ```warning```, ```error```, ```fatal```
+ - ```:log_owner: <owner>``` - logfile owner
+ - ```:log_group: <group>``` - logfile group
+ - ```:log_size: 1048576``` - size in bytes, when exceeded the log rotates. Default is 1MB
+ - ```:watch_plain: false``` - turn on/off syntax highlighting of data being logged in debug mode
+
+### Sample config
 
 ```yaml
+:modules:
+    - hammer_cli_foreman
+    - hammer_cli_katello_bridge
+
 :foreman:
     :host: 'https://localhost/'
     :username: 'admin'
     :password: 'changeme'
-```
 
-Done. Your hammer client is configured and ready to use.
+:katello_bridge:
+    :cli_description: '/home/mbacovsk/work/theforeman/hammer-cli-katello-bridge/katello.json'
 
-#### Git installation
-Optionally you can install hammer from git checkouts. You will need ```rake``` and ```bundler```.
-Clone and install CLI core
-
-    $ git clone git@github.com:theforeman/hammer-cli.git
-    $ cd hammer-cli
-    $ rake install
-    $ cd ..
 
+:log_dir: '/var/log/foreman/'
+:log_level: 'debug'
+```
 
-clone plugin with foreman commands
-
-    $ git clone git@github.com:theforeman/hammer-cli-foreman.git
-    $ cd hammer-cli-foreman
-    $ rake install
-    $ cd ..
-
-and configure. Configuration is by default looked for in ```~/.foreman/``` or in ```/etc/foreman/```.
-Optionally you can put your configuration in ```./config/``` or point hammer
-to some other location using ```-c CONF_FILE``` option
+Use the hammer
+--------------
 
-You can start with config file template we created for you and update it to suit your needs. E.g.:
+Confirm your setup by running ```$ hammer -h``` and check that the desired commands are listed.
 
-    $ cp hammer-cli/config/cli_config.template.yaml ~/.foreman/cli_config.yml
+```
+$ hammer -h 
+Usage:
+    hammer [OPTIONS] SUBCOMMAND [ARG] ...
+
+Parameters:
+    SUBCOMMAND                    subcommand
+    [ARG] ...                     subcommand arguments
+
+Subcommands:
+    architecture                  Manipulate Foreman's architectures.
+    global_parameter              Manipulate Foreman's global parameters.
+    compute_resource              Manipulate Foreman's compute resources.
+    domain                        Manipulate Foreman's domains.
+    fact                          Search Foreman's facts.
+    report                        Browse and read reports.
+    puppet_class                  Browse and read reports.
+    host                          Manipulate Foreman's hosts.
+    hostgroup                     Manipulate Foreman's hostgroups.
+    location                      Manipulate Foreman's locations.
+    medium                        Manipulate Foreman's installation media.
+    model                         Manipulate Foreman's hardware models.
+    os                            Manipulate Foreman's operating system.
+    organization                  Manipulate Foreman's organizations.
+    partition_table               Manipulate Foreman's partition tables.
+    proxy                         Manipulate Foreman's smart proxies.
+    subnet                        Manipulate Foreman's subnets.
+    template                      Manipulate Foreman's config templates.
+    about                         status of the katello server and its subcomponents
+    activation_key                activation key specific actions in the katello server
+    admin                         various administrative actions
+    changeset                     changeset specific actions in the katello server
+    client                        client specific actions in the katello server
+    content                       content namespace command
+    distribution                  repo specific actions in the katello server
+    distributor                   distributor specific actions in the katello server
+    environment                   environment specific actions in the katello server
+    errata                        errata specific actions in the katello server
+    gpg_key                       GPG key specific actions in the katello server
+    node                          node specific actions in the katello server
+    org                           organization specific actions in the katello server
+    package                       package specific actions in the katello server
+    package_group                 package group specific actions in the katello server
+    permission                    permission specific actions in the katello server
+    ping                          get the status of the katello server
+    product                       product specific actions in the katello server
+    provider                      provider specific actions in the katello server
+    puppet_module                 puppet module specific actions in the katello server
+    repo                          repo specific actions in the katello server
+    shell                         run the cli as a shell
+    sync_plan                     synchronization plan specific actions in the katello server
+    system                        system specific actions in the katello server
+    system_group                  system group specific actions in the katello server
+    task                          commands for retrieving task information
+    user                          user specific actions in the katello server
+    user_role                     user role specific actions in the katello server
+    version                       get the version of the katello server
+
+Options:
+    -v, --verbose                 be verbose
+    -c, --config CFG_FILE         path to custom config file
+    -u, --username USERNAME       username to access the remote system
+    -p, --password PASSWORD       password to access the remote system
+    --version                     show version
+    --show-ids                    Show ids of associated resources
+    --csv                         Output as CSV (same as --adapter=csv)
+    --output ADAPTER              Set output format. One of [base, table, silent, csv]
+    --csv-separator SEPARATOR     Character to separate the values
+    -P, --ask-pass                Ask for password
+    --autocomplete LINE           Get list of possible endings
+    -h, --help                    print help
+```
 
 
+And you are Done. Your hammer client is configured and ready to use.
 
 
 Autocompletion
 --------------
 
-It is necessary to copy script hammer_cli_complete to the bash_completion.d directory.
+It is necessary to copy the hammer_cli_complete script to the bash_completion.d directory.
 
     $ sudo cp hammer-cli/hammer_cli_complete /etc/bash_completion.d/
 
-Then in new shell the completion should work.
-
-
-How to test
-------------
-
-Development of almost all the code was test driven.
+Then after starting a new shell the completion should work.
 
-    $ bundle install
-    $ bundle exec "rake test"
 
-should work in any of the cli related repos. Generated coverage reports are stored in ./coverage directory.
+Further reading
+---------------
+If you're interested in hammer and want to develop some plugins for Foreman 
+or use it as a base for your own cli, read 
+[the developer docs](doc/developer_docs.md#hammer-developer-docs).
 
 License
 -------

data/doc/developer_docs.md

@@ -0,0 +1,613 @@
+Hammer Developer Docs
+=====================
+
+Hammer is a generic clamp-based CLI framework. It uses existing clamp features and adds some extra utilities.
+We recommend to get familiar with the [Clamp documentation](https://github.com/mdub/clamp/#quick-start)
+before creating some hammer specific plugins.
+
+
+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.
+
+Create the basic gem structure in a project subdirectory of your choice:
+```
+$ cd ./my_first_hammer_plugin/
+$ touch Gemfile
+$ touch hammer_cli_hello.gemspec
+$ mkdir -p lib/hammer_cli_hello
+$ touch lib/hammer_cli_hello.rb
+$ touch lib/hammer_cli_hello/version.rb
+```
+
+Example `Gemfile`:
+```ruby
+source "https://rubygems.org"
+
+gemspec
+```
+
+Example `hammer_cli_hello.gemspec` file:
+```ruby
+$:.unshift File.expand_path("../lib", __FILE__)
+require "hammer_cli_hello/version"
+
+Gem::Specification.new do |s|
+
+  s.name = "hammer_cli_hello"
+  s.authors = ["Me"]
+  s.version = HammerCLIHello.version.dup
+  s.platform = Gem::Platform::RUBY
+  s.summary = %q{Hello world commands for Hammer}
+
+  s.files = Dir['lib/**/*.rb']
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'hammer_cli', '>= 0.0.6'
+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`:
+```ruby
+module HammerCLIHello
+  def self.version
+    @version ||= Gem::Version.new '0.0.1'
+  end
+end
+```
+
+This should be enough for creating a minimalist gem. Let's build and install it.
+```
+$ gem build ./hammer_cli_hello.gemspec
+$ gem install hammer_cli_hello-0.0.1.gem
+```
+
+Update the hammer config to enable your plugin.
+```yaml
+:modules:
+  - hammer_cli_hello
+# - hammer_cli_foreman
+# - hammer_cli_katello_bridge
+```
+
+
+Verify the installation by running:
+```
+$ 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] Extension module hammer_cli_hello 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.
+
+Optionally you can add a Rakefile and build and install the gem with `rake install`
+```ruby
+# ./Rakefile
+require 'bundler/gem_tasks'
+```
+
+
+Create your first command
+-------------------------
+
+We will create a simple command called `hello` that will print a sentence "Hello World!" to stdout.
+
+### Declare the command
+
+```
+touch ./lib/hammer_cli_hello/hello_world.rb
+```
+
+```ruby
+# ./lib/hammer_cli_hello/hello_world.rb
+require 'hammer_cli'
+
+# it's a good practise to nest commands into modules
+module HammerCLIHello
+
+  # hammer commands must be descendants of AbstractCommand
+  class HelloCommand < HammerCLI::AbstractCommand
+
+    # execute is the heart of the command
+    def execute
+      # we use print_message instead of simple puts
+      # the reason will be described later in the part called Output
+      print_message "Hello World!"
+    end
+  end
+
+  # now plug your command into the hammer's main command
+  HammerCLI::MainCommand.subcommand
+    'hello',                  # command's name
+    "Say Hello World!",       # description
+    HammerCLIHello::HelloCommand  # the class
+end
+```
+
+The last bit is to require the file with your command in `hammer_cli_hello.rb`.
+Hammer actually loads this file and this is how the commands from plugins get loaded
+into hammer.
+```ruby
+# ./lib/hammer_cli_hello.rb
+require 'hammer_cli_hello/hello_world'
+```
+
+Rebuild and reinstall your plugin and see the results of `hammer -h`
+```
+gem build ./hammer_cli_hello.gemspec && gem install hammer_cli_hello-0.0.1.gem
+```
+
+
+```
+$ hammer -h
+Usage:
+    hammer [OPTIONS] SUBCOMMAND [ARG] ...
+
+Parameters:
+    SUBCOMMAND                    subcommand
+    [ARG] ...                     subcommand arguments
+
+Subcommands:
+    shell                         Interactive Shell
+    hello                         Say Hello World!
+
+Options:
+    -v, --verbose                 be verbose
+    -c, --config CFG_FILE         path to custom config file
+    -u, --username USERNAME       username to access the remote system
+    -p, --password PASSWORD       password to access the remote system
+    --version                     show version
+    --show-ids                    Show ids of associated resources
+    --csv                         Output as CSV (same as --adapter=csv)
+    --output ADAPTER              Set output format. One of [csv, table, base, silent]
+    --csv-separator SEPARATOR     Character to separate the values
+    -P, --ask-pass                Ask for password
+    --autocomplete LINE           Get list of possible endings
+    -h, --help                    print help
+```
+
+Now try running the command.
+
+```
+$ hammer hello
+Hello World!
+Error: exit code must be integer
+```
+
+What's wrong here? Hammer requires integer exit codes as return values from the method `execute`.
+It's usually just `HammerCLI::EX_OK`. Add it as the very last line of `execute`, rebuild and the
+command should run fine.
+
+See [exit_codes.rb](https://github.com/theforeman/hammer-cli/blob/master/lib/hammer_cli/exit_codes.rb)
+for the full list of available exit codes.
+
+
+### Declaring options
+Our new command has only one option so far. It's `-h` which is built in for every command by default.
+Option declaration is the same as in clamp so please read it's
+[documentation](https://github.com/mdub/clamp/#declaring-options)
+on that topic.
+
+Example option usage could go like this:
+```ruby
+class HelloCommand < HammerCLI::AbstractCommand
+
+  option '--name', "NAME", "Name of the person you want to greet"
+
+  def execute
+    print_message "Hello %s!" % (name || "World")
+    HammerCLI::EX_OK
+  end
+end
+```
+
+```
+$ hammer hello -h
+Usage:
+    hammer hello [OPTIONS]
+
+Options:
+    --name NAME                   Name of the person you want to greet
+    -h, --help                    print help
+```
+
+```
+$ hammer hello --name 'Foreman'
+Hello Foreman!
+```
+
+
+### Option validation
+Hammer provides extended functionality for validating options.
+
+#### DSL
+First of all there is a dsl for validating combinations of options:
+```ruby
+validate_options do
+  all(:name, :surname).required  # requires all the options
+  option(:age).required          # requires a single option,
+                                 # equivalent of :required => true in option declaration
+  any(:email, :phone).required   # requires at least one of the options
+
+  # Tt is possible to create more complicated constructs.
+  # This example requires either the full address or nothing
+  if any(:street, :city, :zip).exist?
+    all(:street, :city, :zip).required
+  end
+
+  # Here you can reject all address related option when --no-address is passed
+  if option(:no_address).exist?
+    all(:street, :city, :zip).rejected
+  end
+end
+
+```
+
+#### Option formatters
+Another option-related feature is a set of formatters for specific option types:
+
+* _HammerCLI::OptionFormatters.list_
+
+Parses comma separated strings to a list of values.
+
+Usage:
+```ruby
+option "--users", "USER_NAMES", "List of user names", &HammerCLI::OptionFormatters.method(:list)
+```
+`--users='J.R.,Gary,Bobby'` -> `['J.R.', 'Gary', 'Bobby']`
+
+* _HammerCLI::OptionFormatters.file_
+
+Loads contents of a file and returns it as a value of the option.
+
+Usage:
+```ruby
+option "--poem", "PATH_TO_POEM", "File containing the text of your poem", &HammerCLI::OptionFormatters.method(:file)
+```
+`--poem=~/verlaine/les_poetes_maudits.txt` -> content of the file
+
+
+### Adding subcommands
+Commands in the cli can be structured into a tree of parent commands (nodes) and subcommands (leaves).
+Neither the number of subcommands nor the nesting is limited. Please note that no parent command
+can perform any action and therefore it's useless to define `execute` method for them. This limit
+comes from Clamp's implementation of the command hierarchy.
+
+We've already used command nesting for plugging the `HelloCommand` command into the main command.
+But let's create a new command `say` and show how to connect it with others to be more demonstrative.
+
+```ruby
+module HammerCLIHello
+
+  # a new parent command 'say'
+  class SayCommand < HammerCLI::AbstractCommand
+
+    # subcommand 'hello' remains the same
+    class HelloCommand < HammerCLI::AbstractCommand
+
+      option '--name', "NAME", "Name of the person you want to greet"
+
+      def execute
+        print_message "Hello %s!" % (name || "World")
+        HammerCLI::EX_OK
+      end
+    end
+
+    # plug the original command into 'say'
+    subcommand 'hello', "Say Hello World!", HammerCLIHello::SayCommand::HelloCommand
+  end
+
+  # plug the 'say' command into the main command
+  HammerCLI::MainCommand.subcommand 'say', "Say something", HammerCLIHello::SayCommand
+end
+```
+
+The result will be:
+```
+$ hammer say hello
+Hello World!
+```
+
+This is very typical usage of subcommands. When you create more of them it may feel a bit
+duplicit to always define the subcommand structure at the end of the class definition.
+Hammer provides utility methods for subcommand autoloading. This is handy especially
+when you have growing number of subcommands. See how it works in the following example:
+
+```ruby
+module HammerCLIHello
+
+  class SayCommand < HammerCLI::AbstractCommand
+
+    class HelloCommand < HammerCLI::AbstractCommand
+      command_name 'hello'      # name and description moves to the command's class
+      desc 'Say Hello World!'
+      # ...
+    end
+
+    class HiCommand < HammerCLI::AbstractCommand
+      command_name 'hi'
+      desc 'Say Hi World!'
+      # ...
+    end
+
+    class ByeCommand < HammerCLI::AbstractCommand
+      command_name 'bye'
+      desc 'Say Bye World!'
+      # ...
+    end
+
+    autoload_subcommands
+  end
+
+  HammerCLI::MainCommand.subcommand 'say', "Say something", HammerCLIHello::SayCommand
+end
+```
+
+```
+$ hammer say
+Usage:
+    hammer say [OPTIONS] SUBCOMMAND [ARG] ...
+
+Parameters:
+    SUBCOMMAND                    subcommand
+    [ARG] ...                     subcommand arguments
+
+Subcommands:
+    hi                            Say Hi World!
+    hello                         Say Hello World!
+    bye                           Say Bye World!
+
+Options:
+    -h, --help                    print help
+```
+
+
+### Conflicting subcommands
+It can happen that two different plugins define subcommands with the same name by accident.
+In such situations `subcommand` will throw an exception. If this is intentional and you
+want to redefine the existing command, use `subcommand!`.
+This method does not throw exceptions, replaces the original subcommand, and leaves
+a message in a log for debugging purposes.
+
+
+### Printing some output
+We've mentioned above that it's not recommended practice to print output
+directly with `puts` in Hammer. The reason is we separate definition
+of the output from its interpretation. Hammer uses so called _output adapters_
+that can modify the output format.
+
+Hammer comes with four basic output adapters:
+  * __base__   - simple output, structured records
+  * __table__  - records printed in tables, ideal for printing lists of records
+  * __csv__    - comma separated output, ideal for scripting and grepping
+  * __silent__ - no output, used for testing
+
+The detailed documentation on creating adapters is coming soon.
+
+#### Printing messages
+Very simple, just call
+```ruby
+print_message(msg)
+```
+
+#### Printing hash records
+Typical usage of a cli is interaction with some api. In many cases it's listing
+some records returned by the api.
+
+Hammer comes with support for selecting and formatting of hash record fields.
+You first create so called _output definition_ that you apply on your data. The result
+is a collection of fields each having its type. The collection is then passed to some
+_output adapter_ which handles the actuall formatting and printing.
+
+Hammer provides a DSL for defining the output. Next rather complex example will
+explain how to use it in action.
+
+Imagine there's an API of some service that returns list of users:
+```ruby
+[{
+  :id => 1,
+  :email => 'tom@email.com',
+  :phone => '123456111',
+  :first_name => 'Tom',
+  :last_name => 'Sawyer',
+  :roles => ['Admin', 'Editor'],
+  :timestamps => {
+      :created => '2012-12-18T15:24:42Z',
+      :updated => '2012-12-18T15:24:42Z'
+  }
+},{
+  :id => 2,
+  :email => 'huckleberry@email.com',
+  :phone => '123456222',
+  :first_name => 'Huckleberry',
+  :last_name => 'Finn',
+  :roles => ['Admin'],
+  :timestamps => {
+      :created => '2012-12-18T15:25:00Z',
+      :updated => '2012-12-20T14:00:15Z'
+  }
+}]
+```
+
+We can create an output definition that selects and formats some of the fields:
+```ruby
+dsl = HammerCLI::Output::Dsl.new
+dsl.build do
+
+  # Simple field with a label. The first parameter is key in the printed hash.
+  field :id, 'ID'
+
+  # Fields can have types. The type determines how the field is printed.
+  # All available types are listed below.
+  # Here we want the roles to act as list.
+  field :roles, 'System Roles', Fields::List
+
+  # Label is used for grouping fields.
+  label 'Contacts' do
+    field :email, 'Email'
+    field :phone, 'Phone No.'
+  end
+
+  # From is used for accessing nested fields.
+  from :timestamps do
+    # See how date gets formatted in the output
+    field :created, 'Created At', Fields::Date
+  end
+end
+
+definition = HammerCLI::Output::Definition.new
+definition.append(dsl.fields)
+
+print_records(definition, data)
+
+```
+
+Using the base adapter the output will look like:
+```
+ID:            1
+System Roles:  Admin, Editor
+Name:          Tom Sawyer
+Contacts:
+  Email:       tom@email.com
+  Phone No.:   123456111
+Created At:    2012/12/18 15:24:42
+
+ID:            2
+System Roles:  Admin
+Name:          Huckleberry Finn
+Contacts:
+  Email:       huckleberry@email.com
+  Phone No.:   123456222
+Created At:    2012/12/18 15:25:00
+```
+
+All Hammer field types are:
+ * __Date__
+ * __Id__ - Used to mark ID values, current print adapters have support for turning id printing on/off.
+ See hammer's parameter `--show-ids`.
+ * __List__
+ * __KeyValue__ - Formats hashes containing `:name` and `:value`
+ * __Collection__ - Enables to render subcollections. Takes a block with another output definition.
+
+The default adapter for every command is Base adapter. It is possible to override
+the default one by redefining command's method `adapter`.
+
+```ruby
+def adapter
+  # return :base, :table, :csv or name of your own adapter here
+  :table
+end
+```
+
+
+Other useful command features
+-----------------------------
+
+#### Logging
+Hammer provides integrated [logger](https://github.com/TwP/logging)
+with broad setting options (use hammer's config file):
+
+```yaml
+:log_dir: '<path>'    # - directory where the logs are stored.
+                      #   The default is /var/log/foreman/ and the log file is named hammer.log
+:log_level: '<level>' # - logging level. One of debug, info, warning, error, fatal
+:log_owner: '<owner>' # - logfile owner
+:log_group: '<group>' # - logfile group
+:log_size: 1048576  # - size in bytes, when exceeded the log rotates. Default is 1MB
+:watch_plain: false # - turn on/off syntax highlighting of data being logged in debug mode
+```
+
+Example usage in commands:
+```ruby
+# Get a logger instance
+logger('Logger name')
+
+# It uses a command class name as the logger's name by default
+logger
+
+# Log a message at corresponding log level
+logger.debug("...")
+logger.error("...")
+logger.info("...")
+logger.fatal("...")
+logger.warn("...")
+
+# Writes an awesome print dump of a value to the log
+logger.watch('Some label', value)
+```
+
+#### Exception handling
+Exception handling in Hammer is centralized by
+[ExceptionHandler](https://github.com/theforeman/hammer-cli/blob/master/lib/hammer_cli/exception_handler.rb).
+Each plugin, module or even a command can have a separate exception handler. The exception handler class
+is looked up in the module structure from a command to the top level.
+
+Define method `self.exception_handler_class` in your plugin's module to use a custom exception handler:
+```ruby
+# ./lib/hammer_cli_hello.rb
+
+module HammerCLIHello
+
+  def self.exception_handler_class
+    HammerCLIHello::CustomExceptionHandler
+  end
+end
+
+require 'hammer_cli_hello/hello_world'
+```
+
+Centralized exception handling implies that you should raise exceptions on error states in your command
+rather than handle it and return error codes. This approach guarrantees that error messages are logged and
+printed consistently and correct exit codes are returned.
+
+
+#### Configuration
+Values form config files are accesible via class `HammerCLI::Settings`.
+It's method `get` returns either the value or nil when it's not found.
+
+Config values belonging to a specific plugin must be nested under
+the plugin's name in config files.
+
+```yaml
+#cli_config.yml
+:log_dir: /var/log/hammer/
+:hello_world:
+    :name:  John
+```
+
+```ruby
+HammerCLI::Settings.get(:log_dir)             # get a value
+HammerCLI::Settings.get(:hello_world, :name)  # get a nested value
+```
+
+There's more ways where to place your config file for hammer.
+Read more in [the settings howto](https://github.com/theforeman/hammer-cli#configuration).
+
+Creating commands for RESTful API with ApiPie
+---------------------------------------------
+Coming soon...
+
+
+<!--
+- this part is valid for foreman
+- what is apipie
+- apipie bindings
+- apipie, read and write commands
+- define ids a resources
+- apipie support, apipie_options
+-->
+
+
+
+
+

data/lib/hammer_cli/abstract.rb

@@ -32,7 +32,9 @@ module HammerCLI
     def parse(arguments)
       super
       validate_options
-      logger.info "Called with options: %s" % options.inspect
+      safe_options = options.dup
+      safe_options.keys.each { |k| safe_options[k] = '***' if k.end_with?('password') }
+      logger.info "Called with options: %s" % safe_options.inspect
     rescue HammerCLI::Validator::ValidationError => e
       signal_usage_error e.message
     end

data/lib/hammer_cli/output/fields.rb

@@ -50,7 +50,11 @@ module Fields
 
     def symbolize_hash_keys(h)
       if h.is_a? Hash
-        return h.inject({}){|result,(k,v)| result.update k.to_sym => symbolize_hash_keys(v)}
+        return h.inject({}) do |result,(k,v)|
+          # symbolizing empty string fails in ruby 1.8
+          result.update k.to_sym => symbolize_hash_keys(v) unless k.to_s.empty?
+          result
+        end
       elsif h.is_a? Array
         return h.collect{|item| symbolize_hash_keys(item)}
       else

data/lib/hammer_cli/version.rb

@@ -1,5 +1,5 @@
 module HammerCLI
   def self.version
-    @version ||= Gem::Version.new '0.0.7'
+    @version ||= Gem::Version.new '0.0.8'
   end
 end

metadata

@@ -1,7 +1,8 @@
 --- !ruby/object:Gem::Specification
 name: hammer_cli
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
+  prerelease: 
 platform: ruby
 authors:
 - Martin Bačovský
@@ -9,94 +10,107 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-09 00:00:00.000000000 Z
+date: 2013-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clamp
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: logging
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: awesome_print
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: table_print
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: highline
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: |
-  Hammer cli provides universal extendable CLI interface for ruby apps
+description: ! 'Hammer cli provides universal extendable CLI interface for ruby apps
+
+'
 email: mbacovsk@redhat.com
 executables:
 - hammer
@@ -108,39 +122,40 @@ extra_rdoc_files:
 - config/cli_config.template.yml
 - doc/design.png
 - doc/design.uml
+- doc/developer_docs.md
 files:
-- lib/hammer_cli/logger_watch.rb
-- lib/hammer_cli/apipie/write_command.rb
-- lib/hammer_cli/apipie/resource.rb
-- lib/hammer_cli/apipie/read_command.rb
-- lib/hammer_cli/apipie/options.rb
-- lib/hammer_cli/apipie/command.rb
-- lib/hammer_cli/logger.rb
+- lib/hammer_cli.rb
 - lib/hammer_cli/messages.rb
-- lib/hammer_cli/option_formatters.rb
-- lib/hammer_cli/abstract.rb
-- lib/hammer_cli/apipie.rb
-- lib/hammer_cli/version.rb
-- lib/hammer_cli/exception_handler.rb
-- lib/hammer_cli/output.rb
-- lib/hammer_cli/autocompletion.rb
-- lib/hammer_cli/shell.rb
+- lib/hammer_cli/output/fields.rb
+- lib/hammer_cli/output/formatters.rb
 - lib/hammer_cli/output/adapter/table.rb
 - lib/hammer_cli/output/adapter/base.rb
 - lib/hammer_cli/output/adapter/abstract.rb
 - lib/hammer_cli/output/adapter/silent.rb
 - lib/hammer_cli/output/adapter/csv.rb
-- lib/hammer_cli/output/definition.rb
 - lib/hammer_cli/output/adapter.rb
-- lib/hammer_cli/output/dsl.rb
-- lib/hammer_cli/output/formatters.rb
 - lib/hammer_cli/output/output.rb
-- lib/hammer_cli/output/fields.rb
-- lib/hammer_cli/settings.rb
+- lib/hammer_cli/output/dsl.rb
+- lib/hammer_cli/output/definition.rb
+- lib/hammer_cli/abstract.rb
+- lib/hammer_cli/shell.rb
+- lib/hammer_cli/autocompletion.rb
+- lib/hammer_cli/logger_watch.rb
+- lib/hammer_cli/logger.rb
+- lib/hammer_cli/apipie.rb
+- lib/hammer_cli/apipie/command.rb
+- lib/hammer_cli/apipie/options.rb
+- lib/hammer_cli/apipie/resource.rb
+- lib/hammer_cli/apipie/write_command.rb
+- lib/hammer_cli/apipie/read_command.rb
 - lib/hammer_cli/validator.rb
+- lib/hammer_cli/version.rb
 - lib/hammer_cli/exit_codes.rb
+- lib/hammer_cli/output.rb
+- lib/hammer_cli/exception_handler.rb
 - lib/hammer_cli/main.rb
-- lib/hammer_cli.rb
+- lib/hammer_cli/option_formatters.rb
+- lib/hammer_cli/settings.rb
 - bin/hammer
 - README.md
 - LICENSE
@@ -148,29 +163,31 @@ files:
 - config/cli_config.template.yml
 - doc/design.png
 - doc/design.uml
+- doc/developer_docs.md
 homepage: http://github.com/theforeman/hammer-cli
 licenses:
 - GPL-3
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.8
+rubygems_version: 1.8.24
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Universal command-line interface
 test_files: []
 has_rdoc: 

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 1f5774b64875357f58a29b8f41584e1257696886
-  data.tar.gz: f1643f5fb4d1e545646e50ab663765b173684823
-SHA512:
-  metadata.gz: 8ecb458b3c3cf2705a513431c718e5f2bac89c8528f7f11fe1f7364e32c66f20431801787a9d501dbef713b3f9f031750aa24c5f51465bd91778bd129cc867f4
-  data.tar.gz: eec75c3547ddbe73e9ac5a772f617bb440da9f3ae425c330b7b53eaa9bd0841c246b09c4e3b085b1d9f9ea91754f6d955667816bd8fcce2108c3faed69f1c42f