| THE META-HTML LANGUAGE REFERENCE MANUAL

Language Operators | [TOC] | Page Variables

## Section Intro: Macro Commands

Synopsis:

Meta-HTML contains a powerful macro facility, which allows you to define your own commands. Such commands are first-class objects in Meta-HTML; they may even supersede the compiled in definitions.

There are two types of macros that you can define. One type is a complex-tag; it consists of an opening tag, a body, and a closing tag. The other type is a simple-tag; it only has an opening tag.

You create a macro by using one of the macro-defining commands. In the body of the definition, special keywords can be placed, which affect what is produced when the macro is invoked. As a macro writer, you have logical access to the arguments passed to the macro in the opening tag, and for complex-tags, you have access to the body which appears between the opening and closing tags.

Commands:

define-container define-function define-tag | defmacro defsubst defun | defweakmacro function-def undef

### Function Documentation

`<define-container NAME [NAMED-PARAMETER...] [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]> body </define-container>` | Complex

Define NAME as a complex tag. At invocation time, various substitutions are made within BODY. Specifically, if the text string is:

- %0,%1, and so on, upto %9 are replaced with the exact text of the positional arguments that were found in the opening tag of the invocation

- %attributes is replaced by all of the arguments which appeared in the opening tag.

- %body is replaced with the exact text of the material that appeared between the opening and closing tags

- %qbody is similar to %body, but the string is first surrounded by double quotes, and double quote characters which appear in the string are escaped.

- %xbody is replaced with the evaluation of the material that appeared between the opening and closing tags

If any NAMED-PARAMETERs are supplied, the values that were passed in the opening tag are evaluated and bound to the named parameters.

A keyword argument of PACKAGE-NAME wraps the entire body of the macro in an `in-package` statement.

The keyword argument WHITESPACE can be set to the string `delete` to remove whitespace from the starts and ends of lines in the macro definition before it is stored. This effectively concatenates all of the lines of the macro definition into a single long line.

`<define-function NAME [NAMED-PARAMETER...] [PACKAGE=PACKNAME]> body </define-function>` | Complex

Define NAME as a simple tag.

The only differences between `define-function` and `define-tag` are:

1. The whitespace=delete option is assumed.
2. The NAMED-PARAMETERs are evaluated in the context of the caller, not of the definition of the defun.
3. By default, a local package is wrapped around the invocation of the defined function. This can be changed by the use of the PACKAGE=PACKNAME keyword.

    <define-function factorial num>
       <if <lt num 2> 1
          <mul num <factorial <sub num 1>>>>
    </define-function>
    .blank
    <factorial 5> --> 120

`<define-tag NAME [NAMED-PARAMETER...] [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]> body </define-tag>` | Complex

Define NAME as a simple tag. Within BODY, the values of `%0...%9` are defined to be the positional arguments that were found in the opening tag of the invocation, and `%body` is all of that material in a single string.

If any NAMED-PARAMETERs are supplied, the values that were passed in the opening tag are evaluated and bound to the named parameters.

A keyword argument of PACKAGE-NAME wraps the entire body of the macro in an `in-package` statement.

The keyword argument WHITESPACE can be set to the string `delete` to remove whitespace from the starts and ends of lines in the subst definition before it is stored. This effectively concatenates all of the lines of the subst definition into a single long line.

Also see `define-function` and `define-container`.

`<defmacro NAME [NAMED-PARAMETER...] [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]> body </defmacro>` | Complex

A synonym for `define-container`.

`<defsubst NAME [NAMED-PARAMETER...] [PACKAGE=PACKAGE-NAME] [WHITESPACE=DELETE]> body </defsubst>` | Complex

A synonym for `define-tag`.

`<defun NAME [NAMED-PARAMETER...] [PACKAGE=PACKNAME]> body </defun>` | Complex

A synonym for `define-function`.

`<defweakmacro MACRO-NAME> body </defweakmacro>` | Complex

`defweakmacro` is exactly like `defmacro`, with one exception: at invocation time, the closing tag does not have to be present -- in that case, the invocation is treated as if the definition were a `defsubst`.

This facility exists primarily to allow the redefinition of standard HTML constructs which allow the closing tag to be missing, and yet, still inexplicably operate correctly.

For example, the `<p>` tag is often used without its closing counterpart of `</p>`. If you wished to redefine `<p>` to do something special when a closing tag was found, you might write the following definition:

    <defweakmacro p>
      <verbatim><P></verbatim>
      <when %qbody> Look ma! %body See? </when>
      <verbatim></P></verbatim>
    </defweakmacro>

then, a simple `<P>` would produce `<P></P>`, while a complex invocation, such as:

    <P> this is a list </P>

produces

      <P> Look ma!  this is a list See? </P>

`<function-def NAME>` | Simple

Returns the Meta-HTML readable form of the function body stored in the user-defined function NAME.

User-defined functions are made using `defmacro`, `defsubst`, or `defun`.

`<undef NAME ...>` | Simple

Remove the definition of a user-defined `defun`, `defmacro` or `defsubst`. For every NAME that has been defined in this way, the definition is removed.

Edit Section
Function Index
Variable Index

The META-HTML Reference Manual V1.4 Copyright © 1995, 1996, Brian J. Fox, 1996, 1997 Universal Access Inc.
Found a bug? Send mail to bug-manual@metahtml.com