cog 0.2.2 → 0.3.0

data/lib/cog/dsl/language_dsl.rb

@@ -0,0 +1,142 @@
+module Cog
+  module DSL
+
+    # DSL for defining a language
+    class LanguageDSL
+      
+      # @api developer
+      # @param key [String] unique case-insensitive identifier
+      def initialize(key)
+        @lang = Cog::Language.new key
+      end
+
+      # Define a readable name for the language
+      # @param value [String] readable name of the language
+      # @return [nil]
+      def name(value)
+        lang_eval { @name = value }
+        nil
+      end
+      
+      # Define single line comment notation
+      # @param prefix [String] starts a single line comment in the language
+      # @return [nil]
+      def comment(prefix)
+        lang_eval { @comment_prefix = prefix }
+        nil
+      end
+
+      # Define multi-line comment notation
+      # @param prefix [String] starts a multi-line comment in the language
+      # @param postfix [String] ends a multi-line comment in the language
+      # @return [nil]
+      def multiline_comment(prefix, postfix)
+        lang_eval do
+          @multiline_comment_prefix = prefix
+          @multiline_comment_postfix = postfix
+        end
+        nil
+      end
+      
+      # Borrow comment notation from another language
+      # @param lang_key [String] use comment notation from the language with the given key
+      # @return [nil]
+      def comment_style(lang_key)
+        lang_eval { @comment_style = lang_key.to_s.downcase }
+        nil
+      end
+
+      # Define file extensions
+      # @param values [Array<String>] list of file extensions for this language
+      def extension(*values)
+        lang_eval do
+          @extensions = values.collect {|key| key.to_s.downcase}
+        end  
+      end
+      
+      # Define a block to call when using a named scopes in this language
+      # @yieldparam name [String] name of the scope to use
+      # @yieldreturn [String] a using named scope statement in this language
+      # @return [nil]
+      def use_named_scope(&block)
+        lang_eval { @use_named_scope_block = block }
+        nil
+      end
+      
+      # Define a block to call when beginning a named scope in this language
+      # @yieldparam name [String] name of the scope to begin
+      # @yieldreturn [String] a begin named scope statement in this language
+      # @return [nil]
+      def named_scope_begin(&block)
+        lang_eval { @named_scope_begin_block = block }
+        nil
+      end
+
+      # Define a block to call when ending a named scope in this language
+      # @yieldparam name [String] name of the scope to end
+      # @yieldreturn [String] an end named scope statement in this language
+      # @return [nil]
+      def named_scope_end(&block)
+        lang_eval { @named_scope_end_block = block }
+        nil
+      end
+      
+      # Define a block to call when beginning an include guard in this language
+      # @yieldparam name [String] name of the guard
+      # @yieldreturn [String] a begin guard in this language
+      # @return [nil]
+      def include_guard_begin(&block)
+        lang_eval { @include_guard_begin_block = block }
+        nil
+      end
+      
+      # Define a block to call when ending an include guard in this language
+      # @yieldparam name [String] name of the guard
+      # @yieldreturn [String] an end guard in this language
+      # @return [nil]
+      def include_guard_end(&block)
+        lang_eval { @include_guard_end_block = block }
+        nil
+      end
+      
+      # Borrow include guard notation from another language
+      # @param lang_key [String] use include guard notation from the language with the given key
+      # @return [nil]
+      def include_guard_style(lang_key)
+        lang_eval { @include_guard_style = lang_key.to_s.downcase }
+        nil
+      end
+      
+      # @api developer
+      # Compute the comment pattern
+      # @return [Cog::Language] the defined language
+      def finalize
+        pattern = /[*]/
+        esc = lambda do |x|
+          x.gsub(pattern) {|match| "\\#{match}"}
+        end
+        
+        lang_eval do
+          @include_guard_style ||= key
+          @comment_style ||= key
+          @comment_pattern = if @comment_prefix && @multiline_comment_prefix
+            '^\s*(?:%s|%s)\s*%%s\s*(?:%s)?\s*$' % [@comment_prefix, @multiline_comment_prefix, @multiline_comment_postfix].collect(&esc)
+          elsif @comment_prefix
+            '^\s*%s\s*%%s\s*$' % esc.call(@comment_prefix)
+          elsif @multiline_comment_prefix
+            '^\s*%s\s*%%s\s*%s\s*$' % [@multiline_comment_prefix, @multiline_comment_postfix].collect(&esc)
+          else
+            '^\s*%s\s*$'
+          end
+        end
+        @lang
+      end
+      
+      private
+      
+      def lang_eval(&block)
+        @lang.instance_eval &block
+      end
+    end
+  end
+end

