Class
XojoScript
Description
Used to dynamically execute code within a running (compiled) application.
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
optimizationLevel As OptimizationLevels |
|||
optimizationLevel As OptimizationLevels |
|||
cachedObject As MemoryBlock = Nil |
Events
Name |
Parameters |
Returns |
---|---|---|
location As XojoScriptLocation, error As Errors, errorInfo As Dictionary |
||
location As XojoScriptLocation, warning As Warnings, warningInfo As Dictionary |
||
prompt As String |
||
msg As String |
||
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.
Integer Value
Enum
Description
1
Deprecated
%Name is deprecated.
2
DeprecatedWithReplacement
%Name is deprecated. You should use %Replacement instead.
3
OldStyleConstructor
Old-style constructor methods are no longer supported. You should use ""Constructor"" instead.
4
UnknownPragmaWarning
Unknown pragma name.
5
ConversionPrecision
Converting from %OriginalType to %NewType causes a possible loss of precision, which can lead to unexpected results.
6
ConversionSign
Converting from %OriginalType to %NewType causes the sign information to be lost, which can lead to unexpected results.
7
FloatingPointComparison
Performing a %Operator comparison on floating-point values can yield unexpected results due to their inexact binary representation.
8
Custom
A custom warning displayed by Pragma Warning.
9
UnusedLocal
%Name is an unused local variable.
10
UnusedMethodParameter
%Name is an unused method parameter.
11
UnusedEventParameter
%Name is an unused event parameter.
12
ShadowedProperty
This property shadows one already defined by %Superclass.
13
ShadowedConstant
This constant shadows one already defined by %Superclass.
14
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 States
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
Project Types |
Console, Desktop, Web |
Operating Systems |
All |
See also
Object parent class; Introduction To XojoScript, The XojoScript Language, XojoScript Functions, IDE Scripting topics