Provided by: tcllib_1.14-dfsg-1_all bug

NAME

       textutil::expander - Procedures to process templates and expand text.

SYNOPSIS

       package require Tcl  8.2

       package require textutil::expander  ?1.3.1?

       ::textutil::expander expanderName

       expanderName cappend text

       expanderName cget varname

       expanderName cis cname

       expanderName cname

       expanderName cpop cname

       expanderName ctopandclear

       expanderName cpush cname

       expanderName cset varname value

       expanderName cvar varname

       expanderName errmode newErrmode

       expanderName evalcmd ?newEvalCmd?

       expanderName expand string ?brackets?

       expanderName lb ?newbracket?

       expanderName rb ?newbracket?

       expanderName reset

       expanderName setbrackets lbrack rbrack

       expanderName textcmd ?newTextCmd?

       expanderName where

_________________________________________________________________

DESCRIPTION

       The  Tcl  subst  command  is  often used to support a kind of template processing. Given a
       string with embedded variables or function calls, subst will interpolate the variable  and
       function values, returning the new string:

                  % set greeting "Howdy"
                  Howdy
                  % proc place {} {return "World"}
                  % subst {$greeting, [place]!}
                  Howdy, World!
                  %

       By  defining  a  suitable  set  of  Tcl  commands, subst can be used to implement a markup
       language similar to HTML.

       The subst command is efficient, but it has three  drawbacks  for  this  kind  of  template
       processing:

       ·      There's  no  way  to  identify  and process the plain text between two embedded Tcl
              commands; that makes it difficult to handle plain text in a context-sensitive way.

       ·      Embedded commands are necessarily bracketed by [ and ]; it's convenient to be  able
              to  choose  different  brackets in special cases.  Someone producing web pages that
              include a large quantity of Tcl code examples might easily prefer to use << and  >>
              as the embedded code delimiters instead.

       ·      There's  no  easy  way  to  handle  incremental input, as one might wish to do when
              reading data from a socket.

       At present, expander solves the first two problems; eventually it  will  solve  the  third
       problem as well.

       The  following  section describes the command API to the expander; this is followed by the
       tutorial sections, see TUTORIAL.

EXPANDER API

       The textutil::expander package provides only one command, described below. The rest of the
       section  is taken by a description of the methods for the expander objects created by this
       command.

       ::textutil::expander expanderName
              The command creates a new expander object with an associated Tcl command whose name
              is  expanderName.  This  command  may  be  used to invoke various operations on the
              graph. If the expanderName is not fully qualified it is interpreted as relative  to
              the current namespace.  The command has the following general form:

              expanderName option ?arg arg ...?

              Option and the args determine the exact behavior of the command.

       The following commands are possible for expander objects:

       expanderName cappend text
              Appends  a string to the output in the current context.  This command should rarely
              be used by macros or application code.

       expanderName cget varname
              Retrieves the value of variable varname, defined in the current context.

       expanderName cis cname
              Determines whether or not the name of the current context is cname.

       expanderName cname
              Returns the name of the current context.

       expanderName cpop cname
              Pops a context from the context stack, returning all  accumulated  output  in  that
              context.  The context must be named cname, or an error results.

       expanderName ctopandclear
              Returns  the  output  currently  captured  in  the  topmost context and clears that
              buffer. This is similar to a combination of cpop followed  by  cpush,  except  that
              internal state (brackets) is preserved here.

       expanderName cpush cname
              Pushes a context named cname onto the context stack.  The context must be popped by
              cpop before expansion ends or an error results.

       expanderName cset varname value
              Sets variable varname to value in the current context.

       expanderName cvar varname
              Retrieves the internal variable name of context variable varname; this  allows  the
              variable to be passed to commands like lappend.

       expanderName errmode newErrmode
              Sets  the  macro expansion error mode to one of nothing, macro, error, or fail; the
              default value is fail.  The value determines what the expander does if an error  is
              detected during expansion of a macro.

              fail   The  error  propagates  normally  and  can  be  caught  or  ignored  by  the
                     application.

              error  The macro expands into a detailed error message, and expansion continues.

              macro  The macro expands to itself; that is, it  is  passed  along  to  the  output
                     unchanged.

              nothing
                     The macro expands to the empty string, and is effectively ignored.

       expanderName evalcmd ?newEvalCmd?
              Returns  the  current  evaluation  command,  which  defaults  to  uplevel  #0.   If
              specified, newEvalCmd will be saved for future use and then returned; it must be  a
              Tcl command expecting one additional argument: the macro to evaluate.

       expanderName expand string ?brackets?
              Expands the input string, replacing embedded macros with their expanded values, and
              returns the expanded string.

              If brackets is given, it must be a list of two strings; the items will be  used  as
              the left and right macro expansion bracket sequences for this expansion only.

       expanderName lb ?newbracket?
              Returns  the  current value of the left macro expansion bracket; this is for use as
              or within a macro, when the bracket needs to be included in the  output  text.   If
              newbracket is specified, it becomes the new bracket, and is returned.

       expanderName rb ?newbracket?
              Returns  the current value of the right macro expansion bracket; this is for use as
              or within a macro, when the bracket needs to be included in the  output  text.   If
              newbracket is specified, it becomes the new bracket, and is returned.

       expanderName reset
              Resets  all  expander settings to their initial values.  Unusual results are likely
              if this command is called from within a call to expand.

       expanderName setbrackets lbrack rbrack
              Sets the left and right macro expansion brackets.  This command is for  use  as  or
              within  a macro, or to permanently change the bracket definitions.  By default, the
              brackets are [ and ], but any non-empty string can be used; for example, < and > or
              (* and *) or even Hello, and World!.

       expanderName textcmd ?newTextCmd?
              Returns  the current command for processing plain text, which defaults to the empty
              string, meaning identity. If specified, newTextCmd will be saved for future use and
              then returned; it must be a Tcl command expecting one additional argument: the text
              to process. The expander object will this command for all plain text it encounters,
              giving  the  user  of  the  object  the  ability  to process all plain text in some
              standard way before writing it to the output. The object expects that  the  command
              returns the processed plain text.

              Note that the combination of "textcmd plaintext" is run through the evalcmd for the
              actual evaluation. In other words, the  textcmd  is  treated  as  a  special  macro
              implicitly surrounding all plain text in the template.

       expanderName where
              Returns  a  three-element list containing the current character position, line, and
              column the expander is at in the processing of the current input string.

