diff --git a/doc/source/draft/appdev-guide/murano_pl.rst b/doc/source/draft/appdev-guide/murano_pl.rst index cc123918..440956d0 100644 --- a/doc/source/draft/appdev-guide/murano_pl.rst +++ b/doc/source/draft/appdev-guide/murano_pl.rst @@ -15,4 +15,5 @@ YAQL languages. The sections below describe these languages. .. include:: murano_pl/yaql.rst .. include:: murano_pl/class_templ.rst .. include:: murano_pl/core_lib.rst +.. include:: murano_pl/reflection.rst .. include:: murano_pl/actions.rst diff --git a/doc/source/draft/appdev-guide/murano_pl/class_templ.rst b/doc/source/draft/appdev-guide/murano_pl/class_templ.rst index 986f5dd3..cb13a5b7 100644 --- a/doc/source/draft/appdev-guide/murano_pl/class_templ.rst +++ b/doc/source/draft/appdev-guide/murano_pl/class_templ.rst @@ -189,6 +189,9 @@ that values confirm to the contracts. scope: $.scope protocol: $.protocol + +.. _property_usage: + Usage +++++ diff --git a/doc/source/draft/appdev-guide/murano_pl/reflection.rst b/doc/source/draft/appdev-guide/murano_pl/reflection.rst new file mode 100644 index 00000000..3fadcc91 --- /dev/null +++ b/doc/source/draft/appdev-guide/murano_pl/reflection.rst @@ -0,0 +1,267 @@ +.. _reflection: + +Reflection capabilities in MuranoPL. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Reflection provides objects that describes MuranoPL classes and packages. + +The first important function is ``typeinfo`` . Usage: + +.. code-block:: yaml + + $typeInfo: typeinfo($someObject) + + + +Now ``$typeInfo`` variable contains instance of type of ``$someObject`` (``MuranoClass`` instance). + +MuranoPL provide following abilities to reflection: + + +.. _types_reflection: + +Types +----- + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :stub-columns: 0 + :class: borderless + + * - Property + - Description + * - ``name`` + - name of MuranoPL class + * - ``version`` + - version (`SemVer`_) of MuranoPL class. + * - ``ancestors`` + - list of class ancestors + * - ``properties`` + - list of class properties. See :ref:`properties_reflection` + * - ``package`` + - package information. See :ref:`package_reflection` + * - ``methods`` + - list of methods. See :ref:`methods_reflection` + * - ``type`` + - reference to type, which can be used as argument in engine functions + + + +*Example* + +.. code-block:: yaml + + - $typeInfo: typeinfo($) + ... + # log name, version and package name of this class + - $log.info("This is "{class_name}/{version} from {package}", + class_name => $typeInfo.name, + version => str($typeInfo.version), + package => $typeInfo.package.name)) + - $log.info("Ancestors:") + - For: ancestor + In: $typeInfo.ancestors + Do: + #log all ancestors names + - $log.info("{ancestor_name}", ancestor_name => $ancestor.name) + # log full class version + - $log.info("{version}", version => str($typeInfo.version)) + # create object with same class + - $newObject = new($typeInfo.type) + + +.. _properties_reflection: + +Properties +---------- + + +Property introspection +++++++++++++++++++++++ + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :stub-columns: 0 + :class: borderless + + * - Property + - Description + * - ``name`` + - name of property + * - ``hasDefault`` + - boolean value. `True`, if property has default value, `False` otherwise + * - ``usage`` + - `Usage` property's field. See :ref:`property_usage` for details + * - ``declaringType`` + - type - owner of declared property + + +Property access ++++++++++++++++ + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :stub-columns: 0 + :class: borderless + + * - Methods + - Description + * - ``$property.setValue($target, $value)`` + - set value of ``$property`` for object ``$target`` to ``$value`` + * - ``$property.getValue($target)`` + - get value of ``$property`` for object ``$target`` + +*Example* + +.. code-block:: yaml + + - $typeInfo: typeinfo($) + ... + # select first property + - $selectedPropety: $typeInfo.properties.first() + # log property name + - $log.info("Hi, my name is {p_name}, p_name => $selectedProperty.name) + # set new property value + - $selectedProperty.setValue($, "new_value") + # log new property value using reflection + - $log.info("My new value is {value}", value => $selectedProperty.getValue($)) + # also, if property static, $target can be null + - $log.info("Static property value is {value}, + value => $staticProperty.getValue(null)) + + + +.. _package_reflection: + +Packages +-------- + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :stub-columns: 0 + :class: borderless + + * - Property + - Description + * - ``types`` + - list of types, declared in package + * - ``name`` + - package name + * - ``version`` + - package version + + +*Example* + +.. code-block:: yaml + + - $typeInfo: typeinfo($) + ... + - $packageRef: $typeInfo.package + - $log.info("This is package {p_name}/{p_version}", + p_name => $packageRef.name, + p_version => str($packageRef.version)) + - $log.info("Types in package:") + - For: type_ + In: $packageRef.types + Do: + - $log.info("{typename}", typename => type_.name) + + +.. _methods_reflection: + +Methods +------- + +Methods properties +++++++++++++++++++ + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :stub-columns: 0 + :class: borderless + + * - Property + - Description + * - ``name`` + - method's name + * - ``declaringType`` + - type - owner of declared method + * - ``arguments`` + - list of method's arguments. See :ref:`arguments_reflection` + + +Method invoking ++++++++++++++++ + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :stub-columns: 0 + :class: borderless + + * - Methods + - Description + * - ``$method.invoke($target, $arg1, ... $argN, kwarg1 => value1, ..., kwargN => valueN)`` + - call ``$target``'s method $method with ``$arg1``, ..., ``$argN`` positional arguments and ``kwarg1``, .... ``kwargN`` named arguments + +*Example* + +.. code-block:: yaml + + - $typeInfo: typeinfo($) + ... + # select single method by name + - $selectedMethod: $typeInfo.methods.where($.name = sampleMethodName).single() + # log method name + - $log.info("Method name: {m_name}", m_name => $selectedMethod.name) + # log method arguments names + - For: argument + In: $selectedMethod.arguments + Do: + - $log.info("{name}", name => $argument.name) + # call method with positional argument 'bar' and named `baz` == 'baz' + - $selectedMethod.invoke($, 'bar', baz => baz) + + +.. _arguments_reflection: + +Method arguments +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + :stub-columns: 0 + :class: borderless + + * - Property + - Description + * - ``name`` + - argument's name + * - ``hasDefault`` + - `True` if argument has default value, `False` otherwise + * - ``declaringMethod`` + - method - owner of argument + +.. code-block:: yaml + + - $firstArgument: $selectedMethod.arguments.first() + # store argument's name + - $argName = $firstArgument.name + # store owner's name + - $methodName = $firstArgument.declaringMethod.name + - $log.info("Hi, my name is {a_name} ! My owner is {m_name}", + a_name => $argName, + m_name => $methodName) + + +.. Links: +.. _`SemVer`: http://semver.org + +