File Object Agents

 

File
The File() constructor accepts a string that points to the location of a disk file, and an optional mode string that states how to open the file. Then the file command returns a File Object Agent.

sceneFile = File(“/temp.lws”,”w”);

The following list contains the File open modes, which are identical to those provided by C:

r read (ascii)
w write (ascii)
a append (ascii)
b binary (i.e., “rb” would be read-binary)
+ with update (i.e., the file pointer can be moved arbitrarily)

For example, to open a file for random binary read access, you specify “rb+” as the open mode for your file. If you do not specify the optional open mode, then the file is opened in read-ascii (r) mode by default.

The File Object Agent methods that deal with binary file modes now accept an optional Boolean argument that indicates whether or not the read numeric value should have its byte ordering swapped.  By default, byte ordering will remain as it was read in from the file.  Passing a Boolean true will cause the byte ordering to be swapped before the value is returned.

URL Referencing
LScript v2.7 provides hooks in its functionality for a rather interesting new feature: URL file referencing. Currently, this functionality will be employed by LScript in cases where external script components are referenced (Object Agents, include files, etc.).

In order to activate this functionality, you must first acquire the shared-library build for your platform of the W3C code distribution called libwww.

Once you have these files (numbering approximately 26 *.dll files for the Windows distribution), they must be placed in the "w3c" subdirectory of the LScripts/ installation directory. For example, if you have installed LightWave in "C:\LightWave", then the libwww files must be placed in "C:\LightWave\LScripts\W3C" in order to activate this dormant LScript functionality.

Once the W3C files are correctly located and loaded into LScript, your script can specify URL references for script components instead of local filenames. For instance, a script could then reference an Object Agent include file published on an HTTP server as:

...
@include "http://www.myobjectagents.com/cooloa.inc"
...

Further, inside the referenced include file, the Object Agent declaration line would then utilize a URL instead of a file path to bring down the actual Object Agent binary file from the HTTP server:

...
use "http://www.myobjectagents.com/cooloa.oal" as class CoolOA;
...

As with Web pages in your favorite brower, files retrieved from an HTTP server in this fashion are cached locally on your machine (in the same folder as the W3C directory). Each time the files are referenced by URL, the local file dates are checked with the HTTP server, and files with newer dates are refreshed locally. In this way, the component publisher has only to update the files on their HTTP server, and all people using them will receive the updates automatically the next time any script referencing them is executed.

Methods

open(string, mode)
open(string, mode) opens a new file with a specified mode ("r" for read or "w" for write). The newly opened file is assigned to the existing File Object Agent.

IsOpen()
IsOpen() returns a Boolean value indicating that the file is open and accessible.

reopen(mode)
reopen(mode) closes the currently open file, and reopens it in the specified mode ("r" for read or "w" for write).

close()
close()closes the currently open file.

eof()
eof() returns a Boolean value (true/false) indicating whether the file has reached the EOF marker.

rewind()
rewind() resets the file read/write point to the beginning of the file.

name()
name() returns a string containing the name (and path, if it was originally specified) of the currently open file.

write(dataType[,itemN])
writeln(dataType[,itemN])

write() places a series of one or more arguments to the file. writeln() is identical to write() except that a newline character is appended to the line. These commands are illegal when the file is opened in Binary mode.

writeByte(integer)
In ASCII mode, the writeByte(integer) function will write an integer value into the text file as a character. In Binary mode, the provided value is stored in the file as a single binary value of size unsigned character.The value returned is the number of bytes written to the file.

writeData(datablock)

Using writeData(), you can send the binary data in a block to a disc file. This can be used to re-create binary files from the embedded binary data within the script. For instance, a LightWave object file can be embedded in a script and carried along with the script until needed:

@version 2.2
@warnings

generic
{
output = File("ball.lwo","wb");
output.writeData(ball);

// important! the file must be closed to flush any
// remaining data to disc before the call to
// LoadObject()

output.close();

LoadObject("ball.lwo");

filedelete("ball.lwo");
}

