roar 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9b58dcace50d4224e36f81444ce64ca73dfec11a
-  data.tar.gz: 419929c85da4aef8a13243364b1c918acfd5312c
+  metadata.gz: 9ce6093e4d27114a605b64621c20ab9f5e156266
+  data.tar.gz: ac05b9e8989952f88b86caaf2d344a2467f48968
 SHA512:
-  metadata.gz: c090f6a70e513ab5ad28155a9c21a453f0e37a289acb2af3a7ade51484d8cc1a76d0c14a02cf6343b054fb9ef2dd392dcae2383b7d219c77e43513d370369c62
-  data.tar.gz: 3253825814038580793eebb22da120b3af1ce69723d81283b65953e5b30806a91b7627ebb370de30b46440b07b749465ec2db1a9235b884b5de132becf2d4c84
+  metadata.gz: 334f83c90798c648945a3d1f0077e503a26f6a51bd2499a3878f48bdb845ad3815a55f8e372078ac28cf5fba628043e7b4edb031625e1abf14ff36dc4fee890d
+  data.tar.gz: 329f87d78af5d6e8f214e5dc71a22ff9ce932967bc8bb0e86f5b45ecad6a21eabf546afecd0690ab05dc8e5ccbcfe5f98cfccddc2ddd18f381e6a7ddaf2e441e

data/CHANGES.markdown

@@ -1,3 +1,7 @@
+# 1.0.1
+
+* Allow calling `::has_one`, `::links` and `::has_many` in any order in JSON-API. This requires representable >= 2.1.4.
+
 # 1.0.0
 
 ## Breakage

data/Gemfile

@@ -3,8 +3,8 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in roar.gemspec
 gemspec
 
-gem "representable", "~> 2.1.0"
-# gem "representable", :path => "../representable"
+# gem "representable", "~> 2.1.0"
+gem "representable", :path => "../representable"
 
 # as long as this is not merged, i'll vendor the runner file.
 # gem "sinatra-contrib", :git => "git@github.com:apotonick/sinatra-contrib.git", :branch => "runner"

data/README.markdown

@@ -8,10 +8,16 @@ Roar is a framework for parsing and rendering REST documents. Nothing more.
 
 Representers let you define your API document structure and semantics. They allow both rendering representations from your models _and_ parsing documents to update your Ruby objects. The bi-directional nature of representers make them interesting for both server and client usage.
 
