MiniGen
From kolovos
MiniGen is a program that can generate text in any Windows-based (tested on XP/Vista) application based on the currently selected text in a non-invasive manner. As such, it can be used to define reusable templates (in Java Message Format, Velocity, FreeMarker or EGL) for a number of tasks such as coding, writing emails and text documents etc. across a wide range of Windows-based applications (Notepad, Eclipse, Visual Studio, Word, Thunderbird, Dreamweaver or whatever other application uses Ctrl-C/Ctrl-V for copying/pasting text). Minigen is non-invasive, which means you can use it without switching away from the application you are working with.
Contents |
Getting Started
You can download MiniGen here. To run it, extract minigen.zip and double-click eu.kolovos.minigen.jar (or run java -jar eu.kolovos.minigen.jar from the command prompt). MiniGen should open in the system tray (if not, you should download and install Java 1.6 and retry):
Open any text editor (e.g. Notepad) and write hello:John. Then select the text you have just written and hit Ctrl-Alt-Q.
Once you do that hello:John will be replaced with the following:
The magic hides in the hello.jmf template which is located in the templates folder and reads as follows:
Hello {1}!
Welcome to MiniGen!
When you press Ctrl-Alt-Q, MiniGen takes your current text selection from your active editor and splits it into two parts (using : as a separator): hello and John. The first part (hello) is the command, and the second part (John) is the text. Then, it tries to find a template called hello.* under the templates folder, and it passes it John as argument {1}. Then, it evaluates the template and pastes the result straight into your editor again.
The text (whatever follows the : ) is further split into a list of comma-separated fields ({2}, {3} etc) which can be used in different parts of the template. To see how this works, write hello2:John,Dimitris in your editor, select it and press Ctrl-Alt-Q.
Once you do that, hello2:John,Dimitris will be replaced with:
This happens because of the hello2.jmf template which is located in the templates folder and reads as follows:
Hello {1},
Welcome to MiniGen!
Best regards,
{2}
Both templates above follow the Java Message Format, and are essentially evaluated using a find-and-replace mechanism (e.g. {1}->John, {2}->Dimitris etc), although some formatting instructions are available. For more details on the Java Message Format you can have a look at the official documentation page.
Advanced Templates
While the Java Message Format is very useful for simple find-and-replace templates it doesn't go much further than that. To enable the construction of complex templates, MiniGen also supports the Epsilon Generation Language (EGL), a fully-featured, template-based text generation language. Similarly to Java Message Format templates which are stored in .jmf files, EGL templates are stored in .egl files under the templates folder. To see how the EGL templates work, write and select prop:name,String in your editor (we'll use Eclipse for this example, but any Java - or other - editor can be used instead).
Then hit Ctrl-Alt-Q and the contents of the editor become like this:
So, from the prop:name,String input text, we have generated a protected field, a setter and a getter using the prop.egl template (located under templates/java):
[%if (fields.size() = 2){%]
protected [%=fields.at(1)%] [%=fields.at(0)%];
public void set[%=fields.at(0).firstToUpperCase()%]([%=fields.at(1)%] [%=fields.at(0)%]) {
this.[%=fields.at(0)%] = [%=fields.at(0)%];
}
public [%=fields.at(1)%] get[%=fields.at(0).firstToUpperCase()%]() {
return [%=fields.at(0)%];
}
[%}else if (fields.size() = 3){%]
protected [%=fields.at(1)%]<[%=fields.at(2)%]> [%=fields.at(0)%];
public void set[%=fields.at(0).firstToUpperCase()%]([%=fields.at(1)%]<[%=fields.at(2)%]> [%=fields.at(0)%]) {
this.[%=fields.at(0)%] = [%=fields.at(0)%];
}
public [%=fields.at(1)%]<[%=fields.at(2)%]> get[%=fields.at(0).firstToUpperCase()%]() {
return [%=fields.at(0)%];
}
[%}%]
EGL is really similar to web-based scripting languages such as ASP, JSP, PHP etc. It uses [% and %] to separate instructions from static text (similarly to the <%%> of ASP and <??> of PHP). If you are already familiar with one of these languages you should have no problem reading and writing EGL too. A complete manual of EGL (and its expression language - called Epsilon Object Language (EOL) - is available in the [epsilonlabs:Book Epsilon Book]).
In EGL templates, the user has scripting access to the following objects:
dataset: a dataset contains a number of selected rows (accessible using dataset.rows or simply rows)
rows: a collection of all the rows of the dataset. Each row contains a collection of fields (accessible using row.fields).
fields: a collection of all the fields of the dataset (from all rows).
text: the complete text selected (apart from the command). For example in the above example, text holds the value of "name,String".
In this example we demonstrate how multiple rows can be used. In this example we will transform a multi-line text into a simple HTML table. We open Notepad again and write and select:
we press Ctrl-Alt-Q and we get the following HTML table
This is due to the htable.egl template which is located in the templates/html folder
<table>
[%for (row in rows){%]
<tr>
[%for (field in row.fields){%]
<td>[%=field%]</td>
[%}%]
</tr>
[%}%]
</table>
Other template languages supported by MiniGen
Beyond EGL, MiniGen also supports Velocity (*.vm) and FreeMarker (*.fm) templates, which operate similarly to the EGL templates discussed above. You can find a reference of the Velocity template language here and a reference of the FreeMarker language here.
Creating your own templates
The whole point of Minigen is to allow you to write your own templates for your own tasks. To create a new template, right click the MiniGen icon in the system tray and select the Open templates folder item.
This will take you to the folder where templates are stored. Wherever you want (directly under templates or in one of its sub-folders) create a new file called mytemplate.jmf, open it using notepad and copy and paste the following text:
This is my first template!
{1}
Save the template, and then right click the MiniGen icon again and click the Refresh templates item
Then, open a new notepad and write and select mytemplate:MyName and hit Ctrl-Alt-Q. If everything goes well, your text will be replaced with the text generated from the template. However, if you forget to click Refresh, you will get a popup message like the following:
If your template has a logical error - or the arguments are incorrect - and as a result no text is generated from it (e.g. prop:name) you will get the following message and your text will not be replaced:
Finally, if your template has a syntax or logical error which prevents its correct execution, you will get a message providing details about the nature of the error like the following:
Documenting and Browsing your Templates
Chances are that unless you are using a template all the time, soon after you write it you'll forget its name or how it should be called. To overcome this issue, MiniGen provides a template browser. To bring up the browser, you can double-click the icon in the system tray.
On the left hand, the browser has a tree through which you can browse your templates. When you select a template, on the right hand you see its documentation, its source code, and a sandbox where you can experiment with different calls of the template. To document a template, you need to create a file named after the template, with a .txt extension. For example, hello.jmf.txt documents the hello.jmf template displayed above. The contents of the hello.jmf.txt file look like this:
A basic hello world example ***hello:John***
So first comes a description followed by a list of examples enclosed in three stars. From this file, the HTML page in the right hand side of the browser is generated on the fly: the description goes under the summary heading and each example is evaluated and presented in its original form (orange area) and in it's expanded form (yellow area).
Credits
MiniGen uses the following components/libraries
- JIntellitype (for capturing the Ctrl-Alt-Q keyboard event)
- Winlaf (for fixing a couple of glitches in the Swing windows look and feel)
- EGL
- Apache Velocity
- FreeMarker
Also, the icons used in MiniGen have been borrowed from Eclipse.
Troubleshooting
- MiniGen requires Java 1.6 (ie. it won't work with 1.5) as it uses the new system tray functionality introduced in 1.6.
- MiniGen will not run on anything but Windows (yet). I've tested with both XP and Vista but it should also work with older versions.
- If MiniGen doesn't start when you double-click eu.kolovos.minigen.jar, try running it from the command line using java -jar eu.kolovos.minigen.jar. If it still doesn't start, make sure you attach the error message (stack trace) in your email.
- A message reading "java is not recognized as an internal or extenral command..." means that you don't have Java installed - or that it is not properly installed.
For any other problems/bugs, please feel free to contact me. Positive feedback is always welcome too :)
