noe 1.0.0 → 1.1.0

data/templates/ruby/src/tasks/spec_test.rake

@@ -0,0 +1,61 @@
+#
+# Install a rake task for running examples written using rspec.
+#
+# More information about rspec: http://relishapp.com/rspec
+# This file has been written to conform to RSpec v2.4.0
+#
+begin
+  require "rspec/core/rake_task"
+  desc "Run RSpec code examples"
+  RSpec::Core::RakeTask.new(:spec_test) do |t|
+    # Glob pattern to match files.
+    t.pattern = 'spec/**/*_spec.rb'
+
+    # By default, if there is a Gemfile, the generated command will include
+    # 'bundle exec'. Set this to true to ignore the presence of a Gemfile, 
+    # and not add 'bundle exec' to the command.
+    t.skip_bundler = false
+
+    # Name of Gemfile to use
+    t.gemfile = 'Gemfile'
+
+    # Whether or not to fail Rake when an error occurs (typically when 
+    # examples fail).
+    t.fail_on_error = true
+
+    # A message to print to stderr when there are failures.
+    t.failure_message = nil
+
+    # Use verbose output. If this is set to true, the task will print the
+    # executed spec command to stdout.
+    t.verbose = true
+
+    # Use rcov for code coverage?
+    t.rcov = false
+
+    # Path to rcov.
+    t.rcov_path = 'rcov'
+
+    # Command line options to pass to rcov.
+    # See 'rcov --help' about this
+    t.rcov_opts = %w{}
+
+    # Command line options to pass to ruby.
+    # See 'ruby --help' about this 
+    t.ruby_opts = %w{}
+
+    # Path to rspec
+    t.rspec_path = 'rspec'
+
+    # Command line options to pass to rspec.
+    # See 'rspec --help' about this
+    t.rspec_opts = %w{--color --backtrace}
+  end
+rescue LoadError => ex
+  task :spec_test do
+    abort 'rspec is not available. In order to run spec, you must: gem install rspec'
+  end
+ensure
+  task :spec => [:spec_test]
+  task :test => [:spec_test]
+end

data/templates/ruby/src/tasks/unit_test.rake

@@ -0,0 +1,56 @@
+#
+# Install a rake task for running examples written using rspec.
+#
+# More information about rspec: http://relishapp.com/rspec
+# This file has been written to conform to RSpec v2.4.0
+#
+begin
+  desc "Lauches unit tests"
+  require 'rake/testtask'
+  Rake::TestTask.new(:unit_test) do |t|
+
+    # List of directories to added to $LOAD_PATH before running the
+    # tests. (default is 'lib')
+    t.libs = %w{ lib }
+
+    # True if verbose test output desired. (default is false)
+    t.verbose = false
+
+    # Test options passed to the test suite.  An explicit TESTOPTS=opts 
+    # on the command line will override this. (default is NONE)
+    t.options = []
+
+    # Request that the tests be run with the warning flag set.
+    # E.g. warning=true implies "ruby -w" used to run the tests.
+    t.warning = false
+
+    # Glob pattern to match test files. (default is 'test/test*.rb')
+    t.pattern = 'test/test*.rb'
+
+    # Style of test loader to use.  Options are:
+    #
+    # * :rake -- Rake provided test loading script (default).
+    # * :testrb -- Ruby provided test loading script.
+    # * :direct -- Load tests using command line loader.
+    # 
+    t.loader = :rake
+
+    # Array of commandline options to pass to ruby when running test 
+    # loader.
+    t.ruby_opts = []
+
+    # Explicitly define the list of test files to be included in a
+    # test.  +list+ is expected to be an array of file names (a
+    # FileList is acceptable).  If both +pattern+ and +test_files+ are
+    # used, then the list of test files is the union of the two.
+    t.test_files = nil
+
+  end
+rescue LoadError => ex
+  task :unit_test do
+    abort 'rspec is not available. In order to run spec, you must: gem install rspec'
+  end
+ensure
+  task :test => [:unit_test]
+end
+

data/templates/ruby/src/tasks/yard.rake

