Curl macros introduction (part 1)

[RobertShiplett]

This series is about Curl macros

Macros allow you to create both very simple and very complex results in Curl web pages, in Curl applications, and in Curl scripts. Most often they hide complexity from the user of the macro and keep markup simple.

You use a macro in Curl just as you would use any other Curl expression.

{paragraph This is a text procedure }
{my-para This might be a macro or a user-defined text-format or text-proc }
{ml-para "Using quotes is a clue that it might be a proc, but it could be a macro"}
{paragraph Usually only by looking in the docs or user code will you know.}

Default Curl expressions (from the Curl library packages) which begin with {define- are macros. The Curl documentation clearly indicates which expression prefixes are macros both in the index and the respective macro pages. The live-code in the docs in built using the {example } macro.

Expressions with arguments not separated by commas or separated by other characters would be macros (but I suggest using commas in your macros and in what follows I try to show why.)

A macro is used to define new macros: it is {define-macro } and it gets its power from two other macros, those being {syntax-switch } and {expand-template }.

A macro call is replaced by the source code corresponding to the value which the macro returns (although macros do not declare a return value, they use {return } expressions.

In a package write:

Code:

{define-macro public {uc ?txt:text}
    {return {expand-template {{String ?txt}.to-upper-clone}}}
}

In an applet write:

Code:

{import uc from MY.MACROS}
{uc "this quoted text will print in caps without the quotes"}

THIS QUOTED TEXT WILL PRINT IN CAPS WITHOUT THE QUOTES

Note: Curl is an expression-based language, but macros may identify some expressions as statements. Examples are let and set expressions which were not surrounded by curly-braces for your convenience or other expressions where curl-braces were not required. Macro pattern case logic can recognize MyClass.myClassProc as a BinaryOp. But we will set all these details to one side for now.