Class

XojoScript

Description

Used to dynamically execute code within a running (compiled) application.

Properties

Name	Type	Read-Only	Shared
Context	Object
Source	String
State	Integer

Methods

Name	Parameters	Returns
Compile	optimizationLevel As OptimizationLevels	MemoryBlock
Precompile	optimizationLevel As OptimizationLevels	Boolean
Reset
Run	cachedObject As MemoryBlock = Nil

Events

Name	Parameters	Returns
CompilerError	location As XojoScriptLocation, error As Errors, errorInfo As Dictionary
CompilerWarning	location As XojoScriptLocation, warning As Warnings, warningInfo As Dictionary
Input	prompt As String	String
Print	msg As String
RuntimeError	error As RuntimeException

Enumerations

XojoScript.Errors

Errors

These are the errors than can occur when compiling XojoScript or IDE Scripts.

Integer Value	Enum Value	Description
1	Syntax	Syntax error.
2	TypeMismatch	Type mismatch error.
3	UsingOnlyImportsModules	Only modules can be imported, but this is not a module.
4	CantImportSymbolOverExistingSymbol	Can't import symbols over an existing symbol.
5	ParserStackOverflow	The parser's internal stack has overflowed.
6	TooManyParameters	Too many parameters for this function.
7	NotEnoughParameters	Not enough parameters for this function call.
8	WrongNumberOfParameters	Wrong number of parameters for this function call.
9	IncompatibleParameterList	Parameters are incompatible with this function.
10	IncompatibleAssignment	Assignment of an incompatible data type.
11	UndefinedIdentifier	Undefined identifier.
12	UndefinedOperator	Undefined operator.
13	LogicOpsRequireBooleans	Logic operations require Boolean operands.
14	ArrayBoundsMustBeConstant	Array bounds must be integers.
15	CallNonFunction	Can't call something that isn't a function.
16	SubscriptNonArray	This is not an array but you are using it as one.
17	NotEnoughDimensions	This array has more dimensions than you have provided.
18	TooManyDimensions	This array has fewer dimensions than you have provided.
19	ArrayMethod1DOnly	Can't assign an entire array.
20	ArrayCast1DOnly	Can't use an entire array in an expression.
21	ExpressionByRef	You can't pass an expression as a parameter that is defined as ByRef.
22	DuplicateIdentifier	Redefined identifier.
23	BackendFailed	The backend code generator failed.
24	AmbiguousMethodCall	Ambiguous call to overloaded method.
25	NoMultipleInheritance	Multiple inheritance is not allowed.
26	CantInstantiateInterface	You cannot create an instance of interface with New because it is not a class.
27	ImplementNonInterface	One of the interfaces of this class is not of type class interface.
28	InheritNonClass	You can only inherit from a class.
29	DoesNotFullyImplementInterface	This class does not fully implement the specified interface.
30	OnlyObjectsHaveEvents	Event handlers cannot live outside of a class.
31	CantIgnoreFunctionResult	You must use the value returned by this function.
32	CantUseSelfOutsideAClass	"Self" doesn't mean anything in a module method.
33	CantUseMeOutsideAClass	"Me" doesn't mean anything in a module method.
34	ReturnValueFromSub	You cannot return a value because this method has not defined a return type.
35	NonExceptionType	Exception objects must be subclasses of RuntimeException.
36	MismatchReturnInterfaceMethod	Return type does not match the interface method's return type.
37	MismatchReturnOverrideMethod	Return type does not match overridden method's return type.
38	ImplementNonexistentEvent	You cannot implement a nonexistent event.
39	ImplementNonexistentEvent	You cannot implement a nonexistent event.
40	NoDestructorParameters	Destructors can't have parameters.
41	CantUseSuperOutsideAClass	Modules do not have superclasses. So "Super" does not mean anything in a module method.
42	CantUseSuperWithoutASuper	The current class does not have a superclass, so "Super" does not mean anything in this method.
43	UnbalancedCompileElse	This #else does not have a matching #if preceding it.
44	UnbalancedCompileEndIf	This #endif does not have a matching #if preceding it.
45	CompileIfConditionNotBoolean	Only Boolean constants can be used with #if.
46	CompileIfConditionNotConstant	Only constants expressions can be used with #if.
47	ForLoopMultiplyIndexed	The Next variable does not match the loop's counter variable.
48	ArrayBoundsMustBeConstant	The size of an array must be a constant or number.
49	ArrayTypeInExternalCode	You can't pass an array to an external function.
50	ObjectTypeInExternalCode	External functions cannot use objects as parameters.
51	StringTypeInExternalCode	External functions cannot use ordinary strings as parameters. Use CString, PString, WString, or CFStringRef instead.
52	UnsortableDataType	This kind of array can not be sorted.
53	AccessProtectedProperty	This property is protected. It can only be used from within its class.
54	AccessProtectedMethod	This method is protected. It can only be called from within its class.
55	NameDuplicatesDeclareFunction	This local variable or constant has the same name as a Declare in this method. You must resolve this conflict.
56	NameDuplicatesFunction	This global variable has the same name as a global function.
57	NameDuplicatesMethod	This property has the same name as a method. You must resolve this conflict.
58	NameDuplicatesEvent	This property has the same name as an event. You must resolve this conflict.
59	NameDuplicatesClass	This global variable has the same name as a class.
60	NameDuplicatesModule	This global variable has the same name as a module.
61	NameDuplicatesConstant	This local variable or parameter has the same name as a constant. You must resolve this conflict.
62	NameIsReservedKeyword	This identifier is reserved and can't be used as a variable or property name.
63	NoClassByThatName	There is no class with this name. Can't find a type with this name.
64	DeclareLibMustBeStringConstant	The library name must be a string constant.
65	DeclareFunctionWithNoReturnType	This Declare Function statement is missing its return type.
66	CantInstantiateAbstractClass	You can't use the New operator with this class.
67	SubReturnsNoValue	This method doesn't return a value.
68	MissingEndQuote	End quote missing.
69	ClassDescendsFromSelf	A class cannot be its own superclass.
70	AssignToReadOnlyProperty	Cannot assign a value to this property.
71	ReadFromWriteOnlyProperty	Cannot get this property's value.
72	IfMissingCondition	The If statement is missing its condition.
73	MissingReturnTypeInFunction	The current function must return a value, but this Return statement does not specify any value.
74	IncompatibleParameterOptions	Parameter options are incompatible.
75	DuplicateParamOption	Parameter option was already specified.
76	ByRefWithDefaultValue	A parameter passed by reference cannot have a default value.
77	ParamArrayWithDefaultValue	A ParamArray cannot have a default value.
78	AssignsParamWithDefaultValue	An Assigns parameter cannot have a default value.
79	ExtendsParamWithDefaultValue	An Extends parameter cannot have a default value.
80	ExtendsParamMustBeFirst	Only the first parameter may use the Extends option.
81	AssignsParamMustBeLast	Only the last parameter may use the Assigns option.
82	ParamArrayMustBeLast	An ordinary parameter cannot follow a ParamArray.
83	OnlyOneAssignsParamPerMethod	Only one parameter may use the Assigns option.
84	OnlyOneParamArrayPerMethod	Only one parameter may use the ParamArray option.
85	ParamArray1DOnly	A ParamArray cannot have more than one dimension.
86	IfWithoutThen	The keyword "Then" is expected after this If statement's condition.
87	UndefinedMemberIdentifier	Undefined member identifier.
88	ConstantWithVariableValue	Constants must be defined with constant values.
89	IllegalUseOfCall	Illegal use of the Call keyword.
90	CaseFollowingCaseElse	No cases may follow the Else block.
91	UnknownPropertyAccessorType	A computed property can only contain "Get" and "Set" blocks.
92	MismatchedPropertyAccessorTypes	A computed property getter or setter block ends with the wrong "end" line. For example, if you start the block with "Get", it must end with "End Get".
93	DuplicateMethodDeclaration	Duplicate method definition.
94	EmptyDeclareLibString	Syntax Error: The library name for this declaration is blank.
95	IfMissingEndIf	This If statement is missing an End If statement.
96	SelectMissingEndSelect	This Select Case statement is missing an End Select statement.
97	ForMissingNext	This For loop is missing its Next statement.
98	WhileMissingWend	This While loop is missing its Wend statement.
99	TryMissingEndTry	This Try statement is missing an End Try statement.
100	DoMissingLoop	This Do loop is missing its Loop statement.
101	TooFewParentheses	Too few parentheses.
102	TooManyParentheses	Too many parentheses.
103	CantUseContinueOutsideOfALoop	There is no block to continue here.
104	CouldntFindMatchingLoop	There is no (%1) block to (%2) here.
105	CantAccessInstancePropertyFromSharedMethod	Shared methods cannot access instance properties.
106	CantAccessInstanceMethodFromSharedMethod	Instance methods need an object: call this on an instance.
107	CantAccessInstancePropertyFromSharedPropertyAccessor	Shared computed property accessors cannot access instance properties.
108	CantAccessInstanceMethodFromSharedPropertyAccessor	Shared computed property accessors cannot access instance methods.
109	ConstructorIsProtected	The Constructor of this class is protected, and can only be called from within this class.
110	StructureStringWithNoLength	This string field needs to specify its length.
111	StructureCantContainRefType	Structures cannot contain fields of this type.
112	StructureArrays1DOnly	Syntax Error: Structures cannot contain multidimensional arrays.
113	EnumsOnlyInt	Enumerated types can only contain integers.
114	NoStackedEnums	An enumeration cannot be defined in terms of another enumeration.
115	AssignToConstant	This is a constant; its value can't be changed.
116	IllegalStructureStringLength	A String field must be at least 1 byte long.
117	NonStringFieldWithLength	The storage size specifier only applies to String fields.
118	StructureContainsSelf	A structure cannot contain itself.
119	InstantiateStructure	Cannot create an instance of structure with New because it is not a class.
120	InstantiateEnum	Cannot create an instance of enum with New because it is not a class.
121	AccessPrivateType	This type is private, and can only be used within its module.
122	GlobalItemInClass	Class members cannot be global.
123	ProtectedItemInModule	Module members must be public or private; they cannot be protected.
124	GlobalItemInInnerModule	Members of inner modules cannot be global.
125	DimMultipleUsingNewObjectShortcut	A Dim/Var statement creates only one new object at a time.
126	ConstValueExpected	A constant was expected here, but this is some other kind of expression.
127	AccessPrivateModule	This module is private, and can only be used within its containing module.
128	DuplicatePropertyDeclaration	Duplicate property definition.
129	InvalidArrayElementType	This datatype cannot be used as an array element.
130	DelegateOptionalParameter	Delegate parameters cannot be optional.
131	DelegateParameterRole	Delegates cannot use Extends, Assigns, or ParamArray.
132	RbScriptSandboxDeclare	The Declare statement is illegal in XojoScript.
133	RbScriptSandboxPtr	It is not legal to dereference a Ptr value in XojoScript.
134	RbScriptSandboxDelegateFromPtr	Delegate creation from Ptr values is not allowed in XojoScript.
135	DuplicateConstantDeclaration	Duplicate constant definition.
136	AmbiguousInterfaceImplementation	Ambiguous interface method implementation.
137	ClassDoesNotImplement	Illegal explicit interface method implementation. The class does not claim to implement this interface.
138	InterfaceMethodDoesNotExist	The interface does not declare this method.
139	UnbalancedCompileIf	This method contains a #If without a closing #endif statement.
140	CyclicalInterfaceAggregate	This interface contains a cyclical interface aggregation.
141	ExtendsOnClass	The Extends modifier cannot be used on a class method.
142	IncompatibleAssignment	You cannot assign a non-value type to a value.
143	DuplicateAttribute	Duplicate attribute name.
144	DelegateReturnStructure	Delegates cannot return structures.
145	IllegalDelegateDispatch	You cannot use AddressOf on this method. Possible causes include using AddressOf on event declarations or soft declares.
146	IllegalConversionTo	You cannot use an Operator_Convert method to perform a convert-to operation on an interface.
147	ElseIfMissingCondition	Syntax Error: The ElseIf statement is missing its condition.
148	IllegalConstType	This type cannot be used as an explicit constant type.
149	RecursiveConstantDeclaration	Recursive constant declaration error.
150	Custom	Custom error created using "Error" pragma.
151	NotALocalVariable	This is not a local variable or parameter.
152	MaxUlpsMustBeConstant	The maximum units in last position parameter must be a constant.
153	MaxUlpsOutOfRange	The maximum units in last position parameter is out of range.
154	StructureFieldAlignment	The StructureAlignment attribute's value must be of the following: 1, 2, 4, 8, 16, 32, 64, or 128.
155	RbScriptSandboxPairs	Pair creation via the ":" operator is not allowed in XojoScript.
156	RbScriptSandboxGetTypeInfo	Introspection via the GetTypeInfo operator is not allowed in XojoScript.
157	ForNextMissingCondition	The For statement is missing its condition.
158	WhileWendMissingCondition	The While statement is missing its condition.
159	UnsignedExpressionInNegativeStep	Unsigned integer used in negative step loops can cause an infinite loop.
160	MustUseObjectsWithIs	Must use Objects with Is.
161	MustUseObjectsWithAddRemoveHandler	Only objects can be used with AddHandler and RemoveHandler.
162	EventDoesNotExist	The object you are passing to AddHandler does not have the specified event.
163	RbScriptSandboxDelegateToPtr	Converting Delegates to Ptrs is not allowed in XojoScript.
164	WeakAddressOfMustHaveInstanceMethod	WeakAddressOf can only be used on instance methods.
165	RuntimeDeclaresNotAllowed	Declares directly into the runtime via Lib "" are no longer allowed.
166	ObjCDeclaresMustHaveTarget	Objective-C declares must have at least one parameter (the target of the message send).
167	ShadowedPropertyTypeMismatch	This property shadows a property of a different type.
168	JumpToMissingLabel	Goto target not found.
169	PragmaWarningNeedsMessage	'#pragma warning' requires a warning message.
170	PragmaErrorNeedsMessage	'#pragma error' requires an error message.
171	DuplicateLabel	Duplicate label.
172	ObjectPropertyWithDefaultValue	Object properties cannot have default values.
173	ArrayPropertyWithDefaultValue	Array properties cannot have default values.
174	NoIteratorsInXojoScript	For Each loops over iterable objects cannot be used in XojoScript.
175	ObjectNotIterable	This object does not implement the Iterable interface and cannot be used in a For Each loop.
178	AssignToType	This is a type name, not a variable; values can't be assigned to it.
179	AssignToModule	This is a module, not a variable; values can't be assigned to it.
180	UnresolvedType	Can't find a type with this name.
181	TypeRefIsNonTypeSymbol	Expected a type name but found %1 instead.
182	UnresolvedNamespace	Can't find a type or module with this name.
183	NamespaceRefIsNonNamespaceSymbol	Expected a type or module name here but found %1 instead.
184	ExtensionMethodRequiresConversions	Extension method %1 requires a conversion from %2 to %3; use CType to explicitly convert first.
185	UnresolvedTypeWithSuggestion	Can't find a type with this name. Did you mean %1?
186	UndefinedBinop	Undefined operator. Type %1 does not define "%2" with type %3.
187	UndefinedMonop	Undefined operator. Type %1 does not define "%2".
188	ImportGlobalMember	Cannot import %1 from %2 because it is Global, not Public.
189	ImportPrivateMember	Cannot import %1 from %2 because it is Private to its container, not Public.
190	NamespaceAsValue	Expected a value of type %1, but found a static namespace reference to %2.
191	InstantiateNonClass	Cannot create an instance of %1 with New because it is not a class.
192	InstantiateNonClassWithSuggestion	Cannot create an instance of %1 with New because it is not a class. Did you mean %2?
193	ItemNotAvailable	%1 is not available.
194	TooManyArgs	Too many arguments: got %1, expected only %2.
195	TooManyArgsWithOptionals	Too many arguments: got %1, expected no more than %2.
196	OneMissingArg	Not enough arguments: missing %3 value for parameter "%4".
197	NotEnoughArgs	Not enough arguments: got %1, expected %2.
198	NotEnoughArgsWithOptionals	Not enough arguments: got %1, expected at least %2.
199	AssignmentMethodNeedsAssignment	Assignment accessor must be invoked by assigning a value.
200	AssignToNonAssignmentMethod	This method cannot accept an assigned value (it lacks an Assigns parameter).
201	OneArgIsIncompatibleWithParam	Parameter "%1" expects %2, but this is %3.
202	ArgsAreIncompatibleWithParams	Expected (%1), but these arguments are (%2).
203	OneArgIsIncompatibleWithParamArray	ParamArray "%1" expects values of %2, but this is %3.
204	CallInstanceMethodInSharedContext	Instance methods need an object: call this on an instance of %1.
205	CallExtendsMethodWithNoBaseExp	Extension methods need a base expression: call this on a value of %1.
206	CallInstanceMethodOnNamespace	Static reference to instance method: call this on an instance of %1.
207	CallExtendsMethodOnNamespace	Static reference to extension method: call this on a value of %1.
208	IncompatibleBaseExpression	This method extends %1, but the base expression is %2.
209	ProtectedOperatorConvert	Cannot convert from %1 to %2 because %3 is protected.
210	FixedLengthStringsAreGone	Fixed-length string fields are no longer supported; use an array of Byte instead.

