doc.txt simple string templates

_string-template.ss_: simple string templates

Danny Yoo ( /

(Index terms: _string-template_ _string_template.ss_ )


This is a module for building strings out of templates.  Think Mad
Libs, and you have the general idea of what this should do.

At the moment, string-template doesn't support many of the features
one would want out of a full-fledged template library.  In the future,
I'll try to support the features of the StringTemplate library

The main file in this package is "".


    > (require (planet "" ("dyoo" "string-template.plt")))
    > (require (lib ""))  ;; for the HASH-TABLE syntax
    > (define tmpl (make-template #<<EOF
    <head><title>This is a test.</title></head>
        <p>Hello $name$, say $friends; separator=", "$ and enter.
    > (template->string tmpl 
                     (hash-table 'equal 
                                 ("name" "traveller")
                                 ("friends" '("elbereth"
    "<html>\n<head><title>This is a test.</title></head>\n  <body>\n    <p>Hello traveller, say elbereth, frodo, beren and enter."


> make-template: string -> template
Given a string, returns a template object that can be used
to instantiate that template.

> template->string: template hash-table -> string
Given a template, and a hash-table that binds string names to values,
returns a string that is an instantiation of the template for the given
hash-table bindings.

If there's an attribute reference in the template which can't be
satisfied by the hash-table, raises an instance of

> display-template: template hash-table output-port -> void
Displays the template instantiation to the output-port.


> template
Represents a template constructed using MAKE-TEMPLATE.

> exn:template:missing-attribute
Extends exn:fail.  Includes a field ATTRIBUTE-NAME.

Template Language

The current template language is extremely minimal at the moment;
future releases will expand the language support to hopefully cover
StringTemplate's functionality.

A template is a text string with "holes".  Each of these holes is
delimited by a dollar sign '$'.  For example:

    "hello $name$"

is a template string that has a single hole in it.

If you need a literal dollar sign in the content, you can escape the
character with a backslash.  For example:

    (let ([tmpl (make-template
                 "You have \\$$amount$ dollars in your account")])
      (template->string tmpl (hash-table 'equal ("amount" 42))))

A hole will be replaced with its value at template instantiation time.
We define three types of holes:

    * variable-reference: $ {name} $

    Variable references will be replaced with the values passed into
    the second argument (the hash-table) to TEMPLATE->STRING.  Names
    are allowed to be alphanumeric.  (Possible todo: consider relaxing
    this to mzscheme's identifier rules)

    * variable-reference/separator: $ {name} ; separator = {separator} $

    Similar to variable-reference.  The bound value must be a list.
    The separator will be used between elements in the list value.

    * string: $ "[content]" $

    The value of the string will replace the whole.  In this context,
    the string may also include escape characters.

Known Bugs and Concerns

There's minimal error trapping going on at the moment.  If something
goes wrong during parsing, minimal error messages will show up.  I'll
fix these as I use the library more, because I'm sure I'll get annoyed
enough by the bad error messages to do something about it.

Also expect this library's structure to change radically as I work on
this more.  I'll make sure to bump up the PLaneT major version number
appropriately when this happens.


Thanks to the folks at; their design
looks really clean.  Thanks also to the PLT team for the very nice
parser-tools library, which makes writing this library pleasant.
Finally, thanks to the Schematics folks for SchemeUnit: unit tests are
fun when you have good library support for them.