markbates-gemtronics 0.0.1.20090812182507 → 0.1.0.20090813140240

data/README

@@ -1,3 +1,118 @@
-README
-========================================================================
-gemtronics was developed by: markbates
+=Gemtronics - Simple and Smart Gem Management
+
+Gemtronics is designed to mitigate the pain of gem management for your Ruby applications. It can be used with standalone Ruby libraries or in Rails applications, it doesn't much matter to Gemtronics.
+
+===Installation
+
+Gemtronics is, itself, a RubyGem. So yes, there is on dependency you have to have on your machine before you can use it to manage your other gems for your projects.
+
+  $ sudo gem install gemtronics
+
+Or, if you prefer to live on the edge:
+
+  $ sudo gem install markbates-gemtronics --source=http://gems.github.com
+
+==Usage
+
+Gemtronics comes bundled with a binary that can help make life a little nicer. The binary has three different options, generate, convert, and install.
+
+===Generate
+
+Gemtronics will generate a sample file for you by using the binary, like such:
+
+  $ gemtronics generate
+
+That will output the following into a file called <code>config/gemtronics.rb</code>:
+
+  group(:default) do |g|
+    # g.add('gem name here')
+    # g.add('gem name here', :version => '1.2.3')
+    # g.add('gem name here', :version => '1.2.3', :source => 'http://gems.example.com')
+    # g.add('gem name here', :version => '1.2.3', :source => 'http://gems.example.com', :require => ['file1', 'file2'])
+  end
+
+  group(:production, :dependencies => :default) do |g|
+  end
+
+  group(:development, :dependencies => :default) do |g|
+  end
+
+  group(:test, :dependencies => :development) do |g|
+  end
+
+If you don't like that file path you can tell it where to generate the file for you:
+
+  $ gemtronics generate path/to/my/file.rb
+
+It is encouraged that you use the default path for your file, as it will make it easier for Gemtronics to find it later.
+
+===Convert
+
+On the off chance you are using the old Gemtools project for managing your gems, Gemtronics can easily convert that old school YAML file to the Gemtronics format:
+
+  $ gemtronics convert path/to/my/gems.yml
+
+===Install
+
+Once you have setup your Gemtronics file, more on that in a minute, you can use it to easily install your gems from it:
+
+  $ gemtronics install
+
+Gemtronics will read the <code>config/gemtronics.rb</code> and install all the gems in the <code>:default</code> group. If you would like to specify a different group you can do that like so:
+
+  $ gemtronics install production
+
+If you did not put your file in <code>config/gemtronics.rb</code> you will need to specify the path:
+
+  $ gemtronics install default path/to/my/file.rb
+
+Gemtronics will not install gems again if they already exist on your machine. This makes installation fast and easy!
+
+==Configuring Your Gems
+
+Gemtronics has the concept that gems can be grouped. Why would you want to group your gems? Great question. Perhaps you have a default set of gems that you want to use with your application, you would put them in the <code>default</code> group. In testing and development you might want to include other gems, such as <code>ruby-debug</code>, that you wouldn't want running/installed on your production machines. In this case you would group them in another group that depends on the <code>default</code> group.
+
+Defining a group is very easy:
+
+  group(:default) do |g|
+    g.add('gem1')
+  end
+
+When you add gems to a group you can set all the necessary gem options, or just inherit the default options. See the sample file below, or the rest of the RDOC for more information.
+
+===Rails
+
+Right about now you're saying to yourself, I use the Rails gem management system, why should I use this? Well, because the Rails gem management system is flawed at it's very core. You define your gems in the environment, which means the environment must be loaded to load/install your gems. However, this cause blow up if a gem is not installed when it loads the environment. Plus, why would you want to load the environment just to install gems?
+
+Gemtronics also has the advantage of being an independent system to Rails, which means that you can use it to install Rails for you!
+
+==Sample:
+
+  group(:default) do |g|
+    g.add('gem1')
+    g.add('gem2', :version => '1.2.3')
+    g.add('gem3', :source => 'http://gems.github.com')
+    g.add('gem4', :require => 'gem-four')
+    g.add('gem5', :require => ['gem-five', 'gemfive'])
+    g.add('gem6', :load => false)
+  end
+
+  group(:production, :dependencies => :default) do |g|
+    g.add('gem3', :load => false)
+    g.remove('gem1')
+    g.add('gem4', :source => 'http://gems.example.org')
+  end
+
+  group(:development, :dependencies => :default) do |g|
+    g.add('gem7', :version => '>=1.2.3.4', :load => false, :require => 'gemseven')
+  end
+
+  group(:test, :dependencies => :development, :source => 'http://gems.example.com') do |g|
+    g.add('gem8')
+  end
+
+  group(:staging) do |g|
+    g.add('gem2', :version => '3.2.1')
+    g.dependency(:development)
+    g.add('gem7', :load => true)
+  end

data/lib/gemtronics/gemtronics.rb

@@ -1,8 +1,8 @@
-module Gemtronics
+module Gemtronics # :nodoc:
   
   class << self
     
