Provided by: tcllib_1.21+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.

              Note that this method pushes a new (empty) context on the stack of  contexts  while
              it is running, and removes it on return.

              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 textutil::expander
                  1.2
                  % ::textutil::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  of  the  Tcllib  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

SEE ALSO

       [uri, 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