calyx 0.14.2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 129a9b8ddec5530b5f427780572e1e0a3a667bd4
-  data.tar.gz: 445ce73db118256bbf9ad748b82421235bb8573d
+  metadata.gz: ba09252aa5dedcc03c190a14c68be4eb446fc01c
+  data.tar.gz: cf7c1287f4dcfbc35682d74a1f83d3f7eeb8b2a4
 SHA512:
-  metadata.gz: 5b31b154440e67f0bde8ba9cd49784aece4ffa971a3b15731f83b05696f44e4db3fc43cdf78ffba990c962c46ac7d71c4964339133a43c202bd651a9066113bd
-  data.tar.gz: 3aded7ee2f7104244b0d47dc0a06a98607f32bdc05e17a1eabf153b1595cca60e17f708cbc2873eb09bb27b16ec6bb445980f23c3b679a76feb669ecb1bcd601
+  metadata.gz: 670da35d3148a5aaaba3eb81edd7ba9635f3667cc2c1f6288b64cf2f79cafbc2649f752799911e8156609887f9fa260a95bb29765e9342b23bf5ca4f1fa87bca
+  data.tar.gz: 013ab7c2761b8db39e3748fd80602cecbcefe547c1802ccf703a4e459f880d54c0104b502c0798bb9048bcee63e7cf380bf1e6f4d434a04c2bf422e72bfd4200

data/README.md

@@ -214,11 +214,22 @@ end
 By default, the outcomes of generated rules are selected with Ruby’s built-in pseudorandom number generator (as seen in methods like `Kernel.rand` and `Array.sample`). To seed the random number generator, pass in an integer seed value as the first argument to the constructor:
 
 ```ruby
-MyGrammar.new(12345)
-Calyx::Grammar.new(12345, &rules)
+grammar = Calyx::Grammar.new(seed: 12345) do
+  # rules...
+end
+```
+
+Alternatively, you can pass a preconfigured instance of Ruby’s stdlib `Random` class:
+
+```ruby
+random = Random.new(12345)
+
+grammar = Calyx::Grammar.new(rng: random) do
+  # rules...
+end
 ```
 
-When a seed value isn’t supplied, `Time.new.to_i` is used as the default seed, which makes each run of the generator relatively unique.
+When a random seed isn’t supplied, `Time.new.to_i` is used as the default seed, which makes each run of the generator relatively unique.
 
 ### Weighted Selection
 

data/lib/calyx.rb

@@ -1,4 +1,5 @@
 require 'calyx/version'
+require 'calyx/rule'
 require 'calyx/grammar'
 require 'calyx/errors'
 require 'calyx/format'

data/lib/calyx/errors.rb

@@ -9,10 +9,31 @@ module Calyx
     #   end
     #
     #   grammar.evaluate
-    #   # => Calyx::Errors::MissingRule: :blank is not registered
-    class MissingRule < RuntimeError
-      def initialize(msg)
-        super(":#{msg} is not registered")
+    #   # => Calyx::Errors::UndefinedRule: :blank is not defined
+    class UndefinedRule < RuntimeError
+      def initialize(rule, symbol)
+        @trace = if rule
+          rule.trace
+        else
+          trace_api_boundary(caller_locations)
+        end
+
+        super("undefined rule :#{symbol} in #{@trace.path}:#{@trace.lineno}:`#{source_line}`")
+      end
+
+      def trace_api_boundary(trace)
+        (trace.count - 1).downto(0) do |index|
+          if trace[index].to_s.include?('lib/calyx/')
+            return trace[index + 1]
+          end
+        end
+      end
+
+      def source_line
+        File.open(@trace.absolute_path) do |source|
+          (@trace.lineno-1).times { source.gets }
+          source.gets
+        end.strip
       end
     end
 

data/lib/calyx/format.rb

@@ -1,7 +1,63 @@
+require 'pathname'
+
 module Calyx
   # Helper methods for loading and initializing grammars from static files
   # on disk.
   module Format
