hexx 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f14eb96fccf59e4cff2b528b7af4022bc1a06ba0
+  data.tar.gz: 129481aec498d829b4cfefa8826342d3c2656f52
+SHA512:
+  metadata.gz: 33cda7123f07260c0c60b11e81d57fa2acdd15df6e3a918e21956f61564fbd76de750c263d82cdef7b324f757b369ab318ecc5137cf0220faf63d11d465c1da0
+  data.tar.gz: 2f9fc12483c459cde61bb5581a74e3c126f92722d741d323160af374eeefda52bec304735721f7bee9ca8989fc7b6aebe14bc868964f41c5b8617324f46db203

data/.rubocop.yml

@@ -0,0 +1,45 @@
+Lint/HandleExceptions:
+  Exclude:
+    - 'spec/**/*'
+
+Lint/RescueException:
+  Exclude:
+    - 'spec/**/*'
+
+Style/AccessorMethodName:
+  Exclude:
+    - 'spec/**/*'
+
+Style/ClassAndModuleChildren:
+  Exclude:
+    - 'spec/**/*'
+
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+
+Style/EmptyLinesAroundBody:
+  Enabled: false
+
+Style/EmptyLineBetweenDefs:
+  Exclude:
+    - 'spec/**/*'
+
+Style/RaiseArgs:
+  EnforcedStyle: compact
+
+Style/SingleLineMethods:
+  Exclude:
+    - 'spec/**/*'
+
+Style/SpecialGlobalVars:
+  Exclude:
+    - 'Gemfile'
+    - '*.gemspec'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrivialAccessors:
+  Exclude:
+    - 'spec/**/*'

data/CHANGELOG.rdoc

@@ -0,0 +1 @@
+= CHANGELOG

data/LICENSE.rdoc

@@ -0,0 +1,21 @@
+= The MIT License
+
+Copyright (c) 2014 Andrew Kozin, https://github.com/nepalez
+
+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.rdoc

