grammaphone 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6fc51b323812f7278f9e51540cccbc1df3530c17da6abc75f9fb7c97065433d
-  data.tar.gz: 3e17ab606b44b15d37445d81a73102fb2122569ecc43839c40c25498f6ebd340
+  metadata.gz: e243f173f31ceddb840bd5e1c166f2f5aae6574e79f44bcc8edab86f397e6b6e
+  data.tar.gz: 2c3a92d6ecfcccf67b8f3330bceae184df8a64dc4b1a0f3765085f69d57abf51
 SHA512:
-  metadata.gz: b06c48105fd3b8b3682fe66fa1ec747d779100174724dd2b17de1c316e9b6dc81ff64aedebda0c9c97fa5654c7a7bf9767d4d07d9f15bd59f7d13e354d6f977f
-  data.tar.gz: 492dce702c1fa07ce1258c5ff62c32bfc8c8669ec224def19fba81eb8fc7ee69b83f7ca6d8b8518ab7b4d5e491538efbe32c224cea635f80f8d3008a0ad16aee
+  metadata.gz: 867e6191b314ea4a1c1bda97c053fc910ddb44fcea1d8dc24248307676277298066d40390741a48f8337a457283cf84baf92d4a67e03c30e5d90cb7fdbb964e2
+  data.tar.gz: 5fac8bfa0ec133c8fdc1e94cb9d673dd11a902487de46bb941262e33bdc6cd4475e15f4fa03947bf3a2a039eed01cef5c832f29131652a7af022ec7c12fd87d0

data/lib/grammaphone.rb

@@ -1,3 +1,7 @@
+require_relative "grammaphone/errors"
+require_relative "grammaphone/tokens"
+require_relative "grammaphone/rule"
+
 # Grammaphone is a dynamically-definable parser pseudo-generator based on a 
 # BNF-like grammar.
 #
@@ -60,18 +64,29 @@
 #
 # Note that to match a space, you need to use the pattern, since the splitting function 
 # for rules splits on the space character, regardless of where it is.
-
-require_relative "grammaphone/errors"
-require_relative "grammaphone/tokens"
-require_relative "grammaphone/rule"
-
 class Grammaphone
 
+  # Creates a TokenStream instance using `split_method` as the function to 
+  # split `src` into tokens. 
+  #
+  # `split_method` is expected to take a String and return an Array of Strings.
   def self.tokenize(src, &split_method)
     TokenStream.new(src, &split_method)
   end
 
-  # node_type must accept a 
+  # Creates a new instance of Grammaphone. 
+  #
+  # `rules` is a Hash containing the rules of the grammar, as defined above.
+  #
+  # `node_type` must be a class that responds to <<. By default, this is Array.
+  #
+  # `default_action` is the method called on the results of a rule being matched.
+  # This function is passed the results of the rule matching, which is an instance 
+  # of `node_type`, and the name of the rule matched. By default, this is the 
+  # identity function, returning the input node.
+  #
+  # The results of the action are included in the output instead of the input 
+  # instance of `node_type`.
   def initialize(rules = {}, node_type = Array, &default_action)
     raise ArgumentError.new("cannot form parser from a #{rules.class}") unless rules.kind_of? Hash
     raise ArgumentError.new("syntax tree type must respond to <<") unless node_type.method_defined?(:"<<")
@@ -82,6 +97,13 @@ class Grammaphone
     end
   end
 
+  # Adds a rule with a single rule to the grammar, using the associated action, 
+  # replacing existing the rule if there is a conflict.
+  #
+  # `action` is the method called on the results of the rule being matched.
+  # This function is passed the results of the rule matching, which is an instance 
+  # of `node_type`, and the name of the rule matched. By default, this is the 
+  # identity function, returning the input node.
   def add_rule(name, rule, &action)
     m = @rules.find {|r| r.name == name}
     action = @default_action if action.nil?
@@ -93,10 +115,20 @@ class Grammaphone
     end
   end
 
+  # Returns a Hash containint  a representation of existing rules. This does 
+  # not provide access to the underlying rules.
   def rules
     @rules.map{|r| [r.name, r.rule]}.to_h
   end
 
