skeletor 0.6.3 → 0.6.4

data/README.md

@@ -43,6 +43,145 @@ Validates that TEMPLATE is a valid YAML file and that it matches the expected sc
 	
 Shows help information for TASK.
 
+Templates
+---------
+
+###Creating Templates###
+
+A Skeletor template is a YAML file in a folder with the same name as the file so for instance, a basic template on file would look like this:
+
+	sample-template/
+		- sample-template.yml
+	
+The yaml structure looks like this:
+
+	directory_structure:
+		-
+			dirname:
+				-
+					subdir:
+				-
+					NESTEDFILE
+		-
+			FILENAME
+	includes:
+		FILENAME: path/to/file
+		NESTEDFILE: remoteurloffile
+	tasks:
+		- TASKANDARGUMENTS
+		- ANOTHERTASKANDARGUMENTS
+		
+It should match the following schema:
+
+	sections:
+      - name: directory_structure
+        required: yes
+    	type: Array
+    	ok_empty: yes
+        accepts:
+          - directory_list
+          - file_list
+      - name: tasks
+        required: no
+        type: Array
+        accepts: 
+          - String
+      - name: includes
+        required: no
+        type: Hash
+        accepts:
+          - String
+    types:
+      directory_list:
+        type: Hash
+        ok_empty: no
+        accepts:
+          - directory
+      file_list:
+        type: Array
+        ok_empty: no
+        accepts:
+          - file
+      directory:
+        type: Array
+        ok_empty: yes
+        accepts:
+          - empty
+          - directory_list
+          - file_list
+      file:
+        type: String
+
+
+It contains 3 optional sections:
+
+####directory_structure####
+
+This is the main part of the template, but you can still leave it out if you just want skeletor to run tasks for you. In YAML parlance the directory_structure is a sequence 
+that contains either sequences or mappings. What this basically means is that it can contain a list of directories and a list of files.  The directory lists are mappings as
+well, with the directory name being the mapping name and the contents being another sequence defining a list of directories and/or a list of files.  The file list is a sequence
+of strings that define the file names. If the filenames are not listed in the includes section blank files will be created, otherwise the include will be copied from the given location.
+To specify an empty directory just create an empty mapping but remember to still put a space after the colon as YAML seems to be funny about parsing without that. You can use the built in
+validate action to check your template and the build action will also validate the template on load.
+
+####includes####
+
+This is a mapping of filenames to include locations.  The include locations can be anywhere on disk or a remote location accessible through either HTTP or HTTPS. Generally I would recommend
+storing these in subfolders in your template directory.
+
+####tasks####
+
+This denotes a list of tasks to run once the skeleton is set up. They are a string in the following format:
+
+	task[, argument...]
+	
+So for example to call the built in git_init task the tasks section would look like this
+
+	tasks:
+		- git_init, <skeleton_path>
+		
+You can pass any arguments you want but there are 3 placeholders that can be used to populate with data from the skeleton:
+
+* `<skeleton_path>` passes the location of the created skeleton to the task
+* `<skeleton_project>` passes the project name to the task
+* `<skeleton_template>` passes the name of the template used to the task
+ 
+There are also 2 built in tasks:
+ 
+* `git_init` Initializes a git repository in the newly created project
+* `capify` Generates capistrano deployment files
+
+The parser will look for built in tasks with the names supplied first so if you want to provide your own versions you will need to change the names. To supply your own tasks
+put them in a `tasks.rb` file in the root of your template directory.
+
+###Storing Templates###
+
+You can store the templates anywhere you like and just pass the path to them to the function but for ease of use you can create a `.skeletor` folder in your home directory and
+put your templates in a `templates` folder under that.  This way you just have to pass the template name and Skeletor will look here for the template.
+
+###Supplied Templates###
+
+Skeletor comes with 1 presupplied template but I'll be adding a few more as I have time.
+
+* `js-lib` Creates a skeleton for a Javascript library.  This is based on the structure I use for most Javascript projects which is in turn based on the structures of libraries such
+as Prototype and Scriptaculous.
+
+Coming Soon
+-----------
+
+* Add rDoc comments so rubygems.org can generate proper documentation
+* Add Tests
+* More Templates
+* Option to turn off or lessen output
+* Include parsing
+* Option to deal with file/folder existing conflicts.
+
+Notes
+-----
+
+This is my first gem and my first major work with ruby, so I'd be really grateful for any constructive feedback, input, suggestions etc. Also if anybody wants to
+contribute feel free, just check out the guidelines below (pretty standard stuff but it kinda makes sense).
+
 Contributing to Skeletor
 ------------------------
  

