Documentation of the script language of camlserv
Version 0.2


Tags
****

The normal html tags are scanned for question marks around expressions to
provide dynamically changed contents. When a single question mark is needed
just provide two of them and one will remain in the string.

Example: <a href="page.html??parm=p_?string_of_int (number + 2)?&action=?action?">submit</a>
When the internal variable 'number' is filled with 1 and 'action' with 'GO'
this example is send to the client as:
Example: <a href="page.html?parm=p_3&action=GO">submit</a>

The html files that can be shown by the server can contain more than normal
html tags. These extra tags are read by the server but never shown in the end
result:

	<include [set="<set-name>"] file="<script-name>">
   or 
	#include <script> [from <set-name>]

Include other html file into the current page. The set-name is optional, the
default is the first script set.

	<print expr="<string-expr>">
   or
	#print <string-expr>


Print the result of the given expression and put the result inside the rest of
the html on the page.

	<do expr="<expr>">
   or
	#do <expr>

Perform this calculation and dismiss the result.

	<when test="<bool-expr>" set="<name>">
		....
	<else>
		....
	</when>
   or
	#if <expr>
		....
	[#else
		....]
	#end

Conditionally print the html inside the when structure. Also the calculation
tags inside are skipped. The else tag inside is optional. When calculated to
true also set the boolean variable.

	<switch>
	{<case test="<bool-expr>">
		....
	</case>}

	[<default>
		....
	</default>]
	</switch>

Perform the tests in the case statements, when a case is a success the rest
of the tests are skipped. When every case fails the default code is calculated.

	<var name="<name>" expr="<expr>">
   or
	#set <var>=<expr>

Create or mutated a variable <name> and fill it with the given expression.

	<function name="<function-name>" {parm="<variable>"} {local="<variable>"}>
		....
	</function>
   or
	#function <name> [<parm-1> ...  <parm-n>] local [<local-var-1> ... <local-var-n>]
		....
	#end

Adds a new global function to use in expressions. It generates a html structure
as a result that can be printed or written to a file. Functions can be
recursive and have parameters and local variables.

Example: <function name="some_function">hello</function> <print expr="some_function">
This example just prints the text "hello".

	<extern name="<function-name>" {parm="<variable>"}>
   or
	#extern <function-name> [<parm-1> ... <parm-n>]