data/lib/cog/embed_context.rb

@@ -1,5 +1,3 @@
-require 'cog/config'
-
 module Cog
 
   # Describes the environment of an embed statement including the file in which it was found, the line number, the language, an more.

data/lib/cog/embeds.rb

@@ -1,14 +1,9 @@
-require 'cog/config'
-require 'cog/embed_context'
-require 'cog/embeds/file_scanner'
-require 'cog/errors'
-
 module Cog
   
   # @api developer
   # Methods for querying and manipulating project files
   module Embeds
-
+    
     # Search through all project files for cog embeds, and remember them so that generators can refer to them later
     def gather_from_project
       @embeds ||= {}
@@ -45,7 +40,7 @@ module Cog
     # @yieldreturn [String] the value to substitute into the embed expansion 
     # @return [Hash] whether or not the expansion was updated
     def update(c, &block)
-      FileScanner.scan(c.path, statement(c.hook), :occurrence => c.actual_index) do |s|
+      Helpers::FileScanner.scan(c.path, statement(c.hook), :occurrence => c.actual_index) do |s|
         c.lineno = s.marked_line_number
         c.args = s.match[2].split if s.match[2]
         c.once = !s.match[3].nil?

data/lib/cog/errors.rb

@@ -28,37 +28,24 @@ module Cog
       end
     end
 
-    define_error :ActionRequiresProject, 'action' do
-      "the action requires a project, but no Cogfile was found"
-    end
-    
-    define_error :CouldNotLoadTool, 'tool'
+    define_error :ActionRequiresProjectGeneratorPath, 'action'
+    define_error :ActionRequiresProjectTemplatePath, 'action'
+    define_error :ActionRequiresProjectPluginPath, 'action'
     
-    define_error :DestinationAlreadyExists, 'path' do
-      "a file or directory at the given path already exists, cannot create anything there"
-    end
-
     define_error :DuplicateGenerator, 'generator'
-    
-    define_error :DuplicateTemplate, 'template'
-
-    define_error :DuplicateTool, 'tool'
+    define_error :DuplicatePlugin, 'plugin'
 
-    define_error :InvalidToolConfiguration, 'path to cog_tool.rb file' do
-      "invalid directory structure for a cog tool"
+    define_error :InvalidPluginConfiguration, 'path to cog_plugin.rb file' do
+      "invalid directory structure for a cog plugin"
     end
     
     define_error :NoSuchFilter, 'filter'
-    
     define_error :NoSuchGenerator, 'generator'
-    
     define_error :NoSuchLanguage, 'language'
-
     define_error :NoSuchTemplate, 'template'
-
-    define_error :NoSuchTool, 'tool' do
-      "no such tool, make sure it appears in the COG_TOOLS environment variable"
-    end
+    define_error :NoSuchPlugin, 'plugin'
+    
+    define_error :PluginPathIsNotADirectory, 'plugin_path'
     
     define_error :ScopeStackUnderflow, 'caller' do
       "scope stack underflow: this can happen if you have too many *_end calls in a template"
@@ -68,8 +55,8 @@ module Cog
       "a embed expansion in the given file is missing the 'cog: }' terminator"
     end
     
-    define_error :ToolMissingDefinition, 'missing' do
-      "the tool was not fully defined"
+    define_error :PluginMissingDefinition, 'missing' do
+      "the plugin was not fully defined"
     end
   end
 end

data/lib/cog/generator.rb

@@ -1,13 +1,3 @@
-require 'cog/config'
-require 'cog/embeds'
-require 'cog/errors'
-require 'cog/generator/file_methods'
-require 'cog/generator/filters'
-require 'cog/generator/language_methods'
-require 'cog/helpers'
-require 'erb'
-require 'rainbow'
-
 module Cog
   
   # This module defines an interface which can be used by generator objects.
@@ -16,6 +6,10 @@ module Cog
   #
   # @see https://github.com/ktonon/cog#generators Introduction to Generators
   module Generator
+    
+    autoload :FileMethods, 'cog/generator/file_methods'
+    autoload :Filters, 'cog/generator/filters'
+    autoload :LanguageMethods, 'cog/generator/language_methods'
 
     include FileMethods
     include Filters
@@ -33,10 +27,11 @@ module Cog
     end
     
     # Stamp a template into a file or return it as a string
