LEOValue (Public)

Includes:
<limits.h>
<sys/types.h>
<stdbool.h>
"LEOChunks.h"

Introduction

LEOValues are how variables and stack entries are implemented in the LEO runtime. They can have various types, and most types can be transparently converted into each other.

A LEOValue is essentially a base class (with subclasses) implemented in straight C. Each LEOValue has an "isa" that points to the method table. This way, you can e.g. run the InitCopy method on any LEOValue without having to know which "subclass" you are dealing with.



Groups

LEOValue methods

Group members:

 

Constructors

Group members:

 

LEOValue storage measuring

Group members:


Functions

LEOCanGetAsInteger
LEOCanGetAsNumber
LEOCleanUpValue
LEODetermineChunkRangeOfSubstring
LEOFollowReferencesAndReturnValueOfType
LEOGetBooleanValueSize
LEOGetIntegerValueSize
LEOGetKeyCount
LEOGetNativeObjectValueSize
LEOGetNumberValueSize
LEOGetPointValueSize
LEOGetRangeValueSize
LEOGetRectValueSize
LEOGetReferenceValueSize
LEOGetStringConstantValueSize
LEOGetStringValueSize
LEOGetValueAsBoolean
LEOGetValueAsInteger
LEOGetValueAsNumber
LEOGetValueAsPoint
LEOGetValueAsRange
LEOGetValueAsRangeOfString
LEOGetValueAsRect
LEOGetValueAsString
LEOGetValueForKey
LEOGetValueForKeyOfRange
LEOGetValueIsUnset
LEOGetValueSize
LEOGetVariantValueSize
LEOInitArrayVariantValue
LEOInitBooleanValue
LEOInitBooleanVariantValue
LEOInitCopy
LEOInitIntegerValue
LEOInitIntegerVariantValue
LEOInitNativeObjectValue
LEOInitNativeObjectVariantValue
LEOInitNumberValue
LEOInitNumberVariantValue
LEOInitPointValue
LEOInitPointVariantValue
LEOInitRangeValue
LEOInitRangeVariantValue
LEOInitRectValue
LEOInitRectVariantValue
LEOInitReferenceValue
LEOInitReferenceValueWithIDs
LEOInitStringConstantValue
LEOInitStringValue
LEOInitStringVariantValue
LEOInitUnsetValue
LEOPutValueIntoValue
LEOSetValueAsArray
LEOSetValueAsBoolean
LEOSetValueAsCString
LEOSetValueAsInteger
LEOSetValueAsNativeObject
LEOSetValueAsNumber
LEOSetValueAsPoint
LEOSetValueAsRange
LEOSetValueAsRect
LEOSetValueAsString
LEOSetValueForKey
LEOSetValueForKeyOfRange
LEOSetValuePredeterminedRangeAsString
LEOSetValueRangeAsString

LEOCanGetAsInteger


Parameters
v

The value you wish to know about.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns TRUE if the value can be converted to an integral number, FALSE otherwise.


LEOCanGetAsNumber


#define LEOCanGetAsNumber(v,c)  
Parameters
v

The value you wish to know about.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns TRUE if the value can be converted to a number, FALSE otherwise.


LEOCleanUpValue


#define LEOCleanUpValue(v,k,c) do { if( ((LEOValuePtr)(v)) && ((LEOValuePtr)(v))->base.isa ) ((LEOValuePtr)(v))->base.isa->CleanUp(((LEOValuePtr)(v)),(k),(c)); } while(0) 
Parameters
v

The value you wish to dispose of.

k

A LEOKeepReferencesFlag indicating whether to clear references or whether you just want to change the type of this value and will keep the storage valid. Usually, you pass kLEOInvalidateReferences.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Dispose of any additional storage the value has allocated to hold its data. If there are references to this value, this will cause the references to fail with an error when next they try to access this value.


LEODetermineChunkRangeOfSubstring


Parameters
v

The value you wish to examine.

bs

On input, a pointer to a size_t containing the start offset (in bytes) of the substring to examine. On output, it will be set to the chunk's absolute start offset.

be

On input, a pointer to a size_t containing the end offset (in bytes) of the substring to examine. On output, it will be set to the chunk's absolute end offset.

bds

The size_t pointed to by this will be set to the chunk's absolute start offset for deletion.

bde

The size_t pointed to by this will be set to the chunk's absolute end offset for deletion.

t

The chunk type to use for parsing this chunk.

rs

The start offset of the chunk (in whatever unit the 't' parameter defines) to find in the substring.

re

