calyx 0.16.1 → 0.17.0

data/docs/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "calyx-docs",
+  "version": "1.0.0",
+  "main": "index.html",
+  "scripts": {
+    "build": "node-sass --include-path node_modules/bulma calyx-docs.scss assets/calyx-docs.css",
+    "help": "node-sass --help"
+  },
+  "author": "Mark Rickerby <me@maetl.net>",
+  "license": "MIT",
+  "devDependencies": {
+    "bulma": "^0.5.2",
+    "node-sass": "^4.5.3"
+  }
+}

data/lib/calyx.rb

@@ -1,6 +1,8 @@
+require 'rubygems/deprecate'
 require 'calyx/version'
 require 'calyx/options'
 require 'calyx/rule'
+require 'calyx/result'
 require 'calyx/grammar'
 require 'calyx/errors'
 require 'calyx/format'

data/lib/calyx/grammar.rb

@@ -138,23 +138,35 @@ module Calyx
     #   @param [Hash] rules_map
     # @return [String]
     def generate(*args)
-      start_symbol, rules_map = map_default_args(*args)
-
-      @registry.evaluate(start_symbol, rules_map).flatten.reject do |obj|
-        obj.is_a?(Symbol)
-      end.join
+      result = generate_result(*args)
+      result.text
     end
 
     # Produces a syntax tree of nested list nodes as an output of the grammar.
     #
+    # @deprecated Please use {#generate_result} instead.
+    def evaluate(*args)
+      warn <<~DEPRECATION
+        [DEPRECATION] `evaluate` is deprecated and will be removed in 1.0.
+        Please use #generate_result instead.
+        See https://github.com/maetl/calyx/issues/23 for more details.
+      DEPRECATION
+
+      result = generate_result(*args)
+      result.tree
+    end
+
+    # Produces a generated result from evaluating the grammar.
+    #
+    # @see Calyx::Result
     # @overload
     #   @param [Symbol] start_symbol
     #   @param [Hash] rules_map
-    # @return [Array]
-    def evaluate(*args)
+    # @return [Calyx::Result]
+    def generate_result(*args)
       start_symbol, rules_map = map_default_args(*args)
 
-      @registry.evaluate(start_symbol, rules_map)
+      Result.new(@registry.evaluate(start_symbol, rules_map))
     end
 
     private

data/lib/calyx/options.rb

@@ -1,13 +1,25 @@
 module Calyx
+  # Provides access to configuration options while evaluating a grammar.
   class Options
+    # These options are used by default if not explicitly provided during
+    # initialization of the grammar.
     DEFAULTS = {
       strict: true
     }
 
-    def initialize(opts={})
-      @options = DEFAULTS.merge(opts)
+    # Constructs a new options instance, merging the passed in options with the
+    # defaults.
+    #
+    # @params [Hash, Calyx::Options] options
+    def initialize(options={})
+      @options = DEFAULTS.merge(options)
     end
 
+    # Returns the internal random number generator instance. If a seed or random
+    # instance is not passed-in directly, a new instance of `Random` is
+    # initialized by default.
+    #
+    # @return [Random]
     def rng
       unless @options[:rng]
         @options[:rng] = if @options[:seed]
@@ -20,20 +32,39 @@ module Calyx
       @options[:rng]
     end
 
+    # Returns the next pseudo-random number in the sequence defined by the
+    # internal random number generator state.
+    #
+    # The value returned is a floating point number between 0.0 and 1.0,
+    # including 0.0 and excluding 1.0.
+    #
+    # @return [Float]
     def rand
       rng.rand
     end
 
+    # True if the strict mode option is enabled. This option defines whether or
+    # not to raise an error on missing rules. When set to false, missing rules
+    # are skipped over when the production is concatenated.
+    #
+    # @return [TrueClass, FalseClass]
     def strict?
       @options[:strict]
     end
 
-    def merge(opts)
-      Options.new(@options.merge(opts.to_h))
+    # Merges two instances together and returns a new instance.
+    #
+    # @params [Calyx::Options]
+    # @return [Calyx::Options]
+    def merge(options)
+      Options.new(@options.merge(options.to_h))
     end
 
+    # Serializes instance data to a hash.
+    #
+    # @return [Hash]
     def to_h
-      @options
+      @options.dup
     end
   end
 end

data/lib/calyx/result.rb

@@ -0,0 +1,38 @@
+module Calyx
+  # Value object representing a generated grammar result.
+  class Result
+    def initialize(expression)
+      @expression = expression.freeze
+    end
+
+    # The syntax tree of nested nodes representing the production rules which
+    # generated this result.
+    #
+    # @return [Array]
+    def tree
+      @expression
+    end
+
+    alias_method :to_exp, :tree
+
+    # The generated text string produced by the grammar.
+    #
+    # @return [String]
+    def text
+      @expression.flatten.reject do |obj|
+        obj.is_a?(Symbol)
+      end.join
+    end
+
+    alias_method :to_s, :text
+
+    # A symbol produced by converting the generated text string where possible.
+    #
+    # @return [Symbol]
+    def symbol
+      text.to_sym
+    end
+
+    alias_method :to_sym, :symbol
+  end
+end

data/lib/calyx/version.rb

@@ -1,3 +1,3 @@
 module Calyx
-  VERSION = '0.16.1'.freeze
+  VERSION = '0.17.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: calyx
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.17.0
 platform: ruby
 authors:
 - Mark Rickerby
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-02 00:00:00.000000000 Z
+date: 2017-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -68,6 +68,17 @@ files:
 - README.md
 - SYNTAX.md
 - calyx.gemspec
+- docs/404.html
+- docs/CNAME
+- docs/_config.yml
+- docs/_layouts/default.html
+- docs/_posts/2017-09-14-welcome-to-jekyll.markdown
+- docs/about.md
+- docs/assets/calyx-docs.css
+- docs/calyx-docs.scss
+- docs/index.html
+- docs/package-lock.json
+- docs/package.json
 - examples/any_gradient.rb
 - examples/faker.rb
 - examples/faker.yml
@@ -87,6 +98,7 @@ files:
 - lib/calyx/production/unique.rb
 - lib/calyx/production/weighted_choices.rb
 - lib/calyx/registry.rb
+- lib/calyx/result.rb
 - lib/calyx/rule.rb
 - lib/calyx/version.rb
 homepage: https://github.com/maetl/calyx