210 lines
6.6 KiB
HTML
210 lines
6.6 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="keywords" content="PSL, PLIB, OpenGL, portable, script, language, Baker, Steve">
|
|
<meta name="description" content="The PLIB Scripting Language (PSL) Library is a lightweight scripting language that is well suited for games or other interactive programs.">
|
|
<title>The PLIB Scripting Language: Programming Guide.</title>
|
|
</head>
|
|
<body text="#B5A642" bgcolor="#005000" link="#8FFF8F" vlink="#18A515" alink="#20336B" background="../marble.png">
|
|
|
|
<table>
|
|
<tr>
|
|
<td>
|
|
<center>
|
|
<h1>The PLIB Scripting Language Programming Guide </h1></center>
|
|
<center>By Steve Baker</center>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<H1>Introduction</H1>
|
|
|
|
This document explains how to write PSL programs.
|
|
|
|
<p>
|
|
|
|
How you actually run those programs depends on which PSL-enabled
|
|
application you are running. There is a stand-alone PSL interpreter
|
|
in plib/examples/src/psl/psl_demo - but it doesn't include any
|
|
application-specific language extensions - so a PSL program
|
|
that's written for a specific application may not run
|
|
on <code>psl_demo</code>.
|
|
|
|
<p>
|
|
|
|
However, psl_demo is great for learning to write PSL scripts.
|
|
|
|
<H1>The PSL Language</H1>
|
|
|
|
PSL is designed to be as close to the C Programming
|
|
Language - although we
|
|
cut a few corners - we extended the language in a few places - and
|
|
we consciously omitted other features that are dangerous in a
|
|
scripting language.
|
|
|
|
<p>
|
|
|
|
The following C features are implemented much as you'd expect:
|
|
<ul>
|
|
<li> Types 'void', 'int' and 'float' (and arrays of those things).
|
|
<li> Function definitions.
|
|
<li> Global variable definitions.
|
|
<li> Statement types:
|
|
<ul>
|
|
<li> Local variable definitions.
|
|
<li> Static variable definitions.
|
|
<li> "return"
|
|
<li> "break"
|
|
<li> "continue"
|
|
<li> "for"
|
|
<li> "do/while"
|
|
<li> "switch/case/default"
|
|
<li> "while"
|
|
<li> "if"
|
|
<li> "if/else"
|
|
<li> "{}" compound statements.
|
|
<li> Assignment statements.
|
|
<li> Procedure calls.
|
|
</ul>
|
|
<li> Most Arithmetic operators.
|
|
<li> Comments '/*' '*/'.
|
|
<li> C preprocessor directives:
|
|
<ul>
|
|
<li> "#include"
|
|
<li> "#define" without parameters.
|
|
<li> "#undef"
|
|
<li> "#ifdef/#endif"
|
|
<li> "#ifdef/#else/#endif"
|
|
<li> "#ifndef/#endif"
|
|
<li> "#ifndef/#else/#endif"
|
|
</ul>
|
|
<li> Special characters in strings:
|
|
<ul>
|
|
<li> "\n"
|
|
<li> "\r"
|
|
<li> "\a"
|
|
<li> "\b"
|
|
<li> "\f"
|
|
<li> "\t"
|
|
<li> "\\"
|
|
<li> "\""
|
|
</ul>
|
|
<li> Recursion, etc.
|
|
</ul>
|
|
|
|
Some new features have been added that are not part of C:
|
|
<ul>
|
|
<li> "pause" -- Pause the program until next frame.
|
|
<li> "string" data type (and arrays of strings).
|
|
<li> Casts are unnecessary between compatible types.
|
|
<li> C++ style '//' comments.
|
|
<li> C++ style local variable declarations.
|
|
</ul>
|
|
Some features of C are NOT IMPLEMENTED in PSL:
|
|
<ul>
|
|
<li> Pointers.
|
|
<li> Casts.
|
|
<li> Dynamic Memory Allocation.
|
|
<li> ',' and '?:' operators in expressions.
|
|
<li> "static", "auto" and "register" storage class reserved words.
|
|
<li> "char", "short", "unsigned", "signed", "long", "double".
|
|
<li> "typedef"
|
|
<li> "enum", "union", bitfields.
|
|
<li> "goto".
|
|
<li> "#if"
|
|
<li> "#pragma"
|
|
<li> "#define" with parameters.
|
|
<li> 'f' and 'l' suffixes for float and long numbers.
|
|
<li> All preprocessor directives must have the '#' as the
|
|
very first character on the line - they cannot be
|
|
preceded with whitespace.
|
|
</ul>
|
|
|
|
The following features are "NOT IMPLEMENTED YET" - but will
|
|
hopefully arrive soon:
|
|
<ul>
|
|
<li> Multiple variable definitions like 'int i, j, k ;'
|
|
<li> Structs.
|
|
<li> '\' to escape the end-of-line character in strings and macro's.
|
|
<li> Parameter passing by name.
|
|
<li> Many of C's standard library functions are needed.
|
|
</ul>
|
|
|
|
<H1> Compatibility Notes: </H1>
|
|
<H3> C++ style local variables. </H3>
|
|
With PSL's C++ style locals, you can say things like this:
|
|
<pre>
|
|
|
|
for ( int i = 0 ; i < 10 ; i++ ) /* Do something */ ;
|
|
|
|
</pre>
|
|
In standard C++, the scope of the variable 'i' is from it's
|
|
declaration to the end of the 'for' loop. However, Microsoft's
|
|
Visual C++ uses an obsolete version of the C++ standard that
|
|
allows the scope of 'i' to continue to the end of the block
|
|
that contains the for loop. So:
|
|
<p>
|
|
WINDOWS USERS BEWARE: PSL IMPLEMENTS THIS CORRECTLY - *NOT* LIKE
|
|
MSVC.
|
|
|
|
<H1>Hard Limits</H1>
|
|
Currently there are hard limits in many places - the number of
|
|
variables, the size of the program, the depth of nesting, etc.
|
|
These limits will gradually be removed as PSL is developed.
|
|
|
|
<H1>Debugging PSL Programs</H1>
|
|
|
|
Specific PSL-enabled applications may have their own
|
|
special features to assist with debugging - but all
|
|
PSL-enabled applications support several 'shell variables'
|
|
that enable certain debugging features.
|
|
<p>
|
|
When using a command line shell, you can set these
|
|
variables using one of the following commands before
|
|
you run your application:
|
|
<pre>
|
|
setenv VARIABLE value -- csh or tcsh
|
|
export VARIABLE=value -- bash or sh
|
|
set VARIABLE=value -- DOS shell
|
|
</pre>
|
|
<H3> Byte-Code Dump </H3>
|
|
It's possible to view the byte code that PSL generated
|
|
by setting the shell variable 'PSL_DUMP' to either:
|
|
<ul>
|
|
<li> <b>never</b> (the default) -- Never produce a dump unless
|
|
the application demands it.
|
|
<li> <b>on_error</b> -- Produce a dump whenever the PSL program
|
|
fails to compile for whatever reason.
|
|
<li> <b>always</b> -- Always produce a dump after the PSL program
|
|
finishes compiling.
|
|
</ul>
|
|
<H3> Byte-Code Execution Trace </H3>
|
|
It's possible to view the byte code as it's executed
|
|
by setting the shell variable 'PSL_TRACE' to either:
|
|
<ul>
|
|
<li> <b>never</b> (the default) -- Never produce a trace unless
|
|
the application demands it.
|
|
<li> <b>always</b> -- Always produce a trace.
|
|
</ul>
|
|
When the execution trace is enabled, extra instructions will be
|
|
inserted into the byte code to enable the PSL interpreter to
|
|
produce debug indicating which lines of the source code are
|
|
being traced.
|
|
<H3> Byte-Code Stack Display </H3>
|
|
If you have PSL_TRACE turned on (either via the config variable or
|
|
by the application program), then the shell variable 'PSL_STACK'
|
|
can be set to display the contents of the top eight stack locations
|
|
as the program is traced. If PSL_TRACE is disabled then PSL_STACK
|
|
has no effect.
|
|
<ul>
|
|
<li> <b>never</b> (the default) -- Never produce stack dumps
|
|
within a trace.
|
|
<li> <b>always</b> -- Always produce a stack dump within trace.
|
|
</ul>
|
|
<hr>
|
|
<address>
|
|
<a href="http://www.sjbaker.org">Steve J. Baker.</a> <<a href="mailto:sjbaker1@airmail.net">sjbaker1@airmail.net</a>></address>
|
|
</body>
|
|
</html>
|
|
|