---------------- Writing waveperl scripts ------------------


Waveperl is an extended version of the Perl language that
contains additional functions for manipulating data
structures inside The WaveFormer (TWF). Waveperl scripts are
compiled and executed by a perl interpreter embedded into
TWF (actually it's not, strictly speaking, an intepreter since
your script is really compiled on-the-fly).

Related docs: twfapi.txt contains a description of functions
in The WaveFormer that can be called from Waveperl scripts.

-- Why a scripting language?

1) Addition of a scripting language makes it possible
for TWF to potentially import/export any waveform format
(in other words, you can write your own scripts).

2) Scripts make it easier to for SynaptiCAD to upgrade TWF 
capabilities and distribute the upgrades to you, the end-user.

3) End-users can change scripts as desired to meet their
own particular needs (e.g. You're designing an IC that uses	a
3.3V power supply and you want your SPICE test vectors to
represent a high state as 3V instead of 5V).

-- Why Perl?

1) Perl compilation is extremely fast for
reasonable size scripts, making it a good fit for the kind
of iterative programming required when writing an 
import or export script.

2) Perl was originally created for text processing and
report generation, so it simplifies many tasks associated
with file and text processing. Most waveform files are
stored in an ASCII (text) format. Perl also has more
than adequate support for binary file formats.

3) Perl is object-oriented. This makes it possible to
do a direct mapping from TWF internal functions (written
in C++) to Perl functions. Of course, it also means you
can write your own objects in Perl!

4) Perl is extensible. Many Perl modules have already been
placed in the public domain that extend the capabiliities
of Perl, and more are being written all the time. See the
Perl documentation for information on available Perl modules.

5) Perl is fun! Although Perl syntax may first appear
cryptic due to the use of $, @,  and % in variable names,
you will quickly come to appreciate the ease with which
you can write code that would require hours or even
days in C or C++.

-- Things you should know before tweaking a Perl script


                    Perl data types

A Perl variable can be one of three data types: scalar 
(contains a single value), array (integer-indexed array 
of scalar values), and associative arrays (array of scalar
values indexed using a string). In Perl, the type of a
variable dictates the first character of its name. Scalars
begin with a $ (e.g. $myValue), arrays begin with a @ (e.g.
@myArray), and associative arrays begin with a % (e.g. %myHash).

Scalar values can store character strings, numbers,
and references (Perl equivalent of pointers). Scalar values
are automatically converted between strings and numbers
depending on what the function they are passed to expects.


                 Perl's global variables

Perl contains a number of pre-defined global variables. To
distinguish these variables from user-created variables,
the pre-defined variable names are all two characters where
the first character sets the data type ($,@,or %) and the
second character is a non-alphabetic character. 

The most important pre-defined variable is $_. $_ is the 
default scalar upon which many functions automatically 
operate if the functions are called without parameters. 
For example, the statement: 

$l = <STDIN>;

reads a line of characters from standard input into the 
variable $l. If the result of <STDIN> wasn't assigned to $l:

<STDIN>;

then $_ would be assigned the line of characters.

The second most important pre-defined variable is @_.
@_ is the array used to pass arguments to subroutines. At
the beginning of most subroutines you will see a statement
similar to the following:

my ($var1,$var2) = @_;

This copies the first argument from the subroutine call
into $var1 and the second argument into $var2.


         Pattern matching (regular expressions)	

The most common way to search and change text (strings)
in Perl is using regular expressions. Regular expressions
are constructs used to define a pattern to match a string 
against. They are commonly used in many Unix programs. If you 
are not familiar with regular expressions, you should read
the perl documentation on regular expressions (since perl
adds some enhancements to normal regular expressions you
should probably look at this section even if you are
already familiar with regular expressions).

One tip on writing regular expressions: it's often easier
to code a complicated regular expression than it is to
read and interpret it later, so it's a good idea to
document the purpose of a regular expression unless it
is extremely simple.

-- Notes on writing import/export scripts

When running an import script (executed from File/Open
menu option), the file specified by the user in the 
"Open File" dialog is redirected to standard input. This
means that any data read from standard input by your
import script is actually read from the file specified
by the user.

When running an export script (execute from "File/Save As" or
"Export/Export As" menu options), standard output is 
redirected to the file specified by the user in the "Save As"
dialog. Whenever you print something in your export script
without specifying a file handle it gets printed to 
standard output (the export file specified by the user).

-- Tips on debugging Waveperl scripts

Error messages during compilation or execution of a waveperl
script are redirected to a file called waveperl.err. When
debugging a new script it is a good idea to constantly watch
this file! Generally you will want to have at least three
windows up when debugging your script: one for TWF, one
for your script, and one for waveperl.err.

When debugging an export script, the simplest way to view
debugging information is to temporarily add extra print 
statements to your script that will show up in the exported 
file.

When debugging an import script, the simplest way to view
debugging information is to print debug info to waveperl.err.
To do this, add the statement:

select STDERR;

to the beginning of your perl import script. This will redirect
the output of print statements to waveperl.err (don't do this
for an export script as it will redirect your export output).
Of course, you can also open your own file using perl and 
print error messages to it using its file handle.

To make a change to your perl script and execute the new
script, just modify the file, save your change, and 
re-execute the script from TWF. You do NOT have to restart
TWF. Your script is dynamically re-compiled by the Perl
engine inside TWF.