Glyph - Parameters and Attributes

Perhaps the most common things to do in a macro definition is accessing parameters and attributes. When doing so, it is important to consider whether we want to retrieve the raw value of and attribute or parameter or its expanded value. The difference between the two will become clearer in the following sections and also in the Interpreting Glyph Code section.

Accessing Expanded Values

Normally, you just want to get the value of an attribute or parameter and use it in the macro. This means, in other words, its expanded value, i.e. the value resulting from the expansion of the macros (if any) within the attribute or parameter.

To access expanded values, use the following methods:

  • parameter (or param): Returns the expanded value of the parameter specified by number. Other parameters are not expanded.
  • value: Returns the expanded value of the first parameter (i.e. like parameter(0)).
  • attribute (or attr): Returns the expanded value of the attribute specified by name. Other attributes are not expanded.
  • parameters (or params): Returns an array of expanded parameters.
  • attributes (or attrs): Returns a hash of expanded attributes.

Accessing Raw Values

While accessing expanded values is simple and immediate, in some cases it may not produce the desired results. Consider the following macro definition:

 1macro :nest_section do
 2  interpret %{section[
 3    @title[A]
 4    section[
 5      @title[B]
 6      #{value}
 7    ]
 8  ]}
 9end

And suppose to use it as follows:

1nest_section[
2  section[
3    @title[Inner Section]
4    ...
5  ]
6]

It produces the following HTML code:

 1<div class="section">
 2  <h2 id="h_2">A</h2>
 3  <div class="section">
 4    <h3 id="h_3">B</h3>
 5    <div class="section">
 6      <h2 id="h_1">Inner Section</h2>
 7...
 8    </div>
 9  </div>
10</div>

Everything is fine except for the header level: the heading "Inner Section" is of level 2, but it should be level 4!

This happens because the inner section is evaluated before the nest_section macro: after all, we ask for it ourselves when we call the value method inside the macro definition. When the value is expanded, there are no outer sections yet.

To avoid this unwanted behavior, we can use the raw_value method instead, that returns the first parameter converted back to a Glyph code string.

To access raw values, use the following methods:

  • raw_parameter (or raw_param): Returns the raw parameter value of the parameter specified by number.
  • raw_value: Returns the first raw parameter value (i.e. like raw_parameter(0)).
  • raw_attribute (or raw_attr): Returns the attribute value of the attribute specified by name.