-    # @param template_path [String] path to template file relative one of the {Config#template_paths}
-    # @param destination [String] path to which the generated file should be written, relative to the {Config::ProjectMethods#project_source_path}
+    # @param template_path [String] path to template file relative to {Config#template_path}
+    # @param destination [String] path to which the generated file should be written, relative to the {Config::ProjectConfig#project_path}
     # @option opt [Boolean] :absolute_template_path (false) is the +template_path+ absolute?
     # @option opt [Boolean] :absolute_destination (false) is the +destination+ absolute?
+    # @option opt [Boolean] :once (false) if +true+, the file will not be updated if it already exists
     # @option opt [Binding] :binding (nil) an optional binding to use while evaluating the template
     # @option opt [String, Array<String>] :filter (nil) name(s) of {Filters}
     # @option opt [Boolean] :quiet (false) suppress writing to STDOUT?
@@ -52,7 +47,7 @@ module Cog
 
       # Place it in a file
       write_scratch_file(destination, r, opt[:absolute_destination]) do |path, scratch|
-        if files_are_same? path, scratch
+        if files_are_same?(path, scratch) || (opt[:once] && File.exists?(path))
           FileUtils.rm scratch
         else
           updated = File.exists? path
@@ -65,7 +60,7 @@ module Cog
 
     # Provide a value for embeds with the given hook
     # @param hook [String] hook name used in the embed statements
-    # @yieldparam context [Embeds::EmbedContext] provides information about the environment in which the embed statement was found
+    # @yieldparam context [EmbedContext] provides information about the environment in which the embed statement was found
     # @yieldreturn The value which will be used to expand the embed (or replace the embedded content)
     # @return [nil]
     def embed(hook, &block)
@@ -108,7 +103,7 @@ module Cog
     # @yieldparam scratch [String] path to the scratch file
     # @return [nil]
     def write_scratch_file(original, text, absolute=false, &block)
-      path = absolute ? original : File.join(Cog.project_source_path, original)
+      path = absolute ? original : File.join(Cog.project_path, original)
       FileUtils.mkpath File.dirname(path) unless File.exists? path
       scratch = "#{path}.scratch"
       File.open(scratch, 'w') {|file| file.write text}

data/lib/cog/generator/file_methods.rb

@@ -5,7 +5,7 @@ module Cog
     module FileMethods
       
       # Get the template with the given name
-      # @param path [String] path to template file relative one of the {Config#template_paths}
+      # @param path [String] path to file relative to the {Config#template_path}
       # @option opt [Boolean] :absolute (false) is the +path+ argument absolute?
       # @option opt [Boolean] :as_path (false) return the template as an ERB instance (+false+) or an absolute path to the file (+true+)
       # @return [ERB, String] an instance of {http://ruby-doc.org/stdlib-1.9.3/libdoc/erb/rdoc/ERB.html ERB} or an absolute path to the template
@@ -15,7 +15,7 @@ module Cog
         fullpath = if opt[:absolute]
           path
         else
-          Cog.template_paths.inject('') do |found, prefix|
+          Cog.template_path.reverse.inject('') do |found, prefix|
             x = File.join prefix, path
             found.empty? && File.exists?(x) ? x : found
           end

data/lib/cog/generator/filters.rb

@@ -1,5 +1,3 @@
-require 'cog/errors'
-
 module Cog
   module Generator
     
@@ -12,19 +10,17 @@ module Cog
         Cog.active_language.comment text
       end
 
-      # @api developer
-      # Adds a call_filter method which throws NoSuchFilter if
-      # the filter is invalid
-      def self.included(other)
-        valid_filters = Filters.instance_eval {instance_methods}
-        other.instance_eval do
-          define_method "call_filter" do |name, text|
-            raise Errors::NoSuchFilter.new(name) unless valid_filters.member?(name.to_s)
-            method(name).call text
-          end
-        end
+      # Call a filter by name
+      # @param name [Symbol] the filter to call
+      # @param text [String] the text to pass through the filter
+      # @return [String] the filtered text
+      def call_filter(name, text)
+        gcontext[:filters] ||= %w(comment)
+        name = name.to_s
+        raise Errors::NoSuchFilter.new(name) unless gcontext[:filters].member? name
+        method(name).call text
       end
-
+      
     end
   end
 end

data/lib/cog/generator/language_methods.rb

@@ -1,12 +1,11 @@
-require 'cog/errors'
-require 'cog/generator/language_methods/scope'
-
 module Cog
   module Generator
     
     # Methods to help with generating language constructs
     module LanguageMethods
       
