Add Response#parse

[ixti]

Access to parsed body was nuked by merging #39.
This patch brings it back (feature, not the API).

Example

require 'json'

res = HTTP.get('https://api.github.com/repos/tarcieri/http')
res.parse['description']
# => "The HTTP Gem: a simple Ruby DSL for making HTTP requests"

[tarcieri]

Personally I'd prefer calling this method just #parse. Would be curious what others think.

[ixti]

I dislike parse as it's a verb... I might be wrong here.
Probably?:

def parse
  # ...
end
alias :parsed :parse

[ixti]

After discussion I agreed that #parse is better, as it's better conforms with #to_s.

[tarcieri]

Can you rebase against master?

@sferik, thoughts on this?

[sferik]

To be honest, the fact that this library attempts to handle MIME types seems a bit ambitious. I suppose this is a nice convenience, as long as we only support JSON. Not sure about the name parse. To me, it would be a bit more natural to say response.to_json (or to_whatever for whatever MIME type). Of course, this would require using method_missing. Maybe we should spend a bit more time bikeshedding the method name before merging?

Also it seems strange that the consumer needs to require 'json'. Shouldn’t that be abstracted by the parse method (or whatever we call it)?

[tarcieri]

To be honest, the fact that this library attempts to handle MIME types seems a bit ambitious.

I could go either way on this. I think it's convenient, but if it doesn't do a good job it probably isn't helping anyone.

I suppose this is a nice convenience, as long as we only support JSON

Seems good

Maybe we should spend a bit more time bikeshedding the method name before merging?

I am also down to discuss this as I too am not super happy with #parse.

Also it seems strange that the consumer needs to require 'json'. Shouldn’t that be abstracted by the parse method (or whatever we call it)?

Agree. require 'json' is silly since it's available everywhere except 1.8.

[ixti]

@tarcieri rebased
@sferik I dislike idea of to_json as it's absolutely irrelevant. In a worst case it's from_json.

I agree that require 'json' is silly. But it seems to me not very good to use default json as well.
So here's my thoughts:

1. We should use MultiJSON for JSON parser
2. We should also support XML using MultiXML out of box
3. Neither MultiJSON nor MultiJSON should become dependencies, instead an appropriate error should be used if one used #parse method and no such library loaded:

json.prepare do
  begin
    require "multi_json"
  rescue LoadError
    fail "MultiJSON was not required"
  end
end

1. MimeType API should be reworked:
   4.a) it should be a simple inheritance (see below)
   4.b) it should allow association with multiple mime types

# MimeType API changes proposal
module HTTP
  # Yes, HTTP bundles its own MIME type library. Maybe it should be spun off
  # as a separate gem or something.
  class MimeType
    def ready?
      prepare unless @ready
      @ready = true
    end

    # should be implemented on concrete adapter
    def parse(obj)
      obj
    end

    # should be implemented on concrete adapter
    def emit(obj)
      obj
    end

    # should be implemented on concrete adapter
    def prepare; end

    def depend_on(lib)
      require lib
    rescue LoadError
      fail "#{self.class.adapter_name} adapter depends on #{lib}"
    end
    private :depend_on

    class << self
      def adapter_name shortcut
        # ...
      end

      def adapter_mime *mimetypes
        # ...
      end
    end
end

# built in adapters
require 'http/mime_types/json'
require 'http/mime_types/xml'

The proposed idea will allow following adapter declaration:

class HTTP::MimeType::JSON < HTTP::MimeType
  adapter_name :json
  adapter_mime "application/json"

  def prepare
    depend_on "multi_json"
  end

  def parse(obj)
    MultiJSON.load obj
  end

  def emit(obj)
    MultiJSON.dump obj
  end
end

[ixti]

My main reason why I need multiply MIME-types per adapter is because I need to parse application/atom+xml as XML the api above would allow me to:

# append another mime type to be served by XML adapter
HTTP::MimeType::XML.addapter_mime "application/atom+xml"

[tarcieri]

I'm not a fan of MultiJSON:

1. It's an onerous dependency
2. It's an unnecessary dependency in a post 1.9 world where every Ruby implementation can ship a native JSON parser

For the most part I like your MimeType API proposal

[ixti]

OK. I tend to agree about MultiJSON. In a worst case if one would like to use OJ he will be able to easily monkey-patch built-in adapter after all. In this case it's really worth to support only JSON out of the box. Will serve two purposes: fairly common adapter (for Web) and example of how to write adapters.

I think I'll raise different PR with API changes for MimeType - it won't affect this PR anyway.

[ixti]

After some discussions I'm closing this PR. MimeType was broken and it's current state doesn't worth to spend time on updating it.

[ixti]

Closed in favor of #64 :D

[sferik]

I dislike idea of to_json as it's absolutely irrelevant. In a worst case it's from_json.

I mean to_hash (or to_h).