Interface Annotations

About

An interface defines a class that is the base for both the implementation and the automatically created reference class. It is possible to add annotations to the interface to change the behaviour of the Source Processor when creating the reference class.

Annotations are added as comments in this form:

// @MAXON_ANNOTATION{refclass=false}

Interface Annotations

Annotations can be added to the interface itself. These annotations define the overall creation of the reference class.

  • refclass: Defines how the reference class is created. Valid settings are:
    • false: No reference class is created.
  • refprefix: Defines a prefix that is added to the reference class name.

Method Annotations

Annotations can also be added to single functions of the interface.

  • refclass: If set to false the function is not added to the reference class.
  • default: Defines the default return value in case of an error (e.g. no implementation was found).
  • refclassParameter: Set to the name of a function template parameter that should be replaced with the actual reference class.

Special annotations for COW interfaces are:

  • cowName: Changes the name of the generated function of the COW reference class.

Usage

Annotations are used on the definition of the interface.

// This example shows an interface with additional annotations.
// ---------------------------------------------------------------------
// The reference class should be named GenericElementArrayRef
// @MAXON_ANNOTATION{refprefix=Generic}
// ---------------------------------------------------------------------
class ElementArrayInterface : MAXON_INTERFACE_BASES(maxon::ObjectInterface)
{
MAXON_INTERFACE(ElementArrayInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.elementarray");
public:
// ---------------------------------------------------------------------
// If this function is not implemented it should return maxon::InvalidArrayIndex.
// @MAXON_ANNOTATION{default = maxon::InvalidArrayIndex}
// ---------------------------------------------------------------------
// ---------------------------------------------------------------------
// This function should not be added to the reference class.
// @MAXON_ANNOTATION{refclass=false}
// ---------------------------------------------------------------------
// ---------------------------------------------------------------------
// This function should be used instead.
// ---------------------------------------------------------------------
{
if (e == nullptr)
return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, maxon::String("Invalid Index."));
return e;
}
// ---------------------------------------------------------------------
// This function returns a clone of the array and returns an object of
// the currently used reference class type.
// @MAXON_ANNOTATION{refclassParameter=REFCLASS}
// ---------------------------------------------------------------------
template <typename REFCLASS> MAXON_FUNCTION maxon::Result<REFCLASS> CloneArray() const
{
return REFCLASS(static_cast<typename REFCLASS::ReferencedType*>(o));
}
};
[interfaces_annotations_declaration]
Definition: annotations.h:19
MAXON_FUNCTION maxon::Result< Element * > GetElementResult(maxon::Int index)
Definition: annotations.h:38
MAXON_METHOD Element * GetElement(maxon::Int index)
MAXON_METHOD maxon::Int FindIndex(Element *e) const
MAXON_INTERFACE(ElementArrayInterface, MAXON_REFERENCE_NORMAL, "net.maxonexample.interfaces.elementarray")
MAXON_FUNCTION maxon::Result< REFCLASS > CloneArray() const
Definition: annotations.h:52
Definition: objectbase.h:1358
Definition: resultbase.h:766
Definition: string.h:1235
Py_ssize_t * index
Definition: abstract.h:374
PyObject * o
Definition: abstract.h:325
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:213
#define MAXON_FUNCTION
Definition: interfacebase.h:1033
#define MAXON_REFERENCE_NORMAL(FREEIMPL)
Definition: interfacebase.h:1184
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define MAXON_METHOD
Definition: interfacebase.h:1012
#define MAXON_INTERFACE_BASES(...)
Definition: objectbase.h:1049
Py_ssize_t * e
Definition: longobject.h:89
#define iferr_scope
Definition: resultbase.h:1386
#define iferr_return
Definition: resultbase.h:1521
Definition: annotations.h:7

The behaviour of the created reference class is defined by the annotations.

// This example uses the reference class defined with various annotations.
// create a NullValue
GenericElementArrayRef nullValue;
// since FindIndex() is not implemented it should
// return the defined return value
const maxon::Int index = nullValue.FindIndex(nullptr);
DiagnosticOutput("Could not find element.");
// create proper instance
const maxon::Class<GenericElementArrayRef> componentClass = maxon::Classes::Get<GenericElementArrayRef>(id);
const GenericElementArrayRef elementArray = componentClass.Create() iferr_return;
// use some functions
GenericElementArrayRef elements = elementArray.CloneArray() iferr_return;
Element* const e = elementArray.GetElementResult(-1) iferr_return;
Definition: objectbase.h:696
static constexpr Int InvalidArrayIndex
Invalid array index (e.g. returned for an array index out of bounds).
Definition: apibase.h:305
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:176

Further Reading