jsgf 0.3 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a35679fd0c76d2953a7e6bf557f145e0fff63a63
-  data.tar.gz: 04a9e77a8561aa76bf73e4977933adfdec8f9f13
+  metadata.gz: 9e90d5a58e0adaadef490c11911c9443e14fb0a5
+  data.tar.gz: fd7deb3081c443f76c4505b72e1f18397d1ce183
 SHA512:
-  metadata.gz: 43fd8dc5e6757e7c9cc3753784e1fecda9cf4fda61049c54eeb45a0e4b48cf318d1f953ecd2b3b454be709f081ab6d61c885e73a03b24a8bcc1d7bba708563da
-  data.tar.gz: a5d9a59efb08497e731232b6554aaa9015cc8cb8fdc71b7444fdcad6c769789d34d42a2e23643edf9be9814da5dba0eca3c6b663f9e95edd8812139f3609ca6e
+  metadata.gz: 28d2d63a8f51d32efdcf597877e18ce86d45bded53077ef40e2908364af21fa23eb7b1f90262630738c866dd1df79d0a193bea81e04cb9619685bfbe9541645a
+  data.tar.gz: 132cefa593326e8b2d7c603746c8e114a1872de5bb566a5fa1fe8ec76ff5127492a8e28e9fa6f686ba4d1641071732399459bb976cb4a27c2b10592306a98d28

data/README.md

