Runtime Support - KidneyThief/TinScript1.0 GitHub Wiki

The ability to integrate into a C++ project, expose classes and their members and methods to a scripted environment, and to further extend their functionality are all part of the advantages of a runtime development environment. In addition, there are support and debugging features that are ultimately there to provide as much information about the objects and environment as possible.

All of the functions listed below are available as both part of your script logic, and as commands to be entered - perhaps from a console while the system is paused.

• Print(<str1>, <str2>, ...);
  • Embedded print statements are still a great way to see what's going on.
  • This method operates exactly the same as StringCat(), by returning the concatenation of all the argumetns. In addition to returning the string result, it also outputs the string.
• ListFunctions();
  • Outputs a list of all registered global functions.
• ListVariables();
  • Outputs a list of all registered global variables, along with their type and current value.
• ListObjects();
  • Outputs a list of all objects that have currently been created.
  • This includes recursively listing the contents of ObjectGroups and ObjectSets
  • If your object management relies on objects being properly owned in a group hierarchy, this is a useful for finding errant objects that still require management, and are possibly "leaking".
• FindObject(<object name>);
  • Returns the ID for the first instance of an object with a matching name. Returns 0 otherwise.
• IsObject(<object id>);
  • Returns true or false, if an object with the given ID exists.
• ListSchedules();
  • Outputs a list of pending scheduled commands. Note: this is more useful if issued while the system is "paused".
• ScheduleCancel();
  • Debugging a "runaway" thread, is often easier if you pause the system, ListSchedules();, and then kill the thread that is being developed.
• ScheduleCancelObject();
  • Same as above, except kills all scheduled methods associated with a specific object. See the Scheduler section for more details.

The DECLARE_SCRIPT_CLASS() provides several default object methods, available to all objects either created through script, or allocated in code and registered. Remember these are methods, so the syntax is, for example, object.GetObjectName();

• GetObjectName();
  • Returns a string containing the object's name (or "" for unnamed objects).
• GetObjectID();
  • Returns the unique uint32 ID assigned to this object upon creation (or registration).
• GetGroupID();
  • Returns the object ID of the ObjectGroup that currently "owns" the object. See Object Groups and Sets for more details.
• ListMethods();
  • Outputs the methods registered for this object, organized by each namespace in the object's hierarchy.
  • Note: All of the methods described here will be listed under the CScriptObject namespace.
• ListMembers();
  • Outputs the members registered for this object - also organized by each namespace in the object's hierarchy, and starting with the members dynamically added to this particular object.

There are several functions provided to debug TinScript itself:

• SetDebugParseTree(true);
  • The first step in converting a text string into the instruction set used by the virtual machine, is to parse the text according to the syntax, and generate the parse tree. This command displays the parse tree, and is/was very useful in debugging the TinScript parser.
  • E.g. SetDebugParseTree(true);
    Print((5 + 3) * 4);
    • The above generates the following tree:
      N-> type: NOP
      N-> type:NOP
      N-> type: FuncCall, funcname: Print
          L-> type: NOP
          N-> type: BinaryOp, op: Assign
              L-> type: Value, param: 1
              R-> type: BinaryOp, op:Mult
                  L-> type: BinaryOp, op:Add
                      L-> type: value, 5
                      R-> type: Value, 3
                  R-> type:L Value, 4
    • Briefly, if you read the tree from the leaves back up to the root, you can see the instructions are:
      • Add values 5 and 3
      • Multiply the result by 4
      • Assign the result to parameter 1
      • Call the function 'Print'
• SetDebugCodeBlock(true);
  • Outputs the instructions generated by compiling the script. The virtual machine is stack based, so given the above example:
    Print((5 + 3) * 4);
    You can see the sequence of instructions, adding, multiplying, pushing, and calling the Print function.
• SetDebugTrace(true);
  • This function enables output from the virtual machine as it executes.
  • In our above example: Print((5 + 3) * 4); we see the trace:
    • OP [FuncCallArgs]: Print
      OP [PushParam]: Print, param1
      OP [Push]: 5
      OP [Push]: 3
      OP [Add]: 8
      OP [Push]: 4
      OP [Mult]: 32
      OP [Assign]: Var _p1: 32
      OP [FuncCall]: func: Print