Class TCasScriptImageHeight

Execute and calculate this expression.

Returned value is owned by this object. Which should be comfortable for you usually, as you do not have to worry about freeing it. Also, it allows us to make various optimizations to avoid creating/destroying lots of temporary TCasScriptExpression instances during calculation of complex expression.

The disadvantage of this is that returned object value is valid only until you executed this same expression again, or until you freed this expression. If you need to remember the execute result for longer, you have to copy it somewhere. For example you can do

{ This will always work, thanks to virtual TCasScriptValue.Create
  and AssignValue methods. }
Copy := TCasScriptValue(ReturnedValue.ClassType).Create;
Copy.AssignValue(ReturnedValue);

Exceptions raised

ECasScriptError

Execute is guaranteed to raise an ECasScriptError exception if some calculation fails because of invalid arguments.

This means that when you run CastleScript expression provided by the user, you only have to catch ECasScriptError to be safe from errors produced by user. No need to catch something more general like Exception class.

Also it's guaranteed that no hanging floating-point errors are left. Normally, there is no guarantee that floating-point errors are raised immediately, they may be raised at the next fp operation (this is needed for fp operations to proceed in parallel, and be much faster). For executing CastleScript, Execute calls Math.ClearExceptions(true) to make sure that all floating point errors are caught. This ensures that we can safely execute even invalid expressions (like 'ln(-3)') and get reliable exceptions.

Floating-point errors of course also result in ECasScriptError descendants. More specifically, EIntError and EMathError result in ECasScriptAnyMathError.

Source: castlescript/castlescript.pas (line 161).

Try to execute expression, or return Nil if a mathematical error occurred within expression. "Math error within expression" means that a ECasScriptAnyMathError exception occurred while calculating expression.

This is useful to secure you against math arguments errors ('ln(-3)', 'sqrt(-3)') but still raises normal exception on other ECasScriptError errors (like invalid argument type for function).

Source: castlescript/castlescript.pas (line 170).

Execute expression, return the result as a simple float value. It assumes that the expression is written to always return float. To easily create such expression, use ParseFloatExpression.

Source: castlescript/castlescript.pas (line 175).

Execute expression, return the result as a simple integer value. It assumes that the expression is written to always return integer. To easily create such expression, use ParseIntExpression.

Source: castlescript/castlescript.pas (line 180).

Execute expression, return the result as a simple string value. It assumes that the expression is written to always return string. To easily create such expression, use ParseStringExpression.

Source: castlescript/castlescript.pas (line 185).

Execute expression, return the result as a simple boolean value. It assumes that the expression is written to always return boolean. To easily create such expression, use ParseBoolExpression.

Source: castlescript/castlescript.pas (line 190).

Call Free, but only if this is not TCasScriptValue with OwnedByParentExpression = false. (This cannot be implemented cleanly, as virtual procedure, since it must work when Self is Nil, and then virtual method table is not available of course.)

Source: castlescript/castlescript.pas (line 196).

Constructor initializing Args from given TCasScriptExpressionList. AArgs list contents is copied, i.e. AArgs refence is not stored or freed by TCasScriptFunction. But items on AArags are not copied recursively, we copy references from AArags items, and so we become their owners.

Exceptions raised

ECasScriptFunctionArgumentsError

if you specified invalid number of arguments for this function.

Source: castlescript/castlescript.pas (line 536).

This item has no description.

Source: castlescript/castlescript.pas (line 537).

This item has no description.

Source: castlescript/castlescript.pas (line 538).

Long function name for user. This is possibly with spaces, parenthesis and other funny characters. It will be used in error messages and such to describe this function.

Default implementation in this class simply returns ShortName. This should be suitable for most "norma" functions.

Source: castlescript/castlescript.pas (line 546).

Short function name, for the parser. This is the name of the function for use in expressions like "function_name(arg_1, arg_2 ... , arg_n)".

This can be an empty string ('') if no explicit name for this function exists. This is useful for operators, which are implemented just like normal functions (a descendant of TCasScriptFunction), but with a special support from parser (e.g. to turn "x + b" into a call to the TCasScriptAdd function).

Source: castlescript/castlescript.pas (line 557).

Function name when used as an infix operator.

Empty string ('') if no such name for this function. This is returned by default implementation of this in this class.

This does require cooperation from the parser to actually work, that is you cannot simply define new operators by registering new TCasScriptFunction with InfixOperatorName <> ''. For now.

Note that at least one of ShortName and InfixOperatorName must not be empty.

The only exception is the TCasScriptNegate function, that is neither infix operator nor a usual function that must be specified as "function_name(arguments)". So this is an exception, and if there will be a need, I shall fix this (probably by introducing some third field, like PrefixOperatorName ?)

Note 2 things:

1. Function that can be used as infix operator (i.e. has InfixOperatorName <> '') is not necessary binary operator, i.e. InfixOperatorName <> '' does not determine the value of ArgsCount. This way I was able to define infix operators +, -, * etc. that take any number of arguments and operators like ˆ and > that always take 2 arguments.

2. Function may have both ShortName <> '' and InfixOperatorName <> ''. E.g. TCasScriptPower can be used as "Power(3, 1.5)" or "3 ˆ 1.5".

Source: castlescript/castlescript.pas (line 593).

Specify which arguments are calculated before function handler is called.

If = -1 (default value returned by implementation in this class) then all arguments are greedily calculated, which simply means that all arguments are calculated before executing function handler. This is the usual and expected behavior of normal functions. It's also a prerequisite for most of overloaded things to work, since we need to know types of calculated arguments (TCasScriptValue classes) before we choose overloaded handler for function.

If this is >= 0, then arguments with index >= of this will not be calculated before handler execution. Since their type is unknown, they will match any type in handler's ArgumentClasses. Your handler will receive Nil in their places, and is responsible for calling their Execute on it's own if needed.

This is particularly suited for implementing control-flow instructions, like "if" and "while", as normal functions inside CastleScript. For example, "if" will have GreedyArgumentsCalculation = 1, so the first argument (condition) will be calculated, but the execution of 2nd or 3rd argument ("then" code or "else" code) will be left to the handler.

Source: castlescript/castlescript.pas (line 620).

Which arguments should be assignable by this function.

Default implementation in TCasScriptFunction just returns False always. If you're making a function that changes it's argument (like assignment operator, or vector_set, array_set and such) you want to override this.

This is actually checked by CheckArguments, called from constructors.

Source: castlescript/castlescript.pas (line 631).

Environment (outside information) for this expression. May be Nil. This object is not owned by TCasScriptExpression, will not be freed by TCasScriptExpression and such.

Source: castlescript/castlescript.pas (line 201).

Function arguments. Don't modify this list after function is created (although you can modify values inside arguments).

Source: castlescript/castlescript.pas (line 635).