Class TCasScriptExpression

Unit

Declaration

type TCasScriptExpression = class(TObject)

Description

Hierarchy

  • TObject
  • TCasScriptExpression

Overview

Methods

Protected function CoreExecute: TCasScriptValue; virtual; abstract;
Public function Execute: TCasScriptValue;
Public function TryExecuteMath: TCasScriptValue;
Public function AsFloat(const ADefaultValue: Float = 0): Float;
Public function AsInt(const ADefaultValue: Int64 = 0): Int64;
Public function AsString(const ADefaultValue: string = ''): string;
Public function AsBool(const ADefaultValue: boolean = false): boolean;
Public procedure FreeByParentExpression;

Properties

Public property Environment: TCasScriptEnvironment read FEnvironment write FEnvironment;

Description

Methods

Protected function CoreExecute: TCasScriptValue; virtual; abstract;

More internal version of Execute.

This doesn't necessarily check floating-point exceptions. Execute actually calls CoreExecute and then ClearExceptions.

Also this doesn't try to convert EIntError and EMathError to ECasScriptAnyMathError. This is done by Execute.

When one CastleScript CoreExecute calls another function, it can use CoreExecute instead of Execute. This way only one ClearExceptions will be needed for whole expression execution, instead of doing ClearExceptions after each function handler.

Public function Execute: TCasScriptValue;

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.

Public function TryExecuteMath: TCasScriptValue;

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).

Public function AsFloat(const ADefaultValue: Float = 0): Float;

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.

Public function AsInt(const ADefaultValue: Int64 = 0): Int64;

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.

Public function AsString(const ADefaultValue: string = ''): string;

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.

Public function AsBool(const ADefaultValue: boolean = false): boolean;

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.

Public procedure FreeByParentExpression;

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.)

Properties

Public property Environment: TCasScriptEnvironment read FEnvironment write FEnvironment;

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


Generated by PasDoc 0.15.0.