detroit 0.1.0

data/lib/detroit/standard_assembly.rb

@@ -0,0 +1,52 @@
+module Detroit
+
+  # Standard assembly is the default. In the vast majority of
+  # cases this is all that will ever be used.
+  assembly :standard do
+
+    # Main track.
+    #
+    # TODO: Should :install comes before :verify b/c verfication might
+    # require a local installation?
+    track :main,
+      :prepare,    # prepare services / ensure service requirements
+      :generate,   # code generation
+      :compile,    # compile source code
+      :test,       # run tests and specifications
+      :analyze,    # perform code analysis
+      :document,   # generate documentation
+      :package,    # create packages
+      :verify,     # post package verification / integration tests
+      :install,    # install the package locally (if need be)
+      :publish,    # publish website/documentation
+      :release,    # release packages
+      :deploy,     # deploy system to servers
+      :promote     # tell the world about your awesome work
+
+    # The site track is a subset of the main track used to
+    # isolate the distribution of documentation and uploading
+    # a project's website. 
+    #
+    #   prepare -> generate -> analyze -> document -> publish
+    #
+    track :site,
+      :prepare,
+      :generate,
+      :analyze,
+      :document,
+      :publish
+
+    # The attention track is a small subset of main track, used to
+    # isolate the sending of promotional materials, mainly release
+    # announcements.
+    #
+    #   prepare -> generate -> promote
+    #
+    track :attn,
+      :prepare,
+      :generate,
+      :promote
+
+  end
+
+end

data/lib/detroit/tool.rb

