Instruction method

An instruction method is used to define/override a PhpMyCellScript instruction.

How to define an instruction method?

Any public methods whose names start with "cmd_" in a PhpMyCellScript addon class are regarded as an instruction method.

Example:

<?php
namespace PhpMyCellScript\Addons;
use PhpMyCellScript\OutputVariable;
class Test {
 function cmd_DICE(OutputVariable $output_variable) {
  $output_variable->setValue(mt_rand(1, 6));
 }
}
?>

How to get instruction arguments?

Instruction arguments in the spreadsheet can be obtained by declaring the corresponding parameters in an instruction method. You can direct the interpreter to preprocess an argument in a certain way by specifying a parameter type. For example, if the type of a parameter is VariableExpandedString, the variables in the corresponding instruction argument will be expanded by the interpreter before passed to the instruction method. See What parameter types can be used in an instruction method? for details.

How to return results from an instruction?

Results can be returned from an instruction method through parameters of certain types, like OutputVariable and OutputEvalCode. See What parameter types can be used in an instruction method? for details.

What parameter types can be used in an instruction method?

1. Typeless

   If a parameter does not have type hint, the next instruction argument will be assigned to the parameter directly.

   Example:

   EVAL	echo "Hello, {$name}"

   function cmd_EVAL($php_code, OutputEvalCode $code_to_eval) {
    // $php_code == 'echo "Hello, {$name}"'
   }

2. array

   If a parameter is an array, all remaining instruction arguments will be assigned to the parameter.

   Example:

   ARGV

   $a

   $b

   function cmd_ARGV(array $argument_variables, OutputEvalCode $code_to_eval) {
    // $argument_variables == array('$a', '$b')
   }

3. PhpMyCellScript\VariableExpandedStringVariableExpandedString

   If the type of a parameter is VariableExpandedString, the variables in the next instruction argument will be expanded, and the expanded string will be assigned to the parameter (as VariableExpandedString).

   Example:

   ASSIGN	$name	Peter
   ECHO	Hello, {$name}

   function cmd_ECHO(VariableExpandedString $output_string) {
    // $output_string->getValue() == 'Hello, Peter'
   }

4. PhpMyCellScript\PhpExpressionValuePhpExpressionValue

   If the type of a parameter is PhpExpressionValue, the PHP expression in the next instruction argument will be evaluated, and the evaluation result will be assigned to the parameter (as PhpExpressionValue).

   Example:

   IF

   1 == 1

   function cmd_IF(PhpExpressionValue $condition, PhpMyCellScript $interpreter) {
    // $condition->getValue() == true
   }

5. PhpMyCellScript\EvaluatedPhpTemplateEvaluatedPhpTemplate

   If the type of a parameter is EvaluatedPhpTemplate, the PHP template in the next instruction argument will be evaluated, and the evaluation result will be assigned to the parameter (as EvaluatedPhpTemplate).

   Example:

   PHP

   <?php echo PHP_OS; ?>

   $os

   function cmd_PHP(EvaluatedPhpTemplate $php_template, OutputVariable $output_variable) {
    // $php_template->getValue() == 'WINNT', depending on the OS.
   }

6. PhpMyCellScript\OutputVariableOutputVariable

   If the type of a parameter is OutputVariable, the next instruction argument will be regarded as a variable, and the variable will be evaluated and assigned to the parameter (as OutputVariable). The instruction method can get and set the value of the variable through the parameter.

   Example:

   ASSIGN

   $name

   Peter

   function cmd_ASSIGN(OutputVariable $variable, VariableExpandedString $string) {
    // $variable binds to the variable '$name'. The interpreter will update the variable value on return.
    $variable->setValue((string) $string);
   }

7. PhpMyCellScript\OutputEvalCodeOutputEvalCode

   If the type of a parameter is OutputEvalCode, instruction arguments will not be consumed. An OutputEvalCode object will be created and assigned to the parameter for the instruction method to return some PHP code to the interpreter to evaluate.

   Example:

   EVAL	echo "Hello, {$name}"

   function cmd_EVAL($php_code, OutputEvalCode $code_to_eval) {
    // Return some PHP code to the interpreter through the setValue() method.
    $code_to_eval->setValue("{$php_code};");
   }

