# Custom tool class

A custom tool class defines the behavior of a Nova tool that can be instantiated.

The class for a tool is created by the `Tool.register` function. An `execute` method must be added to it to define its behavior, along with additional optional extension methods.

Within the extension methods, instance variables (like tool parameters) can be accessed.

## Extension methods

Tools are specialized with extension methods that define their behavior. Every ToolClass must have an `execute` method that performs the tool’s tasks, and there are other extension methods that can be added for specific purposes.

Extension methods are added to the table returned from `Tool.register`.

Example: Defining the `execute` extension method. The arguments to `Tool.register` are omitted.

    _MyTool = Tool.register{
      -- ...
    }

    function _MyTool:execute(input, output)
      output:add("Pass", true)
    end

The following extension methods are supported.

function ToolClass:constructor()

The constructor is called on new instance of a tool.

Optional: A constructor should only be added to a tool in specific circumstances.

If a tool has this method, it will be called on the instance when the tool type is instantiated for any reason, for example due to:

- a user adding it in the Nova user interface

- a user loading a Nova configuration with instances of this tool in the initial job

- a switch of the active job to a job with instances of this tool.

A constructor is only necessary if the automated default initialization of parameters for the tool is insufficient, for example:

- to do initial (per tool instance) setup of a Crown that the execution uses

- to adapt parameters from a loaded Nova configuration saved with an older version of the tool, for backwards compatibility.

- to initialize variables that shouldn’t be saved with configurations, and therefore are not part of the tool parameters

function ToolClass:destructor()

The destructor is called when a tool instance is removed.

Optional: A destructor should only be added to a tool in specific circumstances.

If a tool has this method, it will be called on instances of this tool type when they are deleted for any reason, for example due to:

- a user deleting the tool instance in the user-interface

- a switch away from the current job

- loading a new configuration, replacing the current tool

function ToolClass:execute(input, output)

The `execute` extension method is called when a tool instance should perform its task.

Required: A Tool must have an execute method.

param input:

  `input`

param output:

  `output`

This method must be attached to a ToolClass and should implement the behavior of the tool, see the MyTool.execute example in Building plug-in tools for SICK Nova.

## Methods

self:getText(label)

  Used within extension methods to get the translated text for a label. See Localization for details on translation.

  param label:

    `string` The label

  return:

    `string` The text for the label in the selected language or fallback language.

## Instance variables

The following properties are available on ToolClass instances. Properties give access to the `parameters` and `thresholds` interfaces, and are used within the extension methods.

self.parameters

  Type: `parameters`

  Provides access to the current values of the parameters defined in the call to `Tool.register` for the tool instance.

  - See the `parameters` interface documentation for usage.

  - See Parameter types for the types of parameters that can be registered.

self.thresholds

  Type: `thresholds`

  Provides access to the current thresholds for tool results for an instance of the Tool. The available thresholds are defined in the call to `Tool.register`.

  - See the `thresholds` interface documentation for usage.

  - See threshold types for the types of thresholds that can be registered.

## Example syntax

Example definition of a tool class named “_MyTool”

    local Tool = require("Nova.Tool")

     _MyTool = Tool.register{
       category="Analysis",
       results={{name="Pass", type="bool"}}
     }

     function _MyTool:execute(input, output)
       output:add("Pass", true)
     end