@@ -0,0 +1,36 @@
+# 
+# Install a rake task to generate API documentation using
+# yard.
+#
+# More information about yard: http://yardoc.org/
+# This file has been written to conform to yard v0.6.4
+#
+# About project documentation
+begin
+  require "yard"
+  desc "Generate yard documentation"
+  YARD::Rake::YardocTask.new(:yard) do |t|
+    # Array of options passed to the commandline utility
+    # See 'yardoc --help' about this
+    t.options = %w{--output-dir doc/api - README.md CHANGELOG.md LICENCE.md}
+    
+    # Array of ruby source files (and any extra documentation files 
+    # separated by '-')
+    t.files = ['lib/**/*.rb']
+    
+    # A proc to call before running the task
+    # t.before = proc{ }
+    
+    # A proc to call after running the task
+    # r.after = proc{ }
+    
+    # An optional lambda to run against all objects being generated. 
+    # Any object that the lambda returns false for will be excluded 
+    # from documentation. 
+    # t.verifier = lambda{|obj| true}
+  end
+rescue LoadError
+  task :yard do
+    abort 'yard is not available. In order to run yard, you must: gem install yard'
+  end
+end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: noe
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  hash: 19
+  prerelease: 
   segments: 
   - 1
+  - 1
   - 0
-  - 0
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Bernard Lambeau
@@ -14,99 +15,323 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-10 00:00:00 +01:00
+date: 2011-01-15 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: wlang
   prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  name: rake
+  type: :development
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
+        hash: 49
         segments: 
         - 0
-        - 9
-        - 2
-        version: 0.9.2
-  type: :runtime
-  version_requirements: *id001
+        - 8
+        - 7
+        version: 0.8.7
+  requirement: *id001
 - !ruby/object:Gem::Dependency 
-  name: quickl
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  name: bundler
+  type: :development
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
+        hash: 15
         segments: 
+        - 1
         - 0
+        version: "1.0"
+  requirement: *id002
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  name: rspec
+  type: :development
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 31
+        segments: 
         - 2
+        - 4
         - 0
-        version: 0.2.0
-  type: :runtime
-  version_requirements: *id002
+        version: 2.4.0
+  requirement: *id003
 - !ruby/object:Gem::Dependency 
-  name: rake
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  name: yard
+  type: :development
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
+        hash: 15
         segments: 
         - 0
-        version: "0"
-  type: :development
-  version_requirements: *id003
+        - 6
+        - 4
+        version: 0.6.4
+  requirement: *id004
 - !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  name: bluecloth
+  type: :development
+  version_requirements: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
+        hash: 29
         segments: 
         - 2
-        - 4
         - 0
-        version: 2.4.0
-  type: :development
-  version_requirements: *id004
+        - 9
+        version: 2.0.9
+  requirement: *id005
 - !ruby/object:Gem::Dependency 
-  name: yard
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  name: wlang
+  type: :runtime
+  version_requirements: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
+        hash: 55
         segments: 
         - 0
-        - 6
-        - 4
-        version: 0.6.4
-  type: :development
-  version_requirements: *id005
+        - 10
+        - 0
+        version: 0.10.0
+  requirement: *id006
 - !ruby/object:Gem::Dependency 
-  name: bluecloth
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  name: quickl
+  type: :runtime
+  version_requirements: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
+        hash: 23
         segments: 
         - 0
+        - 2
+        - 0
+        version: 0.2.0
+  requirement: *id007
+- !ruby/object:Gem::Dependency 
+  prerelease: false
+  name: highline
+  type: :runtime
+  version_requirements: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 1
         - 6
