loxxy 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f8733558204a56db1177c9c25e5fae5af1676c455b1e3a2f3145a70fae741a7
-  data.tar.gz: ac99f27c25e52703adea30eca1db61671a275355a4a3a00657f2f0359e7fe57f
+  metadata.gz: f5383d6eb1725f5c53bb343e46d763f18d9d69f6b010241dbc4a93c18f949a6f
+  data.tar.gz: 286f213ab01ebec8061a9f25c86c6f28be064891880e06942a0d6d86b4210fcb
 SHA512:
-  metadata.gz: beb8fa74fab5d2799ac982a2585a4ba8ebce992ae2b9a98d9356fe9e0afdd8d2b08d371bd9a6940e7b8761710f876c5494697a47ba1b4a047d7a38babb0d1695
-  data.tar.gz: 64df1b2c919c47f8852bc2885e7dc2eac5bd55b5892f2f6477e56401a9e2d1cf01080c512d2592d07472ef8ff053ba26ac0b5c29278e9aefa57cea9f639c33ba
+  metadata.gz: 32d447c7dbe6593ad0002ad383a917561c82da22cbf70b4102d0eaa389cf92196e03ee14ab1cc160f530b1c96a1e259db8e7923e2de81322fc854898fa306d49
+  data.tar.gz: 245d4c9e255b7bb9d8602ab103367d7f83baf516db61f5a9192945ffa689027eb9f5f7a282e7052bca6b9e904cd6f6ed956d61ea949e02b7916f100033ebd9ec

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.0.4] - 2021-01-01
+- A first parser implementation able to parse Lox source code.
+
+## Added
+- Method `LXString::==` equality operator.
+
+## Changed
+- class `Parser` renamed to `RawParser`
+- File `README.md` Added an example showing the use of `RawParser` class.
+
 ## [0.0.3] - 2020-12-29
 - Scanner can recognize strings and nil tokens
 ### Added

data/README.md

@@ -11,11 +11,37 @@ a simple language used in Bob Nystrom's online book [Crafting Interpreters](http
 
 ## Roadmap
 - [DONE] Scanner (tokenizer)
-- [STARTED] Recognizer
-- [TODO] Parser
+- [DONE] Raw parser. It parses Lox programs and generates a parse tree.
+- [TODO] Tailored parser for generating AST (Abstract Syntax Tree)
 - [TODO] Interpreter or transpiler
 
 
+## Example
+At this, stage, the raw parser is able to recognize Lox input and to generate
+a concrete parse tree from it.
+
+```ruby
+require 'loxxy'
+
+lox_input = <<-LOX_END
+  // Your first Lox program!
+  print "Hello, world!";
+LOX_END
+
+# Show that the raw parser accepts the above program
+base_parser = Loxxy::FrontEnd::RawParser.new
+
+# Now parse the input into a concrete parse tree...
+ptree = base_parser.parse(lox_input)
+
+# Dump the parse tree contents...
+p ptree # Lengthy (unwieldy) output
+```
+
+Soon, the `loxxy`will host another, tailored parser, that will generate
+abstract syntax tree which much more convenient for further processing 
+(like implementing an interpreter).
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/lib/loxxy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative './loxxy/version'
+require_relative 'loxxy/version'
+require_relative 'loxxy/front_end/raw_parser'
 
 module Loxxy
   class Error < StandardError; end

data/lib/loxxy/datatype/lx_string.rb

@@ -12,6 +12,20 @@ module Loxxy
         super(aValue)
       end
 
+      # Compare a Lox String with another Lox (or genuine Ruby) String
+      # @param other [Datatype::LxString, String]
+      # @return [Boolean]
+      def ==(other)
+        case other
+          when LXString
+            value == other.value
+          when String
+            value == other
+        else
+          raise StandardError, 'Cannot compare a #{self.class} with #{other.class}'
+        end
+      end
+
       protected
 
       def validated_value(aValue)

data/lib/loxxy/front_end/{parser.rb → raw_parser.rb}

@@ -5,7 +5,22 @@ require_relative 'grammar'
 
 module Loxxy
   module FrontEnd
