haveapi-client 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1f73740e620eeb403f3cdec3491598f9b48bcfc4
-  data.tar.gz: 3e4d8544316b4a47f948f573de365055021725fc
+  metadata.gz: 8c2c9e15337f0d495ac86049fee2e76cf545957c
+  data.tar.gz: 9eaf5f13ad4c6d128a55b7efb3795b2840dd64dd
 SHA512:
-  metadata.gz: 037eee5721e264c732be091ee8fea13e0c96c63e824c8422b4a31e21b503f7e5be3e27114984e71dca37c7237f6c3a8f9392a7206bdd9e381757c0c42fac8d86
-  data.tar.gz: c891d03e167e84a0d7103498a65bfcee3146094de96124d998ea5a4d74d182001dc6609c6e0a58d6d39e327a52e04580cc36662287b8633d8e38345e200f88a0
+  metadata.gz: 7fa14b35b737f100c15ae7c8091e2abb18f9f8b3286ac006e723484f2c967dbb9f0683606fc7cda477c6cbc7d34ed9aabbe9bba83200a01608c3a9b04c825589
+  data.tar.gz: b3ac301b6d97864c2a1ddf909a121efb23aa5ef419be24f9e7ab0a436c16085f156f23ebaff4ed394f67c12665685323c70a7e3e95e147f672a768dc589130c7

data/README.md

@@ -17,8 +17,7 @@ Or install it yourself as:
 
     $ gem install haveapi-client
 
-## Usage
-### CLI
+## CLI
     $ haveapi-cli -h
     Usage: haveapi-cli [options] <resource> <action> [objects ids] [-- [parameters]]
         -u, --api URL                    API URL
@@ -28,50 +27,72 @@ Or install it yourself as:
                                          List available authentication methods
             --list-resources [VERSION]   List all resource in API version
             --list-actions [VERSION]     List all resources and actions in API version
+            --version VERSION            Use specified API version
         -r, --raw                        Print raw response as is
         -s, --save                       Save credentials to config file for later use
         -v, --[no-]verbose               Run verbosely
+            --client-version             Show client version
         -h, --help                       Show this message
   
 Using the API example from
-[HaveAPI README](https://github.com/vpsfreecz/haveapi/blob/master/README.md#example),
+[HaveAPI README](https://github.com/vpsfreecz/haveapi#example),
 users would be listed with:
 
-    $ haveapi-cli --url https://your.api.tld --auth basic --username yourname --password yourpassword user index
+    $ haveapi-cli --url https://your.api.tld --auth basic --username yourname --password yourpassword user list
     
 Nested resources and object IDs:
 
-    $ haveapi-cli --url https://your.api.tld --auth basic --username yourname --password yourpassword user.invoice index 10
+    $ haveapi-cli --url https://your.api.tld --auth basic --username yourname --password yourpassword user.invoice list 10
 
 where `10` is user ID.
 
 User credentials can be saved to a config:
 
-    $ haveapi-cli --url https://your.api.tld --auth basic --username yourname --password yourpassword --save user index
+    $ haveapi-cli --url https://your.api.tld --auth basic --username yourname --password yourpassword --save user list
     
 When saved, they don't have to be specified as command line options:
 
-    $ haveapi-cli --url https://your.api.tld user index
+    $ haveapi-cli --url https://your.api.tld user list
  
-### Client library
+List options specific to authentication methods:
+
+    $ haveapi-cli --url https://your.api.tld --auth basic -h
+    $ haveapi-cli --url https://your.api.tld --auth token -h
+ 
+List action parameters with examples:
+
+    $ haveapi-cli --url https://your.api.tld user new -h
+
+Provide action parameters (notice the ``--`` separator):
+
+    $ haveapi-cli --url https://your.api.tld user new -- --login mylogin --full-name "My Full Name" --role user
+
+ 
+## Client library
 ```ruby
 require 'haveapi/client'
 
 api = HaveAPI::Client::Client.new('https://your.api.tld')
 api.authenticate(:basic, user: 'yourname', password: 'yourpassword')
 
-response = api.user.index
-p response.ok?
-p response.response
+api.user.list.each do |user|
+    puts user.login
+end
 
-p api.user(10).invoice
-p api.user(10).delete
-p api.user(10).delete!
-p api.user.delete(10)
+user = api.user.find(10)
+p user.invoice
+user.destroy
 
 p api.user.create({
   login: 'mylogin',
   full_name: 'Very Full Name',
   role: 'user'
 })
+
+user = api.user.new
+user.login = 'mylogin'
+user.full_name = 'Very Full Name'
+user.role = 'user'
+user.save
+p user.id
 ```

data/haveapi-client.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'rest_client', '~> 1.7.3'
   spec.add_runtime_dependency 'json', '~> 1.8.1'
   spec.add_runtime_dependency 'highline', '~> 1.6.21'
-  spec.add_runtime_dependency 'table_print', '~> 1.5.1'
+  spec.add_runtime_dependency 'table_print', '~> 1.5.3'
 end

data/lib/haveapi/cli/authentication/token.rb

@@ -15,9 +15,15 @@ module HaveAPI::CLI::Authentication
         @token = t
       end
 
-      opts.on('--token-validity SECONDS', Integer,
-              'How long will token be valid in seconds, 0 for forever') do |s|
-        @validity = s
+      opts.on('--token-lifetime LIFETIME',
+              %i(fixed renewable_manual renewable_auto permanent),
+              'Token lifetime, defaults to renewable_auto') do |l|
+        @lifetime = l
+      end
+
+      opts.on('--token-interval SECONDS', Integer,
+              'How long will token be valid in seconds') do |s|
+        @interval = s
       end
 
       opts.on('--new-token', 'Request new token') do
@@ -49,7 +55,8 @@ module HaveAPI::CLI::Authentication
           user: @user,
           password: @password,
           token: @token,
-          validity: @validity,
+          lifetime: @lifetime || :renewable_auto,
+          interval: @interval,
           valid_to: @valid_to,
           via: @via
       })
