ColdFrame: Scripting Stubs

Basic commands

ColdFrame.Stubs.Scripting provides the commands

check_number_of_calls

At execution time, checks the number of calls to the subprogram.

save_number_of_calls

At execution time, saves the current number of calls.

check_number_of_new_calls

At execution time, checks the number of calls to the subprogram since the last save_number_of_calls (if any).

Generic commands

In addition, ColdFrame.Stubs.Scripting provides generics to support type-specific commands (note, values of types are always passed as one argument; if the type has more than one component, it is to be passed as a list, {component-1 component-2 ...}. There is an example of parsing such a list here.

• Set_Returned_Value
• Check_Passed_Value
• Check_Keyed_Value

Set_Returned_Value

generic
   type Returned_Type is private;
   Returned_Type_Name : String;
   with function Value (S : String) return Returned_Type is <>;
package Set_Returned_Value

Creates a Tcl command set-<returned_type_name> (lowercased) which takes 3 or 4 arguments:

1. fully-qualified name of subprogram
2. name of in-out or out parameter ("return" for a function return)
3. the required value
4. optionally, the call from which the value is to be returned (default is 0, implies "from now on").

At execution time, the created event sets the value to be returned by the stub.

As an example,

package Set_Boolean
is new ColdFrame.Stubs.Scripting.Set_Returned_Value
  (Returned_Type      => Boolean,
   Returned_Type_Name => "boolean",
   Value              => Boolean'Value);

allows you to write

set-boolean digital_io.get return false

so that for all subsequent calls to Digital_IO.Get the returned value will be False.

Note the use of 'Value.

Check_Passed_Value

generic
   type Checked_Type is private;
   Checked_Type_Name : String;
   with function "=" (L, R : Checked_Type) return Boolean is <>;
   with function Value (S : String) return Checked_Type is <>;
   with function Image (V : Checked_Type) return String is <>;
package Check_Passed_Value

Creates a Tcl command check-<checked_type_name> (lowercased) which takes 3 or 4 arguments:

1. fully-qualified name of subprogram
2. name of in or in-out parameter
3. expected value
4. optionally, the call to check (default => latest, -1 => last-but-one, 1 => first).

At execution time, the created event retrieves the actual value passed to the subprogram in the parameter and checks against the supplied expected value. If they aren't equal, it raises Execution_Failure with a suitable message.

As an example,

package Check_Output_Signal
  is new ColdFrame.Stubs.Scripting.Check_Passed_Value
    (Checked_Type      => Output_Signal,
     Checked_Type_Name => "Digital_IO.Output_Signal",
     Value             => Digital_IO.Output_Signal'Value,
     Image             => Digital_IO.Output_Signal'Image);

allows you to write

check-digital_io.output_signal digital_io.set to_state true

to check that, at the last call to Digital_IO.Set, the parameter named To_State had the value True.

Note the (recommended) use of the fully-qualified type name, and the use of 'Value, 'Image.

Check_Keyed_Value

generic
   type Checked_Type is private;
   Checked_Type_Name : String;
   with function "=" (L, R : Checked_Type) return Boolean is <>;
   with function Checked_Value (S : String) return Checked_Type is <>;
   with function Checked_Image (V : Checked_Type) return String is <>;
   type Key_Type is private;
   Key_Type_Name : String;
   with function "=" (L, R : Key_Type) return Boolean is <>;
   with function Key_Value (S : String) return Key_Type is <>;
   with function Key_Image (V : Key_Type) return String is <>;
package Check_Keyed_Value

Creates a Tcl command check-<checked_type_name>-for-<key_type_name> (all lowercased) which takes 5 arguments:

1. fully-qualified name of subprogram
2. name of in or in-out key parameter
3. key value
4. name of in or in-out parameter to be checked
5. expected value

At execution time, the created event finds the latest call of the subprogram at which the key parameter had the key value, retrieves the corresponding result parameter value and checks against the supplied expected value. If they aren't equal, it raises Execution_Failure with a suitable message.

As an example,

package Check_Boolean_For_Output_Signal
  is new ColdFrame.Stubs.Scripting.Check_Keyed_Value
    (Checked_Type      => Boolean,
     Checked_Type_Name => "boolean",
     Checked_Value     => Boolean'Value,
     Checked_Image     => Boolean'Image,
     Key_Type          => Output_Signal,
     Key_Type_Name     => "digital_io.output_signal",
     Key_Value         => Output_Signal'Value,
     Key_Image         => Output_Signal'Image);

allows you to write

check-boolean-for-digital_io.output_signal \
    digital_io.set \
    o 1 \
    to_state false

to check that at the last call to Digital_IO.Set at which the parameter O had the value 1, the parameter To_State had the value False.