Expressioned Parameters
=======================

.. py:currentmodule:: NodegraphAPI

A parameter can have its value computed dynamically using a Python expression.
Expressions are set using :meth:`~Parameter.setExpression`, which takes a
Python string representing the expression as its first argument and an optional
*enable* parameter to specify whether to implicitly enable the expression.

A parameter expression must evaluate in the same way that a Python ``eval``
expression would (as a condition list). The global and local scopes of a
parameter expression are sand-boxed so that it is not possible to make
topological changes to the Node Graph whilst it is being resolved.

It is possible to write an expression that references a node by name and not break when the node name changes.

.. note:: You should avoid using the ``nodeName`` variable for parameter expressions that specify scene graph
    locations, and must take care when using them anywhere that a scene graph attribute is set. Node names are not
    namespaced and can therefore change unpredictably.

The following example script sets the expression on a parameter::

    # Add a PrimitiveCreate node
    rootNode = NodegraphAPI.GetRootNode()
    primNode = NodegraphAPI.CreateNode('PrimitiveCreate', rootNode)

    # Add a number parameter called myNumber
    rootParam = primNode.getParameters()
    rootParam.createChildNumber("myNumber", 7.0)

    # Link myNumber to the node's scale x parameter by expression
    scaleXParam = primNode.getParameter('transform.scale.x')
    scaleXParam.setExpression("getParam('%s.myNumber')" % primNode.getName())
    # Alternatively:
    # scaleXParam.setExpression("myNumber")

You can disable an expression with the :meth:`~Parameter.setExpressionFlag` method::

    scaleXParam.setExpressionFlag(False) # Disable
    scaleXParam.setExpressionFlag(True) # Enable

.. automethod:: Parameter.isExpression
.. automethod:: Parameter.getExpression
.. automethod:: Parameter.getExpressionError
.. automethod:: Parameter.setExpression
.. automethod:: Parameter.setExpressionFlag

.. automethod:: Parameter.getReferences
.. automethod:: Parameter.renameExpression
.. automethod:: Parameter.reparentExpression