The end offset of the chunk (in whatever unit the 't' parameter defines) to find in the substring.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Parses the given substring of a value for the given chunk, and then returns the absolute range of that chunk.

See Also

LEOSetValuePredeterminedRangeAsString


LEOFollowReferencesAndReturnValueOfType


Parameters
v

The value you wish to examine.

t

The type of the value that is desired.

c

The context in which your script is currently running and in which errors will be stored.

Return Value

A LEOValuePtr pointing to the value matching the given type, or NULL if no value of that type is in the chain of references.

Discussion

Follow all references in the given value, until a value of a specific type is found.


LEOGetBooleanValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new boolean value.


LEOGetIntegerValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new integer value.


LEOGetKeyCount


#define LEOGetKeyCount(v,c)  
Parameters
v

The value you wish to examine.

c

The context in which your script is currently running and in which errors will be stored.

Return Value

A LEOValuePtr pointing to the actual value in the array.

Discussion

Returns the number of key-value-pairs in this value.


LEOGetNativeObjectValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new native object value.


LEOGetNumberValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new number value.


LEOGetPointValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new point value.


LEOGetRangeValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new range value.


LEOGetRectValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new rectangle value.


LEOGetReferenceValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new reference value.


LEOGetStringConstantValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new constant string value.


LEOGetStringValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new dynamically allocated string value.


LEOGetValueAsBoolean


Parameters
v

The value you wish to read.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns the given value as a bool, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueAsInteger


Parameters
v

The value you wish to read.

ou

A return parameter, the LEOUnit this integer is in.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns the given value as a LEOInteger, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueAsNumber


Parameters
v

The value you wish to read.

ou

A return parameter, the LEOUnit this number is in.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns the given value as a LEONumber, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueAsPoint


#define LEOGetValueAsPoint(v,l,t,c)  
Parameters
v

The value you wish to read.

l

A pointer to a variable to hold the horizontal coordinate for the point (top-left relative)

t

A pointer to a variable to hold the vertical coordinate for the rectangle (top-left relative)

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns the given value as a point, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueAsRange


#define LEOGetValueAsRange(v,s,e,t,c)  
Parameters
v

The value you wish to read.

s

A pointer to a size_t variable to hold the start offset of the range (1-based)

e

A pointer to a size_t variable to hold the end offset of the range (1-based)

t

A pointer to a LEOChunkType variable to hold the unit this range is specified in.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns the given value as a range, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueAsRangeOfString


Parameters
v

The value you wish to read.

t

The LEOChunkType the range is specified in. This can be characters, words, items, lines etc.

rs

The starting index of the range to get. (e.g. rs=1,es=1,t=kLEOChunkTypeWord would give the second word in the string)

re

The ending index of the range to get. (e.g. rs=1,es=1,t=kLEOChunkTypeWord would give the second word in the string)

s

A character buffer to hold the string value.

sl

The size of character buffer s.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Provides a range of the string representation of the given value as a char*, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueAsRect


#define LEOGetValueAsRect(v,l,t,r,b,c)  
Parameters
v

The value you wish to read.

l

A pointer to a variable to hold the left coordinate for the rectangle (top-left relative)

t

A pointer to a variable to hold the top coordinate for the rectangle (top-left relative)

r

A pointer to a variable to hold the right coordinate for the rectangle (top-left relative)

b

A pointer to a variable to hold the bottom coordinate for the rectangle (top-left relative)

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Returns the given value as a rectangle, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueAsString


Parameters
v

The value you wish to read.

s

A character buffer to hold the string value.

l

The size of character buffer s.

c

The context in which your script is currently running and in which errors will be stored.

Return Value

Either s, or a pointer to an internal buffer, if the value has one that contains the entire requested value.

Discussion

Provides the given value as a char*, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOGetValueForKey


#define LEOGetValueForKey(v,ak,t,k,c)  
Parameters
v

The value you wish to examine.

ak

The key of the array item to fetch.

t

Temporary storage for the retrieved value in case the value is not an array and had to be converted to a temporary array.

k

A LEOKeepReferencesFlag indicating whether to clear references or whether you just want to change the type of tempStorage and will keep the storage valid. Usually, you pass kLEOInvalidateReferences.

c

The context in which your script is currently running and in which errors will be stored.

Return Value

A LEOValuePtr pointing to the actual value in the array. If this is equal to t, you need to call LEOCleanUpValue on it.

Discussion

Fetches the value with the given key from the array in the specified value. Returns NULL if there is no value under that key yet.


LEOGetValueForKeyOfRange


Parameters
v

