@@ -4,7 +4,7 @@ require 'plow/core_ext/object'
require 'plow/errors'
require 'plow/application'
-# Project namespace
+# Library namespace
class Plow
# Current stable deployed version
VERSION = "0.1.0"
lib/plow.rb
@@ -2,8 +2,11 @@
require 'plow/generator'
class Plow
- # With a single public method (i.e. `launch`), `Plow::Application` is the main class of and the
- # point of execution for the library.
+ # It's probably no surprise that `Plow::Application` is an **application** class.
+ #
+ # With a single public method, `.launch`, it has the distinct honor of being the point of
+ # execution for the library. As described further in the documentation, it designed to
+ # accept and parse raw command-line arguments (i.e. the `ARGV` constant).
#
# @see Plow::Application.launch
class Application
@@ -12,18 +15,21 @@ class Plow
# `Plow::Application` is as follows:
#
# 1. Output a version stamp.
- # 2. Ensure at least 2 arguments are provided, aborting with a usage message if not.
- # 3. Parse user provided arguments.
+ # 2. Ensure at least 2 arguments are provided or aborting execution with a usage message.
+ # 3. Parse the user-supplied arguments.
# 4. Start a new `Plow::Generator` while handling any library specific exceptions raised.
#
- # @return [Number] Success will return 0, while failure will most likely return a number > 0.
- # @overload launch(user_name, site_name, *site_aliases)
- # In addition to the user_name and site_aliases, an array of n site_aliases are also
- # provided by the user.
- # @param [String] user_name Name of a Linux system account user (e.g. steve)
- # @param [String] site_name Name of the web-site (e.g. www.apple.com)
- # @param [splat] *site_aliases (Optional) List of alias names of the web-site
- # (e.g. apple.com)
+ # @example A simple executable file (assume a working Ruby $LOAD_PATH)
+ # #!/usr/bin/env ruby1.9
+ # require 'plow'
+ # Plow::Application.launch(*ARGV)
+ #
+ # @param [Array] *arguments A splatted `Array` of user-specified, command-line arguments.
+ # At least 2 arguments must be provided.
+ # @return [Number] Success returns 0, while failure results in any raised `Exception`. :(
+ # @raise [SystemExit] Raised when a critical, library-specific exception is rescued and
+ # executation must be terminiated.
+ # @see http://www.ruby-doc.org/ruby-1.9/classes/SystemExit.html
def launch(*arguments)
puts version_stamp
lib/plow/application.rb
@@ -12,12 +12,12 @@ class Plow
# `ERB` object for evaluation within a template.
#
# @example Sample template file at /path/to/a/template/file.txt'
- # My hero is <%= @first_name %> <%= @last_name %>.
+ # <%= @first_name %> <%= @last_name %> invented the Universe.
#
# @example Evaluating an `ERB` template file with a `BindingStruct` context
# template = ERB.new(File.read('/path/to/a/template/file.txt'))
# context = Plow::BindingStruct.new({ first_name: 'Carl', last_name: 'Sagan' })
- # result = template.result(context.get_binding) #=> My hero is Carl Sagan.
+ # result = template.result(context.get_binding) #=> Carl Sagan invented the Universe.
#
# @see http://www.ruby-doc.org/ruby-1.9/classes/Binding.html
# @see http://www.ruby-doc.org/ruby-1.9/classes/ERB.html
lib/plow/binding_struct.rb
@@ -1,6 +1,6 @@
# encoding: UTF-8
-# Carefully adding methods the the base `Object` class.
+# Mindfully expanding the base `Object` class with sensible methods
class Object
# An object is blank if it‘s false, empty, or a whitespace string.
# For example, "", " ", nil, [], and {} are blank.
lib/plow/core_ext/object.rb
@@ -2,13 +2,14 @@
class Plow
# In order to load without a syntax error, this file needs to be compatible with ruby >= 1.8.6
+ # Dependencies are a snapshot in time
class Dependencies
REQUIRED_RUBY_VERSION = '1.9.1'
unless RUBY_VERSION >= REQUIRED_RUBY_VERSION
abort <<-ERROR
- This library requires at least Ruby #{REQUIRED_RUBY_VERSION}, but you're using #{RUBY_VERSION}.
- Please see http://www.ruby-lang.org/
+This library requires at least Ruby #{REQUIRED_RUBY_VERSION}, but you're using #{RUBY_VERSION}.
+Please see http://www.ruby-lang.org/
ERROR
end
@@ -20,6 +21,7 @@ class Plow
:bluecloth => '2.0.5'
}
+ # Thanx rspec for bucking the pattern :(
FILE_NAME_TO_GEM_NAME = {
:spec => :rspec
}
@@ -39,6 +41,10 @@ class Plow
end
end
+ # Attaches a `Proc` to `Kernel#at_exit`.
+ #
+ # @param [String] description A message to be prefixed to the warning errors
+ # @see http://www.ruby-doc.org/ruby-1.9/classes/Kernel.html#M002637
def self.warn_at_exit(description = 'The following dependencies could not be found:')
at_exit do
unless @@development_error_messages.empty?
lib/plow/dependencies.rb
@@ -1,27 +1,35 @@
# encoding: UTF-8
class Plow
+ # Should be raised when the current process is owned by a non-root user.
class NonRootProcessOwnerError < StandardError
end
+ # Should be raised when the user-supplied system user name is invalid.
class InvalidSystemUserNameError < StandardError
end
+ # Should be raised when the user-supplied web-site name is invalid.
class InvalidWebSiteNameError < StandardError
end
+ # Should be raised when the user-supplied web-site alias is invalid.
class InvalidWebSiteAliasError < StandardError
end
+ # Should be raised when the user-supplied system user name is reserved.
class ReservedSystemUserNameError < StandardError
end
+ # Should be raised when the user-supplied system user name is not found when it should be.
class SystemUserNameNotFoundError < StandardError
end
+ # Should be raised when an application root path already exists when it should not.
class AppRootAlreadyExistsError < StandardError
end
+ # Should be raised when a configuration file already exsits when it should not.
class ConfigFileAlreadyExistsError < StandardError
end
end
\ No newline at end of file
lib/plow/errors.rb
@@ -1,14 +1,19 @@
# encoding: UTF-8
require 'erb'
-
require 'plow/binding_struct'
require 'plow/strategy/ubuntu_hardy/user_home_web_app'
class Plow
+ # `Plow::Generator` is both a **context** and a **controller** class.
class Generator
attr_reader :user_name, :site_name, :site_aliases
attr_reader :strategy
+ # Creates a new `Generator`
+ #
+ # @param [String] user_name Name of a Linux system account user (e.g. steve)
+ # @param [String] site_name Name of the web-site (e.g. www.apple.com)
+ # @param [splat] *site_aliases (Optional) List of alias names of the web-site (e.g. apple.com)
def initialize(user_name, site_name, *site_aliases)
if user_name.blank? || user_name.include?(' ')
raise(Plow::InvalidSystemUserNameError, user_name)
@@ -31,15 +36,24 @@ class Plow
@strategy = Plow::Strategy::UbuntuHardy::UserHomeWebApp.new(self)
end
+ # Executes the strategy
+ #
+ # @raise [Plow::NonRootProcessOwnerError] Raised when the process is owned by a non-root user.
def run!
raise Plow::NonRootProcessOwnerError unless Process.uid == 0
strategy.execute
end
+ # Renders a message, via the standard output channel, to the user
+ #
+ # @param [String] message A brief message to the user
def say(message)
puts "==> #{message}"
end
+ # Excutes a set of commands in the user's shell enviroment
+ #
+ # @param [String] commands A set of commands, delimited by line-breaks
def shell(commands)
commands.each_line do |command|
command.strip!
@@ -47,6 +61,11 @@ class Plow
end
end
+ # Evaluates a template file, located on the user's filesystem, with a context
+ #
+ # @return [String] The evaluated template data
+ # @param [String] template_path A Unix path to a template file
+ # @param [Hash] context Key/value pairs, where the key is a template file instance variable, and a value is the value to be substituted during evaluation
def evaluate_template(template_path, context)
template = File.read(template_path)
context_struct = Plow::BindingStruct.new(context)
lib/plow/generator.rb
21a4db2a191b07efab3091dcfecac4e01fc1808b
Ryan Sobol
code@ryansobol.com
http://github.com/ryansobol/plow/commit/ffd1dc9ba6925c6d5e8ed06f1305c56d0415469e
ffd1dc9ba6925c6d5e8ed06f1305c56d0415469e
2009-10-30T02:44:50-07:00
2009-10-30T02:44:50-07:00
* lib/plow.rb
* improving yardoc
* lib/plow/application.rb
* improving yardoc
* lib/plow/binding_struct.rb
* improving yardoc
* lib/plow/core_ext/object.rb
* improving yardoc
* lib/plow/dependencies.rb
* improving yardoc
* white-space tweaks
* lib/plow/errors.rb
* improving yardoc
* lib/plow/generator.rb
* improving yardoc
* line-break tweaks
2dc3abbfd34b95539bbf8a64d5ef9e82b6aa321f
Ryan Sobol
code@ryansobol.com