((( [logo]Racket )))Need Help?
AboutDownloadDocumentationPLaneTCommunityLearning
Home > dyoo > string-template.plt >  package version 1.0
doc.txt

string-template.ss: simple string templates

_string-template.ss_: simple string templates

Danny Yoo (dyoo@hkn.eecs.berkeley.edu / dyoo@cs.wpi.edu)

(Index terms: _string-template_ _string_template.ss_ )


Introduction
============

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
(http://www.stringtemplate.org/).

The main file in this package is "string-template.ss".



Example
=======

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



API
===

> 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
exn:template:missing-attribute.


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


Types
=====

> 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
======

Thanks to the folks at http://www.stringtemplate.org/; 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.