Pre-declare a function so the compiler won't complain when a function is
called that is defined in another (not yet compiled) script. The ordering
of compilation of scripts is not pre-determined by a makefile mechanism.

	<loop [while="<bool-expr>"] [var="<name>"] [from="<number-expr>" to="<number-expr>"] [infinate]>
		....
	[<break>]
		....
	</loop>
   or
	#while <expr> [infinate]
		....
	[#break]
		....
	#end
   or
	#for <var>=<from> to <till>
		....
	[#break]
		....
	#end

Create a loop. The given variable is a counter. There can be a from and to
tag with the expressions for the first and last value of the counter. Without
the first and last value the loop will potentionally be unended but stops on
the first error state encountered (like reading past then end of a file) or on
an encountered break tag.
The infinate field indicates that the loop will not remember the html or text
inside the loop. This can prevent a large memory usage buildup.

	<relas rela="<name>" parm="<name>" extra="<name>" thing="<thing-expr>"
		   type="<string-expr>" [sort | descending]>
		....
	[<break>]
		....
	</relas>
   or
	#relas <thing> type <relation-type> into <related-var> [parm <parameter-var>] [extra <extra-var>]
		....
	[#break]
		....
	#end
   or
        #relas <var>=<thing> type <relation-type> [parm <parameter-var>] [extra <extra-var>]

Loop through the relations of a given thing. There can be given variable names
for the related thing (rela), the parameter to the relation (parm) and the
extra parameter (extra).
When adding the sort or descending field the relations are first sorted on their parameter (or extra parameters when 2 parameters are the same).

	<split str="<string-expr>" on="<regular expression>" var="<name>">
		....
	[<break>]
		....
	</split>
   or
	#split <var> = <expr> on <regexp>
		....
	[#break]
		....
	#end

Split the given string on the given regular expression.

	<match str="<string-expr>" with="<regular expression>" vars="<comma seperate names>" set="<name>" no_case>
		....
	</match>
   or
	#match <var> with <regexp> [into <var-1>, ..., <var-n>]
		....
	#end

Test the string with the given regular expression, leave the result in vars.
When matches set the boolean variable given after set. The "no_case" flag signals case-insensitive matching.

	<database connection="<conn-var-name>" host="hostname"[localhost] user="name"[Empty]
		passwd="passwd"[Empty] db="name" port="nr"[0]>
		....
		perform the queries on this connection
		....
	</database>
   or
	#database [<dbvar> =] [<host>] [user <user> passwd <passwd>] db <dbname> [port <port>]
		....
	#end

Connect to a database (currently only mysql supported). All the fields in the
database start-tag are optional, the default values are listed.

	<record connection="<conn-var>" query="<query-string>" [rows="<var-name>"] [vars="<var-list>"]>
		....
		variables with the name of the fields are filled with their
		corresponding values this is a loop through all the found
		records, or the values will be filled in the given variable
		names in vars
		....
	[<break>]
		....
	</record>
   or
	#record <query> [database <dbvar>] [rows <var>] [vars <var-1>, ..., <var-n>]
		....
	[#break]
		....
	#end

Do a query on a connection database, when multiple connections are opened the
connection name should be given or else the last opened connection is presumed.

	<query [connection="<dbvar>"] do="<query-string>" [rows="<var-name>"] [vars="<var-list>"]>
   or
	#query <query> [database <dbvar>] [rows <var>] [vars <var-1>, ..., <var-n>]

Perform a query but do not return any records.
Both the query tags above can handle expresions inside the query. These
expressions should be written between two question marks.

Example: <query do="INSERT INTO tbl VALUES (?'deb_'^name?, ?value?, 'default', 'Is this right?', \"why?\", ?number * 100?)">

Question marks may still be used in strings both between ' and \". The internal
mechanism of perpared queries of MySQL is used so you must only use ?
expressions on positions that are allowed by MySQL. Look at 
http://www.mysql.com/doc/en/mysql_prepare.html for more details.



Expressions
***********

The following expressions are possible:

	(  <expr>  )      -> <expr>	   Force evaluation ordering
	'<string>'        -> <string>  Constant string (\ = escape-token, 
								    \n = newline  \t = tab-token)
	true              -> <bool>
	false             -> <bool>
	number            -> <number>  Numerical constant
	var               -> <expr>    The value of a variable
	fn <expr> <expr>  -> <expr>    Call a function with parameters

Basic constants and operations.

	<string> [ <string> ]      -> <thing>   Get a thing:   'type'['name']
	'system'['root']	   -> <thing>   The root thing, use this as the top level parent
	<thing> .name              -> <string>  The name of a thing
	<thing> .type              -> <string>  The type of a thing
	<thing> .descr             -> <string>  The description of a thing
	<thing> .parent            -> <thing>   Get the parent of a thing
	<thing> -> <string>        -> <thing>   Get a related thing, only single
	<thing> -> <string>[<number>]-> <thing> Get the relation with parm <number>
	<thing> -> <string> .parm  -> <number>  Get the parameter to an relation
	<thing> -> <string> .extra -> <number>  Get the extra parameter
	<thing> -> <string> .no    -> <number>  Get the number of relations of this type

Operations to read things and relations.

	<string>  ^  <string>  -> <string>     Concatenation of strings

	<number>  *  <number>  -> <number>
	<number>  /  <number>  -> <number>     Integer divitions
	<number>  %  <number>  -> <number>     Modulus calculation
	<number>  +  <number>  -> <number>
	<number>  -  <number>  -> <number>

Normal algebra with more priority given to multiplication than addition.

	<expr>  =  <expr>  -> <bool>
	<expr>  <  <expr>  -> <bool>
	<expr>  >  <expr>  -> <bool>
	<expr>  <>  <expr> -> <bool>
	<expr>  <=  <expr> -> <bool>
	<expr>  >=  <expr> -> <bool>
	not <bool>         -> <bool>
	<bool> and <bool>  -> <bool>
	<bool> or <bool>   -> <bool>

Normal boolean algebra with 'and' and 'or' in letter instead of tokenized.

	if <bool> then <expr> else <expr>

The else part is always needed because expressions need to give a result back.
The type of the 2 resulting expressions should be the same.


Functions
*********

The list of functions inside the expressions:

	string_of_int <number>         -> <string>   Convert numbers to strings
	string_of_dec <decimals> <numb>-> <string>   Convert numbers with fixed decimals
	string_of_hex <number>         -> <string>   Convert numbers to hexadecimal 
	string_of_fhex <len> <number>  -> <string>   Convert numbers to a fixed length hexadecimal
	int_of_string <string>         -> <number> or <error>  Convert strings to numbers
	string_of_bool <bool>          -> <string>   Give 'true' or 'false'
	bool_of_string <string>        -> <bool> or <error>
	string_of_var <var>            -> <string>   Convert various variable types into a string
	string_sub <string> <pos> <len> -> <string>  Get the substring from position (negative: from end) with length
	string_length <string>	       -> <number>   Get the length of the string
	string_find <string> <string>  -> <number>   Search for the second string in the first one and return the position
	string_findf <string> <string> <number> -> <number>  Search the second in the first from a given position
	is_error <expr>                -> <bool>     Give 'true' when <expr>=<error>
	new_array <length>             -> <array>    Define an array of numbers with <length> elements
	set_array <array> <pos> <numb>               Set the value of an array element
	<array> [ <numb> ]	       -> <number>   Get the value of an array element

File operations:
	command <string> 
	    perform command 
	open_in <string>        -> <in-file>
	command_in <string>     -> <in-file>
	close_command <in-file>
	wait_childeren
	check_childeren
	input_line <in-file>    -> <string>
	close_in <in-file>
	open_out <string>       -> <out-file>
	open_out_add <string>   -> <out-file>
	output_string <out-file> <string>
        output_html <out-file> <html>
	    write the result html of a function into a file
        output_text <out-file> <html>
	    replace '<br>' tags in html to end of lines and '/t' tokens into tabs
	    write the result to file
	close_out <out-file>
	read_things <in-file> <thing>
	    read XML data from the file and write that as child things to
	    the given parent thing
	compare_things <in-file> <thing> <string> <thing> -> <boolean>
	    	usage: compare_things fd parent changed_type changed_thing
	    read XML data from the file and compare it to the current data
	    starting at the given parent thing
	    changed things receive a relation with the given type (changed_type) to
	    the given thing (changed_thing)
	write_things <out-file> <thing>
	    write the given thing including child things and their relations in
	    XML to the file
	opendir <string>        -> <dir-handle>
	readdir <dir-handle>    -> <string>
	    reads the next file from the directory and returns this filename
	closedir <dir-handle>
	entry_isdir             -> <boolean>
	    is the last returned directory-entry a directory itself
	entry_isfile		-> <boolean>
	    is the last returned directory-entry a normal file
	entry_user		-> <string>
	entry_group		-> <string>
	entry_rights		-> <string>
	entry_size		-> <int>
	is_file <string>        -> <boolean>
	    check if the given string is a valid filename

Reading pop servers:
	open_pop <server> <account> <password> -> <pop-handle>
	read_pop <pop-handle>	-> <int>
	close_pop <pop-handle>
	message_header		-> <string>
	message_subject		-> <string>
	message_sender		-> <string>
	message_date		-> <int>
	message_body		-> <string>
	message_save		-> <filename>
	message_remove

Future mime type handling:
	message_part		-> <string>
	    when mimeparts are found, these are the temporary files that are created
	message_mimetype	-> <string>
	message_filename	-> <string>
	    the original filename of this mime part

Message sending routines:
	open_message <subject-string> <from-string> <to-string>
	message_write <string>
	message_htmlwrite <html>
	message_urgent
	message_file <filename> <mime-type>
	close_message

Create a new thing:
	new_thing <string> <string> <thing> <string> -> <thing>
Parameters:
	new_thing type name parent description
When a thing already exists it is replaced with the new name and description.


Create a new thing with inheritance from the parent:
	new_child <string> <string> <thing> <string> -> <thing>
Parameters:
	new_child type name parent description
When a thing already exists it is replaced with the new name and description.


Create a new relation:
	new_relation <thing> <string> <thing> <number> <number>
Parameters:
	new_relation thing relation_type related_thing parameter extra_parameter


Remove a relation again:
	del_relation <thing> <string> <thing>
Parameters:
	del_relation thing relation_type related_thing

Mark things and their childeren for removal:
	remove <thing>
Remove all the marked things:
	execute

System functions
****************

system_random unit -> int
	Random number between 0 and MaxInt
system_page_dir scripts_set -> directory -> unit
	Read this directory of active scripts into a named scripts_set.
	Scrips_set are needed to create multiple virtual sites. You can think
	about administrative pages that cannot be started without proper rights
	or only from a specific set of ip addresses.
system_debug_level level -> unit
	This will set the current debug level of the program
script_debug_level level -> unit
	This will set the current debug level of the in-script log messages
system_log level message -> unit
	This will write a notice in the log when the debug level is higher or
	equal the number
system_time unit -> time
	Get the seconds since januari 1th 1900
system_settime unit -> unit
	Remember the time
system_duration unit -> int
	Give the elapesed time since the last remembered one in milliseconds
system_sleep time -> unit
	Sleep for the given number of microseconds
system_set_user username -> unit
	Change effective user ID and effective group ID to those of user
	'username'. This drops the root privilages of the server.
system_add_safe directory -> unit
	Add a directory-tree beginning with the given directory to the set of
	safe dirs
system_check_safe file -> boolean
	Check if this file points to somewhere inside the save directories.
	The first given save	directory is used as starting point.
	Checked operations: '..', '.', symbolic-link

system_stop unit -> unit
	Let the system stop at the next feasable moment with the normal closing
	routines

system_stopped unit -> boolean
	Check if a signal has occurred to stop the processing

system_inactive unit -> boolean
	Check the activity of the system since the last check
	(activity = input or output) When this check holds true the system has
	time to spare for all kinds of background processing

system_connections unit -> boolean
	Get the next open connection to handle, name of the socket that is
	handeled. The boolean is false after the last one

system_sockets unit -> boolean
	Loop through the defined sockets on the system, boolean if false after
	the last one


Socket functions
****************

socket_create port -> max_conn -> socketnr
	Create a socket on a port with a given maximum number of connections
socket_create_ssl port -> max_conn -> cert_file -> key_file -> password -> socketnr
socket_open ip -> port -> connect
socket_open_ssl ip -> port -> connect
socket_listen socket -> unit
socket_close socket -> unit
socket_require_authorization socket -> unit
	Require the user to use basic authorization. This is not safe except
	when using SSL because the passwords are transfered on every request as
	open text.
socket_current unit -> socketnr
	Return the current socket number for tests against the original socket
	number


Connection functions
********************

conn_header unit -> boolean
conn_send unit -> boolean
conn_close unit -> unit
conn_iscalc set_name -> script_name -> boolean
	When the set_name is empty the first read set is used.
	Doesn't calculate but only returns true is the script exists
conn_calc set_name -> script_name -> boolean
	When the set_name is empty the first read set is used.
conn_file set_name -> file_path -> duration -> unit
	Send a file through the socket to the client
conn_var type -> name -> string
	Get the connection variable of given type and name.
conn_var_list type -> name -> string
	Get the next instance of this variable. It breaks a loop when no more
	values are found.
set_server_parm string -> string -> unit
	Write a global server parameter with a value
	Used variables:
	'status' : return status of the server
	'challenge' : name of the server for basic-authorization

Text handling functions
*************************

safe_html string -> string
	Convert text till a few layout tags are still usable, endlines and double spaces from the text are rendered
	Standard tags: 	<u></u>	<b></b>	<i></i> <sub></sub> <sup></sup>
	Other tags: 	<c></c>	code style (class=code)
			<l></l>	list of options
			<n></n>	numerical list
			<link URL>text</link> simple notation link
safe_textarea string -> string
	Convert text till tags are visible in text area's
replace regexp_string replace_string string -> string
	Replace all matches of the regular expression inside one string
password passwd_string -> string
	Encode a password in the BSD-1 style MD5 encoding
check_password passwd_string other -> bool
	Check a password against an already encode one
match string regexp_string -> bool
	Returns true when string matches the regular expression