XojoScript.OptimizationLevels

OptimizationLevels

XojoScript compiler optimization levels.

Enum	Description
None	No optimizations will be performed and the script will be compiled lazily (a JIT). Your script will start quickly, but will run more slowly than the other two optimization levels. This is the default if you do not precompile before calling Run.
Low	The script will be compiled up front, but few optimizations will be applied. It will take longer for your script to start, but it will run more quickly.
High	The script will be compiled up front and all possible optimizations will be applied. This will take the most time to compile the script, but it will run the quickest.

XojoScript.States

States

The state of the script compiler.

Enum	Description
Ready	The script compiler is ready.
Running	The script compiler is running.
Complete	The script compiler has completed running the script.
Aborted	The script compiler has aborted.

XojoScript.Warnings

Warnings

These are the warnings than can occur when compiling XojoScript or IDE Scripts.

Enum	Description
ConversionPrecision	Converting from %OriginalType to %NewType causes a possible loss of precision, which can lead to unexpected results.
ConversionSign	Converting from %OriginalType to %NewType causes the sign information to be lost, which can lead to unexpected results.
Custom	A custom warning displayed by Pragma Warning.
Deprecated	%Name is deprecated.
DeprecatedWithReplacement	%Name is deprecated. You should use %Replacement instead.
FloatingPointComparison	Performing a %Operator comparison on floating-point values can yield unexpected results due to their inexact binary representation.
OldStyleConstructor	Old-style constructor methods are no longer supported. You should use ""Constructor"" instead.
ShadowedConstant	This constant shadows one already defined by %Superclass.
ShadowedProperty	This property shadows one already defined by %Superclass.
UnknownPragmaWarning	Unknown pragma name.
UnusedEventParameter	%Name is an unused event parameter.
UnusedLocal	%Name is an unused local variable.
UnusedMethodParameter	%Name is an unused method parameter.
NameLookupChange	Before 2014r3, this would have referred to the %OldPath but now it refers to the %NewPath.

