Classes and Objects

Classes let you define your own object types.

An object groups data and behavior together. This is useful when a script needs to keep related values and operations in one place.

Examples where objects can help:

• Tool information.
• Probe results.
• Dialog state.
• Reusable ATC or probing helpers.
• Groups of settings or calculated values.

Classes are more advanced than simple functions. Use functions first when the logic is small. Use classes when you need stored data together with methods that operate on that data.

This chapter builds on the scope rules from the previous chapter. Object fields, method parameters, and local variables all use those name lookup rules.

A class is defined with the `class` keyword.

class ToolInfo(number, diameter)
{
    Number = number;
    Diameter = diameter;
 
    function Radius()
    {
        return Diameter / 2;
    }
}

This class defines a new object type named `ToolInfo`.

It has:

• Constructor parameters: `number`, `diameter`.
• Stored object fields: `Number`, `Diameter`.
• A method: `Radius()`.

Create an object by calling the class name like a function.

class ToolInfo(number, diameter)
{
    Number = number;
    Diameter = diameter;
 
    function Radius()
    {
        return Diameter / 2;
    }
}
 
tool = ToolInfo(1, 6);
 
tool.Radius();

The final value is `3`.

`ToolInfo(1, 6)` creates a new object. The variable `tool` stores that object.

The class body is also constructor code.

When you create an object, non-function statements in the class body run once.

class ProbeResult(x, y, z)
{
    X = x;
    Y = y;
    Z = z;
    Valid = true;
}
 
result = ProbeResult(10, 20, -1.5);

The assignments inside the class body create fields on the new object.

Function definitions inside the class body do not run during construction. They become methods.

Object fields can be read with property syntax.

class ToolInfo(number, diameter)
{
    Number = number;
    Diameter = diameter;
}
 
tool = ToolInfo(1, 6);
 
tool.Number;

The final value is `1`.

You can also read fields inside methods by name:

class ToolInfo(number, diameter)
{
    Number = number;
    Diameter = diameter;
 
    function Description()
    {
        return 'Tool ' + Number + ', D=' + Diameter;
    }
}
 
tool = ToolInfo(1, 6);
tool.Description();

The final value is `'Tool 1, D=6'`.

A method is a function that belongs to an object.

Methods are defined with `function` inside a class.

class Counter(start)
{
    Value = start;
 
    function Inc()
    {
        Value += 1;
        return Value;
    }
 
    function Reset()
    {
        Value = 0;
        return Value;
    }
}
 
counter = Counter(10);
counter.Inc();
counter.Inc();
counter.Value;

The final value is `12`.

A method call uses dot syntax:

object.Method(arguments);

Inside a class constructor or method, `this` means the current object.

class Counter(start)
{
    Value = start;
 
    function Read()
    {
        return this.Value;
    }
}
 
counter = Counter(5);
counter.Read();

The final value is `5`.

In many simple methods, you can read fields directly by name:

return Value;

Using `this.Value` can make it clearer that you are reading an object field.

Inside a method, assignment can update object fields.

class ProbeStats()
{
    Count = 0;
    LastError = 0;
 
    function Add(error)
    {
        Count += 1;
        LastError = error;
    }
}
 
stats = ProbeStats();
stats.Add(0.03);
stats.Add(0.02);
 
stats.Count;

The final value is `2`.

Use assignment inside methods for persistent object fields.

You can read fields from outside the object:

stats.Count;

But direct property writes are not supported:

stats.Count = 10;    // not supported

If outside code needs to change object state, create a method for it.

class ProbeStats()
{
    Count = 0;
 
    function SetCount(value)
    {
        Count = value;
    }
}
 
stats = ProbeStats();
stats.SetCount(10);
stats.Count;

The final value is `10`.

A method can call another method on the same object.

class ToolInfo(number, diameter)
{
    Number = number;
    Diameter = diameter;
 
    function Radius()
    {
        return Diameter / 2;
    }
 
    function Summary()
    {
        return 'T' + Number + ' R=' + Radius();
    }
}
 
tool = ToolInfo(3, 8);
tool.Summary();

The final value is `'T3 R=4'`.

Inside object methods, a bare method call such as `Radius()` can resolve to a method on the current object.

You can also write it explicitly:

return 'T' + Number + ' R=' + this.Radius();

A function can create and return an object.

class ToolInfo(number, diameter)
{
    Number = number;
    Diameter = diameter;
 
    function Radius()
    {
        return Diameter / 2;
    }
}
 
function CreateTool6()
{
    return ToolInfo(6, 4);
}
 
tool = CreateTool6();
tool.Radius();

The final value is `2`.

This pattern is useful when object creation needs setup logic.

Some built-in functions create objects too.

For example, arrays and maps are objects with methods:

items = array();
items.add('A');
items.add('B');
items.to_string();

values = map();
values.set('x', 10);
values.set('y', 20);
values.to_string();

User-defined objects and built-in objects use the same method-call style:

object.Method(arguments);

Use a class when you need to keep related data and behavior together.

Good class use cases:

• A probe result with coordinates, status, and helper methods.
• A tool object with number, diameter, radius, and description methods.
• A script helper that stores state between method calls.
• A dialog model that stores user choices and validation logic.

Use a function instead when the logic only calculates one result and does not need stored state.

This is not supported:

tool.Diameter = 8;

Use a method:

tool.SetDiameter(8);

Use parentheses even when the class has no parameters.

stats = ProbeStats();

Object methods can read object fields and root/session variables. Avoid using the same names for unrelated global variables and object fields.

Scope rules were explained in the previous chapter.

Read this script and predict the final value:

class Average()
{
    Count = 0;
    Sum = 0;
 
    function Add(value)
    {
        Count += 1;
        Sum += value;
    }
 
    function Value()
    {
        if(Count == 0)
        {
            return none();
        };
 
        return Sum / Count;
    }
}
 
avg = Average();
avg.Add(10);
avg.Add(20);
avg.Add(30);
 
avg.Value();

The final value is `20`.

Next: none(), nan(), and errors