macro(n): Safe Macro Processor -- quill(n)
SYNOPSIS
DESCRIPTION
COMMANDS
INSTANCE COMMANDS
MACROS
AUTHOR
SEE ALSO
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...>
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.
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.
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.
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.
Will Duquette
quill(n), smartinterp(n), manpage(n).
Generated from macro.manpage on Sat Nov 08 09:29:58 PST 2014