C# Class kOS.Safe.Execution.CPU

Make a new variable at either the local depth or the global depth depending. throws exception if it already exists as a boundvariable at the desired scope level, unless overwrite = true.

Throw exception if the user delegate is not one the CPU can call right now.

Return the subroutine call trace of how the code got to where it is right now.

Build a clone of the current state of the scope stack, for the sake of capturing a closure.

Identical to GetValue(), except that it guarantees the return value is either already a Structure, or it converts it into a Structure if it's a primitive. It bombs out with an exception if it can't be converted thusly.
Use this in places where the stack value *must* come out as an encapsulated value and something has gone seriously wrong if it can't. This applies to cases where you are attempting to store its value inside another user's variable, mostly.
Hypothetically this should never really be required, as the value is coming FROM a user varible in the first place.

Given a value which may or may not be a variable name, return the value back. If it's not a variable, return it as-is. If it's a variable, look it up and return that.

Test if an identifier is a variable you can get the value of at the moment (var name exists and is in scope). Return true if you can, false if you can't.

Build a delegate call for the given function entry point, in which it will capture a closure of the current runtime scoping state to be used when that function gets called later by OpcodeCall:

Peek at a value atop the stack without popping it, and without evaluating it to get the variable's value. (i.e. if the thing in the stack is $foo, and the variable foo has value 5, you'll get the string "$foo" returned, not the integer 5).

Identical to PeekValue(), except that it guarantees the return value is either already a Structure, or it converts it into a Structure if it's a primitive. It bombs out with an exception if it can't be converted thusly.
Use this in places where the stack value *must* come out as an encapsulated value and something has gone seriously wrong if it can't. This applies to cases where you are attempting to store its value inside a user's variable, mostly.

Peek at a value atop the stack without popping it, and if it's a variable name then get its value, else just return it as it is.

NOTE: Evaluating variables when you don't really need to is pointlessly expensive, as it needs to walk the scoping stack to exhaust a search. If you don't need to evaluate variables, then consider using PeekRaw() instead.

Identical to PeekStructureEncapsulated(), except that it doesn't complain if the result can't be converted to a Structure. It's acceptable for it to not be a Structure, in which case the original object is returned as-is.
Use this in places where the stack value *should* come out as an encapsulated value if it can, but there are some valid cases where it might not be.

Pop one or more things from the secret "over" stack, only returning the finalmost thing popped. (i.e if you pop 3 things then you get: pop once and throw away, pop again and throw away, pop again and return the popped thing.)

Identical to PopValue(), except that it guarantees the return value is either already a Structure, or it converts it into a Structure if it's a primitive. It bombs out with an exception if it can't be converted thusly.
Use this in places where the stack value *must* come out as an encapsulated value and something has gone seriously wrong if it can't. This applies to cases where you are attempting to store its value inside a user's variable, mostly.

Pop a value off the stack, and if it's a variable name then get its value, else just return it as it is.

Identical to PopStructureEncapsulated(), except that it doesn't complain if the result can't be converted to a Structure. It's acceptable for it to not be a Structure, in which case the original object is returned as-is.
Use this in places where the stack value *should* come out as an encapsulated value if it can, but there are some valid cases where it might not be.

Push a single thing onto the secret "over" stack.

Removes a variable, following current scoping rules, removing the innermost scope of the variable that is found.

If the variable cannot be found, it fails silently without complaint.

Make a new global variable at the localmost scoping level and give it a starting value, or overwrite an existing variable at the localmost level with a starting value.

This does NOT scan up the scoping stack like SetValue() does. It operates at the global level only.

Try to make a new local variable at the localmost scoping level and give it a starting value. It errors out of there is already one there by the same name.

This does NOT scan up the scoping stack like SetValue() does. It operates at the local level only.

This is the normal way to make a new local variable. You cannot make a local variable without attempting to give it a value.

Try to set the value of the identifier at the localmost level possible, by scanning up the scope stack to find the local-most level at which the identifier is a variable, and assigning it the value there.

If no such value is found, all the way up to the global level, then it resorts to making a global variable with the name and using that.

This is the normal way to make a new global variable. You cannot make a global variable without attempting to give it a value.

Try to set the value of the identifier at the localmost level possible, by scanning up the scope stack to find the local-most level at which the identifier is a variable, and assigning it the value there.

If no such value is found, an error is thrown. It only stores into variables that already exist, refusing to create new variables.

Call when you want to suspend execution of the Opcodes until some future condition becomes true. The CPU will call yieldTracker.Begin() right away, and then after that call yieldTracker.IsFinished() again and again until it returns true. Until IsFinished() returns true, the CPU will not advance any further into the program in its current "mode". Note that the CPU will track "trigger" and "mainline" code separately for this purpose. Waiting in mainline code will still allow triggers to run.

Gets the dictionary N levels of nesting down the dictionary stack, where zero is the current localmost level. Never errors out or fails. If N is too large you just end up with the global scope dictionary. Does not allow the walk to go past the start of the current function scope.

Gets the dictionary that contains the given identifier, starting the search at the local level and scanning the scopes upward all the way to the global dictionary.
Does not allow the walk to use scope frames that were not directly in this scope's lexical chain. It skips over scope frames from other branches of the parse tree. (i.e. if a function calls a function elsewhere).
Returns null when no hit was found.

Get the value of a variable or create it at global scope if not found.

Get the variable's contents, performing a lookup through all nesting levels up to global.