hammer_cli 0.1.0 → 0.1.1

data/doc/developer_docs.md

@@ -3,12 +3,13 @@ Hammer Development 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.
+before creating hammer specific plugins.
 
 Contents:
  - [Writing a plugin](writing_a_plugin.md#writing-your-own-hammer-plugin)
  - [Creating commands](creating_commands.md#create-your-first-command)
+ - [Option builders](option_builders.md#option-builders)
  - [Creating ApiPie commands](creating_apipie_commands.md#creating-commands-for-restful-api-with-apipie)
  - [Development tips](development_tips.md#development-tips)
  - [Option normalizers](option_normalizers.md#option-normalizers)
- - [Internacionalization](i18n.md#internacionalization)
+ - [Internationalization](i18n.md#internationalization)

data/doc/development_tips.md

@@ -2,7 +2,7 @@ Development Tips
 ----------------
 
 ### Local gem modifications
-If you want to modify gems setup for development needs, create a file `Gemfile.local` in the root of your hammer-cli checkout. You can override the setup from `Gemfile` there. This file is git-ignored so you can easily keep your custom tuning.
+If you want to modify the gems setup for development needs, create a file `Gemfile.local` in the root of your hammer-cli checkout. You can override the setup from `Gemfile` there. This file is git-ignored so you can easily keep your custom tuning.
 
 Typical usage is for linking plugins from local checkouts:
 ```ruby
@@ -11,9 +11,9 @@ gem 'hammer_cli_foreman', :path => '../hammer-cli-foreman'
 
 ### Debugging with Pry
 [Pry](https://github.com/pry/pry) is a runtime developer console for ruby.
-It allows for debugging when [Pry Debugger](https://github.com/nixme/pry-debugger) is installed alongside.
+It allows debugging when [Pry Debugger](https://github.com/nixme/pry-debugger) is installed alongside.
 
-For basic usage, add following lines to your `Gemfile.local`:
+For basic usage, add following the lines to your `Gemfile.local`:
 
 ```ruby
 gem 'pry'

data/doc/i18n.md

@@ -1,4 +1,4 @@
-Internacionalization
+Internationalization
 --------------------
 
 Hammer uses [fast gettext](https://github.com/grosser/fast_gettext) for string translations. Most of the localization magic
@@ -46,7 +46,7 @@ HammerCLI::I18n.add_domain(HammerCLIAwesomePlugin::I18n::LocaleDomain.new)
 ```
 
 Then you have to export strings, translate them and place the files in a directory structure.
-Inspiration on how to export the translations can be found in the hammer's [Rakefile](../Rakefile).
+Inspiration on how to export the translations can be found in hammer's [Rakefile](../Rakefile).
 
 Typical directory structure for translation files look like this:
 ```
@@ -65,7 +65,7 @@ locale
 
 ### Translation tips
 
-When writing a code with translations make sure you keep two following rules:
+When writing code with translations make sure you keep two following rules:
 
 1) Don't use variables directly in the strings and make formatting substitutions outside the gettext function `_("...")`.
 ```ruby

data/doc/installation.md

@@ -8,161 +8,11 @@ Hammer CLI is packaged for the following RPM based distributions:
  - 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.
-
-
-Using stable
-
-```bash
-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
-```
-
- - commands for katello [katello cli](https://github.com/Katello/katello)
-
-```bash
-yum install rubygem-hammer_cli_katello
-```
-
-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 deb packages.
-
- - commands for managing foreman
-
-```bash
-$ apt-get install ruby-hammer-cli-foreman
-```
-
- - 1:1 bridge to [katello cli](https://github.com/Katello/katello)
-
-```bash
-$ apt-get install ruby-hammer-cli-katello
-```
-
-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
-```
-
-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 ..
-```
-
-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 via any of the methods mentioned above.
+### Select your way of installation
+- [Installation from RPMs](installation_rpm.md#installation-from-rpms)
+- [Installation from DEBs](installation_deb.md#installation-from-debs)
+- [Installation from GEMs](installation_gem.md#installation-from-gems)
+- [Installation from source](installation_source.md#installation-from-source)
 
 
 Configuration
@@ -184,51 +34,30 @@ the ```cli.modules.d``` subdirectory which is place for specific configuration o
 Later directories and files have precedence if they redefine the same option. Files from ```cli.modules.d```
 are loaded in alphabetical order.
 
-### Format
+### Manual installation
+The packaged version of hammer copies the template to `/etc/hammer` for you.
+When you install from gems or source you'll have to copy config files manually.
 
-Hammer uses yaml formatting for its configuration. The configuration templates are contained in the hammer_cli gem
+The configuration templates are contained in the hammer_cli gem
 
  ```bash
 gem contents hammer_cli|grep 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.
-
-
-### Options
-
- - ```:log_dir: <path>``` - directory where the logs are stored. The default is ```/var/log/hammer/``` 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: <bool>``` - turn on/off syntax highlighting of data being logged in debug mode
- - ```:log_api_calls: <bool>``` - turn on logging of the communication with API (data sent and received)
+and can be copied to one of the locations above and changed as needed.
 
-In the ```:ui``` section there is
 
- - ```:interactive: <bool>``` - whether to ask user for input (pagination, passwords)
- - ```:per_page: <records>``` - number of records per page if server sends paginated data
- - ```:history_file: <path>``` - file where the hammer shell store its history (default is ```~/.hammer_history```)
+### Tuning options
 
+Hammer uses [YAML](http://www.yaml.org/) formatting for its configuration.
 
-#### Sample config
+List of existing options is available in the [configuration template file](https://github.com/theforeman/hammer-cli/blob/master/config/cli_config.template.yml)
+with descriptions.
 
-```yaml
-:ui:
-  :interactive: true
-  :per_page: 20
-  :history_file: '~/.hammer/history'
-
-:watch_plain: false
-
-:log_dir: '~/.hammer/log'
-:log_level: 'error'
-:log_api_calls: false
-```
 
 ### Plugins
 
-Plugins are disabled by default. To enable plugin create configuration file in ```cli.modules.d``` and add```:enable_plugin: true``` in it. Plugin specific configuration should be nested under plugin's name (without the ```hammer_cli_``` prefix).
+Plugins are disabled by default. To enable plugin create configuration file in ```cli.modules.d``` and add```:enable_plugin: true``` in it.
+Plugin specific configuration must be nested under plugin's name (without the ```hammer_cli_``` prefix).
 
 In the example we assume the gem ```hammer_cli_foreman``` with the Foreman plugin is installed. Then the plugin configuration
 in ```~/.hammer/cli.plugins.d/foreman.yml``` should look as follows:
@@ -256,38 +85,26 @@ Parameters:
     [ARG] ...                     subcommand arguments
 
 Subcommands:
-    activation-key                Manipulate activation keys.
     architecture                  Manipulate architectures.
-    compute_resource              Manipulate compute resources.
+    compute-resource              Manipulate compute resources.
     domain                        Manipulate domains.
     environment                   Manipulate environments.
     fact                          Search facts.
-    global_parameter              Manipulate global parameters.
-    gpg                           manipulate GPG Key actions on the server
+    global-parameter              Manipulate global parameters.
     host                          Manipulate hosts.
     hostgroup                     Manipulate hostgroups.
-    lifecycle-environment         manipulate lifecycle_environments on the server
     location                      Manipulate locations.
     medium                        Manipulate installation media.
     model                         Manipulate hardware models.
-    organization                  Manipulate organizations
+    organization                  Manipulate organizations.
     os                            Manipulate operating system.
-    partition_table               Manipulate partition tables.
-    ping                          get the status of the server
-    product                       Manipulate products.
-    provider                      Manipulate providers
+    partition-table               Manipulate partition tables.
     proxy                         Manipulate smart proxies.
-    puppet_class                  Search puppet modules.
+    puppet-class                  Search puppet modules.
     report                        Browse and read reports.
-    repository                    Manipulate repositories
-    repository-set                manipulate repository sets on the server
-    sc_param                      Manipulate smart class parameters.
+    sc-param                      Manipulate smart class parameters.
     shell                         Interactive shell
     subnet                        Manipulate subnets.
-    subscription                  Manipulate subscriptions.
-    system                        manipulate systems on the server
-    systemgroup                   Manipulate system groups
-    task                          Tasks related actions.
     template                      Manipulate config templates.
     user                          Manipulate users.
 
@@ -297,7 +114,7 @@ Options:
     --csv-separator SEPARATOR     Character to separate the values
     --interactive INTERACTIVE     Explicitly turn interactive mode on/off
                                   One of true/false, yes/no, 1/0.
-    --output ADAPTER              Set output format. One of [base, table, silent, csv]
+    --output ADAPTER              Set output format. One of [silent, csv, base, table]
     --show-ids                    Show ids of associated resources
     --version                     show version
     -c, --config CFG_FILE         path to custom config file
@@ -308,7 +125,7 @@ Options:
 ```
 
 
-And you are Done. Your hammer client is configured and ready to use.
+And you are done. Your hammer client is configured and ready to use.
 
 
 Autocompletion

data/doc/installation_deb.md

@@ -0,0 +1,48 @@
+### 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 deb packages.
+
+ - commands for managing foreman
+
+```bash
+$ apt-get install ruby-hammer-cli-foreman
+```
+
+ - commands for managing [katello](https://github.com/Katello/katello)
+
+```bash
+$ apt-get install ruby-hammer-cli-katello
+```
+
+To install any other hammer plugin just make sure the appropriate gem is installed and follow with the [configuration](installation.md#configuration).

data/doc/installation_gem.md

@@ -0,0 +1,30 @@
+### 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
+```
+
+ - commands for managing [katello](https://github.com/Katello/katello)
+
+```bash
+$ gem install hammer_cli_katello
+```
+
+#### Step 3: enable and configure the plugins
+Installation via gems unfortunately won't create configuration files.
+You'll have to copy them to proper locations manually.
+Please check our [configuration instructions](installation.md#configuration).
+

data/doc/installation_rpm.md

@@ -0,0 +1,53 @@
+### 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.
+
+
+Using stable
+
+```bash
+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
+```
+
+ - commands for managing [katello](https://github.com/Katello/katello)
+
+```bash
+yum install rubygem-hammer_cli_katello
+```
+
+To install any other hammer plugin just make sure the appropriate gem is installed and follow with the [configuration](installation.md#configuration).