@@ -58,7 +65,7 @@ module HaveAPI::CLI::Authentication
     def save
       super.update({
                        via: @via,
-                       validity: @validity
+                       interval: @interval
                    })
     end
   end

data/lib/haveapi/cli/cli.rb

@@ -24,7 +24,7 @@ module HaveAPI
         @config = read_config || {}
         args, @opts = options
 
-        @api = HaveAPI::Client::Communicator.new(api_url)
+        @api = HaveAPI::Client::Communicator.new(api_url, @opts[:version])
         @api.identity = $0.split('/').last
 
         if @action
@@ -46,10 +46,7 @@ module HaveAPI
           exit(true)
         end
 
-        action = translate_action(args[1].to_sym)
-
-        action = @api.get_action(resources, action, args[2..-1])
-
+        action = @api.get_action(resources, args[1].to_sym, args[2..-1])
         action.update_description(@api.describe_action(action)) if authenticate(action)
 
         @input_params = parameters(action)
@@ -63,15 +60,18 @@ module HaveAPI
 
           if ret[:status]
             format_output(action, ret[:response])
+
           else
             warn "Action failed: #{ret[:message]}"
 
-            if ret[:errors].any?
+            if ret[:errors] && ret[:errors].any?
               puts 'Errors:'
               ret[:errors].each do |param, e|
                 puts "\t#{param}: #{e.join('; ')}"
               end
             end
+
+            print_examples(action)
           end
 
         else
@@ -119,6 +119,10 @@ module HaveAPI
             @action = [:list_actions, v && v.sub(/^v/, '')]
           end
 
+          opts.on('--version VERSION', 'Use specified API version') do |v|
+            options[:version] = v
+          end
+
           opts.on('-r', '--raw', 'Print raw response as is') do
             options[:raw] = true
           end
@@ -131,6 +135,10 @@ module HaveAPI
             options[:verbose] = v
           end
 
+          opts.on('--client-version', 'Show client version') do
+            @action = [:show_version]
+          end
+
           opts.on('-h', '--help', 'Show this message') do
             options[:help] = true
           end
@@ -178,8 +186,11 @@ module HaveAPI
         if @opts[:help]
           puts @global_opt.help
           puts ''
+          puts 'Action description:'
+          puts action.description, "\n"
           print 'Action parameters:'
           puts @action_opt.help
+          print_examples(action)
           exit
         end
 
@@ -204,56 +215,46 @@ module HaveAPI
         ret
       end
 
-      def translate_action(action)
-        tr = {
-            list: :index,
-            new: :create,
-            change: :update
-        }
-
-        if tr.has_key?(action)
-          return tr[action]
-        end
-
-        action
-      end
-
       def list_versions
-        desc = @api.describe_api
+        desc = @api.available_versions
 
         desc[:versions].each do |v, _|
           next if v == :default
 
           v_int = v.to_s.to_i
 
