cog 0.0.10 → 0.0.11

data/API.rdoc

@@ -1,33 +1,6 @@
-= cog API docs
+= cog API Docs
 
-+cog+ is a command line utility that makes it a bit easier to organize a project
-which uses code generation. Many of your interactions with +cog+ will be using
-the command line interface. However, to get any real mileage out of it you'll
-need to use the API (documented here). For more information on the command line
-interface see https://github.com/ktonon/cog#cog
++cog+ is a command line tool which helps you write code generators.
 
-+cog+ is configured with a +Cogfile+, which should be in the root of your
-project's file tree. The +Cogfile+ is just a ruby file and the commands
-available in it are defined in the Cog::Cogfile class. It is generated for you
-when you issue this command from a shell in the root directory of your project:
-
-  cog init
-
-and it will look something like this:
-
-  # All paths are relative to the directory containing this file.
-
-  # The directory in which to place Ruby generators and +ERB+ templates.
-  cog_dir 'cog'
-
-  # The directory in which to place generated application code.
-  app_dir 'src'
-
-  # The default language in which to generate source code.
-  language 'c++'
-
-== Testing
-
-The tests are written in +RSpec+ and can be found in the <tt>spec/</tt>
-directory. Custom matchers are available to make writing specs easier. See
-Cog::SpecHelpers for more details.
+This is the API docs. For a more general introduction to +cog+ visit
+https://github.com/ktonon/cog#readme

data/Default.cogfile

@@ -1,10 +1,13 @@
 # All paths are relative to the directory containing this file.
 
-# The directory in which to place Ruby generators and +ERB+ templates.
-cog_dir 'cog'
+# Define the directory in which to find project generators
+project_generators_path 'cog/generators'
 
-# The directory in which to place generated application code.
-app_dir 'src'
+# Define the directory in which to find custom project templates
+project_templates_path 'cog/templates'
 
-# The default language in which to generate source code.
+# Define the directory to which project source code is generated
+project_source_path 'src'
+
+# Define the default language in which to generated application source code
 language 'c++'

data/bin/cog

@@ -1,81 +1,91 @@
 #!/usr/bin/env ruby
-# 1.9 adds realpath to resolve symlinks; 1.8 doesn't
-# have this method, so we add it so we get resolved symlinks
-# and compatibility
-unless File.respond_to? :realpath
-  class File #:nodoc:
-    def self.realpath path
-      return realpath(File.readlink(path)) if symlink?(path)
-      path
-    end
-  end
-end
-$: << File.expand_path(File.dirname(File.realpath(__FILE__)) + '/../lib')
-require 'rubygems'
-require 'active_support/core_ext'
-require 'cog'
-require 'cog_version'
 require 'gli'
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+require 'cog'
+require 'active_support/core_ext'
 require 'fileutils'
 
 include GLI::App
 
 program_desc 'This is a utility to help you write code generators.'
 
-version Cog::VERSION
-
-desc 'Write extra information'
-switch [:v,:verbose]
+# version Cog::VERSION
 
-desc 'Add cog to a project by generating a Cogfile in the current directory'
+desc 'Add cog to the project in the present working directory'
+skips_pre
 command :init do |c|
-  c.action do |g,o,a|
-    puts "Generated Cogfile"
-    FileUtils.cp File.join(Cog::Config.gem_dir, 'Default.cogfile'), 'Cogfile'
+
+  c.action do |global_options, options, args|
+    Cog.initialize_project
   end
 end
 
-# desc 'Create a new mirror class'
-# arg_name 'ClassName'
-# command :mirror do |c|
-#   c.desc 'The target language (see languages command)'
-#   c.arg_name 'language'
-#   c.flag [:language, :l]
-#   
-#   c.desc 'Slash (/) separated prefix for generator, templates, and app code'
-#   c.arg_name 'path'
-#   c.flag [:package, :p]
-# 
-#   c.action do |g,opt,a|
-#     a.each do |class_name|
-#       mirror_gen = Cog::Meta::MirrorGen.new class_name
-#       mirror_gen.stamp opt
-#     end
-#   end
-# end
+desc 'Create a tool (or leave name blank to list available tools)'
+arg_name 'name'
+skips_pre
+command :tool do |c|
+
+  c.action do |global_options, options, args|
+    if args.empty?
+      puts 'Available tools:'
+      puts (Cog::Tool.available.collect {|tool| "  #{tool}"}.join "\n")
+    else
+      args.each do |name|
+        unless File.exists? name
+          Cog::Tool.generate_tool name
+        else
+          puts "Could not create tool for '#{name}', a file or directory already exists with that name"
+        end
+      end
+    end
+  end
+end
+
+desc 'Create a generator (or leave name blank to list project generators)'
+arg_name 'name'
+command :generator do |c|
+  
+  c.desc 'which tool to use to create the generator'
+  c.arg_name 'tool_name'
+  c.default_value 'generic'
+  c.flag :tool
+  
+  c.action do |global_options, options, args|
+    if args.empty?
+      puts 'Project generators:'
+      puts (Cog::Generator.available.collect {|gen| "  #{gen}"}.join "\n")
+    else
+      args.each do |name|
+        # TODO: create the generator
+      end
+    end
+  end
+end
 
 desc 'List supported languages'
