noe 1.0.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 1.0.0 / 2011-01-10
+
+* Enhancements
+
+  * Birthday!

data/LICENCE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 - Bernard Lambeau
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,117 @@
+# Noe - A simple and extensible project generator
+
+Noe helps development by providing support for project templates and instantiation.
+
+## Why?
+
+I'm pretty sure I have seen announcements for similar projects on ruby-lang in the past, 
+but I could not find them anymore... so I started mine. Please let me know alternatives
+and I'll add them below:
+
+See also: 
+
+* ...
+    
+Other reasons:
+
+* Noe is agnostic: it does not make any assumption about project semantics
+* Noe does not restrict itself to generation of ruby projects
+* Noe is not required at runtime: once your project is generated you're done
+* I don't like magic
+
+## Getting started
+
+    [sudo] gem install noe
+    [noe --help]
+    [noe help install]
+    noe install 
+    
+Have a loot at ~/.noerc and ~/.noe for configuration and a default ruby 
+template.
+  
+## Usage summary
+
+Maintain your templates under ~/.noe (or what you provided at installation time). Have a 
+look at github to find xxx.noe projects to find well-designed/documented templates for
+specific needs.
+
+To create a fresh new project:
+
+    # Given a template xxx under ~/.noe/xxx
+    noe create --template=xxx foo
+    cd foo
+  
+    # Edit the template configuration foo/foo.noespec
+    edit foo/foo.noespec
+  
+    # Launch template instantiation
+    noe go
+  
+That's it! But also have a look at 'noe help create' and 'not help go' for additional
+options.
+
+## About templates
+
+Under ~/.noe, a valid template folder (say xxx) has the following structure
+
+    xxx                         # Template name
+      README(.md|.txt|...)      #   Information about the template and it's usage
+      CHANGELOG(.md|.txt|...)   #   Change information
+      noespec.yaml              #   Template specification
+      src                       #   Source folder, contains files to be instantiated
+        ...                     #     [everything that will be instantiated]
+
+### noespec.yaml
+
+The noespec.yaml file of a template is used to formally describe the template. When a project 
+(say foo) is created (see 'noe create') using a template (say ruby) the file 
+~/.noe/ruby/noespec.yaml is used to generate foo/foo.noespec. The later is then used by 
+'noe go' to instantiate the project.
+
+The noespec.yaml file should ressemble something like this:
+
+    # DO NOT TOUCH 'name' entry and specify the other
+    template-info:
+      name: !{template_name}
+      description: ...
+      version: ...
+      author: ...
+
+    #
+    # The following is a hash of template-related variables. They are
+    # used to provide dynamic file names and instantiate file contents.
+    #
+    # Current version of Noe only supports variable names matching /[a-z]+/
+    #
+    variables:
+      ...
+
+Have a look at ~/.noe/ruby/noespec.yaml and ~/.noe/ruby/src for an example.
+
+### Instantiation process
+
+The instantiation process is really simple. Given the variables described in the noespec.yaml 
+file (for which values are specified in your .noespec file) templates can use the following
+meta-constructions:
+
+* Template files and directories containing `__variable__` in their name are automatically 
+  renamed (`__variable__` is replaced by the corresponding value).
+* All template files are instantiated by [wlang](https://github.com/blambeau/wlang). You don't
+  have to know wlang in depth. You simply have to know that `!{ruby_expression}` in a file is 
+  replaced by the expression evaluation. Variables are automatically in scope of such expressions,
+  so that `!{variable}` is replaced by its value.
+
+## Contributing
+
+Fork Noe on github! I'm particularly interested in the following enhancements:
+
+* Extend test coverage, which is ugly so far.
+* Enhance the default ruby template, but remember "documentation matters, not magic!"
+* Add support for other generators than _wlang_
+* Add support for multi-generated files from arrays in .noespec files
+* ...
+
+If you think that your template is worth considering for (ruby, rails, js, latex, or anything 
+else) please let me known and I'll add it to the list below.
+
+* ...

data/Rakefile

@@ -0,0 +1,24 @@
+require "rake/gempackagetask"
+require "rspec/core/rake_task"
+require "yard"
+
+# We run tests by default
+task :default => :spec
+
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec) do |t|
+	t.rspec_opts = %w[--color]
+	t.verbose = false
+end
+
+# About yard documentation
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = ['--output-dir', 'doc/api', '-', "README.md", "CHANGELOG.md"]
+end
+
+desc "Create the .gem package"
+$spec = Kernel.eval(File.read(File.expand_path('../noe.gemspec', __FILE__)))
+Rake::GemPackageTask.new($spec) do |pkg|
+	pkg.need_tar = true
+end