-Roar comes with built-in JSON, JSON-HAL, JSON-API and XML support. Its highly modulare architecture provides features like coercion, hypermedia, HTTP transport, client caching and more.
+Roar comes with built-in JSON, JSON-HAL, JSON-API and XML support. Its highly modular architecture provides features like coercion, hypermedia, HTTP transport, client caching and more.
 
 Roar is completely framework-agnostic and loves being used in web kits like Rails, Webmachine, Sinatra, Padrino, etc. If you use Rails, consider [roar-rails](https://github.com/apotonick/roar-rails) for an enjoyable integration.
 
+<a href="https://leanpub.com/trailblazer">
+![](https://raw.githubusercontent.com/apotonick/trailblazer/master/doc/trb.jpg)
+</a>
+
+Roar is part of the [Trailblazer project](https://github.com/apotonick/trailblazer). Please [buy the book](https://leanpub.com/trailblazer) to support the development. Several chapters will be dedicated to Roar, its integration into operations, hypermedia formats and client-side usage.
+
 ## Representable
 
 Roar is just a thin layer on top of the [representable](https://github.com/apotonick/representable) gem. While Roar gives you a DSL and behaviour for creating hypermedia APIs, representable implements all the mapping functionality.
@@ -235,7 +241,7 @@ We're currently [working on](https://github.com/apotonick/roar/issues/85) better
 Roar provides coercion with the [virtus](https://github.com/solnic/virtus) gem.
 
 ```ruby
-require 'roar/feature/coercion'
+require 'roar/coercion'
 
 module SongRepresenter
   include Roar::JSON
@@ -280,7 +286,20 @@ module SongRepresenter
 end
 ```
 
-The `Hypermedia` feature allows declaring links using the `::link` method.
+The `Hypermedia` feature allows declaring links using the `::link` method. In the block, you have access to the represented model. When using representer modules, the block is executed in the model's context.
+
+However, when using decorators, the context is the decorator instance, allowing you to access additional data. Use `represented` to retrieve model data.
+
+```ruby
+class SongRepresenter < Roar::Decorator
+  # ..
+  link :self do
+    "http://songs/#{represented.title}"
+  end
+end
+```
+
+This will render links into your representation.
 
 ```ruby
 song.extend(SongRepresenter)
@@ -358,6 +377,8 @@ end
 
 Documentation for HAL can be found in the [API docs](http://rdoc.info/github/apotonick/roar/Roar/Representer/JSON/HAL).
 
+Make sure you [understand the different contexts](#hypermedia) for links when using decorators.
+
 ### Hypermedia
 
 Including the `Roar::JSON::HAL` module adds some more DSL methods to your module. It still allows using `::link` but treats them slightly different.
@@ -404,6 +425,8 @@ All HAL features in Roar are discussed in the [API docs](http://rdoc.info/github
 
 Roar also supports [JSON-API](http://jsonapi.org/) - yay! It can render _and_ parse singular and collection documents.
 
+Note that you need representable >= 2.1.4 in your `Gemfile`.
+
 ### Resource
 
 A minimal representation can be defined as follows.
@@ -412,7 +435,7 @@ A minimal representation can be defined as follows.
 require 'roar/json/json_api'
 
 module SongsRepresenter
-  include Roar::JSON::JsonApi
+  include Roar::JSON::JSONAPI
   type :songs
 
   property :id

data/examples/example.rb

@@ -4,7 +4,7 @@ require 'bundler'
 Bundler.setup
 
 require 'ostruct'
-require 'roar/representer/json'
+require 'roar/json'
 
 def reset_representer(*module_name)
   module_name.each do |mod|
@@ -19,12 +19,12 @@ class Song < OpenStruct
 end
 
 module SongRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 end
 
-song = Song.new(title: "Fate").extend(SongRepresenter)
+song = Song.new(title: 'Fate').extend(SongRepresenter)
 puts song.to_json
 
 # Parsing
@@ -40,13 +40,13 @@ require 'roar/decorator'
 
 module Decorator
   class SongRepresenter < Roar::Decorator
-    include Roar::Representer::JSON
+    include Roar::JSON
 
     property :title
   end
 end
 
-song = Song.new(title: "Medicine Balls")
+song = Song.new(title: 'Medicine Balls')
 puts Decorator::SongRepresenter.new(song).to_json
 
 # Collections
@@ -54,14 +54,14 @@ puts Decorator::SongRepresenter.new(song).to_json
 reset_representer(SongRepresenter)
 
 module SongRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
   collection :composers
 end
 
 
-song = Song.new(title: "Roxanne", composers: ["Sting", "Stu Copeland"])
+song = Song.new(title: 'Roxanne', composers: ['Sting', 'Stu Copeland'])
 song.extend(SongRepresenter)
 puts song.to_json
 
@@ -71,13 +71,13 @@ class Album < OpenStruct
 end
 
 module AlbumRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
   collection :songs, extend: SongRepresenter, class: Song
 end
 
-album = Album.new(title: "True North", songs: [Song.new(title: "The Island"), Song.new(:title => "Changing Tide")])
+album = Album.new(title: 'True North', songs: [Song.new(title: 'The Island'), Song.new(:title => 'Changing Tide')])
 album.extend(AlbumRepresenter)
 puts album.to_json
 
@@ -88,12 +88,10 @@ album.from_json('{"title":"Indestructible","songs":[{"title":"Tropical London"},
 
 puts album.songs.last.inspect
 
-# Inline Representers # FIXME: what about collections?
-
 reset_representer(AlbumRepresenter)
 
 module AlbumRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 
@@ -102,12 +100,10 @@ module AlbumRepresenter
   end
 end
 
-album = Album.new(title: "True North", songs: [Song.new(title: "The Island"), Song.new(:title => "Changing Tide")])
+album = Album.new(title: 'True North', songs: [Song.new(title: 'The Island'), Song.new(:title => 'Changing Tide')])
 album.extend(AlbumRepresenter)
 puts album.to_json
 
-
-
 album = Album.new
 album.extend(AlbumRepresenter)
 album.from_json('{"title":"True North","songs":[{"title":"The Island"},{"title":"Changing Tide"}]}')
@@ -119,7 +115,7 @@ puts album.songs.first.title
 reset_representer(AlbumRepresenter)
 
 module AlbumRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 
@@ -127,13 +123,13 @@ module AlbumRepresenter
 end
 
 
-album = Album.new(title: "True North", songs: [Song.new(title: "The Island"), Song.new(:title => "Changing Tide")])
+album = Album.new(title: 'True North', songs: [Song.new(title: 'The Island'), Song.new(:title => 'Changing Tide')])
 album.extend(AlbumRepresenter)
 
 puts album.songs[0].object_id
 album.from_json('{"title":"True North","songs":[{"title":"Secret Society"},{"title":"Changing Tide"}]}')
 puts album.songs[0].title
-puts album.songs[0].object_id##
+puts album.songs[0].object_id
 
 # Coercion, renaming, ..
 
@@ -142,8 +138,8 @@ puts album.songs[0].object_id##
 reset_representer(SongRepresenter)
 
 module SongRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Hypermedia
+  include Roar::JSON
+  include Roar::Hypermedia
 
   property :title
 
@@ -163,7 +159,7 @@ puts song.to_json
 reset_representer(SongRepresenter)
 
 module SongRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   property :title
 
@@ -173,7 +169,7 @@ module SongRepresenter
 end
 
 song.extend(SongRepresenter)
-puts song.to_json(base_url: "localhost:3001/")
+puts song.to_json(base_url: 'localhost:3001/')
 
 
 # Discovering Hypermedia
@@ -184,11 +180,11 @@ puts song.links[:self].href
 
 # Media Formats: HAL
 
-require 'roar/representer/json/hal'
+require 'roar/json/hal'
 
 module HAL
   module SongRepresenter
-    include Roar::Representer::JSON::HAL
+    include Roar::JSON::HAL
 
     property :title
 
@@ -204,7 +200,7 @@ puts song.to_json
 reset_representer(AlbumRepresenter)
 
 module AlbumRepresenter
-  include Roar::Representer::JSON::HAL
+  include Roar::JSON::HAL
 
   property :title
 
@@ -213,57 +209,55 @@ module AlbumRepresenter
   end
 end
 
-album = Album.new(title: "True North", songs: [Song.new(title: "The Island"), Song.new(:title => "Changing Tide")])
+album = Album.new(title: 'True North', songs: [Song.new(title: 'The Island'), Song.new(:title => 'Changing Tide')])
 album.extend(AlbumRepresenter)
 puts album.to_json
 
 # Media Formats: JSON+Collection
 
-require 'roar/representer/json/collection_json'
+require 'roar/json/collection_json'
 
 
 module Collection
   module SongRepresenter
-    include Roar::Representer::JSON::CollectionJSON
-    version "1.0"
-    href { "http://localhost/songs/" }
+    include Roar::JSON::CollectionJSON
+    version '1.0'
+    href { 'http://localhost/songs/' }
 
     property :title
 
     items(:class => Song) do
       href { "//songs/#{title}" }
 
-      property :title, :prompt => "Song title"
+      property :title, :prompt => 'Song title'
 
       link(:download) { "//songs/#{title}.mp3" }
     end
 
     template do
-      property :title, :prompt => "Song title"
+      property :title, :prompt => 'Song title'
     end
 
     queries do
       link :search do
-        {:href => "//search", :data => [{:name => "q", :value => ""}]}
+        {:href => '//search', :data => [{:name => 'q', :value => ''}]}
       end
     end
   end
 end
 
-song = Song.new(title: "Roxanne")
+song = Song.new(title: 'Roxanne')
 song.extend(Collection::SongRepresenter)
 puts song.to_json
 
-
-
 # Client-side
 # share in gem, parse existing document.
 
 reset_representer(SongRepresenter)
 
 module SongRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Hypermedia
+  include Roar::JSON
+  include Roar::Hypermedia
 
   property :title
   property :id
@@ -274,34 +268,34 @@ module SongRepresenter
 end
 
 
-require 'roar/representer/feature/client'
+require 'roar/client'
 
 module Client
   class Song < OpenStruct
-    include Roar::Representer::JSON
+    include Roar::JSON
     include SongRepresenter
-    include Roar::Representer::Feature::Client
+    include Roar::Client
   end
 end
 
-song = Client::Song.new(title: "Roxanne")
-song.post("http://localhost:4567/songs", "application/json")
+song = Client::Song.new(title: 'Roxanne')
+song.post(uri: 'http://localhost:4567/songs', as: 'application/json')
 puts song.id
 
 
 song = Client::Song.new
-song.get("http://localhost:4567/songs/1", "application/json")
+song.get(uri: 'http://localhost:4567/songs/1', as: 'application/json')
 puts song.title
 puts song.links[:self].href
 
 # XML
 
-require 'roar/representer/xml'
+require 'roar/xml'
 
 module XML
   module SongRepresenter
-    include Roar::Representer::XML
-    include Roar::Representer::Feature::Hypermedia
+    include Roar::XML
+    include Roar::Hypermedia
 
     property :title
     property :id
@@ -312,7 +306,7 @@ module XML
   end
 end
 
-song = Song.new(title: "Roxanne", id: 42)
+song = Song.new(title: 'Roxanne', id: 42)
 song.extend(XML::SongRepresenter)
 puts song.to_xml
 
@@ -320,11 +314,11 @@ puts song.to_xml
 
 reset_representer(SongRepresenter)
 
-require 'roar/representer/feature/coercion'
+require 'roar/coercion'
 
 module SongRepresenter
-  include Roar::Representer::JSON
-  include Roar::Representer::Feature::Coercion
+  include Roar::JSON
+  include Roar::Coercion
 
   property :title
   property :released_at, type: DateTime
@@ -342,7 +336,7 @@ class LinkOptionsCollection < Array
 end
 
 module HyperlinkiRepresenter
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   def to_hash(*)  # setup the link
     # FIXME: why does self.to_s throw a stack level too deep (SystemStackError) ?
@@ -352,7 +346,7 @@ module HyperlinkiRepresenter
 end
 
 module Representer
-  include Roar::Representer::JSON
+  include Roar::JSON
 
   def self.links
     [:self, :next]
@@ -363,8 +357,8 @@ module Representer
   def links
     # get link configurations from representable_attrs object.
     #self.representable_attrs.links
-    LinkOptionsCollection.new(["self", "next"])
+    LinkOptionsCollection.new(['self', 'next'])
   end
 end
 
-puts "".extend(Representer).to_json
+puts ''.extend(Representer).to_json

data/gemfiles/Gemfile.representable-2.1

@@ -2,4 +2,4 @@ source "http://rubygems.org"
 
 gemspec path: '../'
 
-gem 'representable', '~> 2.1.3'
+gem 'representable', '~> 2.1.5'

data/lib/roar/client.rb

@@ -1,10 +1,12 @@
 require "roar/http_verbs"
 
 module Roar
-  # Automatically add accessors for properties and collections. Also mixes in HttpVerbs.
+
+  # Mix in HttpVerbs. 
   module Client
     include HttpVerbs
 
+    # Add accessors for properties and collections to modules.
     def self.extended(base)
       base.instance_eval do
         representable_attrs.each do |attr|