noe 1.0.0 → 1.1.0

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+# 1.1.0 / FIX ME
+
+* Template specification/instantiation enhancements
+
+  * Introduced a manifest entry in template-info 
+  * Introduced an auto detection of the wlang dialect to use based on file extensions. 
+    The dialect may also be specified under template-info/manifest/a_file_name/wlang-dialect 
+    entry
+  * All hashes found in .noespec variables are methodized before being passed to template
+  * Templates are now instantiated on a specification being the result of YAML merging 
+    between the user's .noespec file and the template noespec.yaml file.
+
+* Command enhancements
+
+  * Removed 'noe create', which is replaced by an extended version named 'noe prepare'
+  * 'noe go' now supports --interactive and --safe-override additional options to control conflict strategy
+  * Added a 'noe show-spec' command that shows the complete specification used by 'noe go'
+    See 'noe help show-spec' for details
+  * 'noe COMMAND --help' is now an alias for 'noe help COMMAND'  
+  * A wlang backtrace is now displayed when an instantation error occurs on 'noe go'
+
+* Other changes
+
+  * Bumped wlang version to 0.10.0 to gain inclusion features on wlang/ruby and wlang/yaml
+  * Ruby skeleton largely enhanced (see it's own CHANGELOG.md)
+  * Noe code is now managed by Noe itself
+
 # 1.0.0 / 2011-01-10
 
 * Enhancements

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec :name => "noe"

data/LICENCE.md

@@ -0,0 +1,22 @@
+# Licence
+
+    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

@@ -1,23 +1,14 @@
 # Noe - A simple and extensible project generator
 
-Noe helps development by providing support for project templates and instantiation.
+Noe is a tool that generates projects from predefined skeletons (aka project/application 
+templates). Skeletons are designed for building specific products (a ruby library, a static 
+or dynamic web site, ...). Noe instantiates them and helps you maintaining your product 
+via meta-information provided by a .noespec yaml file. 
 
-## 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
+Noe comes bundled with a skeleton for creating and maintaining a ruby gem. This skeleton 
+is written and maintained to follow ruby best practices and may also be tuned for your own 
+needs. Read more about it and related projects as well as the underlying philosophy in the 
+sections below.
 
 ## Getting started
 
@@ -26,19 +17,11 @@ Other reasons:
     [noe help install]
     noe install 
     
-Have a loot at ~/.noerc and ~/.noe for configuration and a default ruby 
-template.
-  
-## Usage summary
+Have a loot at ~/.noerc and ~/.noe for configuration and a default ruby template. To 
+instantiate a ruby project simply execute the following commands in turn:
 
-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
+    # Given a template ruby under ~/.noe/ruby, install by default
+    noe prepare --template=ruby foo
     cd foo
   
     # Edit the template configuration foo/foo.noespec
@@ -47,10 +30,92 @@ To create a fresh new project:
     # Launch template instantiation
     noe go
   
-That's it! But also have a look at 'noe help create' and 'not help go' for additional
+That's it! But also have a look at 'noe help prepare' and 'not help go' for additional
 options.
 
-## About templates
+## Philosophy
+
+Noe is designed to follow a certain number of good principles and helps you following 
+them as well.
+
+### Separation of concerns
+
+Noe maintains a strong separation of concerns. In particular one has to make the distinction 
+between a) Noe itself, b) a skeleton and c) an instantiated product. This fact has two 
+main consequences:
+
+* Noe itself **is not dedicated to specific products** (like a ruby library). Even if Noe 
+  comes bundled with a default skeleton for ruby projects, writing skeletons for something
+  else should not be a problem. In other words, Noe itself is agnostic: the semantics of 
+  generated products is the secret of the skeleton, under the responsibility of it's 
+  maintainer. 
+
+* Noe **should not be a runtime dependency** of the product. Good skeletons maintain this 
+  separation. As an example the default ruby skeleton is strictly independent of Noe itself.
+  Principles discussed below explain why this is important.
+
+### Master the tools YOU use
+
+The separation of concerns described previously also drives what you have to learn and what
+tools you have to master:
+
+* As an ordinary Noe user (vs. skeleton maintainer) and because Noe itself (unlike skeletons
+  is project agnostic, you only have to know **basic Noe commands** (see 'noe --help') and 
+  should never have to study Noe's API and internals. In contrast, you have to **master the 
+  tools and best practices of your product's ecosystem**. A good skeleton should help you 
+  along this task. As an example, the default ruby skeleton is fully documented to help you 
+  gaining understanding of ***rake*, *spec*, *yard*, *bundler*** and so on but **not noe 
+  itself**. 
+  
+* This explains why Noe itself is not a runtime dependency. Using a particular skeleton 
+  already means learning a lot, at least in the long run (see the section about Magic below). 
+  Noe avoids interfering with generated products to avoid making the learning curve even 
+  worse.
+
+* Being a skeleton creator/maintainer is another story of course. To write a skeleton you'll 
+  also have to learn **Noe's API and internals**. To write a good/reusable one, you'll 
+  certainly have to **master the full ecosystem and best practices of the targetted product**, 
+  which is a good opportunity for learning and sharing it!
+
+### Magic Only If Flexible
+
+"Don't Repeat Yourself" and "Convention over Configuration" are certainly good principles. 
+However tuning, configuration and options exist, are useful and should certainly not be 
+hidden to the user. Instead configuration and options should come with default values, 
+and should be fully documented. Providing magic is great if there is a user-centric way 
+(in contrast to a developer one) of understanding and controlling the magic and underlying 
+assumptions.
+
+As an example, the default ruby template comes with some magic: you can create a project 
+and immediately invoke 'rake test', 'rake yard', ... and not investigating further. You 
+can also have a look at the _tasks_ folder to understand and control the rake tasks that 
+your project will use... In fact, you **must** investigate: the generated product is yours, 
+not mine and YOU have to master your build chain!
+  
+## Ruby skeleton and Related projects
+
+Noe is inspired by existing projects, mostly from the ruby community. In particular, the 
+default ruby template has been heavily influenced by the projects below as well as feedback 
+of their authors:
+
+* [hoe](http://seattlerb.rubyforge.org/hoe/), Ryan Davis and Eric Hodel 
+* [echoe](https://github.com/fauna/echoe), Evan Weaver 
+* [bones](https://github.com/TwP/bones), Tim Pease
+
+These projects help you generating and maintaining ruby projects (generally gem libraries, 
+in fact). All provide powerful tools that supports you along the different steps of your 
+ruby software lifecycle (creating, testing, releasing, announcing, and so on.). They mostly
+differ in the way you can tune/configure the generated project for specific needs. 
+
+These projects differ from the Ruby skeleton proposed by Noe in that they use a control 
+approach (rake tasks installed in your project via a development/runtime dependency) while 
+Noe uses a generative approach (the generated ruby project and rake tasks do not depend on 
+Noe at all).
+
+You'll find more information about the Noe's ruby skeleton in it's own 
+[README](https://github.com/blambeau/noe/blob/master/templates/ruby/README.md).
+
+## Short guide for template maintainers
 
 Under ~/.noe, a valid template folder (say xxx) has the following structure
 
@@ -63,16 +128,17 @@ Under ~/.noe, a valid template folder (say xxx) has the following structure
 
 ### 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 of a template is used to formally describe the template. When a 
+project (say foo) is created (see 'noe prepare') 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}
+      summary: ...
       description: ...
       version: ...
       author: ...
@@ -90,16 +156,16 @@ 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:
+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 
+* 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.
+* 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
 
@@ -111,7 +177,7 @@ Fork Noe on github! I'm particularly interested in the following enhancements:
 * 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.
+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

@@ -1,24 +1,22 @@
-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
+begin
+  gem "bundler", "~> 1.0"
+  require "bundler/setup"
+rescue LoadError
+  abort "This project requires bundler, try 'gem install bundler'"
 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
+# Dynamically load the gem spec
+$gemspec_file = File.expand_path('../noe.gemspec', __FILE__)
+$gemspec      = Kernel.eval(File.read($gemspec_file))
+
+# We run tests by default
+task :default => :test
 
-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
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  instance_eval File.read(taskfile), taskfile
 end

data/bin/noe

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

data/lib/noe.rb

@@ -1,39 +1,25 @@
 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
+  VERSION = "1.1.0".freeze
   
   class Error < StandardError; end
 
 end # module Noe
-
-Noe.require('quickl', ">= 0.2.0")
-Noe.require('wlang', ">= 0.9")
+require 'noe/loader'
 require 'yaml'
 require 'fileutils'
+require 'noe/ext/array'
+require 'noe/ext/hash'
 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/prepare'
 require 'noe/go'
+require 'noe/show_spec'
 

data/lib/noe/commons.rb

@@ -1,6 +1,16 @@
 module Noe
   module Commons
     
+    # Install options
+    def self.add_common_options(opt)
+      opt.on_tail("--version", "Show version") do
+        raise Quickl::Exit, "#{File.basename($0 || 'noe')} #{Noe::VERSION} (c) 2011, Bernard Lambeau"
+      end
+      opt.on_tail('--help', "Show detailed help") do 
+        raise Quickl::Help
+      end
+    end
+      
     # Returns configuration to use
     def config
       requester.config 
@@ -13,6 +23,19 @@ module Noe
     def template(name = config.default)
       Template.new(File.join(templates_dir, name))
     end
+    
+    def find_noespec_file(args)
+      # 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
+    end
 
   end # module Commons
 end # module Noe

data/lib/noe/config.yaml

@@ -22,8 +22,8 @@ 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.
+# that need a template (see 'noe help prepare', for example) use this 
+# by default, and allow overriding it via a --template=NAME option.
 #
 default:
   ruby

data/lib/noe/ext/array.rb

@@ -0,0 +1,18 @@
+class Array
+  
+  def methodize_hashes!(recursive = true)
+    self.each do |val|
+      case val
+      when Hash
+        val.methodize!(recursive)
+      when Array
+        val.methodize_hashes!(recursive)
+      end
+    end
+  end
+  
+  def noe_merge(right)
+    (self + right).uniq
+  end
+  
+end # class Array

data/lib/noe/ext/hash.rb

@@ -0,0 +1,48 @@
+class Hash
+  
+  # Methodize this hash
+  def methodize!(recursive = true)
+    self.extend(Methodize)
+    if recursive
+      self.values.each do |val|
+        case val
+        when Hash
+          val.methodize!(recursive)
+        when Array
+          val.methodize_hashes!(recursive)
+        end
+      end
+    end
+  end
+  
+  # Makes a fully recursive merge
+  def noe_merge(right)
+    self.merge(right) do |key,oldval,newval|
+      if oldval.nil?
+        newval
+      elsif oldval.class != newval.class
+        raise Noe::Error, "Conflict on #{key} has to be resolved manually, sorry.\n"\
+                          "#{oldval} (#{oldval.class}) vs. #{newval} (#{newval.class})"
+      elsif oldval.respond_to?(:noe_merge)
+        oldval.noe_merge(newval)
+      else
+        newval
+      end
+    end
+  end
+  
+  module Methodize
+  
+    # Allows using hash.key as a synonym for hash[:key] and
+    # hash['key']
+    def method_missing(name, *args, &block)
+      if args.empty? and block.nil?
+        self[name] || self[name.to_s]
+      else
+        super(name, *args, &block)
+      end
+    end
+
+  end
+
+end