Package com.inductiveautomation.ignition.common.script

Class PyArgParser

  • public class PyArgParser
extends java.lang.Object
    Roughly equivalent to the older PyArgumentMap, but with stricter validation of types and some more "modern" conveniences.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean containsKey​(java.lang.String keyword)  
      java.util.Optional<java.util.List<java.lang.Object>> getAsList​(java.lang.String keyword)
      Retrieve the argument specified by keyword as a plain list.
      <T> java.util.Optional<java.util.List<T>> getAsList​(java.lang.String keyword, java.lang.Class<T> clazz)
      Retrieve the argument specified by keyword as a typed list of clazz.
      java.util.Optional<java.util.Map<java.lang.Object,​java.lang.Object>> getAsMap​(java.lang.String keyword)
      Retrieve the argument specified by keyword as an untyped map.
      <K,​V>
      java.util.Optional<java.util.Map<K,​V>>      		 getAsMap​(java.lang.String keyword, java.lang.Class<K> keyType, java.lang.Class<V> valueType)
      Retrieve the argument specified by keyword as a typed map.
      java.util.Optional<java.lang.Boolean> getBoolean​(java.lang.String keyword)
      Gets keyword, if and only if it was supplied as a boolean.
      java.util.Optional<java.util.Date> getDate​(java.lang.String keyword)
      Gets keyword, if and only if it was supplied as a Date.
      java.util.Optional<java.lang.Double> getDouble​(java.lang.String keyword)
      Gets keyword, if and only if it was supplied as a double.
      java.util.Optional<java.lang.Float> getFloat​(java.lang.String keyword)
      Gets keyword, if and only if it was supplied as a float.
      java.util.Optional<java.lang.Integer> getInteger​(java.lang.String keyword)
      Gets keyword, if and only if it was supplied as an integer.
      java.util.Optional<java.lang.Long> getLong​(java.lang.String keyword)
      Gets keyword, if and only if it was supplied as a long.
      java.lang.Boolean getNullableBoolean​(java.lang.String keyword)
      Retrieve argument keyword, if and only if it was supplied as a Boolean.
      java.util.Date getNullableDate​(java.lang.String keyword)
      Retrieve argument keyword, if and only if it was supplied as a Date.
      java.lang.Double getNullableDouble​(java.lang.String keyword)
      Retrieve argument keyword, if and only if it was supplied as a Double.
      java.lang.Float getNullableFloat​(java.lang.String keyword)
      Retrieve argument keyword, if and only if it was supplied as a Float.
      java.lang.Integer getNullableInteger​(java.lang.String keyword)
      Retrieve argument keyword, if and only if it was supplied as a Integer.
      java.lang.Long getNullableLong​(java.lang.String keyword)
      Retrieve argument keyword, if and only if it was supplied as a Long.
      java.lang.String getNullableString​(java.lang.String keyword)
      Retrieve argument keyword, if and only if it was supplied as a String.
      <T> T getNullSafe​(java.lang.String keyword, java.lang.Class<T> clazz)  
      java.util.Optional<org.python.core.PyObject> getPyObject​(java.lang.String keyword)
      Gets keyword, directly as a PyObject; i.e., without doing any casting.
      java.util.Optional<java.lang.String> getString​(java.lang.String keyword)
      Gets keyword, if and only if it was supplied as a String.
      <T> java.util.Optional<T> getTyped​(java.lang.String keyword, java.lang.Class<T> clazz)
      If keyword was supplied, return it (type-safe) or throw a TypeError.
      static PyArgParser parseArgs​(org.python.core.PyObject[] args, java.lang.String[] keywords, java.lang.Class<?> callingClass, java.lang.String methodName)
      Similar to PyArgumentMap.interpretPyArgs(PyObject[], String[], Class, String), but with more explicit type-checking behavior.
      static PyArgParser parseArgs​(org.python.core.PyObject[] args, java.lang.String[] keywords, java.lang.String[] expectedKeywords, java.lang.Class<?>[] expectedTypes, java.lang.String functionName)
      Similar to PyArgumentMap.interpretPyArgs(PyObject[], String[], String[], Class[]), but with more explicit type-checking behavior.
      boolean requireBoolean​(java.lang.String keyword)
      Retrieve required argument keyword, if and only if it was supplied as a boolean.
      java.util.Date requireDate​(java.lang.String keyword)
      Retrieve required argument keyword, if and only if it was supplied as a Date.
      double requireDouble​(java.lang.String keyword)
      Retrieve required argument keyword, if and only if it was supplied as a double.
      float requireFloat​(java.lang.String keyword)
      Retrieve required argument keyword, if and only if it was supplied as a float.
      int requireInteger​(java.lang.String keyword)
      Retrieve required argument keyword, if and only if it was supplied as an integer.
      long requireLong​(java.lang.String keyword)
      Retrieve required argument keyword, if and only if it was supplied as a long.
      org.python.core.PyObject requirePyObject​(java.lang.String keyword)
      Retrieve keyword, directly as a PyObject; i.e., without doing any casting.
      java.lang.String requireString​(java.lang.String keyword)
      Retrieve required argument keyword, if and only if it was supplied as a String.
      <T> T requireTyped​(java.lang.String keyword, java.lang.Class<T> clazz)
      Retrieve required argument keyword, if and only if the supplied value can be coerced to clazz.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • parseArgs

        public static PyArgParser parseArgs​(org.python.core.PyObject[] args,
                                    java.lang.String[] keywords,
                                    java.lang.String[] expectedKeywords,
                                    java.lang.Class<?>[] expectedTypes,
                                    java.lang.String functionName)
        Similar to PyArgumentMap.interpretPyArgs(PyObject[], String[], String[], Class[]), but with more explicit type-checking behavior.
        Parameters:
        args - args from a function call
        keywords - keyword names from a function call
        expectedKeywords - expected keyword arguments
        expectedTypes - expected argument types
        functionName - the name of the function; used for better contextual error messages
        Returns:
        a PyArgParser instance
        Throws:
        java.lang.IllegalArgumentException - if the provided method cannot be found, or is missing the KeywordArgs annotation.
        java.lang.AssertionError - if keywords is shorter than args, or the list of expected keywords doesn't match the list of expected types.

      • parseArgs

        public static PyArgParser parseArgs​(org.python.core.PyObject[] args,
                                    java.lang.String[] keywords,
                                    java.lang.Class<?> callingClass,
                                    java.lang.String methodName)
        Similar to PyArgumentMap.interpretPyArgs(PyObject[], String[], Class, String), but with more explicit type-checking behavior.
        Parameters:
        args - args from a function call
        keywords - keyword names from a function call
        callingClass - the class the method is contained in. Will be checked reflectively for the KeywordArgs annotation.
        methodName - the name of the method. Used to look up annotations reflectively, and for thrown errors.
        Returns:
        a PyArgParser instance
        Throws:
        java.lang.IllegalArgumentException - if the provided method cannot be found, or is missing the KeywordArgs annotation.
        java.lang.AssertionError - if keywords is shorter than args, or the list of expected keywords doesn't match the list of expected types.
        org.python.core.PyException - TypeError if more arguments are provided than expected argument names

      • getTyped

        public <T> java.util.Optional<T> getTyped​(java.lang.String keyword,
                                          java.lang.Class<T> clazz)
        If keyword was supplied, return it (type-safe) or throw a TypeError. If not specified or None was supplied, returns an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value cannot be coerced to clazz.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function

      • requireTyped

        public <T> T requireTyped​(java.lang.String keyword,
                          java.lang.Class<T> clazz)
        Retrieve required argument keyword, if and only if the supplied value can be coerced to clazz.
        Returns:
        the retrieved value of keyword coerced to clazz.
        Throws:
        org.python.core.PyException - TypeError if the supplied value cannot be coerced to clazz.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function.

      • getNullSafe

        @Nullable
