ruby_speech 2.1.0-java

data/lib/ruby_speech/grxml/grammar.rb

@@ -0,0 +1,189 @@
+module RubySpeech
+  module GRXML
+    ##
+    # The Speech Recognition Grammar Language is an XML application. The root element is grammar.
+    #
+    # http://www.w3.org/TR/speech-grammar/#S4.3
+    #
+    # Attributes: uri, language, root, tag-format
+    #
+    # tag-format declaration is an optional declaration of a tag-format identifier that indicates the content type of all tags contained within a grammar.
+    #
+    # NOTE: A grammar without rules is allowed but cannot be used for processing input -- http://www.w3.org/Voice/2003/srgs-ir/
+    #
+    # TODO: Look into lexicon (probably a sub element)
+    #
+    class Grammar < Element
+      include XML::Language
+
+      register :grammar
+
+      self.defaults = { :version => '1.0', :language => "en-US" }
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, Rule, Tag].freeze
+
+      ##
+      #
+      # The mode of a grammar indicates the type of input that the user agent should be detecting. The default mode is "voice" for speech recognition grammars. An alternative input mode is "dtmf" input".
+      #
+      # @return [String]
+      #
+      def mode
+        read_attr :mode, :to_sym
+      end
+
+      ##
+      # @param [String] ia
+      #
+      def mode=(ia)
+        self[:mode] = ia
+      end
+
+      ##
+      #
+      # The root ("rule") attribute indicates declares a single rule to be the root rle of the grammar.  This attribute is OPTIONAL. The rule declared must be defined within the scope of the grammar.  It specified rule can be scoped "public" or "private."
+      #
+      # @return [String]
+      #
+      def root
+        read_attr :root
+      end
+
+      ##
+      # @param [String] ia
+      #
+      def root=(ia)
+        self[:root] = ia
+      end
+
+      ##
+      #
+      # @return [String]
+      #
+      def tag_format
+        read_attr :'tag-format'
+      end
+
+      ##
+      # @param [String] ia
+      #
+      def tag_format=(s)
+        self['tag-format'] = s
+      end
+
+      ##
+      # @return [Rule] The root rule node for the document
+      #
+      def root_rule
+        children(:rule, :id => root).first
+      end
+
+      ##
+      # Checks for a root rule matching the value of the root tag
+      #
+      # @raises [InvalidChildError] if there is not a rule present in the document with the correct ID
+      #
+      # @return [Grammar] self
+      #
+      def assert_has_matching_root_rule
+        raise InvalidChildError, "A GRXML document must have a rule matching the root rule name" unless has_matching_root_rule?
+        self
+      end
+
+      ##
+      # @return [Grammar] an inlined copy of self
+      #
+      def inline
+        clone.inline!
+      end
+
+      ##
+      # Replaces rulerefs in the document with a copy of the original rule.
+      # Removes all top level rules except the root rule
+      #
+      # @return self
+      #
+      def inline!
+        xpath("//ns:ruleref", :ns => namespace_href).each do |ref|
+          rule = children(:rule, :id => ref[:uri].sub(/^#/, '')).first
+          ref.swap rule.nokogiri_children
+        end
+
+        non_root_rules = xpath "./ns:rule[@#{namespace_href && Nokogiri.jruby? ? 'ns:' : ''}id!='#{root}']", :ns => namespace_href
+        non_root_rules.remove
+
+        self
+      end
+
+      ##
+      # Replaces textual content of the document with token elements containing such content.
+      # This homogenises all tokens in the document to a consistent format for processing.
+      #
+      def tokenize!
+        traverse do |element|
+          next unless element.is_a? Nokogiri::XML::Text
+
+          element_type = self.class.import(element.parent).class
+          next if [Token, Tag].include?(element_type)
+
+          tokens = split_tokens(element).map do |string|
+            Token.new.tap { |token| token << string }
+          end
+
+          element.swap Nokogiri::XML::NodeSet.new(Nokogiri::XML::Document.new, tokens)
+        end
+      end
+
+      ##
+      # Normalizes whitespace within tokens in the document according to the rules in the SRGS spec (http://www.w3.org/TR/speech-grammar/#S2.1)
+      # Leading and trailing whitespace is removed, and multiple spaces within the string are collapsed down to single spaces.
+      #
+      def normalize_whitespace
+        traverse do |element|
+          next if element === self
+
+          imported_element = self.class.import element
+          next unless imported_element.respond_to? :normalize_whitespace
+
+          imported_element.normalize_whitespace
+          element.swap imported_element
+        end
+      end
+
+      def dtmf?
+        mode == :dtmf
+      end
+
+      def voice?
+        mode == :voice
+      end
+
+      def <<(arg)
+        raise InvalidChildError, "A Grammar can only accept Rule and Tag as children" unless VALID_CHILD_TYPES.include? arg.class
+        super
+      end
+
+      def eql?(o)
+        super o, :language, :base_uri, :mode, :root
+      end
+
+      def embed(other)
+        raise InvalidChildError, "Embedded grammars must have the same mode" if other.is_a?(self.class) && other.mode != mode
+        super
+      end
+
+      private
+
+      def has_matching_root_rule?
+        !root || root_rule
+      end
+
+      def split_tokens(element)
+        element.to_s.split(/(\".*\")/).reject(&:empty?).map do |string|
+          match = string.match /^\"(.*)\"$/
+          match ? match[1] : string.split(' ')
+        end.flatten
+      end
+    end # Grammar
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/item.rb

@@ -0,0 +1,144 @@
+module RubySpeech
+  module GRXML
+    ##
+    #
+    # The item element is one of the valid expansion elements for the SGR rule element
+    #
+    #   http://www.w3.org/TR/speech-grammar/#S2.4 --> XML Form
+    #
+    # The item element has four (optional) attributes: weight, repeat, repeat-prob, and xml:lang (language identifier)
+    #
+    #   http://www.w3.org/TR/speech-grammar/#S2.4.1
+    #   http://www.w3.org/TR/speech-grammar/#S2.3
+    #
+    # A weight may be optionally provided for any number of alternatives in an alternative expansion. Weights are simple positive floating point values without exponentials. Legal formats are "n", "n.", ".n" and "n.n" where "n" is a sequence of one or many digits.
+    #
+    # A weight is nominally a multiplying factor in the likelihood domain of a speech recognition search. A weight of 1.0 is equivalent to providing no weight at all. A weight greater than "1.0" positively biases the alternative and a weight less than "1.0" negatively biases the alternative.
+    #
+    # repeat has several valid values...
+    #
+    # Any repeated legal rule expansion is itself a legal rule expansion.
+    #
+    # Operators are provided that define a legal rule expansion as being another sub-expansion that is optional, that is repeated zero or more times, that is repeated one or more times, or that is repeated some range of times.
+    #
+    # repeat probability (repeat-prob)  indicates the probability of successive repetition of the repeated expansion.  It is ignored if repeat is not specified
+    #
+    # xml:lang declares declaration declares the language of the grammar section for the item element just as xml:lang in the <grammar> element declares for the entire document
+    #
+    class Item < Element
+      Inf = 1.0 / 0.0
+
+      register :item
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, OneOf, Item, String, Ruleref, Tag, Token].freeze
+
+      ##
+      #
+      # The optional weight attribute
+      #
+      # @return [Float]
+      #
+      def weight
+        read_attr :weight, :to_f
+      end
+
+      ##
+      #
+      # The weight attribute takes a positive (floating point) number
+      # NOTE: the standard says a format of "n" is valid (eg. an Integer)
+      # TODO: possibly support string and check to see if its a valid digit with regex...
+      #
+      # @param [Numeric] w
+      #
+      def weight=(w)
+        raise ArgumentError, "A Item's weight attribute must be a positive floating point number" unless w.to_s.match(/[^0-9\.]/) == nil and w.to_f >= 0
+        self[:weight] = w
+      end
+
+      ##
+      #
+      # The repeat attribute
+      #
+      # @return [String]
+      #
+      def repeat
+        repeat = read_attr :repeat
+        return nil unless repeat
+        if repeat.include?('-')
+          min, max = repeat.split('-').map &:to_i
+          (min || 0)..(max || Inf)
+        else
+          repeat.to_i
+        end
+      end
+
+      ##
+      #
+      # TODO: Raise ArgumentError after doing checking.  See
+      #       http://www.w3.org/TR/speech-grammar/#S2.5
+      #
+      # @param [String] r
+      #
+      def repeat=(r)
+        r = "#{r.min}-#{r.max unless r.max == Inf}" if r.is_a?(Range)
+        r = r.to_s
+        error = ArgumentError.new "A Item's repeat must be 0 or a positive integer"
+
+        raise error unless r.match(/[^0-9-]/) == nil and r.scan("-").size <= 1
+
+        raise error if case di = r.index('-')
+        when nil
+          r.to_i < 0  # must be 0 or a positive number
+        when 0
+          true  # negative numbers are illegal
+        else
+          if di == r.length - 1  # repeat 'm' or more times, m must be 0 or a positive number
+            r[0, r.length - 1].to_i < 0
+          else  # verify range m,n is valid
+            m, n = r.split('-').map &:to_i
+            m < 0 || n < m
+          end
+        end
+        self[:repeat] = r
+      end
+
+      ##
+      #
+      # The optional repeat-prob attribute
+      #
+      # @return [Float]
+      #
+      def repeat_prob
+        read_attr :'repeat-prob', :to_f
+      end
+
+      ##
+      # @param [Numeric] ia
+      #
+      def repeat_prob=(rp)
+        raise ArgumentError, "A Item's repeat probablity attribute must be a floating point number between 0.0 and 1.0" unless rp.to_s.match(/[^0-9\.]/) == nil and rp.to_f >= 0 and rp.to_f <= 1.0
+        self['repeat-prob'] = rp
+      end
+
+      def <<(arg)
+        raise InvalidChildError, "A Item can only accept String, Ruleref, Tag or Token as children" unless VALID_CHILD_TYPES.include? arg.class
+        super
+      end
+
+      def eql?(o)
+        super o, :weight, :repeat
+      end
+
+      def regexp_content # :nodoc:
+        case repeat
+        when Range
+          "#{super}{#{repeat.min},#{repeat.max unless repeat.max == Inf}}"
+        when Integer
+          "#{super}{#{repeat}}"
+        else
+          super
+        end
+      end
+    end # Item
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/match.rb

@@ -0,0 +1,16 @@
+module RubySpeech
+  module GRXML
+    class Match
+      attr_accessor :mode, :confidence, :utterance, :interpretation
+
+      def initialize(options = {})
+        options.each_pair { |k, v| self.send :"#{k}=", v }
+      end
+
+      def eql?(o)
+        o.instance_of?(self.class) && [:mode, :confidence, :utterance, :interpretation].all? { |f| self.__send__(f) == o.__send__(f) }
+      end
+      alias :== :eql?
+    end
+  end
+end

data/lib/ruby_speech/grxml/matcher.rb

@@ -0,0 +1,126 @@
+require 'ruby_speech/ruby_speech'
+
+if RUBY_PLATFORM =~ /java/
+  require 'jruby'
+  com.benlangfeld.ruby_speech.RubySpeechService.new.basicLoad(JRuby.runtime)
+end
+
+module RubySpeech
+  module GRXML
+    class Matcher
+      UTTERANCE_CONVERTER = Hash.new { |hash, key| hash[key] = key }
+      UTTERANCE_CONVERTER['*'] = 'star'
+      UTTERANCE_CONVERTER['#'] = 'pound'
+
+      attr_reader :grammar
+
+      def initialize(grammar)
+        @grammar = grammar
+        prepare_grammar
+        compile_regex regexp_content
+      end
+
+      ##
+      # Checks the grammar for a match against an input string
+      #
+      # @param [String] other the input string to check for a match with the grammar
+      #
+      # @return [NoMatch, PotentialMatch, Match, MaxMatch] depending on the result of a match attempt. A potential match indicates that the buffer is valid, but incomplete. A MaxMatch is differentiated from a Match in that it cannot accept further input. If a match can be found, it will be returned with appropriate mode/confidence/utterance and interpretation attributes
+      #
+      # @example A grammar that takes a 4 digit pin terminated by hash, or the *9 escape sequence
+      #     ```ruby
+      #       grammar = RubySpeech::GRXML.draw :mode => :dtmf, :root => 'pin' do
+      #         rule :id => 'digit' do
+      #           one_of do
+      #             ('0'..'9').map { |d| item { d } }
+      #           end
+      #         end
+      #
+      #         rule :id => 'pin', :scope => 'public' do
+      #           one_of do
+      #             item do
+      #               item :repeat => '4' do
+      #                 ruleref :uri => '#digit'
+      #               end
+      #               "#"
+      #             end
+      #             item do
+      #               "\* 9"
+      #             end
+      #           end
+      #         end
+      #       end
+      #
+      #       matcher = RubySpeech::GRXML::Matcher.new grammar
+      #
+      #       >> matcher.match '*9'
+      #       => #<RubySpeech::GRXML::Match:0x00000100ae5d98
+      #             @mode = :dtmf,
+      #             @confidence = 1,
+      #             @utterance = "*9",
+      #             @interpretation = "*9"
+      #           >
+      #       >> matcher.match '1234#'
+      #       => #<RubySpeech::GRXML::Match:0x00000100b7e020
+      #             @mode = :dtmf,
+      #             @confidence = 1,
+      #             @utterance = "1234#",
+      #             @interpretation = "1234#"
+      #           >
+      #       >> matcher.match '5678#'
+      #       => #<RubySpeech::GRXML::Match:0x00000101218688
+      #             @mode = :dtmf,
+      #             @confidence = 1,
+      #             @utterance = "5678#",
+      #             @interpretation = "5678#"
+      #           >
+      #       >> matcher.match '1111#'
+      #       => #<RubySpeech::GRXML::Match:0x000001012f69d8
+      #             @mode = :dtmf,
+      #             @confidence = 1,
+      #             @utterance = "1111#",
+      #             @interpretation = "1111#"
+      #           >
+      #       >> matcher.match '111'
+      #       => #<RubySpeech::GRXML::NoMatch:0x00000101371660>
+      #       ```
+      #
+      def match(buffer)
+        find_match buffer.dup
+      end
+
+      private
+
+      def regexp_content
+        '^' + grammar.root_rule.children.map(&:regexp_content).join + '$'
+      end
+
+      def prepare_grammar
+        grammar.inline!
+        grammar.tokenize!
+        grammar.normalize_whitespace
+      end
+
+      def match_for_buffer(buffer, maximal = false)
+        match_class = maximal ? MaxMatch : Match
+        match_class.new mode:     grammar.mode,
+                  confidence:     grammar.dtmf? ? 1 : 0,
+                  utterance:      buffer,
+                  interpretation: interpret_utterance(buffer)
+      end
+
+      def interpret_utterance(utterance)
+        find_tag(utterance) || utterance.chars.inject([]) do |array, digit|
+          array << "dtmf-#{UTTERANCE_CONVERTER[digit]}"
+        end.join(' ')
+      end
+
+      def find_tag(utterance)
+        match = /#{regexp_content}/.match(utterance)
+        return if match.captures.all?(&:nil?)
+        last_capture_index = match.captures.size - 1 - match.captures.reverse.find_index { |item| !item.nil? }
+        match.names[last_capture_index]
+      end
+    end
+  end
+end

data/lib/ruby_speech/grxml/max_match.rb

@@ -0,0 +1,6 @@
+module RubySpeech
+  module GRXML
+    class MaxMatch < Match
+    end
+  end
+end

data/lib/ruby_speech/grxml/no_match.rb

@@ -0,0 +1,10 @@
+module RubySpeech
+  module GRXML
+    class NoMatch
+      def eql?(o)
+        o.is_a? self.class
+      end
+      alias :== :eql?
+    end
+  end
+end

data/lib/ruby_speech/grxml/one_of.rb

@@ -0,0 +1,31 @@
+module RubySpeech
+  module GRXML
+    ##
+    #
+    # The one-of element is one of the valid expansion elements for the SGR rule element
+    #
+    # http://www.w3.org/TR/speech-grammar/#S2.4 --> XML Form
+    #
+    # The one-of element has no attributes
+    #
+    # The one-of element identifies a set of alternative elements. Each alternative expansion is contained in a item element. There must be at least one item element contained within a one-of element.
+    #
+    # FIXME: Ensure an 'item' element is in the oneof block... this may be at the final draw or when OneOf is called...
+    #
+    class OneOf < Element
+
+      register :'one-of'
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, Item].freeze
+
+      def <<(arg)
+        raise InvalidChildError, "A OneOf can only accept Item as children" unless VALID_CHILD_TYPES.include? arg.class
+        super
+      end
+
+      def regexp_content # :nodoc:
+        "(#{children.map(&:regexp_content).join '|'})"
+      end
+    end # OneOf
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/potential_match.rb

@@ -0,0 +1,10 @@
+module RubySpeech
+  module GRXML
+    class PotentialMatch
+      def eql?(o)
+        o.is_a? self.class
+      end
+      alias :== :eql?
+    end
+  end
+end

data/lib/ruby_speech/grxml/rule.rb

@@ -0,0 +1,73 @@
+module RubySpeech
+  module GRXML
+    ##
+    #
+    # A rule definition associates a legal rule expansion with a rulename. The rule definition is also responsible for defining the scope of the rule definition: whether it is local to the grammar in which it is defined or whether it may be referenced within other grammars.
+    #
+    #   http://www.w3.org/TR/speech-grammar/#S3
+    #   http://www.w3.org/TR/speech-grammar/#S3.1
+    #
+    # The rule element has two attributes: id and scope. The id attribute is always required; the scope is optional.
+    #
+    # The id must be unique with-in the grammar document
+    #
+    # The scope is either "private" or "public".  If it is not explicitly declared in a rule definition then the scope defaults to "private".
+    #
+    #
+    class Rule < Element
+      include XML::Language
+
+      register :rule
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, String, OneOf, Item, Ruleref, Tag, Token].freeze
+
+      ##
+      #
+      # The id attribute is the unique name to identify the rule
+      #
+      #
+      # @return [String]
+      #
+      def id
+        read_attr :id, :to_sym
+      end
+
+      ##
+      # @param [String] ia
+      #
+      def id=(ia)
+        self[:id] = ia
+      end
+
+      ##
+      #
+      # The scope attribute is optional...
+      #
+      # @return [String]
+      #
+      def scope
+        read_attr :scope, :to_sym
+      end
+
+      ##
+      #
+      # The scope attribute should only be "private" or "public"
+      #
+      # @param [String] ia
+      #
+      def scope=(sc)
+        raise ArgumentError, "A Rule's scope can only be 'public' or 'private'" unless %w{public private}.include?(sc.to_s)
+        self[:scope] = sc
+      end
+
+      def <<(arg)
+        raise InvalidChildError, "A Rule can only accept OneOf, Item, Ruleref, Tag, or Token as children" unless VALID_CHILD_TYPES.include? arg.class
+        super
+      end
+
+      def eql?(o)
+        super o, :id, :scope, :language
+      end
+    end # Rule
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/ruleref.rb

@@ -0,0 +1,69 @@
+module RubySpeech
+  module GRXML
+    ##
+    #
+    # The ruleref element is an empty element which points to another rule expansion in the grammar document.
+    #
+    #   http://www.w3.org/TR/speech-grammar/#S2.2
+    #
+    # Every rule definition has a local name that must be unique within the scope of the grammar in which it is defined. A rulename must match the "Name" Production of XML 1.0 [XML §2.3] and be a legal XML ID. Section 3.1 documents the rule definition mechanism and the legal naming of rules.
+    #
+    # The ruleref has three attributes: uri, special and type. There can be one and only one of the uri or special attribute specified on any given ruleref element.
+    #
+    # The uri attribute contains named identified named rule being referenced
+    #
+    # optional 'type' attribute specifies the media type for the uri
+    #
+    class Ruleref < Element
+
+      register :ruleref
+
+      ##
+      # XML URI: in the XML Form of this specification any URI is provided as an attribute to an element; for example the ruleref and lexicon elements.
+      #
+      # @return [String]
+      #
+      def uri
+        read_attr :uri
+      end
+
+      ##
+      # @param [String]
+      #
+      # @raises ArgumentError if t is nota positive numeric value
+      #
+      def uri=(u)
+        raise ArgumentError, "A Ruleref can only take uri or special" if special
+        self[:uri] = u
+      end
+
+      ##
+      # special...
+      #
+      # @return [String]
+      #
+      def special
+        read_attr :special
+      end
+
+      ##
+      # @param [String]
+      #
+      # TODO: raise ArgumentError if not a valid special...
+      #
+      def special=(sp)
+        raise ArgumentError, "A Ruleref can only take uri or special" if uri
+        raise ArgumentError, "The Ruleref#special method only takes :NULL, :VOID, and :GARBAGE" unless %w{NULL VOID GARBAGE}.include? sp.to_s
+        self[:special] = sp
+      end
+
+      def <<(*args)
+        raise InvalidChildError, "A Ruleref cannot contain children"
+      end
+
+      def eql?(o)
+        super o, :uri, :special
+      end
+    end # Rule
+  end # GRXML
+end # RubySpeech