The value you wish to examine.

ak

The key of the array item to fetch.

so

The start offset of the byte range.

eo

The end offset of the byte range.

ov

This value will be set to a copy of value of the key of that range.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Fetches the value with the given key from the array in the specified value. Returns NULL if there is no value under that key yet.


LEOGetValueIsUnset


Parameters
v

The value you wish to query.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Find out if this value is or references the "unset" value (which to all other calls just shows up as an empty constant string).


LEOGetValueSize


#define LEOGetValueSize(v)  
Parameters
v

The value whose size you want to measure.

Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for this object.


LEOGetVariantValueSize


Discussion

Returns the size (in bytes) of storage you need to provide to LEOInitCopy for a new variant value. Since variants can be converted between all types, this method applies to all kinds of variants.


LEOInitArrayVariantValue


void LEOInitArrayVariantValue(
    LEOValuePtr self,
    struct LEOArrayEntry *array,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  // Takes over ownership of the array. 
Discussion

Initialize the given storage so it's a valid array variant value containing the given array items.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially an array, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsNumber() a number variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitBooleanValue


void LEOInitBooleanValue(
    LEOValuePtr inStorage,
    bool inBoolean,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid boolean value containing the given boolean.

See Also


LEOInitBooleanVariantValue


void LEOInitBooleanVariantValue(
    LEOValuePtr self,
    bool inBoolean,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid boolean variant value containing the given boolean.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a boolean, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsNumber() a number variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitCopy


#define LEOInitCopy(v,d,k,c)  
Parameters
v

The value you wish to copy.

d

A LEOValuePtr to memory where you wish the copy to be stored. This destination must be large enough to hold the given type of value.

k

A LEOKeepReferencesFlag indicating whether to clear references or whether you just want to change the type of this value and will keep the storage valid. Usually, you pass kLEOInvalidateReferences.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Initializes the given storage to be an exact copy of the given value. If the value is a reference, you will get a second reference to the original value, not a copy of the original value, and not a reference to the reference.

See Also

LEOGetValueSize


LEOInitIntegerValue


void LEOInitIntegerValue(
    LEOValuePtr inStorage,
    LEOInteger inNumber,
    LEOUnit inUnit,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid number value containing the given number.

See Also

LEOInitNumberValue

LEOGetIntegerValueSize


LEOInitIntegerVariantValue


void LEOInitIntegerVariantValue(
    LEOValuePtr self,
    LEOInteger inNumber,
    LEOUnit inUnit,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid number variant value containing the given number.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a number, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsBoolean() a boolean variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitNativeObjectValue


void LEOInitNativeObjectValue(
    LEOValuePtr inStorage,
    void *inNativeObject,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid native object value containing the given pointer. Native objects are essentially just opaque 'things' that the scripter hands to native functions. A wrapper to a pointer that you can't answer and can't put into a field or property. You can store it in variants (like local variables or globals), though.

See Also


LEOInitNativeObjectVariantValue


void LEOInitNativeObjectVariantValue(
    LEOValuePtr self,
    void *inNativeObject,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid native object variant value containing the given pointer.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a boolean, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsNumber() a number variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitNumberValue


void LEOInitNumberValue(
    LEOValuePtr inStorage,
    LEONumber inNumber,
    LEOUnit inUnit,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid number value containing the given number.

See Also

LEOGetNumberValueSize

LEOInitIntegerValue


LEOInitNumberVariantValue


void LEOInitNumberVariantValue(
    LEOValuePtr self,
    LEONumber inNumber,
    LEOUnit inUnit,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid number variant value containing the given number.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a number, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsBoolean() a boolean variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitPointValue


void LEOInitPointValue(
    LEOValuePtr inStorage,
    LEOInteger l,
    LEOInteger t,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid point value containing the given four coordinates.

See Also


LEOInitPointVariantValue


void LEOInitPointVariantValue(
    LEOValuePtr inStorage,
    LEOInteger l,
    LEOInteger t,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid point value containing the given four coordinates.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a rect, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsNumber() a number variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitRangeValue


void LEOInitRangeValue(
    LEOValuePtr inStorage,
    LEOInteger s,
    LEOInteger e,
    LEOChunkType t,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid range value containing the given range in the given unit.

See Also


LEOInitRangeVariantValue


void LEOInitRangeVariantValue(
    LEOValuePtr inStorage,
    LEOInteger s,
    LEOInteger e,
    LEOChunkType t,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid range value containing the given range in the given unit.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a range, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsNumber() a number variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitRectValue


void LEOInitRectValue(
    LEOValuePtr inStorage,
    LEOInteger l,
    LEOInteger t,
    LEOInteger r,
    LEOInteger b,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid rectangle value containing the given four coordinates.

See Also


LEOInitRectVariantValue


void LEOInitRectVariantValue(
    LEOValuePtr inStorage,
    LEOInteger l,
    LEOInteger t,
    LEOInteger r,
    LEOInteger b,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid rectangle value containing the given four coordinates.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a rect, if you call LEOSetValueAsString() on it, it will turn itself into a string variant value, or if you call LEOSetValueAsNumber() a number variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitReferenceValue


void LEOInitReferenceValue(
    LEOValuePtr self,
    LEOValuePtr dest,
    LEOKeepReferencesFlag keepReferences, 
    LEOChunkType inType,
    size_t startOffs,
    size_t endOffs,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid reference value that points to the given original value. If the original value is destructed while a reference still points to it, method calls to such a reference will fail with an error message and abort execution of the current LEOContext.

However, the destructor of the value is safe to call, as is InitCopy.

Pass kLEOChunkTypeINVALID if you want to reference the whole value and not only a chunk of it.

See Also


LEOInitReferenceValueWithIDs


void LEOInitReferenceValueWithIDs(
    LEOValuePtr self,
    LEOObjectID referencedObjectID,
    LEOObjectSeed referencedObjectSeed, 
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid reference value that points to an original value referenced by object ID and seed. If the original value is destructed while a reference still points to it, method calls to such a reference will fail with an error message and abort execution of the current LEOContext.

However, the destructor of the value is safe to call, as is InitCopy.

Pass kLEOChunkTypeINVALID if you want to reference the whole value and not only a chunk of it.

See Also


LEOInitStringConstantValue


void LEOInitStringConstantValue(
    LEOValuePtr inStorage,
    const char *inString,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid string constant value directly referencing the given string. The caller is responsible for ensuring that the string is not disposed of while the value still needs it.

See Also


LEOInitStringValue


void LEOInitStringValue(
    LEOValuePtr inStorage,
    const char *inString,
    size_t inLen,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid string value containing a copy of the given string.

See Also


LEOInitStringVariantValue


void LEOInitStringVariantValue(
    LEOValuePtr self,
    const char *inString,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid string variant value containing the given C-string.

A variant is a value whose type changes depending on what type of data you put in it. So while this value is initially a string, if you call LEOSetValueAsNumber() on it, it will turn itself into a number variant value, or if you call LEOSetValueAsBoolean() a boolean variant value.

As such, assignments to variants can never fail due to a type mismatch, but retrieving a variant as a certain type still can.

See Also


LEOInitUnsetValue


void LEOInitUnsetValue(
    LEOValuePtr inStorage,
    LEOKeepReferencesFlag keepReferences,
    struct LEOContext *inContext );  
Discussion

Initialize the given storage so it's a valid "unset" value. An unset value looks just like an empty string (a constant string, in fact), but can be distinguished using the LEOGetValueIsUnset() call. It is used e.g. for initializing the empty result of a handler so you can distinguish whether someone actually returned something or not.

See Also


LEOPutValueIntoValue


Parameters
v

The value you wish to copy.

d

The value to assign to. If the value is a different type than the source, it will take care of conversion (raising errors if it can't be converted), if the destination is a variant, it will change its type accordingly.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Copy the contents of a value to another value, preserving the native type, if possible.


LEOSetValueAsArray


#define LEOSetValueAsArray(v,a,c)  
Parameters
v

The value you wish to change.

a

The new value for that value.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Replace the value of a variant or array with the given array value.


LEOSetValueAsBoolean


Parameters
v

The value you wish to change.

n

The boolean to write to value v, as a bool.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Assigns the given boolean to the value, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOSetValueAsCString


Discussion

Like LEOSetValueAsString, but takes a zero-terminated C string instead of buffer and length byte.

See Also

LEOSetValueAsString


LEOSetValueAsInteger


#define LEOSetValueAsInteger(v,n,u,c)  
Parameters
v

The value you wish to change.

n

The number to write to value v, as a LEOInteger.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Assigns the given number to the value, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOSetValueAsNativeObject


Parameters
v

The value you wish to change.

o

The new value for that value.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Replace the value of a variant or native object with the given native object value.


LEOSetValueAsNumber


#define LEOSetValueAsNumber(v,n,u,c)  
Parameters
v

The value you wish to change.

n

The number to write to value v, as a LEONumber.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Assigns the given number to the value, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


LEOSetValueAsPoint


#define LEOSetValueAsPoint(v,l,t,c)  
Parameters
v

The value you wish to change.

l

The horizontal coordinate for the rectangle (top-left relative)

t

The vertical coordinate for the rectangle (top-left relative)

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Replace the value of another value with the given point.


LEOSetValueAsRange


#define LEOSetValueAsRange(v,s,e,t,c)  
Parameters
v

The value you wish to change.

s

The start offset for the range (1-based)

e

The end offset for the range (1-based)

t

The LEOChunkType for the unit this range is specified in.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Replace the value of another value with the given rectangle.


LEOSetValueAsRect


#define LEOSetValueAsRect(v,l,t,r,b,c)  
Parameters
v

The value you wish to change.

l

The left coordinate for the rectangle (top-left relative)

t

The top coordinate for the rectangle (top-left relative)

r

The right coordinate for the rectangle (top-left relative)

b

The bottom coordinate for the rectangle (top-left relative)

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Replace the value of another value with the given rectangle.


LEOSetValueAsString


Parameters
v

The value you wish to change.

s

The UTF8 string to write to value v, as a char*.

l

The length of the string provided in s.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Assigns the given string to the value, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.

See Also

LEOSetValueAsCString


LEOSetValueForKey


#define LEOSetValueForKey(v,ak,s,c)  
Parameters
v

The value you wish to examine.

ak

The key of the array item to fetch.

s

The source value to copy into the array.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Stores a value under the given key in the array in the specified value.


LEOSetValueForKeyOfRange


Parameters
v

The value you wish to examine.

ak

The key of the array item to fetch.

s

The source value to copy into the array.

so

The start offset of the byte range.

eo

The end offset of the byte range.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Stores a value under the given key in the array in the specified value.


LEOSetValuePredeterminedRangeAsString


Parameters
v

The value you wish to change.

rs

The starting index of the range to get, as obtained from LEODetermineChunkRangeOfSubstring.

re

The ending index of the range to get, as obtained from LEODetermineChunkRangeOfSubstring.

s

The string to insert, or NULL to delete the given range.

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Assigns the given string to the specified range of the given value, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.

See Also

LEODetermineChunkRangeOfSubstring


LEOSetValueRangeAsString


Parameters
v

The value you wish to change.

t

The LEOChunkType the range is specified in. This can be characters, words, items, lines etc.

rs

The starting index of the range to get. (e.g. rs=1,es=1,t=kLEOChunkTypeWord would give the second word in the string)

re

The ending index of the range to get. (e.g. rs=1,es=1,t=kLEOChunkTypeWord would give the second word in the string)

s

The string to insert, or NULL to delete the given range (and any delimiters).

c

The context in which your script is currently running and in which errors will be stored.

Discussion

Assigns the given string to the specified range of the given value, converting it, if necessary. If conversion isn't possible, it will fail with an error message and stop execution in the current LEOContext.


Typedefs

LEOInteger
LEONumber
LEOObjectID
LEOObjectSeed
LEOUnit
LEOUnitGroup
LEOValuePtr
LEOValueTypePtr

LEOInteger


typedef long long LEOInteger;  
Discussion

The type of integers in the language. This is guaranteed to be signed, but large enough to hold a pointer.


LEONumber


typedef float LEONumber;  
Discussion

The type of fractional numbers in the language.


LEOObjectID


typedef unsigned long LEOObjectID;  
Discussion

Object IDs are indexes used internally by reference values to look up the referenced value in a way that's safe even after the original has been disposed of.


LEOObjectSeed


typedef unsigned long LEOObjectSeed;  
Discussion

An Object Seed is a value used internally to allow reference values to detect whether the slot in which their value used to be has already been reused.


LEOUnit


typedef uint8_t LEOUnit;  
Discussion

A unit attached to a numerical value.


LEOUnitGroup


typedef uint8_t LEOUnitGroup;  
Discussion

A group of units. We can convert between numbers of the same group, but not between members of different groups.


LEOValuePtr


typedef union LEOValue * LEOValuePtr;  
Discussion

A LEOValuePtr is a generic pointer to a LEOValue or one of its subclasses.


LEOValueTypePtr


typedef struct LEOValueType * LEOValueTypePtr;  
Discussion

A LEOValueTypePtr is a pointer to a method look-up table for an object used internally.


Structs and Unions

LEOValue
LEOValueArray
LEOValueBase
LEOValueBoolean
LEOValueInteger
LEOValueNumber
LEOValueObject
LEOValuePoint
LEOValueRange
LEOValueRect
LEOValueReference
LEOValueString
LEOValueType

LEOValue


union LEOValue { 
    struct LEOValueBase base; 
    struct LEOValueNumber number; 
    struct LEOValueInteger integer; 
    struct LEOValueString string; 
    struct LEOValueBoolean boolean; 
    struct LEOValueReference reference; 
    struct LEOValueArray array; 
    struct LEOValueObject object; 
    struct LEOValueRect rect; 
    struct LEOValuePoint point; 
    struct LEOValueRange range; 
};  
Discussion

We build the stack out of entries of this union, so we can just add 1 to the stack pointer to add another value to the stack, and so we don't have to check the size of each item before initializing.

It's probably a good idea to keep all the value structs small, so the stack doesn't grow too large.


LEOValueArray


struct LEOValueArray { 
    struct LEOValueBase base; 
    struct LEOArrayEntry *array; 
};  
Fields
base

The instance variables inherited from the base class.

array

Pointer to the root of a B-tree that holds all the array items.

Discussion

Arrays in our language are associative arrays, so they're not necessarily continuously numbered, but rather contain items associated with a string.


LEOValueBase


struct LEOValueBase { 
    LEOValueTypePtr isa;
    LEOObjectID refObjectID;
};  
Fields
isa

Virtual function dispatch table.

refObjectID

If we have a reference to us, this is our index in the LEOContextGroup's reference table, so we can clear it on destruction.

Discussion

IVar layout common to all LEOValueBase subclasses: Each type of subclass should begin with this struct: That way it can be typecasted to the more generic type and methods can be called on it.


LEOValueBoolean


struct LEOValueBoolean { 
    struct LEOValueBase base; 
    bool boolean; 
};  
Fields
base

The instance variables inherited from the base class.

boolean

Where we store the actual boolean.

Discussion

This is a boolean. In our language, booleans and integers are distinct types, but the (case-insensitive) strings "true" and "false" are valid booleans as well.


LEOValueInteger


struct LEOValueInteger { 
    struct LEOValueBase base; 
    LEOInteger integer; 
    LEOUnit unit; 
};  
Fields
base

The instance variables inherited from the base class.

integer

Where we store the actual number.

Discussion

A number that doesn't have fractional parts:


LEOValueNumber


struct LEOValueNumber { 
    struct LEOValueBase base; 
    LEONumber number; 
    LEOUnit unit; 
};  
Fields
base

The instance variables inherited from the base class.

number

Where we store the actual number.

Discussion

A number, which may have a fractional part:


LEOValueObject


struct LEOValueObject { 
    struct LEOValueBase base; 
    void *object; 
};  
Discussion

A generic wrapper around foreign objects. The host may provide its own LEOValueType for an individual instance, so don't make any assumptions. This is mainly here so foreign objects can pass through LEO scripts and be stored on the stack unharmed.


LEOValuePoint


struct LEOValuePoint { 
    struct LEOValueBase base; 
    LEOInteger horizontal; 
    LEOInteger vertical; 
};  
Fields
base

The instance variables inherited from the base class.

horizontal

The distance of the point, measured to the left of the card/screen/whatever.

vertical

The distance of the point, measured to the top of the card/screen/whatever.

Discussion

This is a point. In our language, points are dictionaries that contain the keys left, top, right and bottom. In HyperCard compatibility mode, they are a comma-separated list of numbers, in the order l,t,r,b.


LEOValueRange


struct LEOValueRange { 
    struct LEOValueBase base; 
    LEOInteger start; 
    LEOInteger end; 
    LEOChunkType type; 
};  
Fields
base

The instance variables inherited from the base class.

start

The number of the character/line/etc. that is the first in this range (inclusive).

end

The number of the character/line/etc. that is the last in this range (inclusive).

type

The unit the range is specified in.

Discussion

This is a range. In our language, ranges are conceptually chunk expressions stored in a variable as a string. That is, they start with a type (character, line etc.) then the start offset (1-based), then the word "to", then the end offset (1-based). If a range's start and end are equal, the "to" portion may be omitted. Note that values of *type* range are distinct from reference values that reference a chunk of another value's string representation.


LEOValueRect


struct LEOValueRect { 
    struct LEOValueBase base; 
    LEOInteger left; 
    LEOInteger top; 
    LEOInteger right; 
    LEOInteger bottom; 
};  
Fields
base

The instance variables inherited from the base class.

left

The distance of the left edge, measured to the left of the card/screen/whatever.

top

The distance of the top edge, measured to the top of the card/screen/whatever.

right

The distance of the right edge, measured to the left of the card/screen/whatever.

bottom

The distance of the bottom edge, measured to the top of the card/screen/whatever.

Discussion

This is a rectangle. In our language, rectangles are dictionaries that contain the keys left, top, right and bottom. In HyperCard compatibility mode, they are a comma-separated list of numbers, in the order l,t,r,b.


LEOValueReference


struct LEOValueReference { 
    struct LEOValueBase base; 
    LEOObjectID objectID; 
    LEOObjectSeed objectSeed; 
    LEOChunkType chunkType; 
    size_t chunkStart; 
    size_t chunkEnd; 
};  
Fields
base

The instance variables inherited from the base class.

objectID

Index into the LEOContext's references array to the slot where the actual "master pointer" to our referenced value is stored.

objectSeed

The "seed" number of the object in the LEOContext's references array. When our referenced object goes away, the slot's seed is incremented, and by comparing it to this one, we can detect that even if the slot has been reused in the meantime.

chunkType

The type of chunk of the original value this references, or kLEOChunkTypeINVALID if this references the full value.

chunkStart

If chunkType isn't kLEOChunkTypeINVALID, this specifies the start of the chunk range of the referenced object.

chunkEnd

If chunkType isn't kLEOChunkTypeINVALID, this specifies the end of the chunk range of the referenced object.

Discussion

Essentially our castrated version of a pointer, without pointer arithmetics or other type-unsafeties you wouldn't like to have in our language. A reference can detect whether the value it points to is still valid (or has been disposed) and can gracefully exit in that case, instead of crashing the application.


LEOValueString


struct LEOValueString { 
    struct LEOValueBase base; 
    char *string; 
    size_t stringLen; 
};  
Fields
base

The instance variables inherited from the base class.

string

A pointer to the string constant, or to a malloced block of memory holding the string, depending on what kind of string class it is.

Discussion

This is used both for strings we dynamically allocated, and for ones referencing C string constants built into the program: It can happen that such a string value gets turned from constant into an dynamic one or back.


LEOValueType


struct LEOValueType { 
    const char *displayTypeName;
    size_t size; 
    LEONumber (*GetAsNumber)(
        LEOValuePtr self,
        LEOUnit *outUnit,
        struct LEOContext* inContext ); 
    LEOInteger (*GetAsInteger)(
        LEOValuePtr self,
        LEOUnit *outUnit,
        struct LEOContext* inContext ); 
    const char *(*GetAsString)(
        LEOValuePtr self,
        char* outBuf,
        size_t bufSize,
        struct LEOContext* inContext ); // Either returns buf, or an internal pointer holding the entire string. 
    bool (*GetAsBoolean)(
        LEOValuePtr self,
        struct LEOContext* inContext ); 
    void (*GetAsRangeOfString)(
        LEOValuePtr self,
        LEOChunkType inType, 
        size_t inRangeStart,
        size_t inRangeEnd, 
        char* outBuf,
        size_t bufSize,
        struct LEOContext* inContext );  
    void (*SetAsNumber)(
        LEOValuePtr self,
        LEONumber inNumber,
        LEOUnit inUnit,
        struct LEOContext* inContext ); 
    void (*SetAsInteger)(
        LEOValuePtr self,
        LEOInteger inNumber,
        LEOUnit inUnit,
        struct LEOContext* inContext ); 
    void (*SetAsString)(
        LEOValuePtr self,
        const char* inBuf,
        size_t bufLen,
        struct LEOContext* inContext ); 
    void (*SetAsBoolean)(
        LEOValuePtr self,
        bool inBoolean,
        struct LEOContext* inContext ); 
    void (*SetRangeAsString)(
        LEOValuePtr self,
        LEOChunkType inType, 
        size_t inRangeStart,
        size_t inRangeEnd, 
        const char* inBuf,
        struct LEOContext* inContext ); 
    void (*SetPredeterminedRangeAsString)(
        LEOValuePtr self, 
        size_t inRangeStart,
        size_t inRangeEnd, 
        const char* inBuf,
        struct LEOContext* inContext );  
    void (*InitCopy)(
        LEOValuePtr self,
        LEOValuePtr dest,
        LEOKeepReferencesFlag keepReferences,
        struct LEOContext* inContext );
    void (*InitSimpleCopy)(
        LEOValuePtr self,
        LEOValuePtr dest,
        LEOKeepReferencesFlag keepReferences,
        struct LEOContext* inContext );
    void (*PutValueIntoValue)(
        LEOValuePtr self,
        LEOValuePtr dest,
        struct LEOContext* inContext );
    LEOValuePtr (*FollowReferencesAndReturnValueOfType)(
        LEOValuePtr self,
        LEOValueTypePtr inType,
        struct LEOContext* inContext ); // Returns NULL if no direct reference.  
    void (*DetermineChunkRangeOfSubstring)(
        LEOValuePtr self,
        size_t *ioBytesStart,
        size_t *ioBytesEnd, 
        size_t *ioBytesDelStart,
        size_t *ioBytesDelEnd, 
        LEOChunkType inType,
        size_t inRangeStart,
        size_t inRangeEnd, 
        struct LEOContext* inContext ); 
    void (*CleanUp)(
        LEOValuePtr self,
        LEOKeepReferencesFlag keepReferences,
        struct LEOContext* inContext );  
    bool (*CanGetAsNumber)(
        LEOValuePtr self,
        struct LEOContext* inContext );  
    LEOValuePtr (*GetValueForKey)(
        LEOValuePtr self,
        const char* keyName,
        union LEOValue* tempStorage,
        LEOKeepReferencesFlag keepReferences,
        struct LEOContext* inContext ); 
    void (*SetValueForKey)(
        LEOValuePtr self,
        const char* keyName,
        LEOValuePtr inValue,
        struct LEOContext* inContext );  
    void (*SetValueAsArray)(
        LEOValuePtr self,
        struct LEOArrayEntry* inArray,
        struct LEOContext* inContext );  
    size_t (*GetKeyCount)(
        LEOValuePtr self,
        struct LEOContext* inContext );  
    void (*GetValueForKeyOfRange)(
        LEOValuePtr self,
        const char* keyName,
        size_t startOffset,
        size_t endOffset,
        LEOValuePtr outValue,
        struct LEOContext* inContext ); 
    void (*SetValueForKeyOfRange)(
        LEOValuePtr self,
        const char* keyName,
        LEOValuePtr inValue,
        size_t startOffset,
        size_t endOffset,
        struct LEOContext* inContext );  
    void (*SetValueAsNativeObject)(
        LEOValuePtr self,
        void* inNativeObject,
        struct LEOContext* inContext );  
    void (*SetValueAsRect)(
        LEOValuePtr self,
        LEOInteger l,
        LEOInteger t,
        LEOInteger r,
        LEOInteger b,
        struct LEOContext* inContext ); 
    void (*GetValueAsRect)(
        LEOValuePtr self,
        LEOInteger *l,
        LEOInteger *t,
        LEOInteger *r,
        LEOInteger *b,
        struct LEOContext* inContext ); 
    void (*SetValueAsPoint)(
        LEOValuePtr self,
        LEOInteger l,
        LEOInteger t,
        struct LEOContext* inContext ); 
    void (*GetValueAsPoint)(
        LEOValuePtr self,
        LEOInteger *l,
        LEOInteger *t,
        struct LEOContext* inContext ); 
    bool (*GetValueIsUnset)(
        LEOValuePtr self,
        struct LEOContext* inContext ); 
    void (*SetValueAsRange)(
        LEOValuePtr self,
        LEOInteger s,
        LEOInteger e,
        LEOChunkType t,
        struct LEOContext* inContext ); 
    void (*GetValueAsRange)(
        LEOValuePtr self,
        LEOInteger *s,
        LEOInteger *e,
        LEOChunkType *t,
        struct LEOContext* inContext );  
    bool (*CanGetAsInteger)(
        LEOValuePtr self,
        struct LEOContext* inContext ); 
};  
Fields
displayTypeName

Used for error messages etc. Doesn't distinguish between dynamic and constant strings.

size

Minimal size required for a variable of this type.

Callbacks
InitCopy

dest is an uninitialized value.

InitSimpleCopy

dest is an uninitialized value.

PutValueIntoValue

dest must be a VALID, initialized value!

Discussion

Layout of the virtual function tables for all the LEOValue subclasses: Also doubles as the 'class name'.


Enumerated Types

eLEOKeepReferencesFlag

eLEOKeepReferencesFlag


Constants
kLEOInvalidateReferences

Break all references to this slot and make sure we're treated as a fresh object.

kLEOKeepReferences

Keep all references to this slot, we're really just a new value that happens to have a different type.

Discussion

Flag that decides whether to clear references to this object or keep them. This is used e.g. by variants when re-creating a value as a different type to make sure that any references to it remain valid, or for returning a result. OTOH, you generally want to invalidate references when e.g. creating a stack slot to make sure that references from previous iterations notice that while the address is identical, the old value is gone.


Macro Definitions

kLEOObjectIDINVALID

kLEOObjectIDINVALID


Discussion

If an object ID is invalid, it is set to this value.