@@ -0,0 +1,235 @@
+= Hexx
+
+{<img src="http://img.shields.io/travis/nepalez/hexx.svg?style=flat" alt="Bild Status" />}[https://travis-ci.org/nepalez/hexx]
+{<img src="http://img.shields.io/codeclimate/github/nepalez/hexx.svg?style=flat" alt="Code Metrics" />}[https://codeclimate.com/github/nepalez/hexx]
+{<img src="http://img.shields.io/gemnasium/nepalez/hexx.svg?style=flat" alt="Dependency Status" />}[https://gemnasium.com/nepalez/hexx]
+{<img src="http://img.shields.io/coveralls/nepalez/hexx.svg?style=flat" alt="Coverage Status" />}[https://coveralls.io/r/nepalez/hexx]
+{<img src="http://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="License" />}[https://github.com/nepalez/hexx/blob/master/LICENSE.rdoc]
+
+A part of framework for rapid Rails API development following the hexagonal
+architecture.
+
+Provides:
+* +UseCase+ base class for decoupling a domain business logics from a controller
+* Thor generators for scaffolding use cases, controllers and routes.
+
+== Installation
+
+Add this line to your application's Gemfile:
+
+  gem 'hexx', git: "https://github.com/nepalez/hexx.git"
+
+== Usage
+
+Controllers are expected to serve as a thin delivery layer between a client
+and a use case. They should only orchestrate interactions of use case with its
+listeners: the controller itself, mailers and other outer services.
+
+In a typical case the controller should constist from:
+
+* actions serving as <b>outer ports</b> to client, listening to routes and
+  calling corresponding use cases
+* methods servinge as <b>inner ports</b> called by use case notifications
+  (see wisper[https://github.com/krisleech/wisper.git] for more details).
+
+=== Use case
+
+  # app/my_project/use_cases/get_item.rb
+  require 'hexx'
+
+  module MyProject
+    class GetItem < Hexx::Base
+
+      # whitelists parameters taken by an initializer
+      allow_params :id
+
+      # runs some validation (on the basis of ActiveModel::Validations)
+      validate :id, presence: true
+
+      # runs a use case
+      def run!
+        validate!
+        # provide case-specific business rules
+      end
+    end
+  end
+
+=== Rails controller
+
+  # app/controllers/my_project/rails/api/v1/items_controller.rb
+  require 'my_project'
+  require 'rails'
+
+  module MyProject
+    module Rails
+      module Api
+        module V1
+          class ItemsController < ActionController::Base
+
+          # An action (outer port) of the controller
+          def show
+            use_case = GetItem.new params.allow(:id)
+            # subscribes the controller for listening for the use case
+            # notifications via the controller's inner ports.
+            use_case.subscribe self
+            use_case.run
+          end
+
+          # Inner port to be called by a use case
+          def found(item)
+            render json: { success: true, item: item }, status: 200
+          end
+        end
+      end
+    end
+  end
+
+<i>Note the module above is not +my_project+, but +my_project-rails+
+(a delivery mechanism for +my_project+).</i>
+
+=== Models and Entities
+
+The module also defines module <tt>Hexx::Models</tt> for including to
+entities or active_record models. It defines a +validate!+ method:
+
+  class User < ActiveRecord::Base
+    include Hexx::Models
+  end
+
+  User.new.validate!
+  # => raises Hexx::RecordInvalid error if the record isn't valid.
+
+It also redefines +attr_accessor+, +attr_reader+ and +attr_writer+ helpers
+to allow attribute coercion.
+
+  require "attributes/string"
+
+  class User < ActiveRecord::Base
+    include Hexx::Models
+
+    attr_accessor :name, type: Attributes::String
+  end
+
+This coerces the name with an Attributes::String class object as if its
+setter and getter were:
+
+  def name=(value)
+    super Attributes::String.new(value)
+  end
+
+  def name
+    Attributes::String.new(super)
+  end
+
+== Generators
+
+The module contains generators, written on the basis of the Thor, namely:
+
+* request specs (acceptance tests);
+* controllers with their specs (unit tests)
+* routing specs (unit tests);
+* domain specs (acceptance tests for use cases and models);
+* use_cases with their specs (unit tests);
+
+The scaffolded specs contains examples for writing tests rapidly following
+some conventions.
+
+=== Request spec (acceptance test for the API)
+
+Request specs used to test API from a user view - by sending requests
+and checkign their results. Their should be written on the basis of
+API blueprint. Their shouldn't check the internal states of application, such
+as models, use_cases etc.
+
+Task is called with 1 argument, that consists from two parts divided by colon:
+
+* request type (get, post etc.)
+* requests relative address
+
+Example:
+
+  $ hexx request get:items/{id}
+  # => spec/requests/my_module/api/v1/get_items_id_spec.rb
+
+API namespace (those /my_module/api/v1) will be added by default.
+
+=== Controller action with a corresponding route
+
+A scaffolder provides tests for both a controller and its router. It
+also scaffolds a controller action itself. The router action should be
+added manually.
+
+Except for the requests specs (above) the controller spec is an unit test
+that checks outer and inner controller action in isolation from both
+router and a use case. It only checks that outer actions calls proper use cases,
+and inner actions returns proper responce to a user.
+
+Task is called with 3 argumets:
+
+* name of the controller
+* request type and action name, divided by colon
+* name of the use case for the action
+
+Example:
+
+  $ hexx controller items get:show get_item
+  # => spec/routing/my_module/api/v1/items_routing_spec.rb
+  # => spec/controllers/my_module/api/v1/items_controller_spec.rb
+  # => app/controllers/my_module/api/v1/items_controller.rb
+
+==== Acceptance spec for the domain
+
+The domain spec checks the inner part of the domain (use_cases and models) as
+a whole. Because the domain interacts with outer word through the use cases
+only, the acceptance test should call use_cases and check its results.
+It should not check inner states of the domain (models, entities, repositories,
+databases etc.)
+
+Task is called with 1 argument:
+
+* name of the use_case.
+
+Example:
+
+  $ hexx domain get_item
+  # => spec/my_module/domain/get_item_spec.rb
+
+==== UseCase
+
+The unit tests for checking a use_case in isolation.
+
+Task is called with 1 argument:
+
+* name of the use_case.
+
+Example:
+
+  $ hexx use_case get_item
+  # => spec/my_module/use_cases/get_item_spec.rb
+  # => app/my_module/use_cases/get_item.rb
+
+==== Dependency
+
+Scaffolds the external dependency setting with a corresponding specs.
+
+Task is called with 1 argument:
+
+* name of the dependency.
+
+Example:
+
+  $hexx dependency some_module
+  # => spec/my_module_spec.rb
+  # => lib/my_module.rb
+
+== Relevant Links
+
+1:: Matt Wynne's talk {Hexagonal Rails}[http://www.confreaks.com/videos/977-goruco2012-hexagonal-rails]
+
+== Changelog
+
+To review changes between versions see the {CHANGELOG}[CHANGELOG.rdoc].
+
+== License
+
+The project is distributed under the {MIT LICENSE}[LICENSE.rdoc].

data/Rakefile

@@ -0,0 +1,31 @@
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+begin
+  require "rdoc/task"
+rescue LoadError
+  require "rdoc/rdoc"
+  require "rake/rdoctask"
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "Hexx"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.rdoc")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+Bundler::GemHelper.install_tasks
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+task :default do
+  sh "bundle exec rspec spec"
+end

data/bin/hexx

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+require "thor"
+require "rubygems"
+
+root = File.dirname File.dirname(__FILE__)
+Dir[File.join(root, "lib/generators/**/*.rb")].each { |file| require file }
+
+# Scaffold tasks for the Hexx based projects.
+class HexxRunner < Thor
+
+  desc "install", "scaffolds a new project"
+  def install
+    script = Hexx::Generators::Install.new [project]
+    script.invoke_all
+  end
+
+  desc "request", "scaffolds a new request spec (acceptance test)"
+  def request(name)
+    script = Hexx::Generators::Request.new [project, name]
+    script.invoke_all
+  end
+
+  desc "controller", "scaffolds a new route with a controller action"
+  def controller(name, route, usecase)
+    script = Hexx::Generators::Controller.new [project, name, route, usecase]
+    script.invoke_all
+  end
+
+  desc "domain", "scaffolds a new acceptance test for the domain"
+  def domain(name)
+    script = Hexx::Generators::Domain.new [project, name]
+    script.invoke_all
+  end
+
+  desc "use_case", "scaffolds a new use case"
+  def use_case(name)
+    script = Hexx::Generators::UseCase.new [project, name]
+    script.invoke_all
+  end
+
+  desc "depencency", "scaffolds a dependency"
+  def dependency(name)
+    script = Hexx::Generators::Dependency.new [project, name]
+    script.invoke_all
+  end
+
+  private
+
+  def project
+    Dir.getwd.split("/").last.to_s.downcase
+  end
+end
+
+HexxRunner.start

data/lib/generators/base.rb

@@ -0,0 +1,59 @@
+require "thor"
+require "extlib"
+
+module Hexx
+  module Generators
+
+    # Base class for scaffolders.
+    class Base < Thor::Group
+      include Thor::Actions
+
+      argument :project
+      argument :name
+
+      def self.source_root(file = __FILE__)
+        root = File.dirname File.expand_path(file)
+        @source_root ||= File.join(root, "templates")
+      end
+
+      private
+
+      def gem_name
+        @gem_name ||= project.snake_case
+      end
+
+      def module_name
+        @module_name ||= project.camel_case
+      end
+
+      def class_name
+        @class_name ||= name.camel_case
+      end
+
+      def file_name
+        @file_name ||= name.snake_case
+      end
+
+      def action_type(string)
+        return @action_type if @action_type
+        list = string.split(":")
+        list.count > 1 ? list.first.downcase : "get"
+      end
+
+      def action_name(string)
+        string.split(":").last.downcase
+      end
+
+      def inject_template_into_file(source, file, options)
+        source  = File.expand_path(find_in_source_paths(source.to_s))
+        context = instance_eval("binding")
+        content = ERB.new(::File.binread(source), nil, "-", "@output_buffer")
+          .result(context)
+
+        inject_into_file file, options do
+          content
+        end
+      end
+    end
+  end
+end