Screws Scripting embedded inside HTML
=====================================

There'r two ways to embed code inside HTML:

HSMLv1:
   Slower than 2nd. Every peace of code is a separated code.
   By this way you can use perl,sh and python in the same
   html document.

HSMLv2:
   All the document is the same code. By this way, you can
   work as JSP or PHP but using your favorite language.

Both are supported in the last version. But probably hsml1 will be
deprecated soon.

HSMLv2 documentation:
=====================

This version is under development.

Code tags are identified by <? and ?>. You also can use tags
like JSP does: <?= ?> To print variables.

To specify the language to use you have to rename the hsml
extension by: ".xx.html". For example:

  index.pl.html    hello.lua.html   byteme.py.html

Also you can specify the language in the first line using a hashbang:

$ cat index.hsml
#!perl
<? print "HelloWorld"; ?>


There's also a DIP (Default Include Path), you must recompile
to change it. Just type: 'hsml' to discover where's this path.

Hsml looks there for files called: "include.xx.html". The
content of this file must be the beggining of the final document.

DIP is useful to include default code like variable parsing,
SQL injection detection, loading libraries (SQL...)



HSMLv1 documentation:
=====================

## WARNING ## HSML1 will dissapear in future versions of HSML

In src/Script/ there's a binary that allows you to execute
script code embedded inside HTML. By this way you will be
able to execute programs, codes, include other html/screws
in the same page, etc.

There's a lot of differences between php and Hsml, the main
one, is that hsml isn't a language. Is just a way to embed
code inside html, the code that you write on this <#tags#>
could be written in perl, python, shellscript, etc.

You can also escape tags or special control characters used by 
SWS' scripting embedding with the character '\' before them.

It uses "soft" escaping, so the escaping character will be
treated as such only if it's before a "<#" or a "#>" matching
an open tag (please note that interp cannot contain '+' nor ' '
and subgrp cannot contain '.' nor ' ').

I explain the main concepts, that probably will be more
extensible in the future:

Default tags are:

<# (put code here) #>

No code bloc nesting supported!

In the open-tag and close-tag you could put certain options 
(options inside a [] are optional):

OPEN-TAG: "<#[interp][+subgrp[.]] "
          (beware of the trailing space)

* [interp]:
<#perl
<#python
<#sh
<#!/bin/sh

As you see you could define the language that will be written
inside this tag. There'r few default languages, or you could
specificate a new one with the hashbang (!).

* [+subgrp[.]]:

This lets you group some bloc codes to act as a single one (so
you can call code on another code bloc)

Code blocs are grouped together when having the same interp and
subgrp, and output is only put where a code bloc is declared as
executable, with the '.' character (there can be more than one
executable bloc code on the same group, but the resulting whole
code interpreted will have only one executable part at a time).

So the next example will give us:
	<#perl+foo1 	z1 #>
	<#python+foo1 	z2 #>
	<#sh 		z3 #>
	<#perl+3. 	z4 #>
	<#perl+foo1. 	z5 #>
	<#python+foo1. 	z6 #>
	<#perl+foo1. 	z7 #>
	<#sh 		z8 #>
	<#perl+foo1 	z9 #>
	<#sh+777 	z10 #>

	output_group 		code_used
	sh (no grouping)	z3
	perl+3 			z4
	perl+foo1 		z1 z5 z9
	python+foo1 		z2 z6
	perl+foo1 		z1 z7 z9
	sh (no grouping)	z8
	(ignored sh+777)	z10

As you can see, code blocs can be declared after an executable
code bloc, so it's on the interpreters' hands to get this to
work.

On a non executable grouped bloc, the exit value is always false
by default.

If not grouped, it's always executable by default.

But if it's grouped and no executable block has been declared,
it's as if all blocks on that group were not declared, and their
exit value (look below) will be ignore (?).

CLOSE-TAG: " [exit]#>"
           (beware of the starting space)

* [exit]:

Each code bloc has an exit value (true or false), that tells
if the next text (or code's result) bloc must be ignored or
not.

You can force the exitvalue of the script:

#> -- default output value (script's exit, == 0:false, != 0:true)
?#> -- ignore the exit value and assume the previous one
0#> -- false (no disabling next)
1#> -- true (disable next)

But exit values will be used only on executable code blocks,
so on others it will be implicitly always ignore (?).

