Introduction
SmartText is a tool of generating text.
It can help you rapidly generating lots of text (Like code, report, configuration files, etc.).This help file is also generated by SmartText.
SmartText has a built-in text template engine (similar to Velocity), also provides a fancy and friendly GUI for better user experience.
Features :
- Use very simple Lua syntax to create template (extremely flexible!)
- Support 3 types of parameter files
- .csv
- .xml
- .lua
- Support command line arguments
- Support multi-languages(English, Chinese and Japanese)
- Friendly GUI
Getting Started
SmartText needs to be run on Windows XP/Vista/7 and above OS.
Also needs .Net Framework 4.0 and above installed.
Double click SmartText.exe to run.

Nice GUI huh? OK, let’s see what SmartText can do for you.
- Making Template File
Type following text by using any your favorite text editor, and save to "template.txt"(any location)
Hello ${person.name}!
This year ${person.name} is ${person.age} years old.
Next year ${person.name} is ${person.age+1} years old.
- Making Parameter File
Again, type following text, save to "parameter.xml"(any location).
<person>
<name>WAKU</name>
<age>29</age>
</person>
- Using SmartText
In "Template File", select saved "template.txt" file,
In "Parameter File", select saved "parameter.xml" file,
Leave "Output File" empty,
Click "Generate" button, if everything's ok, you will see the following output text :
So, smart as you can figure out SmartText's capability?
Template
SmartText's template is a skeleton of the text to be generated.
There are some marks in template, to distinguish normal text and special text.
SmartText mainly uses Lua syntax as template syntax,
So if you’re familiar with Lua, you will easily grasp SmartText's template.
if not, it's ok, you just need to learn a couple of simple structures.
Variable
By passing through the example in Getting Started, you should probably know the syntax of variable in SmartText's template:
Any valid expression of Lua, SmartText will evaluate it, and replace its representation with evaluating result.
Due to Lua, we can easily set a default value to a variable, like :
If person.name is nil (means nothing in Lua), use the value after "or"(here is a string "somebody").
Note that string can be surrounded by either double quote (") or single quote (') in Lua.
All the examples before demonstrate a very important thing, using dot (.) to express hierarchical data structure.
We look into that in more detail later in Parameter
Flow Controlling
In template, condition statement (if) and repeat statement (for) can be used to control the flow of text generating.
Because SmartText uses Lua inside (The template will be parsed into Lua code), so all the flow controlling statements use standard Lua syntax.
Only need to use #{} form.
if
See the following example:
${person.name} is a child.
#{else}
${person.name} is an adult.
#{end}
In this example, if statement is used to make decision between "child" and "adult".
By using the previous xml parameter, the output text will be:
Here is the complete syntax of if in Lua:
Lua operator can also be used in condition statement. Following is a brief table of operators.
Operator | Meaning |
== | Equal |
~= | Not Equal |
< | Less than |
> | Great than |
<= | Less than or Equal to |
>= | Great than or Equal to |
and | And |
or | Or |
not | Not |
for
For statement is very useful, it can repeatedly generate a part of text.
For statement has two forms: one numeric and one generic. Let’s see the first.
i = ${i}
#{end}
This template is so simple even need no parameter to generate result:
i = 2
i = 3
i = 4
i = 5
Following is the syntax of numeric form:
exp2 is the termination value,
exp3 is the step value, when omitted, 1 as default.
However, in practice, we often use another form: generic for
Before demonstration, we need to expand our parameter file:
<person>
<name>WAKU</name>
<age>29</age>
</person>
<person>
<name>Joey</name>
<age>2</age>
</person>
</list>
Then use generic for like this:
NAME: ${p.name} AGE: ${p.age}
#{end}
The result:
NAME: Joey AGE: 2
SmartText parses XML parameter into Lua code (detail in Parameter),
"person" is a Lua Table(used as an array here), can be accessed by "list.person".
SmartText provides a very handy function "enum" to enumerate element of a Table,
So "enum(list.peronson)" is enumerating every person, which is assigned to "p".
- Technical Details:
"enum" is a function provided by SmartText, not by Lua,
"enum" can enumerate not only array-form Table in Lua, but also .Net array, collection(List, Dictionary, etc.), and all objects that implement the IEnumerable interface,
When enumerating Lua Table, it's similar to Lua function "ipairs", the difference is, ipairs returns two values(index and value), but enum only returns value.
About specific implementation of enum function, you can view the source code of SmartText.
The syntax of generic for:
Above is all the explanations about flow controlling, mainly if and for, but SmartText and Lua have a very flexible combination,
In fact, you can insert any valid Lua statements into #{...}, they will be parsed into Lua code and executed.
You can define global variables in #{...}, and use it somewhere else.
You can even define functions, in order to implement macros like Velocity does.
Parameter
SmartText supports three types of parameter files (CSV XML LUA), even though they have similar usage (provide data to template),
but each type has its own advantages and disadvantages, you should use appropriate type on different occasions.
SmartText parses CSV and XML parameter files to Lua code. You needn't to grasp the details of parsing, only need to know how to use data correctly.
CSV parameter file is the easiest type, it has a straightforward data relationship. You can use EXCEL to edit CSV files.
The row-column form is also correspond to database table, so if you want to use a database table as a parameter, then, the CSV parameter file is most appropriate.
However, CSV parameter file cannot represent hierarchical relationships of data structure, then you need to consider the use of XML or LUA parameter files.
Example:
Template file:
${parameter[2].name} is ${parameter[2].age} years old.
Parameter file "parameter.csv":
WAKU,29
Joey,2
Generated result:
Joey is 2 years old.
Since CSV file has no root element like XML file, so SmartText uses CSV file name as a prefix of each variable.
In above example, the CSV parameter file's name is "parameter", so the prefix of each variable is "parameter".
Use subscript form "parameter[1]" to access the the line "WAKU,29" (the subscripts of Lua array starts from 1),
Access the content of column "name" is also straightforward: "parameter[1].name".
- Technical Details:
Actually, the parameter has become to a Lua Table.
SmartText parses CSV parameter files into nested Table,
Each line in CSV file (exclude the first line, it is the header line) will be parsed into a child Table.
The parsing result of the CSV file in previous example is as follows:
parameter =
{
{
['name'] = 'WAKU',
['age'] = 29,
},
{
['name'] = 'Joey',
['age'] = 2,
},
}
The above example works well, though; the template was slightly awkward,
Using generic for, you can use the following template form to get exactly the same result:
${p.name} is ${p.age} years old.
#{end}
It is worth mentioning that, SmartText uses LumenWorks parsing CSV files, LumenWorks is the best .Net CSV parser in my opinion.
XML Parameter File
XML is a very popular file format, and has good compatibility. The tree-form is very suitable to represent the data structure with a hierarchical relationship.
.Net also have an excellent support for XML, you can serialize an object to XML file, a Dataset object can be directly written to XML file and so on.
The disadvantage of XML file maybe somewhat lengthy, editing is a little inconvenient without a handy tool.
Same with CSV, SmartText parses XML parameter file into Lua code.
Example:
Template file:
${p.name} is ${p.age} years old.
${p.name} likes ${join(p.favourite_food.food)}.
#{end}
Parameter file "parameter.xml":
<person name="WAKU" age="29">
<favourite_food>
<food>rice</food>
<food>chicken</food>
</favourite_food>
</person>
<person name="Joey" age="2">
<favourite_food>
<food>milk</food>
<food>juice</food>
<food>candy</food>
</favourite_food>
</person>
</list>
Generated result:
WAKU likes rice,chicken.
Joey is 2 years old.
Joey likes milk,juice,candy.
This example demonstrates how to access the content of XML parameter correctly.
Just remember a few simple rules:
1. Variables start from the root node ("list" in the example)
2. Use DOT (.) to access attribute (like "name" and "age" in the example)
3. Also use DOT (.) to access child node
4. If a node appears more than once, it is an array, you can use the "enum" function for enumeration (like "person" and "food" in the example)
There is a new function "join", it's also provided by SmartText.
It is used to concatenate string elements of an array, the first argument is same with "enum"(.Net array, collection or Lua Table); the second argument separator is optional, default is a comma(,).
- Technical Details: li>
The parsing result of the XML file in previous example is as follows:
list =
{
['person'] =
{
{
['name'] = 'WAKU',
['age'] = 29,
['favourite_food'] =
{
['food'] =
{
'rice',
'chicken',
},
},
},
{
['name'] = 'Joey',
['age'] = 2,
['favourite_food'] =
{
['food'] =
{
'milk',
'juice',
'candy',
},
},
},
},
}
Lua parameter file is the most efficient of the three types (as both CSV and XML are required to parse into Lua code first), and also the most flexible one.
Its disadvantage is not very popular, and using it needs a certain knowledge of Lua.
Lua parameter file can get exactly same result of previous examples, just use the Lua code in the technical details as a Lua parameter file.
But there are something that CSV and XML cannot do.
Example:
Template file:
b = ${b}
c = ${c}
a + b + c = ${a + b + c}
Parameter file "parameter.lua":
b = 2
c = 3