TUTORIAL

   BASICS
       To begin, create an expander object:

                  % package require expander
                  1.2
                  % ::expander::expander myexp
                  ::myexp
                  %

       The created ::myexp object can be used to expand  text  strings  containing  embedded  Tcl
       commands.   By  default,  embedded  commands  are delimited by square brackets.  Note that
       expander doesn't attempt to interpolate variables, since variables can  be  referenced  by
       embedded commands:

                  % set greeting "Howdy"
                  Howdy
                  % proc place {} {return "World"}
                  % ::myexp expand {[set greeting], [place]!}
                  Howdy, World!
                  %

   EMBEDDING MACROS
       An  expander  macro  is  simply  a  Tcl  script  embedded  within a text string.  Expander
       evaluates the script in the global context, and replaces it with its result  string.   For
       example,

                  % set greetings {Howdy Hi "What's up"}
                  Howdy Hi "What's up"
                  % ::myexp expand {There are many ways to say "Hello, World!":
                  [set result {}
                  foreach greeting $greetings {
                append result "$greeting, World!\\n"
                  }
                  set result]
                  And that's just a small sample!}
                  There are many ways to say "Hello, World!":
                  Howdy, World!
                  Hi, World!
                  What's up, World!

                  And that's just a small sample!
                  %

   WRITING MACRO COMMANDS
       More  typically,  macro commands are used to create a markup language.  A macro command is
       just a Tcl command that returns an output string.  For example,  expand  can  be  used  to
       implement  a  generic document markup language that can be retargeted to HTML or any other
       output format:

                  % proc bold {} {return "<b>"}
                  % proc /bold {} {return "</b>"}
                  % ::myexp expand {Some of this text is in [bold]boldface[/bold]}
                  Some of this text is in <b>boldface</b>
                  %

       The above definitions of bold and  /bold  returns  HTML,  but  such  commands  can  be  as
       complicated as needed; they could, for example, decide what to return based on the desired
       output format.

   CHANGING THE EXPANSION BRACKETS
       By default, embedded macros are enclosed in square brackets, [ and ].  If square  brackets
       need  to  be  included  in  the  output,  the  input  can  contain the lb and rb commands.
       Alternatively, or if square brackets are objectionable for some other  reason,  the  macro
       expansion brackets can be changed to any pair of non-empty strings.

       The  setbrackets  command  changes  the  brackets permanently.  For example, you can write
       pseudo-html by change them to < and >:

                  % ::myexp setbrackets < >
                  % ::myexp expand {<bold>This is boldface</bold>}
                  <b>This is boldface</b>

       Alternatively, you can change the expansion brackets temporarily by  passing  the  desired
       brackets to the expand command:

                  % ::myexp setbrackets "\\[" "\\]"
                  % ::myexp expand {<bold>This is boldface</bold>} {< >}
                  <b>This is boldface</b>
                  %

   CUSTOMIZED MACRO EXPANSION
       By  default,  macros  are evaluated using the Tcl uplevel #0 command, so that the embedded
       code executes in the global context.  The application can provide a  different  evaluation
       command using evalcmd; this allows the application to use a safe interpreter, for example,
       or even to evaluated something other than Tcl code.  There is one caveat: to be recognized
       as valid, a macro must return 1 when passed to Tcl's "info complete" command.

       For example, the following code "evaluates" each macro by returning the macro text itself.

                  proc identity {macro} {return $macro}
                  ::myexp evalcmd identity

   USING THE CONTEXT STACK
       Often  it's  desirable  to  define a pair of macros which operate in some way on the plain
       text between them.  Consider a set of macros for adding footnotes to a web page: one could
       have implement something like this:

                  Dr. Pangloss, however, thinks that this is the best of all
                  possible worlds.[footnote "See Candide, by Voltaire"]

       The  footnote  macro would, presumably, assign a number to this footnote and save the text
       to be formatted later on.  However, this solution is ugly if the footnote text is long  or
       should contain additional markup.  Consider the following instead:

                  Dr. Pangloss, however, thinks that this is the best of all
                  possible worlds.[footnote]See [bookTitle "Candide"], by
                  [authorsName "Voltaire"], for more information.[/footnote]

       Here  the footnote text is contained between footnote and /footnote macros, continues onto
       a second line, and contains several macros of its own.  This  is  both  clearer  and  more
       flexible;  however,  with  the  features  presented  so  far there's no easy way to do it.
       That's the purpose of the context stack.

       All macro expansion takes place in a particular context.  Here, the footnote macro  pushes
       a  new  context  onto  the context stack.  Then, all expanded text gets placed in that new
       context.  /footnote retrieves it by popping the context.  Here's a skeleton implementation
       of these two macros:

                  proc footnote {} {
                      ::myexp cpush footnote
                  }

                  proc /footnote {} {
                      set footnoteText [::myexp cpop footnote]

                      # Save the footnote text, and return an appropriate footnote
                      # number and link.
                  }

       The cpush command pushes a new context onto the stack; the argument is the context's name.
       It can be any string, but would typically be the name of the  macro  itself.   Then,  cpop
       verifies  that  the  current  context has the expected name, pops it off of the stack, and
       returns the accumulated text.

       Expand provides several other tools related to the context stack.  Suppose the first macro
       in  a  context  pair takes arguments or computes values which the second macro in the pair
       needs.  After calling cpush, the first macro can define one or more context variables; the
       second macro can retrieve their values any time before calling cpop.  For example, suppose
       the document must specify the footnote number explicitly:

                  proc footnote {footnoteNumber} {
                      ::myexp cpush footnote
                      ::myexp csave num $footnoteNumber
                      # Return an appropriate link
                  }

                  proc /footnote {} {
                      set footnoteNumber [::myexp cget num]
                      set footnoteText [::myexp cpop footnote]

                      # Save the footnote text and its footnoteNumber for future
                      # output.
                  }

       At times, it might be desirable to define macros that are valid only within  a  particular
       context  pair;  such  macros  should  verify  that they are only called within the correct
       context using either cis or cname.

HISTORY

       expander was written by William H. Duquette; it is a repackaging of the central  algorithm
       of the expand macro processing tool.

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.  Please report such in the category  textutil  ::  expander  of  the  Tcllib  SF
       Trackers  [http://sourceforge.net/tracker/?group_id=12883].   Please also report any ideas
       for enhancements you may have for either package and/or documentation.

SEE ALSO

       http://www.wjduquette.com/expand, regexp, split, string

KEYWORDS

       string, template processing, text expansion

CATEGORY

       Documentation tools

COPYRIGHT

       Copyright (c) William H. Duquette, http://www.wjduquette.com/expand