@@ -0,0 +1,216 @@
+module Detroit
+
+  require 'detroit/tool/core_ext'
+  require 'detroit/tool/shell_utils'
+  require 'detroit/tool/project_utils'
+  require 'detroit/tool/email_utils'
+
+  # The Toold module provide an isolated namespace for
+  # Detoit's tools. This allows for general use of these
+  # tools by other applications, by including them into
+  # their own namespace.
+  module Tools
+  end
+
+  # Tool registry.
+  def self.tools
+    @tools ||= {}
+  end
+
+  # 
+  def self.services
+    tools
+  end
+
+  # Add tool class to registry. If class name ends in `Tool`
+  # it will be considered a reusable base class and not be added.
+  def self.register_tool(tool_class)
+    name = tool_class.basename
+    return if name.empty?
+    return if name =~ /(Tool|Service)$/
+    tools[name.downcase] = tool_class
+    Tools.const_set(name, tool_class)
+    # TODO: Should we auto-create convenience method?
+    return tool_class
+  end
+
+  # This base class can be used for tools that do not need
+  # all of the utility methods provided by the regular Tool
+  # class.
+  class BasicTool
+    # Add an assembly to which the tool applies.
+    # By default the `standard` assembly is implied.
+    def self.assembly(assembly=nil)
+      @assembly ||= []
+      if assembly
+        @assembly << assembly.to_sym
+        @assembly.uniq!
+      end
+      @assembly
+    end
+
+    # Override the `tracks` method to limit the lines a service
+    # will work with by default. Generally this is not used,
+    # and a return value of +nil+ means all lines apply.
+    #--
+    # TODO: Rename to #lines ?
+    #++
+    def self.tracks
+    end
+
+    # Override this method if the tools availability is conditional.
+    def self.available?
+      true
+    end
+
+    # Returns list of writer method names.
+    def self.options(service_class=self)
+      service_class.instance_methods.
+        select{ |m| m.to_s =~ /\w+=$/ && !%w{taguri=}.include?(m.to_s) }.
+        map{ |m| m.to_s.chomp('=') }
+    end
+
+    # Returns a Class which is a new subclass of the current class.
+    def self.factory(&block)
+      Class.new(self, &block)
+    end
+
+    # When inherited, add class to tool registry.
+    def self.inherited(base)
+      Detroit.register_tool(base)
+    end
+
+    # TODO: Needed? Rename?
+    def service_title
+      self.class.name
+    end
+  end
+
+  # Tool is the base class for all Detroit tools.
+  #
+  # Tool class is essentially the same as a Service class except that it is
+  # a subclass of RedTools::Tool. Use this class to build Detroit services
+  # with all the conveniences of a RedTools::Tool.
+  class Tool < BasicTool
+    include ShellUtils
+    include ProjectUtils
+    include EmailUtils
+
+    public
+
+    #
+    attr :options
+
+    # If applicable tools should override #current to allow tool users
+    # to know if the tool needs to be used. For example the RDoc tool
+    # can look to see if any the files it would document are newer that
+    # the previous generated set of docs.
+    #
+    # The method can return a String instead of `true`, to convey a
+    # custom message explaining that the tool need not be run. For example,
+    # the RDoc tool returns "RDocs are current (path/to/rdocs)". 
+    def current?
+      false
+    end
+
+    private
+
+    # Create a new tool object.
+    #
+    # This sets up utility extensions and assigns options to setter attributes
+    # if they exist and values are not nil. That last point is important.
+    # You must use 'false' to purposely negate an option, as +nil+ will instead
+    # allow any default setting to be used.
+    #
+    def initialize(options={})
+      initialize_extension_defaults
+
+      initialize_requires
+      initialize_defaults
+
+      initialize_options(options)
+
+      initialize_extensions
+    end
+
+    # TODO: It would be best if an error were raised if an option is not
+    # supported, however for now only a warning will be issued, b/c of 
+    # subclassing makes things more complicated.
+    def initialize_options(options)
+      @options = options
+
+      options.each do |k, v|
+        #send("#{k}=", v) unless v.nil? #if respond_to?("#{k}=") && !v.nil?
+        if respond_to?("#{k}=")
+          send("#{k}=", v) unless v.nil? #if respond_to?("#{k}=") && !v.nil?
+        else
+          warn "#{self.class.name} does not respond to `#{k}`."
+        end
+      end
+    end
+
+    #
+    def initialize_extension_defaults
+      super if defined?(super) 
+    end
+
+    # Require support libraries needed by this service.
+    #
+    #   def initialize_requires
+    #     require 'ostruct'
+    #   end
+    #
+    def initialize_requires
+    end
+
+    # When subclassing, put default instance variable settngs here.
+    #
+    # Examples
+    #
+    #   def initialize_defaults
+    #     @gravy = true
+    #   end
+    #
+    def initialize_defaults
+    end
+
+    # --- Odd Utilities -------------------------------------------------------
+
+    require 'facets/platform'
+
+    # Current platform.
+    def current_platform
+      Platform.local.to_s
+    end
+
+    # TODO: Is naming_policy really useful?
+    # TODO: How to set this in a more universal manner?
+    #
+    def naming_policy(*policies)
+      if policies.empty?
+        @naming_policy ||= ['down', 'ext']
+      else
+        @naming_policy = policies
+      end
+    end
+
+    #
+    #
+    def apply_naming_policy(name, ext)
+      naming_policy.each do |policy|
+        case policy.to_s
+        when /^low/, /^down/
+          name = name.downcase
+        when /^up/
+          name = name.upcase
+        when /^cap/
+          name = name.capitalize
+        when /^ext/
+          name = name + ".#{ext}"
+        end
+      end
+      name
+    end
+
+  end
+end

data/lib/detroit/tool/core_ext.rb

@@ -0,0 +1,3 @@
+Dir[File.dirname(__FILE__) + '/core_ext/**/*.rb'].each do |file|
+  require file
+end

data/lib/detroit/tool/core_ext/facets.rb

@@ -0,0 +1,11 @@
+# I know some people will be deterred by the dependency on Facets b/c they
+# see it as a "heavy" dependency. But really that is far from true, consider
+# the facet that the following libs are all that it used.
+
+require 'facets/array/not_empty'
+require 'facets/module/basename'
+require 'facets/module/alias_accessor'
+require 'facets/kernel/yes'               # pulls in #ask and #no? too.
+require 'facets/kernel/silence'           # FIXME ???
+require 'facets/kernel/disable_warnings'
+

data/lib/detroit/tool/core_ext/filetest.rb

@@ -0,0 +1,29 @@
+module FileTest
+
+  # Return a cached list of the PATH environment variable.
+  # This is a support method used by #bin?
+  def command_paths
+    @command_paths ||= ENV['PATH'].split(/[:;]/)
+  end
+
+  # Is a file a bin/ executable?
+  #
+  # TODO: Make more robust. Probably needs to be fixed for Windows.
+  def bin?(fname)
+    is_bin = command_paths.any? do |f|
+      FileTest.exist?(File.join(f, fname))
+    end
+    #is_bin ? File.basename(fname) : false
+    is_bin ? fname : false
+  end
+
+  ## Is a file a task?
+  #
+  #def task?(path)
+  #  task = File.dirname($0) + "/#{path}"
+  #  task.chomp!('!')
+  #  task if FileTest.file?(task) && FileTest.executable?(task)
+  #end
+
+end
+