-          puts "#{v_int == desc[:default_version] ? '*' : ' '} v#{v}"
+          puts "#{v_int == desc[:default] ? '*' : ' '} v#{v}"
         end
       end
 
       def list_auth(v=nil)
-        desc = @api.describe_api
+        desc = @api.describe_api(v)
 
-        desc[:versions][(v && v.to_sym) || desc[:default_version].to_s.to_sym][:authentication].each_key do |auth|
+        desc[:authentication].each_key do |auth|
           puts auth if Cli.auth_methods.has_key?(auth)
         end
       end
 
       def list_resources(v=nil)
-        desc = @api.describe_api
+        desc = @api.describe_api(v)
 
-        desc[:versions][(v && v.to_sym) || desc[:default_version].to_s.to_sym][:resources].each do |resource, children|
+        desc[:resources].each do |resource, children|
           nested_resource(resource, children, false)
         end
       end
 
       def list_actions(v=nil)
-        desc = @api.describe_api
+        desc = @api.describe_api(v)
 
-        desc[:versions][(v && v.to_sym) || desc[:default_version].to_s.to_sym][:resources].each do |resource, children|
+        desc[:resources].each do |resource, children|
           nested_resource(resource, children, true)
         end
       end
 
+      def show_version
+        puts HaveAPI::Client::VERSION
+      end
+
       def describe_resource(path)
         desc = @api.describe_resource(path)
 
@@ -295,7 +296,14 @@ module HaveAPI
         end
       end
 
-      def format_output(action, response)
+      def print_examples(action)
+        unless action.examples.empty?
+          puts "\nExamples:\n"
+          ExampleFormatter.format_examples(self, action)
+        end
+      end
+
+      def format_output(action, response, out = $>)
         if @opts[:raw]
           puts response
           return
@@ -303,15 +311,23 @@ module HaveAPI
 
         return if response.empty?
 
+        tp.set :io, out
+
         namespace = action.namespace(:output).to_sym
 
-        case action.layout.to_sym
-          when :list
+        case action.output_layout.to_sym
+          when :object_list, :hash_list
             cols = []
 
             action.params.each do |name, p|
               if p[:type] == 'Resource'
-                cols << {name => {display_method: ->(r) { r[name] && r[name][p[:value_label].to_sym] } }}
+                cols << {
+                    name => {
+                      display_method: ->(r) {
+                       r[name] && "#{r[name][p[:value_label].to_sym]} (##{r[name][p[:value_id].to_sym]})"
+                      }
+                    }
+                }
               else
                 cols << name
               end
@@ -320,19 +336,19 @@ module HaveAPI
             tp response[namespace], *cols
 
 
-          when :object
+          when :object, :hash
             response[namespace].each do |k, v|
 
               if action.params[k][:type] == 'Resource'
-                puts "#{k}: #{v[action.params[k][:value_label].to_sym]}"
+                out << "#{k}: #{v[action.params[k][:value_label].to_sym]}\n"
               else
-                puts "#{k}: #{v}"
+                out << "#{k}: #{v}\n"
               end
             end
 
 
           when :custom
-            pp response[namespace]
+            PP.pp(response[namespace], out)
 
         end
       end

data/lib/haveapi/cli/example_formatter.rb

@@ -0,0 +1,43 @@
+module HaveAPI::CLI
+  module ExampleFormatter
+    def self.format_examples(cli, action, out = $>)
+      action.examples.each do |example|
+        out << ' > ' << example[:title] << ":\n" unless example[:title].empty?
+
+        # request
+        out << "$ #{$0} #{action.resource_path.join('.')} #{action.name}"
+
+        params = example[:request][action.namespace(:input).to_sym]
+
+        if params
+          out << ' --' unless params.empty?
+
+          params.each do |k, v|
+            out << ' ' << example_param(k, v, action.param_description(:input, k))
+          end
+        end
+
+        out << "\n"
+
+        # response
+        cli.format_output(action, example[:response], out)
+      end
+    end
+
+    def self.example_param(name, value, desc)
+      option = name.to_s.dasherize
+
+      case desc[:type]
+        when 'Boolean'
+          value ? "--#{option}" : "--no-#{option}"
+
+        else
+          "--#{option} #{example_value(value)}"
+      end
+    end
+
+    def self.example_value(v)
+      (v.is_a?(String) && (v.empty? || v.index(' '))) ? "\"#{v}\"" : v
+    end
+  end
+end

data/lib/haveapi/client.rb

@@ -1,2 +1,3 @@
 require 'require_all'
+require 'date'
 require_rel 'client'

data/lib/haveapi/client/action.rb