+    class Trace
+      def initialize(match_symbol, filename, contents)
+        @match_symbol = match_symbol
+        @filename = Pathname.new(filename)
+        @contents = contents
+      end
+
+      def path
+        @filename.basename
+      end
+
+      def absolute_path
+        @filename.expand_path
+      end
+
+      def lineno
+        line_number = 0
+        @contents.each_line do |line|
+          line_number += 1
+          return line_number if line =~ @match_symbol
+        end
+      end
+    end
+
+    class JSONGrammar
+      def initialize(filename)
+        require 'json'
+        @filename = filename
+        @contents = File.read(@filename)
+        @rules = JSON.parse(@contents)
+      end
+
+      def each_rule(&block)
+        @rules.each do |rule, productions|
+          yield rule, productions, Trace.new(/("#{rule}")(\s*)(:)/, @filename, @contents)
+        end
+      end
+    end
+
+    class YAMLGrammar
+      def initialize(filename)
+        require 'yaml'
+        @filename = filename
+        @contents = File.read(@filename)
+        @rules = YAML.load(@contents)
+      end
+
+      def each_rule(&block)
+        @rules.each do |rule, productions|
+          yield rule, productions, Trace.new(/#{rule}:/, @filename, @contents)
+        end
+      end
+    end
+
     # Reads a file and parses its format, based on the given extension.
     #
     # Accepts a JSON or YAML file path, identified by its extension (`.json`
@@ -10,12 +66,12 @@ module Calyx
     # @param [String] filename
     # @return [Calyx::Grammar]
     def self.load(filename)
-      file = File.read(filename)
       extension = File.extname(filename)
+
       if extension == ".yml"
-        self.load_yml(file)
+        self.load_yml(filename)
       elsif extension == ".json"
-        self.load_json(file)
+        self.load_json(filename)
       else
         raise Errors::UnsupportedFormat.new(filename)
       end
@@ -23,28 +79,27 @@ module Calyx
 
     # Converts the given string of YAML data to a grammar instance.
     #
-    # @param [String] data
-    # @return [Calyx::Grammar]
-    def self.load_yml(data)
-      require 'yaml'
-      self.build_grammar(YAML.load(data))
+    # @param [String] filename
+    # @return [Calyx::Format::YAMLGrammar]
+    def self.load_yml(filename)
+      self.build_grammar(YAMLGrammar.new(filename))
     end
 
     # Converts the given string of JSON data to a grammar instance.
     #
-    # @param [String] data
-    # @return [Calyx::Grammar]
-    def self.load_json(data)
-      require 'json'
-      self.build_grammar(JSON.parse(data))
+    # @param [String] filename
+    # @return [Calyx::Format::JSONGrammar]
+    def self.load_json(filename)
+      self.build_grammar(JSONGrammar.new(filename))
     end
 
     private
 
-    def self.build_grammar(rules)
+    def self.build_grammar(grammar_format)
       Calyx::Grammar.new do
-        rules.each do |label, productions|
-          rule(label, *productions)
+        grammar_format.each_rule do |label, productions, trace|
+          productions = [productions] unless productions.is_a?(Enumerable)
+          define_rule(label, trace, productions)
         end
       end
     end

data/lib/calyx/grammar.rb

@@ -59,7 +59,7 @@ module Calyx
       # @param [Symbol] name
       # @param [Array] productions
       def rule(name, *productions)
-        registry.rule(name, *productions)
+        registry.define_rule(name, caller_locations.first, productions)
       end
 
       # Augument the grammar with a method missing hook that treats class
@@ -71,7 +71,7 @@ module Calyx
       # @param [Symbol] name
       # @param [Array] productions
       def method_missing(name, *productions)
-        registry.rule(name, *productions)
+        registry.define_rule(name, caller_locations.first, productions)
       end
 
       # Hook for combining the registry of a parent grammar into the child that
@@ -103,8 +103,16 @@ module Calyx
       unless options.is_a?(Hash)
         config_opts = {}
         if options.is_a?(Numeric)
+          warn [
+            "NOTE: Passing a numeric seed arg directly is deprecated. ",
+            "Use the options hash instead: `Calyx::Grammar.new(seed: 1234)`"
+          ].join
           config_opts[:seed] = options
         elsif options.is_a?(Random)
+          warn [
+            "NOTE: Passing a Random object directly is deprecated. ",
+            "Use the options hash instead: `Calyx::Grammar.new(rng: Random.new)`"
+          ].join
           config_opts[:rng] = options
         end
       else

data/lib/calyx/production/non_terminal.rb

@@ -18,12 +18,7 @@ module Calyx
       # @param [Random] random
       # @return [Array]
       def evaluate(random)
-        expansion = @registry.expand(@symbol)
-        if expansion.nil?
-          raise Errors::MissingRule.new(@symbol)
-        else
-          [@symbol, expansion.evaluate(random)]
-        end
+        [@symbol, @registry.expand(@symbol).evaluate(random)]
       end
     end
   end

data/lib/calyx/registry.rb

@@ -11,14 +11,6 @@ module Calyx
       @modifiers = Modifiers.new
     end
 
-    # Hook for defining rules without explicitly calling the `#rule` method.
-    #
-    # @param [Symbol] name
-    # @param [Array] productions
-    def method_missing(name, *arguments)
-      rule(name, *arguments)
-    end
-
     # Attaches a modifier module to this instance.
     #
     # @param [Module] module_name
@@ -46,19 +38,48 @@ module Calyx
       end
     end
 
+    # Registers a new grammar rule without explicitly calling the `#rule` method.
+    #
+    # @param [Symbol] name
+    # @param [Array] productions
+    def method_missing(name, *productions)
+      define_rule(name, caller_locations.first, productions)
+    end
+
     # Registers a new grammar rule.
     #
     # @param [Symbol] name
     # @param [Array] productions
     def rule(name, *productions)
-      rules[name.to_sym] = construct_rule(productions)
+      define_rule(name, caller_locations.first, productions)
     end
 
-    # Expands the given rule symbol to its production.
+    # Defines a static rule in the grammar.
+    #
+    # @param [Symbol] name
+    # @param [Array] productions
+    def define_rule(name, trace, productions)
+      rules[name.to_sym] = Rule.new(name.to_sym, construct_rule(productions), trace)
+    end
+
+    # Defines a rule in the temporary evaluation context.
+    #
+    # @param [Symbol] name
+    # @param [Array] productions
+    def define_context_rule(name, trace, productions)
+      productions = [productions] unless productions.is_a?(Enumerable)
+      context[name.to_sym] = Rule.new(name.to_sym, construct_rule(productions), trace)
+    end
+
+    # Expands the given symbol to its rule.
     #
     # @param [Symbol] symbol
+    # @return [Calyx::Rule]
     def expand(symbol)
-      rules[symbol] || context[symbol]
+      expansion = rules[symbol] || context[symbol]
+      raise Errors::UndefinedRule.new(@last_expansion, symbol) if expansion.nil?
+      @last_expansion = expansion
+      expansion
     end
 
     # Applies the given modifier function to the given value to transform it.
@@ -129,20 +150,10 @@ module Calyx
           raise Errors::DuplicateRule.new(key)
         end
 
-        context[key.to_sym] = if value.is_a?(Array)
-          Production::Choices.parse(value, self)
-        else
-          Production::Concat.parse(value.to_s, self)
-        end
+        define_context_rule(key, caller_locations.last, value)
       end
 
-      expansion = expand(start_symbol)
-
-      if expansion.respond_to?(:evaluate)
-        [start_symbol, expansion.evaluate(random)]
-      else
-        raise Errors::MissingRule.new(start_symbol)
-      end
+      [start_symbol, expand(start_symbol).evaluate(random)]
     end
 
     private

data/lib/calyx/rule.rb

@@ -0,0 +1,17 @@
+module Calyx
+  # Represents a named rule connected to a tree of productions that can be
+  # evaluated and a trace which represents where the rule was declared.
+  class Rule
+    attr_reader :name, :productions, :trace
+
+    def initialize(name, productions, trace)
+      @name = name.to_sym
+      @productions = productions
+      @trace = trace
+    end
+
+    def evaluate(random)
+      productions.evaluate(random)
+    end
+  end
+end

data/lib/calyx/version.rb

@@ -1,3 +1,3 @@
 module Calyx
-  VERSION = '0.14.2'.freeze
+  VERSION = '0.15.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calyx
 version: !ruby/object:Gem::Version
-  version: 0.14.2
+  version: 0.15.0
 platform: ruby
 authors:
 - Mark Rickerby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-21 00:00:00.000000000 Z
+date: 2017-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -85,6 +85,7 @@ files:
 - lib/calyx/production/unique.rb
 - lib/calyx/production/weighted_choices.rb
 - lib/calyx/registry.rb
+- lib/calyx/rule.rb
 - lib/calyx/version.rb
 homepage: https://github.com/maetl/calyx
 licenses: