Pragmas

 

This section describes the pragmas which lscript uses as compiler directives.All pragma directives must now begin in the first column of the row in order to be recognized. This is to remove confusion when an initblock token ('@') appears as the first character on the line (at a column other than the first).

@version
This tells Lightwave which version or above of lscript should be used.

@warnings
Turns warnings on or off.

@asyncspawn
Allows the spawn() command to spawn asynchronosly.

@script
The LScript pre-preprocessor supports a pragma directive called "script". This directive is an identifier that is intended to aid LightWave's LCore system to identify a script being added as a plug-in.

@script modeler
@script displace
@script generic
@script motion
@script image
@script replace
@script master
@script shader
@script channel

@name
Allows you to name a script something other than the filename of the script.

@insert(filename)
Allows you to use functions from another specified script. The Filename can be relative.
This recognizes the metacharacter '@' at the start of the insertion string. This metacharacter indicates relative pathing for the file to be inserted, allowing files to be located relative to the location of the original script.
For example, say you have two files in the same folder, one named "file1.ls" and the other named "file2.ls". Further, the first file performs an @insert of the second file. In order to successfully insert the second file without the need of maintaining specific absolute pathing, you need only specify the name of the second file preceeded by the '@' symbol:

@insert "@file2.ls"

@fpdepth
The 'fpdepth' pragma specifies the number of digits to the right of the decimal that are to be considered significant when floating point values (numbers, vectors, etc.) are compared for equality. The pragma setting has domain over the entire run-time operation of the script.

@fpdepth 3

@data
Binary data can now be embedded directly within an LScript. This data is handled by LScript as nothing more than a stream of unsigned bytes. This allows any type of binary data to be embedded within the script and accessed at run-time.

Binary data is delimited between a pair of preprocessor directives, "@data" and "@end". Individual bytes are declared as integer values between 0 and 255. The data can be of any length on each line, but you should probably keep them under 80 columns for readibility and maximum editor compatibility.

Each block of binary data must be named. The name provided will become a global variable within the operating environment of the script when it begins to execute.

@data bobdata
070 079 082 077 000 000 039 064 076 087 079 050 084 065 071 083 000 000 000 010
069 121 101 000 073 114 105 115 000 000 076 065 089 082 000 000 000 018 000 000
...
@end

The binary block identifiers exist at run-time just like any other global variable in your script. They can be queried as Objects:

info(bobdata.size());

They can be used with the foreach() iterator:

foreach(x,bobdata)
{
...
}

They can be passed to functions:

info(blocksize(bobdata));

blocksize: data
{
return(data.size());
}

Their data can be accessed and modified as the script executes:

x = bobdata[25];
bobdata[25] = 0;

As a side note, not only will your script sizes be considerably smaller, but parsing of the binary data will go slightly faster if values are included as a bare minimum. For instance, "0" will parse faster than "000", and consume two less bytes in the disc file. The bytes in the examples above have been padded only for visual alignment, not out of any necessity.

@save
This can be original (which stores the full path of the script in the file), relative (which stores just the name of the lscript, and thus you should have a script of this name loaded into Lightwave) or embedded (which will store the entire script within the object or scene).
Debugging should not be attempted with embedded scripts. Debug your scripts first before you activate this saving mode.

@define
This allows you to define a variable for use with pragmas.
Example:
@define TEST 45

@sequence
This pragma allows you to define a collection of names whose values are sequential increments. This pragma type is similar to the C enum function.

A collection of sequence names is enclosed with open and close braces:

...
@sequence { ... }
...

Names in the collection are separated from one another by commas:

...
@sequence { VIEWPORT_CTL, COPY_CTL, PASTE_CTL }
...

Like lines of binary data, entries in the sequence collection can span multiple lines:

...
@sequence { VIEWPORT_CTL,
        COPY_CTL,
        PASTE_CTL }
...

By default, sequences begin at one (1) and increment by one thereafter. That is, in the example above, VIEWPORT_CTL would have the value 1, COPY_CTL would equate to 2, and so on. The sequence value can be overridden at any point by assigning a new sequence value to a collection entry:

...
@sequence { VIEWPORT_CTL,
        COPY_CTL = 5,
        PASTE_CTL }
...

In this case, VIEWPORT_CTL would still have the value of 1, but COPY_CTL would have the value 5 and PASTE_CTL would be assigned the value 6.

An increment value can also be specified by separating the sequence value from the new increment value using a colon:

...
@sequence { VIEWPORT_CTL = 1:2,
        COPY_CTL,
        PASTE_CTL }
...
With this code, VIEWPORT_CTL would still have the value of 1, but COPY_CTL would have the value 3 and PASTE_CTL would equate to 5.

Once declared, you can use these sequence entries anyplace in your script you would otherwise use a @define'd value.

@localipc
LScript's internal IPC mechanism can now be "localized" to the current host (Modeler, Screamernet, etc.). This prevents other processes running the same IPC script on the same machine from colliding with established Queues.

@if
@else
@end
The LScript pre-processor now understands a simple form of conditional code compilation. Using the new @if, @else, and @end directives, you can instruct the compiler to include--or exclude--code from compilation. The @if test expects an identifer, followed by an optional equality operator, and an optional value to test. If the optional value is omitted, then the test will succeed if the identifer exists in either the pre-processor's macro list, or in the LScript environment (enviromental testing is not performed on the Mac).

...
@if LOCALMODE
info("running in local mode");
@end
. . .

If the test value exists without an equality operator, then equality is tested by default. Recognized equality test operators are "<", ">", "<=", ">=", "==", and "!=". . . .
@define TEST 45
. . .
@if TEST > 40
info("TEST > 40");
@else
info("TEST <= 40");
@end
. . .

In addition, a "not" operator can be applied to any test to invert the result.

. . .
@if not version 1.4
scl = degree(obj.getScale(time));
@else
scl = obj.getScale(time);
@end
. . .

Recognised symbols
host_build
host_version
compiler
version
LOCALMODE
running_under (one of LAYOUT,MODELER, or SCREAMERNET)