@@ -1,6 +1,8 @@
 module HaveAPI
   module Client
     class Action
+      attr_accessor :resource_path
+
       def initialize(api, name, spec, args)
         @api = api
         @name = name
@@ -24,6 +26,18 @@ module HaveAPI
         @spec[:auth]
       end
 
+      def aliases(include_name = false)
+        if include_name
+          [@name] + @spec[:aliases]
+        else
+          @spec[:aliases]
+        end
+      end
+
+      def description
+        @spec[:description]
+      end
+
       def input
         @spec[:input]
       end
@@ -32,8 +46,12 @@ module HaveAPI
         @spec[:output]
       end
 
-      def layout
-        @spec[:output][:layout]
+      def input_layout
+        @spec[:input][:layout].to_sym
+      end
+
+      def output_layout
+        @spec[:output][:layout].to_sym
       end
 
       def structure
@@ -44,10 +62,22 @@ module HaveAPI
         @spec[src][:namespace]
       end
 
+      def examples
+        @spec[:examples]
+      end
+
+      def input_params
+        @spec[:input][:parameters]
+      end
+
       def params
         @spec[:output][:parameters]
       end
 
+      def param_description(dir, name)
+        @spec[dir][:parameters][name]
+      end
+
       def url
         @spec[:url]
       end
@@ -77,6 +107,11 @@ module HaveAPI
         apply_args(args)
       end
 
+      def provide_url(url, help)
+        @prepared_url = url
+        @prepared_help = help
+      end
+
       def update_description(spec)
         @spec = spec
       end

data/lib/haveapi/client/authentication/token.rb

@@ -36,7 +36,11 @@ module HaveAPI::Client::Authentication
     protected
     def request_token
       a = HaveAPI::Client::Action.new(@communicator, :request, @desc[:resources][:token][:actions][:request], [])
-      ret = a.execute({login: @opts[:user], password: @opts[:password], validity: @opts[:validity] || 300})
+      ret = a.execute({
+                          login: @opts[:user],
+                          password: @opts[:password],
+                          lifetime: @opts[:lifetime],
+                          interval: @opts[:interval] || 300})
 
       raise AuthenticationFailed.new('bad username or password') unless ret[:status]
 

data/lib/haveapi/client/client.rb

@@ -1,14 +1,34 @@
 require 'pp'
 
+# HaveAPI client interface.
 class HaveAPI::Client::Client
   attr_reader :resources
 
-  def initialize(url, v=nil, identity: 'haveapi-client')
+  # Create an instance of client.
+  # The client by default uses the default version of the API.
+  # API is asked for description only when needed or by calling #setup.
+  # +identity+ is sent in each request to the API in User-Agent header.
+  def initialize(url, v = nil, identity: 'haveapi-client')
+    @setup = false
     @version = v
     @api = HaveAPI::Client::Communicator.new(url, v)
     @api.identity = identity
+  end
+
+  # Get the description from the API now.
+  def setup(v = :_nil)
+    @version = v unless v == :_nil
+    setup_api
+  end
 
-    setup_api(@api.describe_api)
+  # Returns a list of API versions.
+  # The return value is a hash, e.g.:
+  #   {
+  #     versions: [1, 2, 3],
+  #     default: 3
+  #   }
+  def versions
+    @api.available_versions
   end
 
   # See Communicator#authenticate.
@@ -16,14 +36,29 @@ class HaveAPI::Client::Client
     @api.authenticate(*args)
   end
 
-  private
-  def setup_api(description)
-    v = @version || description[:default_version]
+  # Initialize the client if it is not yet initialized and call the resource
+  # if it exists.
+  def method_missing(symbol, *args)
+    return super(symbol, *args) if @setup
+
+    setup_api
+
+    if @resources.include?(symbol)
+      method(symbol).call(*args)
 
+    else
+      super(symbol, *args)
+    end
+  end
+
+  private
+  # Get the description from the API and setup resource methods.
+  def setup_api
+    @description = @api.describe_api(@version)
     @resources = {}
 
-    description[:versions][v.to_s.to_sym][:resources].each do |name, desc|
-      r = HaveAPI::Client::Resource.new(@api, name)
+    @description[:resources].each do |name, desc|
+      r = HaveAPI::Client::Resource.new(self, @api, name)
       r.setup(desc)
 
       define_singleton_method(name) do |*args|
@@ -35,5 +70,7 @@ class HaveAPI::Client::Client
 
       @resources[name] = r
     end
+
+    @setup = true
   end
 end