8. PhpMyCellScript\DynamicOutputVariableDynamicOutputVariable

   If the type of a parameter is DynamicOutputVariable, instruction arguments will not be consumed. A DynamicOutputVariable object will be created and assigned to the parameter for the instruction method to request a variable for input/output. After the instruction method makes a request, it can return control to the interpreter which will call the instruction method again with the variable requested.

   Example:

   VALUE_ARRAY

   1

   2

   3

   $arr

   function cmd_VALUE_ARRAY(array $expressions, DynamicOutputVariable $array_variable, DynamicPhpExpressionValues $values) {
    // $expressions == array(1, 2, 3, '$arr'), as it consumes all instruction arguments.
    // $array_variable->requestVariable() should be used to request the variable '$arr' for output.
   }

9. PhpMyCellScript\DynamicVariableExpandedStringsDynamicVariableExpandedStrings

   If the type of a parameter is DynamicVariableExpandedStrings, instruction arguments will not be consumed. A DynamicVariableExpandedStrings object will be created and assigned to the parameter for the instruction method to request strings to expand dynamically. After the instruction method makes a request, it can return control to the interpreter which will call the instruction method again with the expanded strings.

   Example:

   STRING_ARRAY

   Hello

   ,

   {$name}

   $arr

   function cmd_STRING_ARRAY(array $strings, DynamicOutputVariable $array_variable, DynamicVariableExpandedStrings $expanded_strings) {
    // $strings == array('Hello', ',', '{$name}', '$arr'), where strings are not expanded.
    // $expanded_strings->requestToExpandString() should be used to request the interpreter to expand the strings.
   }

10. PhpMyCellScript\DynamicPhpExpressionValuesDynamicPhpExpressionValues

    If the type of a parameter is DynamicPhpExpressionValues, instruction arguments will not be consumed. A DynamicPhpExpressionValues object will be created and assigned to the parameter for the instruction method to request expressions to evaluate dynamically. After the instruction method makes a request, it can return control to the interpreter which will call the instruction method again with the evaluation results.

    Example:

    VALUE_ARRAY

    1+1

    2+2

    3+3

    $arr

    function cmd_VALUE_ARRAY(array $expressions, DynamicOutputVariable $array_variable, DynamicPhpExpressionValues $values) {
     // $expressions == array('1+1', '2+2', '3+3', '$arr'), where expressions are not evaluated.
     // $array_variable->requestExpression() should be used to request the interpreter to evaluate the expressions.
    }

11. PhpMyCellScriptPhpMyCellScript

    If the type of a parameter is PhpMyCellScript, instruction arguments will not be consumed. The interpreter will be injected into the parameter for the instruction method to access the interpreter states.

    Example:

    IF

    1 == 1

    function cmd_IF(PhpExpressionValue $condition, PhpMyCellScript $interpreter) {
     if ($condition->getValue()) {
      // Process the instructions in the next column.
      $interpreter->enterIfBranch();
     }
    }

How to define an IF-like instruction?

1. Add the instruction to the $if_like_instructions member of the addon class.
2. Alter the program flow in the instruction method through the interpreter.

Example:

class PhpMyCellScript {
 public $if_like_instructions = array('IF', 'ELSEIF', 'FOREACH');
 function cmd_IF(PhpExpressionValue $condition, PhpMyCellScript $interpreter) {
  if ($condition->getValue()) {
   // Process the instructions in the next column.
   $interpreter->enterIfBranch();
  }
 }
}

How to define a WHILE-like instruction?

1. Add the instruction to the $while_like_instructions member of the addon class.
2. Alter the program flow in the instruction method through the interpreter.

Example:

class PhpMyCellScript {
 public $while_like_instructions = array('WHILE', 'FOREACH');
 function cmd_WHILE(PhpExpressionValue $condition, PhpMyCellScript $interpreter) {
  if ($condition->getValue()) {
   // Process the instructions in the next column.
   $interpreter->enterWhileLoop();
  }
 }
}