tcl-quill 0.3.0: Quill Project Automation System for Tcl/Tk

macro(n): Safe Macro Processor -- quill(n)

SYNOPSIS
DESCRIPTION
COMMANDS
INSTANCE COMMANDS
MACROS
AUTHOR
SEE ALSO

SYNOPSIS

package require quill 0.3.0
namespace import ::quill::*
macro name ?option value...?
obj cappend text
obj cget varname
obj cis cname
obj cname
obj cpop cname
obj cpush cname
obj cset varname value
obj cvar varname
obj errmode newErrmode
obj lb
obj rb
obj textcmd newTextCmd
obj where
obj eval args...
obj alias srcCmd ?targetCmd args...?
obj proc name arglist body
obj clone srcProc targetProc
obj ensemble name
obj smartalias name syntax minArgs maxArgs prefix
obj expand text
obj expandfile filename
obj expandonce text
obj macroset macroset
obj pass
obj reset
<do script>
<expand text>
<macro subcommand ?args...?>
<pass>
<template args...>
<tsubst args...>

DESCRIPTION

The Tcllib package textutil::expander is a useful too for building documentation; however, by default it expands macros in the main interpreter. It is possible use a slave interpreter, but error messages for macros aliased into the slave are ugly. In addition, one usually wants two-pass expansion, and textutil::expander doesn't provide this out-of-the-box. This package combines textutil::expander with smartinterp(n) to provide a more helpful infrastructure for macro processing.

COMMANDS

macro(n) defines the following commands:

macro name ?option value...?
This command creates a new instance of macro(n) called name, returning the fully-qualified name. The following options are available:

-brackets pair
This option specifies the left and right macro expansion brackets as a two-item list. The default brackets are "<" and ">".

-commands all|safe|none
This option determines which Tcl commands are available in the slave interpreter. By default, all standard Tcl commands are available. If safe is specified, macro(n) creates a "safe" interpreter; and if none is specified, macro(n) begins with a "safe" interpreter and then removes all commands from the global namespace.

-passcommand commmand
This option specifies a command to call when the first expansion pass is complete but before the second pass begins. This allows the client to build up metadata during the first pass and then operate on it (e.g., to define section numbers) before the second pass begins.

INSTANCE COMMANDS

An instance of macro(n) provides the following subcommands:
obj cappend text
obj cget varname
obj cis cname
obj cname
obj cpop cname
obj cpush cname
obj cset varname value
obj cvar varname
obj errmode newErrmode
obj lb
obj rb
obj textcmd newTextCmd
obj where
These commands are all delegated to the object's internal instance of textutil::expander. See the textutil::expander man page for details.

obj eval args...
obj alias srcCmd ?targetCmd args...?
obj proc name arglist body
obj clone srcProc targetProc
obj ensemble name
obj smartalias name syntax minArgs maxArgs prefix
These commands are all delegated to the object's internal instance of smartinterp(n). proc, clone, and smartalias are especially useful for defining macros. See the smartinterp(n) man page for details.

obj expand text
Performs a two-pass expansion of the text, and returns the result.

Neither this command nor expandfile should be called by any of the macros embedded in text; use expandonce instead.

obj expandfile filename
Performs a two-pass expansion of the text in filename, and returns the result.

Neither this command nor expand should be called by any of the macros embedded in the filename's text; use expandonce instead.

obj expandonce text
It is sometimes useful for a macro to expand one or more of its arguments. This command should be used for that purpose.

obj macroset macroset
Registers a macroset(i) command or command prefix with the object. The macro set's macros will be defined automatically on reset.

obj pass
During macro expansion, returns the current pass number, 1 or 2.

obj reset
Re-initializes the macro evaluation interpreter, leaving it in a clean state. The client will need to redefine any macros.

MACROS

macro(n) defines the following macros by default:

<do script>
Evaluates the script in the context of the macro expansion interpreter, and returns nothing. Text to be expanded can define its own macros using this mechanism:

...
<do {
    proc hello {name} { return "Hello, $name!" }
}>
...
<expand text>
Expands text and returns the result. This is useful for macros that take a body of text: they can expand macros recursively.

<macro subcommand ?args...?>
This "macro" gives access to the macro processor itself, and allows macros defined as procs within the instance's interpreter to access commands like cpush and cpop.

<pass>
Returns the pass number, 1 or 2. Clients often use pass 1 to scan the input, building indices, and then do the formatting proper in pass 2.

<template args...>
<tsubst args...>
Template support; see template(n) for details.

AUTHOR

Will Duquette

SEE ALSO

quill(n), smartinterp(n), manpage(n).
Generated from macro.manpage on Sat Nov 08 09:38:04 PST 2014