Posts tagged "racket-cookbook"urn:www-greghendershott-com:racket-cookbook2015-08-20T14:15:04ZAt-expressionsurn:www-greghendershott-com:-2015-08-at-expressions.html2015-08-20T14:15:04Z2015-08-20T14:15:04ZGreg Hendershott
<div>
<article>
<header>
<h1>At-expressions</h1>
<p class="date-and-tags">
<time datetime="2015-08-20" pubdate="true">2015-08-20</time> :: <span class="tags"><a href="/tags/Racket.html">Racket</a>, <a href="/tags/racket-cookbook.html">racket-cookbook</a></span></p></header>
<p>If you’ve heard of Racket “at-expressions”, maybe you think they’re “that funny Scribble notation in which you write Racket documentation.”</p>
<p>In fact at-expressions are a general, alternative way to write s-expressions. They can be used in various handy ways.</p>
<p>Let’s look at using at-expressions for a few practical things like:</p>
<ul>
<li>“string interpolation”</li>
<li>regular expressions</li>
<li>“here” strings</li></ul><!-- more-->
<h1 id="lang-at-exp-"><code>#lang at-exp ...</code></h1>
<p>You can use the at-expression reader with a language by supplying <a href="http://docs.racket-lang.org/scribble/reader-internals.html#%28mod-path._at-exp%29"><code>at-exp</code></a> before the language. Examples:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">at-exp</span> <span class="n">racket</span>
<span class="kn">#lang </span><span class="nn">at-exp</span> <span class="n">typed/racket</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In the examples below, make sure you’re using:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">at-exp</span> <span class="n">racket</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h1 id="a"><code>~a</code></h1>
<p>Before we talk more about at-expressions, note that <code>racket/format</code> provides the function <a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))"><code>~a</code></a>. <code>(~a v)</code> is a kind of shorthand for <code>(format "~a" v)</code>, plus it offers many more formatting options.</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">racket</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._format))" style="color: inherit">format</a></span> <span class="s2">"~a"</span> <span class="s2">"hi"</span><span class="p">)</span> <span class="c1">;"hi"</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a></span> <span class="s2">"hi"</span><span class="p">)</span> <span class="c1">;"hi"</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._format))" style="color: inherit">format</a></span> <span class="s2">"~a"</span> <span class="mi">1</span><span class="p">)</span> <span class="c1">;"1"</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a></span> <span class="mi">1</span><span class="p">)</span> <span class="c1">;"1"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>We’ll use <code>~a</code> below.</p>
<h1 id="basic-at-expressions">Basic at-expressions</h1>
<p>At-expressions are a very well thought-out system; you can read about the <a href="http://docs.racket-lang.org/scribble/reader.html">full syntax</a>. For this post, we simply need to know that <code>@func{string}</code> is equivalent to <code>(func "string")</code>. So we can rewrite:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a></span> <span class="s2">"foo bar"</span><span class="p">)</span> <span class="c1">; "foo bar"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>as:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@~a</span><span class="p">{</span><span class="n">foo</span> <span class="n">bar</span><span class="p">}</span> <span class="c1">; "foo bar"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>(Note that <code>~a</code> is the name of the function we’re calling. The <code>~</code> has nothing to do with at-expressions; it’s part of this function’s name.)</p>
<p>Also special characters like <code>\</code> and <code>"</code> are automatically escaped:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@~a</span><span class="p">{</span><span class="n">A</span> <span class="n">back</span> <span class="n">slash</span> <span class="n">\}</span> <span class="c1">; "A back slash \\"</span>
<span class="n">@~a</span><span class="p">{</span><span class="s2">"Double quotes"</span><span class="p">}</span> <span class="c1">; "\"Double quotes\""</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Inside the curly brackets, you may use <code>@</code> again to “escape” to any Racket expression. For example an expression like <code>(+ 1 1)</code>:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@~a</span><span class="p">{</span><span class="n">The</span> <span class="n">sum</span> <span class="n">of</span> <span class="n">one</span> <span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span> <span class="n">one</span> <span class="n">is</span> <span class="n">@</span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._+))" style="color: inherit">+</a></span> <span class="mi">1</span> <span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="p">}</span> <span class="c1">; "The sum of one and one is 2."</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Or simply the name of a variable like <code>x</code>:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">x</span> <span class="mi">0</span><span class="p">)</span>
<span class="n">@~a</span><span class="p">{</span><span class="n">x</span> <span class="n">is</span> <span class="n">@x</span><span class="p">}</span> <span class="c1">; "x is 0"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h1 id="string-interpolation">String interpolation</h1>
<p>You can use at-exps as the equivalent of “string interpolation” in some other languages:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">x</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">y</span> <span class="s2">"foo"</span><span class="p">)</span>
<span class="n">@~a</span><span class="p">{</span><span class="n">x</span> <span class="n">is</span> <span class="n">@x</span> <span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span> <span class="n">y</span> <span class="n">is</span> <span class="n">@y</span><span class="p">}</span> <span class="c1">; "x is 0 and y is foo"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Normally in Racket you’d write that as:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._format))" style="color: inherit">format</a></span> <span class="s2">"x is <a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a> <a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a> y is ~a"</span> <span class="n">x</span> <span class="n">y</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Which is fine, albeit you have to flip between the <code>~a</code>s on the left and the values on the right, making sure they match up. The string interpolation style is arguably easier to write, to read, and to update later without making a mistake.</p>
<p>How about mixing formats, such as <code>~a</code> (display) and <code>~v</code> (print)? For example with <code>format</code> we can write</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Writing.html#(def._((quote._~23~25kernel)._format))" style="color: inherit">format</a></span> <span class="s2">"x is <a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ea))" style="color: inherit">~a</a> <a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a> y is ~v"</span> <span class="n">x</span> <span class="n">y</span><span class="p">)</span><span class="o">`</span> <span class="c1">; "x is 0 and y is \"foo\""</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>How can we do this using our at-exp? Well since <code>~a</code> is the outer function it will display the value of any <code>~v</code> inside. Remember that <code>@</code> lets us “escape” to <em>any</em> Racket expression, not just a variable, it could be a function application. So:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@~a</span><span class="p">{</span><span class="n">x</span> <span class="n">is</span> <span class="n">@x</span> <span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span> <span class="n">y</span> <span class="n">is</span> <span class="n">@</span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((lib._racket/format..rkt)._~7ev))" style="color: inherit">~v</a></span> <span class="n">y</span><span class="p">)}</span> <span class="c1">; "x is 0 and y is \"foo\""</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>You can also surround the Racket expression in <code>|</code> characters. This is useful if the expression needs to end next to plain text. You can demarcate the identifier from the text:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@~a</span><span class="p">{</span><span class="n">x</span> <span class="n">is</span> <span class="n">@|x|</span> <span class="k"><a href="http://docs.racket-lang.org/reference/if.html#(form._((lib._racket/private/letstx-scheme..rkt)._and))" style="color: inherit">and</a></span> <span class="n">y</span> <span class="n">is</span> <span class="n">@|y|!</span><span class="p">}</span> <span class="c1">; "x is 0 and y is foo!"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The <code>|</code> keeps <code>!</code> from being read as part of the identifier <code>y</code>.</p>
<h1 id="regular-expressions">Regular expressions</h1>
<p>Do you enjoy writing regular expressions like <code>#px"\\d\\.\\d"</code>? Me neither.</p>
<p>Another useful example is avoiding the need to use <code>\\</code> to get a <code>\</code> in string literals. This is especially handy for regular expressions:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@pregexp</span><span class="p">{</span><span class="n">\d\.\d</span><span class="p">}</span> <span class="c1">; #px"\\d\\.\\d"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>If you find <code>pregexp</code> too verbose, you could define a little alias:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">px</span> <span class="nb"><a href="http://docs.racket-lang.org/reference/regexp.html#(def._((quote._~23~25kernel)._pregexp))" style="color: inherit">pregexp</a></span><span class="p">)</span>
<span class="n">@px</span><span class="p">{</span><span class="n">\d\.\d</span><span class="p">}</span> <span class="c1">; #px"\\d\\.\\d"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h1 id="here-strings">“Here” strings</h1>
<p>Like shells, Racket has “here” strings:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">multi-line</span> <span class="sh">#<<EOF</span>
<span class="sh"><a href="http://docs.racket-lang.org/ts-reference/type-ref.html#(form._((lib._typed-racket/base-env/base-types-extra..rkt)._.Some))" style="color: inherit">Some</a> multi-line</span>
<span class="sh"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((quote._~23~25kernel)._string))" style="color: inherit">string</a> literal.</span>
<span class="sh"><a href="http://docs.racket-lang.org/ts-reference/type-ref.html#(form._((lib._typed-racket/base-env/base-types..rkt)._.E.O.F))" style="color: inherit">EOF</a></span>
<span class="p">)</span>
<span class="n">multi-line</span> <span class="c1">; "Some multi-line\nstring literal."</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Cool. However the indentation is tricky. You get extra spaces if you do this:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">multi-line</span> <span class="sh">#<<EOF</span>
<span class="sh"> <a href="http://docs.racket-lang.org/ts-reference/type-ref.html#(form._((lib._typed-racket/base-env/base-types-extra..rkt)._.Some))" style="color: inherit">Some</a> multi-line</span>
<span class="sh"> <a href="http://docs.racket-lang.org/reference/strings.html#(def._((quote._~23~25kernel)._string))" style="color: inherit">string</a> literal.</span>
<span class="sh"><a href="http://docs.racket-lang.org/ts-reference/type-ref.html#(form._((lib._typed-racket/base-env/base-types..rkt)._.E.O.F))" style="color: inherit">EOF</a></span>
<span class="p">)</span>
<span class="n">multi-line</span> <span class="c1">; " Some multi-line\n string literal."</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Oops.</p>
<p>Also the <code>EOF</code> <em>must</em> be alone on a line <em>and</em> in column 0. You can’t let that get indented, and you can’t put the closing paren on the same line.</p>
<p>At-exps are more elegant and survive typical re-indentation:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">multi-line</span> <span class="n">@~a</span><span class="p">{</span><span class="n"><a href="http://docs.racket-lang.org/ts-reference/type-ref.html#(form._((lib._typed-racket/base-env/base-types-extra..rkt)._.Some))" style="color: inherit">Some</a></span> <span class="n">multi-line</span>
<span class="nb"><a href="http://docs.racket-lang.org/reference/strings.html#(def._((quote._~23~25kernel)._string))" style="color: inherit">string</a></span> <span class="n">literal</span><span class="p">})</span>
<span class="n">multi-line</span> <span class="c1">; "Some multi-line\nstring literal"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h1 id="how-to-write-a-literal-">How to write a literal <code>@</code></h1>
<p>If <code>@</code> is a magic escape character, how do you write a literal <code>@</code>?</p>
<ol>
<li>
<p>We want a string, <code>"@"</code>.</p></li>
<li>
<p>How do we escape to any Racket expression, including (say) a string? Using <code>@</code>.</p></li>
<li>
<p>Therefore prepend a <code>@</code> to <code>"@"</code>:</p></li></ol>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@</span><span class="s2">"@"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>So for example:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">@~a</span><span class="p">{</span><span class="n">The</span> <span class="n">email</span> <span class="n">is</span> <span class="n">foo@</span><span class="s2">"@"</span><span class="n">bar.com</span><span class="p">}</span> <span class="c1">; "The email is foo@bar.com"</span>
</pre></div>
</td></tr></tbody></table>
</div>
<h1 id="conclusion">Conclusion</h1>
<p>This was a quick look at some practical ways to use at-expressions for more than writing Scribble documentation. Again, feel free to read up on the <a href="http://docs.racket-lang.org/scribble/reader.html">full syntax</a>.</p>
<footer></footer></article></div>Does your Racket project need a makefile?urn:www-greghendershott-com:-2014-06-does-your-racket-project-need-a-makefile.html2014-06-19T18:14:59Z2014-06-19T18:14:59ZGreg Hendershott
<div>
<article>
<header>
<h1>Does your Racket project need a makefile?</h1>
<p class="date-and-tags">
<time datetime="2014-06-19" pubdate="true">2014-06-19</time> :: <span class="tags"><a href="/tags/Racket.html">Racket</a>, <a href="/tags/racket-cookbook.html">racket-cookbook</a></span></p></header>
<blockquote>
<p><strong>NOTE</strong>: <strong>See my <a href="/2017/04/racket-makefiles.html">newer post</a></strong>.</p></blockquote>
<p>Most of my Racket projects don’t use a makefile. Why would they? <code>raco
make</code> or <code>raco setup</code> suffices.</p>
<p>But a makefile can consistently define some common project tasks. And it can <em>really</em> help when you want to generate HTML documentation from Scribble sources, and publish it to GitHub Pages using the automagical <code>gh-pages</code> branch.<sup><a href="#does-your-racket-project-need-a-makefile-footnote-1-definition" name="does-your-racket-project-need-a-makefile-footnote-1-return">1</a></sup></p><!-- more-->
<p>GitHub Pages lets you provide a web site for each of your projects. You:</p>
<ol>
<li>
<p>Create an empty, orphan branch named <code>gh-pages</code>. <a href="https://help.github.com/articles/creating-project-pages-manually">GitHub instructions</a>.</p></li>
<li>
<p>Somehow make <code>gh-pages</code> contain just the HTML and other files required for the web site (but preferably not the source files from your <code>master</code> branch).</p></li>
<li>
<p>Somehow keep that up-to-date.</p></li></ol>
<p>Steps 2 and 3 are awkward. To-date I’ve used some shell scripts that felt like duct tape.</p>
<p>Yesterday I discovered Tony Garnock-Jones’ <a href="https://github.com/tonyg/racket-bitsyntax/blob/master/Makefile">makefile</a> for his racket-bitsyntax project. It’s brilliant. I promptly stole it, asked him a question about how it works, and asked if I could blog about it.</p>
<p>Here is his original makefile:</p>
<div class="brush: make">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="nv">PACKAGENAME</span><span class="o">=</span>bitsyntax
<span class="nv">COLLECTS</span><span class="o">=</span>bitsyntax
<span class="nf">all</span><span class="o">:</span> <span class="n">setup</span>
<span class="nf">clean</span><span class="o">:</span>
find . -name compiled -type d <span class="p">|</span> xargs rm -rf
rm -rf htmldocs
<span class="nf">setup</span><span class="o">:</span>
raco setup <span class="k">$(</span>COLLECTS<span class="k">)</span>
<span class="nf">link</span><span class="o">:</span>
raco pkg install --link -n <span class="k">$(</span>PACKAGENAME<span class="k">)</span> <span class="nv">$$</span><span class="o">(</span><span class="nb">pwd</span><span class="o">)</span>
<span class="nf">unlink</span><span class="o">:</span>
raco pkg remove <span class="k">$(</span>PACKAGENAME<span class="k">)</span>
<span class="nf">htmldocs</span><span class="o">:</span>
raco scribble <span class="se">\</span>
--html <span class="se">\</span>
--dest htmldocs <span class="se">\</span>
--dest-name index <span class="se">\</span>
++main-xref-in <span class="se">\</span>
--redirect-main http://docs.racket-lang.org/ <span class="se">\</span>
<span class="se">\</span>
bitsyntax/scribblings/bitsyntax.scrbl
<span class="nf">pages</span><span class="o">:</span>
@<span class="o">(</span>git branch -v <span class="p">|</span> grep -q gh-pages <span class="o">||</span> <span class="o">(</span><span class="nb">echo</span> <span class="nb">local</span> gh-pages branch missing<span class="p">;</span> <span class="nb">false</span><span class="o">))</span>
@echo
@git branch -av <span class="p">|</span> grep gh-pages
@echo
@<span class="o">(</span><span class="nb">echo</span> <span class="s1">'Is the branch up to date? Press enter to continue.'</span><span class="p">;</span> <span class="nb">read</span> dummy<span class="o">)</span>
git clone -b gh-pages . pages
<span class="nf">publish</span><span class="o">:</span> <span class="n">htmldocs</span> <span class="n">pages</span>
rm -rf pages/*
cp -r htmldocs/. pages/.
<span class="o">(</span><span class="nb">cd</span> pages<span class="p">;</span> git add -A<span class="o">)</span>
-<span class="o">(</span><span class="nb">cd</span> pages<span class="p">;</span> git commit -m <span class="s2">"Update </span><span class="nv">$$</span><span class="s2">(date +%Y%m%d%H%M%S)"</span><span class="o">)</span>
<span class="o">(</span><span class="nb">cd</span> pages<span class="p">;</span> git push<span class="o">)</span>
rm -rf pages
</pre></div>
</td></tr></tbody></table>
</div>
<p>As you can see, it defines some targets for common actions like running <code>raco setup</code>, doing a local package link and unlink.</p>
<p>The really interesting bits are the <code>htmldocs</code>, <code>pages</code> and <code>publish</code> targets.</p>
<ul>
<li>
<p><code>htmldocs</code> simply runs <code>raco scribble</code> with the options I can never remember and always need to look up.</p></li>
<li>
<p><code>pages</code> assumes that you’ve already created a <code>gh-pages</code> branch, and… does something really weird. It does a <code>git clone</code> of the <code>gh-pages</code> branch to a <code>pages/</code> subdirectory. Yes, it makes <em>another</em> Git repo down there.</p></li>
<li>
<p><code>publish</code></p>
<ul>
<li>
<p>Deletes the <em>contents</em> of that <code>pages/</code> subdirectory — but leaving its <code>.git</code> folder alone — and copies the <code>htmldocs/</code> files into <code>pages/</code>. In other words it makes the files in <code>pages/</code> be an exact copy of <code>htmldocs/</code>.</p></li>
<li>
<p>Commits all changes (if any), using an “Update <em>datetime</em>” commit message.</p></li>
<li>
<p>Does a <code>git push</code>. This is interesting. To what “remote” repo does it push? Not GitHub. It pushes to the repo in the parent directory — the one from which it was cloned.</p></li>
<li>
<p>Blows away the <code>pages/</code> subdirectory.</p></li></ul></li></ul>
<p>Voila, the <code>gh-pages</code> branch has been updated with the latest HTML output files, and only those files. Very cool.</p>
<h2 id="my-confusion">My confusion</h2>
<p>When I tried using it, two things confused me:</p>
<ol>
<li>When <code>publish</code> finishes, the result has <em>not</em> yet been pushed to the remote for the main repo — <em>nothing has been pushed back to GitHub</em>, yet. This confused me at first. I thought “publish” would mean, “actually push to GitHub”.<sup><a href="#does-your-racket-project-need-a-makefile-footnote-2-definition" name="does-your-racket-project-need-a-makefile-footnote-2-return">2</a></sup> To do so, there needs to be one more <code>git push</code>, up in the main repo directory, as a new last step.</li></ol>
<ol>
<li>
<p>If you’re using a newer Git, like version 1.9.3, when you do just <code>git push</code> you may see this warning:</p>
<pre><code>warning: push.default is unset; its implicit value is changing in
Git 2.0 from 'matching' to 'simple'. To squelch this message
and maintain the current behavior after the default changes, use:
git config --global push.default matching
To squelch this message and adopt the new behavior now, use:
git config --global push.default simple
When push.default is set to 'matching', git will push local branches
to the remote branches that already exist with the same name.
In Git 2.0, Git will default to the more conservative 'simple'
behavior, which only pushes the current branch to the corresponding
remote branch that 'git pull' uses to update the current branch.
See 'git help config' and search for 'push.default' for further information.
(the 'simple' mode was introduced in Git 1.7.11. Use the similar mode
'current' instead of 'simple' if you sometimes use older versions of Git)</code></pre>
<p>To make it go away, you could either:</p>
<ul>
<li>
<p>Make the global configuration change it recommends.</p></li>
<li>
<p>Be explicit and say <code>git push origin gh-pages</code>. I’m leaning towards this so that the makefile will work for someone else, regardless of their Git config.</p></li></ul></li></ol>
<p>Combining these two points, here is the makefile I made to use with my <code>#lang rackjure</code> project:</p>
<div class="brush: make">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="nv">PACKAGENAME</span><span class="o">=</span>rackjure
<span class="nv">COLLECTS</span><span class="o">=</span>rackjure
<span class="nv">SCRBL</span><span class="o">=</span>rackjure/manual.scrbl
<span class="nf">all</span><span class="o">:</span> <span class="n">setup</span>
<span class="nf">clean</span><span class="o">:</span>
find . -name compiled -type d <span class="p">|</span> xargs rm -rf
rm -rf htmldocs
<span class="nf">setup</span><span class="o">:</span>
raco setup <span class="k">$(</span>COLLECTS<span class="k">)</span>
<span class="nf">link</span><span class="o">:</span>
raco pkg install --link -n <span class="k">$(</span>PACKAGENAME<span class="k">)</span> <span class="nv">$$</span><span class="o">(</span><span class="nb">pwd</span><span class="o">)</span>
<span class="nf">unlink</span><span class="o">:</span>
raco pkg remove <span class="k">$(</span>PACKAGENAME<span class="k">)</span>
<span class="nf">htmldocs</span><span class="o">:</span> <span class="k">$(</span><span class="nv">SCRBL</span><span class="k">)</span>
raco scribble <span class="se">\</span>
--html <span class="se">\</span>
--dest htmldocs <span class="se">\</span>
--dest-name index <span class="se">\</span>
++main-xref-in <span class="se">\</span>
--redirect-main http://docs.racket-lang.org/ <span class="se">\</span>
<span class="se">\</span>
<span class="k">$(</span>SCRBL<span class="k">)</span>
<span class="nf">pages</span><span class="o">:</span>
@<span class="o">(</span>git branch -v <span class="p">|</span> grep -q gh-pages <span class="o">||</span> <span class="o">(</span><span class="nb">echo</span> <span class="nb">local</span> gh-pages branch missing<span class="p">;</span> <span class="nb">false</span><span class="o">))</span>
@echo
@git branch -av <span class="p">|</span> grep gh-pages
@echo
@<span class="o">(</span><span class="nb">echo</span> <span class="s1">'Is the branch up to date? Press enter to continue.'</span><span class="p">;</span> <span class="nb">read</span> dummy<span class="o">)</span>
git clone -b gh-pages . pages
<span class="nf">publish</span><span class="o">:</span> <span class="n">htmldocs</span> <span class="n">pages</span>
rm -rf pages/*
cp -r htmldocs/. pages/.
<span class="o">(</span><span class="nb">cd</span> pages<span class="p">;</span> git add -A<span class="o">)</span>
-<span class="o">(</span><span class="nb">cd</span> pages<span class="p">;</span> git commit -m <span class="s2">"Update </span><span class="nv">$$</span><span class="s2">(date +%Y%m%d%H%M%S)"</span><span class="o">)</span>
<span class="o">(</span><span class="nb">cd</span> pages<span class="p">;</span> git push origin gh-pages<span class="o">)</span>
rm -rf pages
git push origin gh-pages
</pre></div>
</td></tr></tbody></table>
</div>
<p>However in case I change it after this blog post, see the latest version <a href="https://github.com/greghendershott/rackjure/blob/master/makefile">here</a>.</p>
<p>Also, FYI, <a href="https://github.com/greghendershott/fear-of-macros/blob/master/makefile">here’s</a> a variant I made for <em>Fear of Macros</em>. This one has targets to build both <a href="http://www.greghendershott.com/fear-of-macros">multi-page</a> and <a href="http://www.greghendershott.com/fear-of-macros/all.html">all-in-one</a> HTML.</p>
<hr />
<p>Racket doesn’t need as much external “infrastructure” as some other languages. You don’t need this for very casual projects. But a makefile like this, plus perhaps a <a href="http://www.greghendershott.com/2013/07/using-travis-ci-for-racket-projects.html"><code>travis.yml</code> for Travis-CI</a>, can be nice for some projects.</p>
<div class="footnotes">
<ol>
<li id="does-your-racket-project-need-a-makefile-footnote-1-definition" class="footnote-definition">
<p>Although overall I much prefer Racket’s new package manager, the old PLaneT system automatically hosts Scribble documentation. When using the new package manager, this makefile makes it much less tedious to host the documentation on GitHub. <a href="#does-your-racket-project-need-a-makefile-footnote-1-return">↩</a></p></li>
<li id="does-your-racket-project-need-a-makefile-footnote-2-definition" class="footnote-definition">
<p>To be clear, Tony did it this way on purpose. He wanted the final push to GitHub to be something he did manually, as a safety-check. I completely understand that. I just expected and want it to behave differently. <a href="#does-your-racket-project-need-a-makefile-footnote-2-return">↩</a></p></li></ol></div>
<footer></footer></article></div>`__FILE__` and `__LINE__` in Racketurn:www-greghendershott-com:-2014-06-file-and-line-in-racket.html2014-06-03T04:00:00Z2014-06-03T04:00:00ZGreg Hendershott
<div>
<article>
<header>
<h1>`__FILE__` and `__LINE__` in Racket</h1>
<p class="date-and-tags">
<time datetime="2014-06-03" pubdate="true">2014-06-03</time> :: <span class="tags"><a href="/tags/Racket.html">Racket</a>, <a href="/tags/racket-cookbook.html">racket-cookbook</a></span></p></header>
<p>Many languages have a variable (or preprocessor macro) called <code>__FILE__</code> or <code>__file__</code> whose value is the pathname of the current source file. Likewise <code>__LINE__</code> for the the source line number.</p>
<p>You probably need this less in Racket than you imagine. For example:</p>
<ul>
<li>
<p>We wouldn’t test that <code>__FILE__</code> ends in <code>main.rkt</code>; instead we’d use a <code>main</code> submodule <code>(module+ main <your code here>)</code>.</p></li>
<li>
<p>To get a data file <code>foo.dat</code> located in the same directory as a source file we’d use <code>(define-runtime-path foo.dat "foo.dat")</code>. If we’re a package or executable this works regardless of where our files happen to get installed.</p></li></ul>
<p>But if you really did need a <code>__FILE__</code> in Racket, how would you do it?</p><!-- more-->
<p>Simply:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-source))" style="color: inherit">syntax-source</a></span> <span class="o">#'</span><span class="n">here</span><span class="p">)</span> <span class="c1">;full path to the source file, i.e. __FILE__</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-line))" style="color: inherit">syntax-line</a></span> <span class="o">#'</span><span class="n">here</span><span class="p">)</span> <span class="c1">;line number, i.e. __LINE__</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>You could use <code>#'0</code> or <code>#'42</code> instead. The only important thing about <code>#'here</code> is that it’s a <em>syntax object</em> representing syntax from the current source file. The <code>#'</code> prefix is what matters; it’s reader shorthand for the <code>syntax</code> function. So <code>#'here</code> is read as <code>(syntax
here)</code>, which you could also use if you don’t mind typing a few more keys.</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="c1">;; Same as above</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-source))" style="color: inherit">syntax-source</a></span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax))" style="color: inherit">syntax</a></span> <span class="n">here</span><span class="p">))</span> <span class="c1">;full path to the source file, i.e. __FILE__</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-line))" style="color: inherit">syntax-line</a></span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax))" style="color: inherit">syntax</a></span> <span class="n">here</span><span class="p">))</span> <span class="c1">;line number, i.e. __LINE__</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In some Lisps, a macro works on a plain s-expression — the <code>0</code> or <code>42</code> or <code>here</code> or <code>(+ 1 1)</code>. A <em>syntax object</em> in Racket contains the s-expression, and also information such as source location (line, column, position, span) and lexical scope.<sup><a href="#file-and-line-in-racket-footnote-1-definition" name="file-and-line-in-racket-footnote-1-return">1</a></sup></p>
<p>So in Racket, you simply need to make <em>some</em> syntax object in your source file, like <code>#'here</code>, and feed it to syntax object accessors like <code>syntax-source</code> and <code>syntax-line</code>.<sup><a href="#file-and-line-in-racket-footnote-2-definition" name="file-and-line-in-racket-footnote-2-return">2</a></sup></p>
<hr />
<p>What if you want to write <code>__FILE__</code> and <code>__LINE__</code> like in other languages? You could define these as macros in a file, and <code>require</code> and use where desired:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">racket/base</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._provide))" style="color: inherit">provide</a></span> <span class="n">__FILE__</span> <span class="n">__LINE__</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._for-syntax))" style="color: inherit">for-syntax</a></span> <span class="n">racket/base</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">__FILE__</span> <span class="n">stx</span><span class="p">)</span>
<span class="c1">;; `stx` comes from where the macro was invoked, so give _that_ to</span>
<span class="c1">;; `syntax-source`.</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._with-syntax))" style="color: inherit">with-syntax</a></span> <span class="p">([</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._file))" style="color: inherit">file</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-source))" style="color: inherit">syntax-source</a></span> <span class="n">stx</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax-case))" style="color: inherit">syntax-case</a></span> <span class="n">stx</span> <span class="p">()</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="o">#'</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._file))" style="color: inherit">file</a></span><span class="p">])))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">__LINE__</span> <span class="n">stx</span><span class="p">)</span>
<span class="c1">;; `stx` comes from where the macro was invoked, so give _that_ to</span>
<span class="c1">;; `syntax-line`.</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._with-syntax))" style="color: inherit">with-syntax</a></span> <span class="p">([</span><span class="n">line</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stxops.html#(def._((quote._~23~25kernel)._syntax-line))" style="color: inherit">syntax-line</a></span> <span class="n">stx</span><span class="p">)])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax-case))" style="color: inherit">syntax-case</a></span> <span class="n">stx</span> <span class="p">()</span>
<span class="p">[</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="o">#'</span><span class="n">line</span><span class="p">])))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>In this case, we care about the source file and line from where the macro was invoked — from where we typed <code>__FILE__</code> or <code>__LINE__</code>. So we’re careful to give that input <code>stx</code> to <code>source-file</code> or <code>source-line</code>. (Whereas if we used some made-up syntax object literal like <code>#'here</code>, it would give us the source or line of <code>#'here</code> in the macro <em>definition</em>.)</p>
<hr />
<p>It turns out that learning how to do a <code>__FILE__</code> in Racket ends up being a gentle, practical introduction to syntax objects.</p>
<div class="footnotes">
<ol>
<li id="file-and-line-in-racket-footnote-1-definition" class="footnote-definition">
<p>For more about syntax objects see my <a href="http://www.greghendershott.com/fear-of-macros/">Fear of Macros</a>. Or if you’re coming to Racket from another Lisp, it might be quicker to read <a href="http://blog.racket-lang.org/2011/04/writing-syntax-case-macros.html">Eli Barzilay’s blog post</a>. <a href="#file-and-line-in-racket-footnote-1-return">↩</a></p></li>
<li id="file-and-line-in-racket-footnote-2-definition" class="footnote-definition">
<p>You might be wondering, why isn’t there an error that no identifier named <code>here</code> is defined? Great question. A syntax object such as <code>#'here</code> a.k.a. <code>(syntax here)</code> is basically quoted data — like <code>'here</code> a.k.a. <code>(quote here)</code>. We’re not <code>eval</code>uating the syntax. <a href="#file-and-line-in-racket-footnote-2-return">↩</a></p></li></ol></div>
<footer></footer></article></div>Fallback when required function not availableurn:www-greghendershott-com:-2014-06-fallback-when-required-function-not-available.html2014-06-02T13:27:17Z2014-06-02T13:27:17ZGreg Hendershott
<div>
<article>
<header>
<h1>Fallback when required function not available</h1>
<p class="date-and-tags">
<time datetime="2014-06-02" pubdate="true">2014-06-02</time> :: <span class="tags"><a href="/tags/Racket.html">Racket</a>, <a href="/tags/racket-cookbook.html">racket-cookbook</a></span></p></header>
<p>Let’s say we want to use <code>find-collects-dir</code>, which was added in Racket 6.0. We get a bug report from someone using Racket 5.3.6.</p>
<p>To fix this, we can <code>dynamic-require</code> the desired function; when it doesn’t exist, we can use our own fallback implementation.<sup><a href="#fallback-when-required-function-not-available-footnote-1-definition" name="fallback-when-required-function-not-available-footnote-1-return">1</a></sup></p><!-- more-->
<p>The basic recipe:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">our-fallback</span> <span class="n">....</span><span class="p">)</span>
<span class="n">....</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">desired-function</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Module_Names_and_Loading.html#(def._((quote._~23~25kernel)._dynamic-require))" style="color: inherit">dynamic-require</a></span> <span class="o">'</span><span class="ss">collection/path</span> <span class="o">'</span><span class="ss">desired-function</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/procedures.html#(form._((lib._racket/function..rkt)._thunk))" style="color: inherit">thunk</a></span> <span class="n">our-fallback</span><span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Here <code>(thunk x)</code> is just shorthand for <code>(lambda () x)</code>.</p>
<p>A simple but full example:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">racket/base</span>
<span class="c1">;; find-collects-dir was added in Racket 6.0.</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._provide))" style="color: inherit">provide</a></span> <span class="n"><a href="http://docs.racket-lang.org/raco/dirs.html#(def._((lib._setup/dirs..rkt)._find-collects-dir))" style="color: inherit">find-collects-dir</a></span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="n">racket/list</span>
<span class="n">racket/function</span>
<span class="n">racket/path</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">our-find-collects-dir</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/procedures.html#(def._((lib._racket/private/base..rkt)._apply))" style="color: inherit">apply</a></span> <span class="nb"><a href="http://docs.racket-lang.org/reference/Manipulating_Paths.html#(def._((quote._~23~25kernel)._build-path))" style="color: inherit">build-path</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/list..rkt)._reverse))" style="color: inherit">reverse</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((quote._~23~25kernel)._cdr))" style="color: inherit">cdr</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/pairs.html#(def._((lib._racket/private/list..rkt)._reverse))" style="color: inherit">reverse</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Manipulating_Paths.html#(def._((quote._~23~25kernel)._explode-path))" style="color: inherit">explode-path</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/collects.html#(def._((lib._racket/private/base..rkt)._collection-path))" style="color: inherit">collection-path</a></span> <span class="s2">"racket"</span><span class="p">)))))))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n"><a href="http://docs.racket-lang.org/raco/dirs.html#(def._((lib._setup/dirs..rkt)._find-collects-dir))" style="color: inherit">find-collects-dir</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/Module_Names_and_Loading.html#(def._((quote._~23~25kernel)._dynamic-require))" style="color: inherit">dynamic-require</a></span> <span class="o">'</span><span class="ss">setup/dirs</span> <span class="o">'</span><span class="ss"><a href="http://docs.racket-lang.org/raco/dirs.html#(def._((lib._setup/dirs..rkt)._find-collects-dir))" style="color: inherit">find-collects-dir</a></span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/procedures.html#(form._((lib._racket/function..rkt)._thunk))" style="color: inherit">thunk</a></span> <span class="n">our-find-collects-dir</span><span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Let’s say this is in a file <code>find-collects-dir.rkt</code>. Then elsewhere in our program instead of <code>(require setup/dirs)</code> we do <code>(require
"find-collects-dir.rkt")</code>.</p>
<p>Now our program uses Racket’s <code>find-collects-dir</code> when running on Racket 6.0 or newer, otherwise it falls back to using our own implementation.</p>
<p>Season with parsley. Serves many.</p>
<div class="footnotes">
<ol>
<li id="fallback-when-required-function-not-available-footnote-1-definition" class="footnote-definition">
<p>Of course another approach is to <em>only</em> use our own implementation, even in newer versions of Racket. Sometimes that would be simpler. However the “official” function might someday change in beneficial ways. Also, someday we might decide to stop supporting an older Racket version, in which case it’s cleaner to discard this scaffolding and adjust the <code>require</code>s to use the “official” function directly. <a href="#fallback-when-required-function-not-available-footnote-1-return">↩</a></p></li></ol></div>
<footer></footer></article></div>Racket cookbookurn:www-greghendershott-com:-2014-06-racket-cookbook.html2014-06-02T13:26:34Z2014-06-02T13:26:34ZGreg Hendershott
<div>
<article>
<header>
<h1>Racket cookbook</h1>
<p class="date-and-tags">
<time datetime="2014-06-02" pubdate="true">2014-06-02</time> :: <span class="tags"><a href="/tags/Racket.html">Racket</a>, <a href="/tags/racket-cookbook.html">racket-cookbook</a></span></p></header>
<p>Two parallel thoughts:</p>
<ol>
<li>
<p>I haven’t blogged in awhile. I’ve been heads-down on a few projects. Plus I haven’t had ideas I feel are “big” or unique enough to merit a post.</p></li>
<li>
<p>It’s occurred to me that a “Racket Cookbook” might be a useful resource. Because examples. Because real-life, practical examples.<sup><a href="#racket-cookbook-footnote-1-definition" name="racket-cookbook-footnote-1-return">1</a></sup></p></li></ol>
<p>Although I haven’t created a cookbook, my working assumption is that it would be better to write one recipe at a time. As they arise. As I think, “Ah right, this wasn’t obvious to me when I was learning Racket.”</p>
<p>So I plan to experiment with releasing the things one at a time, as short blog posts. Thereby terminating two avian organisms with one geologic projectile.</p>
<p>Not sure if I’ll keep it up. Definitely not sure if I’ll ever collect and polish them into a “book” of some form. They might only ever live as a <code>racket-cookbook</code> tag on this blog.</p>
<div class="footnotes">
<ol>
<li id="racket-cookbook-footnote-1-definition" class="footnote-definition">
<p>Admittedly I rarely recall using any “cookbook” resource to find the answer to a problem I have. Taken literally, programming cookbooks are largely a failure, for me. On the other hand, flipping through one can give the “flavor” of a language. And <a href="/2013/07/skim-or-sink.html">as I’ve written</a>, one valid learning strategy is to absorb things shallowly — you may not know the answer, but you know roughly where to <em>find</em> the answer. It rings a bell. Probably cookbooks fit that model — filling your head with, um, bells. <a href="#racket-cookbook-footnote-1-return">↩</a></p></li></ol></div>
<footer></footer></article></div>Using syntax/loc and unit test macrosurn:www-greghendershott-com:-2014-01-syntax-loc-and-unit-tests.html2014-01-31T23:21:56Z2014-01-31T23:21:56ZGreg Hendershott
<div>
<article>
<header>
<h1>Using syntax/loc and unit test macros</h1>
<p class="date-and-tags">
<time datetime="2014-01-31" pubdate="true">2014-01-31</time> :: <span class="tags"><a href="/tags/Racket.html">Racket</a>, <a href="/tags/racket-cookbook.html">racket-cookbook</a>, <a href="/tags/macros.html">macros</a></span></p></header>
<p>In my <a href="http://www.greghendershott.com/2014/01/using-syntax-loc.html">previous post</a>, I wrote about a nuance with <code>syntax/loc</code>, using the example of a macro that both <code>define</code>s and <code>provide</code>s a function. But why don’t I back up, and look at a simpler example of why you’d want to use <code>syntax/loc</code>. The example is a simple macro you might often find yourself wanting, to reduce the tedium of writing unit test cases.</p><!-- more-->
<p>Let’s say we have a function <code>my-function-that-increments</code>, with some unit tests.</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">racket</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="n">rackunit</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="n">x</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._add1))" style="color: inherit">add1</a></span> <span class="n">x</span><span class="p">))</span>
<span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="mi">0</span><span class="p">)</span>
<span class="mi">1</span><span class="p">)</span>
<span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="mi">1</span><span class="p">)</span>
<span class="mi">1</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The last test correctly fails<sup><a href="#syntax-loc-and-unit-tests-footnote-1-definition" name="syntax-loc-and-unit-tests-footnote-1-return">1</a></sup>, and the rackunit error message points to the <code>check-equal?</code> on line 10:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">--------------------</span>
<span class="n">FAILURE</span>
<span class="n">actual:</span> <span class="mi">2</span>
<span class="n">expected:</span> <span class="mi">1</span>
<span class="n">name:</span> <span class="n">check-equal?</span>
<span class="n">location:</span> <span class="p">(</span><span class="n">#<path:/tmp/bp.rkt></span> <span class="mi">10</span> <span class="mi">0</span> <span class="mi">151</span> <span class="mi">62</span><span class="p">)</span>
<span class="n">expression:</span> <span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="mi">1</span><span class="p">)</span> <span class="mi">1</span><span class="p">)</span>
<span class="c1">; Check failure</span>
<span class="n">--------------------</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Great. But let’s say we have dozens of tests, and typing all the <code>check-equal?</code> and <code>my-function-that-increments</code> is wearisome. We think, “Aha, I can write a macro!” So we write:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">racket</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="n">rackunit</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="n">x</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._add1))" style="color: inherit">add1</a></span> <span class="n">x</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">chk</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax-case))" style="color: inherit">syntax-case</a></span> <span class="n">stx</span> <span class="p">()</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">input</span> <span class="n">expected</span><span class="p">)</span>
<span class="o">#'</span><span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="n">input</span><span class="p">)</span>
<span class="n">expected</span><span class="p">)]))</span>
<span class="p">(</span><span class="n">chk</span> <span class="mi">1</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="n">chk</span> <span class="mi">2</span> <span class="mi">1</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Much less tedious. Nice.</p>
<p>But…hey wait. The rackunit error message points to line 11:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">--------------------</span>
<span class="n">FAILURE</span>
<span class="n">actual:</span> <span class="mi">3</span>
<span class="n">expected:</span> <span class="mi">1</span>
<span class="n">name:</span> <span class="n">check-equal?</span>
<span class="n">location:</span> <span class="p">(</span><span class="n">#<path:/tmp/bp.rkt></span> <span class="mi">11</span> <span class="mi">7</span> <span class="mi">166</span> <span class="mi">80</span><span class="p">)</span>
<span class="n">expression:</span> <span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="mi">2</span><span class="p">)</span> <span class="mi">1</span><span class="p">)</span>
<span class="c1">; Check failure</span>
<span class="n">--------------------</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Line 11 isn’t where the failing <code>(chk 2 1)</code> is. It’s <em>inside our macro</em>. Gah. We wanted to write this macro because we have dozens of unit tests…but we can’t see which one of them failed? This whole idea of using a macro seems to have backfired.</p>
<p>Fortunately, this is where <code>syntax/loc</code> helps. It lets us specify the source location for the syntax returned from our macro.</p>
<p>The macro above uses <code>#'</code>, which is shorthand for <code>syntax</code>. First let’s rewrite the macro using <code>syntax</code>:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">chk</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax-case))" style="color: inherit">syntax-case</a></span> <span class="n">stx</span> <span class="p">()</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">input</span> <span class="n">expected</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax))" style="color: inherit">syntax</a></span> <span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="n">input</span><span class="p">)</span>
<span class="n">expected</span><span class="p">))]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Of course this still has the source location problem. But, we change <code>syntax</code> to <code>syntax/loc</code>, supplying it the <code>stx</code> given to our macro:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">chk</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax-case))" style="color: inherit">syntax-case</a></span> <span class="n">stx</span> <span class="p">()</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">input</span> <span class="n">expected</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax/loc))" style="color: inherit">syntax/loc</a></span> <span class="n">stx</span>
<span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="n">input</span><span class="p">)</span>
<span class="n">expected</span><span class="p">))]))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Here’s the full new sample, so that the line numbers work for this blog post:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="kn">#lang </span><span class="nn">racket</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="n">rackunit</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="n">x</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/generic-numbers.html#(def._((quote._~23~25kernel)._add1))" style="color: inherit">add1</a></span> <span class="n">x</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define-syntax))" style="color: inherit">define-syntax</a></span> <span class="p">(</span><span class="n">chk</span> <span class="n">stx</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax-case))" style="color: inherit">syntax-case</a></span> <span class="n">stx</span> <span class="p">()</span>
<span class="p">[(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt).__))" style="color: inherit">_</a></span> <span class="n">input</span> <span class="n">expected</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/stx-patterns.html#(form._((lib._racket/private/stxcase-scheme..rkt)._syntax/loc))" style="color: inherit">syntax/loc</a></span> <span class="n">stx</span>
<span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="n">input</span><span class="p">)</span>
<span class="n">expected</span><span class="p">))]))</span>
<span class="p">(</span><span class="n">chk</span> <span class="mi">1</span> <span class="mi">0</span><span class="p">)</span>
<span class="p">(</span><span class="n">chk</span> <span class="mi">2</span> <span class="mi">1</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And now rackunit has the correct source location to report, line 16:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre> 1
2
3
4
5
6
7
8
9
10</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="n">--------------------</span>
<span class="n">FAILURE</span>
<span class="n">actual:</span> <span class="mi">3</span>
<span class="n">expected:</span> <span class="mi">1</span>
<span class="n">name:</span> <span class="n">check-equal?</span>
<span class="n">location:</span> <span class="p">(</span><span class="n">#<path:/tmp/bp.rkt></span> <span class="mi">16</span> <span class="mi">0</span> <span class="mi">281</span> <span class="mi">9</span><span class="p">)</span>
<span class="n">expression:</span> <span class="p">(</span><span class="n">check-equal?</span> <span class="p">(</span><span class="n">my-function-that-increments</span> <span class="mi">2</span><span class="p">)</span> <span class="mi">1</span><span class="p">)</span>
<span class="c1">; Check failure</span>
<span class="n">--------------------</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Hopefully this shows how <code>syntax/loc</code> can help with the sort of “casual” macro you might frequently want to write.</p>
<div class="footnotes">
<ol>
<li id="syntax-loc-and-unit-tests-footnote-1-definition" class="footnote-definition">
<p>For some definition of “correctly”. <a href="#syntax-loc-and-unit-tests-footnote-1-return">↩</a></p></li></ol></div>
<footer></footer></article></div>Using call/input-urlurn:www-greghendershott-com:-2013-08-using-call-input-url.html2013-08-04T02:28:56Z2013-08-04T02:28:56ZGreg Hendershott
<div>
<article>
<header>
<h1>Using call/input-url</h1>
<p class="date-and-tags">
<time datetime="2013-08-03" pubdate="true">2013-08-03</time> :: <span class="tags"><a href="/tags/Racket.html">Racket</a>, <a href="/tags/racket-cookbook.html">racket-cookbook</a></span></p></header>
<p>When I learned Racket, one of the first things I wanted to try was doing HTTP requests. And Racket’s <code>net/url</code> module is great.</p>
<p>Racket was the first real Lisp/Scheme family language I ever learned. As a result I was focused on building blocks like ports, and assuming I would need to open and close them directly all the time. At that early stage, I also didn’t really appreciate the value of higher-order functions. So I overlooked the value of <code><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._call/input-url))" style="color: inherit">call/input-url</a></code>. I sometimes see other folks do the same, and wanted to write this short blog post.</p><!-- more-->
<p>Let’s say we want a function to take a <code>url?</code>, make an HTTP <code>GET</code> request, and return the response as a <code>string?</code>. For lack of a better name, we’ll call our function <code>fetch</code>.</p>
<p>First we need to <code>require</code> the <code>net/url</code> module:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/require.html#(form._((lib._racket/private/base..rkt)._require))" style="color: inherit">require</a></span> <span class="n">net/url</span><span class="p">)</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>I won’t keep repeating that in the various examples that follow.</p>
<p>Our first cut at <code>fetch</code> uses all the basic, obvious functions:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">fetch</span> <span class="n">url</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">in</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._get-pure-port))" style="color: inherit">get-pure-port</a></span> <span class="n">url</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">out</span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stringport.html#(def._((quote._~23~25kernel)._open-output-string))" style="color: inherit">open-output-string</a></span><span class="p">))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-lib.html#(def._((lib._racket/port..rkt)._copy-port))" style="color: inherit">copy-port</a></span> <span class="n">in</span> <span class="n">out</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/stringport.html#(def._((quote._~23~25kernel)._get-output-string))" style="color: inherit">get-output-string</a></span> <span class="n">out</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>We try using it like this:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="n">fetch</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._string-~3eurl))" style="color: inherit">string->url</a></span> <span class="s2">"http://www.racket-lang.org/"</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And it gives output like this:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="s2">"<?xml version=</span><span class="se">\"</span><span class="s2">1.0</span><span class="se">\"</span><span class="s2"> encoding=</span><span class="se">\"</span><span class="s2">utf-8</span><span class="se">\"</span><span class="s2">?></span><span class="se">\n</span><span class="s2"><!DOCTYPE html PUBLIC </span><span class="se">\"</span><span class="s2">-//W3C//DTD XHTML "</span>
<span class="c1">; ... lots more omitted ...</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Great. So this seems to work. But how can we improve it?</p>
<p>First, the business with <code>open-output-string</code>, <code>copy-port</code>, and <code>get-output-string</code> is a bit tedious. Really, we just want to change an <code>input-port?</code> into a <code>string?</code>. Turns out Racket supplies <code><a href="http://docs.racket-lang.org/reference/port-lib.html#(def._((lib._racket/port..rkt)._port-~3estring))" style="color: inherit">port->string</a></code>, which does just that. So we can simplify:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">fetch</span> <span class="n">url</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">in</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._get-pure-port))" style="color: inherit">get-pure-port</a></span> <span class="n">url</span><span class="p">))</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-lib.html#(def._((lib._racket/port..rkt)._port-~3estring))" style="color: inherit">port->string</a></span> <span class="n">in</span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>Much better. Unfortunately, there’s a problem. We don’t close the <code>input-port?</code> returned from <code>get-pure-port</code>. Let’s do that:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">fetch</span> <span class="n">url</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">in</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._get-pure-port))" style="color: inherit">get-pure-port</a></span> <span class="n">url</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin0))" style="color: inherit">begin0</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-lib.html#(def._((lib._racket/port..rkt)._port-~3estring))" style="color: inherit">port->string</a></span> <span class="n">in</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-ops.html#(def._((quote._~23~25kernel)._close-input-port))" style="color: inherit">close-input-port</a></span> <span class="n">in</span><span class="p">)))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>If you’re unfamiliar with <code><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin0))" style="color: inherit">begin0</a></code>, it’s like <code><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin))" style="color: inherit">begin</a></code> except it returns the value of the <em>first</em> expression instead of the last one. <code><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin0))" style="color: inherit">begin0</a></code> fits the pattern where you need to return a value from a resource then close/release the resource.</p>
<p>OK, but, what if an exception were thrown sometime before we reached <code>close-input-port?</code>, for example some runtime error inside <code>port->string?</code> on line 4? The port would remain open.</p>
<p>Well, we could wrap this in an exception handler:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5
6
7
8</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">fetch</span> <span class="n">url</span><span class="p">)</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="n">in</span> <span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._get-pure-port))" style="color: inherit">get-pure-port</a></span> <span class="n">url</span><span class="p">))</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/exns.html#(form._((lib._racket/private/more-scheme..rkt)._with-handlers))" style="color: inherit">with-handlers</a></span> <span class="p">([</span><span class="nb"><a href="http://docs.racket-lang.org/reference/exns.html#(def._((quote._~23~25kernel)._exn~3afail~3f))" style="color: inherit">exn:fail?</a></span> <span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._lambda))" style="color: inherit">lambda</a></span> <span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/exns.html#(def._((lib._racket/private/base..rkt)._exn))" style="color: inherit">exn</a></span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-ops.html#(def._((quote._~23~25kernel)._close-input-port))" style="color: inherit">close-input-port</a></span> <span class="n">in</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/exns.html#(def._((quote._~23~25kernel)._raise))" style="color: inherit">raise</a></span> <span class="nb"><a href="http://docs.racket-lang.org/reference/exns.html#(def._((lib._racket/private/base..rkt)._exn))" style="color: inherit">exn</a></span><span class="p">))])</span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/begin.html#(form._((quote._~23~25kernel)._begin0))" style="color: inherit">begin0</a></span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-lib.html#(def._((lib._racket/port..rkt)._port-~3estring))" style="color: inherit">port->string</a></span> <span class="n">in</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-ops.html#(def._((quote._~23~25kernel)._close-input-port))" style="color: inherit">close-input-port</a></span> <span class="n">in</span><span class="p">))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>But this is really verbose. We’re writing a lot of boilerplate code to handle exceptions, compared to the task we care about.</p>
<p>Fortunately, Racket provides <code><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._call/input-url))" style="color: inherit">call/input-url</a></code>. It takes three arguments: a <code>url?</code>, a connection function such as <code>get-pure-port</code>, and a “handler” function to do something with the opened <code>input-port?</code>. It guarantees that the input port will be closed, even if an exception is thrown.</p>
<p>Using that:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4
5</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">fetch</span> <span class="n">url</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._call/input-url))" style="color: inherit">call/input-url</a></span> <span class="n">url</span>
<span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._get-pure-port))" style="color: inherit">get-pure-port</a></span>
<span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/lambda.html#(form._((lib._racket/private/base..rkt)._lambda))" style="color: inherit">lambda</a></span> <span class="p">(</span><span class="n">in</span><span class="p">)</span>
<span class="p">(</span><span class="nb"><a href="http://docs.racket-lang.org/reference/port-lib.html#(def._((lib._racket/port..rkt)._port-~3estring))" style="color: inherit">port->string</a></span> <span class="n">in</span><span class="p">))))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>The handler function takes an <code>input-port?</code> and returns <code>any</code> — whatever you need it to — which in turn is what <code>call/input-url</code> returns.</p>
<p>Hey wait a second. I notice that <code>port->string</code> is just such a function: <code>(input-port? . -> . any)</code>. We don’t need to wrap that in a <code>lambda</code>. We can supply it directly:</p>
<div class="brush: racket">
<table class="sourcetable">
<tbody>
<tr>
<td class="linenos">
<div class="linenodiv">
<pre>1
2
3
4</pre></div></td>
<td class="code">
<div class="source">
<pre><span></span><span class="p">(</span><span class="k"><a href="http://docs.racket-lang.org/reference/define.html#(form._((lib._racket/private/base..rkt)._define))" style="color: inherit">define</a></span> <span class="p">(</span><span class="n">fetch</span> <span class="n">url</span><span class="p">)</span>
<span class="p">(</span><span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._call/input-url))" style="color: inherit">call/input-url</a></span> <span class="n">url</span>
<span class="n"><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._get-pure-port))" style="color: inherit">get-pure-port</a></span>
<span class="nb"><a href="http://docs.racket-lang.org/reference/port-lib.html#(def._((lib._racket/port..rkt)._port-~3estring))" style="color: inherit">port->string</a></span><span class="p">))</span>
</pre></div>
</td></tr></tbody></table>
</div>
<p>And that’s the final version. This is a nice example of how using higher-order functions can result in elegant code with a clean separation of concerns.</p>
<p>tl;dr: When you need to do an HTTP <code>GET</code> in Racket, you probably want to use <code><a href="http://docs.racket-lang.org/net/url.html#(def._((lib._net/url..rkt)._call/input-url))" style="color: inherit">call/input-url</a></code>. It ensures the HTTP input port will be closed, and it nudges you into using higher-order functions.</p>
<footer></footer></article></div>