-    def method_missing(sym, *args)
+    def method_missing(sym, *args) # :nodoc:
       Gemtronics::Manager.instance.send(sym, *args)
     end
     

data/lib/gemtronics/grouper.rb

@@ -1,26 +1,95 @@
 module Gemtronics
+  # This class is yielded up when you create/modify a group.
+  # This class holds all the relevant information about the gems
+  # for the defined group.
+  # 
+  # See Gemtronics::Manager for more details on creating a group.
   class Grouper
+    # The Array of gems belonging to this group.
     attr_accessor :gems
+    # A Hash representing the default options for this group.
     attr_accessor :group_options
     
+    # Creates a new Gemtronics::Grouper class. It takes a Hash
+    # of options that will be applied to all gems added to the group.
+    # These options will be merged with Gemtronics::Manager::GLOBAL_DEFAULT_OPTIONS
+    # 
+    # This also takes a special option <tt>:dependencies</tt> which can
+    # be an Array of other groups to inherit gems from.
+    # 
+    # Example:
+    #   group(:development) do |g|
+    #     g.add('gem1')
+    #   end
+    # 
+    #   group(:test, :dependencies => :development) do |g|
+    #     g.add('gem2')
+    #     g.add('gem3')
+    #   end
+    # 
+    # In this example the <tt>:test</tt> group would
+    # now have the following gems: <tt>gem1, gem2, gem3</tt>
     def initialize(options = {})
       self.gems = []
+      options = {} if options.nil?
       deps = options.delete(:dependencies)
       if deps
         [deps].flatten.each do |dep|
           self.dependency(dep)
         end
       end
-      self.group_options = options
+      self.group_options = Gemtronics::Manager::GLOBAL_DEFAULT_OPTIONS.merge(options)
       self
     end
     
+    # Adds a gem to the group. All that is required is the name of the gem.
+    # 
+    # The following is a list of the options that can be passed in:
+    #   :require # a String or Array of file(s) to be required by the system
+    #   :version # a String representing the version number of the gem.
+    #   :source # a String representing the source URL of where the gem lives
+    #   :load # true/false the files specified by the :require option should be loaded
+    # 
+    # These options get merged with the group options and the global options.
+    # 
+    # Example:
+    #   group(:default, :version => '>=1.0.0') do |g|
+    #     g.add('gem1', :source => 'http://gems.example.com')
+    #     g.add('gem2', :version => '0.9.8')
+    #     g.add('gem3', :require => ['gem-three', 'gem3'], :version => '>2.0.0')
+    #     g.add('gem4', :require => 'gemfour', :load => false)
+    #   end
+    # 
+    #   # => [{:name => 'gem1', :version => '>=1.0.0', :source => 'http://gems.example.com', 
+    #          :require => ['gem1'], :load => true},
+    #         {:name => 'gem2', :version => '0.9.8', :source => 'http://gems.rubyforge.org', 
+    #          :require => ['gem2'], :load => true},
+    #         {:name => 'gem3', :version => '>2.0.0', :source => 'http://gems.rubyforge.org', 
+    #          :require => ['gem-three', 'gem3'], :load => true},
+    #         {:name => 'gem4', :version => '>=1.0.0', :source => 'http://gems.rubyforge.org', 
+    #          :require => ['gemfour']}, :load => false]
     def add(name, options = {})
-      g = Gemtronics::Manager::GLOBAL_DEFAULT_OPTIONS.merge(self.group_options.merge({:name => name.to_s, :require => [name.to_s]}.merge(options)))
+      g = self.group_options.merge({:name => name.to_s, :require => [name.to_s]}.merge(options))
       g[:require] = [g[:require]].flatten
       self.gems << g
     end
     
+    # Removes a gem from the group.
+    # 
+    # Example:
+    #   group(:development) do |g|
+    #     g.add('gem1')
+    #     g.add('gem2')
+    #   end
+    # 
+    #   group(:test, :dependencies => :development) do |g|
+    #     g.add('gem3')
+    #     g.remove('gem2')
+    #     g.add('gem4')
+    #   end
+    # 
+    # In this example the <tt>:test</tt> group would
+    # now have the following gems: <tt>gem1, gem3, gem4</tt>
     def remove(name)
       self.gems.each do |g|
         if g[:name] = name.to_s
@@ -30,6 +99,21 @@ module Gemtronics
       end
     end
     
+    # Injects another groups gems into this group.
+    # 
+    # Example:
+    #   group(:development) do |g|
+    #     g.add('gem1')
+    #   end
+    # 
+    #   group(:test) do |g|
+    #     g.add('gem2')
+    #     g.dependency(:development)
+    #     g.add('gem3')
+    #   end
+    # 
+    # In this example the <tt>:test</tt> group would
+    # now have the following gems: <tt>gem2, gem1, gem3</tt>
     def dependency(name)
       group = Gemtronics::Manager.instance.groups[name.to_sym]
       if group

data/lib/gemtronics/manager.rb