+skips_pre
 command :languages do |c|
-  c.action do |g,o,a|
+
+  c.action do
     puts 'c++'
   end
 end
 
-pre do |global, command, options, args|
+desc 'Run generators in the current project'
+arg_name 'generator_name'
+command :run do |c|
+end
+
+pre do |global_options, command, options, args|
   # Pre logic here
   # Return true to proceed; false to abort and not call the
   # chosen command
   # Use skips_pre before a command to skip this block
   # on that command only
-  cogfile = Cog::Config.for_project
-  if !cogfile && command && command.name != :init
-    puts 'No Cogfile could be found'
-    false
-  elsif cogfile && command && command.name == :init
-    puts "A Cogfile already exists at #{cogfile.cogfile_path.inspect}"
+  unless Cog::Config.instance.project?
+    puts 'No Cogfile could be found. Run `cog init` to prepare an existing project.'
     false
   else
-    global[:cogfile] = cogfile
     true
   end
 end

data/lib/cog.rb

@@ -1,6 +1,22 @@
 require 'cog/config'
-require 'cog/meta'
-require 'cog/mixins'
+require 'cog/generator'
+require 'cog/tool'
+require 'cog/version'
+require 'fileutils'
 
+# The static methods on this top level module mirror the commands available to
+# the +cog+ command line utility.
 module Cog
+
+  # Prepare the project in the present working directory for use with +cog+
+  def self.initialize_project
+    Object.new.instance_eval do
+      class << self ; include Generator ; end
+      copy_if_missing File.join(Config.gem_dir, 'Default.cogfile'), 'Cogfile'
+      config = Config.instance
+      touch_path config.project_generators_path
+      touch_path config.project_templates_path
+    end
+  end
+  
 end

data/lib/cog/config.rb

@@ -1,45 +1,60 @@
-require 'rubygems'
+require 'cog/config/cogfile'
 require 'singleton'
-require 'cog/cogfile'
 
 module Cog
   
-  # This interface is intended for use within generators. Instances of this type
-  # are initialized via Cogfile files.
+  # This interface is intended for use within generators. Apps can customize
+  # Instances of this type
+  # can be configured via Cogfile files.
   class Config
         
-    # Directory to which application source code is generated.
-    attr_reader :app_dir
-
-    # Path to the +Cogfile+.
+    # Path to the project's +Cogfile+.
     attr_reader :cogfile_path
 
-    # Directory in which to find Ruby source files. These are files which
-    # control exactly how the code is going to be generated.
-    attr_reader :generator_dir
-
-    # Default language in which to generated application source code.
+    # Default language in which to generated application source code
     attr_reader :language
     
-    # Directory in which the +Cogfile+ is found.
+    # Directory in which to find project generators
+    attr_reader :project_generators_path
+
+    # Directory in which the project's +Cogfile+ is found
     attr_reader :project_root
     
-    # Directory in which to find ERB template files.
-    attr_reader :template_dir
+    # Directory to which project source code is generated
+    attr_reader :project_source_path
+
+    # Directory in which to find custom project templates
+    attr_reader :project_templates_path
     
-    # Initialize from a +Cogfile+ at the given path.
-    # ==== Arguments
-    # * +path+ - A file system path to a +Cogfile+. The file must exists.
-    def initialize(path)
-      @cogfile_path = File.expand_path path
-      @project_root = File.dirname @cogfile_path
-      cogfile = Cogfile.new self
-      cogfile.interpret
+    # Are we operating in the context of a project?
+    # That is, could a Cogfile be found?
+    def project?
+      !@project_root.nil?
     end
-
-    # The default configuration for the project.
+    
+    # A list of directories in which to find ERB template files.
+    # Priority should be given first to last.
+    def template_paths
+      [@project_templates_path, @tool_templates_path, File.join(Config.gem_dir, 'templates')].compact
+    end
+    
+    # Location of the installed cog gem
+    def self.gem_dir # :nodoc:
+      spec = Gem.loaded_specs['cog']
+      if spec.nil?
+        # The current __FILE__ is:
+        #   ${COG_GEM_ROOT}/lib/cog/config.rb
+        File.expand_path File.join(File.dirname(__FILE__), '..', '..')
+      else
+        spec.gem_dir
+      end
+    end
+    
+    # The singleton instance.
+    #
+    # Initialized using the +Cogfile+ for the current project, if any can be
+    # found. If not, then #project? will be +false+.
     #