data/bin/noe

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'noe'
+Noe::Main.run(ARGV)
+

data/lib/noe.rb

@@ -0,0 +1,39 @@
+module Noe
+  
+  # Noe's version
+  VERSION = "1.0.0".freeze
+  
+  # Requires some gem
+  def self.require(gem_name, version = nil, retried = false)
+    begin
+      Kernel.require gem_name
+    rescue LoadError
+      if retried
+        raise
+      else
+        retried = true
+        require 'rubygems'
+        gem gem_name, version
+        retry
+      end
+    end
+  end
+  
+  class Error < StandardError; end
+
+end # module Noe
+
+Noe.require('quickl', ">= 0.2.0")
+Noe.require('wlang', ">= 0.9")
+require 'yaml'
+require 'fileutils'
+require 'noe/config'
+require 'noe/template'
+require 'noe/main'
+require 'noe/commons'
+require 'noe/install'
+require 'noe/help'
+require 'noe/list'
+require 'noe/create'
+require 'noe/go'
+

data/lib/noe/commons.rb

@@ -0,0 +1,18 @@
+module Noe
+  module Commons
+    
+    # Returns configuration to use
+    def config
+      requester.config 
+    end
+    
+    def templates_dir
+      config.templates_dir
+    end
+    
+    def template(name = config.default)
+      Template.new(File.join(templates_dir, name))
+    end
+
+  end # module Commons
+end # module Noe

data/lib/noe/config.rb

@@ -0,0 +1,60 @@
+module Noe
+  class Config
+    
+    # Default configuration hash
+    DEFAULT_CONFIG = {
+      'version'       => Noe::VERSION,
+      'templates-dir' => File.expand_path('../../../templates', __FILE__),
+      'default'       => 'ruby'
+    }
+    
+    # Path to the configuration file
+    attr_reader :file
+    
+    # Loaded configuration hash
+    attr_reader :config
+    
+    # Creates a config instance from some .noerc file
+    def initialize(file = nil)
+      @config = DEFAULT_CONFIG
+      @file = file
+      __load unless file.nil?
+    end
+    
+    # Loads configuration from YAML file
+    def __load
+      if File.file?(file) and File.readable?(file)
+        loaded = YAML::load(File.read(file))
+        if loaded.is_a?(Hash)
+          @config.merge!(loaded)
+        else
+          raise Noe::Error, "Corrupted or invalid config file: #{file}"
+        end
+      else
+        raise Noe::Error, "Not a file or not readable: #{file}"
+      end
+    end
+    
+    # Returns folder where templates are located
+    def templates_dir
+      dir = config['templates-dir']
+      if File.directory?(dir) and File.readable?(dir)
+        dir
+      else
+        raise Noe::Error, "Invalid noe config, not a directory or unreadable: #{dir}"
+      end
+    end
+    
+    # Returns the name of the default template to use
+    def default
+      config['default']
+    end
+    
+    # Sets the name of the default template to use
+    def default=(name)
+      config['default'] = name
+    end
+     
+    private :__load
+  end # class Config
+end # module Noe

data/lib/noe/config.yaml

