h1. About

"SimpleTemplater":http://github.com/botanicus/simple-templater is dead-simple solution for creating generators. It strongly uses convention over configuration, so you don't have to write loads of code to generate one stupid plain text README.

h1. Usage

h2. Available Generators

Even if SimpleTemplater is more API for writting generators, it has some custom included.

h3. Stub Generator

If you want to create your new generator, this is what you are looking for. Just run @simple-templater create stub my_generator@ and that's it!

* @--flat@ | @--no-flat@ (default: @--no-flat@)
* @--full@ | @--no-full@ (default: @--full@)
* @--setup-hook@ | @--no-setup-hook@ (default: @--setup-hook@)
* @--postprocess-hook@ | @--no-postprocess-hook@ (default: @--postprocess-hook@)

h3. Project Generator

Project generator can generate new Ruby project.

* @--full-name="Jakub Stastny"@
* @--git-repository@ if you want to create new Git repository and do the initial commit (default: will ask you)
* @--github-user=botanicus@ (default: ENV["USER"])
* @--github-repository=simple-templater@ (default: same as name of the new project)

h2. API

You would probably want to use simple templater for your own generators, here is how:

<pre>
require "simple-templater"

templater = SimpleTemplater.new(:rango, SimpleTemplater.logger)
if defined?(Gem) # try to find generators installed as gems
  templater.discovery!
else
  SimpleTemplater.logger.warn "Running without RubyGems which means SimpleTemplater won't be able to find generators distributed as a Gems."
  # register generators just for rango
  load File.join(File.dirname(__FILE__), "..", "simple-templater.scope")
end
templater.run(ARGV.shift) # run generator from ARGV, for example "project"
</pre>

h2. File Hierarchy

- @stubs/#{generator_name}/setup.rb@
- @stubs/#{generator_name}/postprocess.rb@
- @stubs/#{generator_name}/content@

h2. Templates

Every file in @stubs/#{generator_name}/content@ will be proceed:

- *Files which doesn't require ERB processing* are simply copy from @stubs/#{generator_name}/content/file.txt@ to @#{project_name}/file.txt@
- *Files with .rbt extension and ERB tags inside* will be proceed by Erubis and the result without @.rbt@ extension will be written to @stubs/#{generator_name}/content/app/models/post.rb@ to @#{project_name}/app/models/post.rb@.
- If you want to generate file with @rbt@ extension, just put append another .rbt: @file.txt.rbt.rbt@ => @#{project_name}/file.txt.rbt@. The template will be proceed by Erubis. If you want to get @<%= %>@ on the output, just use @<%%= %>@.

h2. Hooks

Each item in ARGV starting with @--@ is processed by a hook. Hooks can be distributed

<pre>
# default arguments for hook
hook do |generator, context|
  context.reverse_merge!(git_repository: true)
end
</pre>

h3. Preprocessing

h4. ARGV Parsing

- First argument will typically be name of the generator (unless you provide just one generator and the name is hardcoded)
- @--orm@ to @{orm: true}@
- @--no-orm@ to @{orm: false}@
- @--orm=datamapper@ to @{orm: "datamapper"}@
- @--models=post,comment@ to @{models: ["post", "comment"]}@
- @options = ARGV.parse!@
- For testing you may use the @parse!@ method after @YourArray.extend(ArgvParsingMixin)@

h4. User Interaction

- Do you want to
- @--github@ or @--no-github@

@your-gen project --models=post,comment --controller=posts --orm=datamapper@

- the script don't have to be Ruby, but it will be easier for you since SimpleTemplater provides some basic ARGV parsing for you
- the script have to be executable

h2. Postprocessing

h3. Examples

- initialize Git repository
- create Git repository on GitHub and push

h1. Custom Generators

Each user can create its own generators and put them to @~/.#{project_name}/stubs/#{generator_name}@. For example project generators for Rango should be placed to @~/.rango/stubs/project@

h2. Generators Registration in Plugins

You often may want to

In Rango:

<pre>
SimpleTemplater::Discovery.discover!(:rango)
</pre>

<pre>
SimpleTemplater.register(:rango) # register relative path to stubs/*
</pre>

or

<pre>
SimpleTemplater.register(:rango) do
  # do some initialization
end
</pre>

h2. Diff Generators

- rewrite some default files
- hooks

h1. Links

- "Source Code":http://github.com/botanicus/simple-templater
- "RunCodeRun":http://runcoderun.com/botanicus/simple-templater
- "API Documentation":http://rdoc.info/projects/botanicus/simple-templater