rails_apps_composer 1.0.0

data/README.textile

@@ -0,0 +1,313 @@
+h1. Rails Apps Composer Gem
+
+A gem with recipes to create Rails application templates you can use to generate Rails starter apps. Creates ready-to-run Rails web applications. Makes it easy to create and maintain a starter app using your own preferred options.
+
+h4. Based on Michael Bleigh's RailsWizard Gem
+
+The rails_apps_composer gem is a fork of "Michael Bleigh's RailsWizard gem":https://github.com/intridea/rails_wizard (see credits below). The purpose of this fork is to provide recipes for ready-to-run Rails starter apps. Several recipes provided by the rails_apps_composer gem are different from those provided by the rails_wizard gem. Applications generated with the rails_apps_composer gem are more complete; for example, they may include a home page with sign-in, sign-out navigation links.
+
+Any issues? Please create a "GitHub issue":http://github.com/RailsApps/rails_apps_composer/issues.
+
+h2. !http://twitter-badges.s3.amazonaws.com/t_logo-a.png(Follow on Twitter)!:http://www.twitter.com/rails_apps Follow on Twitter !http://railsapps.github.com/images/mailing-list-icon.jpg(Join the Mailing List)!:http://eepurl.com/dQx3o Join the Mailing List
+
+Follow the project on Twitter: "http://twitter.com/rails_apps":http://twitter.com/rails_apps. Tweet some praise if you like what you've found.
+
+<a href="http://eepurl.com/dQx3o">Join the email list</a> (low volume, announcements only) for project updates and my tips about Rails resources.
+
+h2. Suggested Use
+
+Any developer can quickly generate a Rails web application using the @rails new@ command. In practice, experienced Rails developers typically add an assortment of useful additional packages (gems) before beginning development of any web application. A developer often uses the same set of packages to get started and may create a "starter app" that can be copied and reused for any new project.
+
+It can be a hassle to integrate some of the most commonly used gems, particularly when new versions are released and there are minor "gotchas" that interfere with gems working together. Despite the apparent convenience of creating a starter app, it can be time consuming to maintain and update a starter app as component packages evolve. This project aims to simplify the process of building and maintaining a starter app by providing mix-and-match recipes to assemble the most commonly used Rails packages.
+
+If you use this gem to create your Rails starter app, you can expect the pieces to work together. If they don't, you can report problems and look for identified "issues":http://github.com/RailsApps/rails_apps_composer/issues (and perhaps contributed fixes).
+
+If you use this gem to create a reusable application template (see the instructions below), you can check for changes to recipes here and reassemble your application template as packages evolve.
+
+h2. Dependencies
+
+Before generating a new Rails app, you will need:
+
+* The Ruby language (version 1.8.7 or 1.9.2)
+* Rails (version 3.0.4 or newer)
+
+I recommend installing rvm, the "Ruby Version Manager":http://rvm.beginrescueend.com/, to manage multiple versions of Rails.
+
+If you are using rvm, you can see a list of the Ruby versions currently installed:
+@$ rvm list@
+
+Check that appropriate versions of Ruby and Rails are installed in your development environment:
+@$ ruby -v@
+@$ rails -v@
+
+h2. Installation
+
+Installation is simple:
+
+@$ gem install rails_apps_composer@
+
+h2. Usage
+
+h4. List Recipes
+
+You can display a list of recipes:
+
+@$ rails_apps_composer list@
+
+You'll find more details about the available recipes by browsing the repository "recipes directory":https://github.com/RailsApps/rails_apps_composer/tree/master/recipes. 
+
+h4. Generate a Starter App
+
+There are two ways to use the rails_apps_composer gem to generate a starter app.
+
+If you want to build a starter app for one-time use, you can build an application by providing a list of recipes with the @-r@ option. This will automatically generate an application using the specified recipes.
+
+If you want to create and save an application template that you can reuse as needed to "clone" identical starter apps, you can download the rails_apps_composer project, customize recipes as needed, and use a @rake@ task to save a reusable application template file.
+
+Each of these approaches is described below.
+
+h2. Make Your Own Starter App for One-Time Use
+
+h4. Select Recipes
+
+You can mix and match recipes to create your own customized starter app. Browse the repository "recipes directory":https://github.com/RailsApps/rails_apps_composer/tree/master/recipes to see what is available. Then provide your list of recipes to the rails_apps_composer gem using the @-r@ option and generate an app as needed. Here's an example that creates a simple app using jquery and haml:
+
+<pre>
+$ rails_apps_composer new APP_NAME -r jquery haml
+</pre>
+
+To build the "rails3-mongoid-devise":http://github.com/RailsApps/rails3-mongoid-devise/ example application, run the command:
+
+<pre>
+$ rails_apps_composer new APP_NAME -r jquery haml rspec cucumber mongoid action_mailer devise add_user home_page home_page_users seed_database users_page css_setup application_layout devise_navigation cleanup ban_spiders git
+</pre>
+
+h2. Make Your Own Starter App with a Reusable Application Template
+
+You can modify the recipes and save an application template that creates your own customized starter app.
+
+First, you'll need to make your own copy of the rails_apps_composer gem.
+
+@$ git clone git://github.com/RailsApps/rails_apps_composer.git@
+
+@$ cd rails_apps_composer@
+
+The "mg":https://github.com/sr/mg "minimal gem" is required for development of the rails_apps_composer gem. Several other gems are needed as well:
+
+@$ gem install i18n activesupport thor rspec mg@
+
+h4. Customize the Recipes
+
+Modify or write new recipes as you wish (see below for details about writing recipes). You can run @rake spec@ to make sure your recipes conform to the required syntax.
+
+h4. Save the Application Template
+
+The rails_apps_composer gem creates an application template as an intermediate step before generating an application. You can generate and save the application template. Here's an example of generating an application template and saving the template to a file:
+
+<pre>
+$ rake print --silent RECIPES=recipe1,recipe2 > ~/Desktop/template.txt
+</pre>
+
+If you don't include the @--silent@ option, the rake task will generate the application template with an extraneous first line. Open the template file and remove the first line if you encounter this problem.
+
+The rails_apps_composer gem creates an application template that can be used by the @rails new@ command with the @-m@ option. For example:
+
+<pre>
+$ rails new testapp -m ~/Desktop/template.txt
+</pre>
+
+You can specify the @-T -O -J@ flags as needed to skip Test::Unit files and Active Record files. For Rails 3.0, you can also specify the @-J@ flag to skip Prototype files.
+
+That's all it takes. You'll have a ready-to-customize Rails web application in minutes.
+
+h4. Template for Rails 3 + Devise + RSpec + Cucumber
+
+To build a reusable application template for the "rails3-devise-rspec-cucumber":http://github.com/RailsApps/rails3-devise-rspec-cucumber/ example application, run the command:
+
+<pre>
+$ rake print --silent RECIPES=jquery,haml,rspec,cucumber,action_mailer,devise,add_user,home_page,home_page_users,seed_database,users_page,css_setup,application_layout,devise_navigation,cleanup,ban_spiders,git > ~/Desktop/template.txt
+</pre>
+
+Then generate the application using the @-T@ flag. Add the @-J@ flag for Rails 3.0.
+
+<pre>
+$ rails new testapp -m ~/Desktop/template.txt -T -J
+</pre>
+
+h4. Template for Rails 3 + Mongoid + Devise
+
+To build a reusable application template for the "rails3-mongoid-devise":http://github.com/RailsApps/rails3-mongoid-devise/ example application, run the command:
+
+<pre>
+$ rake print --silent RECIPES=jquery,haml,rspec,cucumber,mongoid,action_mailer,devise,add_user,home_page,home_page_users,seed_database,users_page,css_setup,application_layout,devise_navigation,cleanup,ban_spiders,git > ~/Desktop/template.txt
+</pre>
+
+Then generate the application using the @-T -O@ flags. Add the @-J@ flag for Rails 3.0.
+
+<pre>
+$ rails new testapp -m ~/Desktop/template.txt -T -O -J
+</pre>
+
+h4. Template for Rails 3 + Mongoid + OmniAuth
+
+To build a reusable application template for the "rails3-mongoid-omniauth":http://github.com/RailsApps/rails3-mongoid-omniauth/ example application, run the command:
+
+<pre>
+$ rake print --silent RECIPES=jquery,haml,rspec,cucumber,mongoid,seed_database,add_user,omniauth,home_page,home_page_users,css_setup,application_layout,navigation,users_page,omniauth_email,cleanup,ban_spiders,git > ~/Desktop/template.txt
+</pre>
+
+Then generate the application using the @-T -O@ flags. Add the @-J@ flag for Rails 3.0.
+
+<pre>
+$ rails new testapp -m ~/Desktop/template.txt -T -O -J
+</pre>
+
+h2. The Recipes
+
+The following recipes are available.
+
+h4. Recipes for General Use
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "action_mailer.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/action_mailer.rb          | Changes ActionMailer defaults             | none               | dkehoe |
+| "ban_spiders.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/ban_spiders.rb           | Ban spiders from your site by changing robots.txt | none | dkehoe |
+| "cleanup.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/cleanup.rb               | Remove unnecessary files, add READMEs | none | fnichol, dkehoe |
+| "git.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/git.rb                    | Add a gitignore file, initialize new Git repo | Git | fnichol, dkehoe |
+| "sample_readme.textile":https://github.com/RailsApps/rails-template-recipes/raw/master/sample_readme.textile     | Placeholder text for a README file (textile markup) | none | dkehoe |
+| "sample_readme.txt":https://github.com/RailsApps/rails-template-recipes/raw/master/sample_readme.txt         | Placeholder text for a README file (ASCII) | none | dkehoe |
+
+h4. Recipes for Testing and BDD
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "rspec.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/rspec.rb          | Install RSpec | none | rbrooker, dkehoe |
+| "cucumber.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/cucumber.rb          | Install Cucumber | none | rbrooker, dkehoe |
+
+h4. Recipes for Mongoid
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "mongoid.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/mongoid.rb        | Installs Mongoid with the bson_ext gem | Mongoid | dkehoe |
+
+h4. Recipes for jQuery
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "jquery.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/jquery_fix.rb             | Installs jQuery | none | dkehoe |
+
+h4. Recipes for Devise
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "devise.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/devise.rb          | Installs Devise  | none | dkehoe |
+
+h4. Recipes for OmniAuth
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "omniauth.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/omniauth.rb        | OmniAuth for authentication | none | dkehoe |
+| "omniauth_email.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/omniauth_email.rb        | Requests a new uer's email address when authenticating with Twitter, etc. | OmniAuth | dkehoe |
+
+h4. Recipes for Haml
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "haml.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/haml.rb          | Installs Haml | none | dkehoe |
+
+h4. Recipes for the Application Layout
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "application_layout.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/application_layout.rb     | Adds application layout with flash messages | ERB or Haml      | dkehoe |
+| "css_setup.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/css_setup.rb              | Add a stylesheet with styles for a horizontal menu and flash messages | none | dkehoe |
+
+h4. Recipes for the Example Apps
+
+|_. File                    |_.                                  |_. Dependencies     |_. Authors |
+| "add_user.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/add_user.rb          | adds User model for use with OmniAuth or Devise | none | dkehoe |
+| "navigation.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/_navigation.rb      | Add navigation links to the default application layout | none | dkehoe |
+| "devise_navigation.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/devise_navigation.rb      | Add navigation links to the default application layout | Devise | dkehoe |
+| "home_page.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/home_page.rb              | Create a home controller, route, and simple view | ERB or Haml | dkehoe |
+| "home_page_users.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/home_page_users.rb        | Modify a home page to display a list of users | Home controller, User model, ERB or Haml | dkehoe |
+| "seed_database.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/seed_database.rb          | Adds a db/seeds.rb file to initialize a database | none | dkehoe |
+| "users_page.rb":https://github.com/RailsApps/rails_apps_composer/blob/master/recipes/users_page.rb             | Add a home page containing links to User pages | User model, ERB or Haml | dkehoe |
+
+h2. Writing New Recipes
+
+You can find the rails_apps_composer recipe collection in the GitHub repository's "recipes directory":https://github.com/RailsApps/rails_apps_composer/tree/master/recipes. If you find errors or improve a recipe you can contribute to the project by submitting a pull request or creating a "Github issue":http://github.com/RailsApps/rails_apps_composer/issues.
+
+h4. Rails Wizard Basics
+
+For more information on all available options for authoring recipes that can be read by the rails_wizard or rails_apps_composer gems, please see the "wiki for Michael Bleigh's  RailsWizard gem":https://github.com/intridea/rails_wizard/wiki.
+
+Recipes are made of up *template code* and *YAML back-matter* stored in a ruby file. The @__END__@ parsing convention is used so that each recipe is actually a valid, parseable Ruby file. The structure of a recipe looks something like this:
+
+<pre>
+gem 'supergem'
+
+after_bundler do
+  generate &quot;supergem:install&quot;
+end
+
+__END__
+
+category: templating
+name: SuperGem
+description: Installs SuperGem which is useful for things
+author: mbleigh
+</pre>
+
+h4. Rails Apps Composer Differences
+
+The rails_apps_composer gem is very similar to the rails_wizard gem, with one significant difference. The rails_wizard gem allows specification of execution order for recipes with @run_after@ and @run_after@ configuration flags. The rails_apps_composer gem does not support @run_after@ or @run_after@; instead, the order which you provide the recipes sets the execution order. This makes it easier to chain a series of recipes in the order you prefer. For example,
+
+<pre>
+$ rails_apps_composer new APP_NAME -r git jquery haml
+</pre>
+
+installs jquery before haml.
+
+h4. Recipe Differences
+
+Several recipes provided by the rails_apps_composer gem are different from those provided by the rails_wizard gem.
+
+h4. Rails Wizard RSpec Tests
+
+The gem has RSpec tests that automatically validate each recipe in the repository, so you should run @rake spec@ as a basic syntax check. Note that these don't verify that your recipe code itself works, just that the gem could properly parse and understand your recipe file.
+
+h4. How It Works
+
+Rails generators can use any methods provided by the "Thor::Actions":http://rdoc.info/github/wycats/thor/master/Thor/Actions module. The flexibility of mixing "recipes" for application templates comes from use of the @apply@ method from the Thor::Actions module. Given a web address or a local filepath, the "apply method":http://rdoc.info/github/wycats/thor/master/Thor/Actions#apply-instance_method loads and executes a file within the context of the generator script.
+
+h2. Documentation and Support
+
+This is the only documentation.
+
+h4. Writing Recipes
+
+To understand the code in these templates, take a look at "Thor::Actions":http://rdoc.info/github/wycats/thor/master/Thor/Actions. Your recipes can use any methods provided by "Thor::Actions":http://rdoc.info/github/wycats/thor/master/Thor/Actions or "Rails::Generators::Actions":http://railsapi.com/doc/rails-v3.0.3/classes/Rails/Generators/Actions.html.
+
+h4. About Rails Application Templates
+
+"Cooking Up A Custom Rails 3 Template (11 Oct 2010) by Andrea Singh":http://blog.madebydna.com/all/code/2010/10/11/cooking-up-a-custom-rails3-template.html
+"Rails Application Templates (16 Sept 2010) by Collin Schaafsma":http://quickleft.com/blog/rails-application-templates
+"Application templates in Rails 3 (18 Sept 2009) by Ben Scofield":http://benscofield.com/2009/09/application-templates-in-rails-3/
+"Railscasts: App Templates in Rails 2.3 (9 Feb 2009) by Ryan Bates":http://railscasts.com/episodes/148-app-templates-in-rails-2-3
+"Rails templates (4 Dec 2008) by Pratik Naik":http://m.onkey.org/rails-templates
+
+h2. Issues
+
+Any issues? Please create a "GitHub issue":http://github.com/RailsApps/rails_apps_composer/issues.
+
+h2. Credits
+
+This project is based on "Michael Bleigh's RailsWizard gem":https://github.com/intridea/rails_wizard. The original idea for a RailsWizard and the innovative implementation is the work of Michael Bleigh.
+
+"Fletcher Nichol's":http://silversky.ca/ project  "fnichol/rails-template-recipes":https://github.com/fnichol/rails-template-recipes provides the basis for several recipes.
+
+RSpec, Cucumber, and Yard recipes were contributed by "Ramon Brooker":http://cogniton-mind.tumblr.com/.
+
+Additional recipes by Daniel Kehoe, "http://danielkehoe.com/":http://danielkehoe.com/.
+
+Is the gem useful to you? Follow the project on Twitter:
+"http://twitter.com/rails_apps":http://twitter.com/rails_apps
+and tweet some praise. I'd love to know you were helped out by the gem.
+
+h2. License
+
+h4. MIT License
+
+The rails_apps_composer gem and its recipes are distributed under the MIT License.