Property descriptions

XojoScript.Context

Context As Object

The object (e.g., window or class) that is made available to the XojoScript. The object's methods and properties become global methods and properties available to the script.

You cannot pass any objects between the context and the script. This includes, for example, dates, variants and arrays. Any methods or properties that use objects will not be allowed within the script.

For example, you can create a custom class and assign it to the Context property. The script would then have access to the methods and properties of this class. The methods become global methods and the properties become global properties.

Constants defined on the Context are replaced at compile time, which essentially means the constants do not exist for the XojoScript to reference. As an alternative, you can use a read-only computed property like a constant and it will be available in the XojoScript.

XojoScript.Source

Source As String

The source code the compiler will run.

XojoScript.State

State As Integer

The state of the script compiler.

Use the States enumeration to check the state:

State	Description
Ready	The script compiler is ready.
Running	The script compiler is running.
Complete	The script compiler has completed running the script.
Aborted	The script compiler has aborted.

Method descriptions

XojoScript.Compile

Compile(optimizationLevel As OptimizationLevels) As MemoryBlock

Compiles the source then returns the compiled code.

This allows you to compile the code for storage so that it can be loaded and run without having to be compiled again.

XojoScript.Precompile

Precompile(optimizationLevel As OptimizationLevels) As Boolean

Runs the parser immediately using the specified optimizationLevel instead of waiting until the next call to Run. Returns True if the optimization succeeded, False if there was an error.

