Glyph - Interpreting Glyph Code

What if you need to evaluate some Glyph code within 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 interpret method, as follows:

1macro :fmi do
2  topic, href = @params
3  link = placeholder do |document| 
4    interpret "link[#{href}]"
5  end
6  %{<span class="fmi">for more information on #{topic}, see #{link}</span>}
7end

When the interpret method is called, the following happens:

  1. A new Glyph document is created from the String passed to the method.
  2. 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.
  3. Any macro included in the String 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 the main document is finalized.

Dispatching

Macro Composition can be useful to remove nesting, but you can also use it to create your own macro dispatchers. What is a macro dispatcher? The easies way to understand this is by looking at the source code of one of them, the s macro:

 1macro :s do
 2  dispatch do |node|
 3    forbidden = [:each, :each_line, :each_byte, :upto, :intern, :to_sym, :to_f]
 4    meth = node[:name]
 5    infer_type = lambda do |str|
 6      # Code omitted...
 7    end
 8    macro_error "Macro 's/#{meth}' takes at least one parameter" unless node.params.length > 0
 9    macro_error "String method '#{meth}' is not supported" if meth.in?(forbidden) || meth.to_s.match(/!$/)
10    str = node.param(0).evaluate(node, :params => true)
11    begin
12      if node.param(1) then
13        meth_params = node.params[1..node.params.length-1].map do |p| 
14          infer_type.call(p.evaluate(node, :params => true))
15        end
16        str.send(meth, *meth_params).to_s
17      else
18        str.send(meth).to_s
19      end
20    rescue Exception => e
21      # Code omittted
22    end
23  end
24end

See the dispatch method at the very beginning? This method takes a block with a node parameter, corresponding to the MacroNode of the macro which is being composed with s. So, for example, if you write s/sub[my string|/my/|your] the node of a macro called sub will be passed to the block. Of course there’s no sub 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.

Got it? Tricky, but damn useful to create your own “dynamic” macros.

Defining macros using Glyph

While the interpret 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 define: macro within your Glyph document

Consider the following macro definition:

1macro :issue do
2  interpret %{
3    tr[
4      td[/=>[http://github.com/h3rald/glyph/issues/closed#issue/#{param[0]}|##{param(0)}]]
5      td[txt[#{param(1)}]]
6    ]
7  }
8end

The issue 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 define: macro (aliased by @def:@):

1define:[issue|
2  tr[
3    td[/=>[http://github.com/h3rald/glyph/issues/closed#issue/{{0}}|#{{0}}]]
4    td[txt[{{1}}]]
5  ]
6]

Within the define: macro, it is possible to use a special syntax to call the raw_attr or raw_param methods:
{{parameter_number or attribute_name}}