data/lib/haveapi/client/communicator.rb

@@ -25,6 +25,7 @@ module HaveAPI
         @rest = RestClient::Resource.new(@url)
         @version = v
         @identity = 'haveapi-client-ruby'
+        @desc = {}
       end
 
       # Authenticate user with selected +auth_method+.
@@ -32,7 +33,6 @@ module HaveAPI
       # +options+ are specific for each authentication provider.
       def authenticate(auth_method, options = {})
         desc = describe_api(@version)
-        desc = desc[:versions][desc[:default_version].to_s.to_sym] unless @version
 
         @auth = self.class.auth_methods[auth_method].new(self, desc[:authentication][auth_method], options)
         @rest = @auth.resource || @rest
@@ -42,13 +42,18 @@ module HaveAPI
         @auth.save
       end
 
+      def available_versions
+        description_for(path_for, {describe: :versions})
+      end
+
       def describe_api(v=nil)
-        description_for(path_for(v))
+        return @desc[v] if @desc.has_key?(v)
+
+        @desc[v] = description_for(path_for(v), v.nil? ? {describe: :default} : {})
       end
 
       def describe_resource(path)
-        api = describe_api
-        tmp = api[:versions][ api[:default_version].to_s.to_sym ]
+        tmp = describe_api(@version)
 
         path.each do |r|
           tmp = tmp[:resources][r.to_sym]
@@ -64,10 +69,7 @@ module HaveAPI
       end
 
       def get_action(resources, action, args)
-        @spec ||= describe_api(@version)
-        @spec = @spec[:versions][@spec[:default_version].to_s.to_sym] unless @version
-
-        tmp = @spec
+        tmp = describe_api(@version)
 
         resources.each do |r|
           tmp = tmp[:resources][r.to_sym]
@@ -77,8 +79,19 @@ module HaveAPI
 
         a = tmp[:actions][action]
 
+        unless a # search in aliases
+           tmp[:actions].each do |_, v|
+            if v[:aliases].include?(action.to_s)
+              a = v
+              break
+            end
+          end
+        end
+
         if a
-          Action.new(self, action, a, args)
+          obj = Action.new(self, action, a, args)
+          obj.resource_path = resources
+          obj
         else
           false
         end
@@ -87,9 +100,19 @@ module HaveAPI
       def call(action, params, raw: false)
         args = []
         input_namespace = action.namespace(:input)
+        meta = nil
+
+        if params.is_a?(Hash) && params[:meta]
+          meta = params[:meta]
+          params.delete(:meta)
+        end
 
         if %w(POST PUT).include?(action.http_method)
-          args << {input_namespace => params}.update(@auth.request_payload).to_json
+          ns = {input_namespace => params}
+          ns[:_meta] = meta if meta
+          ns.update(@auth.request_payload)
+
+          args << ns.to_json
           args << {content_type: :json, accept: :json, user_agent: @identity}.update(@auth.request_headers)
 
         elsif %w(GET DELETE).include?(action.http_method)
@@ -99,6 +122,11 @@ module HaveAPI
             get_params["#{input_namespace}[#{k}]"] = v
           end
 
+          meta.each do |k, v|
+            get_params["_meta[#{k}]"] = v # FIXME: read _meta namespace from the description
+
+          end if meta
+
           args << {params: get_params.update(@auth.request_url_params), accept: :json, user_agent: @identity}.update(@auth.request_headers)
         end
 
@@ -142,11 +170,11 @@ module HaveAPI
           ret
         end
 
-        def description_for(path)
+        def description_for(path, query_params={})
           parse(@rest[path].get_options({
-              params: @auth.request_payload.update(@auth.request_url_params),
+              params: @auth.request_payload.update(@auth.request_url_params).update(query_params),
               user_agent: @identity
-          }.update(@auth.request_headers)))
+          }.update(@auth.request_headers)))[:response]
         end
 
         def parse(str)

data/lib/haveapi/client/resource.rb

@@ -1,78 +1,136 @@
-class HaveAPI::Client::Resource
-  attr_reader :actions, :resources, :name
-  attr_accessor :prepared_args
-
-  def initialize(api, name)
-    @api = api
-    @name = name
-    @prepared_args = []
-  end
+module HaveAPI::Client
+  # An API resource.
+  class Resource
+    attr_reader :actions, :resources
+    attr_accessor :prepared_args
+
+    def initialize(client, api, name)
+      @client = client
+      @api = api
+      @name = name
+      @prepared_args = []
+    end
+
+    def setup(description)
+      @actions = {}
+      @resources = {}
 