data/lib/detroit/tool/core_ext/shell_extensions.rb

@@ -0,0 +1,7 @@
+require 'facets/pathname'
+require 'facets/filetest'
+require 'facets/fileutils'
+
+# DEPRECATE: when new #glob is working.
+require 'facets/dir/multiglob'
+

data/lib/detroit/tool/core_ext/to_actual_filename.rb

@@ -0,0 +1,19 @@
+class String
+
+  # Find actual filename (casefolding) and returns it.
+  # Returns nil if no file is found.
+
+  def to_actual_filename
+    Dir.glob(self, File::FNM_CASEFOLD).first
+  end
+
+  # Find actual filename (casefolding) and replace string with it.
+  # If file not found, string remains the same and method returns nil.
+
+  def to_actual_filename!
+    filename = to_actual_filename
+    replace(filename) if filename
+  end
+
+end
+

data/lib/detroit/tool/core_ext/to_console.rb

@@ -0,0 +1,97 @@
+# TODO: Improve the naming scheme of these methods.
+
+#
+class Array #:nodoc:
+
+  # Convert an array into commandline parameters.
+  # The array is accepted in the format of Ruby
+  # method arguments --ie. [arg1, arg2, ..., hash]
+
+  def to_console
+    #flags = (Hash===last ? pop : {})
+    #flags = flags.to_console
+    #flags + ' ' + join(" ")
+    to_argv.join(' ')
+  end
+
+  # TODO: DEPRECATE
+  alias_method :to_params, :to_console
+
+  #
+  def to_argv
+    flags = (Hash===last ? pop : {})
+    flags = flags.to_argv
+    flags + self
+  end
+
+#   def to_console
+#     flags = (Hash===last ? pop : {})
+#     flags = flags.collect do |f,v|
+#       m = f.to_s.size == 1 ? '-' : '--'
+#       case v
+#       when Array
+#         v.collect{ |e| "#{m}#{f} '#{e}'" }.join(' ')
+#       when true
+#         "#{m}#{f}"
+#       when false, nil
+#         ''
+#       else
+#         "#{m}#{f} '#{v}'"
+#       end
+#     end
+#     return (flags + self).join(" ")
+#   end
+
+end
+
+class Hash
+
+  # Convert a Hash into command line arguments.
+  # The array is accepted in the format of Ruby
+  # method arguments --ie. [arg1, arg2, ..., hash]
+  def to_console
+    to_argv.join(' ')
+  end
+
+  # Convert a Hash into command line parameters.
+  # The array is accepted in the format of Ruby
+  # method arguments --ie. [arg1, arg2, ..., hash]
+  def to_argv
+    flags = []
+    each do |f,v|
+      m = f.to_s.size == 1 ? '-' : '--'
+      case v
+      when Array
+        v.each{ |e| flags << "#{m}#{f}='#{e}'" }
+      when true
+        flags << "#{m}#{f}"
+      when false, nil
+        # nothing
+      else
+        flags << "#{m}#{f}='#{v}'"
+      end
+    end
+    flags
+  end
+
+  # Turn a hash into arguments.
+  #
+  #   h = { :list => [1,2], :base => "HI" }
+  #   h.argumentize #=> [ [], { :list => [1,2], :base => "HI" } ]
+  #   h.argumentize(:list) #=> [ [1,2], { :base => "HI" } ]
+  #
+  def argumentize(args_field=nil)
+    config = dup
+    if args_field
+      args = [config.delete(args_field)].flatten.compact
+    else
+      args = []
+    end
+    args << config
+    return args
+  end
+
+  alias_method :command_vector, :argumentize
+
+end
+

data/lib/detroit/tool/core_ext/to_list.rb

@@ -0,0 +1,29 @@
+class Array
+
+  def to_list
+    self
+  end
+
+end
+
+class NilClass
+
+  def to_list
+    []
+  end
+
+end
+
+class String
+
+  # Helper method for cleaning list options.
+  # This will split the option on ':' or ';'
+  # if it is a string, rather than an array.
+  # And it will make sure there are no nil elements.
+
+  def to_list
+    split(/[:;,\n]/)
+  end
+
+end
+