Class: Compiler

The Compiler package consists of functions, datatypes, and constants that are used by Livelink itself to compile, manipulate, and examine Script values and their corresponding OScript source code. This includes the ability to compile OScript source into a Script value, which can then be executed, as well as a variety of functions for internal use only (to support the Livelink SDK).

With the exception of Compiler.Compile(), these functions are not intended for general use by a Livelink application developer and should only be used with extremely careful consideration, if at all. Elements labelled Internal Use Only below may have their interface changed without notice.

A bit of background is necessary to fully understand these functions. Compiled OScript is stored as a value of type Script. Scripts can be executed directly, or stored in object features as methods. Typically, Script values contain both binary code for the OScript virtual machine, as well as the original source code that produced the compiled code. It is possible (using Compiler.MakeScript()), to construct a Script that contains no binary code. The OScript engine will try to compile this type of script "on-the-fly" when it is executed, although this will much slower than using a precompiled script.

Breakpoints - Currently, breakpoints are stored within the compiled script code stored within a Script value. This implies, of course, that a Script containing no compiled code cannot store breakpoints. It should also be noted that the current Compiler functions permit the setting of a breakpoint only at the beginning of a Script (i.e., the first executable statement).

SourceRef - Some of these functions refer to something called a sourceRef. A SourceRef is a String value which defines where the script source originated. This is used internally by the Livelink debugger to correspond compiled scripts with their sources, which may be text files or OSpace object features. By convention only, a SourceRef has the form <resource_type>:<resource_data>. For example, the SourceRef String "file:c:\opentext\joe.lxe" has a resource_type of file. The following SourceRef resource types should be considered reserved: file, weblingo, object, oppfile.

E_CompilationErrors: Indicates errors during compilation.
kLogConversionInfo: Internal use only.
kStripSource: Internal use only.

ClearBreaks( Script theScript ): Clears all breakpoints in the specified script.
Compile( Dynamic sourceValue, [String sourceRef] ): Compiles OScript source into a Script value.
CompileGeneral( Dynamic sourceValue, [String sourceRef], [Integer compilationFlags] ): Compiles OScript and returns a List of errors.
GetBreakOnEntry( Script theScript ): Returns TRUE if the given Script value contains a breakpoint on its first executable line, FALSE otherwise.
MakeScript( String source, [String sourceRef] ): Creates a Script value that contains source, but no compiled binary code.
Prototype( Script theScript ): Internal use only.
SetBreakOnEntry( Script theScript, Boolean setBreak ): Sets or clears the initial breakpoint of a script.
Source( Script theScript ): Extract the source code (if any) from a Script value.
SourceRef( Script theScript ): Extract the SourceRef (if any) from a script.

E_CompilationErrors

 Error E_CompilationErrors

Indicates errors during compilation. See Compiler.Compile() or Compiler.CompileGeneral() for more information.

kLogConversionInfo

 Integer kLogConversionInfo

Internal use only. See Compiler.Compile() or Compiler.CompileGeneral() for more information.

kStripSource

 Integer kStripSource

Internal use only. See Compiler.Compile() or Compiler.CompileGeneral() for more information.

ClearBreaks

 Script ClearBreaks(
              Script theScript )

Clears all breakpoints in the specified script. If the script is not yet compiled and source is available within the script, then it will be compiled. If the script contains compiled code, then any breakpoints present in the script will be removed and the script will be returned. If the script has no binary code or cannot be compiled, then Undefined will be returned.

Parameters:

theScript

Script value to modify.

Returns:

If successful, theScript will be returned. Otherwise, Undefined will be returned.

Compile

 Script Compile(
            Dynamic sourceValue,
           [String sourceRef] )

Compiles OScript source into a Script value. The source can be either a String, a Script, or a File value.

Parameters:

sourceValue	-	A Script, File, or String value that contains or refers to the OScript source to compile.
sourceRef	-	Internal use only. A String which is used by LivelinkSDK to determine where the source originated.

Returns:

A compiled Script value if successful, the Error value E_CompilationErrors otherwise.

If compilation errors or warnings occur, they will be displayed in the Debug Window or logfile. If only warnings are present, then a Script value will still be returned by this function, although the warnings will appear in the Debug Window or logfile. See Compiler.CompileGeneral() for a more powerful way to detect compilation errors.

Here is an example of using Compiler.Compile() to compile a simple piece of OScript:

	String	mySource = "function void myFunc( String myParam );echo( 'Parameter: ', myParam );end"
	Script	s = Compiler.Compile( mySource )
	s( "Hello World" )

The output from the above is:

	Parameter: Hello World

CompileGeneral

 List CompileGeneral(
              Dynamic sourceValue,
             [String sourceRef],
             [Integer compilationFlags] )

Compiles OScript and returns a list of errors. This is similar to the Compiler.Compile() function, except that it will return any errors or warnings that occurred during compilation. This is primarily used by the Livelink SDK.

Parameters:

sourceValue	-	A Script, File, or String value that contains or refers to the OScript source to compile.
sourceRef	-	Internal use only. A String which is used by LivelinkSDK to determine where the source originated.
compilationFlags	-	Internal use only. The following flags can be used: Compiler.kStripSource and Compiler.kLogConversionInfo.

Returns:

A tuple consisting of two elements: the first is either the compiled Script or the Error E_CompilationErrors, the second is a possibly empty list of error message Strings. These error message Strings consist of three parts, separated by an end-of-line (ASCII 10) character.The first part indicates the type or severity of error: Warning, Error, Fatal, or Info. The second part indicates the actual error text, and the third part indicates where in the source that the error occurs.

