RubyGems - sidekick - Versions diffs - 0.5.1 → 0.6.0 - Mend

sidekick 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

data/.gitignore +1 -0
data/.gitmodules +3 -0
data/README.textile +23 -17
data/Rakefile +22 -23
data/VERSION +1 -1
data/annotated/helpers.html +143 -0
data/annotated/index.html +155 -0
data/annotated/lib/sidekick.html +144 -0
data/annotated/sidekick.html +155 -0
data/annotated/triggers.html +76 -0
data/annotated/util.html +74 -0
data/lib/sidekick.rb +44 -20
data/lib/sidekick/helpers/compile.rb +34 -0
data/lib/sidekick/helpers/passenger.rb +14 -0
data/lib/sidekick/helpers/shell.rb +10 -0
data/lib/sidekick/helpers/sidekick.rb +12 -0
data/lib/sidekick/helpers/system.rb +36 -0
data/lib/sidekick/helpers/user_interaction.rb +15 -0
data/lib/sidekick/triggers.rb +3 -4
data/lib/template +1 -3
metadata +17 -7
data/lib/sidekick/helpers.rb +0 -71
data/lib/sidekick/helpers/util.rb +0 -26
data/sidekick.gemspec +0 -71

data/annotated/sidekick.html ADDED

@@ -0,0 +1,155 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>sidekick.rb</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+        <a class="source" href="sidekick.html">sidekick.rb</a>
+        <a class="source" href="helpers.html">helpers.rb</a>
+        <a class="source" href="util.html">util.rb</a>
+        <a class="source" href="triggers.html">triggers.rb</a>
+        </div>
+    </div>
+  </div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>sidekick.rb</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id='section-1'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-1">#</a>
+        </div>
+        <p> <em>Sidekick</em> is a simple event driven background assistant. Among other things, you can use it to automatically compile assets, test code, restart servers and so on &ndash; as prescribed per project, in a <code>.sidekick</code> file. It is powered by EventMachine and Tilt.</p>
+<p> This is the annotated source code. See the <a href="http://github.com/jbe/sidekick#readme">README</a> too.</p>
+<hr />
+<p> Sidekick basically helps you do two things:</p>
+<p> &mdash; <em>Define</em> named triggers, such as saying that <code>watch(glob)</code> means doing something when a file matching <code>glob</code> changes, or that <code>every(duration)</code> means doing something every <code>duration</code> seconds.</p>
+<p> &mdash; <em>Use</em> the defined triggers with callbacks, such as <code>watch(**.rb) { notify 'Code change' }</code></p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="nb">require</span> <span class="s1">&#39;fileutils&#39;</span>
+<span class="nb">require</span> <span class="s1">&#39;eventmachine&#39;</span>
+<span class="k">module</span> <span class="nn">Sidekick</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-2'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-2">#</a>
+        </div>
+        <p> This core functionality is provided by <code>Sidekick::Triggers</code>.</p>
+<p> New triggers can be defined by calling <code>Sidekick::Triggers.register(:trigger_name) { ... }</code>.</p>
+<p>Basically, the job of a trigger definition is to take the parameters and the block from a call in <code>.sidekick</code> and use it to hook into EventMachine in some way. &mdash; Just have a look at the <a href="http://github.com/jbe/sidekick/blob/master/lib/sidekick/triggers.rb">default trigger library</a>.</p>
+<p> By using Ruby&rsquo;s <code>method_missing</code>, we can forward method calls to the registered trigger definitions. Any module can thereby extend the <code>Triggers</code> module in order to expose the defined triggers as if they were methods.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="k">module</span> <span class="nn">Triggers</span>
+    <span class="vc">@@triggers</span> <span class="o">=</span> <span class="p">{}</span>
+    <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">register</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
+      <span class="vc">@@triggers</span><span class="o">[</span><span class="nb">name</span><span class="o">]</span> <span class="o">=</span> <span class="n">block</span>
+    <span class="k">end</span>
+    <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">log</span><span class="p">(</span><span class="n">str</span><span class="p">)</span> <span class="c1"># used by triggers</span>
+      <span class="nb">puts</span> <span class="n">str</span>
+    <span class="k">end</span>
+    <span class="k">def</span> <span class="nf">method_missing</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">blk</span><span class="p">)</span>
+      <span class="vc">@@triggers</span><span class="o">[</span><span class="nb">name</span><span class="o">]</span> <span class="p">?</span>
+        <span class="vc">@@triggers</span><span class="o">[</span><span class="nb">name</span><span class="o">].</span><span class="n">call</span><span class="p">(</span><span class="n">blk</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span> <span class="p">:</span> <span class="k">super</span>
+    <span class="k">end</span>
+    <span class="k">def</span> <span class="nf">respond_to?</span><span class="p">(</span><span class="nb">method</span><span class="p">)</span>
+      <span class="k">super</span> <span class="o">||</span> <span class="o">!!</span><span class="vc">@@triggers</span><span class="o">[</span><span class="nb">method</span><span class="o">]</span>
+    <span class="k">end</span>
+  <span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-3'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-3">#</a>
+        </div>
+        <p> A default library of triggers and helpers is included..</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="nb">require</span> <span class="s1">&#39;sidekick/triggers&#39;</span>
+  <span class="nb">require</span> <span class="s1">&#39;sidekick/helpers&#39;</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-4'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-4">#</a>
+        </div>
+        <p> The <code>.sidekick</code> file is evaluated in a <code>Sidekick::Context</code> module, which exposes DSL style methods by extending <code>Sidekick::Triggers</code> and <code>Sidekick::Helpers</code>.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="no">Context</span> <span class="o">=</span> <span class="no">Module</span><span class="o">.</span><span class="n">new</span>
+  <span class="no">Context</span><span class="o">.</span><span class="n">extend</span> <span class="no">Triggers</span>
+  <span class="no">Context</span><span class="o">.</span><span class="n">extend</span> <span class="no">Helpers</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-5'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-5">#</a>
+        </div>
+        <p> The <code>Sidekick.run!</code> method reads and applies the <code>.sidekick</code> file, wrapping the setup phase inside <code>EM.run { .. }</code>, and thus begins the event loop.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">run!</span><span class="p">(</span><span class="n">path</span><span class="o">=</span><span class="s1">&#39;.sidekick&#39;</span><span class="p">)</span>
+    <span class="n">ensure_config_exists</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
+    <span class="no">Signal</span><span class="o">.</span><span class="n">trap</span><span class="p">(</span><span class="ss">:INT</span><span class="p">)</span> <span class="p">{</span> <span class="n">stop</span> <span class="p">}</span>
+    <span class="no">EventMachine</span><span class="o">.</span><span class="n">run</span> <span class="k">do</span>
+      <span class="no">Context</span><span class="o">.</span><span class="n">module_eval</span><span class="p">(</span>
+        <span class="nb">open</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="p">{</span><span class="o">|</span><span class="n">f</span><span class="o">|</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span> <span class="p">},</span> <span class="n">path</span> <span class="p">)</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+  <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">ensure_config_exists</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
+    <span class="k">unless</span> <span class="no">File</span><span class="o">.</span><span class="n">exists?</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
+      <span class="nb">puts</span> <span class="s1">&#39;Generate new sidekick file? (Y/n)&#39;</span>
+      <span class="nb">gets</span> <span class="o">=~</span> <span class="sr">/^N|n/</span> <span class="p">?</span> <span class="nb">exit</span> <span class="p">:</span>
+        <span class="no">FileUtils</span><span class="o">.</span><span class="n">cp</span><span class="p">(</span><span class="no">File</span><span class="o">.</span><span class="n">expand_path</span><span class="p">(</span><span class="s1">&#39;../template&#39;</span><span class="p">,</span>
+          <span class="bp">__FILE__</span><span class="p">),</span> <span class="n">path</span><span class="p">)</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+  <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">stop</span><span class="p">(</span><span class="n">msg</span><span class="o">=</span><span class="kp">false</span><span class="p">)</span>
+    <span class="no">EventMachine</span><span class="o">.</span><span class="n">stop</span>
+    <span class="nb">puts</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="si">#{</span><span class="n">msg</span><span class="si">}</span><span class="s2">&quot;</span> <span class="k">if</span> <span class="n">msg</span>
+  <span class="k">end</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    </table>
+</div>
+</body>

data/annotated/triggers.html ADDED

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>triggers.rb</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+        <a class="source" href="sidekick.html">sidekick.rb</a>
+        <a class="source" href="helpers.html">helpers.rb</a>
+        <a class="source" href="util.html">util.rb</a>
+        <a class="source" href="triggers.html">triggers.rb</a>
+        </div>
+    </div>
+  </div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>triggers.rb</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id='section-1'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-1">#</a>
+        </div>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="nb">require</span> <span class="s1">&#39;em-dir-watcher&#39;</span>
+<span class="k">module</span> <span class="nn">Sidekick::Triggers</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-2'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-2">#</a>
+        </div>
+        <p> default triggers</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">register</span> <span class="ss">:watch</span> <span class="k">do</span> <span class="o">|</span><span class="n">callback</span><span class="p">,</span> <span class="n">glob</span><span class="o">|</span>
+    <span class="no">EMDirWatcher</span><span class="o">.</span><span class="n">watch</span><span class="p">(</span>
+      <span class="no">File</span><span class="o">.</span><span class="n">expand_path</span><span class="p">(</span><span class="s1">&#39;.&#39;</span><span class="p">),</span>
+      <span class="ss">:include_only</span> <span class="o">=&gt;</span> <span class="o">[</span><span class="n">glob</span><span class="o">]</span><span class="p">,</span>
+      <span class="ss">:grace_period</span> <span class="o">=&gt;</span> <span class="mi">0</span><span class="o">.</span><span class="mi">2</span>
+      <span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">paths</span><span class="o">|</span>
+      <span class="n">log</span> <span class="s2">&quot;watch </span><span class="si">#{</span><span class="n">paths</span><span class="o">.</span><span class="n">inspect</span><span class="si">}</span><span class="s2">&quot;</span>
+      <span class="n">callback</span><span class="o">.</span><span class="n">call</span><span class="p">(</span><span class="n">paths</span><span class="p">)</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+  <span class="n">register</span> <span class="ss">:every</span> <span class="k">do</span> <span class="o">|</span><span class="n">callback</span><span class="p">,</span> <span class="n">duration</span><span class="o">|</span>
+    <span class="no">EventMachine</span><span class="o">::</span><span class="no">PeriodicTimer</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="n">duration</span><span class="p">)</span> <span class="k">do</span>
+      <span class="n">log</span> <span class="s2">&quot;every </span><span class="si">#{</span><span class="n">duration</span><span class="si">}</span><span class="s2"> seconds&quot;</span>
+      <span class="n">callback</span><span class="o">.</span><span class="n">call</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    </table>
+</div>
+</body>

data/annotated/util.html ADDED

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>util.rb</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+        <a class="source" href="sidekick.html">sidekick.rb</a>
+        <a class="source" href="helpers.html">helpers.rb</a>
+        <a class="source" href="util.html">util.rb</a>
+        <a class="source" href="triggers.html">triggers.rb</a>
+        </div>
+    </div>
+  </div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>util.rb</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id='section-1'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-1">#</a>
+        </div>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="k">module</span> <span class="nn">Util</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-2'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-2">#</a>
+        </div>
+        <p> :linux, :darwin, :other</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="k">def</span> <span class="nf">platform</span>
+    <span class="o">[</span><span class="ss">:linux</span><span class="p">,</span> <span class="ss">:darwin</span><span class="o">].</span><span class="n">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">plf</span><span class="o">|</span>
+      <span class="k">return</span> <span class="n">plf</span> <span class="k">if</span> <span class="no">Config</span><span class="o">::</span><span class="no">CONFIG</span><span class="o">[</span><span class="s1">&#39;target_os&#39;</span><span class="o">]</span> <span class="o">=~</span> <span class="sr">/</span><span class="si">#{</span><span class="n">plf</span><span class="si">}</span><span class="sr">/i</span>
+    <span class="k">end</span><span class="p">;</span> <span class="ss">:other</span>
+  <span class="k">end</span>
+  <span class="k">def</span> <span class="nf">gem_load?</span><span class="p">(</span><span class="n">gemname</span><span class="p">,</span> <span class="n">function</span><span class="o">=</span><span class="s1">&#39;full&#39;</span><span class="p">)</span>
+    <span class="vi">@installed</span> <span class="o">||=</span> <span class="k">begin</span>
+      <span class="nb">require</span> <span class="n">gemname</span>
+      <span class="kp">true</span>
+    <span class="k">rescue</span> <span class="no">LoadError</span>
+      <span class="s2">&quot;Please gem install </span><span class="si">#{</span><span class="n">gemname</span><span class="si">}</span><span class="s2"> for </span><span class="si">#{</span><span class="n">function</span><span class="si">}</span><span class="s2"> support.&quot;</span>
+      <span class="o">::</span><span class="no">Sidekick</span><span class="o">.</span><span class="n">stop</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+  <span class="k">def</span> <span class="nf">platform_load?</span><span class="p">(</span><span class="n">gems</span><span class="p">,</span> <span class="n">function</span><span class="o">=</span><span class="s1">&#39;full&#39;</span><span class="p">)</span>
+    <span class="n">gem_load?</span><span class="p">(</span><span class="n">gems</span><span class="o">[</span><span class="n">platform</span><span class="o">]</span><span class="p">,</span> <span class="n">function</span><span class="p">)</span>
+  <span class="k">end</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    </table>
+</div>
+</body>

data/lib/sidekick.rb CHANGED

@@ -1,8 +1,27 @@
+# *Sidekick* is a simple event driven background assistant. Among other things, you can use it to automatically compile assets, test code, restart servers and so on - as prescribed per project, in a `.sidekick` file. It is powered by [EventMachine](http://github.com/eventmachine/eventmachine) and [Tilt](http://github.com/rtomayko/tilt).
+#
+# This is the annotated source code. See the [README](http://github.com/jbe/sidekick#readme) too.
+#
+# ***
+#
+# Sidekick basically helps you do two things:
+#
+# -- *Define* named triggers, such as saying that `watch(glob)` means doing something when a file matching `glob` changes, or that `every(duration)` means doing something every `duration` seconds.
+#
+# -- *Use* the defined triggers with callbacks, such as `watch(**.rb) { notify 'Code change' }`
 require 'fileutils'
 require 'eventmachine'
 module Sidekick
+  # This core functionality is provided by `Sidekick::Triggers`.
+  #
+  # New triggers can be defined by calling `Sidekick::Triggers.register(:trigger_name) { ... }`.
+  #
+  #Basically, the job of a trigger definition is to take the parameters and the block from a directive in the `.sidekick` file, and then hook into EventMachine in some way to set up the trigger. -- Just have a look at the [default trigger library](http://jbe.github.com/sidekick/triggers.html).
+  #
+  # By using Ruby's `method_missing`, we can forward method calls to the registered trigger definitions. Any module can thereby extend the `Sidekick::Triggers` module in order to expose the defined triggers as if they were methods.
   module Triggers
     @@triggers = {}
@@ -25,32 +44,30 @@ module Sidekick
   end
-  # default library
+  # This part includes the default trigger definitions and helper methods. `Sidekick::Helpers` automagically loads the code in `sidekick/helpers` and then includes its sub-modules.
+  module Sidekick::Helpers
+    Dir[File.dirname(__FILE__) + '/sidekick/helpers/**.rb'
+      ].each {|path| load path }
+    constants.each do |name|
+      include const_get(name) if const_get(name).is_a?(Module)
+    end
+  end
   require 'sidekick/triggers'
-  require 'sidekick/helpers'
-  # context in which to evaluate .sidekick file
+  # The `.sidekick` file is evaluated in the `Sidekick::Context` module, which exposes DSL style methods by extending `Sidekick::Triggers` and `Sidekick::Helpers`.
   Context = Module.new
   Context.extend Triggers
   Context.extend Helpers
-  def self.ensure_config_exists(path)
-    unless File.exists?(path)
-      puts 'Generate new sidekick file? (Y/n)'
-      gets =~ /^N|n/ ? exit :
-        FileUtils.cp(File.expand_path('../template',
-          __FILE__), path)
-    end
-  end
-  # reads and applies the .sidekick file, and begins
-  # the event loop.
+  # `Sidekick.run!` reads and applies the `.sidekick` file, wrapping the setup phase inside `EM.run { .. }`, thus starting the event loop.
   def self.run!(path='.sidekick')
     ensure_config_exists(path)
-    Signal.trap(:INT) { ::Sidekick.stop }
+    Signal.trap(:INT) { stop }
     EventMachine.run do
       Context.module_eval(
@@ -58,11 +75,18 @@ module Sidekick
     end
   end
-  # stops Sidekick gracefully
-  def self.stop(msg=false)
+  def self.ensure_config_exists(path)
+    unless File.exists?(path)
+      puts 'Generate new sidekick file? (Y/n)'
+      gets =~ /^N|n/ ? exit :
+        FileUtils.cp(File.expand_path('../template',
+          __FILE__), path)
+    end
+  end
+  def self.stop(msg=nil)
     EventMachine.stop
-    puts
-    puts msg if msg
+    puts "\n#{msg}" if msg
   end
 end

data/lib/sidekick/helpers/compile.rb ADDED

@@ -0,0 +1,34 @@
+module Sidekick::Helpers::Compile
+  # Compiles one template using the `tilt` gem.
+  def compile(source, target)
+    needs 'tilt', 'to compile templates'
+    begin
+      File.open(target, 'w') do |f|
+        f.write(Tilt.new(source).render)
+      end
+    rescue Exception => e
+      notify "Error compiling #{file}:\n#{e}"
+    end
+  end
+  # watches for changes matching the `source` glob, and compiles to `target`, replacing ':name' in `target` with the basename of the changed file.
+  def auto_compile(source, target)
+    watch(source) do |files|
+      files.each do |file|
+        if File.exists?(file)
+            t = target.gsub(':name', File.basename(file, '.*'))
+            compile file, t
+            log "render #{file} => #{t}"
+        end
+      end
+    end
+  end
+end

data/lib/sidekick/helpers/passenger.rb ADDED

@@ -0,0 +1,14 @@
+module Sidekick::Helpers::Passenger
+  def restart_passenger
+    FileUtils.touch './tmp/restart.txt'
+    log 'restarted passenger'
+  end
+end