EZ-Script is the programming language used in EZ-Builder. The scripting language is similar to Basic and has many robot specific commands. The power of EZ-Script also allows controls to interact with each other using the ControlCommand(), which you may have already read about in this tutorial.

This part of the tutorial will demonstrate how to execute EZ-Script code within your plugin. An example of how this is useful is if your plugin provides configuration for the user to configure custom code for a specific action. If you look at DJ's Tic Tac Toe example, you will notice that the configuration dialog allows the user to create custom EZ-Script for Winning, Losing and Tie.

The namespace for all scripting methods is EZ_Builder.Scripting.

Simple Example This code example demonstrates how to run an EZ-Script piece of code that will speak a phrase out of the speaker when the button is pressed. You will need to add a Button to your form and assign the Click event for it to work.

  public partial class MainForm : EZ_Builder.UCForms.FormPluginMaster {

    EZ_Builder.Scripting.Executor _executor;

    public MainForm()
      : base() {

      InitializeComponent();

      _executor = new EZ_Builder.Scripting.Executor();
    }

    private void button1_Click(object sender, EventArgs e) {

      _executor.StartScriptASync("Say(\"Hello, I am ez-script\")");
    }
  }

Example with Events There are many events that can be associated with the Executor, such as OnDone, OnError, etc.. This allows your program to accommodate behaviors. In this example, the Executor will display a message box when the script has completed executing.

  public partial class MainForm : EZ_Builder.UCForms.FormPluginMaster {

    EZ_Builder.Scripting.Executor _executor;

    public MainForm()
      : base() {

      InitializeComponent();

      _executor = new EZ_Builder.Scripting.Executor();
      _executor.OnDone += _executor_OnDone;
    }

    private void button1_Click(object sender, EventArgs e) {

      _executor.StartScriptASync("Say(\"Hello, I am ez-script\")");
    }

    void _executor_OnDone(string compilerName, TimeSpan timeTook) {

      MessageBox.Show(string.Format("Script has completed and took {0} milliseconds", timeTook.TotalMilliseconds));
    }
  }

Starting A New Script When Another Is Running If the executor is currently running an ASync script in the background while you launch another, the first script will be cancelled and the most recent script will begin executing. Each instance of an Executor can run only one script. To run multiple scripts at the same time, use an Executor per script.

Inside the Executor The executor has many methods and events.

EZ_Builder.Scripting.Executor.ExecuteScriptSingleLine(string line); Executes only one line of EZ-Script and blocks until it has completed. This method returns the result of the single line of code. For example, if the code was a function to return the value of a servo (example GetServo(d0)), the value of the servo d0 will be returned.

EZ_Builder.Scripting.Executor.Resume(); There is an EZ-Script command to "Pause" the current running script. If the command is ever executed in the script, this will resume the execution.

EZ_Builder.Scripting.Executor.StartScriptASync(Command[] compiled); This executes the compiled Command Opcode array in the background. If you precompile the script into an array of Command Opcodes, this method can be used. The advantage to pre-compiling the source into Command Opcodes is that the script will execute faster because it will not need to be compiled each time. There is a compiler cache in the Executor, however. This means that if you run the same script twice that is not compiled, the last Opcode cache will be used.

EZ_Builder.Scripting.Executor.StartScriptASync(string script); This method compiles the plain text EZ-Script and executes it in the background. There is a compiler cache in the Executor, however. This means that if you run the same script consecutive times, the last Opcode cache will be used.

EZ_Builder.Scripting.Executor.StartScriptBlocking(Command[] compiled); Executes the compiled Command OpCode array on the current thread.

EZ_Builder.Scripting.Executor.StartScriptBlocking(string script); This method compiles the plain text EZ-Script and executes it on the current thread. There is a compiler cache in the Executor, however. This means that if you run the same script consecutive times, the last Opcode cache will be used.

EZ_Builder.Scripting.Executor.StopScript(); Stops the current ASync running EZ-Script on this Executor.

Events These events can be assigned to an Executor and will be raised at their appropriate function. The "CompilerName" parameter will include the optional compiler name that can be provided when the Executor class is initiated. In the above examples, the Executor class is created without any parameters. If a parameter was supplied, it would be the name of this compiler. If your program has many Executors that share these events, the CompilerName parameter will come in handy to identify what executor it originated from.

event OnCmdExecHandler(string compilerName, int lineNumber, string execTxt) Event is raised for each line that is executed in the script. This will dramatically slow the execution of the script, but is great for debugging.

event OnDoneHandler(string compilerName, TimeSpan timeTook) Event is raised when the script has completed.

event OnPausedHandler(string compilerName) Event is raised when the EZ-Script calls the Pause method. The Executor.Resume() function is necessary to continue, or StopScript().

event OnResumeHandler(string compilerName) Event is raised when the script is instructed to resume after a Pause.

event OnStartHandler(string compilerName) Event is raised when the script begins to execute.