@@ -2,14 +2,29 @@ module Gemtronics
   class Manager
     include Singleton
     
+    # A Hash of the default options that are applied to all the gems.
+    # These options can be overidden at both the group and the individual
+    # gem level.
     GLOBAL_DEFAULT_OPTIONS = {:load => true, :version => '>=0.0.0', :source => 'http://gems.rubyforge.org'}
     
+    # A Hash of all the groups that have been defined.
     attr_accessor :groups
     
-    def initialize
+    def initialize # :nodoc:
       reset!
     end
     
+    # Creates, or reopens a new group of gems. It takes the name of the 
+    # group, and any options you would like all of the gems in that group 
+    # to inherit.
+    # 
+    # Example:
+    #   group(:development, :source => 'http://gems.example.com') do |g|
+    #     g.add('gem1')
+    #     g.add('gem2')
+    #   end
+    # 
+    # For more information see Gemtronics::Grouper
     def group(name, options = {})
       name = name.to_sym
       options = GLOBAL_DEFAULT_OPTIONS.merge(options)
@@ -17,14 +32,63 @@ module Gemtronics
       yield g if block_given?
     end
     
+    # Aliases one gem group to another group.
+    # 
+    # Example:
+    #   group(:development) do |g|
+    #     g.add('gem1')
+    #     g.add('gem2')
+    #   end
+    # 
+    #   alias_group :test, :development
+    # 
+    # The result would be the same as if you had done this:
+    # 
+    #   group(:development) do |g|
+    #     g.add('gem1')
+    #     g.add('gem2')
+    #   end
+    #   group(:test, :dependencies => :development) do |g|
+    #   end
     def alias_group(name, src)
       group(name, :dependencies => src)
     end
     
+    # Reads in a file and sets up the gems appropriately.
+    # The default path is <tt>'<pwd>/config/gemtronics.rb'</tt>
+    # 
+    # See README for an example file.
     def load(file = File.join(FileUtils.pwd, 'config', 'gemtronics.rb'))
       eval(File.read(file), binding)
     end
     
+    # Requires all the gems and the specified files for the group.
+    # It will not require any gems that have the <tt>:load</tt>
+    # options set to <tt>false</tt>
+    # 
+    # Example:
+    #   group(:default) do |g|
+    #     g.add('gem1')
+    #     g.add('gem2', :version => '1.2.3')
+    #     g.add('gem3', :load => false)
+    #     g.add('gem4', :require => 'gem-four')
+    #     g.add('gem5', :require => ['gem-five', 'gemfive'])
+    #     g.add('gem6', :load => false)
+    #   end
+    # 
+    #   Gemtronics.require_gems(:default)
+    # 
+    # In this example it would do the following:
+    # 
+    #   gem('gem1', '>=0.0.0')
+    #   require 'gem1'
+    #   gem('gem2', '1.2.3')
+    #   require 'gem2'
+    #   gem('gem4', '>=0.0.0')
+    #   require 'gem-four'
+    #   gem('gem5', '>=0.0.0')
+    #   require 'gem-five'
+    #   require 'gemfive'
     def require_gems(group = :default, options = {})
       group = self.groups[group.to_sym]
       return if group.nil?
@@ -40,6 +104,25 @@ module Gemtronics
       end
     end
     
+    # This will install only the gems in the group that
+    # are not currently installed in the system.
+    # 
+    # Example:
+    #   group(:default) do |g|
+    #     g.add('gem1')
+    #     g.add('gem2', :version => '1.2.3')
+    #     g.add('gem3', :load => false)
+    #     g.add('gem4', :require => 'gem-four')
+    #     g.add('gem5', :require => ['gem-five', 'gemfive'])
+    #     g.add('gem6', :load => false, :source => 'http://gems.example.com')
+    #   end
+    # 
+    # Assuming gems <tt>gem3, gem4, gem5</tt> are previously installed:
+    # 
+    #   Gemtronics.install_gems(:default)
+    #   # gem install gem1 --source=http://gems.rubyforge.org
+    #   # gem install gem2 --source=http://gems.rubyforge.org --version=1.2.3
+    #   # gem install gem6 --source=http://gems.example.com
     def install_gems(group = :default)
       group = self.groups[group.to_sym]
       return if group.nil?
@@ -55,17 +138,18 @@ module Gemtronics
       end
     end
     
-    def install_all_gems
+    def install_all_gems # :nodoc:
       self.groups.each do |name, value|
         self.install_gems(name)
       end
     end
     
-    def reset!
+    def reset! # :nodoc:
       self.groups = {}
     end
     
-    def gem_installed?(name, version)
+    private
+    def gem_installed?(name, version) # :nodoc:
       begin
         gem(name, version)
         return true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: markbates-gemtronics
 version: !ruby/object:Gem::Version 
-  version: 0.0.1.20090812182507
+  version: 0.1.0.20090813140240
 platform: ruby
 authors: 
 - markbates
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-12 00:00:00 -07:00
+date: 2009-08-13 00:00:00 -07:00
 default_executable: gemtronics
 dependencies: []