-    class Parser
+    # A Lox parser that produce concrete parse trees.
+    # Concrete parse trees are the default kind of parse tree
+    # generated by the Rley library.
+    # They consist of two node types only:
+    # - NonTerminalNode
+    # - TerminalNode
+    # A NonTerminalNode has zero or more child nodes (called subnodes)
+    # A TerminalNode is leaf node, that is, it has no child node.
+    # While concrete parse tree nodes can be generated out of the box,
+    # they have the following drawbacks:
+    # - Generic node classes that aren't always suited for the needs of 
+    #     the language being processing.
+    # - Concrete parse tree tend to be deeply nested, which may complicate
+    #   further processing.
+    class RawParser
+      # @return [Rley::Engine] A facade object for the Rley parsing library
       attr_reader(:engine)
 
       def initialize

data/lib/loxxy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Loxxy
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/spec/datatype/lx_string_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../spec_helper' # Use the RSpec framework
+
+# Load the class under test
+require_relative '../../lib/loxxy/datatype/lx_string'
+
+module Loxxy
+  module Datatype
+    describe LXString do
+      let(:sample_text) { 'some_text' }
+      subject { LXString.new(sample_text) }
+      
+      context 'Initialization:' do
+        it 'should accept a String value at initialization' do
+          expect { LXString.new(sample_text) }.not_to raise_error
+        end
+        
+        it 'should know its value' do
+          expect(subject.value).to eq(sample_text)
+        end
+      end
+
+      context 'Provided services:' do
+        it 'compares with another string' do
+          expect(subject).to eq(sample_text)
+          expect(subject).to eq(LXString.new(sample_text.dup))
+
+          expect(subject).not_to eq('')
+          expect(subject).not_to eq('other-text')
+        end
+      end
+    end # describe
+  end # module
+end # module