public <T> T getNullSafe​(java.lang.String keyword,
                         java.lang.Class<T> clazz)

      • getBoolean

        public java.util.Optional<java.lang.Boolean> getBoolean​(java.lang.String keyword)
        Gets keyword, if and only if it was supplied as a boolean.
        Returns:
        the boolean value of keyword, if supplied, or an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a boolean.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireBoolean(String)

      • requireBoolean

        public boolean requireBoolean​(java.lang.String keyword)
        Retrieve required argument keyword, if and only if it was supplied as a boolean.
        Returns:
        the boolean value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a boolean, or was not specified.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getBoolean(String)

      • getNullableBoolean

        @Nullable
public java.lang.Boolean getNullableBoolean​(java.lang.String keyword)
        Retrieve argument keyword, if and only if it was supplied as a Boolean. Unlike requireBoolean(String), will accept a supplied value of PyNone and return null.
        Returns:
        the Boolean value of keyword, or null.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Boolean
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireBoolean(String)

      • getInteger

        public java.util.Optional<java.lang.Integer> getInteger​(java.lang.String keyword)
        Gets keyword, if and only if it was supplied as an integer.
        Returns:
        the integer value of keyword, if supplied, or an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a integer.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireInteger(String)

      • requireInteger

        public int requireInteger​(java.lang.String keyword)
        Retrieve required argument keyword, if and only if it was supplied as an integer.
        Returns:
        the integer value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a integer, or was not specified.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getInteger(String)

      • getNullableInteger

        @Nullable