@@ -0,0 +1,29 @@
+#
+# .noerc - Configuration of Noe, a simple project generator.
+#
+# This file provides Noe's configuration. More information can be 
+# found at https://github.com/blambeau/noe. 
+#
+# If you want to regenerate a fresh new file, simply run:
+#
+#   noe install
+#
+
+# This is Noe's version, change only if you known what you 
+# are doing!
+version:
+  !{Noe::VERSION}
+
+#
+# Absolute path to the folder containing Noe's templates.
+#
+templates-dir:
+  !{templates_dir}
+
+#
+# Name of the default template that you want to use. Commands
+# that need a template (see 'noe help create', for example) use this 
+# by default, and allow overriding this via a --template=NAME option.
+#
+default:
+  ruby

data/lib/noe/create.rb

@@ -0,0 +1,77 @@
+require 'fileutils'
+module Noe
+  class Main
+    #
+    # Create a fresh new project
+    #
+    # SYNOPSIS
+    #   #{program_name} #{command_name} [options] PROJECT_NAME
+    #
+    # OPTIONS
+    # #{summarized_options}
+    #
+    # DESCRIPTION
+    #   This command guides you with the creation of a new project whose
+    #   name is given as first argument. A new folder is created and a .noespec
+    #   file is generated in it. The template specified in ~/.noerc under :default 
+    #   is used by default. Use --template to override this. 
+    #
+    #   After creation, you'll have to edit the generated .noespec file then run
+    #   'noe go' in the new directory.
+    #
+    # TYPICAL USAGE
+    #
+    #   # start creation of a ruby project
+    #   noe create --ruby hello_world
+    #   cd hello_world
+    #  
+    #   # edit the configuration
+    #   edit hello_world.noespec
+    #
+    #   # launch template generation
+    #   noe go
+    #
+    class Create < Quickl::Command(__FILE__, __LINE__)
+      include Noe::Commons
+      
+      # Install options
+      options do |opt|
+        opt.on('--template=TPLNAME',
+               'Set the template to use') do |name|
+          config.default = name
+        end
+      end
+      
+      def execute(args)
+        raise Quickl::Help unless args.size == 1
+
+        # get project name and check folder and template
+        pname = args.first
+        if File.exists?(pname)
+          raise Noe::Error, "File #{pname} already exists, remove it first."
+        end
+        tpl = template
+        
+        # create folder now
+        FileUtils.mkdir(pname)
+        
+        # instantiate the configuration
+        File.open(File.join(pname, "#{pname}.noespec"), 'w') do |out|
+          context = {'template_name' => tpl.name}
+          out << WLang::file_instantiate(tpl.spec_file, context, "wlang/active-string")
+        end 
+        
+        # what's next
+        puts "Project successfully started !"
+        puts 
+        puts "What's next?"
+        puts " * cd #{pname}"
+        puts " * vim #{pname}.noespec"
+        puts " * noe go"
+        puts
+        puts "Thank you for using Noe (v#{Noe::VERSION}), enjoy!"
+      end
+
+    end # class Create
+  end # class Main
+end # module Noe

data/lib/noe/go.rb

