Curl macros introduction (part 2)

[RobertShiplett]

Curl macro basics

A Curl macro is declared using a default macro that comes with the Curl language:

{define-macro }

which also has a more powerful version, {define-syntax } which we will look at later.
The Curl documentation states:

{define-macro [attributes] {macro-name pattern-template}
code-body
}

The default attribute is package, but public and library are also permitted.

The pattern template uses the types common to the macro {syntax-switch }. We will start with token and text.

The code body of the macro uses one or more {return } expressions and other expressions to produce the Curl source output of the macro which is then inserted into the program. The most important expression for that code block is likely to be the expression {expand-template }.
Here is a macro to insert a UNICODE ndash between two words:

Code:

{curl 7.0 package}

{curl-file-attributes character-encoding = "utf8"}
{package TIKI-MACROS,
   {compiler-directives careful? = true}
}

{def c-dash:char='\u2013'} || so-called ndash character usable in HTML as –
{def n-dash:String={String c-dash}}

{define-macro public { ndash ?t1:token, ?t2:text }
   {return
      {expand-template
         {value
            ?t1 & n-dash & ?t2
         }
      }
   }
}

In our example, the {value } expression is not needed, and is there for illustration only. A {do } expression might be used in a macro which is used to simplify a task. But the macro must return a value (try replacing the value with do in our example.) You should experiment by placing any string in quotes after our {value } expression in the macro, then after a {do } in place of that {value }.


A macro returns CurlSource to be inserted into the source file at the time that file is parsed (macro coding errors may crop up before applets are even running).


Our macro must be defined in a package outside of our source code which will use the macro. Here is that source code:

Code:

{curl 7.0 applet}
{curl-file-attributes character-encoding = "windows-latin-1"}
{applet manifest = "manifest.mcurl",
   {compiler-directives careful? = true}
}

{import  ndash  from TIKI-MACROS}

{def test:String = "this"}

{paragraph We en-dash { ndash test, "that"}}

And this is how our ndash-ed text items appear in a web page:

We en-dash this–that

Our macro has substituted the two hyphenated values into our source code.
Without the macro our code might have been

{paragraph We en-dash {value test} \u2013 that}

There are subtle differences: the latter requires a value expression and the macro version required a quoted string.

In our ndash macro, the {value } expression is not needed, and is there for illustration only. A {do } expression might be used in a macro which is used to simplify a task. But the macro must return a value (try replacing the value with do in our example.) You should experiment by placing any string in quotes after our {value } expression in the macro, then after a {do } in place of that {value }.

A macro returns CurlSource to be inserted into the source file at the time that file is parsed (macro coding errors may crop up before applets are even running).

Our {ndash } macro accepts first a token, and then consumes all remaining characters up to the first '}' - so it would be easier just to use two tokens, or two identifiers or two expressions, but here we illustrate the singular use of text as a syntax-switch pattern type. Our parameters are separated by a comma, but we could have been cute and used an ordinary keyboard hyphen - or nothing. The comma is the common delimiter to convey intent and facilitate documentation.