data/bin/rails_apps_composer

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+$:.push File.dirname(__FILE__) + '/../lib'
+
+require 'rubygems'
+require 'rails_wizard/command'
+
+RailsWizard::Command.start

data/lib/rails_wizard.rb

@@ -0,0 +1,10 @@
+require 'rails_wizard/recipes'
+require 'rails_wizard/recipe'
+require 'rails_wizard/config'
+require 'rails_wizard/template'
+
+Dir[File.dirname(__FILE__) + '/../recipes/*.rb'].each do |path|
+  key = File.basename(path, '.rb')
+  recipe = RailsWizard::Recipe.generate(key, File.open(path))
+  RailsWizard::Recipes.add(recipe)
+end

data/lib/rails_wizard/command.rb

@@ -0,0 +1,79 @@
+require 'rails_wizard'
+require 'thor'
+
+module RailsWizard
+  class Command < Thor
+    include Thor::Actions
+    desc "new APP_NAME", "create a new Rails app"
+    method_option :recipes, :type => :array, :aliases => "-r"
+    def new(name)
+      if options[:recipes]
+        run_template(name, options[:recipes])
+      else
+        @recipes = []
+
+        while recipe = ask("#{print_recipes}#{bold}Which recipe would you like to add? #{clear}#{yellow}(blank to finish)#{clear}")
+          if recipe == ''
+            run_template(name, @recipes)
+            break
+          elsif RailsWizard::Recipes.list.include?(recipe)
+            @recipes << recipe
+            puts
+            puts "> #{green}Added '#{recipe}' to template.#{clear}"
+          else
+            puts
+            puts "> #{red}Invalid recipe, please try again.#{clear}"
+          end
+        end
+      end
+    end
+
+    desc "list [CATEGORY]", "list available recipes (optionally by category)"
+    def list(category = nil)
+      if category
+        recipes = RailsWizard::Recipes.for(category).map{|r| RailsWizard::Recipe.from_mongo(r) }
+      else
+        recipes = RailsWizard::Recipes.list_classes
+      end
+
+      recipes.each do |recipe|
+        puts recipe.key.ljust(15) + "# #{recipe.description}"
+      end
+    end
+
+    no_tasks do
+      def cyan; "\033[36m" end
+      def clear; "\033[0m" end
+      def bold; "\033[1m" end
+      def red; "\033[31m" end
+      def green; "\033[32m" end
+      def yellow; "\033[33m" end
+
+      def print_recipes
+        puts
+        puts
+        puts
+        if @recipes && @recipes.any?
+          puts "#{green}#{bold}Your Recipes:#{clear} " + @recipes.join(", ")
+          puts
+        end
+        puts "#{bold}#{cyan}Available Recipes:#{clear} " + RailsWizard::Recipes.list.join(', ')
+        puts
+      end
+
+      def run_template(name, recipes)
+        puts
+        puts
+        puts "#{bold}Generating and Running Template..."
+        puts
+        file = Tempfile.new('template')        
+        template = RailsWizard::Template.new(recipes)
+        file.write template.compile
+        file.close
+        system "rails new #{name} -m #{file.path} #{template.args.join(' ')}"
+      ensure
+        file.unlink
+      end
+    end
+  end
+end

