deb-murano/doc/source/draft/appdev-guide/murano_pl/statics.rst

Static methods and properties

In MuranoPL, static denotes class methods and class properties (as opposed to instance methods and instance properties). These methods and properties can be accessed without an instance present.

Static methods are often used for helper methods that are not bound to any object (that is, do not maintain a state) or as a convenient way to write a class factory.

Type objects

Usually static methods and properties are accessed using type object. That is, an object that represents the class rather than class instance.

For any given class foo.Bar its type object may be retrieved using any of the following ways: * Using ns:Bar notation considering that ns is declared in Namespaces section (and it is foo in this case), * Using :Bar syntax if Bar is in the current namespace (that is, what =:Bar would mean if = was a valid namespace prefix), * Using type() function with a fully qualified class name: type('foo.Bar'), * By obtaining a type of class instance: type($object) (available for packages with format version starting from 1.3), * Through reflection: typeinfo($object).type.

No matter what method was used to get type object, the returned object will be the same because there can be only one type object per class.

All functions that accept type name, for example new() function, also accept type objects.

Accessing static methods and properties

Static methods can be invoked using one of the two ways:

• Using `type object`: ns:Bar.foo(arg), :Bar.foo(arg), and so on,
• On a class instance similar to normal methods: $obj.foo(arg).

Access to properties is similar to that:

• Using `type object`: ns:Bar.property, :Bar.property, and so on,
• On a class instance: $obj.property.

Static properties are defined on a class rather than on an instance. Therefore, their values will be the same for all class instances (for particular version of the class).

Declaration of static methods and properties

Methods and properties are declared to be static by specifying Usage: Static on them.

For example:

Properties:
  property:
    Contract: $.string()
    Usage: Static

Methods:
  foo:
    Usage: Static
    Body:
    - Return: $.property

Static properties are never initialized from object model but can be modified from within MuranoPL code (i.e. they are not immutable). Static methods also can be executed as an action from outside using Scope: Public. Within static method Body $this (and $ if not set to something else in expression) are set to type object rather than to instance, as it is for regular methods.

Static methods written in Python

For MuranoPL classes entirely or partially written in Python, all methods that have either @staticmethod or @classmethod decorators are automatically imported as static methods and work as they normally do in Python.

Extension methods

Extension methods are a special kind of static methods that can act as if they were regular instance methods of some other type.

Extension methods enable you to "add" methods to existing types without modifying the original type.

Defining extension methods

Extension methods are declared with the Usage: Extension modifier.

For example:

Name: SampleClass
Methods:
  mul:
    Usage: Extension
    Arguments:
    - self:
        Contract: $.int().notNull()
    - arg:
        Contract: $.int().notNull()
    Body:
      Return: $self * $arg

Extension method are said to extend some other type and that type is deducted from the first method argument contract. Thus extension methods must have at least one argument.

Extension methods can also be written in Python just the same way as static methods. However one should be careful in method declaration and use precise yaql specification of the type of first method argument otherwise the method will become an extension of any type.

To turn Python static method into extension method it must be decorated with @yaql.language.specs.meta('Usage', 'Extension') decorator.

Using extension methods

The example above defines a method that extends integer type. Therefore, with the method above it becomes possible to say 2.mul(3). However, the most often usage is to extend some existing MuranoPL class using class() contract.

If the first argument contract does not have notNull(), then the method can be invoked on the null object as well (like null.foo()).

Extension methods are static methods and, therefore,can be invoked in a usual way on type object: :SampleClass.mul(2, 3). However, unlike regular static methods extensions cannot be invoked on a class instance because this can result in ambiguity.

Using extension lookup order

When somewhere in the code the $foo.bar() expression is encountered, MuranoPL uses the following order to locate bar() implementation: - If there is an instance or static method in $foo's class, it will be used. - Otherwise if the current class (where this expression was encountered) has an extension method called bar and $foo satisfies the contract of its first argument, then this method will be called.

Normally, if no method was found an exception will be raised. However, additional extension methods can be imported into the current context. This is done using the Import keyword on a class level. The Import section specifies either a list or a single type name (or type object) which extension methods will be available anywhere within the class code:

Name: MyClass
Import:
- ns:SomeOtherType
- :ClassFomCurrentContext
- 'io.murano.foo.Bar'

If no method was found with the algorithm above, the search continues on extension methods of all classes listed in the Import section in the order types are listed.