Here is an example of using Compiler.CompileGeneral() to successfully compile a simple piece of OScript:

	String	mySource = "function void myFunc( String myParam );echo( 'Parameter: ', myParam );end"
	List	tuple = Compiler.CompileGeneral( mySource )
	if IsNotError( tuple[ 1 ] )
		tuple[ 1 ]( "Hello World" )
	end

And the output from the above is:

	Parameter: Hello World

The following example shows how errors can be extracted:

	String	mySource = "function void myFunc( String myParam );echo( 'Parameter: ', myBuggyParam );end"
	List	tuple = Compiler.CompileGeneral( mySource )

	if IsError( tuple[ 1 ] )
		String	s
		for s in tuple[ 2 ]
			echo( "Error before breakup: /", s, "/" )
		
			List	errTuple = Str.Elements( s, Str.Eol() )
			echo( "...Severity: ", errTuple[ 1 ] )
			echo( "...Text: ", errTuple[ 2 ] )
			echo( "...Range: ", errTuple[ 3 ] )
		end
	end

And the output from the above is:

	Error before breakup: /Error
	The name 'myBuggyParam' is not known at this point. Please check your spelling and compile again.
	[1.60:1.72]/
	...Severity: Error
	...Text: The name 'myBuggyParam' is not known at this point. Please check your spelling and compile again.
	...Range: [1.60:1.72]

Note that even a successful compilation can result in warnings, which will be returned from Compiler.CompileGeneral().

GetBreakOnEntry

 Boolean GetBreakOnEntry(
                 Script theScript )

Returns TRUE if the given Script value contains a breakpoint on its first executable line, FALSE otherwise.

Parameters:

theScript

Script value to examine.

Returns:

TRUE if the given Script value contains a breakpoint on its first executable line, FALSE otherwise.

Note that there is currently no scripting interface that permits setting arbitrary breakpoints within a script. Currently, only the initial executable statement of a script can be affected via Compiler.SetBreakOnEntry() and Compiler.GetBreakOnEntry().

MakeScript

 Script MakeScript(
              String source,
             [String sourceRef] )

Creates a Script value that contains source, but no compiled binary code. The script can still be executed later, although this will require it to be compiled "on-the-fly", perhaps at a substantial performance penalty.

Parameters:

source	-	A String containing OScript source code.
sourceRef	-	Internal use only. A String which is used by LivelinkSDK to determine where the source originated.

Returns:

A Script value that contains no compiled code, but that has the specified source code within it.

Prototype

 List Prototype(
           Script theScript )

Internal use only. Describes the function prototype(s) within a compiled script by returning a list containing function names, return types, and parameter names and types.

Parameters:

theScript

A compiled Script whose function(s) are described as prototypes.

Returns:

A List if successful, or Undefined otherwise. If successful, the first element is a List with two elements, the Integer type number of the value returned by the main function (for example IntegerType), and the String name of the main function. The second element is a List of Lists, where each List defines a formal parameter using two elements; the first element is the Integer data type of the parameter, and the second element is the String name of the parameter. This function returns Undefined if theScript is not a Script, or if theScript cannot be successfully loaded or compiled.

The following example illustrates the use of this function:

	String	src = "function Integer MyFunc( String myParam1, Integer myParam2 );end"
	Script	s = Compiler.Compile( src )
	List	proto = Compiler.Prototype( s )
	echo( "Compiler.Prototype() returns: ", proto )
	echo( "The first function is named: ", proto[ 1 ][ 2 ] )
	echo( "The first function is typed: ", Datatypename( proto[ 1 ][ 1 ] ) )
	echo( "The first parameter is named: ", proto[ 2 ][ 1 ][ 2 ] )
	echo( "The first parameter is typed: ", Datatypename( proto[ 2 ][ 1 ][ 1 ] ) )
	echo( "The second parameter is named: ", proto[ 2 ][ 2 ][ 2 ] )
	echo( "The second parameter is typed: ", Datatypename( proto[ 2 ][ 2 ][ 1 ] ) )

The output from the above is:

	Compiler.Prototype() returns: {{2,'MyFunc'},{{-1,'myParam1'},{2,'myParam2'}}}
	The first function is named: MyFunc
	The first function is typed: Integer
	The first parameter is named: myParam1
	The first parameter is typed: String
	The second parameter is named: myParam2
	The second parameter is typed: Integer

Limitation: The Livelink 8.0 version of this function can only return information about the first entry point within a Script. A future version of Livelink will extend this function in an upward compatible fashion to return a list containing information about all of the entry points.

SetBreakOnEntry

 Script SetBreakOnEntry(
                Script theScript,
                Boolean setBreak )

Sets or clears the initial breakpoint for a script. Given a Script value, this either sets or clears the initial breakpoint (i.e., the break-on-entry state) for the Script. The modified script is returned. See GetBreakOnEntry().

Parameters:

theScript	-	Script value to modify
setBreak	-	TRUE means that the breakpoint will be set, FALSE means that it will be cleared

Returns:

If successful, a script identical with theScript is returned, otherwise, Undefined is returned.

Source

 String Source(
            Script theScript )

Extracts the source code (if any) from a Script value.

Parameters:

theScript

Script value to extract source from.

Returns:

A String containing the source code. In the event that the script was compiled without source (e.g., via Compiler.kStripSource), then this function will return the empty string ("").

Most OScript source is stored as source lines separated by newline characters (i.e., Str.EOL() or ASCII 10).

SourceRef

 String SourceRef(
             Script theScript )

Extract the SourceRef (if any) from a script. This is used internally by the Livelink SDK to synchronize information between the compiler, debugger, inspector and other SDK tools.

Parameters:

theScript

Script value to extract SourceRef from.

Returns:

A String containing the SourceRef, or the empty string ("") if there is no SourceRef.