treebis 0.0.1

data/README

@@ -0,0 +1,98 @@
+<embed
+  style='position: absolute; right:0; top:0'
+  src="svg/go-green.svg" width="150px" height="150px"
+  type="image/svg+xml"
+  pluginspage="http://www.adobe.com/svg/viewer/install/" />
+
+
+# treebis
+
+## summary
+minimal single-file rake-like task DSL for wrapping common filesystem tasks like copying files.
+
+
+## description
+Treebis is a minimal, general scripting/task utility written in ruby that wraps common actions for moving, copying and altering filetrees.  It is geared towards things like generators.  It is comparable to a shell script that does a lot of mkdir, mv, cp commmands etc.
+
+
+## what it is:
+  - task wrapper for external commands that make filetrees, e.g.
+    - maybe the generators in things like rails, ramaze, nandoc
+  - proxy around FileUtils that allows customizing its output
+  - copies filetrees to filetrees
+  - removes filetrees from filetrees
+  - applies diffs to filetrees
+  - different ways to represent trees and diffs - heredocs, diffs, filesystem.
+  - under 1000 SLOC
+  - rcov test coverage usually hovers between 95-100%
+
+## what it is not:
+  - a vcs or vcs wrapper (version control system)
+  - atomic
+
+## frequently asked questions
+
+### Q: why use it?
+<span class='answer'>A</span>: Because you want a consistent way to wrap these common tasks that doesn't explicitly rely on shelling out to the underlying system, or other hodgepodges.  (also see 'why did you make this?' below)
+
+### Q: why not use it?
+<span class='answer'>A</span>: Because it doesn't do what you want or it does what you do not want.
+
+### Q: why is it named "Treebis?"
+<span class='answer'>A</span>: because it rhymes with "Jeebus."
+
+### Q: why did you make this?
+<span class='answer'>A</span>: by the third or fourth time i found myself re-writing this same kind of thing for different projects, or bleeding from its absence, i decided to abstract it.  It's more readable than a bunch of FileUtils statements,  it paves the way for possible future enhancements like atomicitiy and units of work; and wouldn't it be nice if every generator of every project used the same library?
+
+## requirements
+  - ruby 1.8.7
+  - Treebis supports the application of unified diffs to single files
+      and whole directories.  If this functionality is desired,
+      Treebis was developed with GNU `patch` 2.5.8.  Most versions of patch
+      will likely work.
+
+## installation
+
+### install the gem:
+
+from the command line:
+~~~
+~ > gem install treebis
+~~~
+
+
+### or grab the file:
+
+<em>
+<a class='no-style' href='#' title='At The Time of This Writing'>ATTOTW</a>
+treebis is a single file without dependencies except 'json'.  You can
+<a href='http://github.com/hipe/treebis/blob/master/lib/treebis.rb'>just download it</a> and throw it in your code directory
+<sup id="fnref:trollop"><a href="#fn:trollop" rel="footnote">1</a></sup>
+</em>
+
+
+## usage
+May I refer you to these [usage examples](usage-examples)?
+
+## future promises made today:
+  - dry run ?
+  - two-pass units of work !!??
+
+
+<br />
+<br />
+<hr />
+
+### Footnotes
+
+<div class="footnotes">
+  <ol>
+    <li id="fn:trollop">
+      <p>Appologies to <a href='http://trollop.rubyforge.org/'>trollop</a>
+        from which is stole this langauge and idea of keeping things in a
+        single file when practical.
+        <a href="#fnref:trollop" rev="footnote">&#8617;</a>
+      </p>
+    </li>
+  </ol>
+</div>

data/Rakefile

@@ -0,0 +1,49 @@
+task :default => :test
+
+me = "\e[35mtreebis\e[0m "
+
+desc  "#{me}generate rcov coverage"
+task :rcov do
+  sh "rcov --exclude '.*gem.*' lib/treebis.rb"
+end
+
+desc "#{me}run them"
+task :test do
+  sh "ruby -w lib/treebis.rb"
+  require File.dirname(__FILE__)+'/test/test-for-doc.rb'
+end
+
+desc "#{me}see if the tests for docs run"
+task :doc do
+  require File.dirname(__FILE__)+'/test/test_for_doc.rb'
+end
+
+desc "#{me}hack turns the installed gem into a symlink to this directory"
+task :hack do
+  kill_path = %x{gem which treebis}
+  kill_path = File.dirname(File.dirname(kill_path))
+  new_name  = File.dirname(kill_path)+'/ok-to-erase-'+File.basename(kill_path)
+  FileUtils.mv(kill_path, new_name, :verbose => 1)
+  this_path = File.dirname(__FILE__)
+  FileUtils.ln_s(this_path, kill_path, :verbose => 1)
+end
+
+
+require 'jeweler'
+require 'nandoc'
+require 'nandoc/parse-readme'
+
+Jeweler::Tasks.new do |s|
+  s.add_dependency 'json'
+  s.authors = ['Chip Malice']
+  s.description = NanDoc::ParseReadme.description('README')
+  s.files =  FileList['[A-Z]*', '{bin,doc,generators,lib,test}/**/*']
+  s.email = 'chip.malice@gmail.com'
+  s.homepage = 'http://treebis.hipeland.org'
+  s.name = 'treebis'
+  s.rubyforge_project = 'treebis'
+  s.summary = NanDoc::ParseReadme.summary('README')
+  
+  s.add_dependency 'json', '~> 1.2.3'
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/doc/additional-goodies/persistent-dotfile.md

