Package org.eclipse.core.variables

Interface IStringVariableManager

  • public interface IStringVariableManager
    Registry for string variables.
    Since:
    3.0
    Restriction:
    This interface is not intended to be implemented by clients.

    • Field Detail

      • EXTENSION_POINT_DYNAMIC_VARIABLES

        static final String EXTENSION_POINT_DYNAMIC_VARIABLES
        Simple identifier constant (value "dynamicVariables") for the dynamic variables extension point.
        See Also:
        Constant Field Values

      • EXTENSION_POINT_VALUE_VARIABLES

        static final String EXTENSION_POINT_VALUE_VARIABLES
        Simple identifier constant (value "valueVariables") for the value variables extension point.
        See Also:
        Constant Field Values

    • Method Detail

      • getVariables

        IStringVariable[] getVariables()
        Returns all registered variables.
        Returns:
        a collection of all registered variables

      • getValueVariables

        IValueVariable[] getValueVariables()
        Returns all registered value variables.
        Returns:
        a collection of all registered value variables

      • getValueVariable

        IValueVariable getValueVariable​(String name)
        Returns the value variable with the given name, or null if none.
        Parameters:
        name - variable name
        Returns:
        the value variable with the given name, or null if none

      • getDynamicVariables

        IDynamicVariable[] getDynamicVariables()
        Returns all registered dynamic variables.
        Returns:
        a collection of all registered dynamic variables

      • getDynamicVariable

        IDynamicVariable getDynamicVariable​(String name)
        Returns the dynamic variable with the given name or null if none.
        Parameters:
        name - variable name
        Returns:
        the dynamic variable with the given name or null if none

      • getContributingPluginId

        String getContributingPluginId​(IStringVariable variable)
        Returns the plug-in identifier of the plug-in that contributed the given variable via extension or null if the given variable wasn't contributed via extension.
        Parameters:
        variable - the variable
        Returns:
        the plug-in identifier of the plug-in that contributed the given variable or null
        Since:
        3.1

      • performStringSubstitution

        String performStringSubstitution​(String expression)
                          throws CoreException
        Recursively resolves and replaces all variable references in the given expression with their corresponding values. Reports errors for references to undefined variables (equivalent to calling performStringSubstitution(expression, true)).
        Parameters:
        expression - expression referencing variables
        Returns:
        expression with variable references replaced with variable values
        Throws:
        CoreException - if unable to resolve the value of one or more variables

      • performStringSubstitution

        String performStringSubstitution​(String expression,
                                 boolean reportUndefinedVariables)
                          throws CoreException
        Recursively resolves and replaces all variable references in the given expression with their corresponding values. Allows the client to control whether references to undefined variables are reported as an error (i.e. an exception is thrown).
        Parameters:
        expression - expression referencing variables
        reportUndefinedVariables - whether a reference to an undefined variable is to be considered an error (i.e. throw an exception)
        Returns:
        expression with variable references replaced with variable values
        Throws:
        CoreException - if unable to resolve the value of one or more variables

      • validateStringVariables

        void validateStringVariables​(String expression)
                      throws CoreException
        Validates variables references in the given expression and reports errors for references to undefined variables.
        Parameters:
        expression - expression referencing variables
        Throws:
        CoreException - if one or more referenced variables do not exist

      • newValueVariable

        IValueVariable newValueVariable​(String name,
                                String description)
        Returns a new read-write value variable with the given name and description with a null value.
        Parameters:
        name - variable name, cannot be null
        description - variable description, possibly null
        Returns:
        a new value variable

      • newValueVariable

        IValueVariable newValueVariable​(String name,
                                String description,
                                boolean readOnly,
                                String value)
        Returns a new value variable with the given properties.
        Parameters:
        name - variable name, cannot be null
        description - variable description, possibly null
        readOnly - whether this variable is to be a read only variable
        value - the string value to initialize this variable to - should not be null for read-only variables
        Returns:
        a new value variable
        Since:
        3.3

      • addVariables

        void addVariables​(IValueVariable[] variables)
           throws CoreException
        Adds the given variables to the variable registry.
        Parameters:
        variables - the variables to add
        Throws:
        CoreException - if one or more variables to add has a name collision with an existing variable

      • removeVariables

        void removeVariables​(IValueVariable[] variables)
        Removes the given variables from the registry. Has no effect for unregistered variables.
        Parameters:
        variables - variables to remove

      • addValueVariableListener

        void addValueVariableListener​(IValueVariableListener listener)
        Registers the given listener for value variable notifications. Has no effect if an identical listener is already registered.
        Parameters:
        listener - value variable listener to add

      • removeValueVariableListener

        void removeValueVariableListener​(IValueVariableListener listener)
        Removes the given listener from the list of registered value variable listeners. Has no effect if an identical listener is not already registered.
        Parameters:
        listener - value variable listener to remove

      • generateVariableExpression

        String generateVariableExpression​(String varName,
                                  String arg)
        Convenience method that returns an expression referencing the given variable and optional argument. For example, calling the method with a varName of my_var and an argument of my_arg results in the string $(my_var:my_arg}.
        Parameters:
        varName - variable name
        arg - argument text or null
        Returns:
        an expression referencing the given variable and optional argument