ruby_speech 0.2.2 → 0.3.0

data/lib/ruby_speech/grxml/grammar.rb

@@ -0,0 +1,126 @@
+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
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, Rule, Tag].freeze
+
+      ##
+      # Create a new GRXML grammar root element
+      #
+      # @param [Hash] atts Key-value pairs of options mapping to setter methods
+      #
+      # @return [Grammar] an element for use in an GRXML document
+      #
+      def self.new(atts = {}, &block)
+        new_node = super('grammar', atts)
+        new_node[:version] = '1.0'
+        new_node.namespace = GRXML_NAMESPACE
+        new_node.language ||= "en-US"
+        new_node.instance_eval &block if block_given?
+        new_node
+      end
+
+      ##
+      # @return [String] the base URI to which relative URLs are resolved
+      #
+      def base_uri
+        read_attr :base
+      end
+
+      ##
+      # @param [String] uri the base URI to which relative URLs are resolved
+      #
+      def base_uri=(uri)
+        write_attr 'xml:base', uri
+      end
+
+      ##
+      #
+      # 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
+      end
+
+      ##
+      # @param [String] ia
+      #
+      def mode=(ia)
+        write_attr :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)
+        write_attr :root, ia
+      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 to_doc
+        Nokogiri::XML::Document.new.tap do |doc|
+          doc << self
+        end
+      end
+
+      ##
+      #
+      # @return [String]
+      #
+      def tag_format
+        read_attr :'tag-format'
+      end
+
+      ##
+      # @param [String] ia
+      #
+      def tag_format=(s)
+        write_attr :'tag-format', s
+      end
+
+      def +(other)
+        self.class.new(:base_uri => base_uri).tap do |new_grammar|
+          (self.children + other.children).each do |child|
+            new_grammar << child
+          end
+        end
+      end
+
+      def eql?(o)
+        super o, :language, :base_uri, :mode, :root
+      end
+    end # Grammar
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/item.rb

@@ -0,0 +1,135 @@
+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
+
+      register :item
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, OneOf, Item, String, Ruleref, Tag, Token].freeze
+
+      ##
+      # Create a new GRXML item element
+      #
+      # @param [Hash] atts Key-value pairs of options mapping to setter methods
+      #
+      # @return [Item] an element for use in an GRXML document
+      #
+      def self.new(atts = {}, &block)
+        super 'item', atts, &block
+      end
+
+      ##
+      #
+      # 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
+        write_attr :weight, w
+      end
+
+      ##
+      #
+      # The repeat attribute
+      #
+      # @return [String]
+      #
+      def repeat
+        read_attr :repeat
+      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.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
+        write_attr :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
+        write_attr :'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, :language
+      end
+    end # Item
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/one_of.rb

@@ -0,0 +1,42 @@
+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
+
+      ##
+      # Create a new GRXML one-of element
+      #
+      # @param [Hash] atts Key-value pairs of options mapping to setter methods
+      #
+      # @return [OneOf] an element for use in an GRXML document
+      #
+      def self.new(atts = {}, &block)
+        super 'one-of', atts, &block
+      end
+
+      def <<(arg)
+        raise InvalidChildError, "A OneOf can only accept Item as children" unless VALID_CHILD_TYPES.include? arg.class
+        super
+      end
+
+      def eql?(o)
+        super o, :language
+      end
+    end # OneOf
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/rule.rb

@@ -0,0 +1,84 @@
+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
+
+      ##
+      # Create a new GRXML rule element
+      #
+      # @param [Hash] atts Key-value pairs of options mapping to setter methods
+      #
+      # @return [Rule] an element for use in an GRXML document
+      #
+      def self.new(atts = {}, &block)
+        super 'rule', atts, &block
+      end
+
+      ##
+      #
+      # 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)
+        write_attr :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)
+        write_attr :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,80 @@
+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
+
+      ##
+      # Create a new GRXML ruleref element
+      #
+      # @param [Hash] atts Key-value pairs of options mapping to setter methods
+      #
+      # @return [Ruleref] an element for use in an GRXML document
+      #
+      def self.new(atts = {}, &block)
+        super 'ruleref', atts, &block
+      end
+
+      ##
+      # 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
+        write_attr :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
+        write_attr :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

