hammer_cli 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 83ee93e64de515a960acf80a4ed0452d700fb5cd
-  data.tar.gz: fb55752f1a394e1261a342bf3d8e9a68ed98386f
+  metadata.gz: 290f41e5f2227f4e71ffbaf977f02ba0cf8b1601
+  data.tar.gz: 14502a8f77396925e426d8e1384f73e77fd6288a
 SHA512:
-  metadata.gz: 772c2a0849cde3c134977dfe3856cd4e6deb4b3cdbaa0568eb7656e64c9a9d722b11ba00a61a65a99e75978fd377e069f2aa9b4adb9e1fe7f8535dc4cc1edb19
-  data.tar.gz: dff56f16e56b6632e1e82e5327f1c0ae7fd39e218ce6aaaf5d0d4c30643b12dc3864e83fd9279066e504f0c740de9b666fe103498eeaf086caf11633ecf62bba
+  metadata.gz: 05159163a04fb707dbdfcd1292bd2d9b845742643b3d39fde9d422a060dab9cd4d8d8a3cd82b957427c01ca7629444eee63834d8afff2c649d917509acb12105
+  data.tar.gz: 238d88468d9fc4e74c209d991a6b1cde091eb14f5cb0f31e7c5ad7e5932a8f2a5d9f6e67999eb982b2b40ac81e22ff38c85e495e42be42190f4ed5b25331ec02

data/README.md

@@ -1,7 +1,6 @@
 Hammer - the CLI tool (not only) for Foreman
 ============================================
 
-
 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.
 
@@ -16,22 +15,31 @@ You also can easily add custom commands for your specific use, such as bulk acti
 
 Installation
 ------------
