==========
quintCode v1.1 by C.S. Allin, copyright 2025
Visit my website at http://www.crunchyslug.com
or http://tilde.com/~cslug 

quintCode and all associated files are 
released under the C.S. Allin quintCode 
License v1.0. See license.txt for details.
 
(If you think quintCode is worth money, please
visit my website and consider donating. 
Every little bit helps me avoid the 
poor house)
==========


NEW FOR RELEASE 1.1:
The quintCode interpreter will no longer get stuck in a loop if you pass an empty string to insertString(). It will now quit gracefully. Also, test1.htm and test2.htm have been updated to the proper versions. I had accidentally included outdated versions of them in release 1.0.  


WHAT QUINTCODE IS AND HOW TO USE IT


quintCode is an extension to HTML that allows webpages to be dynamically altered without any reliance on relatively slow scripting languages like Javascript or PHP, or any cumbersome frameworks or tool chains.

Thanks to being implemented in C, quintCode is blazingly fast and efficient. And thanks to being open source, you can make it do whatever you want. 

The basic idea behind quintCode is that you can designate areas of your webpage as "dynamic zones". You then program the quintCode interpreter to fill these dynamic zones with any kind of dynamic data you want, when you want, how you want. 

The process of designating a dynamic zone(or zones) is straight forward. Just put a quintCode where you want the dynamic zone to start, and an end statement where you want the dynamic zone to end.


This is a quintCode: 
;EXMPL

This is an end statment: 
;END


The space between ;EXMPL and ;END would be a dynamic zone. 


Note: quintCodes must always start with the ; symbol(chosen in order to minimize conflicts between quintCodes and other scripting/programming languages), must be 5 characters long, and can only consist of uppercase letters and/or the numbers 0 to 9. Every quintCode must also terminate with an ;END statement so the quintCode interpreter can tell where each dynamic zone begins and where it ends.


Here's an example. Let's say you want the background color of your webpage to change every day. 


Excerpt of your hypothetical webpage
----------
<html>
<head>
<title>My page!</title>
</head>
<body ;BGCOL bgcolor=white ;END>
...
----------


You would then program the quintCode interpreter to insert a new bgcolor in the dynamic zone between ;BGCOL and ;END.


Excerpt of quintCode interpreter sourcecode in quint.c
----------
...
if(quintCodeName("BGCOL"))
{
		if(random == 0){
		
			insertString("bgcolor=blue");
			
		}else if(random == 1){
		
			insertString("bgcolor=green");
			
		}else{
		
			insertString("bgcolor=red");
			
		}
		
		return 1;
}
...
----------


This will insert a randomized background color(blue, green, or red) in the dynamic zone between ;BGCOL and ;END. Alternatively, you could also load background colors from files:


Hypothetical code:
----------
...
if(quintCodeName("BGCOL"))
{
		if(random == 0){
		
			insertFile("bg1.txt");
			
		}else if(random == 1){
		
			insertFile("bg2.txt");
			
		}else{
		
			insertFile("bg3.txt");
		}
		
		return 1;
}
...
----------


Where bg1.txt, bg2.txt, and bg3.txt each contain a different bgcolor.

You can also use the same quintCode multiple times in the same HTML page. In the following example, the quintCode ;TXCOL is used on three separate <font> tags.


;TXCOL example
----------
<html>
<head>
<title>My page!</title>
</head>
<font ;TXCOL color=black ;END>Hi</font><br>
<font ;TXCOL color=black ;END>Hello</font><br>
<font ;TXCOL color=black ;END>Howdy</font>
...
----------


If you program the quintCode interpreter to write "bgcolor=purple" in response to the quintCode ;TXCOL, then "Hi", "Hello", and "Howdy" will all be changed from black to purple. 

But you can do more with quintCodes than just modify HTML tags. You can designate entire sections of your website as dynamic zones by combining quintCodes with HTML comments. For example, I use quintCode on my personal website to populate a daily news feed, which functions something like this:


Excerpt of my website
----------
<table>
<tr><td>
<!==;NEWSF==>
News article 1
News article 2
News article 2
etc.
<!==;END==>
</td></tr>
</table>
---------- 


My website's quintCode interpreter is programmed to automatically insert new news articles between <!==;NEWSF==> and <!==;END==> every day. You can program it to do the same thing for your website, too. Or to do anything else you can imagine. 


NOTE: The quintCode interpreter is strict. A quintCode or end statement inside of an HTML comment must contain no spaces. <!--;EXMPL--> is good, <!-- ;EXMPL --> is bad. 


The quintCode interpreter was designed to be as straight forward and easy to program as possible. Generally, the only function you need to pay attention to is handleQuintCode(). This is where you'll determine what the interpreter should write in response to each quintCode. 

The quintCode interpreter sourcecode is located in quint.c and knowledge of C is required to program it. You can compile it with just about any C compiler on just about any platform. 

But before you program the quintCode interpreter, it's important to understand how it processes HTML pages. It begins by copying a page(the "source page") to a temporary file("qtemp.txt" by default), pauses when it detects a quintCode in the HTML, writes whatever data you want it to write in response to said quintCode, then upon reaching the ;END statement it resumes copying the source page to the temporary file. Once this process is complete, it deletes the source page and replaces it with the temporary file. 

Source pages are specified in the file qsources.txt by default. This is simply a list of paths to every HTML page that the quintCode interpreter should process. For a working example, see qsources.txt and the sample HTML pages that ship with this distribution of quintCode.


Example of qsources.txt
----------
www\test1.htm
www\test2.htm
etc.
----------


It's also important to understand that DOS and Windows expect paths to use backslashes like "example\index.htm", while Unix-like systems expect paths to use forward slashes like "example/index.htm". As a convenience, the quintCode interpreter will automatically convert between DOS/Windows style paths and Unix-style paths. 

But if you're using a platform with more a exotic path format like the classic Mac OS("example:index.htm") then you'll have to manually ensure that qsources.txt uses the correct path format. The interpreter won't do any automatic conversions for these exotic paths.

If you want the quintCode interpreter to use a list of soure pages other than qsources.txt, you can specify it as the first argument to the interpreter:

quint.exe mylist.txt

And you can specify a different name for the temporary file by passing it as the second argument:

quint.exe mylist.txt mytemp.txt

This is useful if you want to run multiple quintCode interpreters and have each one update different sets of HTML pages. And if two or more interpreters are going to run simultaneously, then you definitely want them to each use separate temporary files. 

To schedule a quintCode interpreter to run at a specific interval, such as every day, you can simply use whatever task scheduling system you prefer on your platform of choice. This could be Scheduled Tasks/Task Scheduler on Windows, crontabs on Unix-like platforms, etc. 


ABOUT THE INCLUDED EXAMPLE

The quintCode interpreter is distributed with a simple example website to demonstrate how quintCodes work. Every time you run quint.exe, the two .htm files in the directory www will be updated with a randomized background color and greeting. If you're using a platform that quint.exe is incompatible with, then just compile quint.c and run the resulting binary. 


Now go make something cool with quintCode!

- C.S. Allin