txt[ 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] section. ] section[ @title[Accessing Expanded Values] @id[expanded_values] txt[ 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. ] txt[ 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. ] ] section[ @title[Accessing Raw Values] p[While accessing expanded values is simple and immediate, in some cases it may not produce the desired results. Consider the following macro definition:] highlight[=ruby| macro :nest_section do interpret %{section[ @title[A] section[ @title[B] #{value} ] ]} end =] p[And suppose to use it as follows:] highlight[=ruby| nest_section[ section[ @title[Inner Section] ... ] ] =] p[It produces the following HTML code:] highlight[=html|

A

B

Inner Section

...
=] p[Everything is fine em[except] for the header level: the heading "Inner Section" is of level 2, but it should be level 4!] p[This happens because the inner section is evaluated em[before] the code[nest_section] macro: after all, we ask for it ourselves when we call the code[value] method inside the macro definition. When the value is expanded, there are no outer sections em[yet].] p[To avoid this unwanted behavior, we can use the code[raw_value] method instead, that returns the first parameter converted back to a Glyph code string.] tip[To be on the safe side, always use code[raw_*] methods when interpreting.] txt[ 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. ] ]