@@ -0,0 +1,38 @@
+# treebis
+
+## additional goodies
+
+### PersistentDotfile
+
+Initially an auxilliary class for testing, `PeristentDotfile` proved to be a useful little utility in its own right which I may end up getting more miles out of than Treebis itself in my other projects.  It simply:
+
+  * wraps `Dir#tmpdir` which gives you a platform-independent api to (the platform dependent location of) a temporary directory.
+  * gives you an awesome little persistent JSON structure that you can write to and read accross invocations to your app.[^sessions]
+
+(see: test-for-doc.rb - 'persistent dotfile')
+
+
+What's happening here is: 1) we're using the dubious pattern of making some modules and extending `self`, which is a quick and dirty way to get a singleton object[^sing].
+
+2) We're enhancing the modules in question with `PersistentDotfile`. Instead of `include`ing it, we employ the `include_to` pseudo-pattern. It's like an `include()` but it makes explicit (some of) the creepy metaprogramming going on behind the scenes, and it allows us to pass parameters to the enhancement.
+
+In this case, we are passing `'somefile.json'` which is an argument that tells the module where to write its persistent data.  (Making it a relative path like this, it will write the file to whatever the current working directory is when it goes to save it.)
+
+As you can (sort of) see from the output, the first module writes the data to the file and the second module reads it.
+
+Just for fun, let's see what it's writing to that file:
+
+(see: test-for-doc.rb - 'persistent dotfile' -- 'see contents')
+
+
+Simply amazing.
+
+There're other mind-blowing things `PersistentDotfile` can achieve that will change your life, like making a temporary directory.
+
+<br />
+<br />
+<hr />
+### _Footnotes_ ###
+
+[^sessions]:comparable to a really cheap & easy session façade you find in all web frameworks
+[^sing]:the other kind of purist would have you use the [singleton module](http://www.ruby-doc.org/stdlib/libdoc/singleton/rdoc/files/singleton_rb.html) to make a singleton module.

data/doc/svg/go-green.svg

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="175" height="175"
+ viewBox="0.00 0.00 175.00 175.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="blah1" class="whatevs" transform="scale(1 1) rotate(0) translate(0 0)">
+<title>this_some_awesome_thing</title>
+<polygon fill="white" stroke="white" points="5,140 5,0 140,0 140,140 5,140"/>
+<g id="node1" class="node">
+<polygon fill="#ccee33" points="19,0 175,0 175,132 169,122 162,132 157,122 148,130 145,119 136,127 133,116 124,124 121,113 112,120 109,109 99,116 98,104 87,109 87,98 76,104 76,92 65,97 65,86 54,91 55,80 43,84 45,73 33,75 38,64 26,64 32,54 21,53 28,44 17,42 25,34 14,32 23,25 12,21 22,16 12,12 21,7 13,3 15,0"/>
+
+<g id="blah2" class="whatevs" transform="scale(1) rotate(20) translate(12, -30)">
+<text text-anchor="middle" x="108" y="32" font-family="Super Sans; sans-serif" font-size="22" fill="#332200">go green!</text>
+<text text-anchor="middle" x="108" y="59" font-family="serif" font-size="22" fill="#332200">go treebis!</text>
+</g>
+
+</g>
+</g>
+</svg>

data/doc/usage-examples.md

@@ -0,0 +1,41 @@
+# Treebis
+
+## Usage Examples
+
+### Using DirAsHash to write files
+_quick and dirty way to make files and folders from a hash:_
+
+(see: test-for-doc.rb - 'using dir as hash')
+
+In the above example we see a way to write two folders with three files.
+
+The class we make included DirAsHash and used its `hash_to_dir()` method.
+
+For the hash elements that are strings, the keys become filenames and the string become file contents.  For the hash values that are themselves hashes, the hash key becomes a folder name, and so on.
+
+The last line shows that the files were written successfully.
+
+### Making and Running a Treebis Task
+_minimal treebis example_
+
+The above example was just for giving us some files to work with.  In practice it is not a very practical way to write files of any significant length, if for no other reason than for how unreadable it would be (and hence useless to be in ruby.)[^in_prac]
+
+Let's say you want to write a script that installs these files to some arbitrary directory.  *That* is exactly what our little Treebis here is for.
+
+Let's say also you don't want to write all the files to the target location, just those files matching a fileglob pattern.  Furthermore let's say you want to process one of the files as an erb template, for which we will provide values to substitute for placeholders in the document:
+
+(see: test-for-doc.rb - 'first task')
+
+Above we see that a Task object is composed of a code block composed of a sequence of commands, many of which are wrappers around the familiar FileUtils methods.
+
+Treebis tasks usually work with files _from_ a location and apply them _on_ another location (either copying files directly or interpolating them along the way, or applying diff patches.)  A Task won't autmatically make any directories without explicitly being told to do so, so we make directories in two places above.
+
+In the last line we see that the net result of this is that the task wrote to the target directory two of the three files from the source directory, and in one of the files it interpolated the erb template with values that we passed to it.
+
+I really wanted to show you the pretty colors in the output but I must get going!
+
+<br />
+<hr />
+### _Footnotes_ ###
+
+[^in_prac]: In practice I *do* however write files this way for many of my tests, including the one that generated the examples for this file ;)