halogen 0.0.1

data/halogen.gemspec

@@ -0,0 +1,32 @@
+# encoding: utf-8
+#
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'halogen/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'halogen'
+  spec.version       = Halogen::VERSION
+  spec.authors       = ['Heather Rivers']
+  spec.email         = ['heather@modeanalytics.com']
+  spec.summary       = 'HAL+JSON generator'
+  spec.description   = 'Provides a framework-agnostic interface for ' \
+                       'generating HAL+JSON representations of resources'
+  spec.homepage      = 'https://github.com/mode/halogen'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '~> 2.0'
+
+  spec.add_dependency 'json', '~> 1.8'
+
+  spec.add_development_dependency 'bundler',   '~> 1.7'
+  spec.add_development_dependency 'rake',      '~> 10.0'
+  spec.add_development_dependency 'rspec',     '~> 3.2'
+  spec.add_development_dependency 'simplecov', '~> 0.9'
+  spec.add_development_dependency 'yard',      '~> 0.8'
+end

data/lib/halogen.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__)))
+
+require 'json'
+
+# HAL+JSON generator
+#
+# Provides a framework-agnostic interface for generating HAL+JSON
+# representations of resources
+#
+module Halogen
+  # Provide Halogen methods for the including module
+  #
+  # @return [Module]
+  #
+  def self.included(base)
+    base.extend ClassMethods
+
+    base.send :include, InstanceMethods
+    base.send :include, Properties
+    base.send :include, Links
+    base.send :include, Embeds
+
+    config.extensions.each { |extension| base.send :include, extension }
+
+    base.send :attr_reader, :options
+  end
+
+  module ClassMethods # :nodoc:
+    # @return [Halogen::Definitions] the definitions container instance
+    #
+    def definitions
+      @definitions ||= Definitions.new
+    end
+
+    # @param [Symbol, String] name of the resource
+    #
+    # @return [Module] self
+    #
+    def resource(name)
+      include Resource
+
+      define_resource(name)
+    end
+
+    # @param [Symbol, String] name of the collection
+    #
+    # @return [Module] self
+    #
+    def collection(name)
+      include Collection
+
+      define_collection(name)
+    end
+  end
+
+  module InstanceMethods # :nodoc:
+    # @param options [nil, Hash] hash of options
+    #
+    # @return [Object] the representer instance
+    #
+    def initialize(options = {})
+      @options = Halogen::HashUtil.symbolize_keys!(options)
+    end
+
+    # @return [String] rendered JSON
+    #
+    def to_json
+      render.to_json
+    end
+
+    # @return [Hash] rendered representation
+    #
+    def render
+      {}
+    end
+
+    # @return [nil, Object] the parent representer, if this instance is an
+    #   embedded child
+    #
+    def parent
+      @parent ||= options.fetch(:parent, nil)
+    end
+
+    # @return [Integer] the depth at which this representer is embedded
+    #
+    def depth
+      @depth ||= parent ? parent.depth + 1 : 0
+    end
+
+    protected
+
+    # Allow included modules to decorate rendered hash
+    #
+    # @param key [Symbol] the key (e.g. `embedded`, `links`)
+    # @param result [Hash] the partially rendered hash to decorate
+    #
+    # @return [Hash] the decorated hash
+    #
+    def decorate_render(key, result)
+      result.tap do
+        value = send(key)
+
+        result[:"_#{key}"] = value if value.any?
+      end
+    end
+
+    # Iterate through enabled definitions of the given type, allowing instance
+    # to build up resulting hash
+    #
+    # @param type [Symbol, String] the definition type
+    #
+    # @return [Hash] the result
+    #
+    def render_definitions(type)
+      definitions = self.class.definitions.fetch(type, [])
+
+      definitions.each_with_object({}) do |definition, result|
+        next unless definition.enabled?(self)
+
+        yield definition, result
+      end
+    end
+  end
+
+  class << self
+    # @yield [Halogen::Configuration] configuration instance for modification
+    #
+    def configure
+      yield config
+    end
+
+    # Configuration instance
+    #
+    # @return [Halogen::Configuration]
+    #
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end
+
+require 'halogen/collection'
+require 'halogen/configuration'
+require 'halogen/definition'
+require 'halogen/definitions'
+require 'halogen/embeds'
+require 'halogen/errors'
+require 'halogen/links'
+require 'halogen/properties'
+require 'halogen/resource'
+require 'halogen/hash_util'
+require 'halogen/version'
+
+require 'halogen/railtie' if defined?(::Rails)

data/lib/halogen/collection.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+#
+module Halogen
+  # Behavior for representers with a primary collection resource.
+  #
+  # The main reason to declare a collection is that the resource with that name
+  # will always be embedded during rendering.
+  #
+  module Collection
+    def self.included(base) # :nodoc:
+      if base.included_modules.include?(Resource)
+        fail InvalidCollection, "#{base.name} has already defined a resource"
+      end
+
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+
+      base.class.send :attr_accessor, :collection_name
+    end
+
+    module ClassMethods # :nodoc:
+      # @param name [Symbol, String] name of the collection
+      #
+      # @return [Module] self
+      #
+      def define_collection(name)
+        self.collection_name = name.to_s
+      end
+    end
+
+    module InstanceMethods # :nodoc:
+      # Override super to ensure that the primary collection is always embedded
+      #
+      # @param key [String] the embed key to check
+      #
+      # @return [true, false] whether the given key should be embedded
+      #
+      def embed?(key)
+        super || key == self.class.collection_name
+      end
+    end
+  end
+end