-  def setup(description)
-    @actions = {}
-    @resources = {}
+      description[:actions].each do |name, desc|
+        action = HaveAPI::Client::Action.new(@api, name, desc, [])
+        define_action(action)
+        @actions[name] = action
+      end
 
-    description[:actions].each do |name, desc|
-      action = HaveAPI::Client::Action.new(@api, name, desc, [])
-      define_action(action)
-      @actions[name] = action
+      description[:resources].each do |name, desc|
+        r = HaveAPI::Client::Resource.new(@client, @api, name)
+        r.setup(desc)
+        define_resource(r)
+        @resources[name] = r
+      end
     end
 
-    description[:resources].each do |name, desc|
-      r = HaveAPI::Client::Resource.new(@api, name)
-      r.setup(desc)
-      define_resource(r)
-      @resources[name] = r
+    # Copy actions and resources from the +original+ resource
+    # and create methods for this instance.
+    def setup_from_clone(original)
+      original.actions.each_value do |action|
+        define_action(action)
+      end
+
+      original.resources.each_value do |resource|
+        define_resource(resource)
+      end
     end
-  end
 
-  def setup_from_clone(original)
-    original.actions.each_value do |action|
-      define_action(action)
+    def inspect
+      super
     end
 
-    original.resources.each_value do |resource|
-      define_resource(resource)
+    # Create a new instance of a resource. The created instance
+    # is not persistent until ResourceInstance#save is called.
+    def new
+      ResourceInstance.new(@client, @api, self, action: @actions[:create], persistent: false)
     end
-  end
 
-  private
-  def define_action(action)
-    define_singleton_method(action.name) do |*args|
-      all_args = @prepared_args + args
+    # Return resource name.
+    # Method is prefixed with an underscore to prevent name collision
+    # with ResourceInstance attributes.
+    def _name
+      @name
+    end
 
-      if action.unresolved_args?
-        all_args.delete_if do |arg|
-          break unless action.unresolved_args?
+    protected
+    # Define access/write methods for action +action+.
+    def define_action(action)
+      action.aliases(true).each do |name|
+        next unless define_method?(action, name)
 
-          action.provide_args(arg)
-          true
-        end
+        define_singleton_method(name) do |*args|
+          all_args = @prepared_args + args
 
-        if action.unresolved_args?
-          raise ArgumentError.new('One or more object ids missing')
-        end
-      end
+          if action.unresolved_args?
+            all_args.delete_if do |arg|
+              break unless action.unresolved_args?
 
-      all_args << {} if all_args.empty?
+              action.provide_args(arg)
+              true
+            end
 
-      HaveAPI::Client::Response.new(action, action.execute(*all_args))
+            if action.unresolved_args?
+              raise ArgumentError.new('One or more object ids missing')
+            end
+          end
+
+          if all_args.empty?
+            all_args << default_action_input_params(action)
+
+          elsif all_args.last.is_a?(Hash)
+            last = all_args.pop
+
+            all_args << default_action_input_params(action).update(last)
+          end
+
+          ret = Response.new(action, action.execute(*all_args))
+
+          raise ActionFailed.new(ret) unless ret.ok?
+
+          case action.output_layout
+            when :object
+              ResourceInstance.new(@client, @api, self, action: action, response: ret)
+
+            when :object_list
+              ResourceInstanceList.new(@client, @api, self, action, ret)
+
+            when :hash, :hash_list
+              ret
+
+            else
+              ret
+          end
+        end
+      end
     end
 
-    define_singleton_method("#{action.name}!".to_sym) do |*args|
-      ret = method(action.name).call(*args)
-      raise HaveAPI::Client::ActionFailed.new(ret) unless ret.ok?
+    # Called before defining a method named +name+ that will
+    # invoke +action+.
+    def define_method?(action, name)
+      return false if %i(new).include?(name.to_sym)
+      true
+    end
 
-      ret
+    # This method is called when an action is invoked.
+    # Override it to return a default hash of parameters to be sent to API.
+    # Used for example in ResourceInstance, which returns its instance attributes.
+    def default_action_input_params(action)
+      {}
     end
-  end
 
-  def define_resource(resource)
-    define_singleton_method(resource.name) do |*args|
-      tmp = resource.dup
-      tmp.prepared_args = @prepared_args + args
-      tmp.setup_from_clone(resource)
-      tmp
+    def define_resource(resource)
+      define_singleton_method(resource._name) do |*args|
+        tmp = resource.dup
+        tmp.prepared_args = @prepared_args + args
+        tmp.setup_from_clone(resource)
+        tmp
+      end
     end
   end
 end

