lightrail 0.0.1 → 0.99.0

data/.gitignore

@@ -0,0 +1,7 @@
+coverage/
+rdoc/
+doc/
+pkg/
+.yardoc
+.bundle
+Gemfile.lock

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format documentation
+--backtrace
+--default_path spec

data/.travis.yml

@@ -0,0 +1,11 @@
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ree
+  - ruby-head
+  - jruby-18mode
+  - jruby-19mode
+  - jruby-head
+  - rbx-18mode
+  - rbx-19mode

data/CHANGES.md

@@ -0,0 +1,8 @@
+0.99.0
+------
+* Not quite 1.0-pre quality yet, but better!
+* Import Rails generators, generate lightrail apps
+
+0.0.1
+-----
+* Stealth release

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 José Valim, Carl Lerche, and contributors
+
+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,205 @@
+![Lightrail](https://github.com/lightness/lightrail/raw/master/logo.png)
+============
+[![Build Status](https://secure.travis-ci.org/lightness/lightrail.png?branch=master)](http://travis-ci.org/lightness/lightrail)
+
+Lightrail is a minimalist Rails 3 stack for apps that serve primarily APIs,
+with a particular focus on JSON APIs. If [Sinatra][sinatra] doesn't give
+you enough, but [Rails][rails] is still too much, Lightrail is for you.
+
+[sinatra]: http://www.sinatrarb.com/
+[rails]: http://rubyonrails.org/
+
+Join the mailing list by sending a message to: lightrail@librelist.com
+
+Getting Started
+---------------
+
+Install the lightrail gem:
+
+`gem install lightrail`
+
+Like Rails, installing the lightrail gem will install a command line utility
+called 'lightrail'. This command is in fact identical to the 'rails' command,
+but tweaked for Lightrail defaults instead of Rails defaults.
+
+You can use 'lightrail' to create a new application skeleton just like Rails:
+
+`lightrail new myapp`
+
+The skeleton application that Lightrail generates is identical to a standard
+Rails application, with only these changes:
+
+* Gemfile pulls in lightrail instead of rails
+* application.rb pulls in lightrail instead of rails
+* ApplicationController descends from Lightrail::ActionController::Metal
+  instead of ActionController::Base. ActionView is not used or installed.
+
+Once you've created your application, run:
+
+`lightrail server`
+
+to launch a web server in the development environment (just like Rails!)
+
+You can convert an existing Rails 3 application to a Lightrail application
+by retrofitting the changes mentioned above.
+
+Lightrail::ActionController::Metal
+----------------------------------
+
+A lightweight `ActionController::Base` replacement designed for when APIs are your main concern.
+It removes several irrelevant modules and also provides following additional behaviors:
+
+  * `halt` stops rendering at any point using Ruby's throw/catch mechanism.
+    Any option passed to `halt` is forwarded to the `render` method
+
+  * `render :errors` is a renderer extension that allows you to easily render an error as JSON.
+    It is simply a convenience method for `render json: errors, status: 422`.
+    With the `halt` mechanism above you'll see this common pattern: `halt errors: { request: "invalid" }`.
+
+
+Lightrail::Wrapper
+------------------
+
+Wrappers are Lightrail's view replacement, and handle JSON serialization of your models.
+Instead of having a monster `#to_json` method in your model, you can factor that into a
+wrapper instead, and wrappers will automatically take care of many additional JSON
+serialization concerns for you.
+
+**Creating A Wrapper**
+
+Each model needs to have a wrapper in order to be rendered as JSON.
+Instead of using several options (like `:only`, `:method`, and friends) it expects you to explicitly define the hash to returned through the `view` method.
+Here is an example:
+
+``` ruby
+class AccountWrapper < Lightrail::Wrapper::Model
+  has_one :credit_card
+  has_one :subscription
+
+  def view
+    attributes = [:id, :name, :user_id]
+
+    if owner?
+      attributes.concat [:billing_address, :billing_country]
+    end
+
+    # Shortcut for account.attributes.slice()
+    hash = account.slice(*attributes)
+    hash[:owner] = owner?
+    hash
+  end
+
+  # Whenever an association method is defined explicitly
+  # it is given higher preference. That said, whenever
+  # including a credit_card, it will invoke this method
+  # instead of calling account.credit_card directly.
+  def credit_card
+    account.credit_card if owner?
+  end
+
+  protected
+
+  def owner?
+    account.owners.include? scope
+  end
+end
+```
+
+A wrapper is initialized with two arguments:
+the `resource` which is the `account` in this case and a `scope`.
+In most cases the scope is the `current_user`.
+The idea of having a scope inside the wrapper is to be able to properly handle permissions when exposing a resource.
+In the example above you can notice that a `credit_card` is only exposed if the user actually owns the account being showed.
+Billing information is also hidden except when the user is an `owner?`.
+
+Another convenience is that the wrapper can automatically handle associations.
+Associations, when exposed are not nested exposed but rather flat in the JSON here is an example:
+
+
+``` json
+{
+  "account": {
+    "id": 1,
+    "name": "Main",
+    "user_id": null,
+    "credit_card_id": 1
+  },
+
+  "credit_cards": {
+    "id": 1,
+    "last_4": "3232"
+  }
+}
+```
+
+In order to render a wrapper with its associations you can use the `render` method and pass the associations explicitly:
+
+``` ruby
+AccountWrapper.new(@account, current_user).render include: [:credit_card]
+```
+
+Although most of the times this will be done automatically by the controller.
+
+**Using The Wrapper In The Controller**
+
+`Lightrail::Wrapper::Controller` provides several facilities to use wrappers from the controller:
+
+  * `#json(resources)` is the main method.
+    Given a resource (or an array of resources) it will find the proper wrapper and render it.
+    Any include given at `params[:include]` will be validated and passed to the underlying wrapper.
+    Consider the following action:
+
+    ``` ruby
+    def last
+      json Account.last
+    end
+    ```
+
+    When accessed as `/accounts/last` it won't return any credit card or subscription resource in the JSON, unless it is given explicitly as `/accounts/last?include=credit_cards,subscriptions` (in plural).
+
+    In order for the `json` method to work, a `wrapper_scope` needs to be defined.
+    You can usually define it in your `ApplicationController` as follow:
+
+    ``` ruby
+    def wrapper_scope
+      current_user
+    end
+    ```
+
+  * `errors(resource)` is a method that makes pair with `json(resource)`.
+    It basically receives a resource and render its errors.
+    For instance, `errors(account)` will return `:errors => { :account => account.errors }`;
+
+  * `wrap_array(resources)` as the `json` method accepts extra associations to be included through `params[:include]` we need to be careful to not do `N+1` db queries.
+    This can be fixed by using the `wrap_array` method that will automatically wrap the given array and preload all associations.
+    For instance, you want will to do this in your `index` actions:
+
+    ``` ruby
+    def index
+      json wrap_array(current_user.accounts.active.all)
+    end
+    ```
+
+**Active Record Extensions**
+
+`Lightrail::Wrapper` provides one Active Record extension method called `#slice()`.
+In order to understand what it does, it is easier to look at the source:
+
+``` ruby
+def slice(*keys)
+  keys.map! { |key| key.to_s }
+  attributes.slice(*keys)
+end
+```
+
+This method was used in the example showed above.
+
+
+config.lightrail.*
+------------------
+
+Lightrail adds a `config.lightrail` namespace to your application with two main methods:
+
+  * `remove_session_middlewares!` removes `ActionDispatch::Cookies`,
+  `ActionDispatch::Session::CookieStore` and `ActionDispatch::Flash` middlewares.
+  * `remove_browser_middlewares!` removes the `ActionDispatch::BestStandardsSupport` middleware.

data/Rakefile

@@ -0,0 +1,5 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+Dir["tasks/**/*.task"].each { |task| load task }
+
+task :default => :spec

data/bin/lightrail

@@ -1 +1,2 @@
-require "rails/cli"
+#!/usr/bin/env ruby
+require "lightrail/cli"

data/lib/lightrail.rb

@@ -0,0 +1,2 @@
+require 'lightrail/version'
+require 'lightrail/railtie'

data/lib/lightrail/action_controller/metal.rb

@@ -1,5 +1,4 @@
 require 'lightrail/action_controller/haltable'
-require 'lightrail/action_controller/param'
 
 module Lightrail
   module ActionController
@@ -36,7 +35,6 @@ module Lightrail
       include ::ActionController::Instrumentation
 
       include Haltable
-      include Param
     end
   end
 end

data/lib/lightrail/cli.rb

@@ -0,0 +1,16 @@
+require 'rbconfig'
+require 'rails/script_rails_loader'
+
+# If we are inside a Rails application this method performs an exec and thus
+# the rest of this script is not run.
+Rails::ScriptRailsLoader.exec_script_rails!
+
+require 'rails/ruby_version_check'
+Signal.trap("INT") { puts; exit(1) }
+
+if ARGV.first == 'plugin'
+  ARGV.shift
+  require 'rails/commands/plugin_new'
+else
+  require 'lightrail/commands/application'
+end

data/lib/lightrail/commands/application.rb

@@ -0,0 +1,26 @@
+require 'lightrail/version'
+
+if ['--version', '-v'].include?(ARGV.first)
+  puts "Lightrail #{Lightrail::VERSION}"
+  exit(0)
+end
+
+if ARGV.first != "new"
+  ARGV[0] = "--help"
+else
+  ARGV.shift
+  railsrc = File.join(File.expand_path("~"), ".railsrc")
+  if File.exist?(railsrc)
+    extra_args_string = File.open(railsrc).read
+    extra_args = extra_args_string.split(/\n+/).map {|l| l.split}.flatten
+    puts "Using #{extra_args.join(" ")} from #{railsrc}"
+    ARGV << extra_args
+    ARGV.flatten!
+  end
+end
+
+require 'rubygems' if ARGV.include?("--dev")
+require 'lightrail/generators'
+require 'lightrail/generators/app_generator'
+
+Lightrail::Generators::AppGenerator.start

data/lib/lightrail/generators.rb

@@ -0,0 +1,323 @@
+require 'active_support'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/kernel/singleton_class'
+require 'active_support/core_ext/array/extract_options'
+require 'active_support/core_ext/hash/deep_merge'
+require 'active_support/core_ext/module/attribute_accessors'
+require 'active_support/core_ext/string/inflections'
+
+require 'lightrail/generators/base'
+
+module Lightrail
+  module Generators
+    autoload :Actions,         'rails/generators/actions'
+    autoload :ActiveModel,     'rails/generators/active_model'
+    autoload :Migration,       'rails/generators/migration'
+    autoload :NamedBase,       'rails/generators/named_base'
+    autoload :ResourceHelpers, 'rails/generators/resource_helpers'
+    autoload :TestCase,        'rails/generators/test_case'
+
+    mattr_accessor :namespace
+
+    DEFAULT_ALIASES = {
+      :rails => {
+        :actions => '-a',
+        :orm => '-o',
+        :javascripts => '-j',
+        :javascript_engine => '-je',
+        :resource_controller => '-c',
+        :scaffold_controller => '-c',
+        :stylesheets => '-y',
+        :stylesheet_engine => '-se',
+        :template_engine => '-e',
+        :test_framework => '-t'
+      },
+
+      :test_unit => {
+        :fixture_replacement => '-r',
+      }
+    }
+
+    DEFAULT_OPTIONS = {
+      :rails => {
+        :assets => true,
+        :force_plural => false,
+        :helper => true,
+        :integration_tool => nil,
+        :javascripts => true,
+        :javascript_engine => :js,
+        :orm => false,
+        :performance_tool => nil,
+        :resource_controller => :controller,
+        :scaffold_controller => :scaffold_controller,
+        :stylesheets => true,
+        :stylesheet_engine => :css,
+        :test_framework => false,
+        :template_engine => :erb
+      }
+    }
+
+    def self.configure!(config) #:nodoc:
+      no_color! unless config.colorize_logging
+      aliases.deep_merge! config.aliases
+      options.deep_merge! config.options
+      fallbacks.merge! config.fallbacks
+      templates_path.concat config.templates
+      templates_path.uniq!
+      hide_namespaces(*config.hidden_namespaces)
+    end
+
+    def self.templates_path
+      @templates_path ||= []
+    end
+
+    def self.aliases #:nodoc:
+      @aliases ||= DEFAULT_ALIASES.dup
+    end
+
+    def self.options #:nodoc:
+      @options ||= DEFAULT_OPTIONS.dup
+    end
+
+    # Hold configured generators fallbacks. If a plugin developer wants a
+    # generator group to fallback to another group in case of missing generators,
+    # they can add a fallback.
+    #
+    # For example, shoulda is considered a test_framework and is an extension
+    # of test_unit. However, most part of shoulda generators are similar to
+    # test_unit ones.
+    #
+    # Shoulda then can tell generators to search for test_unit generators when
+    # some of them are not available by adding a fallback:
+    #
+    #   Rails::Generators.fallbacks[:shoulda] = :test_unit
+    #
+    def self.fallbacks
+      @fallbacks ||= {}
+    end
+
+    # Remove the color from output.
+    def self.no_color!
+      Thor::Base.shell = Thor::Shell::Basic
+    end
+
+    # Track all generators subclasses.
+    def self.subclasses
+      @subclasses ||= []
+    end
+
+    # Rails finds namespaces similar to thor, it only adds one rule:
+    #
+    # Generators names must end with "_generator.rb". This is required because Rails
+    # looks in load paths and loads the generator just before it's going to be used.
+    #
+    # ==== Examples
+    #
+    #   find_by_namespace :webrat, :rails, :integration
+    #
+    # Will search for the following generators:
+    #
+    #   "rails:webrat", "webrat:integration", "webrat"
+    #
+    # Notice that "rails:generators:webrat" could be loaded as well, what
+    # Rails looks for is the first and last parts of the namespace.
+    #
+    def self.find_by_namespace(name, base=nil, context=nil) #:nodoc:
+      lookups = []
+      lookups << "#{base}:#{name}"    if base
+      lookups << "#{name}:#{context}" if context
+
+      unless base || context
+        unless name.to_s.include?(?:)
+          lookups << "#{name}:#{name}"
+          lookups << "rails:#{name}"
+        end
+        lookups << "#{name}"
+      end
+
+      lookup(lookups)
+
+      namespaces = Hash[subclasses.map { |klass| [klass.namespace, klass] }]
+
+      lookups.each do |namespace|
+        klass = namespaces[namespace]
+        return klass if klass
+      end
+
+      invoke_fallbacks_for(name, base) || invoke_fallbacks_for(context, name)
+    end
+
+    # Receives a namespace, arguments and the behavior to invoke the generator.
+    # It's used as the default entry point for generate, destroy and update
+    # commands.
+    def self.invoke(namespace, args=ARGV, config={})
+      names = namespace.to_s.split(':')
+      if klass = find_by_namespace(names.pop, names.any? && names.join(':'))
+        args << "--help" if args.empty? && klass.arguments.any? { |a| a.required? }
+        klass.start(args, config)
+      else
+        puts "Could not find generator #{namespace}."
+      end
+    end
+
+    def self.hidden_namespaces
+      @hidden_namespaces ||= begin
+        orm      = options[:rails][:orm]
+        test     = options[:rails][:test_framework]
+        template = options[:rails][:template_engine]
+        css      = options[:rails][:stylesheet_engine]
+
+        [
+          "rails",
+          "#{orm}:migration",
+          "#{orm}:model",
+          "#{orm}:observer",
+          "#{orm}:session_migration",
+          "#{test}:controller",
+          "#{test}:helper",
+          "#{test}:integration",
+          "#{test}:mailer",
+          "#{test}:model",
+          "#{test}:observer",
+          "#{test}:scaffold",
+          "#{test}:view",
+          "#{test}:performance",
+          "#{template}:controller",
+          "#{template}:scaffold",
+          "#{template}:mailer",
+          "#{css}:scaffold",
+          "#{css}:assets",
+          "css:assets",
+          "css:scaffold"
+        ]
+      end
+    end
+
+    class << self
+      def hide_namespaces(*namespaces)
+        hidden_namespaces.concat(namespaces)
+      end
+      alias hide_namespace hide_namespaces
+    end
+
+    # Show help message with available generators.
+    def self.help(command = 'generate')
+      lookup!
+
+      namespaces = subclasses.map{ |k| k.namespace }
+      namespaces.sort!
+
+      groups = Hash.new { |h,k| h[k] = [] }
+      namespaces.each do |namespace|
+        base = namespace.split(':').first
+        groups[base] << namespace
+      end
+
+      puts "Usage: lightrail #{command} GENERATOR [args] [options]"
+      puts
+      puts "General options:"
+      puts "  -h, [--help]     # Print generator's options and usage"
+      puts "  -p, [--pretend]  # Run but do not make any changes"
+      puts "  -f, [--force]    # Overwrite files that already exist"
+      puts "  -s, [--skip]     # Skip files that already exist"
+      puts "  -q, [--quiet]    # Suppress status output"
+      puts
+      puts "Please choose a generator below."
+      puts
+
+      # Print Rails defaults first.
+      rails = groups.delete("rails")
+      rails.map! { |n| n.sub(/^rails:/, '') }
+      rails.delete("app")
+      rails.delete("plugin_new")
+      print_list("rails", rails)
+
+      hidden_namespaces.each {|n| groups.delete(n.to_s) }
+
+      groups.sort.each { |b, n| print_list(b, n) }
+    end
+
+    protected
+
+      # Prints a list of generators.
+      def self.print_list(base, namespaces) #:nodoc:
+        namespaces = namespaces.reject do |n|
+          hidden_namespaces.include?(n)
+        end
+
+        return if namespaces.empty?
+        puts "#{base.camelize}:"
+
+        namespaces.each do |namespace|
+          puts("  #{namespace}")
+        end
+
+        puts
+      end
+
+      # Try fallbacks for the given base.
+      def self.invoke_fallbacks_for(name, base) #:nodoc:
+        return nil unless base && fallbacks[base.to_sym]
+        invoked_fallbacks = []
+
+        Array(fallbacks[base.to_sym]).each do |fallback|
+          next if invoked_fallbacks.include?(fallback)
+          invoked_fallbacks << fallback
+
+          klass = find_by_namespace(name, fallback)
+          return klass if klass
+        end
+
+        nil
+      end
+
+      # Receives namespaces in an array and tries to find matching generators
+      # in the load path.
+      def self.lookup(namespaces) #:nodoc:
+        paths = namespaces_to_paths(namespaces)
+
+        paths.each do |raw_path|
+          ["rails/generators", "generators"].each do |base|
+            path = "#{base}/#{raw_path}_generator"
+
+            begin
+              require path
+              return
+            rescue LoadError => e
+              raise unless e.message =~ /#{Regexp.escape(path)}$/
+            rescue Exception => e
+              warn "[WARNING] Could not load generator #{path.inspect}. Error: #{e.message}.\n#{e.backtrace.join("\n")}"
+            end
+          end
+        end
+      end
+
+      # This will try to load any generator in the load path to show in help.
+      def self.lookup! #:nodoc:
+        $LOAD_PATH.each do |base|
+          Dir[File.join(base, "{rails/generators,generators}", "**", "*_generator.rb")].each do |path|
+            begin
+              path = path.sub("#{base}/", "")
+              require path
+            rescue Exception
+              # No problem
+            end
+          end
+        end
+      end
+
+      # Convert namespaces to paths by replacing ":" for "/" and adding
+      # an extra lookup. For example, "rails:model" should be searched
+      # in both: "rails/model/model_generator" and "rails/model_generator".
+      def self.namespaces_to_paths(namespaces) #:nodoc:
+        paths = []
+        namespaces.each do |namespace|
+          pieces = namespace.split(":")
+          paths << pieces.dup.push(pieces.last).join("/")
+          paths << pieces.join("/")
+        end
+        paths.uniq!
+        paths
+      end
+  end
+end