Declarative style?

[jamis]

This is something I'm baking into my side-project, but I figured I'd run it by you to see if you thought it might fit in Webmachine directly. The idea is that declaring a method name in content_types_provided, and then declaring the method elsewhere, seems like an unfortunately large disconnect. (Same with content_types_accepted.) So what I've got is a set of macros:

class SampleResource < Resource
  when_client_wants "text/html" do
     # ...
   end

  when_client_wants "application/json", "text/x-json", "application/jsonrequest" do
     # ...
  end

  when_client_provides "application/xml", "application/x-xml", "text/xml" do
    # ...
  end

  when_client_provides "application/json", "text/x-json", "application/jsonrequest" do
    # ...
  end
end

It's built on top of the existing content_types_accepted and content_types_provided callbacks, so it's still possible to declare those mappings in the existing way. Thoughts?

[seancribbs]

I think that's nice from a developer perspective, but I wonder if we lose a bit of explicit nature of the method form; specifically, the ordering of content-types provided and accepted, since order is significant when doing content negotiation.

Perhaps this is being picky, but I would almost want to have the meta-programming methods be named in a way that implies declaration rather than reaction. This would keep in the paradigm of saying what the resource is rather than does. Again, minor point. How about this for a middle ground:

class SampleResource < Resource
  provides "text/html" do
    #...
  end

  accepts "application/xml", "application/x-xml", "text/xml" do
    #...
  end
end

or even

class SampleResource < Resource
  provides do
    type "text/html" {  }
  end

  accepts do
    type "application/xml", "application/x-xml", "text/xml" { }
  end
end

Because of the block around media-type declarations, the second form maybe forces the developer to recognize that ordering is significant.

[jamis]

As I've thought about this, I think it comes down to what you intend for Webmachine. Is Webmachine something that you expect people to use directly to write web applications, like Rails or Sinatra is? Or is it something like Rack which can be used directly, but is intentionally bare-metal and sparse on conventions, so that it can accomodate a variety of different opinions?

If the former, then I think the meta-programming has a place, but if the latter, I think it makes sense to leave the callbacks as they are. As I demonstrated, I was able to use the existing callbacks to build a declarative interface that suited my particular needs, so they definitely suffice.

[seancribbs]

@jamis That's a great insight. It's also so early in the project that I think it makes sense to solidify the core behavior first (it's pretty solid already but there are a few things I want to address). I think once more people start using WM we'll see more activity in customizing the interface and maybe something universal will emerge. I prefer to be freer of magic in the beginning.

[jamis]

That sounds good to me. I'll close this ticket. Looking forward to seeing where WM evolves!