descriptionA flexible HTML 4 compliant script/module for CGI-aware embeded Perl, shell-scripts, and other scripting languages, executed at the server side.
ownerR.J.J.H.vanSon@gmail.com
last changeThu, 17 Apr 2014 09:34:36 +0000 (17 11:34 +0200)
content tags
add:
readme

CGIscriptor 2.4: An implementation of integrated server side CGI scripts

HYPE

CGIscriptor merges plain ASCII HTML files transparantly and safely with CGI variables, in-line PERL code, shell commands, and executable scripts in many languages (on-line and real-time). It combines the "ease of use" of HTML files with the versatillity of specialized scripts and PERL programs. It hides all the specifics and idiosyncrasies of correct output and CGI coding and naming. Scripts do not have to be aware of HTML, HTTP, or CGI conventions just as HTML files can be ignorant of scripts and the associated values. CGIscriptor complies with the W3C HTML 4.0 recommendations.

In addition to its use as a WWW embeded CGI processor, it can be used as a command-line document preprocessor (text-filter).

THIS IS HOW IT WORKS

The aim of CGIscriptor is to execute "plain" scripts inside a text file using any required CGIparameters and environment variables. It is optimized to transparantly process HTML files inside a WWW server. The native language is Perl, but many other scripting languages can be used.

CGIscriptor reads text files from the requested input file (i.e., from $YOUR_HTML_FILES$PATH_INFO) and writes them to <STDOUT> (i.e., the client requesting the service) preceded by the obligatory "Content-type: text/html\n\n" or "Content-type: text/plain\n\n" string (except for "raw" files which supply their own Content-type message and only if the SERVER_PROTOCOL contains HTTP, FTP, GOPHER, MAIL, or MIME).

When CGIscriptor encounters an embedded script, indicated by an HTML4 tag

<SCRIPT TYPE="text/ssperl" [CGI="$name='default value'"] [SRC="ScriptSource"]>
PERL script
</SCRIPT>
or
<SCRIPT TYPE="text/osshell" [CGI="$name='default value'"] [SRC="ScriptSource"]>
OS Shell script
</SCRIPT>

construct (anything between []-brackets is optional, other MIME-types are supported), the embedded script is removed and both the contents of the source file (i.e., "do 'ScriptSource'") AND the script are evaluated as a PERL program (i.e., by eval()), a shell script (i.e., by a "safe" version of `Command`, qx) or an external interpreter. The output of the eval() function takes the place of the original <SCRIPT></SCRIPT> construct in the output string. Any CGI parameters declared by the CGI attribute are available as simple perl variables, and can subsequently be made available as variables to other scripting languages (e.g., bash, python, or lisp).

Example: printing "Hello World"

<HTML><HEAD><TITLE>Hello World</TITLE>
<BODY>
<H1><SCRIPT TYPE="text/ssperl">"Hello World"</SCRIPT></H1>
</BODY></HTML>

Save this in a file, hello.html, in the directory you indicated with $YOUR_HTML_FILES and access http://your_server/SHTML/hello.html (or to whatever name you use as an alias for CGIscriptor.pl). This is realy ALL you need to do to get going.

You can use any values that are delivered in CGI-compliant form (i.e., the "?name=value" type URL additions) transparently as "$name" variables in your scripts IFF you have declared them in a META or SCRIPT tag before e.g.:

<META CONTENT="text/ssperl; CGI='$name = `default value`' 
[SRC='ScriptSource']">
or
<SCRIPT TYPE=text/ssperl CGI="$name = 'default value'" 
[SRC='ScriptSource']>

After such a 'CGI' attribute, you can use $name as an ordinary PERL variable (the ScriptSource file is immediately evaluated with "do 'ScriptSource'"). The CGIscriptor script allows you to write ordinary HTML files which will include dynamic CGI aware (run time) features, such as on-line answers to specific CGI requests, queries, or the results of calculations.

For example, if you wanted to answer questions of clients, you could write a Perl program called "Answer.pl" with a function "AnswerQuestion()" that prints out the answer to requests given as arguments. You then write a HTML page "Respond.html" containing the following fragment:


<CENTER>
The Answer to your question
<META CONTENT="text/ssperl; CGI='$Question'">
<h3><SCRIPT TYPE="text/ssperl">$Question</SCRIPT></h3>
is
<h3><SCRIPT TYPE="text/ssperl" SRC="./PATH/Answer.pl">
AnswerQuestion($Question);
</SCRIPT></h3>
<CENTER>
<FORM ACTION=Respond.html METHOD=GET>
Next question: <INPUT NAME="Question" TYPE=TEXT SIZE=40><br>
<INPUT TYPE=SUBMIT VALUE="Ask">
</FORM>

The output could look like the following (in HTML-speak):


The Answer to your question

What is the capital of the Netherlands?

is

Amsterdam

<FORM ACTION=Respond.html METHOD=GET> Next question: <INPUT NAME="Question" TYPE=TEXT SIZE=40>
<INPUT TYPE=SUBMIT VALUE="Ask">

Note that the function "Answer.pl" does know nothing about CGI or HTML, it just prints out answers to arguments. Likewise, the text has no provisions for scripts or CGI like constructs. Also, it is completely trivial to extend this "program" to use the "Answer" later in the page to call up other information or pictures/sounds. The final text never shows any cue as to what the original "source" looked like, i.e., where you store your scripts and how they are called.

There are some extra's. The argument of the files called in a SRC= tag can access the CGI variables declared in the preceding META tag from the @ARGV array. Executable files are called as: `file '$ARGV[0]' ... ` (e.g., `Answer.pl \'$Question\'`;) The files called from SRC can even be (CGIscriptor) html files which are processed in-line. Furthermore, the SRC= tag can contain a perl block that is evaluated. That is,

<META CONTENT="text/ssperl; CGI='$Question' SRC='{$Question}'">

will result in the evaluation of "print do {$Question};" and the VALUE of $Question will be printed. Note that these "SRC-blocks" can be preceded and followed by other file names, but only a single block is allowed in a SRC= tag.

One of the major hassles of dynamic WWW pages is the fact that several mutually incompatible browsers and platforms must be supported. For example, the way sound is played automatically is different for Netscape and Internet Explorer, and for each browser it is different again on Unix, MacOS, and Windows. Realy dangerous is processing user-supplied (form-) values to construct email addresses, file names, or database queries. All Apache WWW-server exploits reported in the media are based on faulty CGI-scripts that didn't check their user-data properly.

There is no panacee for these problems, but a lot of work and problems can be safed by allowing easy and transparent control over which <SCRIPT></SCRIPT> blocks are executed on what CGI-data. CGIscriptor supplies such a method in the form of a pair of attributes: IF='...condition..' and UNLESS='...condition...'. When added to a script tag, the whole block (including the SRC attribute) will be ignored if the condition is false (IF) or true (UNLESS). For example, the following block will NOT be evaluated if the value of the CGI variable FILENAME is NOT a valid filename:

<SCRIPT TYPE='text/ssperl' CGI='$FILENAME' IF='CGIscriptor::CGIsafeFileName($FILENAME)'>
.....
</SCRIPT>

(the function CGIsafeFileName(String) returns an empty string ("") if the String argument is not a valid filename). The UNLESS attribute is the mirror image of IF.

shortlog
2014-04-17 Rob van SonCorrected documentationmaster
2014-02-19 Rob van SonAdded documentation of USEFAT
2014-02-10 Rob van SonCorrected error in file permissions
2014-02-10 Rob van SonAdded USEFAT and spaces to filenames
2014-02-10 Rob van SonAdded USEFAT and spaces to filenames
2014-02-10 Rob van SonAdded USEFAT and spaces to filenames
2014-02-06 Rob van SonCorrected behavior of ACCEPT.lis and REJECT.lis
2014-02-06 Rob van SonCorrected behavior of ACCEPT.lis and REJECT.lis
2013-06-27 Rob van SonAdded REMOTE_HOST to saved login file procedure to...
2013-06-26 Rob van SonAdded REMOTE_HOST to login procedure to protect against...
2013-05-31 Rob van SonUndone previous changes as they would never work
2013-05-30 Rob van SonStarted cli input for CGIMasterKey
2013-05-17 Rob van SonSmall changes in CGIservlet, removing pid info from...
2013-05-16 Rob van SonUpdate manual
2013-05-16 Rob van SonUpdate manual
2013-05-16 Rob van SonHandled empty ticket files
...
heads
3 years ago master