halogen 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 491dfa5f8eb8f51c4973205d1fbab6e883ce40db
+  data.tar.gz: 79c6b3b9b20ba7e86b6684daa38440b60b34460c
+SHA512:
+  metadata.gz: a69872769a3355f338b642ff0ae66dcbbc37a76edb9e74f7826e3abf7c53d8525ef8399a042db3d4d38b971d3bd7851984395779af628cd1df99e10983224024
+  data.tar.gz: d6ba44f85ce1d6b5bf1108975aa3426354f8f1b32d3cfc62bd16d91d9f894ac14e8186d8ca6121a561d0e5659cef16b7a81c9421ea386328421329c98c5b4b06

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.gem

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+
+rvm:
+  - '2.0'
+  - '2.1'

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in halogen.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Heather Rivers
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,244 @@
+# Halogen
+
+[![Build Status](https://travis-ci.org/mode/halogen.svg)](https://travis-ci.org/mode/halogen)
+
+This library provides a framework-agnostic interface for generating
+[HAL+JSON](http://stateless.co/hal_specification.html)
+representations of resources in Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'halogen'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install halogen
+
+## Usage
+
+### Basic usage
+
+Create a simple representer class and include Halogen:
+
+```ruby
+class GoatRepresenter
+  include Halogen
+
+  property :name do
+    'Gideon'
+  end
+
+  link :self do
+    '/goats/gideon'
+  end
+end
+```
+
+Instantiate:
+
+```ruby
+repr = GoatRepresenter.new
+```
+
+Then call `repr.render`:
+
+```ruby
+{
+  name: 'Gideon',
+  _links: {
+    self: { href: '/goats/gideon' }
+  }
+}
+```
+
+Or `repr.to_json`:
+
+```ruby
+'{"name": "Gideon", "_links": {"self": {"href": "/goats/gideon"}}}'
+```
+
+### Representer types
+
+#### 1. Simple
+
+Not associated with any particular resource or collection. For example, an API
+entry point:
+
+```ruby
+class ApiRootRepresenter
+  include Halogen
+
+  link(:self) { '/api' }
+end
+```
+
+#### 2. Resource
+
+Represents a single item:
+
+```ruby
+class GoatRepresenter
+  include Halogen
+
+  resource :goat
+end
+```
+
+When a resource is declared, `#initialize` expects the resource as the first argument:
+
+```ruby
+repr = GoatRepresenter.new(Goat.new, ...)
+```
+
+This makes property definitions cleaner:
+
+```ruby
+property :name # now calls Goat#name by default
+```
+
+#### 3. Collection
+
+Represents a collection of items. When a collection is declared, the embedded
+resource with the same name will always be embedded, whether it is requested
+via standard embed options or not.
+
+```ruby
+class GoatKidsRepresenter
+  include Halogen
+
+  collection :kids
+
+  embed(:kids) { ... } # always embedded
+end
+```
+
+### Defining properties, links and embeds
+
+Properties can be defined in several ways:
+
+```ruby
+property(:age) { "#{goat.age} years old" }
+```
+
+```ruby
+property :age # => Goat#age, if resource is declared
+```
+
+```ruby
+property :age do
+  goat.age.round
+end
+```
+
+```ruby
+property(:age) { calculate_age }
+
+def calculate_age
+  ...
+end
+```
+
+#### Conditionals
+
+The inclusion of properties can be determined by conditionals using `if` and
+`unless` options. For example, with a method name:
+
+```ruby
+property :age, if: :include_age?
+
+def include_age?
+  goat.age < 10
+end
+```
+
+With a proc:
+```ruby
+property :age, unless: proc { goat.age.nil? }, value: ...
+```
+
+For links and embeds:
+
+```ruby
+link :kids, :templated, unless: :exclude_kids_link?, value: ...
+```
+
+```ruby
+embed :kids, if: proc { goat.kids.size > 0 } do
+  ...
+end
+```
+
+#### Links
+
+Simple link:
+
+```ruby
+link(:root) { '/' }
+# => { _links: { root: { href: '/' } } ... }
+```
+
+Templated link:
+
+```ruby
+link(:find, :templated) { '/goats/{?id}' }
+# => { _links: { find: { href: '/goats/{?id}', templated: true } } ... }
+```
+
+### Embedded resources
+
+Embedded resources are not rendered by default. They will be included if both
+of the following conditions are met:
+
+1. The proc returns either a Halogen instance or an array of Halogen instances
+2. The embed is requested via the parent representer's options, e.g.:
+
+```ruby
+GoatRepresenter.new(embed: { kids: true, parents: false })
+```
+
+Embedded resources can be nested to any depth, e.g.:
+
+```ruby
+GoatRepresenter.new(embed: {
+  kids: {
+    foods: {
+      ingredients: true
+    },
+    pasture: true
+  }
+})
+```
+
+### Using with Rails
+
+If Halogen is loaded in a Rails application, Rails url helpers will be
+available in representers:
+
+```ruby
+link(:new) { new_goat_url }
+```
+
+### More examples
+
+* [Full representer class](examples/simple.rb)
+* [Extensions](examples/extensions.md)
+
+### What's with the goat?
+
+It is [majestic](https://twitter.com/ModeAnalytics/status/497876416013537280).
+
+## Contributing
+
+1. Fork it ( https://github.com/mode/halogen/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/extensions.md

@@ -0,0 +1,25 @@
+# Extensions
+
+You can extend Halogen by configuring it to include your own Ruby modules.
+
+For instance, if you wanted to cache the rendered versions of your
+representers, you might use something like this to override the default
+`#render` behavior:
+
+```ruby
+module MyCachingExtension
+  def render
+    Rails.cache.fetch(cache_key) { super }
+  end
+
+  def cache_key
+    ...
+  end
+end
+```
+
+```ruby
+Halogen.configure do |config|
+  config.extensions << MyCachingExtension
+end
+```

data/examples/simple.rb

@@ -0,0 +1,142 @@
+# encoding: utf-8
+#
+$LOAD_PATH.unshift(File.expand_path('../lib', File.dirname(__FILE__)))
+
+require 'halogen'
+require 'pp'
+
+# Example of a straightforward Halogen representer with no resource,
+# collection, or conditional definitions
+#
+class GoatRepresenter
+  include Halogen
+
+  # Simple instance methods that will be used for properties below
+  #
+  def id;         1;        end
+  def first_name; 'Gideon'; end
+  def last_name;  'Goat';   end
+
+  # == 1. Properties
+  #
+  # If you define a property without an explicit value or proc, Halogen will
+  # look for a public instance method with the corresponding name.
+  #
+  # This will call GoatRepresenter#id.
+  #
+  property :id # => { id: 1 }
+
+  # You can also define a property with an explicit value, e.g.:
+  #
+  property :age, value: 9.2 # => { age: 9.2 }
+
+  # Or you can use a proc to determine the property value at render time.
+  #
+  # The example below could also be written: property(:full_name) { ... }
+  #
+  property :full_name do # => { full_name: 'Gideon Goat' }
+    "#{first_name} #{last_name}"
+  end
+
+  # == 2. Links
+  #
+  # As with properties, links can be defined with a proc:
+  #
+  link :self do
+    "/goats/#{id}" # => { self: { href: '/goats/1' } }
+  end
+
+  # ...Or with an explicit value:
+  #
+  link :root, value: '/goats' # => { root: { href: '/goats' } }
+
+  # Links can also be defined as "templated", following HAL+JSON conventions:
+  #
+  link :find, :templated do # => ... { href: '/goats/{?id}', templated: true }
+    '/goats/{?id}'
+  end
+
+  # If Halogen is loaded in a Rails application, url helpers will be available
+  # automatically:
+  #
+  # link(:new) { new_goat_path }
+
+  # == 3. Embeds
+  #
+  # Embedded resources are not rendered by default. They will be included if
+  # both of the following conditions are met:
+  #
+  # 1. The proc returns either a Halogen instance or an array of Halogen instances
+  # 2. The embed is requested via the parent representer's options, e.g.:
+  #
+  #      GoatRepresenter.new(embed: { kids: true, parents: false })
+  #
+  embed :kids do # => { kids: <GoatKidsRepresenter#render> }
+    GoatKidsRepresenter.new
+  end
+
+  embed :parents do # => will not be included according to example options above
+    [
+      self.class.new,
+      self.class.new
+    ]
+  end
+
+  # Embedded resources can be nested to any depth, e.g.:
+  #
+  # GoatRepresenter.new(embed: {
+  #   kids: {
+  #     foods: {
+  #       ingredients: true
+  #     },
+  #     enclosure: true
+  #   }
+  # })
+end
+
+# Another simple representer to demonstrate embedded resources above
+#
+class GoatKidsRepresenter
+  include Halogen
+
+  property :count, value: 5
+end
+
+puts 'GoatRepresenter.new(embed: { kids: true }).render:'
+puts
+pp GoatRepresenter.new(embed: { kids: true }).render
+#
+# Result:
+#
+# {
+#   id: 1,
+#   age: 9.2,
+#   full_name: "Gideon Goat",
+#   _embedded: {
+#     kids: { count: 5 }
+#   },
+#   _links: {
+#     self: { href: '/goats/1' },
+#     root: { href: '/goats"'},
+#     find: { href: '/goats/{?id}', templated: true }
+#   }
+# }
+#
+
+puts
+puts 'GoatRepresenter.new.render:'
+puts
+pp GoatRepresenter.new.render
+#
+# Result:
+#
+# {
+#   id: 1,
+#   age: 9.2,
+#   full_name: "Gideon Goat",
+#   _links: {
+#     self: { href: '/goats/1' },
+#     root: { href: '/goats"'},
+#     find: { href: '/goats/{?id}', templated: true }
+#   }
+# }