Class AbstractRuleBasedInterpreter

  • All Implemented Interfaces:
    HumanLanguageInterpreter

    public abstract class AbstractRuleBasedInterpreter
    extends Object
    implements HumanLanguageInterpreter
    A human language command interpretation service.
    Author:
    Tilman Kamp - Initial contribution, Kai Kreuzer - Improved error handling
    • Constructor Detail

      • AbstractRuleBasedInterpreter

        public AbstractRuleBasedInterpreter()
    • Method Detail

      • name

        protected Expression name()
        Creates an item name placeholder expression. This expression is greedy: Only use it, if there are no other expressions following this one. It's safer to use thingRule instead.
        Returns:
        Expression that represents a name of an item.
      • name

        protected Expression name​(Expression stopper)
        Creates an item name placeholder expression. This expression is greedy: Only use it, if you are able to pass in all possible stop tokens as excludes. It's safer to use thingRule instead.
        Parameters:
        stopper - Stop expression that, if matching, will stop this expression from consuming further tokens.
        Returns:
        Expression that represents a name of an item.
      • getRules

        public Rule[] getRules​(Locale locale)
        Retrieves all Rules to a given Locale. It also retrieves all the same-language rules into greater indexes of the array (lower match priority).
        Parameters:
        locale - Locale filter
        Returns:
        Rules in descending match priority order.
      • addRules

        protected void addRules​(Locale locale,
                                Rule... rules)
        Adds Locale specific rules to this interpreter. To be called from within createRules().
        Parameters:
        locale - Locale of the rules.
        rules - Rules to add.
      • itemRule

        protected Rule itemRule​(Object headExpression)
        Creates an item rule on base of an expression, where the tail of the new rule's expression will consist of an item name expression.
        Parameters:
        headExpression - The head expression that should contain at least one cmd(java.lang.Object) generated expression. The corresponding Command will in case of a match be sent to the matching Item.
        Returns:
        The created rule.
      • itemRule

        protected Rule itemRule​(Object headExpression,
                                Object tailExpression)
        Creates an item rule on base of a head and a tail expression, where the middle part of the new rule's expression will consist of an item name expression. Either the head expression or the tail expression should contain at least one cmd(java.lang.Object) generated expression.
        Parameters:
        headExpression - The head expression.
        tailExpression - The tail expression.
        Returns:
        The created rule.
      • exp

        protected Expression exp​(Object obj)
        Converts an object to an expression. Objects that are already instances of Expression are just returned. All others are converted to match expressions.
        Parameters:
        obj - the object that's to be converted
        Returns:
        resulting expression
      • exps

        protected Expression[] exps​(Object... objects)
        Converts all parameters to an expression array. Objects that are already instances of Expression are not touched. All others are converted to match expressions.
        Parameters:
        obj - the objects that are to be converted
        Returns:
        resulting expression array
      • tag

        protected Expression tag​(String name,
                                 Object expression)
        Adds a name to the resulting AST tree, if the given expression matches.
        Parameters:
        name - name to add
        expression - the expression that has to match
        Returns:
        resulting expression
      • tag

        protected Expression tag​(Object expression,
                                 Object tag)
        Adds a value to the resulting AST tree, if the given expression matches.
        Parameters:
        expression - the expression that has to match
        tag - the tag that's to be set
        Returns:
        resulting expression
      • tag

        protected Expression tag​(String name,
                                 Object expression,
                                 Object tag)
        Adds a name and a tag to the resulting AST tree, if the given expression matches.
        Parameters:
        name - name to add
        expression - the expression that has to match
        tag - the tag that's to be set
        Returns:
        resulting expression
      • cmd

        protected Expression cmd​(Object expression)
        Adds a command to the resulting AST tree. If the expression evaluates to a numeric value, it will get a DecimalType, otherwise a StringType.
        Parameters:
        expression - the expression that has to match
        Returns:
        resulting expression
      • cmd

        protected Expression cmd​(Object expression,
                                 Command command)
        Adds a command to the resulting AST tree, if the expression matches.
        Parameters:
        expression - the expression that has to match
        command - the command that should be added
        Returns:
        resulting expression
      • alt

        protected org.eclipse.smarthome.core.voice.text.ExpressionAlternatives alt​(Object... expressions)
        Creates an alternatives expression. Matches, as soon as one of the given expressions matches. They are tested in the provided order. The value of the matching expression will be used for the resulting nodes's value.
        Parameters:
        expressions - the expressions (alternatives) that are to be tested
        Returns:
        resulting expression
      • seq

        protected ExpressionSequence seq​(Object... expressions)
        Creates a sequence expression. Matches, if all the given expressions match. They are tested in the provided order. The resulting nodes's value will be an Object[] that contains all values of the matching expressions.
        Parameters:
        expressions - the expressions (alternatives) that have to match in sequence
        Returns:
        resulting expression
      • opt

        protected ExpressionCardinality opt​(Object expression)
        Creates an optional expression. Always succeeds. The resulting nodes's value will be the one of the matching expression or null.
        Parameters:
        expression - the optionally matching expression
        Returns:
        resulting expression
      • star

        protected ExpressionCardinality star​(Object expression)
        Creates a repeating expression that will match the given expression as often as possible. Always succeeds. The resulting node's value will be an Object[] that contains all values of the matches.
        Parameters:
        expression - the repeating expression
        Returns:
        resulting expression
      • plus

        protected ExpressionCardinality plus​(Object expression)
        Creates a repeating expression that will match the given expression as often as possible. Only succeeds, if there is at least one match. The resulting node's value will be an Object[] that contains all values of the matches.
        Parameters:
        expression - the repeating expression
        Returns:
        resulting expression
      • executeSingle

        protected String executeSingle​(ResourceBundle language,
                                       String[] labelFragments,
                                       Command command)
                                throws InterpretationException
        Executes a command on one item that's to be found in the item registry by given name fragments. Fails, if there is more than on item.
        Parameters:
        language - resource bundle used for producing localized response texts
        labelFragments - label fragments that are used to match an item's label. For a positive match, the item's label has to contain every fragment - independently of their order. They are treated case insensitive.
        command - command that should be executed
        Returns:
        response text
        Throws:
        InterpretationException - in case that there is no or more than on item matching the fragments
      • getMatchingItems

        protected List<Item> getMatchingItems​(ResourceBundle language,
                                              String[] labelFragments,
                                              Class<?> commandType)
        Filters the item registry by matching each item's name with the provided name fragments. The item's label and its parent group's labels are tokenized tokenize(java.util.Locale,java.lang.String) and then altogether looked up by each and every provided fragment. For the item to get included into the result list, every provided fragment has to be found among the label tokens. If a command type is provided, the item also has to support it. In case of channels and their owners being ambiguous due to sharing most of the label sequence, only the top most item with support for the given command type is kept.
        Parameters:
        language - Language information that is used for matching
        labelFragments - label fragments that are used to match an item's label. For a positive match, the item's label has to contain every fragment - independently of their order. They are treated case insensitive.
        commandType - optional command type that all items have to support. Provide {null} if there is no need for a certain command to be supported.
        Returns:
        All matching items from the item registry.
      • tokenize

        protected List<String> tokenize​(Locale locale,
                                        String text)
        Tokenizes text. Filters out all unsupported punctuation. Tokens will be lower case.
        Parameters:
        locale - the locale that should be used for lower casing
        text - the text that should be tokenized
        Returns:
        resulting tokens
      • setItemRegistry

        public void setItemRegistry​(ItemRegistry itemRegistry)
      • unsetItemRegistry

        public void unsetItemRegistry​(ItemRegistry itemRegistry)
      • setEventPublisher

        public void setEventPublisher​(EventPublisher eventPublisher)
      • unsetEventPublisher

        public void unsetEventPublisher​(EventPublisher eventPublisher)