hammer_cli 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f94cb081ad874612f32639ed07cdf5626fb69ba4
-  data.tar.gz: 479cf176ac7bb522702489eb0205286ea0a98bf4
+  metadata.gz: 8f3bb9d5531d8e5c2686fa69e7715c4f746c677b
+  data.tar.gz: 9af8fd7a349392f0c00e69df2183fe0015232639
 SHA512:
-  metadata.gz: 5a52be94f2ad2519e8eff5737b4f1fafbefb247db4fc49a6be931f0129f4a12fae8641e086ab4f0b9cca8bef691db8a5a6035c43e94afb7cb1c6ef0da7504403
-  data.tar.gz: b97b952d02e88eb7541ea041d61b32cfe5374200a1d59ba6d24a38f8f3e58289b598606a075863ba58501f038c61547ce0b669e42befa81ea1b074d914c2ceec
+  metadata.gz: 220f699b4bdd24f5ad223a9b9d310361de3da6ebf5fa222425f1efcade8fc81d7d66392794bb6f5cac5f5311f20f646187a819b4f63955cde1a44ea96300b36d
+  data.tar.gz: 7bfee673681c83321ce82f73981f7c5f90be6d6e4ed78fbd6fae73ebc98cbbe319d37e3c084f2c742d84b2e395d3c434e296d442fb980b94b938b1ba45b9ea9b

data/README.md

@@ -2,7 +2,7 @@ Hammer - the CLI tool (not only) for Foreman
 ============================================
 
 
-Hammer is a generic [clamp-based](https://github.com/mdub/clamp) CLI framework. 
+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.
 
 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.
@@ -244,7 +244,7 @@ Use the hammer
 Confirm your setup by running ```$ hammer -h``` and check that the desired commands are listed.
 
 ```
-$ hammer -h 
+$ hammer -h
 Usage:
     hammer [OPTIONS] SUBCOMMAND [ARG] ...
 
@@ -332,9 +332,9 @@ Then after starting a new shell the completion should work.
 
 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).
+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-development-docs).
 
 License
 -------

data/doc/creating_apipie_commands.md

@@ -0,0 +1,296 @@
+Creating commands for RESTful API with ApiPie
+---------------------------------------------
+
+CLIs binded to a rest api do simillar things for most of the resources. Typically it's
+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.
+
+
+### 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
+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.
+
+
+### ApiPie commands in Hammer
+
+Hammer identifies two basic types of ApiPie commands:
+
+-  __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
+  # define resource and the action together
+  resource ForemanApi::Resources::Architecture, :index
+end
+
+# or
+
+class ListCommand2 < HammerCLI::Apipie::ReadCommand
+  # define them separately
+  resource ForemanApi::Resources::Architecture
+  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.
+
+```ruby
+class ListCommand < HammerCLI::Apipie::ReadCommand
+  resource ForemanApi::Resources::Architecture, :index
+
+  apipie_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).
+```
+$ hammer architecture list -h
+Usage:
+    hammer architecture list [OPTIONS]
+
+Options:
+    --search SEARCH               filter results
+    --order ORDER                 sort results
+    --page PAGE                   paginate results
+    --per-page PER_PAGE           number of entries per request
+    -h, --help                    print help
+```
+
+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.
+See following example.
+```ruby
+class ListCommand < HammerCLI::Apipie::ReadCommand
+  resource ForemanApi::Resources::Architecture, :index
+
+  apipie_options :without => [:search, :order]
+  option '--search', 'QUERY', "search query"
+end
+```
+
+```
+hammer architecture list -h
+Usage:
+    hammer architecture list [OPTIONS]
+
+Options:
+    --page PAGE                   paginate results
+    --per-page PER_PAGE           number of entries per request
+    --search QUERY                search query
+    -h, --help                    print help
+```
+Note that the `--search` description has changed and `--order` disappeared.
+
+Automatic 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
+
+Write 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.
+
+```ruby
+success_message "The user has been created"
+failure_message "Could not create the user"
+```
+
+
+#### Example 1: Create an architecture
+
+```ruby
+class CreateCommand < HammerCLI::Apipie::WriteCommand
+  command_name "create"
+  resource ForemanApi::Resources::Architecture, :create
+
+  success_message "Architecture created"
+  failure_message "Could not create the architecture"
+
+  apipie_options
+end
+```
+
+```
+$ hammer architecture create -h
+Usage:
+    hammer architecture create [OPTIONS]
+
+Options:
+    --name NAME
+    --operatingsystem-ids OPERATINGSYSTEM_IDS Operatingsystem ID’s
+                                  Comma separated list of values.
+    -h, --help                    print help
+```
+
+```
+$ hammer architecture create
+ERROR: option '--name' is required
+
+See: 'hammer architecture create --help'
+```
+
+```
+$ hammer architecture create --name test --operatingsystem-ids=1,2
+Architecture created
+```
+
+```
+$ hammer architecture create --name test
+Could not create the architecture:
+  Name has already been taken
+```
+
+
+#### Example 2: Show an architecture
+
+```ruby
+class InfoCommand < HammerCLI::Apipie::ReadCommand
+  command_name "info"
+  resource ForemanApi::Resources::Architecture, :show
+
+  # It's a good practice to reuse output definition from list commands
+  # and add more details. It helps avoiding duplicities.
+  output ListCommand.output_definition do
+    from "architecture" do
+      field :operatingsystem_ids, "OS ids", Fields::List
+      field :created_at, "Created at", Fields::Date
+      field :updated_at, "Updated at", Fields::Date
+    end
+  end
+
+  apipie_options
+end
+```
+
+```
+$ hammer architecture info -h
+Usage:
+    hammer architecture info [OPTIONS]
+
+Options:
+    --id ID
+    -h, --help                    print help
+```
+
+```
+$ hammer architecture info --id 1
+Id:          1
+Name:        x86_64
+OS ids:      1, 3
+Created at:  2013/06/08 18:53:56
+Updated at:  2013/06/08 19:17:43
+```
+
+
+#### Tips
+
+When you define more command 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.
+
+```ruby
+ class Architecture < HammerCLI::Apipie::Command
+
+    resource ForemanApi::Resources::Architecture
+
+    class ListCommand < HammerCLI::Apipie::ReadCommand
+      action :index
+      # ...
+    end
+
+
+    class InfoCommand < HammerCLI::Apipie::ReadCommand
+      action :show
+      # ...
+    end
+
+    # ...
+  end
+```
+
+ApiPie resources are being looked up in the encapsulating classes and modules
+when the definition is missing in the command class. If they are not found even there
+the resource of the parent command is used at runtime. This is useful for context-aware
+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.
+```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'
+  end
+end
+
+class Architecture < HammerCLI::Apipie::Command
+  resource ForemanApi::Resources::Architecture
+  # ...
+  include Tags
+  autoload_subcommands
+end
+
+class User < HammerCLI::Apipie::Command
+  resource ForemanApi::Resources::User
+  # ...
+  include Tags
+  autoload_subcommands
+end
+```
+
+```
+$ hammer architecture add_tag -h
+Usage:
+    hammer architecture add_tag [OPTIONS]
+
+Options:
+    --id ID                       ID of the resource
+    --tag TAG                     Name of the tag to add
+    -h, --help                    print help
+```
+
+```
+$ hammer user add_tag -h
+Usage:
+    hammer user add_tag [OPTIONS]
+
+Options:
+    --id ID                       ID of the resource
+    --tag TAG                     Name of the tag to add
+    -h, --help                    print help
+```
+