Conrad Irwin2023-10-07T04:27:40+00:00http://cirw.in/blog/Conrad Irwinconrad.irwin@gmail.comWhat does = do in rust?2023-10-03T00:00:00+00:00http://cirw.in//blog/rust-assignment.html<p>I have been learning rust for the last few months and, like many others, have found it hard to develop an intuition for when the borrow checker will disallow what I’m trying to do.</p>
<p>I had an insight recently that may be helpful to others who are switching to rust from other languages, and I wanted to share it.</p>
<p>In prior languages (for me, a hodgepodge of Go, Javascript and variants, Ruby, Python, and a bit of C), the = operator has usually had relatively straightforward semantics: <code class="language-plaintext highlighter-rouge">a = b</code> gives you a new copy of the value <code class="language-plaintext highlighter-rouge">b</code> and stores it in <code class="language-plaintext highlighter-rouge">a</code>. (With some hand-waving for whether <code class="language-plaintext highlighter-rouge">b</code> is a pointer under the hood or not).</p>
<p>In rust, this is <em>not</em> the case, and figuring out the difference made it easier for me to predict the outcome of borrow checking.</p>
<h3 id="three-assignments-for-beginners">Three assignments for beginners</h3>
<p>In rust <code class="language-plaintext highlighter-rouge">=</code> does three similar (but different) things depending on the type of the expression on the right:</p>
<ol>
<li><code class="language-plaintext highlighter-rouge">a = b</code> “move”s <code class="language-plaintext highlighter-rouge">b</code> into <code class="language-plaintext highlighter-rouge">a</code> (it removes it from <code class="language-plaintext highlighter-rouge">b</code>, so you cannot use <code class="language-plaintext highlighter-rouge">b</code> again!) by default.</li>
<li>If <code class="language-plaintext highlighter-rouge">b</code> implements the <code class="language-plaintext highlighter-rouge">Copy</code> trait, then <code class="language-plaintext highlighter-rouge">a = b</code> makes a “copy” of <code class="language-plaintext highlighter-rouge">b</code> in <code class="language-plaintext highlighter-rouge">a</code>. (this is the case for most primitive types like numbers, as well as small usually-immutable custom types).</li>
<li>If <code class="language-plaintext highlighter-rouge">b</code> is a reference, <code class="language-plaintext highlighter-rouge">a = b</code> does a “reborrow” of <code class="language-plaintext highlighter-rouge">b</code> into <code class="language-plaintext highlighter-rouge">a</code> if <code class="language-plaintext highlighter-rouge">b</code> instead.</li>
</ol>
<p>I should clarify that this is not limited to the <code class="language-plaintext highlighter-rouge">=</code> operator: passing a value to a function, or returning a value from a function acts the same way. It helps me to think of those as just syntactically hidden assignments under the hood.</p>
<p>(I also want to be clear that <code class="language-plaintext highlighter-rouge">b</code> can be any expression, not just a variable. It’s the type of the expression that matters).</p>
<h3 id="raii-ge-against-the-machine">RAII-ge against the machine</h3>
<p>Rust takes an opinionated approach to garbage collection (as you probably know), inspired by the <a href="https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization">RAII</a> principles developed for C++:</p>
<ul>
<li>Each value lives from the point it is created to the point it goes out of scope, at which point it is dropped.</li>
<li>The compiler would like to (as far as possible) be able to statically determine when it is dropped.
This is why the “move” semantics for <code class="language-plaintext highlighter-rouge">=</code> exist. If you allowed people to make a copy of a value that owns something else, then you’d end up with 2 owners, and it would be even more difficult to statically determine when the value should be dropped. (Besides you get some wins about “fearless concurrency” or something).</li>
</ul>
<p>The <code class="language-plaintext highlighter-rouge">Copy</code> trait is a way of opting out of this insanity. In exchange for promising the compiler that there’s nothing funny going on (your value doesn’t need any special care when being dropped, and it can be cheaply copied) you get to use <code class="language-plaintext highlighter-rouge">=</code> like a normal person.</p>
<h3 id="reborrowing">Reborrowing…</h3>
<p>In my first few weeks of rust, my intuition with borrow checker errors was to try and add more explicit lifetimes. This was a bad intuition: at least in the code I work with, very few explicit lifetimes are needed.</p>
<p>The confusion arises because the <code class="language-plaintext highlighter-rouge">=</code> operator handles references specially:</p>
<ul>
<li>When you reborrow an immutable reference <code class="language-plaintext highlighter-rouge">a = b</code> you get another reference to referent of <code class="language-plaintext highlighter-rouge">b</code>. You are only allowed to do this if <code class="language-plaintext highlighter-rouge">a</code> is dropped before the referent of <code class="language-plaintext highlighter-rouge">b</code>.</li>
<li>When you reborrow a mutable reference <code class="language-plaintext highlighter-rouge">a = b</code>, you take control of the referent <code class="language-plaintext highlighter-rouge">b</code> . You are only allowed to do this if <code class="language-plaintext highlighter-rouge">a</code> is dropped before the referent of <code class="language-plaintext highlighter-rouge">b</code>; <em>and</em> you cannot use <code class="language-plaintext highlighter-rouge">b</code> again until <code class="language-plaintext highlighter-rouge">a</code> is dropped.</li>
</ul>
<p>There is a little <a href="https://doc.rust-lang.org/book/ch04-02-references-and-borrowing.html">more nuance</a> to it than this, but one of the things that catches me out is that rusts notion of “before” in these statements is fuzzy. Sometimes moving borrows to a different statement fixes the code even though the order of execution doesn’t change. If <code class="language-plaintext highlighter-rouge">b</code> is a mutable reference then <code class="language-plaintext highlighter-rouge">a(b, c(b))</code> is sometimes disallowed even though <code class="language-plaintext highlighter-rouge">let tmp = c(b); a(b, tmp)</code> is allowed.</p>
<h3 id="pointing-and-laughing">Pointing and laughing</h3>
<p>Another thing I struggled with is to figure out how rusts “smart” pointers interact with all of this. What is an <code class="language-plaintext highlighter-rouge">Rc</code>, or an <code class="language-plaintext highlighter-rouge">Arc</code>, or a <code class="language-plaintext highlighter-rouge">Box</code> anyway, and how on earth do they work?</p>
<p>The answer is that they use <code class="language-plaintext highlighter-rouge">unsafe</code> under the hood, so they are built using primitives to which these rules do not apply. They can do whatever they want. (In particular, they are allowed to make copies of values that point to values).</p>
<p>Although I initially saw these types as maybe a bit of a code-smell, it turns out that there are many valid programs where the lifetime of a value is not statically determinable; and that is why these types exist. Use them!</p>
<p>But… beware the <code class="language-plaintext highlighter-rouge">=</code> operator.</p>
<p>If you have <code class="language-plaintext highlighter-rouge">a = b</code> and <code class="language-plaintext highlighter-rouge">b</code> is a smart pointer, the <code class="language-plaintext highlighter-rouge">=</code> is doing a move – that means you won’t be able to use <code class="language-plaintext highlighter-rouge">b</code> afterwards. This seems to defeat the point of having a reference count…</p>
<p>Because this is a common problem with all similar types, there is another trait <code class="language-plaintext highlighter-rouge">Clone</code> that smart pointers (among others) implement to get “clever” copy semantics. Instead write <code class="language-plaintext highlighter-rouge">a = b.clone()</code>.</p>
<p>Clone is a bit of a misnomer, because it is not actually “just” copying under the hood. For example an <code class="language-plaintext highlighter-rouge">Rc</code> is a reference counted pointer so <code class="language-plaintext highlighter-rouge">Rc::clone</code> increments the reference count, and returns you a new pointer to the <code class="language-plaintext highlighter-rouge">Rc</code>. When the returned pointer is dropped (which it will be, thanks RAII!) it will decrement the reference count.</p>
<h3 id="in-summary">In summary</h3>
<p>Rust is a complicated language built on top of some (comparatively) simple ideas. When you can see through the syntax to what’s going on under the hood, you’ll have a much better time.</p>
<p>At least for me (so far) the “aha” moment was that <code class="language-plaintext highlighter-rouge">=</code> is another example of this! In order to make your code look a little more sensible rust overloads one humble operator with three different operations, the downside is that you have to pay attention to discover which one you’re getting.</p>
<p>Until next time, when we’ll have to mention that <code class="language-plaintext highlighter-rouge">=</code> can be used for pattern matching too (and it can be affected by <code class="language-plaintext highlighter-rouge">Deref</code> coercions… (and anything else I missed…!)).</p>
Smooth animated HTML-5 icons2015-09-27T00:00:00+00:00http://cirw.in//blog/smooth-animations.html<p>Recently we added our first animated icon to Superhuman as part of the transition to the search interface:</p>
<p><a style="display: block; text-align: center" href="../images/search.mp4">
<video style="display: inline; width: 100%" autoplay="true" loop="true">
<source src="../images/search.mp4" />
</video>
</a></p>
<aside>NOTE: The animations in this video are running at 1/10th of normal speed.</aside>
<p>There’s clearly more work to be done here, but you get the idea: the icon animates to enforce the perceptual link between the user’s click and its effect, while the text flicks right to draw the user’s attention to the now visible textbox.</p>
<p>#Using <canvas></p>
<p>While the text transition can be achieved easily using translate, opacity and transition in CSS, making the icon morph from a magnifying glass to a cross requires significantly more work.</p>
<p>We did this by writing a simple program that can draw the animation into an HTML canvas. The advantage of this approach is that we can re-use d3’s easing and scaling functions, and run the animation at any size or speed.</p>
<aside>I've uploaded [the code](https://gist.github.com/ConradIrwin/e6b3d65beab92f1ce19d) behind this icon in case you're curious.</aside>
<p>The disadvantage of using canvas is that we need javascript to compute a new frame every 16ms. In an ideal world, this would not be a problem as we can use <code class="language-plaintext highlighter-rouge">requestAnimationFrame</code> and rendering each frame takes significantly less than 16ms of CPU-time.</p>
<p>Unfortunately in our more realistic world, the browser is busy trying to render the search UI, or (even more challengingly) the user’s Important inbox during the transition. As javascript is single-threaded, this means animation frames may be delayed by significant periods of time while the browser runs unrelated javascript code, or renders chunks of HTML. This causes lag and kills the delightful user experience.</p>
<h1 id="accelerating-canvas">Accelerating canvas</h1>
<p>There are a couple of ways to avoid the single-threaded nature of javascript. In this case the most pertinent is to offload the animation to the graphics card. Unfortunately graphics cards are not good at executing arbitrary javascript, and so we need to re-frame the problem in a manner that the GPU can handle well.</p>
<p>The idea is relatively simple, and borrowed from how pre-digital motion pictures work. We just paint a strip of ‘film’ and pass it in front of an opening really fast (at 60 frames per second). This can be done using a stepped CSS animation:</p>
<div>
<style style="display: block; white-space: pre; font-family: monospace;">
.window {
width: 32px;
overflow: hidden;
}
.slide {
width: 352px;
height: 32px;
background-image: url(../images/10frames.svg);
transform: translateX(0px);
transition: transform 166ms steps(10);
}
.window:hover .slide {
transform: translateX(-320px);
}
</style>
<style>
.window {
overflow: visible !important;
position: relative;
height: 34px;
margin: auto;
}
.window::after {
display: block;
outline: 3px solid aqua;
content: " ";
height: 32px;
width: 32px;
position: absolute;
top: 0;
left: 0;
}
.slide {
transition: transform 1328ms steps(10) !important;
}
</style>
</div>
<p>Here’s the actual ten frames of the icon we’re using right now. Hover over it
to see how it works in slow-motion:</p>
<div class="window">
<div class="slide"></div>
</div>
<h1 id="canvas-animation-loader">canvas-animation-loader</h1>
<p>We use Webpack to build the Superhuman front-end, and so we’ve created <a href="https://github.com/ConradIrwin/canvas-animation-loader">canvas-animation-loader</a> to compile these canvas icons to SVGs using the excellent <a href="https://github.com/gliffy/canvas2svg">canvas2svg</a> library.</p>
<p>This gives us the best of both worlds: We can develop animated icons interactively using canvas and test them at various speeds and scales; and when we’re happy with the result webpack automatically builds the GPU-ready SVG versions that are used in production.</p>
<p>I’d love your feedback and comments, please get in touch <a href="mailto:conrad@superhuman.com">conrad@superhuman.com</a>. I’m particularly looking for a lead designer who can make Superhuman the most delightful email experience in the world.</p>
Hacking smart-quote support into a font2015-08-23T00:00:00+00:00http://cirw.in//blog/smart-quotes.html<figure class="image">
<style>
figure.image img {
border: 1px solid rgba(200,200,30,0.3) !important;
}
</style>
<a href="../images/fanwood.png">
<img src="../images/fanwood.png" />
</a>
</figure>
<p>I’ve recently been doing some work on making <a href="http://superhuman.com">Superhuman</a> the most beautiful email client in the world. (N.B. We’re looking to hire a lead designer, please <a href="mailto:conrad@superhuman.com">email me</a>).</p>
<p>One of the features we wanted was automatic “smart quotes”. Instead of the bland vertical quotes you often see on a computer “•”, we’d replace them at render time by fun curvy quotes “•” to make the text more alive.</p>
<p>I’d known for a while that <a href="https://en.wikipedia.org/wiki/OpenType">OpenType</a> was capable of some processing during font rendering, and so I set myself the challenge of implementing smart quotes in the font file itself. To cut a long-story short: <a href="/etc/fanwood">it works</a>, and it’s easy to modify an existing font to support it.</p>
<h1 id="font-feature-settings">font-feature-settings</h1>
<p>The first trick to getting fancy font features working on the web is to set up your <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings"><code class="language-plaintext highlighter-rouge">font-feature-settings</code></a> CSS property (actually <code class="language-plaintext highlighter-rouge">-webkit-font-feature-settings</code> or <code class="language-plaintext highlighter-rouge">-moz-font-feature-settings</code>). This also works in IE 10+, but surprisingly, is not available in Safari.</p>
<figure class="highlight"><pre><code class="language-css" data-lang="css"><span class="nt">body</span> <span class="p">{</span>
<span class="nl">font-feature-settings</span><span class="p">:</span> <span class="s1">"kern"</span> <span class="m">1</span><span class="p">,</span> <span class="s1">"dlig"</span> <span class="m">1</span><span class="p">;</span>
<span class="nl">-webkit-font-feature-settings</span><span class="p">:</span> <span class="s1">"kern"</span> <span class="m">1</span><span class="p">,</span> <span class="s1">"dlig"</span> <span class="m">1</span><span class="p">;</span>
<span class="nl">-moz-font-feature-settings</span><span class="p">:</span> <span class="s1">"kern"</span> <span class="m">1</span><span class="p">,</span> <span class="s1">"dlig"</span> <span class="m">1</span><span class="p">;</span>
<span class="p">}</span></code></pre></figure>
<p>The value of this property is a list of quoted four-letter <a href="https://en.wikipedia.org/wiki/List_of_typographic_features">OpenType features</a> followed by a number for its value.</p>
<p>The most essential feature to enable is <code class="language-plaintext highlighter-rouge">"kern"</code>, which enables proper kerning. It’s also nice to enable <code class="language-plaintext highlighter-rouge">"liga"</code> and <code class="language-plaintext highlighter-rouge">"dlig"</code> which control the use of ligatures. Hover over the following image and notice how the ugly space between the <code class="language-plaintext highlighter-rouge">nw</code> of <a href="https://www.theleagueofmoveabletype.com/fanwood">Fanwood</a> is tightened, and how the messy <code class="language-plaintext highlighter-rouge">fl</code> is replaced by a ligature.</p>
<figure class="image">
<style>
figure.image div#kern {
border: 1px solid rgba(200,200,30,0.3) !important;
background-image: url("../images/fanwood.png");
width: 475px;
height: 237px;
margin: auto;
background-position: 0 0;
background-size: 200%;
}
figure.image div#kern:hover {
background-position: 0 269px;
}
</style>
<a href="../images/fanwood.png">
<div id="kern"></div>
</a>
</figure>
<h1 id="smart-quotes">Smart quotes</h1>
<p>Under the hood each OpenType feature is a set of pattern matches: when a certain sequence of glyphs occurs you can <b>sub</b>stitute a new glyph into place, or change its <b>pos</b>ition. The <a href="http://opentypecookbook.com/index.html">OpenType Cookbook</a> is a good reference for the syntax used, which is supported by most font editing tools and processed by the <a href="https://github.com/adobe-type-tools/afdko">ADFKO</a>.</p>
<p>The patterns are very simple, but you can use a few techniques to implement surprisingly complicated substitutions.</p>
<ol>
<li>You can specify an <code class="language-plaintext highlighter-rouge">ignore</code> rule to skip a rule.</li>
<li>You can define character classes to group characters together.</li>
<li>(I haven’t needed this yet) You can group rules into lookups, where only one rule from each lookup is used.</li>
</ol>
<aside>Exercise for the reader: I think this makes an OpenType font a finite-state machine, anyone fancy implementing arbitrary regexes?</aside>
<p>Starting small, we can implement a simple rule to replace exactly two hyphens (–) by an em-dash (—):</p>
<figure class="highlight"><pre><code class="language-text" data-lang="text"># ignore two hyphens followed by a third hyphen
ignore sub hyphen' hyphen' hyphen;
# and ignore two hyphens preceded by a hyphen
ignore sub hyphen hyphen' hyphen';
# replace all remaining hyphens by em-dashes
sub hyphen' hyphen' by emdash;</code></pre></figure>
<p>To implement smart-quotes we need to be able to tell if a quote is at the start of a line. We can approximate this by defining the character class <code class="language-plaintext highlighter-rouge">@All</code> which contains all the glyphs in the font, and then using <code class="language-plaintext highlighter-rouge">@All</code> to catch any quotes that happen after a character. Quotes that don’t happen after any character are at the start of a line.</p>
<figure class="highlight"><pre><code class="language-text" data-lang="text"># smart-quotes.
# quotes surrounded by spaces, just leave alone.
ignore sub space quotedbl' space;
# quotes after numers, assume are primes, and leave alone.
ignore sub [
one two three four five six seven eight nine zero
] quotedbl';
# quotes after opening characters are open-quotes.
sub [space
equal
less
parenleft parenleft.u
bracketleft bracketleft.u
braceleft braceleft.u
guillemotleft guillemotleft.u
guilsinglleft guilsinglleft.u
quotedblleft quoteleft quotesingle quotedbl
] quotedbl' @All by quotedblleft;
# other quotes in the middle of the line are closing quotes.
sub @All quotedbl' by quotedblright;
# quotes at the start of the line are opening.
sub quotedbl' @All by quotedblleft;</code></pre></figure>
<p>Because there was no pre-defined OpenType feature name for smart
quotes, I’ve added it to the font as <code class="language-plaintext highlighter-rouge">"ss01"</code> or Stylistic Set 1.
You can see the effects of <a href="https://gist.github.com/ConradIrwin/d78c9895c0989d143a4d#file-smartquotes-fea">the full
code</a>
by hovering below:</p>
<figure class="image">
<style>
figure.image div#ss01 {
border: 1px solid rgba(200,200,30,0.3) !important;
background-image: url("../images/fanwood.png");
width: 475px;
height: 237px;
margin: auto;
background-position: 0 269px;
background-size: 200%;
}
figure.image div#ss01:hover {
background-position: -452px 0px;
}
</style>
<a href="../images/fanwood.png">
<div id="ss01"></div>
</a>
</figure>
<h1 id="hanging-punctuation">Hanging punctuation</h1>
<p>Inspired by <a href="https://blot.im/typeset/">Typeset</a>, I wanted to see if I could also implement <a href="https://en.wikipedia.org/wiki/Hanging_punctuation">hanging punctuation</a>. This gives the left-margin a strong vertical line by having punctuation marks extend beyond it. Once I had the substitution rules and the character classes set up for the smart quotes, this turned out to be simple:</p>
<figure class="highlight"><pre><code class="language-text" data-lang="text"># feature "opbd"
ignore pos @All quotedblleft';
pos quotedblleft' <-421 0 -421 0>;
ignore pos @All quoteleft';
pos quoteleft' <-228 0 -228 0>;</code></pre></figure>
<p>The positioning rules move the left and right of the glyph independently. The number <code class="language-plaintext highlighter-rouge">421</code> comes from looking at the glyph for a curvy left quote and taking its width including some spacing. I only needed to look at the curly left-quote, because the <code class="language-plaintext highlighter-rouge">"opbd"</code> feature is defined after <code class="language-plaintext highlighter-rouge">"ss01"</code> and so all the plain quotes have already been replaced at this point.</p>
<p>This technique only works for punctuation on the left, but as most text on-screen is set with a ragged right margin, you don’t normally need punctuation that hangs out to the right.</p>
<p>More work could be done, Typeset moves “Y”s, “V”s and “W”s out a little too, but this served as a proof of concept.</p>
<figure class="image">
<style>
figure.image div#opbd {
border: 1px solid rgba(200,200,30,0.3) !important;
background-image: url("../images/fanwood.png");
width: 475px;
height: 237px;
margin: auto;
background-position: -452px 0px;
background-size: 200%;
}
figure.image div#opbd:hover {
background-position: -452px 269px;
}
</style>
<a href="../images/fanwood.png">
<div id="opbd"></div>
</a>
</figure>
<h1 id="conclusion">Conclusion</h1>
<p>Implementing smart-quotes in your font is totally feasible. It’s not as good as using the correct glyphs in the first place, but it’s on-par with doing it in Javascript and a lot more convenient (there’s no code to run).</p>
<p>You can download my hacked version of <a href="https://github.com/ConradIrwin/fanwood">Fanwood Text</a> from GitHub, or <a href="/etc/fanwood">preview it</a>. I used <a href="https://glyphsapp.com">Glyphs</a> to open the existing Fanwood font and add a new feature. If you use a different app, I’m sure you can re-use the syntax, but the UI might be more or less confusing.</p>
<p>If you’re still reading and would like to chat about fonts, or work on a beautiful email client, please <a href="mailto:conrad@superhuman.com">email me</a>.</p>
How to serve a static site from Heroku2014-06-22T00:00:00+00:00http://cirw.in//blog/heroku-static-site.html<p>Heroku provides an awesome hosting service for all your apps. But it turns out
that you can use it to serve static pages too.</p>
<p>There are a variety of tricks I’ve seen, but most of them seem to involve
complicated hackery, this solution uses ruby’s builtin web-server: it’s not going
to be the most scalable site in the world, but it’s more than enough considering
that it’s totally free :).</p>
<h2 id="solution">Solution</h2>
<p>Heroku is controlled by a <a href="http://ddollar.github.io/foreman/#PROCFILE">Procfile</a>, which tells it what to run when your app is
deployed. To serve a static site, this is what it should look like:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># ./Procfile</span>
<span class="c"># Use ruby's builtin library tp run an HTTP server</span>
<span class="c"># that listens on $PORT and serves the current directory.</span>
web: ruby <span class="nt">-run</span> <span class="nt">-e</span> httpd <span class="nt">-p</span> <span class="nv">$PORT</span> <span class="nb">.</span>
</code></pre></div></div>
<p>And that’s it. Just include that Procfile in your git repository then run:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>heroku create <name-of-site>
git push heroku master
</code></pre></div></div>
<p>And your site will be live, you can visit it by running:</p>
<div class="language-bash highlighter-rouge"><div class="highlight"><pre class="highlight"><code>heroku open
</code></pre></div></div>
IPv6 comes to San Francisco2014-04-15T00:00:00+00:00http://cirw.in//blog/ipv6.html<p>If you live in San Francisco there’s a good chance that you can use IPv6 on
your home router. Comcast, AT&T, and Sonic.net all support it. (<a href="https://twitter.com/ConradIrwin">let me
know</a> if there’s one I missed).</p>
<p>It took me a while to get everything set up, so here is a collection of
everything you need to know to move from IPv4 only to IPv4 + IPv6.</p>
<p>It goes without saying that you’ll need an IPv6 compatible modem. Almost
all modern equipment should work, and Comcast maintains an <a href="http://mydeviceinfo.comcast.net/">official
list</a> of what they support. If you need to
upgrade, I have a <a title="Motorola Surfboard 6141 — affiliate link" href="http://www.amazon.com/gp/product/B00AJHDZSI/ref=as_li_tf_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=B00AJHDZSI&linkCode=as2&tag=cirwin-20">Motorola
Surfboard 6141</a> and a <a title="Netgear R6300v2 — affiliate link" href="http://www.amazon.com/gp/product/B00EM5UFP4/ref=as_li_qf_sp_asin_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=B00EM5UFP4&linkCode=as2&tag=cirwin-20">Netgear
R6300v2</a> that work together flawlessly.</p>
<h2 id="configuring-ipv6">Configuring IPv6</h2>
<p>The configuration instructions got a bit long, so I’ve put the details of
how to configure IPv6 for <a href="ipv6-config#comcast">Comcast</a> and
<a href="ipv6-config#sonic-net">Sonic.net</a> on a separate page.</p>
<h2 id="troubleshooting-tips">Troubleshooting tips</h2>
<p>IPv6 is a little confusing if you’re used to debugging IPv4 networks. There’s
no <a href="https://en.wikipedia.org/wiki/Network_address_translation" title="Network Address Translation">NAT</a>, and no <a href="https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol" title="Dynamic Host Configuration Protocol">DHCP</a>, instead devices
automatically assign themselves <a href="#multiple-addresses">multiple addresses</a>.</p>
<p>If you open <a href="http://test-ipv6.com/">test-ipv6.com</a>, it will hopefully show you
that you are connected to IPv6 and that everything works. If not, there are two
scenarios to consider:</p>
<ol>
<li>
<p>Everything’s working, but only on IPv4. In this case your laptop is not
trying to use IPv6. Double check that the router has an IPv6 address, and
that your laptop is configured to use it automatically. You should turn
your laptop’s Wifi off and on again after everything has been configured.</p>
<figure class="image">
<a href="../images/ipv6-laptop.png">
<img src="../images/ipv6-laptop.png" />
</a>
</figure>
</li>
<li>
<p>Things are broken. This means that your laptop is using IPv6, but your
connection isn’t. This usually implies that the router is using IPv6
correctly on the <a href="https://en.wikipedia.org/wiki/Local_area_network" title="Local area network — Your personal wifi">LAN</a>, but the <a href="https://en.wikipedia.org/wiki/Wide_area_network" title="Wide area network — Your connection to Comcast">WAN</a> IPv6 is mis-configured.
Hopefully your router will have a readable status page where you can see
what it thinks is going on, or <a href="https://twitter.com/ConradIrwin">ask for
help</a>.</p>
</li>
</ol>
<h2 id="what-are-all-these-addresses"><span id="multiple-addresses">What are all these addresses?</span></h2>
<p>The most confusing thing I found about IPv6 is that every device gets many IPv6
addresses.</p>
<p>At a minimum every adaptor automatically gets a <a href="http://en.wikipedia.org/wiki/Link-local_address#IPv6">link-local
address</a> that is based on its
<a href="http://en.wikipedia.org/wiki/MAC_address">MAC address</a>. These can’t be used for
anything (you can’t even <code class="language-plaintext highlighter-rouge">ping6</code> them) but they appear in routing tables (<code class="language-plaintext highlighter-rouge">netstat -nr</code>).</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code># On my network, there are three of these.
fe80::2acf:e9ff:fe1a:d1e5 # laptop wifi
fe80::2acf:e9ff:fe1a:d1e6 # laptop wired
fe80::c604:15ff:fe3e:407c # router LAN
</code></pre></div></div>
<p>Adaptors connected to the internet also
<a href="http://en.wikipedia.org/wiki/IPv6_address#Stateless_address_autoconfiguration">obtain</a>
one or two globally unique IPv6 addresses. These all share the address prefix that Comcast
has assigned to my network (<code class="language-plaintext highlighter-rouge">2601:9:8480:11d2::/64</code>), and they can actually be used (you
can <code class="language-plaintext highlighter-rouge">ping6</code> them).</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>2601:9:8480:11d2:2acf:e9ff:fe1a:d1e5 # laptop, MAC-address autoconfig
2601:9:8480:11d2:195d:8dd3:6e4a:d7a # laptop, random autoconfig
2601:9:8480:11d2:486f:6805:63c7:fe4a # router LAN, random autoconfig
2001:558:6045:109:58cc:71bf:9106:df9a # router WAN, comcast-provided
</code></pre></div></div>
<p>Because there’s no NAT in IPv6, when I visit
<a href="http://whatismyv6.com">whatismyv6.com</a> I actually see
<code class="language-plaintext highlighter-rouge">2601:9:8480:11d2:195d:8dd3:6e4a:d7a</code> which is the random autoconfig address of
my laptop. If you’re used to IPv4 + NAT, you might expect to see the WAN address
of the router, but that is not the case anymore.</p>
<h2 id="ipv6-tools">IPv6 tools</h2>
<p>In addition to <a href="http://ipv6-test.com">ipv6-test.com</a> and
<a href="http://whatismyv6.com">whatismyv6.com</a>, there are an array of local tools you can use:</p>
<ul>
<li>
<p><code class="language-plaintext highlighter-rouge">ping6</code> It’s just like ping, but for IPv6.</p>
</li>
<li>
<p><code class="language-plaintext highlighter-rouge">curl</code> works as expected (http requires square brackets around IPv6
addresses) but you need to pass -g and use single quotes to avoid shell shenanigans</p>
<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>curl -L -g 'http://[2a03:2880:2110:df07:face:b00c:0000:0001]/'
</code></pre></div> </div>
</li>
<li>
<p><code class="language-plaintext highlighter-rouge">ifconfig</code>. Prints out all your IPv6 addresses, and IPv4 address too.</p>
</li>
<li>
<p><code class="language-plaintext highlighter-rouge">netstat -nr</code>. Prints out the routing table so you can see which packets are
being sent where.</p>
</li>
<li>
<p><code class="language-plaintext highlighter-rouge">ndp -a</code>. Finds all IPv6 addresses on your LAN (equivalent to <code class="language-plaintext highlighter-rouge">arp -a</code> in IPv4)</p>
</li>
</ul>
<h2 id="feedback-or-questions">Feedback, or questions?</h2>
<p>If you’ve got feedback on this post, or need a hand getting IPv6 working, <a href="https://twitter.com/ConradIrwin">let
me know</a>.</p>
IPv6 configuration instructions2014-04-14T00:00:00+00:00http://cirw.in//blog/ipv6-config.html<p>This is a companion article to <a href="ipv6">IPv6 comes to San Francisco</a> that explains
how to set up IPv6 with Sonic.net and Comcast.</p>
<h2 id="comcast"><span id="comcast">Comcast</span></h2>
<p>For Comcast, you can double-check that you have support by visiting
<a href="http://www.comcast6.net/">comcast6.net</a>. If you see “Your <abbr title="Cable Modem Termination System">CMTS</abbr> is ready for IPv6.”, you’re ready to
rock!</p>
<figure class="image">
<a href="../images/ipv6-ready.png">
<img src="../images/ipv6-ready.png" />
</a>
</figure>
<p>Then navigate to your router (probably 192.168.1.1 or 192.168.0.1) and
find the IPv6 settings.</p>
<p>There are two questions to be answered: How should the router obtain an
IPv6 address from Comcast? How should devices connected to the network
obtain IPv6 addresses?</p>
<p>The answers are “DHCP” and “Auto config” respectively, as can be seen here:</p>
<figure class="image">
<a href="../images/ipv6-comcast.png">
<img src="../images/ipv6-comcast.png" />
</a>
</figure>
<p>It takes a few minutes for the DHCP to work the first time. After the router
has an IPv6 address, you also need to reset the wireless connection on your
laptop. (on a Mac you may need to open network settings and click “Forget this
network”)</p>
<h2 id="sonicnet"><span id="sonic-net">Sonic.net</span></h2>
<p>Sonic.net is a little more manual to configure. They use IPv6 tunnelling (instead
of IPv6 end-to-end) but there’s no difference as far as your laptop is concerned.</p>
<p>There are two questions to be answered: What’s the IPv4 address of Sonic.net’s IPv6
tunnel? Which IPv6 network prefix have Sonic.net assigned to you?</p>
<p>You can find both of the answers in your Sonic.net account page under Labs /
IPv6. Then configure your router as a 6to4 Tunnel:</p>
<figure class="image">
<a href="../images/ipv6-sonic.png">
<img src="../images/ipv6-sonic.png" />
</a>
</figure>
<p>Once you’ve applied these changes to the router, you need to reset the wireless
connection on your laptop. (on a Mac you may need to open network settings and click
“Forget this network”)</p>
dotgpg — easy to use storage for your production secrets2014-01-27T00:00:00+00:00http://cirw.in//blog/dotgpg.html<p>Where are your database passwords? your cookie encryption keys? your SSL certificates?</p>
<p>The most common answers are “in git” and “in Dropbox”. Hopefully with a guilty
squirm and followed by an awkward “it’s on my todo list”…</p>
<p>Storing production secrets on cloud services in plain text is very tempting but it’s obviously insecure. We’ve seen hacks via <a href="http://open.bufferapp.com/buffer-has-been-hacked-here-is-whats-going-on/#update10">API keys in git</a>, we’ve seen <a href="https://blog.dropbox.com/2012/07/security-update-new-features/">Dropbox passwords leak</a>.</p>
<p>Luckily, help is at hand!</p>
<h2 id="announcing-dotgpg">Announcing dotgpg</h2>
<p><a href="https://github.com/ConradIrwin/dotgpg"><code class="language-plaintext highlighter-rouge">dotgpg</code></a> is an easy to use tool that
lets you read and write encrypted files in your favourite text editor. It
maintains an access list so that each file can be decrypted by everyone on your
team, but no one else.</p>
<p>As encrypted files are still “just files” you can store them in git or Dropbox
so that they’re easy to share. Obviously if you’re really paranoid a USB stick
in a locked drawer might be safer, until your co-workers gang up on you…</p>
<p>Under the hood <code class="language-plaintext highlighter-rouge">dotgpg</code> is using the battle-tested <a href="http://gnupg.org">GnuPG</a>
library. So unless someone gets access to your laptop and you chose a weak
passphrase it’s highly unlikely anyone malicious can decrypt them.</p>
<h2 id="what-can-i-store-in-dotgpg">What can I store in dotgpg?</h2>
<p>Dotgpg was designed for storing production secrets. Things like API keys or
database passwords that your app needs to run. At <a href="https://bugsnag.com">Bugsnag</a>
we use <a href="https://github.com/bkeepers/dotenv">dotenv</a> in production, and store the
master copy of our <code class="language-plaintext highlighter-rouge">.env</code> file inside <code class="language-plaintext highlighter-rouge">dotgpg</code>. We then check this <code class="language-plaintext highlighter-rouge">dotgpg</code>
directory into git, so we can go back and see old versions if someone makes a
mistake.</p>
<p>At Rapportive we used <code class="language-plaintext highlighter-rouge">dotgpg</code>’s ancestor to share passwords for things like
Pingdom for which we all logged into the same account. We put the encrypted
files in Dropbox so that changes propogated automatically to everyone.</p>
<p>At LinkedIn the second version of the system was used to encrypt the SSL
certificates that my team needed. We then stored the encrypted files on USB
sticks locked in a drawer, just to be sure.</p>
<p>I also use it for encrypting the secrets in my personal backups. At the moment
that includes ssh keys, gem signing certificates and emergency two-factor-auth
codes. (My passwords are now in a system with a browser extension, but I used
to use gpg for those as well).</p>
<h2 id="how-easy-is-it-really">How easy is it really?</h2>
<p>While GPG is amazing at encrypting stuff, the user-interface leaves a lot to be
desired. With <code class="language-plaintext highlighter-rouge">dotgpg</code> I’ve removed as many options and operations as possible,
and boiled it down to two every-day commands.</p>
<ol>
<li><code class="language-plaintext highlighter-rouge">dotgpg cat</code> decrypts a file and pipes it to standard out.</li>
<li><code class="language-plaintext highlighter-rouge">dotgpg edit</code> opens a file in your <code class="language-plaintext highlighter-rouge">$EDITOR</code> and re-encrypts it when you’re done.</li>
</ol>
<p>To get started is even simpler, just run <code class="language-plaintext highlighter-rouge">dotgpg init</code> to create a new
directory and then <code class="language-plaintext highlighter-rouge">dotgpg edit</code> to create files within it.</p>
<p>Adding collaborators is also pretty quick. They run <code class="language-plaintext highlighter-rouge">dotgpg key</code> on their
computer and then send the key to you (by Dropbox, email, whatever suits). You
then run <code class="language-plaintext highlighter-rouge">dotgpg add</code> on your computer to add them to the access list.</p>
<h2 id="how-secure-is-it">How secure is it?</h2>
<p>Secure enough for me. If you still have your Rails
<a href="http://edgeguides.rubyonrails.org/upgrading_ruby_on_rails.html#config-secrets-yml"><code class="language-plaintext highlighter-rouge">secret_key_base</code></a>
or SSL certificates in cloud services unencrypted, then it’s more than secure
enough for you too. The easiest way to get more secure than <code class="language-plaintext highlighter-rouge">dotgpg</code> is to
store everything on a USB stick offline, but this is too inconvenient for many
people.</p>
<p>That said, <code class="language-plaintext highlighter-rouge">dotgpg</code> is only designed to add an extra layer of protection if
someone gets into your git or Dropbox. If an attacker gets access to your
laptop you should probably assume that they will guess your password and
decrypt your files.</p>
<p>For more information see the <a href="https://github.com/ConradIrwin/dotgpg#security">security</a> section of the README. If you have concerns, please <a href="mailto:me@cirw.in">email me</a>.</p>
<h2 id="installation">Installation</h2>
<p>Full instructions, including use without ruby, are available on the <a href="https://github.com/ConradIrwin/dotgpg">README</a>. But if you want to dive straight in, just</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="o">(</span><span class="nb">sudo</span><span class="o">)</span> gem <span class="nb">install </span>dotgpg</code></pre></figure>
<p>Please file an <a href="https://github.com/ConradIrwin/dotgpg">issue</a> if you have difficulties, and feel free to <a href="https://twitter.com/ConradIrwin">get in touch</a> if you need a hand!</p>
Avoiding MongoDB hash-injection attacks2014-01-07T00:00:00+00:00http://cirw.in//blog/hash-injection.html<p><a href="http://mongodb.com">MongoDB</a> is a popular document store. Its query API neatly
sidesteps SQL-injection attacks by not being SQL. Unfortunately when using a
framework like Rails, it’s easy to build an app that’s vulnerable to a
hash-injection attack.</p>
<p>Hash-injection is much less severe than SQL-injection, because an attacker is
more limited in the kind of changes they can make, but it can lead to
authentication-bypass, denial of service, or timing attacks.</p>
<p>I reported this to MongoDB as SECURITY-90, and they recommend fixing this by
patching your application as described below. Alternatively you can install my
<a href="https://github.com/ConradIrwin/mongoid-rails">mongoid-rails</a> gem which
automatically fixes this for you.</p>
<h2 id="the-problem-with-rails">The Problem with Rails</h2>
<p>The underlying problem is that Rails query parameters are not strongly typed.
This was first noticed in early versions of Rails when people were writing
code that blindly passed parameters to the update function of a model.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="n">user</span><span class="p">.</span><span class="nf">update</span><span class="p">(</span><span class="n">params</span><span class="p">[</span><span class="ss">:user</span><span class="p">])</span></code></pre></figure>
<p>A devious attacker could add <code class="language-plaintext highlighter-rouge">?user[is_admin]=1</code> to the URL or the form, and
make themselves an admin. This problem eventually led to the adoption of
<a href="https://github.com/rails/strong_parameters">strong parameters</a> in rails 4
which protects you against this kind of attack.</p>
<aside>Rails is not the only framework with this problem. PHP has it, Node.js's
express web framework does the same, and I'm certain there are many others.</aside>
<h2 id="the-problem-with-mongodb">The Problem with MongoDB</h2>
<p>The rails problem is exacerbated by the MongoDB API. MongoDB lets you either
query by equality with a String or using a query operator nested in a Hash:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="no">User</span><span class="p">.</span><span class="nf">where</span><span class="p">(</span><span class="ss">email: </span><span class="n">params</span><span class="p">[</span><span class="ss">:email</span><span class="p">])</span>
<span class="no">User</span><span class="p">.</span><span class="nf">where</span><span class="p">(</span><span class="ss">email: </span><span class="p">{</span><span class="s2">"$regex"</span> <span class="o">=></span> <span class="n">params</span><span class="p">[</span><span class="ss">:search</span><span class="p">]})</span></code></pre></figure>
<p>Unfortunately, Rails doesn’t guarantee that <code class="language-plaintext highlighter-rouge">params[:email]</code> is a String.
This means that a devious attacker can again change the structure of the
URL to get an unexpected result.</p>
<p>They can turn a look-up by String into a look-up by regex by passing a
parameter like <code class="language-plaintext highlighter-rouge">?email[$regex]=.*@google.com</code>.</p>
<h2 id="the-consequences">The consequences</h2>
<p>This is much less severe than an SQL injection attack would be, but it still has several dangerous consequences.</p>
<ol>
<li><b>Authentication Bypass</b>. If you’re verifying API tokens using a query like <code class="language-plaintext highlighter-rouge">User.where(api_token: params[:api_token])</code>, an attacker could use this to access the API without having an API token by passing in a regex.</li>
<li><b>Denial of Service</b>. If you have a large table with an index on <code class="language-plaintext highlighter-rouge">_id</code> and you do a query like <code class="language-plaintext highlighter-rouge">BlogPost.find(params[:id])</code>, an attacker can craft a query that forces MongoDB to do a full table scan.</li>
<li><b>Data leakage</b>. An attacker who can force you to do a full table scan on your users table can use a regex search to find out which domains are signed up to your site by seeing how fast the query returns. This is an example of a <a href="https://en.wikipedia.org/wiki/Timing_attack">timing attack</a></li>
</ol>
<h2 id="the-solution">The solution</h2>
<p>If you’re using Rails 3 with strong parameters and Mongoid then the quick fix
is to use my <a href="https://github.com/ConradIrwin/mongoid-rails">mongoid-rails</a> gem.
This protects you from hash-injection attacks both when querying and when
updating.</p>
<p>For everyone else, I’m afraid the only way to fix this is to manually call
<code class="language-plaintext highlighter-rouge">.to_s</code> on the parameters. You should find most instances of the problem if you
grep for <code class="language-plaintext highlighter-rouge">where.*params</code>, <code class="language-plaintext highlighter-rouge">find.*params</code>, <code class="language-plaintext highlighter-rouge">creates.*params</code> and
<code class="language-plaintext highlighter-rouge">update.*params</code>.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># These examples are safe, because params[:event_id] and</span>
<span class="c1"># params[:auth_token] are coerced to strings.</span>
<span class="no">Event</span><span class="p">.</span><span class="nf">find</span><span class="p">(</span><span class="n">params</span><span class="p">[</span><span class="ss">:event_id</span><span class="p">].</span><span class="nf">to_s</span><span class="p">)</span>
<span class="no">Account</span><span class="p">.</span><span class="nf">where</span><span class="p">(</span><span class="ss">auth_token: </span><span class="n">params</span><span class="p">[</span><span class="ss">:auth_token</span><span class="p">].</span><span class="nf">to_s</span><span class="p">).</span><span class="nf">first</span></code></pre></figure>
Node's Unicode Dragon2013-09-09T00:00:00+00:00http://cirw.in//blog/node-unicode.html<p>At <a href="https://bugsnag.com/">Bugsnag</a> we accept JSON payloads of application
crashes. These often contain broken data. For example, if your app has crashed
with an invalid encoding error, the JSON will often contain the invalid string
that crashed your server.</p>
<p>This shouldn’t be a problem for us as we read the JSON payload with Node and
Node replaces all the invalid bytes with the unicode replacement character (�
U+FFFD). But something strange was happening:</p>
<p>Sometimes our Rails app would crash due to invalid UTF-8 <em>after</em> the Node app
had validated it!</p>
<p>Here, as they say, be dragons…</p>
<h1 id="the-problem">The problem</h1>
<p>In 1991 Unicode 1.0 was published. It defined 12,795 characters and reserved
space for 65,536 in total. To represent these values in memory you use the
character encoding UCS-2, which maps each pair of bytes in RAM directly to the
unicode code-point. This is very simple to implement, particularly compared to
other encodings proposed at the time, and so saw wide-spread adoption.</p>
<p>Five years later Unicode 2.0 came out. It defined 178,500 characters and
reserved space for 1,112,064. This is a lot more than can fit comfortably into
2 bytes. To avoid irritating everyone who had implemented Unicode 1.0, the
consortium came up with a clever backward-compatible encoding called UTF-16.</p>
<p>UTF-16 works by taking an unused portion of the unicode range (U+D800 through
U+DFFF) and marking it as invalid. Unicode strings must never contain code
points in that range. They took these unused code-points (known as surrogates)
and used them in pairs (known as surrogate pairs) to represent the extra
million code-points they wanted. For characters in the range 0x0000 - 0xFFFF,
UTF-16 uses two bytes to represent the code-point exactly like UCS-2. For
characters outside this range UTF-16 uses four bytes, with each pair of bytes
in the range 0xD800 - 0xDFFF.</p>
<figure class="image">
<a href="../images/unicode.png" title="Bit layout comparison"><img src="../images/unicode.png" alt="Bit layout comparison" /></a>
</figure>
<p>Unfortunately for us, Javascript has never been updated to support UTF-16.
Instead it continues to treat strings as UCS-2. Most of the time this isn’t a
problem, but if your input happens to contain a character in the range 0xD800 -
0xDFFF then Node will erroneously think it is valid Unicode. This isn’t a huge
problem in and of itself, but as soon as you want to share data between Node
and anything else, you need to be careful to ensure your Unicode is actually
valid according to the post-1996 definition.</p>
<h1 id="the-solution">The solution</h1>
<p>For now the easiest solution is to install the
<a href="https://npmjs.org/package/unicode-dragon">unicode-dragon</a> module from npm, and
use it to ensure your strings are valid Unicode:</p>
<figure class="highlight"><pre><code class="language-javascript" data-lang="javascript"><span class="nx">unicodeDragon</span> <span class="o">=</span> <span class="nx">require</span><span class="p">(</span><span class="dl">'</span><span class="s1">unicode-dragon</span><span class="dl">'</span><span class="p">);</span>
<span class="kd">var</span> <span class="nx">validString</span> <span class="o">=</span> <span class="nx">unicodeDragon</span><span class="p">(</span><span class="nx">buffer</span><span class="p">.</span><span class="nx">toString</span><span class="p">(</span><span class="dl">'</span><span class="s1">utf-8</span><span class="dl">'</span><span class="p">));</span></code></pre></figure>
<p>Ideally this problem would be fixed in V8 itself, and I’ve opened a <a href="https://code.google.com/p/v8/issues/detail?id=2875">bug
report</a> about it. There may
be valid reasons not to fix this completely, for example it’s quite likely that
people are relying on this bug to parse CESU-8, but we’ll see what happens.</p>
<h1 id="caveat-emptor">Caveat emptor</h1>
<p>If this bug is fixed in Node, or you use <code class="language-plaintext highlighter-rouge">unicodeDragon</code>, you still have to be
careful. Any time you modify a string in Javascript you have to be careful not
to chop a UTF-16 character in half. The exceptions that were crashing us were
caused by people using <code class="language-plaintext highlighter-rouge">String.prototype.substr</code>. That function works perfectly
on strings that only contain Unicode 1.0 data, but as soon as you’re storing
UTF-16 in your UCS-2 string there’s a possibility that when you take a slice
you’ll split a valid surrogate pair into two invalid lonely surrogates.</p>
<p>Almost all javascript String functions have the same problem, but luckily the
standard is slowly beginning to include some <a href="https://gist.github.com/slevithan/2290602">UTF-16 aware
helpers</a>. Hopefully someone will
figure out a nice way to make Javascript Unicode native sooner rather than
later, but until then we’ll have to continue being careful.</p>
bracketed paste mode2013-04-07T00:00:00+00:00http://cirw.in//blog/bracketed-paste.html<p>One of the least well known, and therefore least used, features of many terminal
emulators is <a href="http://www.xfree86.org/current/ctlseqs.html#Bracketed Paste Mode">bracketed paste
mode</a>. When
you are in bracketed paste mode and you paste into your terminal the content
will be wrapped by the sequences <code class="language-plaintext highlighter-rouge">\e[200~</code> and <code class="language-plaintext highlighter-rouge">\e[201~</code>.</p>
<aside>For example, let's say I copied the string <code>"echo 'hello'\n"</code> from a
website. When I paste into my terminal it will send <code>"\e[200~echo 'hello'\n\e[201~"</code>
to whatever program is running.</aside>
<p>I admit this is hard to get excited about, but it turns out that it enables
something very cool: programs can tell the difference between stuff you type
manually and stuff you pasted.</p>
<p>Why is that cool?</p>
<p>Lots of terminal applications handle some characters specially: in particular
when you hit your enter key it sends a newline. Most shells will execute the
contents of the input buffer at that point, which is usually what you want.
Unfortunately, this means that they will also run the contents of the input
buffer if there’s a newline in anything you paste into the terminal.</p>
<p>I’m clumsy and often paste random stuff into my terminal; there was also a neat
<a href="http://thejh.net/misc/website-terminal-copy-paste">proof of concept</a> for how to
make usually not-clumsy people do the same. This can obviously be dangerous as
your shell has the ability to do all kinds of things that you don’t want to
happen by accident.</p>
<p>For a while I’ve been running with bracketed paste mode enabled to protect me
from myself, and I figured it was time to share this support more widely. I take
no credit for writing any of this code; as clichéd as it sounds, I copy-pasted
it from the internet :).</p>
<figure>
<h1>
<a href="https://github.com/robbyrussell/oh-my-zsh/pull/1698">safe-paste</a> for oh-my-zsh
</h1>
The safe-paste plugin for <a href="https://github.com/robbyrussell/oh-my-zsh">oh-my-zsh</a>
is built out of the code I originally got from <a href="http://www.zsh.org/mla/users/2011/msg00367.html">Michael
Magnusson</a>. It turns off
running lines of input during pastes. This means that nothing you paste into
your shell, either deliberately or accidentally, will run until you manually hit
the enter key. This gives you time to double-check what you pasted before your
computer gets totally destroyed.
</figure>
<p>If you use <code class="language-plaintext highlighter-rouge">oh-my-zsh</code> you can install this by upgrading to the latest version
and adding <code class="language-plaintext highlighter-rouge">safe-paste</code> to the array of plugins in your <code class="language-plaintext highlighter-rouge">~/.zshrc</code>. If you just
use vanilla zsh, then you can just copy <a href="https://github.com/robbyrussell/oh-my-zsh/blob/master/plugins/safe-paste/safe-paste.plugin.zsh">the
code</a>
into your <code class="language-plaintext highlighter-rouge">~/.zshrc</code>.</p>
<p><b>Update:</b> Readline (as of v 7) and thus Bash (as of v4.4) now have support for bracketed paste mode too! You can enable it by adding <a href="https://tiswww.case.edu/php/chet/readline/rluserman.html#SEC9"><code class="language-plaintext highlighter-rouge">set enable-bracketed-paste on</code></a> to your <code class="language-plaintext highlighter-rouge">~/.inputrc</code>.</p>
<h1 id="vim-bracketed-paste"><a href="https://github.com/ConradIrwin/vim-bracketed-paste">vim-bracketed-paste</a></h1>
<p>Vim also handles newlines specially. When I am manually typing out code, vim
will add extra space characters each time I hit return so that the resulting
indentation is correct. Unfortunately when pasting into vim these extra spaces
end up making a mess because the content I’m pasting already includes the
correct indentation.</p>
<p>The usual work around for this is to manually run <code class="language-plaintext highlighter-rouge">":set paste"</code> inside vim
before pasting, but I often forget. The
<a href="https://github.com/ConradIrwin/vim-bracketed-paste">vim-bracketed-paste</a>
plugin uses code from <a href="http://stackoverflow.com/questions/5585129/pasting-code-into-terminal-window-into-vim-on-mac-os-x/7053522#7053522">Chis
Page</a>
to do this automatically for me, so the content I paste into vim does not get
automatically indented but the lines I type manually still do. You can install
this plugin using pathogen, or by copy-pasting <a href="https://github.com/ConradIrwin/vim-bracketed-paste/blob/master/plugin/bracketed-paste.vim">the
code</a>
into your <code class="language-plaintext highlighter-rouge">~/.vimrc</code>.</p>
<h1 id="technical-details">Technical details</h1>
<p>If you want to write a program that handles bracketed paste mode yourself you
have to do a bit of extra work. Bracketed paste mode isn’t enabled by default
because most programs make a mess of the extra escape sequences. To enable it
you need to output the sequence <code class="language-plaintext highlighter-rouge">\e[?2004h</code> to STDOUT when your program
starts. As bracketed paste mode is global to the terminal window you need to
remember to turn it off again when your program exits. To do this output the
sequence <code class="language-plaintext highlighter-rouge">\e[?2004l</code> to STDOUT.</p>
<p>In summary:</p>
<ol>
<li>Enable bracketed paste: <code class="language-plaintext highlighter-rouge">printf "\e[?2004h"</code></li>
<li>Wait for paste to start: you’ll see <code class="language-plaintext highlighter-rouge">\e[200~</code> on STDIN.</li>
<li>Wait for paste to stop: you’ll see <code class="language-plaintext highlighter-rouge">\e[201~</code> on STDIN.</li>
<li>Disable bracketed paste: <code class="language-plaintext highlighter-rouge">printf "\e[?2004l"</code></li>
</ol>
<aside>If you want more detail, there's a thorough (and thoroughly inscrutable)
reference on <a href="http://www.xfree86.org/4.7.0/ctlseqs.html#Bracketed%20Paste%20Mode">xfree86.org</a>.</aside>
<h1 id="terminal-support">Terminal support</h1>
<p>For a long time bracketed paste mode was only supported by xterm and its
derivatives (urxvt, etc.), but as of recently (a year or so ago) support has
been added to most other terminals, including libvte which powers
gnome-terminal et.al., iTerm 2 and Terminal.app. In other words, almost every
terminal in widespread use now suppports bracketed paste mode.</p>
<p>If you maintain a program that runs inside a terminal emulator, now is
definitely the time to consider adding support for bracketed paste mode. Even
little niceties like waiting for an extra newline after pasting can make the
user feel much more in control.</p>
Visualizing memory leaks in Ruby2013-03-02T00:00:00+00:00http://cirw.in//blog/find-references.html<p>Memory leaks are my least favourite type of bug. To track them down requires not only a detailed knowledge of the entire codebase but also strong intuition (or a lot of luck). To make the process more fun I’ve written a patch for ruby 1.9.3 that lets you visualize portions of the memory graph.</p>
<h1 id="objectspaceeach_object">ObjectSpace.each_object</h1>
<p>Ruby already comes with <code class="language-plaintext highlighter-rouge">ObjectSpace</code> which contains a few methods for analyzing your program. The most useful for finding memory leaks is <code class="language-plaintext highlighter-rouge">ObjectSpace.each_object</code> which yields every single ruby object in your program.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="n">counts</span> <span class="o">=</span> <span class="no">Hash</span><span class="p">.</span><span class="nf">new</span><span class="p">{</span> <span class="mi">0</span> <span class="p">}</span>
<span class="no">ObjectSpace</span><span class="p">.</span><span class="nf">each_object</span> <span class="k">do</span> <span class="o">|</span><span class="n">o</span><span class="o">|</span>
<span class="n">counts</span><span class="p">[</span><span class="n">o</span><span class="p">.</span><span class="nf">class</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="k">end</span></code></pre></figure>
<p>By dumping the counts into a file after each request and using <code class="language-plaintext highlighter-rouge">diff</code> it’s possible to determine what kind of objects are leaking. This is essential to know, but it doesn’t give you any insight into why they’re not being garbage collected.</p>
<h1 id="objectspacefind_references">ObjectSpace.find_references</h1>
<p>The first step in getting more insight is to find everything that references the object that is being leaked. Ruby already knows how to calculate this information, as it’s needed for the mark and sweep garbage collection, but it doesn’t expose it to ruby code. The patches add a <code class="language-plaintext highlighter-rouge">find_references</code> method to <code class="language-plaintext highlighter-rouge">ObjectSpace</code> that returns an array of all objects that reference the object you’re looking for.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="no">ObjectSpace</span><span class="p">.</span><span class="nf">find_references</span><span class="p">(</span>
<span class="no">ObjectSpace</span><span class="p">.</span><span class="nf">each_object</span><span class="p">(</span><span class="no">MainController</span><span class="p">).</span><span class="nf">first</span>
<span class="p">)</span></code></pre></figure>
<p>This works but it turns out to be far too fiddly for manual use while debugging. The main problem is that every time you run <code class="language-plaintext highlighter-rouge">find_references</code> the array that is returned adds a whole slew of additional bogus references. This pollutes the reference graph quickly, so you continually have to restart the process to flush these out.</p>
<h1 id="objectgraphview">ObjectGraph#view!</h1>
<p>The next step is to recursively run <code class="language-plaintext highlighter-rouge">find_references</code> until you’ve generated a graph that shows all the ways in which your object is referenced. This is wrapped up by the <code class="language-plaintext highlighter-rouge">ObjectGraph</code> class, which takes care to avoid the bogus-references problem. The most useful thing this class can do is let you <code class="language-plaintext highlighter-rouge">view!</code> the graph using graphviz.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="nb">require</span> <span class="s1">'object_graph'</span>
<span class="no">ObjectGraph</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="mi">9</span><span class="p">).</span><span class="nf">view!</span></code></pre></figure>
<div class="highlight">
<a href="../images/references.pdf"><img src="../images/references-preview.png" /></a>
</div>
<p>While 9 is a silly example it hopefully gives you a feel for how easy it is to reason about the resulting graph. You’ll notice that not only is each node labelled with the inspect output for the object, each edge is also labelled in a way that corresponds to how the reference was made. If you need programmatic access to this information then the <code class="language-plaintext highlighter-rouge">annotated_edges</code> method returns an array of edges along with their description.</p>
<h1 id="installation">Installation</h1>
<p>My <a href="https://github.com/ConradIrwin/ruby/commits/find-references">patches</a> add both <a href="https://github.com/ConradIrwin/ruby/commit/af5266875503d58b9fd16a6748d71649e69af922"><code class="language-plaintext highlighter-rouge">ObjectSpace.find_references</code></a> and a new <a href="https://github.com/ConradIrwin/ruby/blob/find-references/lib/object_graph.rb"><code class="language-plaintext highlighter-rouge">ObjectGraph</code></a> standard library. If you want to use them you can either clone my repository and build the <code class="language-plaintext highlighter-rouge">find-references</code> branch yourself, or use one of the quick methods below:</p>
<p>Using <a href="http://rvm.io">rvm</a> with a patch:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">curl <span class="nt">-L</span> http://git.io/kRIgxw <span class="o">></span> references.patch
rvm <span class="nb">install </span>1.9.3-p392-ref <span class="nt">--patch</span> ./references.patch
rvm use 1.9.3-p392-ref</code></pre></figure>
<p>Using <a href="https://github.com/sstephenson/rbenv">rbenv</a> with ruby-build:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">curl <span class="nt">-L</span> http://git.io/4fQ9Jg <span class="o">></span> 1.9.3-p392-ref
rbenv <span class="nb">install</span> ./1.9.3-p392-ref
rbenv shell 1.9.3-p392-ref</code></pre></figure>
<p>Using <a href="https://github.com/postmodern/chruby">chruby</a> with ruby-build:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">curl <span class="nt">-L</span> http://git.io/4fQ9Jg <span class="o">></span> 1.9.3-p392-ref
ruby-build ./1.9.3-p392-ref ~/.rubies/ruby-1.9.3-p392-ref
chruby 1.9.3-p392-ref</code></pre></figure>
<p>To get pretty pictures, you’ll also need to <code class="language-plaintext highlighter-rouge">brew install graphviz</code> or <code class="language-plaintext highlighter-rouge">apt-get install graphviz</code>.</p>
LSpace: Dynamic scope for Ruby2012-12-01T00:00:00+00:00http://cirw.in//blog/lspace.html<p>At <a href="http://rapportive.com">Rapportive</a> we have one master database that’s always
up-to-date, and a read slave that may be a little bit behind. Usually a database
read can use either connection, but if a user is viewing their own page we need
to use the master database. This is so that if they’ve just edited their
information, their edits are guaranteed to show up, even if the read slave is
lagging.</p>
<p><a href="https://github.com/ConradIrwin/lspace">LSpace</a> is a library designed for
holding implicit state like this. We can tell the database layer to use the
master database at the top level, and that decision will be transparently passed
down through the page loading logic:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="nb">require</span> <span class="s1">'lspace'</span>
<span class="k">class</span> <span class="nc">DatabaseConnection</span>
<span class="k">def</span> <span class="nf">get_read_connection</span>
<span class="no">LSpace</span><span class="p">[</span><span class="ss">:database</span><span class="p">]</span> <span class="o">||</span> <span class="n">slave_db</span>
<span class="k">end</span>
<span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">use_master</span><span class="p">(</span><span class="o">&</span><span class="n">block</span><span class="p">)</span>
<span class="no">LSpace</span><span class="p">.</span><span class="nf">with</span><span class="p">(</span><span class="ss">:database</span> <span class="o">=></span> <span class="n">master_db</span><span class="p">)</span> <span class="k">do</span>
<span class="n">block</span><span class="p">.</span><span class="nf">call</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="no">DatabaseConnection</span><span class="p">.</span><span class="nf">use_master</span> <span class="k">do</span>
<span class="n">load_data_for_page</span>
<span class="k">end</span></code></pre></figure>
<p>As you can see, <code class="language-plaintext highlighter-rouge">load_data_for_page</code> doesn’t need to take an argument to tell it which
database to use. It just uses the LSpace for implicit context.</p>
<h1 id="why-not-just-a-global">Why not just a global?</h1>
<p>In the example above I clearly could have used a global variable, though that gets a bit
messy if there are multiple threads. I could even have used a Thread-local, but LSpace is
better than Thread-locals for two reasons:</p>
<ol>
<li>LSpace locals are changed only for the duration of a block. This means that
you won’t permanently clobber the value that someone else set, and that your
value won’t leak once you no-longer need it.</li>
<li>LSpace can automatically extend the notion of thread when you’re using
<a href="https://github.com/eventmachine/eventmachine">eventmachine</a> or
<a href="http://celluloid.io">celluloid</a>. Values in LSpace are preserved even when your code
jumps between actors or continues after a callback.</li>
</ol>
<p>As I’m sure the old-time-lispers are eager to point out, the first makes
LSpace an implementation of
<a href="http://en.wikipedia.org/wiki/Dynamic_scope">dynamic scoping</a>
and the second exists to avoid the confusion caused by the
<a href="http://en.wikipedia.org/wiki/Funarg_problem#Upwards_funarg_problem">upwards funarg problem</a>.</p>
<h1 id="why-is-dynamic-scope-useful">Why is dynamic scope useful?</h1>
<p>LSpace is good for anything that needs implicit context. You’ll notice that to demonstate
how it works, I did not need to show you the implementation of
<code class="language-plaintext highlighter-rouge">load_data_for_page</code>. By the same token, <code class="language-plaintext highlighter-rouge">load_data_for_page</code> doesn’t need to
care which database connection it’s using; it just relies on the fact that a
connection will be available when it needs one.</p>
<p>Let’s take another example. When logging I want to ensure related log messages have the
same prefix, so I can tie them back together again:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">log</span><span class="p">(</span><span class="n">str</span><span class="p">)</span>
<span class="nb">puts</span> <span class="s2">"</span><span class="si">#{</span><span class="no">LSpace</span><span class="p">[</span><span class="ss">:log_prefix</span><span class="p">]</span><span class="si">}</span><span class="s2">: </span><span class="si">#{</span><span class="n">str</span><span class="si">}</span><span class="s2">"</span>
<span class="k">end</span>
<span class="no">LSpace</span><span class="p">.</span><span class="nf">with</span><span class="p">(</span><span class="ss">:log_prefix</span> <span class="o">=></span> <span class="s2">"example"</span><span class="p">)</span> <span class="k">do</span>
<span class="n">log</span> <span class="s2">"hello world"</span>
<span class="k">end</span>
<span class="c1"># => example: hello world</span></code></pre></figure>
<p>I could have just passed <code class="language-plaintext highlighter-rouge">log_prefix</code> into the log method directly, but I chose not to in
order to keep the API clean. The benefits of this become more obvious in a larger example:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">fetch</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
<span class="n">url</span> <span class="o">=</span> <span class="no">URI</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
<span class="n">log</span> <span class="s2">"Fetching </span><span class="si">#{</span><span class="n">url</span><span class="si">}</span><span class="s2">"</span>
<span class="no">Net</span><span class="o">::</span><span class="no">HTTP</span><span class="p">.</span><span class="nf">get</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
<span class="k">end</span>
<span class="k">def</span> <span class="nf">get_title</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
<span class="n">html</span> <span class="o">=</span> <span class="n">fetch</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
<span class="p">(</span><span class="no">Nokogiri</span><span class="o">::</span><span class="no">HTML</span><span class="p">(</span><span class="n">html</span><span class="p">)</span> <span class="o">/</span> <span class="s1">'title'</span><span class="p">).</span><span class="nf">to_s</span>
<span class="k">end</span>
<span class="no">LSpace</span><span class="p">.</span><span class="nf">with</span><span class="p">(</span><span class="ss">:log_prefix</span> <span class="o">=></span> <span class="s2">"example"</span><span class="p">)</span> <span class="k">do</span>
<span class="n">log</span> <span class="n">get_title</span><span class="p">(</span><span class="s1">'http://www.google.com'</span><span class="p">)</span>
<span class="k">end</span></code></pre></figure>
<p>If I didn’t have LSpace (or thread locals) then I’d have had to pass
<code class="language-plaintext highlighter-rouge">log_prefix</code> as an argument to <code class="language-plaintext highlighter-rouge">get_title</code>. This works, but it’s ugly:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">def</span> <span class="nf">get_title</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">log_prefix</span><span class="p">)</span>
<span class="n">html</span> <span class="o">=</span> <span class="n">fetch</span><span class="p">(</span><span class="n">url</span><span class="p">,</span> <span class="n">log_prefix</span><span class="p">)</span>
<span class="p">(</span><span class="no">Nokogiri</span><span class="o">::</span><span class="no">HTML</span><span class="p">(</span><span class="n">html</span><span class="p">)</span> <span class="o">/</span> <span class="s1">'title'</span><span class="p">).</span><span class="nf">to_s</span>
<span class="k">end</span></code></pre></figure>
<p>I don’t just mean “it’s ugly because it now takes two parameters”, though that
certainly doesn’t help. It’s ugly because <code class="language-plaintext highlighter-rouge">get_title</code> shouldn’t depend on how
<code class="language-plaintext highlighter-rouge">fetch</code> is implemented; in fact, <code class="language-plaintext highlighter-rouge">fetch</code> shouldn’t even depend on how the logger
is implemented.</p>
<p>This tight coupling means that if I ever want to add a new <code class="language-plaintext highlighter-rouge">log</code> call to my
application, I’m going to have to change a lot of code to pass the <code class="language-plaintext highlighter-rouge">log_prefix</code>
all the way down to the logger. This is clearly bad for maintainability, as it’s
adding a lot of extra work for the programmer.</p>
<h1 id="should-i-use-lspace">Should I use LSpace?</h1>
<p>LSpace makes part of your context implicit. This is good because it reduces the
amount of boilerplate state-passing you need, but can be confusing if over-used
(<code class="language-plaintext highlighter-rouge">this</code> in Javascript is perhaps the most infamous example of the problem).</p>
<p>We use LSpace mostly for framework-level concerns, rather than directly for
application logic:</p>
<ol>
<li>Setting a logging prefix (just like in the example above). It makes logs much
easier to read when you can associate lines that came from the same request.</li>
<li>Being able to use a particular database connection for the duration of a
block. When we show the user their own information, we force the code to read
from our master database so that any changes they just made will appear.</li>
<li>Maintaining state in our metrics library to enable
<a href="http://twitter.github.com/zipkin/">Zipkin</a>-style traces of which slownesses
are caused by which others.</li>
</ol>
<p>Other people are using similar ideas for some really cool stuff. In particular
you should look at how the reactive programming is implemented in
<a href="http://docs.meteor.com/#reactivity">meteor.js</a>, or why dynamic scope is used in
<a href="http://www.gnu.org/software/emacs/emacs-paper.html#SEC18">Emacs lisp</a>.</p>
<p>I’d encourage you to read the <a href="https://github.com/ConradIrwin/lspace">README</a>,
and see whether LSpace can work its magic for you.</p>
Everything you ever wanted to know about constant lookup in Ruby2012-11-23T00:00:00+00:00http://cirw.in//blog/constant-lookup.html<p>One of the best things about Ruby is that it just does what you mean. The downside of this
is that if you’re dealing with a fiddly situation, it can be somewhat hard to work out
exactly what it will do.</p>
<p>This is particularly true of constant lookup. To access a constant in ruby, you just use
its name: <code class="language-plaintext highlighter-rouge">FooClass</code>. But how does that actually work?</p>
<aside>Although the answer turns out to be reasonably straightforward, I've included a lot
of examples. It's easy to tell you that constant lookup searches for constants that are defined in
`Module.nesting`, `Module.nesting.first.ancestors`, and `Object.ancestors` if
Module.nesting.first is nil or a module, but that doesn't really help with understanding.</aside>
<h1 id="modulenesting">Module.nesting</h1>
<p>To a first approximation, Ruby looks for constants attached to modules and classes in the
surrounding lexical scope of your code, for example:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">module</span> <span class="nn">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">module</span> <span class="nn">C</span>
<span class="k">module</span> <span class="nn">D</span>
<span class="no">B</span> <span class="o">==</span> <span class="no">A</span><span class="o">::</span><span class="no">B</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="k">end</span></code></pre></figure>
<p>It first looks for <code class="language-plaintext highlighter-rouge">A::C::D::B</code> (doesn’t exist), then <code class="language-plaintext highlighter-rouge">A::C::B</code> (still doesn’t exist), and
then finally <code class="language-plaintext highlighter-rouge">A::B</code> (which does).</p>
<p>Like almost everything in Ruby, the chain of namespaces that will be searched (known to
l33t hackers as the <code class="language-plaintext highlighter-rouge">cref</code>) is introspectable at runtime with <code class="language-plaintext highlighter-rouge">Module.nesting</code>:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">module</span> <span class="nn">A</span>
<span class="k">module</span> <span class="nn">C</span>
<span class="k">module</span> <span class="nn">D</span>
<span class="no">Module</span><span class="p">.</span><span class="nf">nesting</span> <span class="o">==</span> <span class="p">[</span><span class="no">A</span><span class="o">::</span><span class="no">C</span><span class="o">::</span><span class="no">D</span><span class="p">,</span> <span class="no">A</span><span class="o">::</span><span class="no">C</span><span class="p">,</span> <span class="no">A</span><span class="p">]</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="k">end</span></code></pre></figure>
<p>If you’ve ever tried to take a short-cut when re-opening a module, you may have noticed
that constants from skipped namespaces aren’t available. This is because the outer
namespaces are not added to <code class="language-plaintext highlighter-rouge">Module.nesting</code>.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">module</span> <span class="nn">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">module</span> <span class="nn">A::C</span>
<span class="no">B</span>
<span class="k">end</span>
<span class="c1"># NameError: uninitialized constant A::C::B</span></code></pre></figure>
<p>In order to find <code class="language-plaintext highlighter-rouge">B</code>, <code class="language-plaintext highlighter-rouge">Module.nesting</code> would have to include <code class="language-plaintext highlighter-rouge">A</code>, but it doesn’t. It only
includes <code class="language-plaintext highlighter-rouge">A::C</code>.</p>
<h1 id="ancestors">Ancestors</h1>
<p>If the constant cannot be found by looking at any of the modules in <code class="language-plaintext highlighter-rouge">Module.nesting</code>, Ruby
takes the currently open module or class, and looks at its ancestors.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">class</span> <span class="nc">C</span> <span class="o"><</span> <span class="no">A</span>
<span class="no">B</span> <span class="o">==</span> <span class="no">A</span><span class="o">::</span><span class="no">B</span>
<span class="k">end</span></code></pre></figure>
<p>The currently open class or module is the innermost <code class="language-plaintext highlighter-rouge">class</code> or <code class="language-plaintext highlighter-rouge">module</code> statement in the
code. A common misconception is that constant lookup uses <code class="language-plaintext highlighter-rouge">self.class</code>, which is not true.
(btw, it’s not using the <a href="http://yugui.jp/articles/846">default definee</a> either, just in
case you wondered):</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">A</span>
<span class="k">def</span> <span class="nf">get_c</span><span class="p">;</span> <span class="no">C</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">class</span> <span class="nc">B</span> <span class="o"><</span> <span class="no">A</span>
<span class="k">module</span> <span class="nn">C</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="no">B</span><span class="p">.</span><span class="nf">new</span><span class="p">.</span><span class="nf">get_c</span>
<span class="c1"># NameError: uninitialized constant A::C</span></code></pre></figure>
<h1 id="object">Object::</h1>
<p><code class="language-plaintext highlighter-rouge">Module.nesting == []</code> at the top level, and so constant lookup starts at the currently
open class and its ancestors. While there’s no <code class="language-plaintext highlighter-rouge">class</code> or <code class="language-plaintext highlighter-rouge">module</code> statement that you can
see, it is taken for granted that at the top level of a ruby file the currently open class
is Object:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">Object</span>
<span class="k">module</span> <span class="nn">C</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="no">C</span> <span class="o">==</span> <span class="no">Object</span><span class="o">::</span><span class="no">C</span></code></pre></figure>
<p>Although I’ve not explicitly said it yet, you’ve probably noticed that newly defined
constants also get defined on the currently open class. So constants you define at the top
level end up attached to <code class="language-plaintext highlighter-rouge">Object</code>.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">module</span> <span class="nn">C</span><span class="p">;</span> <span class="k">end</span>
<span class="no">Object</span><span class="o">::</span><span class="no">C</span> <span class="o">==</span> <span class="no">C</span></code></pre></figure>
<p>This in turn explains why top-level constants are available throughout your program.
Almost all classes in Ruby inherit from Object, so Object is almost always included in
the list of ancestors of the currently open class, and thus its constants are almost
always available.</p>
<p>That said, if you’ve ever used a <code class="language-plaintext highlighter-rouge">BasicObject</code>, and noticed that top-level constants are
missing, you now know why. Because <code class="language-plaintext highlighter-rouge">BasicObject</code> does not subclass <code class="language-plaintext highlighter-rouge">Object</code>, all of the
constants are not in the lookup chain:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">Foo</span> <span class="o"><</span> <span class="no">BasicObject</span>
<span class="no">Kernel</span>
<span class="k">end</span>
<span class="c1"># NameError: uninitialized constant Foo::Kernel</span></code></pre></figure>
<p>For cases like this, and anywhere else you want to be explicit, Ruby allows you to use
<code class="language-plaintext highlighter-rouge">::Kernel</code> to access <code class="language-plaintext highlighter-rouge">Object::Kernel</code>.</p>
<p>Ruby assumes that you will mix modules into something that inherits from <code class="language-plaintext highlighter-rouge">Object</code>. So if
the currently open module is a module, it will also add <code class="language-plaintext highlighter-rouge">Object.ancestors</code> to the lookup
chain so that top-level constants work as expected:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">module</span> <span class="nn">A</span><span class="p">;</span> <span class="k">end</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span>
<span class="no">A</span> <span class="o">==</span> <span class="no">Object</span><span class="o">::</span><span class="no">A</span>
<span class="k">end</span></code></pre></figure>
<h1 id="class_eval"><code class="language-plaintext highlighter-rouge">class_eval</code></h1>
<p>As mentioned above, constant lookup uses the currently open class, as determined by
<code class="language-plaintext highlighter-rouge">class</code> and <code class="language-plaintext highlighter-rouge">module</code> statements. Importantly, if you pass a block into <code class="language-plaintext highlighter-rouge">class_eval</code> or
<code class="language-plaintext highlighter-rouge">module_eval</code> (or <code class="language-plaintext highlighter-rouge">instance_eval</code> or <code class="language-plaintext highlighter-rouge">define_method</code>), this won’t change constant lookup.
It continues to use the constant lookup at the point the block was defined:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">class</span> <span class="nc">C</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="no">A</span><span class="p">.</span><span class="nf">class_eval</span><span class="p">{</span> <span class="no">B</span> <span class="p">}</span> <span class="o">==</span> <span class="no">C</span><span class="o">::</span><span class="no">B</span>
<span class="k">end</span></code></pre></figure>
<aside>This was not true in ruby 1.9.1, and is perhaps the main reason that that
particular version was quick to fade out of existence. Many DSLs rely on instance eval'ing
the programmer's code in internal contexts, and it was considered very confusing to break
access to the programmer's own constants.</aside>
<p>Confusingly however, if you pass a String to these methods, then the String is evaluated
with <code class="language-plaintext highlighter-rouge">Module.nesting</code> containing just the class itself (for <code class="language-plaintext highlighter-rouge">class_eval</code>) or just the
singleton class of the object (for <code class="language-plaintext highlighter-rouge">instance_eval</code>).</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">class</span> <span class="nc">C</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="no">A</span><span class="p">.</span><span class="nf">class_eval</span><span class="p">(</span><span class="s2">"B"</span><span class="p">)</span> <span class="o">==</span> <span class="no">A</span><span class="o">::</span><span class="no">B</span>
<span class="k">end</span></code></pre></figure>
<h1 id="other-gotchas">Other gotchas</h1>
<p>Finally I want to point out that if you’re in a singleton class of a class, you don’t get
access to constants defined in the class itself:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">class</span> <span class="o"><<</span> <span class="no">A</span>
<span class="no">B</span>
<span class="k">end</span>
<span class="c1"># NameError: uninitialized constant Class::B</span></code></pre></figure>
<p>This is because the ancestors of the singleton class of a class do not include the class
itself, they start at the <code class="language-plaintext highlighter-rouge">Class</code> class.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">class</span> <span class="o"><<</span> <span class="no">A</span><span class="p">;</span> <span class="nb">ancestors</span><span class="p">;</span> <span class="k">end</span>
<span class="p">[</span><span class="no">Class</span><span class="p">,</span> <span class="no">Module</span><span class="p">,</span> <span class="no">Object</span><span class="p">,</span> <span class="no">Kernel</span><span class="p">,</span> <span class="no">BasicObject</span><span class="p">]</span></code></pre></figure>
<p>In a similar vein, it may also worth noting that superclasses of things in
<code class="language-plaintext highlighter-rouge">Module.nesting</code> are ignored. For example:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">A</span>
<span class="k">module</span> <span class="nn">B</span><span class="p">;</span> <span class="k">end</span>
<span class="k">end</span>
<span class="k">class</span> <span class="nc">C</span> <span class="o"><</span> <span class="no">A</span>
<span class="k">class</span> <span class="nc">D</span>
<span class="no">B</span>
<span class="k">end</span>
<span class="k">end</span>
<span class="c1"># NameError: uninitialized constant C::D::B</span></code></pre></figure>
<h1 id="summary">Summary</h1>
<p>Constant lookup in ruby isn’t actually that hard after-all. It just looks at the lexical
nesting of <code class="language-plaintext highlighter-rouge">class</code> and <code class="language-plaintext highlighter-rouge">module</code> statements. You can calculate the currently open class by
using the first value in <code class="language-plaintext highlighter-rouge">Module.nesting</code>, or defaulting to <code class="language-plaintext highlighter-rouge">Object</code> if that array is
empty.</p>
<p>Here’s some code that accurately replicates Ruby’s inbuilt constant lookup. You’ll notice
that I have to use binding.eval with a String so that <code class="language-plaintext highlighter-rouge">Module.nesting</code> is taken from the
binding object and not the block :).</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">Binding</span>
<span class="k">def</span> <span class="nf">const</span><span class="p">(</span><span class="nb">name</span><span class="p">)</span>
<span class="nb">eval</span> <span class="o"><<-</span><span class="no">CODE</span><span class="p">,</span> <span class="kp">__FILE__</span><span class="p">,</span> <span class="kp">__LINE__</span> <span class="o">+</span> <span class="mi">1</span><span class="sh">
modules = Module.nesting + (Module.nesting.first || Object).ancestors
modules += Object.ancestors if Module.nesting.first.class == Module
found = nil
modules.detect do |mod|
found = mod.const_get(</span><span class="si">#{</span><span class="nb">name</span><span class="p">.</span><span class="nf">inspect</span><span class="si">}</span><span class="sh">, false) rescue nil
end
found or const_missing(</span><span class="si">#{</span><span class="nb">name</span><span class="p">.</span><span class="nf">inspect</span><span class="si">}</span><span class="sh">)
</span><span class="no"> CODE</span>
<span class="k">end</span>
<span class="k">end</span></code></pre></figure>
pry to the rescue2012-08-17T00:00:00+00:00http://cirw.in//blog/pry-to-the-rescue.html<aside>This post is also available [in
Russian](http://scriptogr.am/entooru/post/20120827-pry-to-the-rescue). Thanks [kyrylo](mailto:kyrylosilin@gmail.com)!</aside>
<p>Introducing: <a href="https://github.com/ConradIrwin/pry-rescue">pry-rescue</a>: super-fast,
painless, debugging for the (ruby) masses.</p>
<h1 id="what-does-it-do">What does it do?</h1>
<p>Whenever an unhandled exception happens in your program, pry-rescue opens an interactive
<a href="http://pryrepl.org/">pry</a> shell right at the point it was raised. Instead of glowering
at a stack-trace spewed out by a dying process, you’ll be engaging with your program as
though it were still alive!</p>
<p>The pry console gives you access to the method that raised the exception, you can use it
to inspect the values of variables (no more print statements!), the source code of methods
(no more flapping around with a text editor!), and even move up and down the call stack
(like a real debugger!).</p>
<p>Because the shell opens as though the exception were just about to be raised, you don’t
even need to re-run your program from the beginning in order to start debugging. It’s
optimized for the “exceptions-happen” workflow that you need when developing code.</p>
<h1 id="ok-sounds-good-how-do-i-use-this">Ok, sounds good, how do I use this?</h1>
<p>It’s easy: <code class="language-plaintext highlighter-rouge">gem install pry-rescue pry-stack_explorer</code>, and then run your program using
<code class="language-plaintext highlighter-rouge">rescue foo.rb</code> instead of <code class="language-plaintext highlighter-rouge">ruby foo.rb</code>. If <code class="language-plaintext highlighter-rouge">rescue</code> doesn’t float your boat, then just
wrap chunks of your program in <code class="language-plaintext highlighter-rouge">Pry::rescue{ }</code>. Any exceptions that are unhandled within
that block will be rescued by pry on your behalf. (rack middleware coming soon!)</p>
<p>Whenever pry opens because of an exception you have two choices: hit <ctrl-d> to let
the exception bubble on its way, or do some debugging! If you choose the latter path, then
you can use the full power of pry to fix the problem; and then <code class="language-plaintext highlighter-rouge">try-again</code> to verify the
fix worked.</p>
<h1 id="uh-do-you-have-an-example">Uh… do you have an example?</h1>
<p>Sure! Let’s imagine that I wrote some code that looks like this:</p>
<div class="highlight"><pre><code clas="ruby"><span class="bold"><span class="f8"></span><span class="bold">def</span> <span class="f8"><span class="nf">find_capitalized</span></span></span>(a)
a.select <span class="f8"></span><span class="bold">do</span> |name|
name.chars.first == name.chars.first.upcase
<span class="f8"></span><span class="bold">end</span>
<span class="f8"></span><span class="bold">end</span>
</code></pre></div>
<p>Now I run the code: <code class="language-plaintext highlighter-rouge">rescue rescue.rb</code></p>
<div class="highlight"><pre><code clas="ruby"><span class="bold">From:</span> rescue.rb @ line 2 Object#find_capitalized:
<span class="ef30">2</span>: <span class="f8"></span><span class="bold">def</span> <span class="f8"><span><span class="nf">find_capitalized</span></span></span>(a)
<span class="ef30">3</span>: a.select <span class="f8"></span><span class="bold">do</span> |name|
=> <span class="ef30">4</span>: name.chars.first == name.chars.first.upcase
<span class="ef30">5</span>: <span class="f8"></span><span class="bold">end</span>
<span class="ef30">6</span>: <span class="f8"></span><span class="bold">end</span>
NoMethodError: undefined method `chars' for :direction:Symbol
from rescue.rb:4:in `block in find_capitalized'
[1] pry(main)>
</code></pre></div>
<p>Well, it’s gone wrong. But at least I can see why. Let’s move <code class="language-plaintext highlighter-rouge">up</code> the stack and see if we
can find which code is calling this method with symbols:</p>
<div class="highlight"><pre><code clas="ruby">[1] pry(main)> up
<span class="bold">From:</span> rescue.rb @ line 8 Object#extract_people:
<span class="ef30">8</span>: <span class="f8"></span><span class="bold">def</span> <span class="f8"><span><span class="nf">extract_people</span></span></span>(opts)
=> <span class="ef30">9</span>: name_keys = find_capitalized(opts.keys)
<span class="ef30">10</span>:
<span class="ef30">11</span>: name_keys.each_with_object({}) <span class="f8"></span><span class="bold">do</span> |name, o|
<span class="ef30">12</span>: o[name] = opts.delete name
<span class="ef30">13</span>: <span class="f8"></span><span class="bold">end</span>
<span class="ef30">14</span>: <span class="f8"></span><span class="bold">end</span>
[2] pry(main)> opts
=> {<span class="ef161"><span class="ef161">"</span></span><span class="ef161"><span class="ef161">Arthur</span></span><span class="ef161"><span class="ef161">"</span></span><span class="ef161"></span>=><span class="ef161"><span class="ef161">"</span></span><span class="ef161"><span class="ef161">Dent</span></span><span class="ef161"><span class="ef161">"</span></span><span class="ef161"></span>, <span class="ef90">:direction</span>=><span class="ef90">:left</span>}
</code></pre></div>
<p>Ok, that seems odd, but fair enough, let’s see if there’s a better way of implementing
<code class="language-plaintext highlighter-rouge">find_capitalized</code>:</p>
<div class="highlight"><pre><code clas="ruby">[3] pry(main)> down
[4] pry(main)> name.first
NoMethodError: undefined method `first' for :direction
from (pry):9:in `block in find_capitalized'
[5] pry(main)> name.capitalize
=> <span class="ef90">:Direction<span>
</code></pre></div>
Got it. Let's `edit-method` to fix the code, and `try-again` to verify the fix worked:
<div class="highlight"><pre><code clas="ruby">[6] pry(main)> edit-method
[7] pry(main)> whereami
<span class="bold">From:</span> rescue.rb @ line 2 Object#find_capitalized:
<span class="ef30">2</span>: <span class="f8"></span><span class="bold">def</span> <span class="f8"><span><span class="nf">find_capitalized</span></span></span>(a)
=> <span class="ef30">3</span>: a.select <span class="f8"></span><span class="bold">do</span> |name|
<span class="ef30">4</span>: name.capitalize == name
<span class="ef30">5</span>: <span class="f8"></span><span class="bold">end</span>
<span class="ef30">6</span>: <span class="f8"></span><span class="bold">end</span>
[8] pry(main)> try-again
Arthur Dent moves left
</pre></code></div>
<aside>If you want to work through this example yourself, just clone
`https://github.com/ConradIrwin/pry-rescue` and then run `rescue examples/rescue.rb`.</aside>
What else do I need to know?
============================
Well, there are a myriad of pry commands that are useful while debugging: `wtf?` and
`cat --ex` can be used to examine stack traces and the associated code; `cd` and `ls`
can be used to closely examine objects; `$` and `edit-method` can be used to view and edit
source code. The best thing to do is just type `help` once you've installed pry.
The other useful `pry-rescue` command is `cd-cause`. It lets you rewind back the the
previously raised exception. So, if you've rescued one exception, and then raised another
(it happens…) you can jump back to the original cause of the problem.
Apart from that, the only thing you might want to know is that you can use
`Pry::rescue{ }` with exceptions that you handle yourself. Just call `Pry::rescued(e)` in
your rescue block.
So, `gem install pry-rescue` now. If you find problems, please
let me know on [github](https://github.com/ConradIrwin/pry-rescue).
</pre></div></span></span></code></pre></div>
MVC is dead, it's time to MOVE on.2012-06-29T00:00:00+00:00http://cirw.in//blog/time-to-move-on.html<p>MVC is a phenomenal idea. You have models, which are nice self-contained bits of
state, views which are nice self-contained bits of UI, and controllers which are nice
self-contained bits of …</p>
<p>What?</p>
<p>I’m certainly not the first person to notice this, but the problem with MVC as given is
that you end up stuffing too much code into your controllers, because you don’t know where
else to put it.</p>
<p>To fix this I’ve been using a new pattern: <b>MOVE</b>. <b>M</b>odels, <b>O</b>perations,
<b>V</b>iews, and <b>E</b>vents.</p>
<h1 id="overview">Overview</h1>
<figure class="image">
<a href="../images/move.jpg" title="Architecture of a MOVE app">
<img src="../images/move.jpg" alt="Architecture of a MOVE app" />
</a>
</figure>
<p>I’ll define the details in a minute, but this diagram shows the basic structure of a MOVE
application.</p>
<ul>
<li>Models encapsulate everything that your application knows.</li>
<li>Operations encapsulate everything that your application does.</li>
<li>Views mediate between your application and the user.</li>
<li>Events are used to join all these components together safely.</li>
</ul>
<p>In order to avoid spaghetti code, it’s also worth noting that there are recommendations
for what objects of each type are allowed to do. I’ve represented these as arrows on the
diagram. For example, views are allowed to listen to events emitted by models, and
operations are allowed to change models, but models should not refer to either views or
operations.</p>
<h1 id="models">Models</h1>
<p>The archetypal model is a “user” object. It has at the very least an email address, and
probably also a name and a phone number.</p>
<p>In a MOVE application models only wrap knowledge. That means that, in addition to getters
and setters, they might contain functions that let you check “is this the user’s
password?”, but they don’t contain functions that let you save them to a database or
upload them to an external API. That would be the job of an operation.</p>
<h1 id="operations">Operations</h1>
<p>A common operation for applications is logging a user in. It’s actually two sub-operations
composed together: first get the email address and password from the user, second load the
“user” model from the database and check whether the password matches.</p>
<p>Operations are the doers of the MOVE world. They are responsible for making changes to
your models, for showing the right views at the right time, and for responding to events
triggered by user interactions. In a well factored application, each sub-operation can be
run independently of its parent; which is why in the diagram events flow upwards, and
changes are pushed downwards.</p>
<p>What’s exciting about using operations in this way is that your entire application can
itself be treated as an operation that starts when the program boots. It spawns as many
sub-operations as it needs, where each concurrently existing sub-operation is run in
parallel, and exits the program when they are all complete.</p>
<h1 id="views">Views</h1>
<p>The login screen is a view which is responsible for showing a few text boxes to the user.
When the user clicks the “login” button the view will yield a “loginAttempt” event which
contains the username and password that the user typed.</p>
<p>Everything the user can see or interact with should be powered by a view. They not only
display the state of your application in an understandable way, but also simplify the
stream of incoming user interactions into meaningful events. Importantly views don’t
change models directly, they simply emit events to operations, and wait for changes by
listening to events emitted by the models.</p>
<h1 id="events">Events</h1>
<p>The “loginAttempt” event is emitted by the view when the user clicks login. Additionally,
when the login operation completes, the “currentUser” model will emit an event to notify
your application that it has changed.</p>
<p>Listening on events is what gives MOVE (and MVC) the inversion of control that you need to
allow models to update views without the models being directly aware of which views they
are updating. This is a powerful abstraction technique, allowing components to be coupled
together without interfering with each other.</p>
<h1 id="why-now">Why now?</h1>
<p>I don’t wish to be misunderstood as implying that MVC is bad; it truly has been an
incredibly successful way to structure large applications for the last few decades. Since
it was invented however, new programming techniques have become popular. Without closures
(or anonymous blocks) event binding can be very tedious; and without deferrables (also
known as deferreds or promises) the idea of treating individual operations as objects in
their own right doesn’t make much sense.</p>
<p>To re-iterate: MVC is awesome, but it’s designed with decades old technologies. MOVE is
just a update to make better use of the new tools we have.</p>
<aside>P.S. I'm not the only one beginning to think this way either, if you like
the idea of MOVE you should check out <a href="https://github.com/bitlove/objectify">objectify</a>
and
<a href="http://collectiveidea.com/blog/archives/2012/06/28/wheres-your-business-logic/">interactions</a>
which try to add some of the benefits of MOVE to existing MVC applications. Please <a href="https://twitter.com/conradirwin">let me know</a> if you have other links that should be
here!</aside>
<aside>P.P.S This blog post has been translated into Japanese no fewer than twice:
<a href="http://d.hatena.ne.jp/nowokay/20120704#c">d.hatena.ne.jp</a> and <a href="http://blog.neo.jp/dnblog/index.php?module=Blog&blog=pg&action=CommentPostDo&entry_id=3442">blog.neo.jp</a>, and also into <a href="http://habrahabr.ru/post/147038/">Russian</a>, <a href="http://woonohyo.tistory.com/39">Korean</a> and <a href="http://www.alanchavez.com/mvc-esta-muerto-es-tiempo-de-darle-paso-a-una-alternativa-move/">Spanish</a>. Thanks!</aside>
A quick introduction to Teacup2012-06-15T00:00:00+00:00http://cirw.in//blog/introducing-teacup.html<p><a href="https://github.com/rubymotion/teacup">Teacup</a> is a library for
<a href="http://rubymotion.com/">RubyMotion</a> that let’s you create views and layouts in simple
declarative code. The simplest way to understand it is that it’s “CSS for iOS”, but that
would be to heavily underestimate what it can do. Perhaps a better analogy is “Interface
Builder for RubyMotion”, as both tools solve the same problem.</p>
<h2 id="creating-layouts">Creating layouts</h2>
<p>Once you’ve <a href="https://github.com/rubymotion/teacup#installation">added teacup to your app</a>,
you can get started immediately by creating views in your controller:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">MyViewController</span> <span class="o"><</span> <span class="no">UIViewController</span>
<span class="nb">attr_accessor</span> <span class="ss">:button</span>
<span class="n">layout</span> <span class="k">do</span>
<span class="n">subview</span> <span class="no">UILabel</span><span class="p">,</span>
<span class="ss">text: </span><span class="s2">"Hello World"</span>
<span class="nb">self</span><span class="p">.</span><span class="nf">button</span> <span class="o">=</span> <span class="n">subview</span><span class="p">(</span>
<span class="no">UIButton</span><span class="p">.</span><span class="nf">buttonWithType</span><span class="p">(</span><span class="no">UIButtonTypeCustom</span><span class="p">),</span>
<span class="ss">title: </span><span class="s2">"Click me!"</span>
<span class="p">)</span>
<span class="k">end</span>
<span class="k">end</span></code></pre></figure>
<p>Now, whenever <code class="language-plaintext highlighter-rouge">MyViewController</code> is shown, it will contain both a label and a button.
You’ll also notice that I’ve stashed the button away on <code class="language-plaintext highlighter-rouge">self.button</code> so that I can refer
to it later in the controller. I won’t need to use the label in my code, so I can just
rely on the view heirarchy to retain it as necessary.</p>
<aside>The `subview` method is actually nestable, so if I wanted to I could put
`subview(MyMenuBar){ subview(MyButton1) }` to put a button into a menu. This can come in
handy when you need detailed structures, though in some cases it may be clearer to
encapsulate complicated structures in a `UIView` subclass. For this reason, Teacup's
`layout` method is available not only on `UIViewController` but also `UIView`.</aside>
<h2 id="making-them-pretty">Making them pretty</h2>
<p>Unfortunately the code in the previous section had a bit of a flaw; when you run it the
label and the button don’t actually appear. This is because Cocoa defaults all elements to
zero width and zero height, and is really easy to fix:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="k">class</span> <span class="nc">MyViewController</span> <span class="o"><</span> <span class="no">UIViewController</span>
<span class="nb">attr_accessor</span> <span class="ss">:button</span>
<span class="n">layout</span> <span class="k">do</span>
<span class="n">subview</span><span class="p">(</span><span class="no">UILabel</span><span class="p">,</span>
<span class="ss">text: </span><span class="s2">"Hello World"</span><span class="p">,</span>
<span class="ss">top: </span><span class="mi">60</span><span class="p">,</span> <span class="ss">left: </span><span class="mi">60</span><span class="p">,</span>
<span class="ss">width: </span><span class="mi">200</span><span class="p">,</span> <span class="ss">height: </span><span class="mi">100</span><span class="p">,</span>
<span class="ss">backgroundColor: </span><span class="no">UIColor</span><span class="p">.</span><span class="nf">blueColor</span>
<span class="p">)</span>
<span class="nb">self</span><span class="p">.</span><span class="nf">button</span> <span class="o">=</span> <span class="n">subview</span><span class="p">(</span>
<span class="no">UIButton</span><span class="p">.</span><span class="nf">buttonWithType</span><span class="p">(</span><span class="no">UIButtonTypeCustom</span><span class="p">),</span>
<span class="ss">title: </span><span class="s2">"Click me!"</span><span class="p">,</span>
<span class="ss">top: </span><span class="mi">200</span><span class="p">,</span> <span class="ss">left: </span><span class="mi">60</span><span class="p">,</span>
<span class="ss">width: </span><span class="mi">200</span><span class="p">,</span> <span class="ss">height: </span><span class="mi">100</span>
<span class="p">)</span>
<span class="k">end</span>
<span class="k">end</span></code></pre></figure>
<p>Again this hopefully stating the obvious, but I should now have a blue label a short
distance from the top of the screen and a button just underneath that. Both of them are
60px from the left and 200px wide so that they appear centered.</p>
<aside>Any Cocoa view property that supports key-value coding can be set in this manner,
you can even set up the `delegate` of your button if you'd like. We also support setting
the properties of the view's layers, you just add add a sub-hash:
`layer: { cornerRadius: 10 }`.</aside>
<h2 id="stylesheets">Stylesheets</h2>
<p>While the code in the previous section works just fine, it’s somewhat ugly on two fronts.
The most obvious issue is that if I want to change the left margin I have to do that in
multiple places, but also my controller is being filled with irrelevant details. It really
doesn’t matter what size the button has, from a controller’s point of view, that’s a
view-level concern.</p>
<p>To solve these problems teacup provides you with stylesheets:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># app/controllers/my_view_controller.rb</span>
<span class="k">class</span> <span class="nc">MyViewController</span> <span class="o"><</span> <span class="no">UIViewController</span>
<span class="nb">attr_accessor</span> <span class="ss">:button</span>
<span class="n">stylesheet</span> <span class="ss">:iphone</span>
<span class="n">layout</span> <span class="k">do</span>
<span class="n">subview</span><span class="p">(</span><span class="no">UILabel</span><span class="p">,</span> <span class="ss">:hello_world</span><span class="p">)</span>
<span class="nb">self</span><span class="p">.</span><span class="nf">button</span> <span class="o">=</span> <span class="n">subview</span><span class="p">(</span><span class="no">UIButton</span><span class="p">,</span> <span class="ss">:click_me</span><span class="p">)</span>
<span class="k">end</span>
<span class="k">end</span></code></pre></figure>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># style/iphone.rb</span>
<span class="no">Teacup</span><span class="o">::</span><span class="no">Stylesheet</span><span class="p">.</span><span class="nf">new</span> <span class="ss">:iphone</span> <span class="k">do</span>
<span class="n">style</span> <span class="ss">:widget</span><span class="p">,</span>
<span class="ss">left: </span><span class="mi">60</span><span class="p">,</span>
<span class="ss">width: </span><span class="mi">200</span><span class="p">,</span>
<span class="ss">height: </span><span class="mi">100</span>
<span class="n">style</span> <span class="ss">:hello_world</span><span class="p">,</span> <span class="ss">extends: :widget</span><span class="p">,</span>
<span class="ss">text: </span><span class="s2">"Hello World"</span><span class="p">,</span>
<span class="ss">top: </span><span class="mi">60</span><span class="p">,</span>
<span class="ss">backgroundColor: </span><span class="no">UIColor</span><span class="p">.</span><span class="nf">blueColor</span>
<span class="n">style</span> <span class="ss">:click_me</span><span class="p">,</span> <span class="ss">extends: :widget</span><span class="p">,</span>
<span class="ss">title: </span><span class="s2">"Click me!"</span><span class="p">,</span>
<span class="ss">top: </span><span class="mi">200</span>
<span class="k">end</span></code></pre></figure>
<p>This new code solves both of the code structure problems; the nitty-gritty of making the
view look right is no-longer polluting the controller, and the left-margin is only
specified in one place due to use of the <code class="language-plaintext highlighter-rouge">extends:</code> meta-property.</p>
<aside>If you're coming from a web-development background it might surprise you that we
put the text into the stylesheet too. This actually makes sense because the text on the
button doesn't matter at all to the controller but it makes a lot of difference to how
the app looks. In the HTML world we're just stuck the wrong way around due to abusing a
markup language to build apps :).</aside>
<h2 id="further-reading">Further reading</h2>
<p>This blog post has just scratched the surface of what’s available in teacup. To get full
information you should read the API docs for
<a href="http://rdoc.info/github/rubymotion/teacup/master/Teacup/Stylesheet">Stylesheets</a> and for
the <a href="http://rdoc.info/github/rubymotion/teacup/master/Teacup/Layout">layout function</a>.</p>
<p>To get the example code created in this blog post you can clone <a href="https://github.com/ConradIrwin/introducing-teacup">the git
repository</a>. Other example uses of
teacup can be found in <a href="https://github.com/rubymotion/teacup/tree/master/app">the sample
app</a> that’s included with teacup
itself, and <a href="https://github.com/ConradIrwin/Commune">the Commune app</a> which is where some
of the initial experiments were done.</p>
<p>If you are having problems or want to help us improve teacup, please join in on
<a href="https://github.com/rubymotion/teacup">GitHub</a> or in
<a href="irc://irc.freenode.net#teacuprb">#teacuprb</a> on Freenode.</p>
adding context to a shared git repository2012-06-08T00:00:00+00:00http://cirw.in//blog/git-aliae-3.html<p>At <a href="https://rapportive.com/">Rapportive</a> we use git extensively for its powerful
branching and merging capabilities. The workflow we use is very similar to that
<a href="http://scottchacon.com/2011/08/31/github-flow.html">used by GitHub</a>: everything
in master is deployed, everything else is in branches based off master. We’re
also using <a href="https://heroku.com/">Heroku</a>’s <code class="language-plaintext highlighter-rouge">git push</code> deployment model, so git
is the canonical source of information about which code is where.</p>
<p>In order to make this easier to work with we’ve adopted two simple conventions
to add extra context to the information already stored in git. These help us
understand what’s going on in the repository quickly, which leads to fewer
mistakes when deploying, and lessens the need to interrupt other people just to
find out what they’ve been doing.</p>
<h2 id="commit-prefixes">Commit prefixes</h2>
<p>Not all commits are equal, and when we create one that makes a particularly
scary change we add a short, loud marker to the commit message. For example:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">[MIG]</code> — This commit introduces a database migration.</li>
<li><code class="language-plaintext highlighter-rouge">[ENV]</code> — This commit requires an environment variable to be set.</li>
<li><code class="language-plaintext highlighter-rouge">[GEM]</code> — This commit adds or alters a gem dependency.</li>
<li><code class="language-plaintext highlighter-rouge">[TEMP]</code> — This commit is a hot-fix that will only be needed for a short time.</li>
</ul>
<p>Providing everyone does this when such a commit is created, it’s easy to scan
down the git log and spot which commits are likely to cause problems. This is
useful both when deploying, to ensure that you don’t break everything; and also
when fetching changes from GitHub before starting to work on something new.</p>
<aside>We try to ensure that [MIG] commits contain only database migrations, and
no code changes. This means that we can deploy database migrations with little
downtime by first pushing out only the [MIG] commit, then running the database
migration, and finally push out the code changes.</aside>
<h2 id="git-undeployed">git-undeployed</h2>
<p>The convention of prefixing works no-matter which tool you use to view git logs.
Just before deploying however, I run <code class="language-plaintext highlighter-rouge">git undeployed</code>. It shows me all the
commits that differ between production, GitHub, and my local master:</p>
<div class="highlight"><pre style="white-space: normal;"><code clas="ruby" style="white-space: normal">
<span class="f4">/0/rapportive</span><span class="f3">[master]</span> $ git undeployed
<br />* <span class="f2">583adaf <span class="f1">Sam<span class="f4"> (prod/master) </span></span></span>[TEMP] No queueing
<br />| * <span class="f2">7e7c8bc <span class="f1">Conrad<span class="f4"> (master) </span></span></span> Moar caching!
<br />| * <span class="f2">88e2cf5 <span class="f1">Conrad<span class="f4"> </span></span></span>[ENV] Configure redis
<br />|/
<br />* <span class="f2">05a2e01 <span class="f1">Martin<span class="f4"> (github/master) </span></span></span>Use .present?
</code></pre></div>
<p>This (fictitious) output tells me quickly what I need to do in order to deploy,
namely:</p>
<ol>
<li>Check with Sam to find out what’s going on with the queues.</li>
<li>Push my changes to GitHub (always done before pushing to production).</li>
<li>Add the new redis configuration to the production environment.</li>
<li>Push my changes to production.</li>
</ol>
<p>We also have an internal deploy script that wraps <code class="language-plaintext highlighter-rouge">git undeployed</code> and
<code class="language-plaintext highlighter-rouge">git push</code>, and which detects these prefixes. It then asks the user for
confirmation before letting the push go through, which can be useful when
deploying in a hurry!</p>
<aside>Under the hood: `git undeployed` is powered by
[`git plog`](https://github.com/ConradIrwin/git-aliae/blob/master/wip/git-plog),
my `git log` wrapper. The main advantages of `git plog` are that it shows the
commit graph, uses pretty colours, and shows the first line of each commit
message.</aside>
<h2 id="branch-prefixes">Branch prefixes</h2>
<p>The other convention alluded to in the introductory section is branch prefixes.
In order that we can keep track of what state everything is in, we group our
branches into meaningful categories:</p>
<ul>
<li><code class="language-plaintext highlighter-rouge">wip.</code> — A feature or bugfix that someone is working on right now.</li>
<li><code class="language-plaintext highlighter-rouge">review.</code> — A feature or bugfix waiting on a second pair of eyes before
it gets deployed.</li>
<li><code class="language-plaintext highlighter-rouge">experiment.</code> — A cool hack being worked on, that probably won’t go into
production in the near future.</li>
<li><code class="language-plaintext highlighter-rouge">shelf.</code> — All the old useful bits of code we didn’t get round to finishing,
but don’t want to throw away.</li>
</ul>
<p>After the prefix comes a short descriptive name, so we end up with branches
called things like <code class="language-plaintext highlighter-rouge">wip.cache-robots-txt</code>, or <code class="language-plaintext highlighter-rouge">shelf.debug-console</code>. This means
that it’s really easy to see at a glance both what code branches contain, and
also what state different branches are in. The <code class="language-plaintext highlighter-rouge">shelf.</code> prefix is particularly
useful for automatically removing irrelevant branches from git’s output.</p>
<h2 id="git-happening">git-happening</h2>
<p>Just like commit prefixes, branch prefixes are useful no matter what tools you
are using to interact with git as they give you extra context with no need to
shell out to a different tool. That said they enable one very useful ability
which is not present in vanilla git (though it is on
<a href="https://github.com/blog/611-branch-lists">GitHub</a>), and that is seeing the
current status of all your branches:</p>
<div class="highlight"><pre style="white-space: normal;"><code clas="ruby" style="white-space: normal">
* <span class="f1">Conrad</span> (<span class="f5">master</span>) 28 hours ago
<br />* <span class="f1">Conrad</span> (<span class="f5">review.html-escape</span>) 2 days ago
<br />* <span class="f1">Martin</span> (<span class="f2">wip.cache-expiry</span>) 30 minutes ago
<br />* <span class="f1">Lee</span> (<span class="f2">wip.hi-res-photos</span>) 4 hours ago
<br />* <span class="f1">Conrad</span> (<span class="f2">wip.hover-intent</span>) 2 months ago
</code></pre></div>
<p>This very quickly shows you who is working on what, and when they last touched
it. As it excludes shelf branches it doesn’t matter that we keep a whole load of
old stuff around, because it will never show up.</p>
<p>It also shows you other house-keeping data about the branches. In the given
example, I need to delete the <code class="language-plaintext highlighter-rouge">review.html-escape</code> branch from GitHub, because
it has been merged into master. I’ll also consider renaming <code class="language-plaintext highlighter-rouge">wip.hover-intent</code>
to <code class="language-plaintext highlighter-rouge">shelf.hover-intent</code>; because clearly no-one is working on it any more.</p>
<h2 id="installation">Installation</h2>
<p>In order to use branch prefixes and commit prefixes, you don’t have to install
anything, just get into the habit. It takes very little extra time, and makes it
much easier to see what’s going on in your repository at a glance.</p>
<p>In order to get <code class="language-plaintext highlighter-rouge">git happening</code> and <code class="language-plaintext highlighter-rouge">git undeployed</code>, and a host of other useful
<a href="https://github.com/ConradIrwin/git-aliae">git aliae</a>:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">git clone https://github.com/ConradIrwin/git-aliae
<span class="c"># Add the following line to your ~/.bashrc</span>
<span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="nv">$PATH</span>:/path/to/git-aliae/bin</code></pre></figure>
<p>Please report bugs and feature requests to <a href="https://github.com/ConradIrwin/git-aliae/issues">GitHub
issues</a>.</p>
How to program like an explorer (with Pry!).2012-06-01T00:00:00+00:00http://cirw.in//blog/explore-with-pry.html<aside>I'm one of the core committers to the [Pry REPL](http://pry.github.com/). Talking about this at
work a few weeks ago, a colleague asked me: "Why should I use pry? I mean, I
know it's better, but what's it for?". This is a somewhat long-winded attempt to
answer that question.</aside>
<p>Exploring is a large part of what programmers do during the time when we’re not
typing out code. Attempting to discover the correct way to do something, or to
get a feeling for how something works is an essential part of the job, and for
many people it’s also the most fun.</p>
<p>While these aren’t the only examples, I classify the following as exploring:</p>
<ol>
<li>Trying out new libraries.</li>
<li>Designing good APIs.</li>
<li>Debugging existing programs.</li>
<li>Exploring data sets.</li>
</ol>
<p>There are several passive ways to solve these tasks. You can try Google, and see
if someone else has blogged about the problem, or try reading lots of existing
code or documentation in the hope that inspiration strikes. A more active
approach however is to write some code.</p>
<h2 id="exploring-with-code">Exploring with code</h2>
<p>Writing code to explore problem domains is the best way to get tangible
feedback. If you’re designing an API, but don’t try using it, your API will not
be very good. If you’re trying to learn a new library, but don’t actually use
it, you’ll not gain much. Finally, if you are trying to debug without writing
code; you are trying to emulate an entire computer with your mind, which is
pretty tiring.</p>
<p>The code you write while exploring will be different from the code you write
when building applications. Instead of the aim being an application you can
deploy, the aim is to improve your mental model. This in turn means that you
need to treat code differently: good exploratory code is designed to be written
quickly, run once, and to give you plenty of output that you can understand what
happened. It’s expected to be buggy, and you’re expected to just keep adding
hacks until it works.</p>
<aside>Obviously, application code is optimized in completely the other
direction. It should be written thoroughly as it is run and read many times, it
should also be reasonably free of hacks, and output only a small amount of
critical information.</aside>
<h2 id="programming-in-a-repl">Programming in a REPL</h2>
<p>Read-evaluate-print loops are an invaluable tool for exploratory coding. They
have features that are so obvious to enable this that you probably didn’t notice
them before:</p>
<ol>
<li>Intermediate values generated are always displayed.</li>
<li>Running programs can be inspected in arbitrary detail.</li>
<li>You can always decide which line of code to execute next.</li>
</ol>
<p>Contrast this to a normal development cycle of using a text-editor and then
running the program from the start. In that process the computer mindlessly
re-evaluates the entire program, dumps out a tiny amount of information at any
<code class="language-plaintext highlighter-rouge">print</code> statements you’ve inserted, and then exits, throwing away the entire
state.</p>
<h2 id="using-pry-as-a-repl">Using Pry as a REPL</h2>
<p>Pry is a REPL designed with these features in mind. Taking inspiration from Smalltalk and
SLIME, it embraces the idea of exploratory programming and helps you to do it more
effectively. While it’d take me too long to cover <a href="https://github.com/pry/pry/wiki">all of its
features</a>, here are the two I consider most important:</p>
<figure><h3>`ls`</h3>
<div class="highlight"><pre style="white-space: normal;"><code clas="ruby" style="white-space: normal">
[1] pry(main)> ls <span class="bold"><span class="f4 underline">CodeRay</span></span>
<br /><span class="bold">constants</span>: CODERAY_PATH <span class="f3">Duo</span> <span class="f4">Encoders</span> <span class="f3">FileType</span> <span class="f3">GZip</span> <span class="f4">Plugin</span> <span class="f4">PluginHost</span> <span class="f4">Scanners</span> <span class="f3">Styles</span> <span class="f3">TokenKinds</span> <span class="f4">Tokens</span> <span class="f4">TokensProxy</span> VERSION <span class="f4">WordList</span>
<br /><span class="bold">CodeRay.methods</span>: coderay_path encode encode_file encode_tokens encoder get_scanner_options highlight highlight_file scan scan_file scanner
</code></pre></div>
</figure>
<p>If you’ve ever wondered what a given object can do, the
<a href="https://github.com/pry/pry/wiki/State-navigation#wiki-Ls"><code class="language-plaintext highlighter-rouge">ls</code></a> command will
help you. Additionally, and along with the
<a href="https://github.com/pry/pry/wiki/State-navigation#wiki-Find_method"><code class="language-plaintext highlighter-rouge">find-method</code></a>
command, it can also answer questions like “How do I use this API to achieve X?”.</p>
<figure><h3>`show-source`</h3>
<div class="highlight"><pre style="white-space: normal;"><code clas="ruby" style="white-space: normal">
[2] pry(main)> $ binding.pry
<br /><span class="bold"><span class="f1">def</span></span> <span class="bold"><span class="f4">pry</span></span>(*args)
<br /> <span class="bold"><span class="f1">if</span></span> args.first.is_a?(<span class="bold"><span class="f4"><span class="underline">Hash</span></span></span>) || args.length == <span class="bold"><span class="f4">0</span></span>
<br /> args.unshift(<span class="bold"><span class="f6">self</span></span>)
<br /> <span class="bold"><span class="f1">end</span></span>
<br />
<br /> <span class="bold"><span class="f4"><span class="underline">Pry</span></span></span>.start(*args)
<br /><span class="bold"><span class="f1">end</span></span>
</code></pre></div>
</figure>
<p>The
<a href="https://github.com/pry/pry/wiki/Source-browsing#wiki-Show_method"><code class="language-plaintext highlighter-rouge">show-source</code></a>
command, aliased to <code class="language-plaintext highlighter-rouge">$</code>, allows you to see how something is implemented. This is
vital both for debugging, and also for exploring new libraries. The
<a href="https://github.com/pry/pry/wiki/Editor-integration#wiki-Edit_method"><code class="language-plaintext highlighter-rouge">edit-method</code></a>
command can be used in combination to fix bugs you spot on the fly.</p>
<aside>You'll notice in both of the screenshots that Pry loves colours. They're
used in the `ls` command to distinguish different kinds of constant (classes are
blue, exceptions are pink, and those pending autoload are yellow); and anywhere that
code is displayed, including old prompts, to enhance readability.</aside>
<h2 id="summary">Summary</h2>
<p>Acknowledging the existence of temporary exploratory code as distinct from
permanent application code has huge benefits. When you’re comfortable with
writing code that will be immediately thrown away, you can iterate purposefully
to find solutions instead of relying on google and inspiration.</p>
<p>A REPL is the best tool to help you do this. Unlike your text editor which is
designed for writing permanent robust code, a REPL is designed to help you write
temporary code to quickly understand problem domains. Exploration tasks where
this is most helpful include learning new libraries, designing APIs, debugging,
data analysis, smoke testing, etc.</p>
<p>Pry is a world-class REPL. It’s written in Ruby, and due to its extensive
wrapping of Ruby’s introspection APIs excels for exploring in Ruby. Due to the
JVM’s homogeneous object model and JRuby we’re also beginning to see Pry used
as an exploration tool for non-ruby
projects<sup><a href="https://wiki.jenkins-ci.org/display/JENKINS/Pry+Plugin">1</a></sup>.</p>
<p>And so that is why you should use <a href="http://pry.github.com">Pry</a> :).</p>
git aliae so that you never lose work (part 2)2012-05-26T00:00:00+00:00http://cirw.in//blog/git-aliae-2.html<p>Git is an incredibly powerful tool for version control. Much of this power stems
from its underlying append-only object database which ensures that once you’ve
made a commit it can never be changed or unmade. This is great because it means
you can <a href="http://cirw.in/blog/git-aliae-1">refactor history</a> safe in the
knowledge that you can <code class="language-plaintext highlighter-rouge">git reset</code> back to a working version if something goes
wrong.</p>
<p>One thing I’ve yearned for however is the same functionality for uncommitted
changes. Wouldn’t it be great if every time git modified your working tree, it
took a backup?</p>
<h2 id="dangerous-git-commands">Dangerous git commands</h2>
<p>Luckily the number of git commands that actually modify the working tree is
small, in fact there are only three commands that you’ll usually come across:</p>
<ol>
<li><code class="language-plaintext highlighter-rouge">git checkout</code> (with <code class="language-plaintext highlighter-rouge">-f</code>, or with a filename)</li>
<li><code class="language-plaintext highlighter-rouge">git reset --hard</code></li>
<li><code class="language-plaintext highlighter-rouge">git clean -f</code></li>
</ol>
<p>If you’ve used git for a significant length of time, and are not some kind of
super-hero, then I can guarantee that you’ll have lost work with each of these.</p>
<p>It was after one particularly badly timed <code class="language-plaintext highlighter-rouge">git checkout -f</code> that I finally decided
that something needed to be done. While retyping out the hours of code that I’d
accidentally deleted I came up with a plan: Every time I wanted to do a
<code class="language-plaintext highlighter-rouge">git checkout -f</code> I’d first store a copy of my working tree into the object
database. Then whenever I realise that I’ve thrown away the wrong changes, I
can recover them.</p>
<aside>Under the hood: In order that the size of your repository doesn't grow
larger forever git does occasionally run a garbage collector over the object
database. This will delete unused things (like backups) which are over two weeks
old.</aside>
<h2 id="git-cof--git-foc">git-cof && git-foc</h2>
<p>To this end I wrote <code class="language-plaintext highlighter-rouge">git cof</code>. All it does is take a backup of the working
tree, and then forward any arguments on to <nobr>`git checkout -f`</nobr>. To
facilitate undoing this, I also wrote <code class="language-plaintext highlighter-rouge">git foc</code> (the name is intentionally
evocative of the expletive I no longer need to use).</p>
<p><code class="language-plaintext highlighter-rouge">git cof</code> can be used as a drop-in replacement for all uses of <code class="language-plaintext highlighter-rouge">git checkout</code>,
(excepting <code class="language-plaintext highlighter-rouge">-m</code> and <code class="language-plaintext highlighter-rouge">-p</code> because those flags are incompatible with <code class="language-plaintext highlighter-rouge">-f</code>). This
means that if you use it when changing branch, or when checking out a particular
file, you’ll also get a backup of your unsaved changes.</p>
<p><code class="language-plaintext highlighter-rouge">git foc</code> just automates the restore process. It finds the latest backup commit
made by <code class="language-plaintext highlighter-rouge">git cof</code>, and re-instates any changes that <code class="language-plaintext highlighter-rouge">git cof</code> removed. You do
have to be somewhat careful with <code class="language-plaintext highlighter-rouge">git foc</code> as if you make conflicting changes
between running <code class="language-plaintext highlighter-rouge">git cof</code> and <code class="language-plaintext highlighter-rouge">git foc</code>, you’ll end up with a merge conflict.</p>
<p>Although <code class="language-plaintext highlighter-rouge">git foc</code> only allows you to restore the most recent backup, all the
other backups are also preserved for at least two weeks. If you need them back
you can <code class="language-plaintext highlighter-rouge">tail .git/tree_backups</code> and use normal git commands to reinstate
changes from those commits.</p>
<aside>The observant reader will notice that `git stash` can be used as a
poor-man's replacement for `git cof` and `git foc`. I find it useful to separate
out the two commands so that I don't have to worry about filling up `git stash
list` with rubbish that I most likely will never need again.</aside>
<h2 id="git-reset-keep">git reset –keep</h2>
<p>While I was considering writing an equivalent script to wrap <code class="language-plaintext highlighter-rouge">git reset --hard</code>
I discovered <code class="language-plaintext highlighter-rouge">git reset --keep</code>. This mode of <code class="language-plaintext highlighter-rouge">git reset</code> was added in
git version 1.7.1, and is exactly like <code class="language-plaintext highlighter-rouge">git reset --hard</code> except that it
preserves any uncommitted changes in the working tree.</p>
<p>Concretely that means that it makes your current branch point to the commit you
specify, and then it re-applies all of your uncommitted changes. If it can’t do
this properly, then it will abort and tell you what went wrong.</p>
<p>This means that there’s now no reason to use <code class="language-plaintext highlighter-rouge">git reset --hard</code> ever. You can
always use <code class="language-plaintext highlighter-rouge">git reset --keep</code>. In the rare cases that it aborts because you have
uncommitted changes that conflict with the reset, you can use <code class="language-plaintext highlighter-rouge">git cof</code> to throw
away your local changes in a safe way, and then retry.</p>
<aside>If your version of git is too old, it's actually very easy to upgrade.
See [the git website](http://git-scm.com/) for details.</aside>
<h2 id="preserving-untracked-files">Preserving untracked files</h2>
<p>One thing that <code class="language-plaintext highlighter-rouge">git cof</code> doesn’t do is preserve files that are untracked (i.e.
you haven’t yet <code class="language-plaintext highlighter-rouge">git add</code>ed them). This is for consistency with most git commands
which refuse to touch untracked files; and also to ensure that it doesn’t
accidentally add a large number of useless files to your git object database.</p>
<p>This means that <code class="language-plaintext highlighter-rouge">git cof</code> doesn’t help avoid the data-loss caused by
<code class="language-plaintext highlighter-rouge">git clean -f</code> yet. I’ve not implemented a solution that does and instead just
avoid using <code class="language-plaintext highlighter-rouge">git clean</code> at all. Instead I use <code class="language-plaintext highlighter-rouge">rm</code> manually as I find that
copying and pasting the list of files to remove one-by-one makes me think a
little harder about whether I actually want to delete it.</p>
<h2 id="summary">Summary</h2>
<p>Internalising three things can thus help you avoid losing most work with git:</p>
<ol>
<li>Use <code class="language-plaintext highlighter-rouge">git cof</code> instead of <code class="language-plaintext highlighter-rouge">git checkout</code></li>
<li>Use <code class="language-plaintext highlighter-rouge">git reset --keep</code> instead of <code class="language-plaintext highlighter-rouge">git reset --hard</code></li>
<li>Use <code class="language-plaintext highlighter-rouge">rm</code> instead of <code class="language-plaintext highlighter-rouge">git clean -f</code></li>
</ol>
<p>I’ve found that these rules have saved me a considerable amount of time that
would otherwise be wasted re-writing lost code.</p>
<p>To install git aliae:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">git clone https://github.com/ConradIrwin/git-aliae
<span class="c"># Add the following line to your ~/.bashrc</span>
<span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="nv">$PATH</span>:/path/to/git-aliae/bin</code></pre></figure>
<p>Please report bugs and feature requests to <a href="https://github.com/ConradIrwin/git-aliae/issues">GitHub
issues</a>.</p>
<aside>If you've already installed the git aliae mentioned in [part
one](http://cirw.in/blog/git-aliae-1), you can just `git pull` to get the latest
changes. See the [README](https://github.com/ConradIrwin/git-aliae) for
more.</aside>
ampex — a practical use of Ruby's & operator2012-05-19T00:00:00+00:00http://cirw.in//blog/ampex.html<p>Ruby is renowned for both its readability and its flexibility. The ultimate
goal of every Ruby program is to work well while appearing as simple as possible.</p>
<p>To achieve this as a Ruby programmer, you’re encouraged to push a lot of the
fiddly bits of code deep into parts of your program where a casual reader of
the source can ignore them.</p>
<p>Out of the box Ruby ships with some very powerful tools to help you do this, the
most famous of which is its syntax for custom blocks. This allows you to re-use
existing fiddly code (for example iterating over a list) but to insert a little
bit of customisation (so now you can iterate over a list doubling as you go).</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">].</span><span class="nf">map</span><span class="p">{</span> <span class="o">|</span><span class="n">i</span><span class="o">|</span> <span class="n">i</span> <span class="o">*</span> <span class="mi">2</span> <span class="p">}</span>
<span class="o">=></span> <span class="p">[</span><span class="mi">2</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">6</span><span class="p">]</span></code></pre></figure>
<h2 id="the--operator">The & operator</h2>
<p>Blocks are only the beginning of this ability as Ruby has the <code class="language-plaintext highlighter-rouge">&</code> operator which
can be used to “cast” any object to a block. This behaviour works out-of-the-box
on Procs, Methods, and Symbols.</p>
<p>You will have seen the Proc support in action a lot, because that’s
how you pass <code class="language-plaintext highlighter-rouge">&block</code> from one function to the next. Method objects are rarely
used in Ruby, though sometimes inserting <code class="language-plaintext highlighter-rouge">.tap(&method(:puts))</code> is a useful way
to debug an object in the middle of an expression.</p>
<p>The most interesting example of <code class="language-plaintext highlighter-rouge">&</code> however is on the Symbol class. This was
ported to the core Ruby language in version 1.8.7 because it was so popular
with users of the libraries that implemented it (the <a href="http://extensions.rubyforge.org/rdoc/index.html">Ruby Extensions
Project</a> and
<a href="http://apidock.com/rails/v1.1.1/Symbol/to_proc">ActiveSupport</a>).</p>
<p>The whole purpose of using <code class="language-plaintext highlighter-rouge">&</code> with a symbol is to generate more readable code,
compare:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="p">[</span><span class="s2">"1"</span><span class="p">,</span> <span class="s2">"2"</span><span class="p">,</span> <span class="s2">"3"</span><span class="p">].</span><span class="nf">map</span><span class="p">{</span> <span class="o">|</span><span class="n">string</span><span class="o">|</span> <span class="n">string</span><span class="p">.</span><span class="nf">to_i</span> <span class="p">}</span>
<span class="o">=></span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>
<span class="p">[</span><span class="s2">"1"</span><span class="p">,</span> <span class="s2">"2"</span><span class="p">,</span> <span class="s2">"3"</span><span class="p">].</span><span class="nf">map</span><span class="p">(</span><span class="o">&</span><span class="ss">:to_i</span><span class="p">)</span>
<span class="o">=></span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span></code></pre></figure>
<figure>
The version with the symbol has two benefits:
1. There are fewer punctuation characters.
2. You don't need to introduce a temporary name for a variable.
</figure>
<p>This second point is the one that has the biggest impact on people reading your
code. The mental machinery that programmers use to track variables is
necessarily hefty, so if they don’t need to invoke it so often they will find
that your code takes less effort to understand.</p>
<aside>Under the hood: The `&` operator is actually not as 'magic' as it might
appear when you first begin using it. All it does is call `.to_proc` on the
object. The above example works equivalently to `block = (:to_i).to_proc`,
followed by `["1", "2", "3"].map(&block)`</aside>
<h2 id="x-itself">&X itself</h2>
<p>The <a href="https://github.com/rapportive-oss/ampex">ampex</a> library takes the idea from
<code class="language-plaintext highlighter-rouge">&:symbol</code>, and adds a little more flexibility. This means that you can get all
the punctuation-free, variable-free goodness, but more often!</p>
<figure>
A few examples of how cool this can be:
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># when you want to pass an argument to a method</span>
<span class="p">[</span><span class="mi">10</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">12</span><span class="p">].</span><span class="nf">map</span><span class="p">(</span><span class="o">&</span><span class="no">X</span><span class="p">.</span><span class="nf">to_s</span><span class="p">(</span><span class="mi">16</span><span class="p">))</span>
<span class="o">=></span> <span class="p">[</span><span class="s2">"a"</span><span class="p">,</span> <span class="s2">"b"</span><span class="p">,</span> <span class="s2">"c"</span><span class="p">]</span></code></pre></figure>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># when you want to parse some JSON</span>
<span class="n">owners</span> <span class="o">=</span> <span class="p">[{</span><span class="s1">'name'</span> <span class="o">=></span> <span class="s1">'Fred'</span><span class="p">,</span> <span class="s1">'dog'</span> <span class="o">=></span> <span class="s1">'Fido'</span><span class="p">},</span>
<span class="p">{</span><span class="s1">'name'</span> <span class="o">=></span> <span class="s1">'Ron'</span><span class="p">,</span> <span class="s1">'dog'</span> <span class="o">=></span> <span class="s1">'Rex'</span><span class="p">}];</span>
<span class="n">owners</span><span class="p">.</span><span class="nf">map</span><span class="p">(</span><span class="o">&</span><span class="no">X</span><span class="p">[</span><span class="s1">'name'</span><span class="p">])</span>
<span class="o">=></span> <span class="p">[</span><span class="s2">"Fred"</span><span class="p">,</span> <span class="s2">"Ron"</span><span class="p">]</span></code></pre></figure>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="c1"># when you want to chain some method calls</span>
<span class="s2">"alpha</span><span class="se">\n</span><span class="s2">beta</span><span class="se">\n</span><span class="s2">gamma</span><span class="se">\n</span><span class="s2">"</span><span class="p">.</span><span class="nf">lines</span><span class="p">.</span><span class="nf">map</span><span class="p">(</span><span class="o">&</span><span class="no">X</span><span class="p">.</span><span class="nf">strip</span><span class="p">.</span><span class="nf">upcase</span><span class="p">)</span>
<span class="o">=></span> <span class="p">[</span><span class="s2">"ALPHA"</span><span class="p">,</span> <span class="s2">"BETA"</span><span class="p">,</span> <span class="s2">"GAMMA"</span><span class="p">]</span></code></pre></figure>
</figure>
<p>This last example gives you something similar to the new
<a href="http://blog.railsware.com/2012/03/13/ruby-2-0-enumerablelazy/"><code class="language-plaintext highlighter-rouge">Enumerable::Lazy</code></a> module
added in Ruby 2.0; but without having to wait for that to be released. If you’re
interested in more that ampex can help you with, the
<a href="https://github.com/rapportive-oss/ampex">README</a> contains a few more examples.</p>
<aside>While I think the benefits of this are obvious, when ampex was mentioned
in [#ruby-lang](irc://irc.freenode.net/#ruby-lang), it elicited the response
from [ZenSpider](http://irclog.whitequark.org/ruby-lang/2011-12-23#1324608192;):
"honestly... if someone used that in production on one of my systems, I'd fire
them on the spot" (Your-Mileage/Manager-May-Vary)</aside>
<h2 id="installation">Installation</h2>
<p>The <a href="https://github.com/rapportive-oss/ampex">ampex</a> library is distributed as a
<a href="https://rubygems.org/gems/ampex">rubygem</a>, so to use it, you can either install
it one-off:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span class="nv">$ </span>gem <span class="nb">install </span>ampex</code></pre></figure>
<p>Or add it to your <code class="language-plaintext highlighter-rouge">Gemfile</code>.</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="n">source</span> <span class="ss">:rubygems</span>
<span class="n">gem</span> <span class="s1">'ampex'</span></code></pre></figure>
<p>We’ve been using ampex in production for over a year now, and beacuse it’s
written in pure Ruby, it works on Ruby 1.8.7, Ruby 1.9 and JRuby out of the
box.</p>
<h2 id="further-thinking">Further Thinking</h2>
<p>While ampex helps a lot, there are still cases where you need to introduce a
temporary variable unnecessarily. As mentioned above, for some of these cases
you can use <code class="language-plaintext highlighter-rouge">&method(:foo)</code>; but I find that that code makes me think even
harder than the equivalent block version.</p>
<p>I would really love to see something like Scala’s
<a href="http://books.google.com/books?id=MFjNhTjeQKkC&pg=PA146">underscore</a> in Ruby itself. There
have been a few attempts at this, mostly catalogued in Reg Braithwaite’s comprehensive
guide to <a href="https://github.com/raganwald/homoiconic/blob/master/2012/05/anaphora.md#anaphora-in-ruby-2012-edition">Anaphora in
Ruby</a>,
for example <a href="https://github.com/danielribeiro/RubyUnderscore">RubyUnderscore</a> adds it to
Ruby 1.8.7 by syntax rewriting and <a href="https://gist.github.com/1224361">this patch</a> adds it
to Rubinius, but none are yet ready to actually be used.</p>
<p>Particularly I think it should be possible with some ingenuity to come up with
a solution that covers another 90% of the things you want to do. For example,
with pure Ruby and a little cunning, the following could be made to work:</p>
<figure class="highlight"><pre><code class="language-ruby" data-lang="ruby"><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">].</span><span class="nf">map</span><span class="p">(</span><span class="o">&</span><span class="err">»</span><span class="p">.</span><span class="nf">puts</span><span class="p">(</span><span class="no">X</span><span class="p">))</span></code></pre></figure>
<p>The question, I suppose, is whether or not it can be done simply enough…</p>
git aliae to make you more awesome (part 1)2012-05-12T00:00:00+00:00http://cirw.in//blog/git-aliae-1.html<p>One of the amazing advantages of git is that you can create commits locally on your own
computer. I think this is one of the massively underestimated features of distributed
version control systems as it enables (at least) three hugely wonderful things:</p>
<ol>
<li>
<p>You can make permanent check-points every time you get the code into a working state,
and refer to them to when you break stuff.</p>
</li>
<li>
<p>You can save what you’re working on right now, and switch to work on something else for
a while, and then just jump right back in where you left off.</p>
</li>
<li>
<p>You can refactor the commits you make so that you end up with a string of neatly
wrapped chunks of changes, one after the other. (aka. <em><a href="http://sethrobertson.github.com/GitBestPractices/#sausage">sausage making</a></em>).</p>
</li>
</ol>
<p>To be honest, point one is both the most obvious advantage and the least useful — most
editors have undo features, so this is only game changing if your machine crashes a lot
(maybe essential for Kernel developers, but not really for me).</p>
<p>The second point is pretty exciting however. It means you can have an infinite number of
things going on at the same time, without having to keep them all in your head. To help
me do this I’ve written two <a href="https://github.com/ConradIrwin/git-aliae">git-aliae</a> that I use all of the time:</p>
<h2 id="git-pause--git-resume">git-pause && git-resume</h2>
<p>Let’s say I’m sitting at my desk adding a password-reset dialog to the site, and suddenly
the person across from me says: “Hey, I just noticed we’re broken on IE7 again, can you fix
it?”.</p>
<p>No problem, I just <code class="language-plaintext highlighter-rouge">git pause</code> on my current branch (<code class="language-plaintext highlighter-rouge">wip.password-reset</code>) and then
<code class="language-plaintext highlighter-rouge">git checkout master</code>. I’m now ready to go and get a cup of tea and get stuck straight
into the IE7 bug.</p>
<p>A few hours later, I’ve fixed the bug, deployed a new version of master, and am ready to
get back to working on the password-reset dialog again. I go back to the branch I was
working on with <code class="language-plaintext highlighter-rouge">git checkout wip.password-reset</code>, and then <code class="language-plaintext highlighter-rouge">git resume</code>, and all my work
is back ready for me to get stuck back in.</p>
<aside>Under the hood: `git pause` works by creating a temporary commit on the tip of the
branch you're currently working on, and `git resume` removes the commit again. Importantly
this means that (unlike `git-stash`) you can have multiple paused branches at the same
time, and you can always find your work again.</aside>
<h2 id="sausage-making">sausage making</h2>
<p>The third bullet point is the one I’m really wanting to rave about. If I can refactor
commits as I go, then I can make the git history look awesome. This is vitally important
to me because I’m very proud of my work as a programmer; if the person reviewing my changes
isn’t thinking “wow, this stuff is awesome”, I feel sad.</p>
<p>There are also sound “business” reasons to ensure your history is in working order: it
makes code review easier, the <code class="language-plaintext highlighter-rouge">git log</code> output more useful for status tracking, and tracking
down regressions much less painful. Finally of course, happy developers are productive developers,
so letting me spend time being happy is good for everyone.</p>
<aside>Seth Robertson (who I would credit with coining the phrase "sausage making") has
written more extensively about the pros cons and techniques of the practice on his very
thorough [Git Best Practices
page](http://sethrobertson.github.com/GitBestPractices/).</aside>
<p>In order that all this refactoring of history doesn’t take up too much of my time, I’d
like to introduce you to two more <a href="https://github.com/ConradIrwin/git-aliae">git-aliae</a>.
This is really the tip of the iceberg in terms of what git can do, but these are
definitely the commands I use most.</p>
<h2 id="git-amend">git-amend</h2>
<p>Going back to me having written a shiny new password-reset dialog, I notice while I’m
committing (with <code class="language-plaintext highlighter-rouge">git commit -v</code> so I can review my own diff) that I’ve just duplicated a
lot of logic from the main sign-up form… This triggers my refactor alert, and so after
I’ve finished committing the working (but lamely written) version of the password-reset
dialog, I get stuck back into the code and refactor the sign-up form and the new
password-reset dialog to share the same code.</p>
<p>Once the refactoring is done, I just <code class="language-plaintext highlighter-rouge">git amend .</code>, which takes all my new refactorings
and shoves them straight into the previous commit. No-one else need know that I even
considered duplicating the code, looking at the git history will make it appear as though
the beautiful new version just sprang fully-formed into my mind.</p>
<aside>Under the hood: `git amend` is a wrapper for `git add "$@" &&` `git commit --amend`,
this means it supports the `-p` flag. It also means that you can "undo" an amendment with
normal git commands: `git reset HEAD@{1}` (do not use `--hard`).</aside>
<h2 id="git-uncommit">git-uncommit</h2>
<p>Unfortunately the commit that introduces the beautiful new version is quite chunky: it
both refactors the main sign up form and adds a password reset dialog. To make this much
nicer I really want to split it into two separate commits, first refactor the sign-up form
into a reusable form; and then add a password reset dialog that uses the new reusable
code.</p>
<p>Thankfully, <code class="language-plaintext highlighter-rouge">git uncommit -p</code> can be used to help with this. It walks me through a nice
interactive process where I can choose which parts of the previous commit I want to keep,
and which ones I want to pretend haven’t yet happened.</p>
<p>Once that is done I need to do two more things: firstly change the message on the commit
(which now contains only the sign-up form refactor), which I can do with <code class="language-plaintext highlighter-rouge">git amend</code>; and
secondly commit all the password-reset dialog code that’s now in my working tree, which I
can do with <code class="language-plaintext highlighter-rouge">git commit -av</code> as normal.</p>
<aside>Under the hood: `git uncommit` is a clever wrapper for `git checkout HEAD^ "$@" &&`
`git commit -CHEAD`. This means that, just like with `git amend`, if something goes wrong
you can undo a git-uncommit with `git reset HEAD@{1}` (do not use `--hard`).</aside>
<h2 id="installation">installation</h2>
<p>There’s nothing quite as satisfying as the feeling of a job-well-done, and fixing up my
commits like that gives me immense satisfaction. As I’m certain you’ll also want to do
this, I’ve made these aliae available on <a href="https://github.com/ConradIrwin/git-aliae">GitHub</a>.</p>
<p>To install git aliae:</p>
<figure class="highlight"><pre><code class="language-bash" data-lang="bash">git clone https://github.com/ConradIrwin/git-aliae
<span class="c"># Add the following line to your ~/.bashrc</span>
<span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="nv">$PATH</span>:/path/to/git-aliae/bin</code></pre></figure>
<p>Please report bugs and feature requests to <a href="https://github.com/ConradIrwin/git-aliae/issues">GitHub
issues</a>.</p>
<aside>I will award 10 points to Gryffindor if you noticed that `git uncommit` with no
arguments can be used instead of `git resume`; 20 points if you know that using *aliae* as
the plural of *alias* is an etymological disaster; and 50 points if you get in touch with
feedback :).</aside>