data/spec/front_end/raw_parser_spec.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative '../spec_helper' # Use the RSpec framework
+
+# Load the class under test
+require_relative '../../lib/loxxy/front_end/raw_parser'
+
+module Loxxy
+  module FrontEnd
+    describe RawParser do
+      subject { RawParser.new }
+
+      context 'Initialization:' do
+        it 'should be initialized without argument' do
+          expect { RawParser.new }.not_to raise_error
+        end
+
+        it 'should have its parse engine initialized' do
+          expect(subject.engine).to be_kind_of(Rley::Engine)
+        end
+      end # context
+
+      context 'Parsing blank files:' do
+        def check_empty_input_result(aParseTree)
+          # Parse results MUST to comply to grammar rule:
+          #   program => declaration_star EOF
+          #   where the declaration_star MUST be empty
+          expect(aParseTree.root.symbol.name).to eq('program')
+          (decls, eof) = aParseTree.root.subnodes
+          expect(decls).to be_kind_of(Rley::PTree::NonTerminalNode)
+          expect(decls.symbol.name).to eq('declaration_star')
+          expect(decls.subnodes).to be_empty
+          expect(eof).to be_kind_of(Rley::PTree::TerminalNode)
+          expect(eof.symbol.name).to eq('EOF')
+        end
+
+        it 'should cope with an empty input' do
+          ptree = subject.parse('')
+          check_empty_input_result(ptree)
+        end
+
+        it 'should cope with whitespaces only input' do
+          ptree = subject.parse(' ' * 80 + "\n" * 20)
+          check_empty_input_result(ptree)
+        end
+
+        it 'should cope with comments only input' do
+          input = +''
+          %w[First Second Third].each do |ordinal|
+            input << "// #{ordinal} comment line\r\n"
+          end
+          ptree = subject.parse(input)
+          check_empty_input_result(ptree)
+        end
+      end # context
+
+      context 'Parsing expressions:' do
+        # Utility method to walk towards deeply nested node
+        # @param aNTNode [Rley::PTree::NonTerminalNode]
+        # @param subnodePath[Array<Integer>] An Array of subnode indices
+        def walk_subnodes(aNTNode, subnodePath)
+          curr_node = aNTNode
+          subnodePath.each do |index|
+            curr_node = curr_node.subnodes[index]
+          end
+
+          curr_node
+        end
+        it 'should parse a hello world program' do
+          program = <<-LOX_END
+            // Your first Lox program!
+            print "Hello, world!";
+LOX_END
+          ptree = subject.parse(program)
+          root = ptree.root
+          expect(root.symbol.name).to eq('program')
+          (decls, eof) = root.subnodes
+          expect(decls).to be_kind_of(Rley::PTree::NonTerminalNode)
+          expect(decls.symbol.name).to eq('declaration_star')
+          stmt = decls.subnodes[1].subnodes[0]
+          expect(stmt).to be_kind_of(Rley::PTree::NonTerminalNode)
+          expect(stmt.symbol.name).to eq('statement')
+          prnt_stmt = stmt.subnodes[0]
+          expect(prnt_stmt).to be_kind_of(Rley::PTree::NonTerminalNode)
+          expect(prnt_stmt.subnodes.size).to eq(3)
+          expect(prnt_stmt.subnodes[0]).to be_kind_of(Rley::PTree::TerminalNode)
+          expect(prnt_stmt.subnodes[0].symbol.name).to eq('PRINT')
+          expect(prnt_stmt.subnodes[1]).to be_kind_of(Rley::PTree::NonTerminalNode)
+          leaf_node = walk_subnodes(prnt_stmt, [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
+          expect(leaf_node).to be_kind_of(Rley::PTree::TerminalNode)
+          expect(leaf_node.symbol.name).to eq('STRING')
+          expect(leaf_node.token.value).to eq('Hello, world!')
+          expect(prnt_stmt.subnodes[2]).to be_kind_of(Rley::PTree::TerminalNode)
+          expect(prnt_stmt.subnodes[2].symbol.name).to eq('SEMICOLON')
+        end
+      end
+    end # describe
+  end # module
+end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: loxxy
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Dimitri Geshef
@@ -93,11 +93,12 @@ files:
 - lib/loxxy/datatype/true.rb
 - lib/loxxy/front_end/grammar.rb
 - lib/loxxy/front_end/literal.rb
-- lib/loxxy/front_end/parser.rb
+- lib/loxxy/front_end/raw_parser.rb
 - lib/loxxy/front_end/scanner.rb
 - lib/loxxy/version.rb
 - loxxy.gemspec
-- spec/front_end/parser_spec.rb
+- spec/datatype/lx_string_spec.rb
+- spec/front_end/raw_parser_spec.rb
 - spec/front_end/scanner_spec.rb
 - spec/loxxy_spec.rb
 - spec/spec_helper.rb
@@ -126,6 +127,7 @@ signing_key:
 specification_version: 4
 summary: An implementation of the Lox programming language. WIP
 test_files:
-- spec/front_end/parser_spec.rb
+- spec/datatype/lx_string_spec.rb
+- spec/front_end/raw_parser_spec.rb
 - spec/front_end/scanner_spec.rb
 - spec/loxxy_spec.rb

data/spec/front_end/parser_spec.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../spec_helper' # Use the RSpec framework
-require_relative '../../lib/loxxy/front_end/parser' # Load the class under test
-
-module Loxxy
-  module FrontEnd
-    describe Parser do
-      subject { Parser.new }
-
-      context 'Initialization:' do
-        it 'should be initialized without argument' do
-          expect { Parser.new }.not_to raise_error
-        end
-
-        it 'should have its parse engine initialized' do
-          expect(subject.engine).to be_kind_of(Rley::Engine)
-        end
-      end # context
-      
-      context 'Parsing blank files:' do
-        def check_empty_input_result(aParseTree)
-          # Parse results MUST to comply to grammar rule:
-          #   program => declaration_star EOF
-          #   where the declaration_star MUST be empty
-          expect(aParseTree.root.symbol.name).to eq('program')
-          (decls, eof) = aParseTree.root.subnodes
-          expect(decls).to be_kind_of(Rley::PTree::NonTerminalNode)
-          expect(decls.symbol.name).to eq('declaration_star')
-          expect(decls.subnodes).to be_empty
-          expect(eof).to be_kind_of(Rley::PTree::TerminalNode)
-          expect(eof.symbol.name).to eq('EOF')
-        end
-
-        it 'should cope with an empty input' do
-          ptree = subject.parse('')
-          check_empty_input_result(ptree)
-        end
-
-        it 'should cope with whitespaces only input' do
-          ptree = subject.parse(' ' * 80 + "\n" * 20)
-          check_empty_input_result(ptree)
-        end
-
-        it 'should cope with comments only input' do
-          input = +''
-          %w[First Second Third].each do |ordinal|
-            input << "// #{ordinal} comment line\r\n"
-          end
-          ptree = subject.parse(input)
-          check_empty_input_result(ptree)
-        end
-      end # context
-    end # describe
-  end # module
-end # module