@data ball
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
000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 000 080 078 084 083
...
@end

writeInt(integer)
In ASCII mode, the writeInt(integer) function will write a numeric integer value into the text file as a character. In Binary mode, a single binary value of size integer is written to the file. The value returned is the number of bytes written to the file.

writeNumber(number)
In ASCII mode, the writeNumber(number) function will write a value into the text file as a floating-point number in character format. In Binary mode, a string is written to the file. The value returned is the number of bytes written to the file.

writeDouble(number)
writeDouble() will store a numeric value of double-size (usually eight bytes)

writeShort(number)
writeDouble() will store a numeric value of short-size (usually two bytes)

writeString(string)
In ASCII mode, the writeString(string) function will write a value into the text file as a string in character format. In Binary mode, a single binary value of size double is written to the file. The value returned is the number of bytes written to the file.

writeVector(vector)
In ASCII mode, the writeVector(Vector) function will write a value into the text file as three floating point numbers separated by spaces in character format. In Binary mode, a triple binary value of size double is written to the file. The value returned is the number of bytes written to the file.

read()
read()reads a text line from the file, returning it as a character string. This function is illegal when the file is opened in Binary mode.

readByte()
In ASCII mode, the readByte()function will return a single character from the text file as an integer value. In Binary mode, a single binary value of size unsigned char is read from the file and returned as an integer value.

readInt()
In ASCII mode, the readInt() function will read a sequence of characters from the text file and return an integer data type. In Binary mode, a single binary value of size integer will be read from the file.

readNumber()
In ASCII mode, the readNumber() function reads a sequence of characters from the file, converting them to a single numeric (floating-point) value. In Binary mode, a single numeric value (of size double) is read from the file.

readDouble()
readDouble() will read a numeric value of double-size (usually eight bytes)

readShort()
readShort() will read a numeric value of short-size (usually two bytes)

readString()
In ASCII mode, the readString() function reads a sequence of characters from the file, converting them to a string value. In Binary mode, a single string is read from the file.

readVector()
In ASCII mode, the readVector() function will read a sequence of characters from the file, return them as a vector data type. The data in the file should appear as space-separated, floating-point numbers. In Binary mode, three numeric values each of size double will be read and returned as a vector.

parse(string)
parse(string) reads a line from the file, and returns a variable number of elements representing the tokens of the line. These elements are stored in a character array. Tokens are separated by one of the characters provided in the character string argument. This function is illegal in Binary mode.

nl()
nl()writes a new line character to the file. This command is illegal in Binary mode.

linecount()
When the file is opened in ASCII mode, the linecount() function returns the number of text lines in the currently-open file. However, in Binary mode, it returns the size, in bytes, of the file.

line([integer])
In ASCII mode, the line([integer])function returns the current line number in the file when no argument is provided. When a integer value is provided that falls within the range of text lines in the file, it will move the file pointer to the line number indicated. It is illegal in Binary mode.

offset([integer[,method]])
Called without parameters, the offset([integer[,method]]) method will return the current byte offset of the file. Providing an integer value will cause the file pointer to be placed at the specified offset in the file, relative to an offset method. This optional offset method can be one of the following:

FROMSTART will position the file from the beginning (and is the default when no method is specified);

FROMEND will position from the end of the file;

FROMHERE assumes that the provided offset value is relative to the current location of the pointer.

Examples:

@version 2.2
@warnings
@script generic
@name FileObjectAgentTest

// global values go here