data/lib/rails_wizard/config.rb

@@ -0,0 +1,86 @@
+require 'active_support/ordered_hash'
+
+module RailsWizard
+  class Config
+    attr_reader :questions
+
+    def initialize(schema)
+      @questions = ActiveSupport::OrderedHash.new
+      schema.each do |hash| 
+        key = hash.keys.first
+        details = hash.values.first
+
+        kind = details['type']
+        raise ArgumentError, "Unrecognized question type, must be one of #{QUESTION_TYPES.keys.join(', ')}" unless QUESTION_TYPES.keys.include?(kind)
+        @questions[key] = QUESTION_TYPES[kind].new(details)
+      end
+    end
+
+    def compile(values = {})
+      result = []
+      result << "config = #{values.inspect}"
+      @questions.each_pair do |key, question|
+        result << "config['#{key}'] = #{question.compile} unless config.key?('#{key}')"
+      end
+      result.join("\n")
+    end
+
+    class Prompt
+      attr_reader :prompt, :details
+      def initialize(details)
+        @details = details
+        @prompt = details['prompt']
+      end
+
+      def compile
+        "#{question} if #{conditions}"
+      end
+
+      def question
+        "ask_wizard(#{prompt.inspect})"
+      end
+
+      def conditions
+        [config_conditions, recipe_conditions].join(' && ')
+      end
+
+      def config_conditions
+        if details['if']
+          "config['#{details['if']}']"
+        elsif details['unless']
+          "!config['#{details['unless']}']"
+        else
+          'true'
+        end
+      end
+
+      def recipe_conditions
+        if details['if_recipe']
+          "recipe?('#{details['if_recipe']}')"
+        elsif details['unless_recipe']
+          "!recipe?('#{details['unless_recipe']}')"
+        else
+          'true'
+        end
+      end
+    end
+
+    class TrueFalse < Prompt
+      def question 
+        "yes_wizard?(#{prompt.inspect})"
+      end
+    end
+
+    class MultipleChoice < Prompt
+      def question
+        "multiple_choice(#{prompt.inspect}, #{@details['choices'].inspect})"
+      end 
+    end
+
+    QUESTION_TYPES = {
+      'boolean' => TrueFalse,
+      'string' => Prompt,
+      'multiple_choice' => MultipleChoice
+    }
+  end
+end