@@ -0,0 +1,194 @@
+module Noe
+  class Main
+    #
+    # Instantiate a project template using a .noespec file.
+    #
+    # SYNOPSIS
+    #   #{program_name} #{command_name} [options] [SPEC_FILE]
+    #
+    # OPTIONS
+    # #{summarized_options}
+    #
+    # DESCRIPTION
+    #   This command instantiate a project template using a .noespec file 
+    #   given as first argument. If no spec file is specified, Noe expects 
+    #   one .noespec file to be present in the current directory and uses it.
+    # 
+    #   This command is generally used immediately after invoking 'create',
+    #   on an almost empty directory. By default it safely fails if any file
+    #   or directory would be overriden by the instantiation process. This
+    #   safe behavior can be bypassed through the --force and --add-only 
+    #   options.
+    #
+    # TYPICAL USAGE
+    #
+    #   When a fresh new project is created, this command is typically used
+    #   with the following scenario
+    #
+    #     noe create --ruby hello_world
+    #     cd hello_world
+    #     edit hello_world.noespec
+    #     noe go
+    #
+    #   If you modify your .noespec file and want to force overriding of all 
+    #   files:
+    #     
+    #     noe go --force
+    #
+    #   If you want to regenerate some files only (README and gemspec, for 
+    #   example):
+    #
+    #     rm README.md hello_world.gemspec
+    #     noe go --add-only
+    #
+    class Go < Quickl::Command(__FILE__, __LINE__)
+      include Noe::Commons
+
+      # Dry-run mode ?
+      attr_reader :dry_run
+      
+      # Force mode ?
+      attr_reader :force
+
+      # Only make additions ?
+      attr_reader :adds_only
+
+      # Install options
+      options do |opt|
+        @dry_run = false
+        opt.on('--dry-run', '-d',
+               "Say what would be done but don't do it"){ 
+          @dry_run = true
+        }
+        @force = false
+        opt.on('--force', '-f',
+               "Force overriding on all existing files"){ 
+          @force = true
+        }
+        @adds_only = false
+        opt.on('--add-only', '-a',
+               "Only make additions, do not override any existing file"){ 
+          @adds_only = true
+        }
+      end
+      
+      def build_one(entry, variables)
+        relocated = entry.relocate(variables)
+        todo = []
+        
+        # The file already exists, we should maybe do something
+        if File.exists?(relocated)
+          if force
+            unless entry.directory? and File.directory?(relocated)
+              todo << Rm.new(entry, variables)
+            end
+          elsif adds_only
+            return todo
+          else
+            raise Noe::Error, "Noe aborted: file #{relocated} already exists.\n"\
+                              "Use --force to override."
+          end
+        end
+        
+        # Create directories
+        if entry.directory? and not(File.exists?(relocated))
+          todo << MkDir.new(entry, variables)
+          
+        # Create files  
+        elsif entry.file?
+          todo << FileInstantiate.new(entry, variables)
+
+        end
+        todo
+      end
+      
+      def execute(args)
+        raise Quickl::Help if args.size > 1
+        
+        # Find spec file
+        spec_file = if args.size == 1
+          valid_read_file!(args.first)
+        else
+          spec_files = Dir['*.noespec']
+          if spec_files.size > 1
+            raise Noe::Error, "Ambiguous request, multiple specs: #{spec_files.join(', ')}"
+          end
+          spec_files.first
+        end
+        
+        # Load spec now
+        spec = YAML::load(File.read(spec_file))
+        template = template(spec['template-info']['name'])
+        variables = spec['variables']
+        
+        # Build what has to be done
+        commands = template.collect{|entry|
+          build_one(entry, variables)
+        }.flatten
+        
+        # let's go now
+        if dry_run
+          commands.each{|c| puts c}
+        else
+          commands.each{|c| c.run}
+        end
+        
+      end
+      
+      class DoSomething
+
+        attr_reader :entry
+        attr_reader :variables
+
+        def initialize(entry, variables)
+          @entry, @variables = entry, variables
+        end
+        
+        def relocated
+          entry.relocate(variables)
+        end
+
+      end
+        
+      class MkDir < DoSomething
+
+        def run
+          FileUtils.mkdir relocated
+        end
+        
+        def to_s
+          "mkdir #{relocated}"
+        end
+        
+      end # class MkDir
+      
+      class Rm < DoSomething
+
+        def run
+          FileUtils.rm_rf relocated
+        end
+        
+        def to_s
+          "rm -rf #{relocated}"
+        end
+        
+      end # class Rm
+      
+      class FileInstantiate < DoSomething
+        
+        def run
+          File.open(relocated, 'w') do |out|
+            dialect = "wlang/active-string"
+            out << WLang::file_instantiate(entry.realpath, variables, dialect)
+          end
+        end
+        
+        def to_s
+          "wlang #{entry.path} > #{relocated}"
+        end
+        
+      end
+
+    end # class Go
+  end # class Main
+end # module Noe