-        - 4
-        version: 0.6.4
-  type: :development
-  version_requirements: *id006
-description: A simple and extensible project generator
-email: blambeau@gmail.com
+        - 0
+        version: 1.6.0
+  requirement: *id008
+description: |
+  # Noe - A simple and extensible project generator
+  
+  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. 
+  
+  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
+  
+      [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. To 
+  instantiate a ruby project simply execute the following commands in turn:
+  
+      # Given a template ruby under ~/.noe/ruby, install by default
+      noe prepare --template=ruby 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 prepare' and 'not help go' for additional
+  options.
+  
+  ## 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
+  
+      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 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: ...
+  
+      #
+      # 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.
+  
+  * ...
+
+email: 
+- blambeau@gmail.com
 executables: 
 - noe
 extensions: []
@@ -114,44 +339,82 @@ extensions: []
 extra_rdoc_files: 
 - README.md
 - CHANGELOG.md
+- LICENCE.md
 files: 
-- bin/noe
-- lib/noe/commons.rb
-- lib/noe/config.rb
-- lib/noe/config.yaml
-- lib/noe/create.rb
-- lib/noe/go.rb
-- lib/noe/help.rb
-- lib/noe/install.rb
-- lib/noe/list.rb
-- lib/noe/main.rb
-- lib/noe/template.rb
-- lib/noe.rb
+- ./noe.gemspec
+- ./CHANGELOG.md
+- ./Gemfile
+- ./bin/noe
+- ./lib/noe/commons.rb
+- ./lib/noe/config.rb
+- ./lib/noe/config.yaml
+- ./lib/noe/ext/array.rb
+- ./lib/noe/ext/hash.rb
+- ./lib/noe/go.rb
+- ./lib/noe/help.rb
+- ./lib/noe/install.rb
+- ./lib/noe/list.rb
+- ./lib/noe/loader.rb
+- ./lib/noe/main.rb
+- ./lib/noe/prepare.rb
+- ./lib/noe/show_spec.rb
+- ./lib/noe/template.rb
+- ./lib/noe.rb
+- ./LICENCE.md
+- ./Rakefile
+- ./README.md
+- ./spec/ext/hash/methodize_spec.rb
+- ./spec/noe_spec.rb
+- ./spec/spec_helper.rb
+- ./spec/template/entry/infer_wlang_dialect_spec.rb
+- ./spec/template/entry/relocate_spec.rb
+- ./spec/template/entry/rename_one_spec.rb
+- ./tasks/gem.rake
+- ./tasks/spec_test.rake
+- ./tasks/unit_test.rake
+- ./tasks/yard.rake
+- ./templates/ruby/CHANGELOG.md
+- ./templates/ruby/noespec.yaml
+- ./templates/ruby/README.md
+- ./templates/ruby/short.yaml
+- ./templates/ruby/src/__lower__.gemspec
+- ./templates/ruby/src/CHANGELOG.md
+- ./templates/ruby/src/Gemfile
+- ./templates/ruby/src/lib/__lower__/loader.rb
+- ./templates/ruby/src/lib/__lower__.rb
+- ./templates/ruby/src/LICENCE.md
+- ./templates/ruby/src/Manifest.txt
+- ./templates/ruby/src/Rakefile
+- ./templates/ruby/src/README.md
+- ./templates/ruby/src/spec/__lower___spec.rb
+- ./templates/ruby/src/spec/spec_helper.rb
+- ./templates/ruby/src/tasks/gem.rake
+- ./templates/ruby/src/tasks/spec_test.rake
+- ./templates/ruby/src/tasks/unit_test.rake
+- ./templates/ruby/src/tasks/yard.rake
+- spec/ext/hash/methodize_spec.rb
 - spec/noe_spec.rb
 - spec/spec_helper.rb
+- spec/template/entry/infer_wlang_dialect_spec.rb
 - spec/template/entry/relocate_spec.rb
 - spec/template/entry/rename_one_spec.rb
-- templates/ruby/CHANGELOG.md
-- templates/ruby/noespec.yaml
-- templates/ruby/README.md
-- templates/ruby/src/__lower__.gemspec
-- templates/ruby/src/CHANGELOG.md
-- templates/ruby/src/lib/__lower__.rb
-- templates/ruby/src/LICENCE.txt
-- templates/ruby/src/Rakefile
-- templates/ruby/src/README.md
-- templates/ruby/src/spec/__lower___spec.rb
-- templates/ruby/src/spec/spec_helper.rb
-- noe.gemspec
-- Rakefile
+- bin/noe
 - README.md
 - CHANGELOG.md
-- LICENCE.txt
+- LICENCE.md
 has_rdoc: true
 homepage: http://github.com/blambeau/noe
 licenses: []
 
-post_install_message: 
+post_install_message: |
+  Noe successfully installed!
+  
+  What's next?
+    - 'noe help install' for configuration and default templates
+    - 'noe prepare --template=ruby hello_world'
+  
+  Thank you for using Noe, enjoy!
+
 rdoc_options: []
 
 require_paths: 
@@ -161,6 +424,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -169,15 +433,21 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.4.2
 signing_key: 
 specification_version: 3
-summary: Noe helps development by providing support for project templates and instantiation.
-test_files: []
-
+summary: 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.
+test_files: 
+- spec/ext/hash/methodize_spec.rb
+- spec/noe_spec.rb
+- spec/spec_helper.rb
+- spec/template/entry/infer_wlang_dialect_spec.rb
+- spec/template/entry/relocate_spec.rb
+- spec/template/entry/rename_one_spec.rb