@@ -9,12 +9,48 @@ For all of your [Java Speech Grammar Format](http://www.w3.org/TR/jsgf/) parsing
 Usage
 -----
 
+Reading an existing JSGF file is as simple as...
+
 ```ruby
 require 'jsgf'
 
 grammar = JSGF.read('example.gram')
 ```
 
+Writing to a file is similarly simple.
+
+```ruby
+grammar.write('my_grammar.gram')
+```
+
+You can also write to an IO stream.
+
+```ruby
+File.open('my_grammar.gram', 'w') do |f|
+    grammar.write(f)
+end
+```
+
+### Grammar DSL
+
+The JSGF gem includes a simple DSL for generating new grammars. The syntax follows the
+the [JSGF](http://www.w3.org/TR/jsgf/) syntax, but with a few differences.
+
+- Rule names can be either Symbols or Strings (they're converted to Strings internally)
+- Rules can be referenced using symbols in addition to the angle-bracket syntax used by JSGF.
+- Alternations are created using arrays
+- Rules are private by default, however the root rules are automatically made public
+
+```ruby
+grammar = JSGF.grammar 'Turtle' do
+    rule quit: 'quit'                       # 'quit' and 'move' are public because
+    rule move: 'go :direction :distance'    #   they are the roots of the grammar tree
+
+    rule direction: %w{forward backward}
+    rule distance: %w{one two three four five six seven eight nine ten}
+end
+```
+
 Installation
 ------------
 

data/jsgf.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
     spec.name          = "jsgf"
-    spec.version       = '0.3'
+    spec.version       = '0.4'
     spec.authors       = ["Brandon Fosdick"]
     spec.email         = ["bfoz@bfoz.net"]
     spec.summary       = %q{Java Speech Grammar Format}

data/lib/jsgf.rb

@@ -1,3 +1,4 @@
+require_relative 'jsgf/builder'
 require_relative 'jsgf/parser'
 require_relative 'jsgf/tokenizer'
 
@@ -5,8 +6,11 @@ require_relative 'jsgf/tokenizer'
 A parser for JSGF files.
 
 http://www.w3.org/TR/jsgf/
+http://en.wikipedia.org/wiki/JSGF
 
-# Usage
+http://en.wikipedia.org/wiki/JSGF
+
+@example
     grammar = JSGF.read(filename)
 =end
 module JSGF
@@ -16,4 +20,9 @@ module JSGF
 	tokenzier = JSGF::Tokenizer.new(File.read(filename))
 	JSGF::Parser.new(tokenzier).parse
     end
+
+    # @return [Grammar] a new {Grammar} built from the block argument
+    def self.grammar(name=nil, &block)
+	Builder.build(name, &block)
+    end
 end

data/lib/jsgf/alternation.rb

@@ -7,7 +7,20 @@ module JSGF
 	attr_reader :tags
 
 	def initialize(*args)
-	    @elements = args
+	    @elements = args.map do |a|
+		case a
+		    when String
+			case a
+			    when /\<(.*)\>/, /:(.*)/ then {name:$1, weight:1.0, tags:[]}
+			    else
+				{atom:a, weight:1.0, tags:[]}
+			end
+		    when Symbol then {name:a.to_s, weight:1.0, tags:[]}
+		    else
+			a
+		end
+	    end
+
 	    @optional = false
 	    @tags = []
 	end

data/lib/jsgf/builder.rb

@@ -0,0 +1,54 @@
+require_relative 'alternation'
+require_relative 'grammar'
+
+module JSGF
+    class Builder
+	def initialize
+	    @rules = {}
+	end
+
+	# Convenience method for instantiating a builder and then building a {Grammar}
+	# @param name [String]	the name of the new {Grammar}
+	# @return [Grammar] a new {Grammar} built from the block argument
+	def self.build(name=nil, &block)
+	    self.new.build(name, &block)
+	end
+
+	# @param name [String]	the name of the new {Grammar}
+	# @return [Grammar] a new {Grammar} built from the block argument
+	def build(name=nil, &block)
+	    @name = name || 'DSL'
+	    instance_eval(&block) if block_given?
+	    Grammar.new(name:@name, rules:@rules)
+	end
+
+	# Set the name attribute from the DSL block
+	def name(arg)
+	    @name = arg
+	end
+
+	# Create a new rule using the provided name and string
+	#   By default, all new rules are private, unless they're root rules
+	# @example
+	#   rule rule1: 'This is a rule'
+	#   rule rule2: ['one', 'two']
+	#   rule rule3: 'This is not :rule2'
+	# @return [JSGF::Grammar]
+	def rule(**options)
+	    options.each do |name, v|
+		@rules[name.to_s] = case v
+		    when Array	then [Alternation.new(*v)]
+		    when Symbol	then [{name:v.to_s, weight:1.0, tags:[]}]
+		    else
+			v.split(' ').map do |a|
+			    case a
+				when /\<(.*)\>/, /:(.*)/ then {name:$1, weight:1.0, tags:[]}
+				else
+				    {atom:a, weight:1.0, tags:[]}
+			    end
+			end
+		end
+	    end
+	end
+    end
+end

data/lib/jsgf/grammar.rb

@@ -1,3 +1,5 @@
+require_relative 'optional'
+
 module JSGF
     class Grammar
 	attr_reader :character_encoding
@@ -7,26 +9,50 @@ module JSGF
 	attr_reader :public_rules
 	attr_reader :version
 
-	def initialize(name:nil, character_encoding:nil, locale:nil, private_rules:{}, public_rules:{}, version:nil)
+	# @param rules	[Hash]	the rules to search
+	# @return [Array<Hash,Hash>]	the set of root and non-root rules from the given set of rules
+	def self.roots(rules)
+	    # Descend through the rule trees to see if they reference each other.
+	    #  Root rules aren't referenced by any other rule.
+	    names = rules.flat_map {|(name,rule)| find_rule_names(rule)}.compact.uniq
+	    left, right = rules.partition {|name, rule| names.include?(name) }
+	    [Hash[right], Hash[left]]
+	end
+
+	# Expand the given rule and collect any references to other rules
+	# @param rule	[Array]	the right-hand-side of the rule to expand
+	# @return [Array]   an array of referenced rule names
+	def self.find_rule_names(rule)
+	    case rule
+		when Alternation, Array, Optional
+		    rule.flat_map {|a| find_rule_names(a) }
+		when Hash
+		    rule[:name]
+		else
+		    raise StandardError, "Unkown atom #{rule.class}"
+	    end
+	end
+
+	def initialize(name:nil, character_encoding:nil, locale:nil, private_rules:{}, public_rules:{}, rules:nil, version:nil)
 	    raise ArgumentError, "Grammar requires a name" unless name
 	    @character_encoding = character_encoding
 	    @locale = locale
 	    @grammar_name = name
-	    @private_rules = private_rules
-	    @public_rules = public_rules
 	    @version = version
+
+	    if rules and !rules.empty?
+		@public_rules, @private_rules = ::JSGF::Grammar.roots(rules)
+	    else
+		@private_rules = private_rules
+		@public_rules = public_rules
+	    end
 	end
 
 	# @!attribute roots
 	#   @return [Hash]  the set of public rules that comprise the roots of the {Grammar} tree
 	def roots
-	    # Descend through the public rule trees to see if they reference each other
-	    root_rules = public_rules.dup
-	    public_rules.each do |(name, rule)|
-		names = find_rule_names(rule).compact
-		root_rules.delete_if {|k,v| names.include?(k)}
-	    end
-	    root_rules.empty? ? nil : root_rules
+	    r = self.class.roots(public_rules).first
+	    r.empty? ? nil : r
 	end
 
 	# @!attribute rules
@@ -54,21 +80,18 @@ module JSGF
 	    [header, grammar_header, *public_rule_array, *private_rule_array].join("\n")
 	end
 
-    private
-	# Expand the given rule and collect any references to other rules
-	# @param rule	[Array]	the right-hand-side of the rule to expand
-	# @return [Array]   an array of referenced rule names
-	def find_rule_names(rule)
-	    case rule
-		when Alternation, Array, Optional
-		    rule.flat_map {|a| find_rule_names(a) }
-		when Hash
-		    rule[:name]
-		else
-		    raise StandardError, "Unkown atom #{rule.class}"
+	# Write the {Grammar} to a file or an {IO} stream
+	# @param file	[String,IO] a filename, or an IO stream, to write to
+	def write(file)
+	    if file.is_a?(String)
+		File.write(file, self.to_s)
+	    else
+		file.write(self.to_s)
 	    end
 	end
 
+    private
+
 	# Generate the grammar name header line
 	def grammar_header
 	    "grammar #{grammar_name};"

data/lib/jsgf/tokenizer.rb

@@ -12,7 +12,7 @@ module JSGF
 	    %r{/\d*(\.\d+)?/}			=> :WEIGHT,
 	}
 
-	# @param io [IO]    the {IO} stream to read from
+	# @param io [IO]    the {::IO} stream to read from
 	def initialize(io)
 	    io = io.read unless io.is_a?(String)
 	    @scanner = StringScanner.new(io)

data/test/jsgf/alternation.rb

@@ -2,6 +2,11 @@ require 'minitest/autorun'
 require 'jsgf/parser'
 
 describe JSGF::Alternation do
+    it 'must convert string arguments into atoms' do
+	alternation = JSGF::Alternation.new('one', 'two', 'three')
+	alternation.elements.must_equal [{atom:'one', weight:1.0, tags:[]}, {atom:'two', weight:1.0, tags:[]}, {atom:'three', weight:1.0, tags:[]}]
+    end
+
     it 'must be enumerable' do
 	alternation = JSGF::Alternation.new('one', 'two', 'three')
 	alternation.all? {|a| a}

data/test/jsgf/builder.rb

@@ -0,0 +1,108 @@
+require 'minitest/autorun'
+require 'jsgf/builder'
+
+describe JSGF::Builder do
+    it 'must set the name from inside the block' do
+	grammar = JSGF::Builder.build do
+	    name 'MyName'
+	end
+	grammar.grammar_name.must_equal 'MyName'
+    end
+
+    it 'must set the name from an argument' do
+	grammar = JSGF::Builder.build 'MyName'
+	grammar.grammar_name.must_equal 'MyName'
+    end
+
+    it 'must build a single-atom rule' do
+	grammar = JSGF::Builder.new.build do
+	    rule rule1: 'one'
+	end
+
+	grammar.rules.size.must_equal 1
+	grammar.rules['rule1'].must_equal [{atom:'one', weight:1.0, tags:[]}]
+    end
+
+    it 'must build a multi-atom rule' do
+	grammar = JSGF::Builder.build {rule rule1: 'one two' }
+	grammar.rules.size.must_equal 1
+	grammar.rules['rule1'].must_equal [{atom:'one', weight:1.0, tags:[]}, {atom:'two', weight:1.0, tags:[]}]
+    end
+
+    it 'must build a rule with a rule reference as a Symbol' do
+	grammar = JSGF::Builder.build do
+	    rule rule1: :one
+	    rule one: 'one'
+	end
+
+	grammar.rules.size.must_equal 2
+	grammar.rules['rule1'].must_equal [{name:'one', weight:1.0, tags:[]}]
+    end
+
+    it 'must build a rule with a JSGF-style rule reference embedded in a string' do
+	grammar = JSGF::Builder.build do
+	    rule rule1: '<one>'
+	    rule one: 'one'
+	end
+
+	grammar.rules.size.must_equal 2
+	grammar.rules['rule1'].must_equal [{name:'one', weight:1.0, tags:[]}]
+    end
+
+    it 'must build a rule with a rule reference symbol embedded in a string' do
+	grammar = JSGF::Builder.build do
+	    rule rule1: ':one'
+	    rule one: 'one'
+	end
+
+	grammar.rules.size.must_equal 2
+	grammar.rules['rule1'].must_equal [{name:'one', weight:1.0, tags:[]}]
+    end
+
+    describe 'alternation' do
+	it 'must build an alternation from an array of atoms' do
+	    grammar = JSGF::Builder.build do
+		rule rule1: %w{one two}
+	    end
+	    grammar.rules.size.must_equal 1
+	    grammar.rules['rule1'].first.must_be_kind_of JSGF::Alternation
+	    grammar.rules['rule1'].first.elements.must_equal [{atom:'one', weight:1.0, tags:[]}, {atom:'two', weight:1.0, tags:[]}]
+	end
+
+	it 'must build an alternation from an array of rule reference symbols' do
+	    grammar = JSGF::Builder.build do
+		rule rule1: [:one, :two]
+		rule one: 'one'
+		rule two: 'two'
+	    end
+
+	    grammar.rules.size.must_equal 3
+	    grammar.rules['rule1'].first.must_be_kind_of JSGF::Alternation
+	    grammar.rules['rule1'].first.elements.must_equal [{name:'one', weight:1.0, tags:[]}, {name:'two', weight:1.0, tags:[]}]
+	end
+
+	it 'must build an alternation from an array of strings containing embedded rule reference symbols' do
+	    grammar = JSGF::Builder.build do
+		rule rule1: %w[:one :two]
+		rule one: 'one'
+		rule two: 'two'
+	    end
+
+	    grammar.rules.size.must_equal 3
+	    grammar.rules['rule1'].first.must_be_kind_of JSGF::Alternation
+	    grammar.rules['rule1'].first.elements.must_equal [{name:'one', weight:1.0, tags:[]}, {name:'two', weight:1.0, tags:[]}]
+	end
+
+	it 'must build an alternation from an array of strings containing embedded JSGF-style rule reference names' do
+	    grammar = JSGF::Builder.build do
+		rule rule1: %w[<one> <two>]
+		rule one: 'one'
+		rule two: 'two'
+	    end
+
+	    grammar.rules.size.must_equal 3
+	    grammar.rules['rule1'].first.must_be_kind_of JSGF::Alternation
+	    grammar.rules['rule1'].first.elements.must_equal [{name:'one', weight:1.0, tags:[]}, {name:'two', weight:1.0, tags:[]}]
+	end
+    end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsgf
 version: !ruby/object:Gem::Version
-  version: '0.3'
+  version: '0.4'
 platform: ruby
 authors:
 - Brandon Fosdick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-26 00:00:00.000000000 Z
+date: 2015-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,12 +53,14 @@ files:
 - jsgf.gemspec
 - lib/jsgf.rb
 - lib/jsgf/alternation.rb
+- lib/jsgf/builder.rb
 - lib/jsgf/grammar.rb
 - lib/jsgf/optional.rb
 - lib/jsgf/parser.rb
 - lib/jsgf/repetition.rb
 - lib/jsgf/tokenizer.rb
 - test/jsgf/alternation.rb
+- test/jsgf/builder.rb
 - test/jsgf/grammar.rb
 - test/jsgf/optional.rb
 - test/jsgf/parser.rb
@@ -83,12 +85,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Java Speech Grammar Format
 test_files:
 - test/jsgf/alternation.rb
+- test/jsgf/builder.rb
 - test/jsgf/grammar.rb
 - test/jsgf/optional.rb
 - test/jsgf/parser.rb