This precompiles a script with an optimization level of "High" before it runs:

If XojoScript1.Precompile(XojoScript.OptimizationLevels.High) Then
  XojoScript1.Run
End If

XojoScript.Reset

Reset

Rewinds the compiler to start over from the beginning.

In this example, script is the XojoScript that executes.

script.Reset

XojoScript.Run

Run(cachedObject As MemoryBlock = Nil)

Runs the code Source until it is done.

CachedObject must be code compiled with the Compile method.

If the CachedObject is not valid compiled code, a XojoScriptException is raised.

Event descriptions

XojoScript.CompilerError

CompilerError(location As XojoScriptLocation, error As Errors, errorInfo As Dictionary)

This event gets called if the script could not be compiled due to a syntax error in the code. Return True to stop the compilation and prevent further errors/warnings.

XojoScriptLocation contains information about the location in the script containing the error.

Errors shows the enumeration for all the available error messages.

The errorInfo Dictionary keys are not stable nor are they guaranteed to always be present. You should explicitly use Dictionary.Lookup or Dictionary.HasKey when looking up these values.

XojoScript.CompilerWarning

CompilerWarning(location As XojoScriptLocation, warning As Warnings, warningInfo As Dictionary)

This event gets called if there were any compiler warnings in the script code.

XojoScriptLocation contains information about the location in the script containing the warning.