+  # Runs the grammar on the given token stream. If `token_stream` is not a 
+  # TokenStream instance, then a new TokenStream instance is created.
+  #
+  # The initial rule is the first rule added, either from the initial Hash or 
+  # the first call to `add_rule`.
+  #
+  # If the ruleset is empty when `parse` is called, an EmptyRulesetError is 
+  # raised.
   def parse(token_stream)
     token_stream = TokenStream.new(token_stream) unless token_stream.kind_of?(TokenStream)
     raise EmptyRulesetError if @rules.size == 0
@@ -104,6 +136,8 @@ class Grammaphone
     res
   end
 
+  # Runs the specified rule. Useful for testing purposes.
+  #
   # Not to be released in shipped version
   def test(name, token_stream)
     self.send(name, TokenStream.new(token_stream))

data/lib/grammaphone/tokens.rb

@@ -7,6 +7,17 @@ class Grammaphone
     # This doesn't need to be here, but it could potentially be useful
     include Enumerable
 
+    # Creates a new instance of TokenStream, using the data from `tokens`. If
+    # `tokens` is a String, it's split using `split_method`, which takes a 
+    # String and returns an Array. if `split_method` isn't provided, then 
+    # `String#split` is called on `tokens`, using the space character as the 
+    # separator.
+    #
+    # If `tokens` is an Array of Strings, the Array is duplicated, and used 
+    # directly.
+    #
+    # If `tokens` is not a String or Array, then `to_a` is called on `tokens` 
+    # and the result is used as the token stream.
     def initialize(tokens, &split_method)
       case tokens
       when String
@@ -16,6 +27,7 @@ class Grammaphone
           @enum = split_method.call(tokens).to_a
         end
       when Array
+        raise TokenStreamError unless tokens.all?{|t| t.kind_of?(String)}
         @enum = tokens.dup
       else
         raise TokenStreamError unless tokens.respond_to?(:to_a)
@@ -110,29 +122,50 @@ class Grammaphone
     end
   end
 
+  # Token contains methods that classify what kind of element type a specific 
+  # rule pattern is.
   module Token
+    # The prefix used to denote a literal element.
     LITERAL_PREFIX = "\""
 
+    # Checks if an element expects a literal value. A literal element is 
+    # denoted by being prefixed by the value of `LITERAL_PREFIX`.
     def self.literal?(token)
       token[0] == LITERAL_PREFIX
     end
 
+    # Removes the denotative marks of a literal, and returns the resulting value.
     def self.clean_literal(token)
       token[1..]
     end
 
+    # Returns whether the token is described by the element and that the 
+    # element is a literal.
+    #
+    # Returns `false` if the token is `nil`, since it's impossible to match a 
+    # literal `nil`. Note, `nil` differs from an empty token.
     def self.matches_literal?(element, token)
       !token.nil? && literal?(element) && token == clean_literal(element)
     end
 
+    # Checks if an element expects a pattern value. A pattern element is 
+    # denoted by being surrounded by forward slashes.
     def self.pattern?(token)
       token[0] == "/" && token[-1] == "/"
     end
 
+    # Removes the denotative marks of a pattern, and returns a Regexp that 
+    # matches the pattern exactly. That is, the pattern describes the 
+    # whole token, and nothing less.
     def self.clean_pattern(token)
       /\A#{token[1...-1]}\Z/
     end
 
+    # Returns whether the token is described by the element and that the 
+    # element is a pattern.
+    #
+    # Returns `false` if the token is `nil`, and the pattern doesn't match 
+    # the empty string.
     def self.matches_pattern?(element, token)
       pattern?(element) && (token =~ clean_pattern(element)) ||
         token.nil? && "" =~ clean_pattern(element)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: grammaphone
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kellen Watt
@@ -10,7 +10,7 @@ bindir: bin
 cert_chain: []
 date: 2020-09-15 00:00:00.000000000 Z
 dependencies: []
-description: A dynamic parser written in Ruby that uses a BNF-adjascent grammar.
+description: A dynamic RD parser written in Ruby that uses a BNF-adjacent grammar.
 email: kbw6d9@mst.edu
 executables: []
 extensions: []