data/lib/skeletor.rb

@@ -1,5 +1,6 @@
 require 'skeletor/version'
 
+# Base module for gem.
 module Skeletor
   autoload :Skeletons, 'skeletor/skeletons'
   autoload :Tasks, 'skeletor/tasks'

data/lib/skeletor/builder.rb

@@ -2,8 +2,11 @@ require 'fileutils'
 
 module Skeletor
   
+  # The *Builder* class performs the main task of parsing the 
+  # loaded *Skeleton* and generating a project structure from it.
   class Builder
     
+    # Creates a new *Builder* instance
     def initialize(project,template,path)
       
       @project = project
@@ -13,6 +16,13 @@ module Skeletor
       
     end
     
+    # Builds the project skeleton
+    #
+    # If the target directory does not exist it is created, then the 
+    # directory structure is generated.
+    #
+    # Once the folder structure is set up and all includes have been 
+    # loaded/created, any tasks specified in the template file are run.    
     def build()
       
       #check dir exists, if not, make it
@@ -32,6 +42,7 @@ module Skeletor
       
     end
     
+    # Builds the directory structure
     def build_skeleton(dirs,path=@path)
         
         dirs.each{
@@ -62,6 +73,7 @@ module Skeletor
       
     end
     
+    # Cleans the directory of all files and folders
     def self.clean(path=@path)
       
       puts 'Cleaning directory of files and folders'
@@ -79,6 +91,8 @@ module Skeletor
       
     end
     
+    # Checks if file is listed in the includes list and if so copies it from
+    # the given location. If not it creates a blank file.
     def write_file(file,path)
       
       #if a pre-existing file is specified in the includes list, copy that, if not write a blank file      
@@ -96,6 +110,10 @@ module Skeletor
       
     end
     
+    # Parses the task string and runs the task.
+    #
+    # Will check *Skeleton::Tasks* module first before running tasks
+    # from the `tasks.rb` file in the template directory.
     def execute_tasks(tasks,template_path)
       
       if File.exists?(File.expand_path(File.join(template_path,'tasks.rb')))

data/lib/skeletor/cli.rb

@@ -2,8 +2,10 @@ require 'thor'
 
 module Skeletor
   
+  # The *CLI* class provides an interface for the command line functions 
   class CLI < Thor
     
+    
     desc "build TEMPLATE [options]", "Build project skeleton from TEMPLATE"
     method_option :directory,             
                   :aliases => "-d",
@@ -11,6 +13,7 @@ module Skeletor
     method_option :project, 
                   :aliases => "-p",
                   :desc => "Sets the project name. Defaults to current directory name."
+    # Creates a new *Builder* instance and builds the skeleton in the specified directory
     def build(template)
       path = options[:directory] || Dir.pwd
       project = options[:project] || File.basename(path)
@@ -19,10 +22,12 @@ module Skeletor
       skeleton.build
     end
 
+    
     desc "clean [options]" ,"Clean directory"
     method_option :directory,
                   :aliases => "-d",
                   :desc => "Sets the target directory. Defaults to current directory"
+    # Cleans out the specified directory
     def clean
       print 'Are you sure you want to clean this project directory? (Y|n): '
       confirm = gets.chomp
@@ -35,7 +40,8 @@ module Skeletor
       
     end
     
-    desc "validate TEMPLATE" ,"Checks TEMPLATE is a valid YAML file and matches the required schema."    
+    desc "validate TEMPLATE" ,"Checks TEMPLATE is a valid YAML file and matches the required schema."
+    # Loads a template, creates a new *Validator* and validates the template    
     def validate(template)
       skeleton = Skeletons::Loader.loadTemplate(template)
       validator = Skeletons::Validator.new(skeleton)

data/lib/skeletor/includes.rb

@@ -5,11 +5,17 @@ autoload :HTTPS, 'skeletor/protocols/https'
 
 module Skeletor
   
+  # The *Includes* class contains methods for dealing with
+  # loading and parsing required include files.
   class Includes
     
+    # Internal regular expression to match for includes that should be loaded from a remote destination
     PROTOCOL_PATTERN = /(?:([a-z][\w-]+):(?:\/{1,3}|[a-z0-9%]))/
+    # Specifies a list of supported protocols that *Skeletor* can load from.
     SUPPORTED_PROTOCOLS = ['http','https']
     
+    # Reads the required include from either the remote url or the local path and writes it to the 
+    # required location in the skeleton.
     def self.copy_include(include,target,path)
       
       #if include path includes a protocol. Load from that

data/lib/skeletor/protocols/http.rb

@@ -1,2 +1,3 @@
 require 'net/http'
+# loads HTTP module into constant
 HTTP = Net::HTTP

data/lib/skeletor/protocols/https.rb

@@ -1,3 +1,3 @@
-#require 'always_verify_ssl_certificates'
 require 'net/https'
+# loads HTTP module into constant
 HTTPS = Net::HTTP

data/lib/skeletor/skeletons.rb

@@ -1,5 +1,6 @@
 module Skeletor
   
+  # Contains the classes for dealing with the project templates
   module Skeletons
     autoload :Loader,     'skeletor/skeletons/loader'
     autoload :Validator,  'skeletor/skeletons/validator' 

data/lib/skeletor/skeletons/loader.rb

@@ -3,12 +3,20 @@ require 'YAML'
 module Skeletor
   
   module Skeletons
-
+    # *Loader* is a wrapper class to handle loading in the template file 
+    # from the various possible load paths.
+    #
+    # While accessible externally this is generally called internally.
     class Loader
       
+      # *TEMPLATE_PATH* specifies the internal directory for any included project templates.
       TEMPLATE_PATH = File.expand_path(File.join(File.dirname(File.dirname(__FILE__)), "templates"))
+      # *USER_TEMPLATE_PATH* specifies the path to the users personal template directory
       USER_TEMPLATE_PATH = File.expand_path('~/.skeletor/templates')
-       
+      
+      # Searches for the specified template and loads it into a variable
+      #
+      # Also adds the path where it was found to the returned Hash
       def self.loadTemplate(template)
         
         puts 'Loading Template - ' + template

data/lib/skeletor/skeletons/skeleton.rb

@@ -2,8 +2,12 @@ module Skeletor
   
   module Skeletons
     
+    # The *Skeleton* class provides a wrapper round the template file
+    # and handles loading it and validating it, as well as providing 
+    # default values for any missing sections.
     class Skeleton
       
+      #Creates a new *Skeleton* instance from `template`
       def initialize(template)
         
         begin
@@ -24,18 +28,22 @@ module Skeletor
           
       end
       
+      # Returns the directory structure section
       def directory_structure
         @directory_structure
       end
       
+      # Returns the tasks section
       def tasks
         @tasks
       end
       
+      # Returns the includes section
       def includes
         @includes
       end
       
+      # Returns the template path
       def path
         @path
       end   

data/lib/skeletor/skeletons/validator.rb

@@ -2,10 +2,15 @@ module Skeletor
   
   module Skeletons
     
+    # *Validator* handles validation of the loaded project template files against 
+    # the required schema
+    
     class Validator
       
+      # Defines the location to the required schema file for the templates
       SCHEMA_FILE = File.join Skeletons::Loader::TEMPLATE_PATH,'template-schema.yml'
       
+      # Creates a new *Validator* instance
       def initialize(template,schema=SCHEMA_FILE)
         @errors = []
         @template = template
@@ -13,7 +18,8 @@ module Skeletor
         @types = @schema['types'] || {}
       end
       
-       def validate()
+      # Validates the template against the schema
+      def validate()
         failed = []
         
         @schema['sections'].each{
@@ -48,7 +54,11 @@ module Skeletor
         end
         
       end
-
+      
+      # Checks template node matches the schema.
+      #
+      # Checks type of node against expected type and 
+      # checks any children are of the accepted types.
       def match_node(node,expected,label)
         
         #check type    
@@ -149,6 +159,11 @@ module Skeletor
                 
       end
       
+      # Checks that the node is of the correct type
+      #
+      # If the expected node is a custom node type as defined in the schema
+      # It will run `match_node` to check that the node schema matches the 
+      # custom type.
       def check_type(node,expected_type,label,accept_nil = false)
         
         valid_type = true;

data/lib/skeletor/tasks.rb

@@ -1,12 +1,16 @@
 module Skeletor
   
+  # The *Tasks* class contains the included tasks that may
+  # be run after the skeleton has been created.
   class Tasks
     
+    # Initializes an empty git repository in the new project directory
     def self.git_init(path)
       system "cd " + path + '
               git init'
     end
     
+    # Creates default capistrano deployment files in the new project directory
     def self.capify(path)
       system "capify " + path
     end

data/lib/skeletor/version.rb

@@ -1,3 +1,4 @@
 module Skeletor
-  VERSION="0.6.3"
+  # Current version number
+  VERSION="0.6.4"
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 6
-  - 3
-  version: 0.6.3
+  - 4
+  version: 0.6.4
 platform: ruby
 authors: 
 - Will McKenzie
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-26 00:00:00 +01:00
+date: 2011-09-27 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency