Expands currently to ';)' but could be made to generate a link to some smiley graphics somewhere on the net.. Or even take in a plethora of grin configurations? ;P
Updated 23-Jun-04 /AK
This file is both a manual of Lumikki and a sample of its use. For more feedback and support, visit the development site at luaforge.net/projects/lumikki.
With Lumikki, you can craft your documentation using familiar HTML tags (s.a. '<i>' for italics, '<b%gt;' for bold and so on..) However, many of the more cumbersome tags (s.a. '<a href=...>' and '<gra src=...'>') can be replaced by Lumikki specific, functional tags.
Functional tags - what are they?
Well, much of this doc will probably focus on them. The basic idea of Lumikki (and pretty much the _only_ idea) is to allow functional tags within the HTML template to call Lua functions, named appropriately. This interaction of part static HTML (and text), part functions and their returned strings, will generate your website.
Or, as in the case of this 'manual', a single HTML page.
Still with us?
Let's take a short sample (I won't craft a long one, since just looking at the template of this file - MANUAL.HTL will serve as a 'real' example).
Sample Lumikki template.
Calling a <@EVAL>1+2</@EVAL> function.
Now, when this template is run through the Lumikki system (lua lumikki.lua manual.htl(*), it generates (roughly) this output:
<HTML><BODY>
<P>Sample Lumikki template. Calling a 3 function.</P>
</BODY></HTML>
*) If you want to save the output, just add '>manual.htm' redirection at the end.
Note that Lumikki has added the HTML and BODY tags, making the output be proper HTML. Also, it has added paragraph tags (P and /P).
Furthermore, it has calculated 1+2 but how did it do that?
Simply, by calling a predefined 'EVAL' function, which is part of the Lumikki Lua code. It could be defined as:
function EVAL( tbl, text )
return loadstring( "return "..text )()
end
Now, what this does is add "return" to the beginning (of 1+2) and then make a Lua on-the-fly function of it ("return 1+2"). Running such function (the "()") obviously returns 3, which is fed back to Lumikki. Lumikki replaces the <@EVAL> portion in the template with this string (or anything the function returned). Nice.
Well, apart from the stupidity of this sample, you probably get the point. Having full access to both the template (well, you make them :) and the Lua functions (you can craft your own, use the built-in ones, or expand their functionality) gives you total control on how your code is done, and what the functions are being used for.
I mean, you can use CSS (cascading style sheets) with Lumikki, or you might not. Same applies for JavaScript, Dynamic HTML, whatever.. Lumikki is ignorant of any such higher level tools, but versatile to work with them if taught so. The 'teaching' means crafting appropriate Lua functions that will do their job.
Broaden your mind
The Lua functions called don't necessarily need to be plain-through filters (string in, string out). They can also store interim data for later use in Lua data structures. This way, you can for example cause a <@NEWSITEM> tag to actually collect data on the news items that have passed through it. Eventually, a <NEWS> tag would be able to make a list of news articles based on the collected data. Cool.
Well, I think it's time to go into the bread-and-butter, namely the built-in functions. Consider this as a short reference manual (you won't get more!) of what's available.
Note that all this functionality is easily replacable or expandable by you simply by defining new global functions that behave the way you like.
You may have noticed the 'tbl' parameter in our sample above, that didn't get used. That is where you get tag params. Like:
<@FUNC param1=val1 [param2=val2 [...]]>
...text...
</@FUNC>
The table will hold any named parameters that were given inside the starting tag.
You can also omit giving them a value (see examples below) in which case they'll hold 'true'.
Actual text within the starting and ending tags is received in the secons function param (as used in the simple example).
Also, the ending tag (</@FUNC>) is optional. If your tag doesn't need the text input, there's no need for a terminating tag, either. (we're not XML here ;)
Conveniency function to do pretty much the same as traditional <A> tag has done. If no URL is given, the string contents are used (so no need to write the same thing twice).
A very important one. Expands currently to ';)' but could be made to generate a link to some smiley graphics somewhere on the net.. Or even take in a plethora of grin configurations? ;P
The rest is still undocumented - please send a note.
What more to say? There's more simple, tiny details to Lumikki, but looking at the sample code should make them obvious. If you have any questions, please be my guest and join us at the Lumikki development site (luaforge.net/projects/lumikki for discussion forum, mailing list, news archive, the lot!
I hope you will enjoy this little tool and -I hope- it will remain little. Smallness and simplicity has been one of the strengths of the Lua language and I hope that applies to Lumikki as well.
Yours truly, Asko Kauppi asko.kauppi@sci.fi
Lumikki is released under the GPL license. You are free to use the software in any project, for any purpose, as long as you don't (need to) make modifications to it. If you need to modify, you also need to provide the modifications to others that might benefit from them. This is how GPL works in a nutshell.
The original author of the package can be reached at: asko.kauppi@sci.fi
This page was created by Lumikki