data/lib/haveapi/client/resource_instance.rb

@@ -0,0 +1,201 @@
+module HaveAPI::Client
+  # Instance of an object from the API.
+  # An instance of this class may be in three states:
+  # - resolved/persistent - the instance was created by an action that retrieved
+  #   it from the API.
+  # - unresolved - this instance is an attribute of another instance that was resolved
+  #   and will be resolved when first accessed.
+  # - not persistent - created by Resource.new, the object was not yet sent to the API.
+  class ResourceInstance < Resource
+    def initialize(client, api, resource, action: nil, response: nil,
+                   resolved: false, meta: nil, persistent: true)
+      super(client, api, resource._name)
+
+      @action = action
+      @resource = resource
+      @resolved = resolved
+      @meta = meta
+      @persistent = persistent
+      @resource_instances = {}
+
+      if response
+        if response.is_a?(Hash)
+          @params = response
+
+        else
+          @response = response
+          @params = response.response
+        end
+
+        setup_from_clone(resource)
+        define_attributes
+      end
+
+      unless @persistent
+        setup_from_clone(resource)
+        define_implicit_attributes
+        define_attributes(@action.input_params)
+      end
+    end
+
+    def new
+      raise NoMethodError.new
+    end
+
+    # Invoke +create+ action if the object is not persistent,
+    # +update+ action if it is.
+    def save
+      if @persistent
+        method(:update).call
+
+      else
+        @action.provide_args
+        @response = Response.new(@action, @action.execute(attributes_for_api(@action)))
+
+        if @response.ok?
+          @params = @response.response
+          define_attributes
+
+        else
+          return nil
+        end
+
+        @persistent = true
+        self
+      end
+    end
+
+    # Call #save and raise ActionFailed if it fails.
+    def save!
+      raise ActionFailed.new(@response) if save.nil?
+      self
+    end
+
+    # Resolve the object (fetch it from the API) if it is not resolved yet.
+    def resolve
+      return self if @resolved
+
+      @action.provide_args(*@meta[:url_params])
+      @response = Response.new(@action, @action.execute({}))
+      @params = @response.response
+
+      setup_from_clone(@resource)
+      define_attributes
+
+      @resolved = true
+      self
+    end
+
+    # Return Response object which created this instance.
+    def api_response
+      @response
+    end
+
+    # Return a hash of all object attributes retrieved from the API.
+    def attributes
+      @params
+    end
+
+    def to_s
+      "<#{self.class.to_s}:#{object_id}:#{@resource._name}>"
+    end
+
+    protected
+    # Define access/writer methods for object attributes.
+    def define_attributes(params = nil)
+      (params || @action.params).each do |name, param|
+        case param[:type]
+          when 'Resource'
+            @resource_instances[name] = find_association(param, @params[name])
+
+            # id reader
+            ensure_method(:"#{name}_id") { @params[name][ param[:value_id].to_sym ] }
+
+            # id writer
+            ensure_method(:"#{name}_id=") { |id| @params[name][ param[:value_id].to_sym ] = id }
+
+            # value reader
+            ensure_method(name) do
+              @resource_instances[name] && @resource_instances[name].resolve
+            end
+
+            # value writer
+            ensure_method(:"#{name}=") do |obj|
+              @params[name][ param[:value_id].to_sym ] = obj.method(param[:value_id]).call
+              @params[name][ param[:value_label].to_sym ] = obj.method(param[:value_label]).call
+
+              @resource_instances[name] = obj
+            end
+
+          else
+            # reader
+            ensure_method(name) { @params[name] }
+
+            # writer
+            ensure_method(:"#{name}=") { |new_val| @params[name] = new_val }
+        end
+      end
+    end
+
+    # Define method +name+ with +block+ if it isn't defined yet.
+    def ensure_method(name, &block)
+      define_singleton_method(name, &block) unless respond_to?(name)
+    end
+
+    # Define nil references to resource attributes.
+    # Used only for not-persistent objects.
+    def define_implicit_attributes
+      @params = {}
+
+      @action.input_params.each do |name, param|
+        @params[name] = {} if param[:type] == 'Resource'
+      end
+    end
+
+    # Return a hash of all attributes suitable to be sent to the API +action+.
+    def attributes_for_api(action)
+      ret = {}
+
+      return ret if action.input_layout != :object
+
+      action.input_params.each do |name, param|
+        case param[:type]
+          when 'Resource'
+            ret[name] = @params[name][ param[:value_id].to_sym ]
+
+          else
+            ret[name] = @params[name]
+        end
+      end
+
+      ret
+    end
+
+    # Find associated resource and create its unresolved instance.
+    def find_association(res_desc, res_val)
+      return nil unless res_val
+
+      tmp = @client
+
+      res_desc[:resource].each do |r|
+        tmp = tmp.method(r).call
+      end
+
+      # FIXME: read _meta namespace from description
+      ResourceInstance.new(
+          @client,
+          @api,
+          tmp,
+          action: tmp.actions[:show],
+          resolved: res_val[:_meta][:resolved],
+          response: res_val[:_meta][:resolved] ? res_val : nil,
+          meta: res_val[:_meta]
+      )
+    end
+
+    # Override Resource.default_action_input_params.
+    def default_action_input_params(action)
+      attributes_for_api(action)
+    end
+  end
+end

