templar 0.7.1 → 0.7.2

data/README.md

@@ -7,14 +7,14 @@ Usage
 -----
 
 Once **Templar** is installed and configured, it will automatically keep your local copies of configurations up-to-date. It
-does this by running prior to initialization of the Rails environment.
+does this by running prior to initialization of the Rails (and Capistrano) environment.
 
 The *Example* section below, will give you the best idea of the usage of **Templar**.
 
 Example
 -------
 
-Most of this example is now handled by `rake templar:file[filename]`.
+Most of this example is now handled by `rake templar:file[filename]`, this task is currently only supported by Rails.
 
 This will take you, step by step, through the process of configuring and using **Templar** to manage the database.yml file
 in a Rails application.
@@ -129,9 +129,9 @@ It will also have added some lines to the `.gitignore` file.
 Confguration
 ------------
 
-There are two configuration files for **Templar**.
+There are two types of configuration files for **Templar**.
 
-### config/templar.yml
+### Templar Configuration (config/templar.yml)
 
 The `templar.yml` file is the primary configuration for **Templar**. Most often, you will only need to change the
 `templates` section of this file.
@@ -157,12 +157,7 @@ always_update: false
 data_file: data.yml
 ```
 
-### config/templar/data.sample.yml
-
-This file should contain the default local development environment configuration data. This is used to create the
-`config/templar/data.yml` file for users when they first setup their local development environment for the app.
-
-### config/templar/data.yml
+### Configuration Data (config/templar/data.yml)
 
 This file is ignored by git automatically (as part of the installation process). This should contain the configuration
 for the local development environment.
@@ -182,8 +177,27 @@ database:
 This file contains any of the data that will be inserted into the template configuration files. Such that if you have a
 `database.yml.erb` file managed by **Templar**, you can populate the data from the database block in the `data.yml` file.
 
+### Configuration Data (config/templar/data.sample.yml)
+
+This file should contain the default local development environment configuration data. This is used to create the
+`config/templar/data.yml` file for users when they first setup their local development environment for the app.
+
+
 See *Example* for more info.
 
+Capistrano
+----------
+
+The Capistrano integration is used for one specific purpose. It is rare and few will need it.
+
+You can use Templar in conjunction with Capistrano to manage templated configuration files which you will be pushing
+directly to the server using Capistrano's push method.
+
+This allows you to have all the same functionality of templar, when running in something other than Ruby and Rails.
+
+I use this to manage properties files for a J2EE application in SVN, and use Capistrano to push the properties
+files to the servers
+
 TODO
 ----
 

data/lib/templar/capistrano.rb

@@ -1,6 +1,12 @@
 require 'templar'
 require 'awesome_print'
 
+##
+# Capistrano integration
+# Generally you will not need to use this, unless you specifically want to use
+# capistrano to deploy templar templates directly to a server (rather than
+# using deploy via remote cache)
+
 configuration = Capistrano::Configuration.respond_to?(:instance) ?
     Capistrano::Configuration.instance(:must_exist) :
     Capistrano.configuration(:must_exist)

data/lib/templar/config.rb

@@ -1,19 +1,16 @@
-# stolen from mjijackson
-# http://mjijackson.com/2010/02/flexible-ruby-config-objects
-
+##
+# Templar is a configuration template manager.
 module Templar
+  ##
+  # Basic, easy-to-use configuration object.
+  # @note would like to use Ribbon, but it only supports 1.9.x from what I've seen.
+  # @see http://mjijackson.com/2010/02/flexible-ruby-config-objects
   class Config
     def initialize(data={ })
       @data = { }
       update!(data)
     end
 
-    def update!(data)
-      data.each do |key, value|
-        self[key] = value
-      end
-    end
-
     def [](key)
       @data[key.to_sym]
     end
@@ -38,5 +35,11 @@ module Templar
         self[sym]
       end
     end
+
+    def update!(data)
+      data.each do |key, value|
+        self[key] = value
+      end
+    end
   end
 end

data/lib/templar/engine.rb

@@ -1,4 +1,8 @@
+##
+# Templar is a configuration template manager.
 module Templar
+  ##
+  # Rails 3.x integrations
   class Engine < Rails::Engine
     engine_name "templar"
   end

data/lib/templar/processor.rb

@@ -1,11 +1,20 @@
 require 'erubis'
 require 'templar/config'
 
+##
+# Templar is a configuration template manager.
 module Templar
+  ##
+  # This is the implementation of template processing.
   class Processor
+    # @return [Templar::Config] contains the templar configuration data, usually config/templar.yml
     attr_accessor :config
+    # @return [Templar::Config] contains the data loaded from the YAML data file, usually config/templar/data.yml
     attr_accessor :data
 
+    ##
+    # Get a new processor
+    # @param [Hash] config_overrides these values will be merged on top of the defaults.
     def initialize(config_overrides = {})
       {:print_format => "  templar: (update: %s) %s => %s"}.merge(config_overrides)
       yaml_hash = YAML.load_file('config/templar.yml') || {}
@@ -18,6 +27,9 @@ module Templar
       @data      = Templar::Config.new(data_hash)
     end
 
+    ##
+    # Process configuration templates
+    # @raise [TemplarException] Raises exception when it cannot find files
     def process
       @use_environments = @config.use_environments
       @environment = @config.environment
@@ -26,14 +38,26 @@ module Templar
       process_templates
     end
 
+
+    ##
+    # Determine the data file to use.
+    # If #{directory}/data.yml exists, use that, otherwise use #{directory}/data.sample.yml
+    # data.sample.yml should contain non-development template data.
     def data_file
       @data_file ||= File.exists?("#{@directory}/data.yml") ? "#{@directory}/data.yml" : "#{@directory}/data.sample.yml"
     end
 
+    ##
+    # Load the template configuration data, usually config/templar/data.yml
+    # @return [Templar::Config] load the template configuration data.
     def load_data
       @data ||= Templar::Config.new(YAML::load(File.open(data_file)))
     end
 
+    ##
+    # Process all defined template files
+    #
+    # @raise [TemplarException] Raises exception when it cannot find files
     def process_templates
       if File.exists?(data_file) && @templates.count
 
@@ -45,6 +69,11 @@ module Templar
       end
     end
 
+    ##
+    # Process template file
+    # @param [String] source The source (template) file.
+    # @param [String] dest The destination for the processed file.
+    # @raise [TemplarException] Raises exception when it cannot find files
     def process_template(source, dest)
       update = update_file?(source, dest)
       puts @config.print_format % [update, source, dest]
@@ -58,13 +87,25 @@ module Templar
       end
     end
 
+    ##
+    # Check to see if we should update a file
+    #
+    # always_update will force the file to always be updated
+    # checking if data_file is newer verifies that files get regenerated when every the data file changes
+    # otherwise, check to see if the template file has been modified more recently than the destination
+    #
+    # @param [String] source The source (template) file.
+    # @param [String] dest The destination for the processed file.
+    # @return [Boolean] true if we should update the file
     def update_file?(source, dest)
-      # always_update will force the file to always be updated
-      # checking if data_file is newer verifies that files get regenerated when every the data file changes
-      # otherwise, check to see if the template file has been modified more recently than the destination
       @config.always_update == true || template_newer?(@data_file, dest) == true || template_newer?(source, dest) == true
     end
 
+    ##
+    # Check to see if source is newer than the destination.
+    # @param [String] source The source (template) file.
+    # @param [String] dest The destination for the processed file.
+    # @return [Boolean] true if source is newer or destination does not exist.
     def template_newer?(source, dest)
       return true unless File.exists?(dest)
       File.mtime(source) > File.mtime(dest)

data/lib/templar/version.rb

@@ -3,7 +3,7 @@ if !defined?(Templar::VERSION)
     module Version #:nodoc:
       MAJOR = 0
       MINOR = 7
-      TINY  = 1
+      TINY  = 2
 
       STRING = [MAJOR, MINOR, TINY].join('.')
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: templar
 version: !ruby/object:Gem::Version 
-  hash: 1
+  hash: 7
   prerelease: 
   segments: 
   - 0
   - 7
-  - 1
-  version: 0.7.1
+  - 2
+  version: 0.7.2
 platform: ruby
 authors: 
 - Shawn Catanzarite
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-04-23 00:00:00 Z
+date: 2012-04-27 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rake
@@ -46,7 +46,7 @@ dependencies:
   prerelease: false
   requirement: *id002
 - !ruby/object:Gem::Dependency 
-  name: sqlite3
+  name: yard
   version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
@@ -59,6 +59,20 @@ dependencies:
   type: :development
   prerelease: false
   requirement: *id003
+- !ruby/object:Gem::Dependency 
+  name: sqlite3
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  prerelease: false
+  requirement: *id004
 description: "[config] templar allows you to manage development environment configuration files as templates."
 email: 
 - scatanzarite@gmail.com
@@ -176,3 +190,4 @@ test_files:
 - test/dummy/script/rails
 - test/templar_test.rb
 - test/test_helper.rb
+has_rdoc: