zabby 0.0.5 → 0.1.0

data/ChangeLog.rdoc

@@ -2,6 +2,19 @@
 
 List of visible changes:
 
+== v0.1.0 (2012/03/14)
+
+* Major refactoring: Zabbix items are now represented by classes instead
+  of class instances ("Host" vs. "host", "Item" vs. "item") and their
+  methods are now class methods.
+* Simplify code, remove unused or useless methods.
+* Move helper methods to their own module.
+* Update documentation and improve code samples.
+* Online "help" command.
+* Get rid of the elegant but buggy "set <param> <value>" syntax, the only
+  valid syntax for setting parameters is "set :<param> => <value>".
+* Improve exceptions definition.
+
 == v0.0.5 (2012/01/05)
 
 * Better command file parsing and add rcfile support.

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2011 Farzad FARID / Pragmatic Source. All rights reserved.
+Copyright 2011-2012 Farzad FARID / Pragmatic Source. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are
 permitted provided that the following conditions are met:

data/README.rdoc

@@ -5,11 +5,6 @@ clean interface to the {Zabbix Web Services}[http://www.zabbix.com/documentation
 
 == Goals
 
-There already are Ruby Zabbix libraries but some of them are unfinished (and apparently
-abandonned) and some other's code is too complicated or poorly designed. This is why I decided
-to write another tool for which my primary goal is to keep the code design, the user interaction
-and application interface clean and simple.
-
 Zabby has the following caracteristics:
 - Works both as a Ruby API and a command line tool.
 - Uses an internal Ruby DSL (Domain Specific Langage) that give access to the full power of
@@ -17,6 +12,11 @@ Zabby has the following caracteristics:
 - Simple design: avoids spaghetti code, WTF and facepalm, unlike some other
   Ruby Zabbix libraries.
 
+There already are Ruby Zabbix libraries but some of them are unfinished (and apparently
+abandonned) and some other's code is too complicated or poorly designed. This is why I decided
+to write this tool for which my primary goal is to keep the code design the user interaction
+and application interface clean and simple.
+
 == Features
 
 - Low level Ruby API that maps every Zabbix API (JSON RPC) to Ruby hashes.
@@ -24,14 +24,22 @@ Zabby has the following caracteristics:
 - Supports SSL and authenticated HTTP proxies.
 - Full featured IRB like shell included with Readline support. You can mix Zabbix instructions
   with Ruby calls transparently.
+- Reads a configuration file on startup.
+
+== Changes
+
+See the [ChangeLog.rdoc] file.
 
 == Configuration
 
-The file <tt>~/.zabbyrc</tt> is read on startup unless the option "<tt>--no-rcfile</tt>" is
+All the settings can be used interactively or written in a configuration file. The file
+<tt>~/.zabbyrc</tt> is read on startup unless the option "<tt>--no-rcfile</tt>" is
 used.
 
 === Command line
 
+The main configuration parameters are:
+
   --[no-]rcfile [CONFIG FILE]:  Configuration file to load on startup. Default is '~/.zabbyrc'. With the 'no' prefix no configuration file will be loaded.
   -f, --extra-file COMMAND_FILE:    Execute the instructions in COMMAND_FILE
 
@@ -62,33 +70,7 @@ This is a configuration <tt>.zabbyrc</tt> file example, it will be loaded at sta
 
 == Examples
 
-=== API use
-
-The barebone API can be used in Ruby like this:
-
-    require "rubygems"
-    require "zabby"
-    require "pp"
-
-    z = Zabby.init do
-      server "https://monitoring.example.com"
-      user "api_user"
-      password "s3cr3t"
-      proxy_host "http://10.10.10.10"
-      proxy_user "john"
-      proxy_password "D0e"
-    end
-    z.login
-
-    pp z.connection.perform_request("host", "get", { "filter" => { "host" => "master.example.com" } })
-    pp z.connection.perform_request("item", "get", { "host" => "master.example.com", "output" => "shorten" })
-
-- The _server_, _user_ and _passord_ are necessary.
-- If you don't provide the path to the JSON-RPC script "/api_jsonrpc.php" is appended
-  to the URI automatically.
-- The <em>proxy_*</em> settings are optionnal.
-
-=== Shell
+=== Zabby on the Command Line
 
 *zabbysh* is an simple Zabbix Shell. It runs either interactively or
 can be used to execute a command file with the "-f CMD_FILE" option.
@@ -99,36 +81,114 @@ the shell after executing the file.
 *zabbysh* provides Readline support but does no support advanced IRB features likes
 multi-lines instructions.
 
-*zabbyrb* is another Zabbix Shell based on *IRB*. It provides the whole power of IRB
+*Note*: *zabbyrb* is another Zabbix Shell based on *IRB*. It provides the whole power of IRB
 but may be less stable than zabbysh because the IRB API is poorly documented and hard
 to use.
 
 ==== Interactive shell
 
+Provided you created a <tt>~/.zabbyrc</tt> configuration file with authentication settings
+you can launch the interactive shell and start talking to the Zabbix server:
+
     # zabbysh
-    zabby> set server "https://monitoring.example.com"
-    zabby> set user "api_user"
-    zabby> set password "s3cr3t"
-    zabby> set proxy_host "http://10.10.10.10"
-    zabby> set proxy_user "john"
-    zabby> set proxy_password "D0e"
-    zabby> login
-    zabby> puts logged_in?
-    zabby> host.get "filter" => { "host" => "monitor.example.com" }, "output" => "extend"
-    zabby> item.get "host" => "monitor.example.com", "output" => "refer"
+    Zabby Shell 0.1.0
+
+    ** This is a simple irb like Zabbix Shell. Multiline commands do not work for e.g. **
+    Type "help" for online documentation.
+    zabby> logged_in?
+    => true
+    zabby> Host.get "filter" => { "host" => "monitor.example.com" }, "output" => "extend"
+    => [{"snmp_errors_from"=>"0", "ipmi_port"=>"623", "outbytes"=>"0", "proxy_hostid"=>"0",
+     "maintenance_status"=>"0", "ipmi_password"=>"", "ipmi_privilege"=>"2",
+     "ipmi_disable_until"=>"0", "available"=>"1", "maintenances"=>[{"maintenanceid"=>"0"}],
+     "ipmi_error"=>"", "maintenanceid"=>"0", "useipmi"=>"0", "port"=>"10050", "useip"=>"1",
+     "ipmi_errors_from"=>"0", "maintenance_from"=>"0", "ipmi_ip"=>"", "hostid"=>"10017",
+     "ipmi_available"=>"0", "disable_until"=>"0", "ip"=>"127.0.0.1", "maintenance_type"=>"0",
+     "ipmi_authtype"=>"0", "inbytes"=>"0", "lastaccess"=>"0",
+     "host"=>"monitor.example.com", "snmp_error"=>"", "ipmi_username"=>"", "status"=>"0",
+     "dns"=>"monitor.example.com", "snmp_available"=>"0", "snmp_disable_until"=>"0",
+     "errors_from"=>"0", "error"=>""}]
+    zabby> Item.get "host" => "monitor.example.com", "output" => "refer"
+    => [{"itemid"=>"18435", "host"=>"monitor.example.com"},
+    {"itemid"=>"18436", "host"=>"monitor.example.com"},
+    {"itemid"=>"18438", "host"=>"monitor.example.com"},
+    {"itemid"=>"18439",....]
     zabby> [...]
     zabby> logout
+    => nil
     zabby> exit
 
+To execute a script file before dropping into the shell type:
+
+    # zabbysh --extra-file some_zabbix_cmds.zby
+
+===== Online help
+
+Type *help* to get a brief description of available commands.
+
 ==== Execute a command script
 
-Create a file and put the same instructions as above in it, then execute *zabbysh*:
+To execute a script non interactively create a file and put the same
+instructions as above in it then execute *zabbysh*:
 
-    # zabbysh --file my_zabbix_commands.txt
+    # zabbysh my_zabbix_commands.zby
+
+You can even create auto-executable scripts! Just add "<tt>#!/usr/bin/env zabbysh</tt>"
+on the first line of the script and make it executable with "<tt>chmod +x my_zabby_commands.zby</tt>".
+
+For example create the script "my_zabbix_command.zby":
+
+    #!/usr/bin/env zabbysh
+    #
+    # Zabby configuration
+    set :server => "https://monitoring.example.com"
+    set :user => "api_user"
+    set :password => "s3cr3t"
+    set :proxy_host => "http://10.10.10.10"
+    set :proxy_user => "john"
+    set :proxy_password => "D0e"
+    login
+
+    hosts = Host.get "filter" => { "host" => "monitor.example.com" }, "output" => "extend"
+    h = hosts.first
+    puts "Host #{h['host']} has IP address #{h['ip']}"
+
+    exit 0
+
+Now to execute the script you just have to type:
+
+    # ./my_zabbix_commands.zby
+
+=== API use
+
+The barebone API can be used in Ruby like this:
+
+    require "rubygems"
+    require "zabby"
+    require "pp"
+
+    z = Zabby.init do
+      set :server => "https://monitoring.example.com"
+      set :user => "api_user"
+      set :password => "s3cr3t"
+      set :proxy_host => "http://10.10.10.10"
+      set :proxy_user => "john"
+      set :proxy_password => "D0e"
+      login
+    end
+
+    pp z.run { Host.get "filter" => { "host" => "master.example.com" } }
+    pp z.run { Item.get "host" => "master.example.com", "output" => "shorten" }
+
+
+- The _server_, _user_ and _passord_ are necessary.
+- If you don't provide the path to the JSON-RPC script "/api_jsonrpc.php" is appended
+  to the URI automatically.
+- The <em>proxy_*</em> settings are optionnal.
 
 == Requirements
 
-- Ruby 1.8.5. IT BASICALLY RUNS ANYWHERE!
+- Ruby 1.8.5. <b>IT BASICALLY RUNS ANYWHERE!</b>
 - JSON library: 'json' or 'json_pure'
 - OptionParser
 - Readline (optionnal, used by the interactive shell)
@@ -142,7 +202,8 @@ Create a file and put the same instructions as above in it, then execute *zabbys
 
 == Contributing
 
-All contributions are welcome. You can either open a ticket on Github, send a pull request
+All contributions are welcome. You can either
+{open a ticket on Github}[https://github.com/Pragmatic-Source/zabby/issues], send a pull request
 with a patch or send an email to the author.
 
 == Author
@@ -154,6 +215,7 @@ Farzad FARID mailto:ffarid@pragmatic-source.com
 - Jean-Hadrien Chabran (jhchabran): Advices on code design.
 - Nicolas Blanco (slainer68): Advices on code design and Triple Facepalming after reading other Ruby/Zabbix code.
 - Renaud Chaput (renchap): For suggesting the "zabby" name.
+- Folks on the irc channel #rubyonrails.fr@Freenode
 
 === Sources of inspiration
 

data/bin/zabbyrb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 # This is an experimental Zabby Shell based on IRB. It is still buggy and the code

data/bin/zabbysh

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 
@@ -49,7 +49,8 @@ EOT
   opts.on_tail("--version", "Show version") do
     puts <<EOT
 Zabby #{Zabby::VERSION}
-Copyright (c) 2011 Farzad FARID / Pragmatic Source
+Copyright (c) 2011-2012-2012 Farzad FARID / Pragmatic Source
+Home page: http://www.zabby.org/
 License: Simplified BSD
 EOT
     exit

data/lib/zabby.rb

@@ -1,6 +1,6 @@
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 require 'rubygems'
@@ -14,8 +14,9 @@ require 'pp'
 require 'zabby/version'
 require 'zabby/exceptions'
 require 'zabby/config'
-require 'zabby/zobject'
+require 'zabby/zclass'
 require 'zabby/connection'
+require 'zabby/shell_helpers'
 require 'zabby/runner'
 
 module Zabby

data/lib/zabby/config.rb

@@ -1,27 +1,33 @@
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 # Configuration setting
 module Zabby
   class Config
     SETTING_LIST = %w{server user password proxy_host proxy_user proxy_password}
-    
-    def initialize &block
-      setup(&block)
-    end
 
-    def setup &block
-      instance_eval(&block) if block_given?
+    # Initialize Zabby configuration settings
+    # @todo Anything to configure here?
+    def initialize
     end
 
+    # Display configuration variables
     def list
+    puts "Zabby configuration"
+    puts "==================="
       SETTING_LIST.each do |k|
         puts "#{k} = #{instance_variable_get("@#{k}")}"
       end
+      nil
     end
 
+    # Dynamic setter and getter methods for the configuration variables.
+    # @param [String] name Setting name, ending with "=" in case we are setting a value
+    # @param [Array] args Setting value
+    # @param [Proc] block Unused
+    # @return [Object] Return the value set
     def method_missing(name, *args, &block)
       name = name.to_s.gsub(/=$/, '')
       raise ConfigurationError.new("Unknown setting '#{name}'") if !SETTING_LIST.include?(name.to_s)

data/lib/zabby/connection.rb

@@ -1,6 +1,6 @@
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 module Zabby
@@ -71,6 +71,7 @@ module Zabby
     end
 
     # Perform an authenticated request
+    # @return [Object] The Zabbix response (Hash, Boolean, etc.) in JSON format.
     def perform_request(element, action, params)
       raise AuthenticationError.new("Not logged in") if !logged_in?
 
@@ -78,6 +79,9 @@ module Zabby
       query_zabbix_rpc(message)
     end
 
+    # Prepare a JSON request HTTP Post format
+    # @param [Hash] message A hash with all parameters for the Zabbix web service.
+    # @return [Net::HTTP::Post] Message ready to be POSTed.
     def request(message)
       req = Net::HTTP::Post.new(@request_path)
       req.add_field('Content-Type', 'application/json-rpc')
@@ -99,34 +103,41 @@ module Zabby
       http
     end
 
+    # Raise a Zabby exception
+    # @param [Hash] zabbix_response JSON formatted Zabbix response.
+    # @raise [Zabby::AuthenticationError] Authentication error.
+    # @raise [zabby::APIError] Generic Zabbix Web Services error.
+    def format_exception(zabbix_response)
+      error = zabbix_response['error']
+      error_message = error['message']
+      error_data = error['data']
+      error_code = error['code']
+
+      if error_data == "Login name or password is incorrect"
+        raise AuthenticationError.new(error_message, error_code, error_data)
+      else
+        raise APIError.new(error_message, error_code, error_data)
+      end
+    end
+
+    # Query the Zabbix Web Services and extract the JSON response.
+    # @param [Hash] message request in JSON format.
+    # @return [Object] The Zabbix response (Hash, Boolean, etc.) in JSON format.
+    # @raise [Zabby::ResponseCodeError] HTTP error.
     def query_zabbix_rpc(message)
       # Send the request!
-      response = http.request(request(message))
+      http_response = http.request(request(message))
 
-      if response.code != "200" then
-        raise ResponseCodeError.new("Response code from [#{@uri}] is #{response.code}): #{response.body}")
+      # Check for HTTP errors.
+      if http_response.code != "200"
+        raise ResponseCodeError.new("Error from #{@uri}", http_response.code, http_response.body)
       end
 
-      zabbix_response = JSON.parse(response.body)
-
-      #if not ( responce_body_hash['id'] == id ) then
-      # raise Zabbix::InvalidAnswerId.new("Wrong ID in zabbix answer")
-      #end
-
-      # Check errors in zabbix answer. If error exist - raise exception Zabbix::Error
-      if (error = zabbix_response['error']) then
-        error_message = error['message']
-        error_data = error['data']
-        error_code = error['code']
-
-        e_message = "Code: [" + error_code.to_s + "]. Message: [" + error_message +
-                "]. Data: [" + error_data + "]."
+      zabbix_response = JSON.parse(http_response.body)
 
-        if error_data == "Login name or password is incorrect"
-          raise AuthenticationError.new(e_message)
-        else
-          raise StandardError.new(e_message)
-        end
+      # Check for Zabbix errors.
+      if zabbix_response['error']
+        format_exception(zabbix_response)
       end
 
       zabbix_response['result']

data/lib/zabby/exceptions.rb

@@ -1,10 +1,26 @@
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 module Zabby
-  class ResponseCodeError < StandardError; end
-  class AuthenticationError < StandardError; end
+  class APIError < StandardError
+    attr_reader :code, :msg, :data
+
+    def initialize(msg, code = nil, data = nil)
+      @msg = msg
+      @code = code
+      @data = data
+    end
+
+    def message
+      text = "#{msg}"
+      text += ": #{data}" if data
+      text += " (code: #{code})" if code
+      text
+    end
+  end
+  class ResponseCodeError < APIError; end
+  class AuthenticationError < APIError; end
   class ConfigurationError < StandardError; end
-end
+end

data/lib/zabby/runner.rb

@@ -1,6 +1,6 @@
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 require 'singleton'
@@ -12,72 +12,23 @@ end
 
 
 module Zabby
+  # This is the main interpreter.
+  # Additional shell commands are defined in the ShellHelpers module.
   class Runner
     include Singleton
+    include ShellHelpers
 
     attr_reader :config, :connection
 
-    # Meta-create methods with the same name as the configuration settings.
-    # This way we can write:
-    #   set host "http://my.zabbix.server"
-    # instead of:
-    #   set :host => "http://my.zabbix.server"
-    # or "set host" instead of "set :host"
-    # All the created method does is return the second form which will be
-    # used by "set".
-    Zabby::Config::SETTING_LIST.each { |setting|
-      # TODO.rdoc: Ruby 1.8 does not support default values for block arguments..
-      # Writing "... do |value = nil|" would be more elegant.
-      define_method(setting) do |*args|
-        if args.empty?
-          setting.intern
-        else
-          { setting.intern => args.first }
-        end
-      end
-    }
-
-    # Create a method mapping a Zabbix object.
-    # @param [Symbol] name Zabbix Object name (:item, :host, etc.)
-    # @param [Array] zmethods The list of supported verbs
-    def self.create_zobject(name, zmethods)
-      define_method(name) do
-        @zobject[name] ||= Zabby::ZObject.new(name, zmethods)
-      end
-    end
-
-    # Create all Zabbix object types and theirs verbs.
-    create_zobject(:action, [ :create, :delete, :exists, :get, :update ])
-    create_zobject(:alert, [ :create, :delete, :get ])
-    create_zobject(:apiinfo, [ :version ])
-    create_zobject(:application, [ :create, :delete, :exists, :get, :massAdd, :update ])
-    create_zobject(:event, [ :acknowledge, :create, :delete, :get ])
-    create_zobject(:graph, [ :create, :delete, :exists, :get, :update ])
-    create_zobject(:graphitem, [ :get ])
-    create_zobject(:history, [ :delete, :get ])
-    create_zobject(:host, [ :create, :delete, :exists, :get, :update ])
-    create_zobject(:hostgroup, [ :create, :delete, :exists, :get, :massAdd, :massRemove, :massUpdate, :update ])
-    create_zobject(:image, [ :create, :delete, :exists, :get, :update ])
-    create_zobject(:item, [ :create, :delete, :exists, :get, :update ])
-    create_zobject(:maintenance, [ :create, :delete, :exists, :get, :update ])
-    create_zobject(:map, [ :create, :delete, :exists, :get, :update ])
-    create_zobject(:mediatype, [ :create, :delete, :get, :update ])
-    create_zobject(:proxy, [ :get ])
-    create_zobject(:screen, [ :create, :delete, :get, :update ])
-    create_zobject(:script, [ :create, :delete, :execute, :get, :update ])
-    create_zobject(:template, [ :create, :delete, :exists, :get, :massAdd, :massRemove, :massUpdate, :update ])
-    create_zobject(:trigger, [ :addDependencies, :create, :delete, :deleteDependencies, :exists, :get, :update ])
-    create_zobject(:user, [ :addMedia, :authenticate, :create, :delete, :deleteMedia, :get, :login, :logout, :update, :updateMedia, :updateProfile ])
-    create_zobject(:usergroup, [ :create, :delete, :exists, :get, :massAdd, :massRemove, :massUpdate, :update ])
-    create_zobject(:usermacro, [ :createGlobal, :deleteGlobal, :deleteHostMacro, :get, :massAdd, :massRemove, :massUpdate, :updateGlobal ])
-    create_zobject(:usermedia, [ :get ])
-
     def initialize &block
-      @config = Zabby::Config.new &block
+      @config = Zabby::Config.new
       @connection = Zabby::Connection.new
       @pure_binding = instance_eval "binding"
-      @zobject = {} # List of Zabbix Object
 
+      # Configure the application
+      run(&block) if block_given?
+
+      # Configure Readline for the shell, if available
       if Object.const_defined?(:Readline)
         @readline = true
         Readline.basic_word_break_characters = ""
@@ -86,45 +37,14 @@ module Zabby
 
 			  $last_res = nil
       else
+        # Without Readline the Zabby shell is not available.
         @readline = false
       end
     end
 
-    def setup &block
-      @config.setup &block
-    end
-
-    def set(key_value = nil)
-      if key_value.nil?
-        @config.list
-      elsif [ String, Symbol ].include?(key_value.class)
-        puts "#{key_value} = #{@config.send(key_value)}"
-      elsif key_value.instance_of? Hash
-        key = key_value.keys.first
-        value = key_value[key]
-        @config.send(key, value)
-      end
-    end
-
-    def login
-      @connection.login(@config)
-    end
-
-    def logout
-      @connection.logout
-    end
-
-    def logged_in?
-      @connection.logged_in?
-    end
-    alias_method :loggedin?, :logged_in?
-
-    def version
-      Zabby::VERSION
-    end
-
-    # @param command_file [String] Filename containing commands to execute.
-    # @param block [Proc] A block containing commands to execute.
+    # Execute script file and/or instruction block
+    # @param [String] command_file Filename containing commands to execute.
+    # @param [Proc] block A block containing commands to execute.
     def run(command_file = nil, &block)
       unless command_file.nil?
         commands = File.read(command_file)
@@ -137,9 +57,12 @@ module Zabby
     def shell
       raise RuntimeError.new("Shell cannot run because 'readline' is missing.") if !@readline
 
-      puts "Zabby Shell #{Zabby::VERSION}"
-      puts
-      puts "** This is a simple irb like Zabbix Shell. Multiline commands do not work for e.g. **"
+      puts <<HEADER
+Zabby Shell #{Zabby::VERSION}
+
+** This is a simple irb like Zabbix Shell. Multiline commands do not work for e.g. **
+Type "help" for online documentation.
+HEADER
       loop do
         cmd = Readline.readline('zabby> ')
 
@@ -154,7 +77,7 @@ module Zabby
     private
 
     # Run a single command.
-    # @param cmd [String] A command to execute in the object's context.
+    # @param [String] cmd A command to execute in the object's context.
     def execute(cmd)
       res = eval(cmd, @pure_binding)
       $last_res = res
@@ -167,9 +90,13 @@ module Zabby
       end
     end
 
+    # Print a single command's output on the screen using "inspect" if necessary.
+    # @param [Object] res Result object to display
     def print_result(res)
       if res.kind_of? String
         puts res
+      elsif res.nil?
+        # Do not print nil values
       else
         puts "=> #{res.inspect}"
       end

data/lib/zabby/shell_helpers.rb

@@ -0,0 +1,102 @@
+# -*- encoding: utf-8 -*-
+# Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
+# License:: Simplified BSD License
+
+module Zabby
+  # Useful helper methods for the Zabbix Shell. Methods added to this module
+  # are available in the scripting language and commande line.
+  # The following instance variable should be available to helper methods:
+  # - @config: Zabby::Config instance
+  # - @connection: Zabby::Connection instance
+  module ShellHelpers
+    # Documentation for helpers.
+    # Each helper method definition must be preceded by a call to "desc" and a short
+    # online help for the method.
+    @helpers_doc = {}
+    @last_doc = nil
+
+    # Save the documentation for a method about to be defined.
+    # @param text [String] Documentation of the method following the call to "desc"
+    def self.desc(text)
+      @last_doc = text
+    end
+
+    # Push helper documentation for the method just defined in a hash.
+    # @param [Symbol] method Helper method to document
+    # @todo Display functions in alphabetical or arbitrary order.
+    def self.method_added(method)
+      if @last_doc.nil?
+        @helpers_doc[method.id2name] = "** UNDOCUMENTED FUNCTION **"
+      else
+        @helpers_doc[method.id2name] = @last_doc
+        @last_doc = nil
+      end
+    end
+
+    # Show the Shell helpers documentation
+    def self.show_helpers_doc
+      help = <<EOT
+Available commands:
+==================
+
+EOT
+      @helpers_doc.each do |name, text|
+        help += name + ":\n"
+        help += '-' * name.size + "\n"
+        help += text + "\n\n"
+      end
+      help
+    end
+
+    desc %q{Set or query Zabby parameters.
+- "set" without argument displays all parameters.
+- "set <param>" shows the value of <param>
+- "set <param> => <value>" set <param> to <value>}
+    def set(key_value = nil)
+      if key_value.nil?
+        @config.list
+      elsif [ String, Symbol ].include?(key_value.class)
+        puts "#{key_value} = #{@config.send(key_value)}"
+      elsif key_value.instance_of? Hash
+        key = key_value.keys.first
+        value = key_value[key]
+        @config.send(key, value)
+      end
+    end
+
+    desc %q{Login to the Zabbix server.
+The parameters 'server', 'user' and 'password' must be defined.}
+    def login
+      @connection.login(@config)
+    end
+
+    desc 'Logout from the Zabbix server'
+    def logout
+      @connection.logout
+    end
+
+    desc 'Return true if we are connected to the Zabbix server, false otherwise.'
+    def logged_in?
+      @connection.logged_in?
+    end
+
+    desc 'Alias for "logged_in?".'
+    alias_method :loggedin?, :logged_in?
+
+    desc 'Show Zabby version.'
+    def version
+      Zabby::VERSION
+    end
+
+    desc 'Return the list of available Zabbix Classes (object types).'
+    def zabbix_classes
+      Zabby::ZClass.zabbix_classes
+    end
+
+    desc 'Show this help text.'
+    def help
+      puts Zabby::ShellHelpers.show_helpers_doc
+    end
+  end
+end

data/lib/zabby/version.rb

@@ -1,8 +1,8 @@
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 module Zabby
-  VERSION = "0.0.5"
+  VERSION = "0.1.0"
 end

data/lib/zabby/zclass.rb

@@ -0,0 +1,193 @@
+# -*- encoding: utf-8 -*-
+# Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
+# License:: Simplified BSD License
+
+module Zabby
+  # Create Zabbix classes as provided by the Zabbix API
+  module ZClass
+    # List of available Zabbix classes
+    @zabbix_classes = []
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      # Keep a list of Zabbix classes
+      @zabbix_classes << base.name.gsub(/^.*::/, '')
+    end
+
+    # Return the list of Zabbix classes
+    # @return [Array] List of Zabbix classes
+    def self.zabbix_classes
+      @zabbix_classes
+    end
+
+    module ClassMethods
+      # List of valid Web Service methods for the current Zabbix Object
+      attr_reader :zmethods
+
+      # Name of the current class without the namespace
+      # @return [String]
+      # @example
+      #   Zabby::Host.object_name => "host"
+      def object_name
+        @object_name ||= self.name.gsub(/^.*::/, '').downcase
+      end
+
+      # Add the list of Web Service methods to the current class.
+      # @param [Array] zmethods Method names
+      # @example
+      #   class Host
+      #     include ZClass
+      #     add_zmethods :create, :delete, :exists, :get, :update
+      #   end
+      def add_zmethods(*zmethods)
+        @zmethods = zmethods.map { |f| f.to_sym }
+      end
+
+      # Simulate methods on the object and call the Zabbix Web Service ("host.get", "item.create", etc.).
+      # See http://www.zabbix.com/documentation/1.8/api for the API documentation.
+      # @param [String] zmethod Name of the Web Service methods
+      # @param [Array] args Method arguments
+      # @param [Proc] block Unused
+      # @raise [NoMethodError] Raised on invalid method names.
+      def method_missing(zmethod, *args, &block)
+        if @zmethods.include? zmethod
+          Zabby::Runner.instance.connection.perform_request(object_name, zmethod, args.first)
+        else
+          super
+        end
+      end
+
+      # Human representation of the Zabbix Class
+      # @return [String] Class representation
+      # @example
+      #   Host.inspect => "<Zabbix Object 'host', methods: create, delete, exists, get, update>"
+      def inspect
+        "<Zabbix Object '#{object_name}', methods: #{@zmethods.join(', ')}>"
+      end
+    end
+  end
+
+  # Create all Zabbix object types and theirs methods.
+
+  class Action
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :update
+  end
+
+  class Alert
+    include ZClass
+    add_zmethods :create, :delete, :get
+  end
+
+  class APIInfo
+    include ZClass
+    add_zmethods :version
+  end
+
+  class Application
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :massAdd, :update
+  end
+
+  class Event
+    include ZClass
+    add_zmethods :acknowledge, :create, :delete, :get
+  end
+
+  class Graph
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :update
+  end
+
+  class Graphitem
+    include ZClass
+    add_zmethods :get
+  end
+
+  class History
+    include ZClass
+    add_zmethods :delete, :get
+  end
+
+  class Host
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :update
+  end
+
+  class Hostgroup
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :massAdd, :massRemove, :massUpdate, :update
+  end
+
+  class Image
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :update
+  end
+
+  class Item
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :update
+  end
+
+  class Maintenance
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :update
+  end
+
+  class Map
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :update
+  end
+
+  class Mediatype
+    include ZClass
+    add_zmethods :create, :delete, :get, :update
+  end
+
+  class Proxy
+    include ZClass
+    add_zmethods :get
+  end
+
+  class Screen
+    include ZClass
+    add_zmethods :create, :delete, :get, :update
+  end
+
+  class Script
+    include ZClass
+    add_zmethods :create, :delete, :execute, :get, :update
+  end
+
+  class Template
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :massAdd, :massRemove, :massUpdate, :update
+  end
+
+  class Trigger
+    include ZClass
+    add_zmethods :addDependencies, :create, :delete, :deleteDependencies, :exists, :get, :update
+  end
+
+  class User
+    include ZClass
+    add_zmethods :addMedia, :authenticate, :create, :delete, :deleteMedia, :get, :login, :logout, :update, :updateMedia, :updateProfile
+  end
+
+  class Usergroup
+    include ZClass
+    add_zmethods :create, :delete, :exists, :get, :massAdd, :massRemove, :massUpdate, :update
+  end
+
+  class Usermacro
+    include ZClass
+    add_zmethods :createGlobal, :deleteGlobal, :deleteHostMacro, :get, :massAdd, :massRemove, :massUpdate, :updateGlobal
+  end
+
+  class Usermedia
+    include ZClass
+    add_zmethods :get
+  end
+
+end

data/zabby.gemspec

@@ -1,6 +1,6 @@
 # -*- encoding: utf-8 -*-
 # Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
 # License:: Simplified BSD License
 
 $:.push File.expand_path("../lib", __FILE__)
@@ -30,4 +30,5 @@ service.}
   s.add_development_dependency "bundler", ">= 1.0.0"
   s.add_development_dependency "rspec", ">= 2.0.0"
   s.add_development_dependency "rake", ">= 0.8.7"
+  s.add_development_dependency "yard"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: zabby
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 27
   prerelease: 
   segments: 
   - 0
+  - 1
   - 0
-  - 5
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors: 
 - Farzad FARID
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-01-05 00:00:00 Z
+date: 2012-03-14 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
@@ -79,6 +79,20 @@ dependencies:
         version: 0.8.7
   type: :development
   version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
 description: |-
   Zabby is a Zabby API and CLI. It provides a provisioning tool for
   creating, updating and querying Zabbix objects (hosts, items, triggers, etc.) through the web
@@ -109,8 +123,9 @@ files:
 - lib/zabby/connection.rb
 - lib/zabby/exceptions.rb
 - lib/zabby/runner.rb
+- lib/zabby/shell_helpers.rb
 - lib/zabby/version.rb
-- lib/zabby/zobject.rb
+- lib/zabby/zclass.rb
 - spec/spec_helper.rb
 - zabby.gemspec
 homepage: http://zabby.org/

data/lib/zabby/zobject.rb

@@ -1,31 +0,0 @@
-# -*- encoding: utf-8 -*-
-# Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
-# Copyright:: Copyright (c) 2011 Farzad FARID
-# License:: Simplified BSD License
-
-module Zabby
-  # Definition of the Zabbix Objects as provided by the Zabbix API
-  class ZObject
-    attr_reader :zname, :zmethods
-
-    # Define the Zabbix object name and associated methods
-    #
-    # @param [String] zname Zabbix Object name
-    # @param [Array] zmethods List of associated methods
-    def initialize(zname, zmethods)
-      @zname = zname
-      @zmethods = zmethods.map { |f| f.to_sym }
-    end
-
-    # Simulate methods on the object.
-    # For example: "host.get", "item.create"..
-    # The instance variable @zmethods is the list of valid methods.
-    def method_missing(zmethod, *args, &block)
-      if @zmethods.include? zmethod
-        Zabby::Runner.instance.connection.perform_request(@zname, zmethod, args.first)
-      else
-        super
-      end
-    end
-  end
-end