public java.lang.Integer getNullableInteger​(java.lang.String keyword)
        Retrieve argument keyword, if and only if it was supplied as a Integer. Unlike requireInteger(String), will accept a supplied value of PyNone and return null.
        Returns:
        the Integer value of keyword, or null.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Integer
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireInteger(String)

      • getLong

        public java.util.Optional<java.lang.Long> getLong​(java.lang.String keyword)
        Gets keyword, if and only if it was supplied as a long.
        Returns:
        the long value of keyword, if supplied, or an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a long.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireLong(String)

      • requireLong

        public long requireLong​(java.lang.String keyword)
        Retrieve required argument keyword, if and only if it was supplied as a long.
        Returns:
        the long value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a long, or was not specified.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getLong(String)

      • getNullableLong

        @Nullable
public java.lang.Long getNullableLong​(java.lang.String keyword)
        Retrieve argument keyword, if and only if it was supplied as a Long. Unlike requireLong(String), will accept a supplied value of PyNone and return null.
        Returns:
        the Long value of keyword, or null.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Long
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireLong(String)

      • getFloat

        public java.util.Optional<java.lang.Float> getFloat​(java.lang.String keyword)
        Gets keyword, if and only if it was supplied as a float.
        Returns:
        the float value of keyword, if supplied, or an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a float.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireFloat(String)

      • requireFloat

        public float requireFloat​(java.lang.String keyword)
        Retrieve required argument keyword, if and only if it was supplied as a float.
        Returns:
        the float value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a float, or was not specified.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getFloat(String)

      • getNullableFloat

        @Nullable
public java.lang.Float getNullableFloat​(java.lang.String keyword)
        Retrieve argument keyword, if and only if it was supplied as a Float. Unlike requireFloat(String), will accept a supplied value of PyNone and return null.
        Returns:
        the Float value of keyword, or null.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Float
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireFloat(String)

      • getDouble

        public java.util.Optional<java.lang.Double> getDouble​(java.lang.String keyword)
        Gets keyword, if and only if it was supplied as a double.
        Returns:
        the double value of keyword, if supplied, or an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a double.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireDouble(String)

      • requireDouble

        public double requireDouble​(java.lang.String keyword)
        Retrieve required argument keyword, if and only if it was supplied as a double.
        Returns:
        the double value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a double, or was not specified.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getDouble(String)

      • getNullableDouble

        @Nullable