+      autoload :Scope, 'cog/generator/language_methods/scope'
+      
       # @return [String] a warning comment not to edit the generated file
       def warning
         stamp 'warning', :filter => 'comment'

data/lib/cog/generator_sandbox.rb

@@ -0,0 +1,32 @@
+module Cog
+  
+  # Generators files are executed as instances of this type.
+  # Plugins make themselves available to generators via a call to {DSL::Cogfile#autoload_plugin}
+  class GeneratorSandbox
+    
+    include Generator
+    
+    # @api developer
+    # @param path [String] path to the generator ruby file
+    def initialize(path)
+      @path = path
+    end
+    
+    # Interpret the generator ruby file as this instance
+    # @api developer
+    # @return [nil]
+    def interpret
+      eval File.read(@path), binding
+      nil
+    end
+    
+    # Register an autoload variable.
+    # @api developer
+    # @return [nil]
+    def self.autoload_plugin(name, path)
+      autoload name, path
+      nil
+    end
+    
+  end
+end

data/lib/cog/helpers.rb

@@ -1,2 +1,10 @@
-require 'cog/helpers/cascading_template_set'
-require 'cog/helpers/string'
+module Cog
+
+  # @api developer
+  module Helpers
+    
+    autoload :CascadingSet, 'cog/helpers/cascading_set'
+    autoload :FileScanner, 'cog/helpers/file_scanner'
+
+  end
+end

data/lib/cog/helpers/cascading_set.rb

@@ -0,0 +1,104 @@
+module Cog
+  module Helpers
+    
+    # @api developer
+    class SourceInfo
+      attr_reader :name
+      attr_accessor :path
+      
+      def initialize(name)
+        @info = []
+        @types = []
+        @name = name
+      end
+      
+      def add_source(source, type=nil)
+        type ||= source
+        @info << source
+        @types << type
+      end
+      
+      def style(text, type)
+        case type
+        when :built_in
+          text.color :cyan
+        when :gem
+          text.color :blue
+        when :user
+          text.color :green
+        when :plugin
+          text.color :yellow
+        when :project
+          text.color(:white).bright
+        else
+          text
+        end
+      end
+      
+      def override_s(width=nil)
+        colorless = "[#{@info.join ' < '}]"
+        if width
+          x = @info.zip(@types).collect {|source, type| style source, type}
+          "[#{x.join ' < '}]" + " " * (width - colorless.length)
+        else
+          colorless
+        end
+      end
+      
+      def <=>(other)
+        (@path || @name) <=> (other.path || other.name)
+      end
+      
+      def to_s(override_column_width)
+        "#{override_s override_column_width} #{style @path || @name, @types.last}"
+      end
+    end
+    
+    # @api developer
+    class CascadingSet
+      def initialize
+        @info = {}
+      end
+
+      # Look for sources in each of the given paths
+      # @param paths [Array<String>] a list of file system paths containing sources
+      # @option opt [String] :ext File extension of sources to glob for in each path
+      # @return [Array<String>] formatted listing of the sources
+      def self.process_paths(paths, opt={})
+        cs = Helpers::CascadingSet.new
+        paths.each_with_cog_source do |source, type, path|
+          opt[:source] = source
+          opt[:type] = type
+          opt[:root_dir] = path
+          cs.add_sources opt
+        end
+        cs.to_a
+      end
+      
+      # @option opt [String] :source (nil) the name of the source
+      # @option opt [Symbol] :type (nil) must be one of <tt>:built_in</tt>, <tt>:user</tt>, <tt>:plugin</tt>, or <tt>:project</tt>
+      # @option opt [String] :root_dir (nil) directory in which to look for sources
+      def add_sources(opt={})
+        Dir.glob("#{opt[:root_dir]}/**/*.#{opt[:ext]}") do |path|
+          name = path.relative_to(opt[:root_dir]).slice(0..-(2 + opt[:ext].length))
+          @info[name] ||= SourceInfo.new name
+          @info[name].path = path if Cog.show_fullpaths?
+          @info[name].add_source opt[:source], opt[:type]
+        end
+      end
+      
+      # @param plugin [Plugin] name of the plugin
+      def add_plugin(plugin, opt={})
+        @info[plugin.name] ||= SourceInfo.new plugin.name
+        @info[plugin.name].path = plugin.path if Cog.show_fullpaths?
+        @info[plugin.name].add_source *plugin.path.cog_source_and_type
+      end
+      
+      def to_a
+        w = @info.values.collect {|t| t.override_s.length}.max
+        @info.values.sort.collect {|t| t.to_s(w)}
+      end
+    end
+    
+  end
+end