data/lib/halogen/configuration.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+#
+module Halogen
+  # Simple configuration class
+  #
+  class Configuration
+    # Array of extension modules to be included in all representers
+    #
+    # @return [Array<Module>]
+    #
+    def extensions
+      @extensions ||= []
+    end
+  end
+end

data/lib/halogen/definition.rb

@@ -0,0 +1,73 @@
+# encoding: utf-8
+#
+module Halogen
+  # Stores instructions for how to render a value for a given representer
+  # instance
+  #
+  class Definition
+    attr_reader :name, :options
+
+    attr_accessor :procedure
+
+    # Construct a new Definition instance
+    #
+    # @param name [Symbol, String] definition name
+    # @param options [Hash] hash of options
+    #
+    # @return [Halogen::Definition] the instance
+    #
+    def initialize(name, options, procedure)
+      @name      = name.to_sym
+      @options   = Halogen::HashUtil.symbolize_keys!(options)
+      @procedure = procedure
+    end
+
+    # @param instance [Object] the representer instance with which to evaluate
+    #   the stored procedure
+    #
+    def value(instance)
+      options.fetch(:value) do
+        procedure ? instance.instance_eval(&procedure) : instance.send(name)
+      end
+    end
+
+    # @return [true, false] whether this definition should be included based on
+    #   its conditional guard, if any
+    #
+    def enabled?(instance)
+      if options.key?(:if)
+        !!eval_guard(instance, options.fetch(:if))
+      elsif options.key?(:unless)
+        !eval_guard(instance, options.fetch(:unless))
+      else
+        true
+      end
+    end
+
+    # @return [true] if nothing is raised
+    #
+    # @raise [Halogen::InvalidDefinition] if the definition is invalid
+    #
+    def validate
+      return true unless options.key?(:value) && procedure
+
+      fail InvalidDefinition,
+           "Cannot specify both value and procedure for #{name}"
+    end
+
+    private
+
+    # Evaluate guard procedure or method
+    #
+    def eval_guard(instance, guard)
+      case guard
+      when Proc
+        instance.instance_eval(&guard)
+      when Symbol, String
+        instance.send(guard)
+      else
+        guard
+      end
+    end
+  end
+end

data/lib/halogen/definitions.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+#
+module Halogen
+  # Each representer class has a Halogen::Definitions instance which stores
+  # Halogen::Definition instances by type.
+  #
+  class Definitions < Hash
+    # @param definition [Halogen::Definition]
+    #
+    # @return [Halogen::Definition] the added definition
+    #
+    def add(definition)
+      type = definition.class.name
+
+      definition.validate
+
+      self[type] ||= []
+      self[type] << definition
+
+      definition
+    end
+  end
+end

data/lib/halogen/embeds.rb

@@ -0,0 +1,105 @@
+# encoding: utf-8
+#
+module Halogen
+  module Embeds # :nodoc:
+    def self.included(base) # :nodoc:
+      base.extend ClassMethods
+
+      base.send :include, InstanceMethods
+    end
+
+    module ClassMethods # :nodoc:
+      # @param name [Symbol, String]
+      # @param options [nil, Hash]
+      #
+      # @return [Halogen::Embeds::Definition]
+      #
+      def embed(name, options = {}, &procedure)
+        definitions.add(Definition.new(name, options, procedure))
+      end
+    end
+
+    module InstanceMethods # :nodoc:
+      # @return [Hash] the rendered hash with embedded resources, if any
+      #
+      def render
+        decorate_render :embedded, super
+      end
+
+      # @return [Hash] hash of rendered resources to embed
+      #
+      def embedded
+        render_definitions(Definition.name) do |definition, result|
+          next unless embed?(definition.name.to_s)
+
+          value = instance_eval(&definition.procedure)
+
+          child = embedded_child(definition.name.to_s, value)
+
+          result[definition.name] = child if child
+        end
+      end
+
+      # @return [Hash, Array<Hash>] either a single rendered child representer
+      #   or an array of them
+      #
+      def embedded_child(key, value)
+        return unless value
+
+        opts = child_embed_opts(key)
+
+        if value.is_a?(Array)
+          value.map { |item| render_child(item, opts) }.compact
+        else
+          render_child(value, opts)
+        end
+      end
+
+      # @param key [String]
+      #
+      # @return [Hash]
+      #
+      def child_embed_opts(key)
+        opts = embed_options.fetch(key, {})
+
+        # Turn { :report => 1 } into { :report => {} } for child
+        opts = {} unless opts.is_a?(Hash)
+
+        opts
+      end
+
+      # @param repr [Object] the child representer
+      # @param opts [Hash] the embed options to assign to the child
+      #
+      # @return [nil, Hash] the rendered child
+      #
+      def render_child(repr, opts)
+        return unless repr.class.included_modules.include?(Halogen)
+
+        repr.options.merge!(embed: opts, parent: self)
+
+        repr.render
+      end
+
+      # @return [Hash] hash of options with top level string keys
+      #
+      def embed_options
+        options.fetch(:embed, {}).tap do |result|
+          Halogen::HashUtil.stringify_keys!(result)
+        end
+      end
+
+      # @param key [String]
+      #
+      # @return [true, false] whether to embed the key
+      #
+      def embed?(key)
+        return false unless embed_options.include?(key)
+
+        !%w(0 false).include?(embed_options.fetch(key).to_s)
+      end
+    end
+  end
+end
+
+require 'halogen/embeds/definition'