expander man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

textutil::expanderText and string utilities, macro procestextutil::expander(n)

______________________________________________________________________________

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 pro‐
       cessing. 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 imple‐
       ment 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	 quan‐
	      tity  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 pre‐
	      served here.

       expanderName cpush cname
	      Pushes  a	 context named cname onto the context stack.  The con‐
	      text 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 var‐
	      name; 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 contain‐
       ing 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 lan‐
       guage 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 accu‐
       mulated text.

       Expand provides several other tools related to the context stack.  Sup‐
       pose the first macro in a context pair takes arguments or computes val‐
       ues 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://source‐
       forge.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

textutil			     1.3.1		 textutil::expander(n)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net