data/lib/haveapi/client/resource_instance_list.rb

@@ -0,0 +1,29 @@
+module HaveAPI::Client
+  # A list of ResourceInstance objects.
+  class ResourceInstanceList < Array
+    def initialize(client, api, resource, action, response)
+      @response = response
+
+      response.response.each do |hash|
+        self << ResourceInstance.new(client, api, resource, action: action, response: hash)
+      end
+    end
+
+    # Return the API response that created this object.
+    def api_response
+      @response
+    end
+
+    def meta
+      @response.meta
+    end
+
+    # Return the total count of items.
+    # Note that for this method to work, the action that returns this
+    # object list must be invoked with +meta: {count: true}+, otherwise
+    # the object count is not sent.
+    def total_count
+      meta[:total_count]
+    end
+  end
+end

data/lib/haveapi/client/response.rb

@@ -1,6 +1,9 @@
+# Represents a response from the API.
 class HaveAPI::Client::Response
   attr_reader :action
 
+  # Create instance.
+  # +action+ being the called action and +response+ a received hash.
   def initialize(action, response)
     @action = action
     @response = response
@@ -15,14 +18,22 @@ class HaveAPI::Client::Response
   end
 
   def response
-    case @action.layout.to_sym
-      when :object, :list
+    case @action.output_layout
+      when :object, :object_list, :hash, :hash_list
         @response[:response][@action.namespace(:output).to_sym]
       else
         @response[:response]
     end
   end
 
+  def meta
+    @response[:response][:_meta] # FIXME: read _meta from API description
+  end
+
+  def to_hash
+    response
+  end
+
   def message
     @response[:message]
   end
@@ -30,4 +41,19 @@ class HaveAPI::Client::Response
   def errors
     @response[:errors]
   end
+
+  # Access namespaced params directly.
+  def [](key)
+    return unless %i(object hash).include?(@action.layout.to_sym)
+
+    @response[:response][@action.namespace(:output).to_sym][key]
+  end
+
+  # Iterate over namespaced items directly. Works for only for
+  # object_list or hash_list.
+  def each
+    return unless %i(list).include?(@action.layout.to_sym)
+
+    @response[:response][@action.namespace(:output).to_sym].each
+  end
 end

data/lib/haveapi/client/version.rb

@@ -1,5 +1,5 @@
 module HaveAPI
   module Client
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: haveapi-client
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jakub Skokan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-18 00:00:00.000000000 Z
+date: 2015-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -114,14 +114,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.5.1
+        version: 1.5.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 1.5.1
+        version: 1.5.3
 description: Ruby API and CLI for HaveAPI
 email:
 - jakub.skokan@vpsfree.cz
@@ -141,6 +141,7 @@ files:
 - lib/haveapi/cli/authentication/basic.rb
 - lib/haveapi/cli/authentication/token.rb
 - lib/haveapi/cli/cli.rb
+- lib/haveapi/cli/example_formatter.rb
 - lib/haveapi/client.rb
 - lib/haveapi/client/action.rb
 - lib/haveapi/client/authentication/base.rb
@@ -152,6 +153,8 @@ files:
 - lib/haveapi/client/exceptions.rb
 - lib/haveapi/client/inflections.rb
 - lib/haveapi/client/resource.rb
+- lib/haveapi/client/resource_instance.rb
+- lib/haveapi/client/resource_instance_list.rb
 - lib/haveapi/client/response.rb
 - lib/haveapi/client/version.rb
 - lib/restclient_ext/request.rb
@@ -176,7 +179,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Ruby API and CLI for HaveAPI