-We build rpms, debs and gems. Alternatively you can install hammer form a git checkout. See our [installation instructions](doc/installation.md#installation) for details.
+We build rpms, debs and gems. Alternatively you can install hammer form a git checkout.
+See our [installation and configuration instuctions](doc/installation.md#installation).
+
+
+Having issues?
+--------------
+If one of hammer commands doesn't work as you would expect, you can run `hammer -d ...` to get
+full debug output from the loggers. It should give you an idea what went wrong.
+
+If you have questions, don't hesitate to contact us on `foreman-users@googlegroups.com` or
+`FreeNode#foreman` irc channel.
 
 
 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
+or use it as a base for your own CLI, read
 [the developer docs](doc/developer_docs.md#hammer-development-docs).
 
+
 License
 -------
-
 This project is licensed under the GPLv3+.
 
 
 Acknowledgements
 ----------------
-
 Thanks to Brian Gupta for the initial work and a great name.

data/config/cli_config.template.yml

@@ -1,15 +1,24 @@
+# User interface related settings
 :ui:
+  # Enable interactive queries?
   :interactive: true
+  # Number of records listed per page
   :per_page: 20
+  # Location of shell history file
   :history_file: '~/.hammer/history'
 
 
-# enable/disable color output of logger in Clamp commands
+# Enable/disable color output of logger in Clamp commands
 :watch_plain: false
 
+# Directory where the logs are stored. The default is /var/log/hammer/ and the log file is named hammer.log
 :log_dir: '~/.hammer/log'
+
+# Logging level. One of debug, info, warning, error, fatal
 :log_level: 'error'
-:log_api_calls: false
+
 #:log_owner: 'foreman'
 #:log_group: 'foreman'
-#:log_size: 5 #MB
+
+# Maximum log size in bytes. Log rotates when the value gets exceeded
+#:log_size: 5 #in MB

data/doc/creating_apipie_commands.md

@@ -1,76 +1,69 @@
 Creating commands for RESTful API with ApiPie
 ---------------------------------------------
 
-CLIs binded to a rest api do simillar things for most of the resources. Typically it's
+CLIs bound to a REST API do simillar things for most of the resources. Typically there are
 CRUD actions that appear for nearly every resource. Actions differ with parameters
 accross resources but the operations remain the same.
 
 Hammer is optimised for usage with [ApiPie](https://github.com/Pajk/apipie-rails)
-and generated api bindings and tries to reduce the effort neccessary for a command creation.
+and generated API bindings and tries to reduce the effort neccessary for a command creation.
 
 
 ### ApiPie and bindings
 
 [ApiPie](https://github.com/Pajk/apipie-rails) is a documentation library for RESTful APIs.
-Unlike traditional tools ApiPie uses DSL for api description. This brings many advantages. See its
+Unlike traditional tools ApiPie uses DSL for API descriptions. This brings many advantages. See its
 documentation for details.
 
 Foreman comes with [ruby bindings](https://github.com/theforeman/foreman_api) automatically generated
 from the information provided by ApiPie. Every resource (eg. Architecture, User) has it's own
-class with methods for each available action (eg. create, show, index, destroy).
-Apart from that it contains also full api documentation with parameters for the actions.
-This enables to reuse the documentation on client side for automatic option definition
-and reduce the amount of custom code per CLI action.
+class with methods for each available action (e.g. create, show, index, destroy).
+Apart from that it contains also full API documentation with parameters for the actions.
+This allows to reuse the documentation on the client side for automatic option definition
+and to reduce the amount of custom code per CLI action.
 
 
 ### ApiPie commands in Hammer
 
-Hammer identifies two basic types of ApiPie commands:
+Hammer provides `HammerCLI::Apipie::Command` base class for apipie actions.
+The command class is single resource related and expect the resource and an action to be defined.
 
--  __ReadCommand__
-  - should be used for actions that print records
-  - retrieves the data and prints them in given format (uses output definition)
-  - typical actions in rails terminology: _index, show_
-
-- __WriteCommand__
-  - should used for actions that modify records
-  - sends modifying request and prints the result
-  - typical actions in rails terminology: _create, update, destroy_
-
-Both command classes are single resource related and expect the resource and an action to be defined.
 There's a simple DSL for that:
 
 ```ruby
-class ListCommand < HammerCLI::Apipie::ReadCommand
+class ListCommand < HammerCLI::Apipie::Command
   # define resource and the action together
-  resource ForemanApi::Resources::Architecture, :index
+  resource :architectures, :index
 end
 
 # or
 
-class ListCommand2 < HammerCLI::Apipie::ReadCommand
+class ListCommand2 < HammerCLI::Apipie::Command
   # define them separately
-  resource ForemanApi::Resources::Architecture
+  resource :architectures
   action :index
 end
 ```
 
 #### Options definition
 
-When the resource-action pair is defined we can take the advantage of automatic option definition.
-There's a class method `apipie_options` for this purpose.
+When the resource-action pair is defined we can take advantage of automatic option definition.
+There's an [option builder](https://github.com/theforeman/hammer-cli/blob/master/lib/hammer_cli/apipie/option_builder.rb)
+for apipie parameters pre-set in the apipie command's base class.
+You can read details about the option builder principles [here](option_builders.md#option-builders).
+
 
 ```ruby
-class ListCommand < HammerCLI::Apipie::ReadCommand
-  resource ForemanApi::Resources::Architecture, :index
+class ListCommand < HammerCLI::Apipie::Command
+  resource :architectures, :index
 
-  apipie_options
+  build_options
 end
 ```
 
 If we plug the command into an existing command tree and check the help we will see there
 are four parameters defined from the ApiPie docs. Compare the result with
-[online api documentation](http://www.theforeman.org/api/apidoc/architectures/index.html).
+[online API documentation](http://www.theforeman.org/api/apidoc/architectures/index.html).
 ```
 $ hammer architecture list -h
 Usage:
@@ -85,14 +78,18 @@ Options:
 ```
 
 It is possible to combine apipie options with custom ones. If the generated options
-doesn't suit your needs for any reason, you can always skip and redefine them by hand.
+don't suit your needs for any reason, you can always redefine them by hand or just skip them.
+
 See following example.
 ```ruby
-class ListCommand < HammerCLI::Apipie::ReadCommand
-  resource ForemanApi::Resources::Architecture, :index
+class ListCommand < HammerCLI::Apipie::Command
+  resource :architectures, :index
 
-  apipie_options :without => [:search, :order]
+  # first created option takes precedence
   option '--search', 'QUERY', "search query"
+
+  # use option :without to define what options should be skipped
+  build_options :without => [:order]
 end
 ```
 
@@ -109,16 +106,16 @@ Options:
 ```
 Note that the `--search` description has changed and `--order` disappeared.
 
-Automatic options reflect:
+Automaticaly generated options reflect:
 - parameter names and descriptions
 - required parameters
 - parameter types - the only supported type is array, which is translated to option normalizer `List`
 
-#### Write commands
+#### Status messages
 
-Write commands are expected to print result of the api action. There are
+Some commands are expected to print result of the API action. There are
 two class methods for setting success and failure messages. Messages are
-printed according to the http status code the api returned.
+printed according to the HTTP status code the API returned.
 
 ```ruby
 success_message "The user has been created"
@@ -129,14 +126,14 @@ failure_message "Could not create the user"
 #### Example 1: Create an architecture
 
 ```ruby
-class CreateCommand < HammerCLI::Apipie::WriteCommand
+class CreateCommand < HammerCLI::Apipie::Command
   command_name "create"
-  resource ForemanApi::Resources::Architecture, :create
+  resource :architectures, :create
 
   success_message "Architecture created"
   failure_message "Could not create the architecture"
 
-  apipie_options
+  build_options
 end
 ```
 
@@ -174,12 +171,12 @@ Could not create the architecture:
 #### Example 2: Show an architecture
 
 ```ruby
-class InfoCommand < HammerCLI::Apipie::ReadCommand
+class InfoCommand < HammerCLI::Apipie::Command
   command_name "info"
-  resource ForemanApi::Resources::Architecture, :show
+  resource :architectures, :show
 
   # It's a good practice to reuse output definition from list commands
-  # and add more details. It helps avoiding duplicities.
+  # and add more details. This helps avoiding duplicities.
   output ListCommand.output_definition do
     from "architecture" do
       field :operatingsystem_ids, "OS ids", Fields::List
@@ -188,7 +185,7 @@ class InfoCommand < HammerCLI::Apipie::ReadCommand
     end
   end
 
-  apipie_options
+  build_options
 end
 ```
 
@@ -214,7 +211,7 @@ Updated at:  2013/06/08 19:17:43
 
 #### Tips
 
-When you define more command like we've shown above you find yourself repeating
+When you define more commands like we've shown above you find yourself repeating
 `resource ...` in every one of them. As the commands are usually grouped by
 the resource it is handy to extract the resource definition one level up to
 the encapsulating command.
@@ -222,15 +219,15 @@ the encapsulating command.
 ```ruby
  class Architecture < HammerCLI::Apipie::Command
 
-    resource ForemanApi::Resources::Architecture
+    resource :architectures
 
-    class ListCommand < HammerCLI::Apipie::ReadCommand
+    class ListCommand < HammerCLI::Apipie::Command
       action :index
       # ...
     end
 
 
-    class InfoCommand < HammerCLI::Apipie::ReadCommand
+    class InfoCommand < HammerCLI::Apipie::Command
       action :show
       # ...
     end
@@ -245,20 +242,20 @@ the resource of the parent command is used at runtime. This is useful for contex
 shared commands.
 
 The following example shows a common subcommand that can be attached to
-any parent of which resource implements method `add_tag`. Please note that this example
-is fictitious. There's no tags in Foreman's architectures and users.
+any parent which has a resource implementing the method `add_tag`. Please note that this example
+is fictitious. There are no tags in Foreman's architectures and users.
 ```ruby
 module Tags
   class AddTag < HammerCLI::Apipie::WriteCommand
     option '--id', 'ID', 'ID of the resource'
     option '--tag', 'TAG', 'Name of the tag to add'
     action :add_tag
-    command_name 'add_tag'
+    command_name 'add-tag'
   end
 end
 
 class Architecture < HammerCLI::Apipie::Command
-  resource ForemanApi::Resources::Architecture
+  resource :architectures
   # ...
   include Tags
   autoload_subcommands
@@ -273,9 +270,9 @@ end
 ```
 
 ```
-$ hammer architecture add_tag -h
+$ hammer architecture add-tag -h
 Usage:
-    hammer architecture add_tag [OPTIONS]
+    hammer architecture add-tag [OPTIONS]
 
 Options:
     --id ID                       ID of the resource
@@ -284,9 +281,9 @@ Options:
 ```
 
 ```
-$ hammer user add_tag -h
+$ hammer user add-tag -h
 Usage:
-    hammer user add_tag [OPTIONS]
+    hammer user add-tag [OPTIONS]
 
 Options:
     --id ID                       ID of the resource

data/doc/creating_commands.md

@@ -13,7 +13,7 @@ touch ./lib/hammer_cli_hello/hello_world.rb
 # ./lib/hammer_cli_hello/hello_world.rb
 require 'hammer_cli'
 
-# it's a good practise to nest commands into modules
+# it's a good practice to nest commands into modules
 module HammerCLIHello
 
   # hammer commands must be descendants of AbstractCommand
@@ -97,7 +97,7 @@ for the full list of available exit codes.
 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. However unlike in Clamp, the option accessors in Hammer are created with prefix 'option_', to avoid
+on that topic. However, unlike in Clamp, the option accessors in Hammer are created with prefix 'option_', to avoid
 conflict with methods of the commands. So to access value of an `--name` option you have to call `option_name()`
 
 
@@ -129,6 +129,9 @@ $ hammer hello --name 'Foreman'
 Hello Foreman!
 ```
 
+### Option builders
+Hammer commands offer option builders that can be used for automatic option generation.
+See [documentation page](option_builders.md#option-builders) dedicated to this topic for more details.
 
 ### Option validation
 Hammer provides extended functionality for validating options.
@@ -139,10 +142,10 @@ First of all there is a dsl for validating combinations of options:
 validate_options do
   all(:option_name, :option_surname).required  # requires all the options
   option(:option_age).required          # requires a single option,
-                                 # equivalent of :required => true in option declaration
+                                        # equivalent of :required => true in option declaration
   any(:option_email, :option_phone).required   # requires at least one of the options
 
-  # Tt is possible to create more complicated constructs.
+  # It is possible to create more complicated constructs.
   # This example requires either the full address or nothing
   if any(:option_street, :option_city, :option_zip).exist?
     all(:option_street, :option_city, :option_zip).required
@@ -204,7 +207,7 @@ option "--attributes", "ATTRIBUTES", "Values of various attributes",
 `--attributes="material=unoptanium,thickness=3"` -> `{'material' => 'unoptanium', 'thickness' => '3'}`
 
 ### Adding subcommands
-Commands in the cli can be structured into a tree of parent commands (nodes) and subcommands (leaves).
+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.
@@ -247,7 +250,7 @@ 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:
+when you have a growing number of subcommands. See how it works in the following example:
 
 ```ruby
 module HammerCLIHello
@@ -307,7 +310,7 @@ a message in a log for debugging purposes.
 
 
 ### Removing subcommands
-If your plugin needs to disable existing subcommand, you can use `remove_subcommand` for this.
+If your plugin needs to disable an existing subcommand, you can use `remove_subcommand` for this.
 
 ```ruby
   HammerCLI::MainCommand.remove_subcommand 'say'
@@ -337,13 +340,13 @@ 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.
+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.
+You first create a _output definition_ that you apply to your data. The result
+is a collection of fields, each having its type. The collection is then passed to an
+_output adapter_ which handles the actual formatting and printing.
 
 Hammer provides a DSL for defining the output. Next rather complex example will
 explain how to use it in action.
@@ -380,7 +383,7 @@ We can create an output definition that selects and formats some of the fields:
 class Command < HammerCLI::AbstractCommand
 
   output do
-    # Simple field with a label. The first parameter is key in the printed hash.
+    # Simple field with a label. The first parameter is the key in the printed hash.
     field :id, 'ID'
 
     # Fields can have types. The type determines how the field is printed.
@@ -403,7 +406,7 @@ class Command < HammerCLI::AbstractCommand
 
   def execute
     records = retrieve_data
-    print_records(         # <- printing utility of AbstractCommand
+    print_record(          # <- printing utility of AbstractCommand
       output_definition,   # <- method for accessing fields defined in the block 'output'
       records              # <- the data to print
     )
@@ -432,7 +435,7 @@ Contacts:
 Created At:    2012/12/18 15:25:00
 ```
 
-You can optionally use output definition from another command as a base and extend it with
+You can optionally use the output definition from another command as a base and extend it with
 additional fields. This is helpful when there are two commands, one listing brief data and
 another one showing details. Typically it's list and show.
 ```ruby
@@ -455,7 +458,7 @@ All Hammer field types are:
  * __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 adapter for every command is the Base adapter. It is possible to override
 the default one by redefining command's method `adapter`.
 
 ```ruby
@@ -523,7 +526,7 @@ 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
+rather than handle it and return error codes. This approach guarantees that error messages are logged and
 printed consistently and correct exit codes are returned.
 
 
@@ -532,7 +535,7 @@ 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.
+the plugin's name (without the prefix 'hammer_cli_') in config files.
 
 ```yaml
 #cli_config.yml
@@ -546,6 +549,9 @@ 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.
+There are more ways where to place your config file for hammer.
+The best practice is to place module's configuration into a separate file named by
+the module. In this example it would be `~/.hammer/cli.modules.d/hello_world.yml`.
+
 Read more in [the settings howto](https://github.com/theforeman/hammer-cli#configuration).