generic
{
    file = "C:/newtek/scenes/benchmark/DOF.lws";
    f = File(file,"r") || error("Cannot open file
    '",file,"'");

     if(f.linecount())
    {
         // Display some Method values.
         info("Linecount: ", f.linecount());

     // Read and display the first line.
    line1 = f.read();

     if(line1 != "LWSC")
         error("Not a valid LightWave Scene!");
    else
         info("line1: ", line1);

     // Read and display the next line.
    line2 = f.read();
    info("line2: ", line2);
    }
}

General commands

filerename
The filerename() command renames a file on disk. The first argument is the file that already exists and the second argument is the new filename that you want to apply.

filerename(“c:\\test.txt”, “C:\\test2.txt”);

fileredelete
The filedelete() command deletes a file on disk.

filedelete(“c:\\test.txt”);

filestat
The filestat() function returns various system-related values associated with the file on disk. When filestat() is passed a valid filename, it returns (in order) the file’s last access time, creation time, and last modification time, the file size, the number of links to the file (UNIX or NTFS file systems only), the file owner’s user id (UNIX only), and the file’s group id (UNIX only).

(a,c,m,s,l,u,g) = filestat(“/etc/profile”);

All values are integers, and the access, creation, and modification times can be arguments for the time() and date() functions.

fullpath

The fullpath() function takes a single path value (string), and returns a full path version if the provided path is relative. If the path is already a full path, then that value is returned.

path1 = fullpath(“test2.txt”);
// result: “E:\content\test2.txt”
path2 = fullpath(“c:\\test2.txt”);
// result: ”c:\test2.txt”

getdir
The getdir() command returns the working value used by the application for any one of the following constants (string literal/ constant):

“Fonts”/FONTSDIR Modeler
“Macros”/MACROSDIR Modeler
“Install”/INSTALLDIR Layout/Modeler
                   (LW Install Dir.)
“Objects”/OBJECTSDIR Layout/Modeler
“Images”/IMAGESDIR Layout/Modeler
“Motions”/MOTIONSDIR Layout/Modeler
“Temp”/TEMPDIR Layout/Modeler
“Plugins”/PLUGINSDIR Layout/Modeler
“Scripts”/SCRIPTSDIR Layout/Modeler
    returns the executing script's directory
“Settings”/SETTINSDIR Layout/Modeler
This points to the alternate Configs directory, a good place to store settings as a file for your plugins.
“Content”/CONTENTDIR Layout
“Scenes”/SCENESDIR Layout
“Hierarchies”/HIERARCHIESDIR Layout
“Surfaces”/SURFACESDIR Layout
“Output”/OUTPUTDIR Layout
“Animations”/ANIMATIONSDIR Layout
“Envelopes”/ENVELOPESDIR Layout
“Previews”/PREVIEWSDIR Layout
“Command”/COMMANDDIR Layout

You might retrieve one of these directory values in the following fashion:

install = getdir(“Install”);
plugins = getdir(PLUGINSDIR);

getsep
A getsep() function has been added that will return the platform-specific path separator character.

...
info(getsep()); // displays "\", "/" or ":" depending on the operating system
...

getfile
getfile() gives LScript an interface for selecting files. When you need to let the user specify a disk file, getfile() posts a fileselection dialog box, and returns the file name (including path information) that the user selects. If the user cancels, getfile() will return nil.

All of getfile()’s parameters are optional. You can specify a title for the dialog box, a file name mask, and even a default directory.

getfile([title],[mask],[dir],[reqtype]);

title -- String; dialogue box title
mask -- String; file mask to use, which can include * wildcards
dir -- String; start directory
reqtype -- Boolean; 0 = save, 1= open


getfolder
This function is similar to getfile() except it only allows the user to select folders. It takes two optional parameters: the first is the title of the dialog (defaults to "Select A Folder"); the second is a starting path. Returns a string representing the path to the selected folder, or returns nil if the user cancelled.

getfile([title],[dir]);

title -- String; dialogue box title
dir -- String; start directory

getmultifile (LW 9.2 or above only)
This presents an open file dialog box that allows the user to selection one or more files for opening. The selected files are returned to the script as an array

getmultifile([title],[mask]);

     title string; dialog box title
     mask string; file mask to use (can include wildcards)

filefind
filefind() takes a file name (sans path information) and scans through the directory paths in the application in order to locate the file. The path to the file is returned.

if((where = filefind("lw.cfg")) != nil)
{
...

This function uses those paths that are available to the getdir() function in order to find the file.

filecrc
A new function called filecrc() calculates the CRC-32 value of the contents of a file, and returns this integer value.

library
The Layout LScript Compiler provides a new mode for generating compiled scripts. This new compiled type is a "library", and is intended to be a collection of functions (potentially unrelated) that are not associated with any single plug-in architecture. Once compiled, this "library" script can be used by any LScript through the use of the library command.

Functions defined within the "library" file can be referenced from a script as though they were built into LScript.

@version 2.6
@warnings
@script generic

// the 'functions.lsc' library contains the gimmeStringFrom() function

library "functions.lsc"; // no path, so file should be in \NewTek\LScripts

generic
{
t = 104;
info(gimmeStringFrom(t));
}

matchfiles
The matchfiles() command scans a directory for files and folders that match a pattern. matchfiles() returns an array with files that match the given path and search parameters.

path1 = matchfiles(“c:\\”, “*.txt”);

matchdirs
The matchdirs() command returns an array with folders that match the given search parameters.

path1 = matchdirs(“c:\\”, “*.*”);

chdir
chdir() is one of three functions for managing directories that LScript offers to you. When you use this function, you can change the “working” directory of an LScript from the directory where the script was started. This command also returns a character string with the current “working” directory as a full path.
The chdir() command can be handy for launching external processes that must run from a specific directory. ScreamerNet is a perfect example of such a process: ScreamerNet must be launched from the NewTek/Programs directory so it can properly locate support files, such as configuration files and images. However, your LScript may already be running in an entirely different location. The following code snippet, illustrates how chdir() solves this particular situation:


// change the “working” directory to one required
// by ScreamerNet
if((snDir = getenv(“LW3D”)) == nil)
    // is it (properly) in the environment?
oldDir = chdir(“\\windows\\apps\\newtek\\programs”);
else
    oldDir = chdir(snDir);
snID = spawn(“lwsn -2 “, getenv(“TMP”),” \\snii.job “,_
getenv(“TMP”),”\\snii.rpl”);
chdir(olddir);
// move back to our start-up directory

If the chdir() function fails to set the working directory to the one specified, a value of nil is returned.

mkdir
mkdir() is another function for directory management. An LScript can use mkdir to create a new file system directory. The function accepts a string that specifies the directory (with optional path), and returns a result code (0 means no error).

mdir(“c:\\temp2”);

rmdir
rmdir() can remove an existing directory. The directory to be removed must be completely empty for this command to succeed. As with mkdir(), this command accepts a string that specifies the directory (with optional path) to be removed, and returns a result code.

rmdir(“c:\\temp2”);

Layout Commands

LoadAudio();
LoadFromScene("<filename>");
LoadMotion("<filename>");
LoadPreview();
LoadScene("<filename>");
ReplaceWithNull("<name>");
ReplaceObjectLayer(<layer number>,<filename>);
Replace the current selected object layer with the layer chosen from the file.

ReplaceWithObject("<filename>");
Replace the current selected object layer with the file.

SaveAllObjects();

SaveRGBServer();
This allows you to set the file type for the RGB render file saver. You need to contain it in the Command Input style wrapper.
CommandInput("SaveRGBServer LW_JPEG(.jpg)");

SaveAlpha();
SaveAlphaPrefix(filename);
SaveCommandList();
SaveCommandMessages();
SaveEndomorph("<name>");
SaveLight();
SaveLWSC1("<filename>");
SaveMotion("<filename>");
SaveObject("<filename>");
SaveObjectCopy("<name>");
SavePreview();
SaveRGB();
SaveRGBPrefix(filename);
SaveScene();
SaveSceneAs("<filename>");
SaveSceneCopy("<filename>");
SaveTransformed("<filename>");
SaveViewLayout();

FileFormats
Mdd
totalframes totalPoints Times while(!totalframes) { while(!totalPoints) { write point[frame][point][axis]; point++; } frame++; }