-    # Initialized using the +Cogfile+ for the current project.
     # The +Cogfile+ will be looked for in the present working directory. If none
     # is found there the parent directory will be checked, and then the
     # grandparent, and so on.
@@ -47,8 +62,11 @@ module Cog
     # ==== Returns
     # An instance of Cogfile which has been configured with a +Cogfile+. If no
     # such file was found then +nil+.
-    def self.for_project
-      return @for_project if @for_project
+    def self.instance
+      return @instance if @instance
+      @instance = self.new
+      
+      # Attempt to find a Cogfile
       parts = Dir.pwd.split File::SEPARATOR
       i = parts.length
       while i >= 0 && !File.exists?(File.join(parts.slice(0, i) + ['Cogfile']))
@@ -56,22 +74,22 @@ module Cog
       end
       path = File.join(parts.slice(0, i) + ['Cogfile']) if i >= 0
       if path && File.exists?(path)
-        @for_project = self.new path
+        @instance.instance_eval do
+          @cogfile_path = File.expand_path path
+          @project_root = File.dirname @cogfile_path
+          cogfile = Cogfile.new self
+          cogfile.interpret
+        end
       end
+      
+      @instance
     end
 
-    # Location of the installed cog gem
-    def self.gem_dir # :nodoc:
-      spec = Gem.loaded_specs['cog']
-      if spec.nil?
-        # The current __FILE__ is:
-        #   ${COG_GEM_ROOT}/lib/cog/config.rb
-        File.expand_path File.join(File.dirname(__FILE__), '..', '..')
-      else
-        spec.gem_dir
-      end
+  private
+
+    def initialize
+      @project_root = nil
     end
-    
+
   end
-  
 end

data/lib/cog/config/cogfile.rb

@@ -0,0 +1,76 @@
+module Cog
+  class Config
+    
+    # In your project's +Cogfile+, +self+ has been set to an instance of this class.
+    #
+    # ==== Example +Cogfile+
+    #   project_generators_path 'cog/generators'
+    #   project_templates_path 'cog/templates'
+    #   project_source_path 'src'
+    #   language 'c++'
+    #
+    # Typing `cog init` will create a +Cogfile+ in the present working directory.
+    #
+    # +Cogfile+ files are used to configure an instance of Config.
+    class Cogfile
+    
+      def initialize(config) # :nodoc:
+        @config = config
+      end
+    
+      # Interpret the Cogfile and initialize @config
+      def interpret # :nodoc:
+        eval File.read(@config.cogfile_path), binding
+      rescue Exception => e
+        raise CogfileError.new(e.to_s)
+      end
+    
+      # Define the directory in which to find project generators
+      # ==== Arguments
+      # * +path+ - A file system path
+      # * +absolute+ - If false, the path is relative to the directory containing the +Cogfile+
+      def project_generators_path(path, absolute=false)
+        @config.instance_eval do
+          @project_generators_path = absolute ? path : File.join(project_root, path)
+        end
+      end
+
+      # Define the directory in which to find custom project templates
+      # ==== Arguments
+      # * +path+ - A file system path
+      # * +absolute+ - If false, the path is relative to the directory containing the +Cogfile+
+      def project_templates_path(path, absolute=false)
+        @config.instance_eval do
+          @project_templates_path = absolute ? path : File.join(project_root, path)
+        end
+      end
+
+      # Define the directory to which project source code is generated
+      # ==== Arguments
+      # * +path+ - A file system path
+      # * +absolute+ - If false, the path is relative to the directory containing the +Cogfile+
+      def project_source_path(path, absolute=false)
+        @config.instance_eval do
+          @project_source_path = absolute ? path : File.join(project_root, path)
+        end
+      end
+
+      # Define the default language in which to generated application source code
+      # ==== Arguments
+      # * +lang+ - A code for the language. Acceptable values are <tt>c++</tt>.
+      def language(lang)
+        @config.instance_eval do
+          @language = lang
+        end
+      end
+    end
+
+    # For wrapping errors which occur during the processing of a +Cogfile+.
+    class CogfileError < StandardError
+      def message
+        "in Cogfile, " + super
+      end
+    end
+    
+  end
+end

data/lib/cog/errors.rb

@@ -0,0 +1,16 @@
+module Cog
+  
+  module Errors
+    # Indiciates an attempt to use a non-existant template.
+    class MissingTemplate < Exception
+      def initialize(template_path)
+        @template_path = template_path
+      end
+      
+      def message
+        "could not find the template '#{@template_path}'\n#{super}"
+      end
+    end
+  end
+
+end