DESCRIPTION

Sourcery is an journey into the realm of Ruby meta-meta-programming. Let's call it astrological-programming or just plan Sourcery.

The idea is that all source code files are written with the ability to embedded eRuby templating, combined with dotRuby metadata, the source "spells" are cast to static lib files for actual usage. While arguably esoteric (but really what wizard isn't?), the result is equally as powerful.

FEATURES

  • Easy to use.
  • Uses ERB template. Versatile and Easy.
  • Uses meta or var directory entries for template variables. Clever and Easy.
  • Uses .ruby metadata for template variables too, if available. Smart and Easy.
  • Did I mention it was easy?

INSTRUCTION

Creating "Spells"

Sourcery template files reside in a project's src directory. The need no special naming. Simply edit files in src/ just as you would if they were in lib/.

For example, here's a file that provides copyright information and project version in code gathered from project metadata.

# <%= title %>
<% copyrights.each |c| %>
# Copyright (c) <%= c['year'] %> <%= c['owner'] %>
<% end %>

class Example
  VERSION = "<%= version %>"
end

While not strictly necessary, it is advisable that you edit only src files and let all lib files be generated from there. Of course, if you are using it to cast only one or two files, then that is manageable and this course is not as pressing, but it remains a good idea in case you decide to become an archmage. If you do not you will find yourself burned by your creations, making the mistake of editing lib file when you should not. You have been warned.

Casting "Spells"

The sourcery command simply takes the files from the src directory, or specific files given as arguments to the command, and renders them to the `lib` directory. Typically all you need type is:

  $ sourcery

And all the source files ("spells") will be rendered ("cast") to lib/.

INSTALLATION

To install with RubyGems simply open a console and type:

  $ sudo gem install sourcery

Site installation requires Setup.rb (gem install setup), then download the tarball package and type:

  $ tar -xvzf sourcery-1.0.0.tar.gz
  $ cd sourcery-1.0.0.tar.gz
  $ sudo setup.rb all

Windows users will not need the sudo, but will probably need to be logged-in as an administrator of the system.