Warnings is the enumeration for all the available warning messages.

The warningInfo Dictionary keys are not stable nor are they guaranteed to always be present. You should explicitly use Dictionary.Lookup or Dictionary.HasKey when looking up these values.

XojoScript.Input

Input(prompt As String) As String

The script requests input from the end user with prompt being text to display. Returns a String. You are responsible for creating any UI that prompts the user for data.

In your script, the Input function calls this event handler. In the event handler you can display your own UI with a prompt for the user to enter data and then return the result (as a string) from the event handler to have it passed back to the script.

XojoScript.Print

Print(msg As String)

The compiler is returning the results of the script in msg.

Using the Print method in your script calls this event handler with the supplied string. In the event handler you can display the string.

This example Xojo script calls the Print event handler:

Print("Hello, world!")

XojoScript.RuntimeError

RuntimeError(error As RuntimeException)

A runtime error, error has occurred in the running script.

Notes

The XojoScript language is an implementation of the Xojo language that allows end users to write and execute their own code within a compiled application. Scripts are compiled into machine language, rather then being interpreted.

Since XojoScript is a class, you use it by creating an instance of this class either via code or by adding an XojoScript control to a window. The easiest way to use XojoScript is to assign the code to the Source property of the XojoScript object and call the Run method.

To provide information to an XojoScript while it's running, use the Input function. This function calls the Input event of the XojoScript object where you can return the information you wish returned by the Input function in your XojoScript code. In the following example, the results of the Input function are assigned to a variable:

Var years, days As Integer
years = Input("").Val // Prompt the user to enter a value
days = years * 365

The Input function takes a String that can be used to provide a prompt in case you are going to provide a dialog box in which the user enters the information. Since the Input function returns a String and we want to store the value as an integer, the Val function is used to convert the string to an integer. In this case, if the number of years is going to be entered into a TextField called TextField1, then the Input event of the XojoScript object would look like this:

Function Input(prompt As String) As String
  Return TextField1.Text
End Sub

When the Run method of the XojoScript object is called, the code will be compiled and then executed. Since the Input function is called, the Input event of the XojoScript object is executed and the contents of the Text property of the TextField is returned and assigned to the Years variable. Then the Days value is calculated.

Output information

The Print method is used to output data. This method takes a String and passes it to the Print event of the XojoScript object. Here is the example modified to use the Print function:

Var years, days As Integer
years = Input("").Val
days = years * 365
Print(days.ToString)

You access the value passed to the Print method through the Print event handler. For example, if you want to assign the value to the Text property of a Label object, the code for the Print event of the XojoScript object would look like this:

Sub Print(msg As String)
Label1.Text = msg

Handling errors in your code

If an error occurs while XojoScript is compiling your code, the CompilerError event is called with appropriate error information so you can then decide how to handle the error. If the error occurs while the code is running, the RuntimeError event of the XojoScript object is called and is passed appropriate error information. You can then decide how to respond to the error.

Macos requirements

Newer versions of macOS may require additional permissions or entitlements in order to use XojoScript in code-signed applications.

Compatibility

All project types on all supported operating systems.