Macros

Macros are a powerful feature which enables you to create shortcuts for often used text. As you can also pass arguments to macros, it is even possible to create templates for whole pages.

General Syntax

Macros can be defined like

<$macro MacroName [ modifiers ] [ attributes ] >

...macro text...

</$macro>

Here are some examples of macro definitions:

Use as Shortcuts

You can define a macro called Hugo-Address that only is a shortcut for your email-address like

<$macro Hugo-Address>
hugo@some.where
</$macro>

So every time, you insert the macro-tag <Hugo-Address> in your hsc-source, it will be replaced by

hugo@some.where

in the html-object.

Container Macros

Container macros allow you to create a macros with a text before and after the content. While the preceding/succeeding text is specified with the macro declaration, the content is assigned during the macro call.

To declare a macro as container, you have to specify the modifier ``/CLOSE''. To insert the contents, use the special tag <$content>.

For example, one could declare his own ``logical'' style. Below a macro <FILE> will be created, which can be used to render filenames:

<$macro FILE /Close><I><$content></I></$macro>

Your new style can be used like all other styles:

  ..open the file <FILE>hugo.txt</FILE> and..

In this case, filenames will be rendered italic:

..open the file hugo.txt and..

It should be rather obvious how this one works: When calling the macro using <FILE>hugo.txt</FILE>, hsc will scan the input until it reaches a </FILE>. Anything between the corresponding start and end tag will be used as content, in this case ``hugo.txt''.

Now the macro text will be interpreted: The first part is easy, a simple <I> will be inserted. After that, a <$content> shows up, and the content read before will be inserted. In this case, this is a simple plain text, but of course you could also use tags or even other (container) macros. At the end of the macro, a closing </I> is appended, and the macro call exits.

You can use <$content> multiple times inside the same macro, too.

Macros with Attributes

Take a look at this example:

<$macro Button.Next NxtRef:uri>
<A HREF=(NxtRef)><IMG SRC=":image/next.gif" ALT="Next"></A>
</$macro>

This defines a macro that defines a button that references to the next page. As every page has its own next page, you can set one attribute for this macro: NXTREF, which is the URI that should be referenced as the "next" page.

So an example usage of this macro would be:

  <Button.Next NXTREF=":features/rplcent.html">

which will give the button seen below:

Note that the value of NXTREF is passed to the HREF attribute within the <A> tag when the macro is extracted.

If you wonder, what HREF=(NxtRef) (see above) should mean: This sets HREF with the value stored in NxtRef. For details, read the section about expressions.

Nesting Container Macros

You should be aware that the macro content (the text specified between the corresponding start and end macro tag) can not access attributes which have been declared for the macro text (the text which is assigned to the macro while declaring it using <$macro>).

For example:

<$macro sepp /close hugo:string>
sepp   : hugo=<(hugo)>
<$content>
sepp   : hugo=<(hugo)>
</$macro>

<$define hugo:string="content's hugo">

<sepp hugo="sepp's hugo">
content: hugo=<(hugo)>
</sepp>

will result in


sepp   : hugo=sepp's hugo

content: hugo=content's hugo
sepp   : hugo=sepp's hugo

The line

content: hugo=<(hugo)>

does not - as some might have expected - access the attribute hugo passed to the container macro <sepp> just before, but still reads the attribute hugo declared above using <$define>.

The reason for this shows up soon when you start using container macros inside container macros: every time a <$content> shows up while just processing a <$content>, it does not make much sense to include the same content as just before. Instead, the parser uses the content passed to the previous but one container macro. For example:

<$macro hinz /close>
hinz=( <$content> )
</$macro>

<$macro kunz /close>
kunz=( <$content> )
</$macro>

<hinz><kunz>...some text...</kunz></hinz>

will result in


hinz=( kunz=( ...some text... ) )

Macros inside Macros

Currently, locale macros are not supported. If you declare a macro inside a macro, the inner macro will be declared when the outer macro is called. For example:

<$macro outer-sepp>
  now in outer sepp

  <* define inner-sepp *>
  <$macro inner-sepp>
    now in inner sepp
  </$macro>

  <* use inner-sepp *>
  <inner-sepp>
</$macro>

<outer-sepp>

will result in

  now in outer sepp

    
        now in inner sepp

At the moment you can call <inner-sepp> even outside of <outer-sepp>, as it is defined globally. When calling <outer-sepp> another time, you will receive a message #59, as this tries to redefine <inner-sepp>.

Obviously this behaviour doesn't make sense, but local macros are not supported in this release.