content/glyph/book/extending/interpreting.html
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 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 |
<!DOCTYPE html>
<html lang="en">
<head>
<title>Interpreting Glyph Code - Glyph</title>
<link href='http://fonts.googleapis.com/css?family=Crimson+Text:400,400italic,600,600italic,700,700italic' rel='stylesheet' type='text/css'>
<meta charset="utf-8" />
<meta name="author" content="Fabio Cevasco" />
<meta name="copyright" content="Fabio Cevasco" />
<meta name="robots" content="all, follow" />
<meta name="Revisit-After" content="2 Days" />
<meta name="language" content="en" />
<meta name="target_country" content="en-us" />
<meta name="country" content="United States" />
<meta name="readability-verification" content="XmaVzRjmcFL5Bb2Fu9TZVdDKzhA3apQdxexTB2rK"/>
<meta name="description" content="H3RALD - Fabio Cevasco's Web Site" />
<meta name="keywords" content="h3rald, fabio cevasco, glyph" />
<link rel="shortcut icon" href="/favicon.png" type="image/png" />
<meta content="44.388041;9.073248" name="ICBM" />
<link rel="stylesheet" type="text/css" href="/styles/html5reset.css" />
<link rel="stylesheet" type="text/css" href="/styles/style.css" />
<script src="http://www.google.com/jsapi?key=ABQIAAAAr6RY1Z6dchG_sX9WDLSy3xRlq2n1sm52B5HDRR5tm6o8XM18FhR56xHNNH6CsX86uN5VoTrglpyOyQ" type="text/javascript"></script>
<script src="/js/sevenup.js" type="text/javascript"></script>
<script src="/js/sevenup_black.js" type="text/javascript"></script>
<script type="text/javascript">google.load("jquery", "1");</script>
<script src="/js/jquery-timeago.js" type="text/javascript"></script>
<script src="/js/jquery-easing.js" type="text/javascript"></script>
<script src="/js/jquery-fancybox.js" type="text/javascript"></script>
<script src="/js/date.js" type="text/javascript"></script>
<script src="/js/feeds.js" type="text/javascript"></script>
<script src="/js/hyphenator.js" type="text/javascript"></script>
<script src="/js/init.js" type="text/javascript"></script>
<script src="/js/search.js" type="text/javascript"></script>
</head>
<body>
<section id="container">
<header class="page">
<nav class="home-link">
<a href="/">
<img src="/images/h3rald_small.png" alt="H3RALD" class="default"/>
<![if !IE]>
<img src="/images/h3rald_hover_small.png" alt="H3RALD" class="hover"/>
<![endif]>
</a>
</nav>
<nav class="section">
/<a href="/glyph/" rel="glyph">GLYPH</a>
</nav>
</header>
<article class="page glyph-book">
<header>
<hgroup>
<h1>Interpreting Glyph Code</h1>
<h2>Glyph</h2>
</hgroup>
</header>
<section id="body-text" class="hyphenate glyph-book">
<nav class="navigation"><a href="/glyph/book/extending/validators.html">Using Validators</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/layouts.html">Layouts</a></nav>
<p>What if you need to evaluate some Glyph code <em>within</em> a macro? Say for example you want to transform a parameter in a link, and you want to make sure that link gets validated exactly like the others, in this case, you can use the <code>interpret</code> method, as follows:</p>
<div class="CodeRay">
<div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>macro <span class="symbol">:fmi</span> <span class="keyword">do</span>
<span class="line-numbers"><a href="#n2" name="n2">2</a></span> topic, href = <span class="instance-variable">@params</span>
<span class="line-numbers"><a href="#n3" name="n3">3</a></span> link = placeholder <span class="keyword">do</span> |document|
<span class="line-numbers"><a href="#n4" name="n4">4</a></span> interpret <span class="string"><span class="delimiter">"</span><span class="content">link[</span><span class="inline"><span class="inline-delimiter">#{</span>href<span class="inline-delimiter">}</span></span><span class="content">]</span><span class="delimiter">"</span></span>
<span class="line-numbers"><a href="#n5" name="n5">5</a></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n6" name="n6">6</a></span> <span class="string"><span class="delimiter">%{</span><span class="content"><span class="fmi">for more information on </span><span class="inline"><span class="inline-delimiter">#{</span>topic<span class="inline-delimiter">}</span></span><span class="content">, see </span><span class="inline"><span class="inline-delimiter">#{</span>link<span class="inline-delimiter">}</span></span><span class="content"></span></span><span class="delimiter">}</span></span>
<span class="line-numbers"><a href="#n7" name="n7">7</a></span><span class="keyword">end</span>
</pre></div>
</div>
<p>When the <code>interpret</code> method is called, the following happens:</p>
<ol>
<li>A new Glyph document is created from the <code>String</code> passed to the method.</li>
<li>Document-specific objects (bookmarks, headers, snippet, fragments, placeholders, etc.) are passed from the main document to the new one. Because they are stored in arrays and hashes, they are passed by reference, so for example any new bookmark stored in the new document will also become available in the main document.</li>
<li>Any macro included in the <code>String</code> is evaluated, and the resulting text is returned by the method. Note that this new document does not get finalized: in other words, placeholders will be left as they are, and they’ll eventually be replaced when <em>the main document</em> is finalized.</li>
</ol>
<section class="section">
<header><h1 id="h_93">Dispatching</h1></header>
<p><a href="/glyph/book/text_editing/macro_composition.html#composition">Macro Composition</a> can be useful to remove nesting, but you can also use it to create your own macro <em>dispatchers</em>. What is a macro dispatcher? The easies way to understand this is by looking at the source code of one of them, the <a href="/glyph/book/macros/macros_core.html#m_s"><code>s</code></a> macro:</p>
<div class="CodeRay">
<div class="code"><pre><span class="line-numbers"> <a href="#n1" name="n1">1</a></span>macro <span class="symbol">:s</span> <span class="keyword">do</span>
<span class="line-numbers"> <a href="#n2" name="n2">2</a></span> dispatch <span class="keyword">do</span> |node|
<span class="line-numbers"> <a href="#n3" name="n3">3</a></span> forbidden = [<span class="symbol">:each</span>, <span class="symbol">:each_line</span>, <span class="symbol">:each_byte</span>, <span class="symbol">:upto</span>, <span class="symbol">:intern</span>, <span class="symbol">:to_sym</span>, <span class="symbol">:to_f</span>]
<span class="line-numbers"> <a href="#n4" name="n4">4</a></span> meth = node[<span class="symbol">:name</span>]
<span class="line-numbers"> <a href="#n5" name="n5">5</a></span> infer_type = lambda <span class="keyword">do</span> |str|
<span class="line-numbers"> <a href="#n6" name="n6">6</a></span> <span class="comment"># Code omitted...</span>
<span class="line-numbers"> <a href="#n7" name="n7">7</a></span> <span class="keyword">end</span>
<span class="line-numbers"> <a href="#n8" name="n8">8</a></span> macro_error <span class="string"><span class="delimiter">"</span><span class="content">Macro 's/</span><span class="inline"><span class="inline-delimiter">#{</span>meth<span class="inline-delimiter">}</span></span><span class="content">' takes at least one parameter</span><span class="delimiter">"</span></span> <span class="keyword">unless</span> node.params.length > <span class="integer">0</span>
<span class="line-numbers"> <a href="#n9" name="n9">9</a></span> macro_error <span class="string"><span class="delimiter">"</span><span class="content">String method '</span><span class="inline"><span class="inline-delimiter">#{</span>meth<span class="inline-delimiter">}</span></span><span class="content">' is not supported</span><span class="delimiter">"</span></span> <span class="keyword">if</span> meth.in?(forbidden) || meth.to_s.match(<span class="regexp"><span class="delimiter">/</span><span class="content">!$</span><span class="delimiter">/</span></span>)
<span class="line-numbers"><strong><a href="#n10" name="n10">10</a></strong></span> str = node.param(<span class="integer">0</span>).evaluate(node, <span class="symbol">:params</span> => <span class="predefined-constant">true</span>)
<span class="line-numbers"><a href="#n11" name="n11">11</a></span> <span class="keyword">begin</span>
<span class="line-numbers"><a href="#n12" name="n12">12</a></span> <span class="keyword">if</span> node.param(<span class="integer">1</span>) <span class="keyword">then</span>
<span class="line-numbers"><a href="#n13" name="n13">13</a></span> meth_params = node.params[<span class="integer">1</span>..node.params.length-<span class="integer">1</span>].map <span class="keyword">do</span> |p|
<span class="line-numbers"><a href="#n14" name="n14">14</a></span> infer_type.call(p.evaluate(node, <span class="symbol">:params</span> => <span class="predefined-constant">true</span>))
<span class="line-numbers"><a href="#n15" name="n15">15</a></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n16" name="n16">16</a></span> str.send(meth, *meth_params).to_s
<span class="line-numbers"><a href="#n17" name="n17">17</a></span> <span class="keyword">else</span>
<span class="line-numbers"><a href="#n18" name="n18">18</a></span> str.send(meth).to_s
<span class="line-numbers"><a href="#n19" name="n19">19</a></span> <span class="keyword">end</span>
<span class="line-numbers"><strong><a href="#n20" name="n20">20</a></strong></span> <span class="keyword">rescue</span> <span class="constant">Exception</span> => e
<span class="line-numbers"><a href="#n21" name="n21">21</a></span> <span class="comment"># Code omittted</span>
<span class="line-numbers"><a href="#n22" name="n22">22</a></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n23" name="n23">23</a></span> <span class="keyword">end</span>
<span class="line-numbers"><a href="#n24" name="n24">24</a></span><span class="keyword">end</span>
</pre></div>
</div>
<p>See the <code>dispatch</code> method at the very beginning? This method takes a block with a <code>node</code> parameter, corresponding to the MacroNode of the macro which is being composed with <code>s</code>. So, for example, if you write <code>s/sub[my string|/my/|your]</code> the node of a macro called <code>sub</code> will be passed to the block. Of course there’s no <code>sub</code> macro defined in Glyph, but it doesn’t matter: its name will be interpreted as the name of a method of the Ruby String class in this case, so no worries.</p>
<p>Got it? Tricky, but damn useful to create your own “dynamic” macros.</p>
</section>
<section class="section">
<header><h1 id="rewriting">Defining macros using Glyph</h1></header>
<p>While the <code>interpret</code> method is useful to evaluate Glyph code in a macro while performing other actions (storing a bookmark, checking for the presence of an anchor, etc.), in some cases it may not be necessary. If you simply want your macro to be converted into existing Glyph macro without performing any action excepting parameter substitution, you can just use the <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro within your Glyph document</p>
<p>Consider the following macro definition:</p>
<div class="CodeRay">
<div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>macro <span class="symbol">:issue</span> <span class="keyword">do</span>
<span class="line-numbers"><a href="#n2" name="n2">2</a></span> interpret <span class="string"><span class="delimiter">%{</span><span class="content"></span></span>
<span class="line-numbers"><a href="#n3" name="n3">3</a></span><span class="string"><span class="content"> tr[</span></span>
<span class="line-numbers"><a href="#n4" name="n4">4</a></span><span class="string"><span class="content"> td[/=>[http://github.com/h3rald/glyph/issues/closed#issue/</span><span class="inline"><span class="inline-delimiter">#{</span>param[<span class="integer">0</span>]<span class="inline-delimiter">}</span></span><span class="content">|#</span><span class="inline"><span class="inline-delimiter">#{</span>param(<span class="integer">0</span>)<span class="inline-delimiter">}</span></span><span class="content">]]</span></span>
<span class="line-numbers"><a href="#n5" name="n5">5</a></span><span class="string"><span class="content"> td[txt[</span><span class="inline"><span class="inline-delimiter">#{</span>param(<span class="integer">1</span>)<span class="inline-delimiter">}</span></span><span class="content">]]</span></span>
<span class="line-numbers"><a href="#n6" name="n6">6</a></span><span class="string"><span class="content"> ]</span></span>
<span class="line-numbers"><a href="#n7" name="n7">7</a></span><span class="string"><span class="content"> </span><span class="delimiter">}</span></span>
<span class="line-numbers"><a href="#n8" name="n8">8</a></span><span class="keyword">end</span>
</pre></div>
</div>
<p>The <code>issue</code> macro is only rewriting existing Glyph code around the two parameters provided. In this case, it is possible to do exactly the same thing using the <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro (aliased by @def:@):</p>
<div class="CodeRay">
<div class="code"><pre><span class="line-numbers"><a href="#n1" name="n1">1</a></span>define:[issue|
<span class="line-numbers"><a href="#n2" name="n2">2</a></span> tr[
<span class="line-numbers"><a href="#n3" name="n3">3</a></span> td[/=<span class="error">></span>[http://github.com/h3rald/glyph/issues/closed#issue/{{0}}|#{{0}}]]
<span class="line-numbers"><a href="#n4" name="n4">4</a></span> td[txt[{{1}}]]
<span class="line-numbers"><a href="#n5" name="n5">5</a></span> ]
<span class="line-numbers"><a href="#n6" name="n6">6</a></span>]
</pre></div>
</div>
<p>Within the <a href="/glyph/book/macros/macros_core.html#m_define_"><code>define:</code></a> macro, it is possible to use a special syntax to call the <code>raw_attr</code> or <code>raw_param</code> methods: <br />
<code>{{</code><em>parameter_number</em> or <em>attribute_name</em><code>}}</code></p>
</section>
<nav class="navigation"><a href="/glyph/book/extending/validators.html">Using Validators</a> | <a href="/glyph/book/index.html">Contents</a> | <a href="/glyph/book/extending/layouts.html">Layouts</a></nav>
<nav id="sharing-buttons">
<a href="http://twitter.com/share" class="twitter-share-button" data-count="horizontal" data-via="h3rald">Tweet</a>
<script type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>
<g:plusone size="medium"></g:plusone>
<script type="text/javascript">
(function() {
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
po.src = 'https://apis.google.com/js/plusone.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
})();
</script>
</nav>
</section>
</article>
<footer>
<section class="ads">
<script type="text/javascript"><!--
google_ad_client = "pub-2871497824158668";
/* 728x90, created 9/10/10 */
google_ad_slot = "3963343166";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript" src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
</section>
<section>
<nav>
<a href="/about/">ABOUT</a>|<a href="/contact/">CONTACT</a>
</nav>
<p>H3RALD Web Site v8.1.2 © 2004 — 2011 <em>Fabio Cevasco</em></p>
</section>
</footer>
</section><!-- #container end -->
<!-- Start Google Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-18587377-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
<!-- End Google Analytics -->
<!-- Start of StatCounter Code -->
<script type="text/javascript">
var sc_project=6193656;
var sc_invisible=1;
var sc_security="57f7ee2a";
</script>
<script type="text/javascript" src="http://www.statcounter.com/counter/counter_xhtml.js"></script>
<!-- End of StatCounter Code -->
</body>
</html>
|