hammer_cli 0.0.18 → 0.1.0

data/doc/developer_docs.md

@@ -11,3 +11,4 @@ Contents:
  - [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)

data/doc/i18n.md

@@ -0,0 +1,85 @@
+Internacionalization
+--------------------
+
+Hammer uses [fast gettext](https://github.com/grosser/fast_gettext) for string translations. Most of the localization magic
+is done for you in hammer already. If you want your plugin to support i18n it needs to register it's translation domain
+at hammer's i18n module:
+```ruby
+require 'hammer_cli/i18n'
+
+# namespace your i18n module
+module HammerCLIAwesome
+  module I18n
+
+    # create a locale domain for your plugin
+    class LocaleDomain < HammerCLI::I18n::LocaleDomain
+
+      # lists all your source files that use _()
+      def translated_files
+        Dir.glob(File.join(File.dirname(__FILE__), '../**/*.rb'))
+      end
+
+      # returns path to your locale directory
+      # it's typically "locale" in the root of your plugin
+      def locale_dir
+        File.join(File.dirname(__FILE__), '../../locale')
+      end
+
+      # name for your language domain
+      def domain_name
+        'hammer-cli-awesome'
+      end
+
+      # type of the translation files, 'mo' files are default
+      # you can also use 'po' and 'yaml' files for testing purposes
+      def type
+        :mo
+      end
+
+    end
+
+  end
+end
+
+# register the domain
+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).
+
+Typical directory structure for translation files look like this:
+```
+locale
+├── de
+│   ├── hammer-cli-awesome.po
+│   └── LC_MESSAGES
+│       └── hammer-cli-awesome.mo
+├── en
+│   ├── hammer-cli-awesome.po
+│   └── LC_MESSAGES
+│       └── hammer-cli-awesome.mo
+└── hammer-cli-awesome.pot
+```
+
+
+### Translation tips
+
+When writing a 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
+# WRONG
+puts _("Hello #{name}")
+puts _("Hello %s" % name)
+# CORRECT
+puts _("Hello %s") % name
+```
+
+2) Use named placeholders when there is more than one replacement. Languages differ in their word order.
+```ruby
+# WRONG
+puts _("Hello %s, it is %s" % [name, day])
+# CORRECT
+puts _("Hello %{name}, it is %{day}") % {:name => name, :day => day}
+```

data/doc/installation.md

@@ -0,0 +1,321 @@
+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.
+
+
+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.
+
+
+Configuration
+-------------
+
+### Locations
+
+Configuration is by default looked for in the following directories, loaded in this order:
+
+ - ```RbConfig::CONFIG['sysconfdir']/hammer/``` (The actual value depends on your operatingsystem and ruby defaults.)
+ - ```/etc/hammer/```
+ - ```~/.hammer/```
+ - ```./config/``` (config dir in CWD)
+ - custom location (file or directory) specified on command line - ```-c CONF_FILE_PATH```
+
+In each of these directories hammer is trying to load ```cli_config.yml``` and anything in
+the ```cli.modules.d``` subdirectory which is place for specific configuration of hammer modules.
+
+Later directories and files have precedence if they redefine the same option. Files from ```cli.modules.d```
+are loaded in alphabetical order.
+
+### Format
+
+Hammer uses yaml formatting for its configuration. 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)
+
+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```)
+
+
+#### Sample config
+
+```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).
+
+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:
+
+```yaml
+:foreman:
+    :enable_module: true
+    :host: 'https://localhost/'
+    :username: 'admin'
+    :password: 'changeme'
+```
+
+Use the hammer
+--------------
+
+Confirm your setup by running ```$ hammer -h``` and check that the desired commands are listed.
+
+```
+$ hammer -h
+Usage:
+    hammer [OPTIONS] SUBCOMMAND [ARG] ...
+
+Parameters:
+    SUBCOMMAND                    subcommand
+    [ARG] ...                     subcommand arguments
+
+Subcommands:
+    activation-key                Manipulate activation keys.
+    architecture                  Manipulate architectures.
+    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
+    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
+    os                            Manipulate operating system.
+    partition_table               Manipulate partition tables.
+    ping                          get the status of the server
+    product                       Manipulate products.
+    provider                      Manipulate providers
+    proxy                         Manipulate smart proxies.
+    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.
+    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.
+
+Options:
+    --autocomplete LINE           Get list of possible endings
+    --csv                         Output as CSV (same as --output=csv)
+    --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]
+    --show-ids                    Show ids of associated resources
+    --version                     show version
+    -c, --config CFG_FILE         path to custom config file
+    -h, --help                    print help
+    -p, --password PASSWORD       password to access the remote system
+    -u, --username USERNAME       username to access the remote system
+    -v, --verbose                 be verbose
+```
+
+
+And you are Done. Your hammer client is configured and ready to use.
+
+
+Autocompletion
+--------------
+
+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 after starting a new shell the completion should work.

data/lib/hammer_cli.rb

@@ -1,8 +1,11 @@
+require 'hammer_cli/i18n'
+require 'hammer_cli/exceptions'
 require 'hammer_cli/utils'
 require 'hammer_cli/version'
 require 'hammer_cli/modules'
 require 'hammer_cli/exit_codes'
 require 'hammer_cli/settings'
+require 'hammer_cli/connection'
 require 'hammer_cli/validator'
 require 'hammer_cli/output'
 require 'hammer_cli/options/normalizers'

data/lib/hammer_cli/abstract.rb

@@ -87,6 +87,19 @@ module HammerCLI
       super
     end
 
+    class SortedBuilder < Clamp::Help::Builder
+      def add_list(heading, items)
+        items.sort! do |a, b|
+          a.help[0] <=> b.help[0]
+        end
+        super(heading, items)
+      end
+    end
+
+    def help
+      self.class.help(invocation_path, SortedBuilder.new)
+    end
+
     def self.output(definition=nil, &block)
       dsl = HammerCLI::Output::Dsl.new
       dsl.build &block if block_given?
@@ -116,35 +129,13 @@ module HammerCLI
       @output_definition
     end
 
-    protected
 
     def interactive?
-      if context[:interactive].nil?
-        return STDOUT.tty? && (HammerCLI::Settings.get(:ui, :interactive) != false)
-      else
-        return context[:interactive]
-      end
+      HammerCLI.interactive?
     end
 
-    def ask_username
-      ask("Username: ") if interactive?
-    end
-
-    def ask_password
-      ask("Password for '%s': " % username) {|q| q.echo = false} if interactive?
-    end
 
-    def username(ask_interactively=true)
-      context[:username] ||= ENV['FOREMAN_USERNAME'] || HammerCLI::Settings.get(:foreman, :username)
-      context[:username] ||= ask_username if ask_interactively
-      context[:username]
-    end
-
-    def password(ask_interactively=true)
-      context[:password] ||= ENV['FOREMAN_PASSWORD'] || HammerCLI::Settings.get(:foreman, :password)
-      context[:password] ||= ask_password if ask_interactively
-      context[:password]
-    end
+    protected
 
     def print_record(definition, record)
       output.print_record(definition, record)