data/lib/ruby_speech/grxml/tag.rb

@@ -0,0 +1,36 @@
+module RubySpeech
+  module GRXML
+    ##
+    #
+    # The tag element is one of the valid expansion elements for the SGR rule element
+    #
+    #   http://www.w3.org/TR/speech-grammar/#S2.6
+    #
+    #
+    # TODO: Make sure this is complete...
+    #
+    #
+    class Tag < Element
+
+      register :tag
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, String].freeze
+
+      ##
+      # Create a new GRXML tag element
+      #
+      # @param [Hash] atts Key-value pairs of options mapping to setter methods
+      #
+      # @return [Tag] an element for use in an GRXML document
+      #
+      def self.new(atts = {}, &block)
+        super 'tag', atts, &block
+      end
+
+      def <<(arg)
+        raise InvalidChildError, "A Tag can only accept Strings as children" unless VALID_CHILD_TYPES.include? arg.class
+        super
+      end
+    end # Tag
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml/token.rb

@@ -0,0 +1,38 @@
+module RubySpeech
+  module GRXML
+    ##
+    #
+    # A token (a.k.a. a terminal symbol) is the part of a grammar that defines words or other entities that may be spoken. Any legal token is a legal expansion.
+    #
+    #   http://www.w3.org/TR/speech-grammar/#S2.1
+    #
+    #  The token element may include an optional xml:lang attribute to indicate the language of the contained token.
+    #
+    class Token < Element
+
+      register :token
+
+      VALID_CHILD_TYPES = [Nokogiri::XML::Element, Nokogiri::XML::Text, String].freeze
+
+      ##
+      # Create a new GRXML token element
+      #
+      # @param [Hash] atts Key-value pairs of options mapping to setter methods
+      #
+      # @return [Token] an element for use in an GRXML document
+      #
+      def self.new(atts = {}, &block)
+        super 'token', atts, &block
+      end
+
+      def <<(arg)
+        raise InvalidChildError, "A Token can only accept Strings as children" unless VALID_CHILD_TYPES.include? arg.class
+        super
+      end
+
+      def eql?(o)
+        super o, :language
+      end
+    end # Token
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/grxml.rb

@@ -0,0 +1,25 @@
+module RubySpeech
+  module GRXML
+    extend ActiveSupport::Autoload
+
+    autoload :Element
+    autoload :Grammar
+    autoload :Rule
+    autoload :Item
+    autoload :OneOf
+    autoload :Ruleref
+    autoload :Tag
+    autoload :Token
+
+    InvalidChildError = Class.new StandardError
+
+    GRXML_NAMESPACE = 'http://www.w3.org/2001/06/grammar'
+
+    def self.draw(attributes = {}, &block)
+      Grammar.new(attributes).tap do |grammar|
+        block_return = grammar.instance_eval(&block) if block_given?
+        grammar << block_return if block_return.is_a?(String)
+      end
+    end
+  end # GRXML
+end # RubySpeech

data/lib/ruby_speech/ssml/element.rb

@@ -1,11 +1,11 @@
-require 'active_support/core_ext/class/inheritable_attributes'
+require 'active_support/core_ext/class/attribute'
 
 module RubySpeech
   module SSML
     class Element < Niceogiri::XML::Node
       @@registrations = {}
 
-      class_inheritable_accessor :registered_ns, :registered_name
+      class_attribute :registered_ns, :registered_name
 
       # Register a new stanza class to a name and/or namespace
       #

data/lib/ruby_speech/version.rb

@@ -1,3 +1,3 @@
 module RubySpeech
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/ruby_speech.rb

@@ -11,5 +11,6 @@ module RubySpeech
   autoload :Version
 
   autoload :SSML
+  autoload :GRXML
   autoload :XML
 end