public java.lang.Double getNullableDouble​(java.lang.String keyword)
        Retrieve argument keyword, if and only if it was supplied as a Double. Unlike requireDouble(String), will accept a supplied value of PyNone and return null.
        Returns:
        the Double value of keyword, or null.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Double
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireDouble(String)

      • getDate

        public java.util.Optional<java.util.Date> getDate​(java.lang.String keyword)
        Gets keyword, if and only if it was supplied as a Date.
        Returns:
        the Date value of keyword, if supplied, or an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Date.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireDate(String)

      • requireDate

        public java.util.Date requireDate​(java.lang.String keyword)
        Retrieve required argument keyword, if and only if it was supplied as a Date.
        Returns:
        the Date value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Date, or was not specified.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getDate(String)

      • getNullableDate

        @Nullable
public java.util.Date getNullableDate​(java.lang.String keyword)
        Retrieve argument keyword, if and only if it was supplied as a Date. Unlike requireDate(String), will accept a supplied value of PyNone and return null.
        Returns:
        the Date value of keyword, or null.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a Date
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireDate(String)

      • getString

        public java.util.Optional<java.lang.String> getString​(java.lang.String keyword)
        Gets keyword, if and only if it was supplied as a String.
        Returns:
        the String value of keyword, if supplied, or an empty optional.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a String.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireString(String)

      • requireString

        @Nonnull
public java.lang.String requireString​(java.lang.String keyword)
        Retrieve required argument keyword, if and only if it was supplied as a String.
        Returns:
        the String value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a String, or was not specified.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getString(String)

      • getNullableString

        @Nullable
public java.lang.String getNullableString​(java.lang.String keyword)
        Retrieve argument keyword, if and only if it was supplied as a String. Unlike requireString(String), will accept a supplied value of PyNone and return null.
        Returns:
        the String value of keyword, or null.
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not a String
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requireString(String)

      • getPyObject

        public java.util.Optional<org.python.core.PyObject> getPyObject​(java.lang.String keyword)
        Gets keyword, directly as a PyObject; i.e., without doing any casting.
        Returns:
        the PyObject value of keyword, if supplied, or an empty optional. Can be Py.None if None was supplied.
        Throws:
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        requirePyObject(String)

      • requirePyObject

        public org.python.core.PyObject requirePyObject​(java.lang.String keyword)
        Retrieve keyword, directly as a PyObject; i.e., without doing any casting.
        Returns:
        the PyObject value of keyword
        Throws:
        org.python.core.PyException - TypeError if the supplied value was not provided.
        java.lang.IllegalArgumentException - if the provided keyword is not an expected argument for the function
        See Also:
        getPyObject(String)

      • containsKey

        public boolean containsKey​(java.lang.String keyword)

      • getAsList

        public <T> java.util.Optional<java.util.List<T>> getAsList​(java.lang.String keyword,
                                                           java.lang.Class<T> clazz)
        Retrieve the argument specified by keyword as a typed list of clazz. Will be a shallow copy.
        Throws:
        org.python.core.PyException -
      • TypeError if any elements of the PyList supplied as an argument can't be coerced to clazz
      • TypeError if the supplied PyObject is not iterable

      • getAsList

        public java.util.Optional<java.util.List<java.lang.Object>> getAsList​(java.lang.String keyword)
        Retrieve the argument specified by keyword as a plain list. Will be a shallow copy.
        Throws:
        org.python.core.PyException -
      • TypeError if the supplied PyObject is not iterable

      • getAsMap

        public <K,​V> java.util.Optional<java.util.Map<K,​V>> getAsMap​(java.lang.String keyword,
                                                                         java.lang.Class<K> keyType,
                                                                         java.lang.Class<V> valueType)
        Retrieve the argument specified by keyword as a typed map. Will be a shallow copy.
        Throws:
        org.python.core.PyException -
      • TypeError if any elements of the PyDictionary supplied as an argument can't be coerced to the right class
      • TypeError if the supplied PyObject is not iterable

      • getAsMap

        public java.util.Optional<java.util.Map<java.lang.Object,​java.lang.Object>> getAsMap​(java.lang.String keyword)
        Retrieve the argument specified by keyword as an untyped map. Will be a shallow copy.
        Throws:
        org.python.core.PyException -
      • TypeError if the supplied PyObject is not iterable