loxxy 0.0.10 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4f33203580d2b83ee7139e449787b439c0fb56c5a8c3dcc8035d114ffd957d3
-  data.tar.gz: 46c9fb2f55849c6aa9b9e4d58588746ddb3ac3353f7ed09922d9394a9fc512c6
+  metadata.gz: 7624afc97e5e8d3cee171dc9fbbe7a45c45698595109a5281d9f58fcaebd73ec
+  data.tar.gz: 67ec959b7758245f414314ea9c8b0a2bbf40a5e01133f17325fa40ab720858f0
 SHA512:
-  metadata.gz: 30f554af6338b50297ce6befaa62c86c8406df681e25098cc95dc28da64bb6feabbb9e085846eb8032f51d8d3655332105eb1d7165903bbd0d6be24cb13c4d0b
-  data.tar.gz: d9d9a69a010d16807f6c4bf24b15e8135367bb62b6d2e052943e0d6030751f282c777f652dd3fced08093aee8abae228e63d365cae156fa6e87ac7f52fc7e2e6
+  metadata.gz: adcb9cf6b353b09cf623df330fbdff35255571f8781dfd0b46ea6ab32c02cf55bd0130f94414cd91aa8cb798b1ea7cd4aef4844acc556147b5e4b387d099b8c0
+  data.tar.gz: 47230281481b965fe1dddd74f763568a0ca125454800984c41fb29629d26c37ae8f7fa0320a38ca784abe605dfb5dc14f4a9c26b0d269240ea07c5e2feb6241b

data/CHANGELOG.md

@@ -1,3 +1,67 @@
+## [0.0.15] - 2021-01-11
+- The interpreter can evaluate substraction between two numbers.
+
+## Added
+- Method `Datatype::Number#-` implmenting the subtraction operation
+
+## Changed
+- File `README.md` minor editorial changes.
+- File `lx_string_spec.rb` Added test for string concatentation
+- File `number_spec.rb` Added tests for addition and subtraction operations
+- File `interpreter_spec.rb` Added tests for subtraction operation
+
+## [0.0.14] - 2021-01-10
+- The interpreter can evaluate addition of numbers and string concatenation
+
+## Added
+- Method `Ast::ASTVisitor::visit_binary_expr` for visiting binary expressions
+- Method `Ast::LoxBinaryExpr#accept` for visitor pattern
+- Method `BackEnd::Engine#after_binary_expr` to trigger execution of binary operator
+- `Boolean` class hierarchy: added methos `true?` and `false?` to ease spec test writing
+- Method `Datatype::LXString#+` implementation of the string concatenation
+- Method `Datatype::Number#+` implementation of the addition of numbers
+
+## Changed
+- File `interpreter_spec.rb` Added tests for addition operation and string concatenation
+
+
+## [0.0.13] - 2021-01-10
+- The interpreter can evaluate directly simple literals.
+
+## Changed
+- Class `AST::ASTBuilder` added `reduce_exprStmt` to support the evaluation of literals.
+- File `README.md` added one more example.
+- File `parser_spec.rb` Updated the tests to reflect the change in the AST.
+- File `interpreter_spec.rb` Added a test for literal expression.
+
+## Fixed
+- File `loxxy.rb`: shorthand method `lox_true` referenced the ... false object (oops).
+
+## [0.0.12] - 2021-01-09
+- Initial interpreter capable of evaluating a tiny subset of Lox language.
+
+## Added
+- Class `AST::LoxNoopExpr`
+- Class `AST::LoxPrintStmt`
+- Class `BackEnd::Engine` implementation of the print statement logic
+- Class `Interpreter`
+
+## Changed
+- Class `Ast::ASTVisitor` Added visit method
+- File `README.md` added Hello world example.
+
+## [0.0.11] - 2021-01-08
+- AST node generation for logical expression (and, or).
+
+## Changed
+- Class `AST::ASTBuilder` added `reduce_` methods for logical operations.
+- File `grammar.rb`added name to logical expression rules
+- File `README.md` added gem version and license badges, expanded roadmap section.
+
+## Fixed
+- File `grammar.rb`: a rule had incomplete non-terminal name `conjunct_` in its lhs.
+
+
 ## [0.0.10] - 2021-01-08
 - AST node generation for equality expression.
 

data/README.md

@@ -2,69 +2,87 @@
 [![Gem Version](https://badge.fury.io/rb/loxxy.svg)](https://badge.fury.io/rb/loxxy)
 [![License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://github.com/famished-tiger/loxxy/blob/main/LICENSE.txt)
 
-
+### What is loxxy?
 A Ruby implementation of the [Lox programming language](https://craftinginterpreters.com/the-lox-language.html ),
 a simple language used in Bob Nystrom's online book [Crafting Interpreters](https://craftinginterpreters.com/ ).
 
-## Purpose of this project:
+### Purpose of this project:
 - To deliver an open source example of a programming language fully implemented in Ruby  
-  (from the scanner, parser, code generation).
+  (from the scanner, parser, an interpreter).
 - The implementation should be mature enough to run [LoxLox](https://github.com/benhoyt/loxlox),  
   a Lox interpreter written in Lox.
 
-## Current status
-The __loxxy__ gem hosts two distinct parsers classes (`RawParser` and `Parser`).
-- A `RawParser` instance is able to recognize valid Lox input and to generate
-  a concrete parse tree from it.
-- A `Parser` instance can also parse Lox source code but will generate an AST
-  (Abstract Syntax Tree) that will be used by the future tree-walking interpreter.
-  Currently it generates AST for arithmetic expressions with literal numbers only.
-
-## Roadmap
-### Done
-- Scanner (tokenizer)
-- Lox grammar (in format required by Rley gem)   
-- Raw parser. It parses Lox programs and generates a raw parse tree.
-- Tailored parser for generating AST (Abstract Syntax Tree)
-  
-### Started
--  Custom AST builder class  
--  Classes for representing Lox expressions in AST
-
-### TODO
-AST Node generation
-Goal: parser should generate AST for any input Lox program
-- [X] Equality operator
-- [] Logical operator (and, or)
-- [] Unary expressions (negate, not)
-- [] Grouping expressions
-- [] Print statement
-- [] Simple assignment expressions
-- [] Variable declaration
-- [] Dot notation
-- [] Block statement
-- [] If statement
-- [] For statement
-- [] While statement
-- [] Function declaration
-- [] Call expression
-- [] Return statement
-- [] Class declaration
-- [] AST generation covers complete grammar
-
-Tree-walking:
-- [] Tree visitor recognizes all AST node types
-
-Interpreter:
-- Keywords: symbol table, scope, activation record, class & object model, Lox test suite
-- [] Milestone: Interpreter handles expressions but function calls
-- [] Milestone: Interpreter handles `for`, `if`, `print`, `while` and block statements
-- [] Milestone: Interpreter handles variable declarations (global, block)
-- [] Milestone: Interpreter handles function declarations and calls
-- [] Milestone: Interpreter supports class and object definition
-- [] Milestone: Lox interpreter complete
+### Current status
+The project is still in inception and the interpreter is being implemented...  
+Currently it can execute a tiny subset of __Lox__ language.
+
+But the __loxxy__ gem hosts also a parser class `RawPaser` that can parse, in principle, any valid Lox input.
+
+## What's the fuss about Lox?
+... Nothing...  
+Bob Nystrom designed a language __simple__ enough so that he could present 
+two implementations (an interpreter, then a compiler) in one single book.
+
+Although __Lox__ is fairly simple, it is far from a toy language:
+- Dynamically typed,
+- Provides datatypes such as booleans, number, strings,
+- Supports arithmetic operations (+, -, *, / ) and comparison ( >, >= , <, <=)
+- Implements equality operators (==, !=) and the logical connectors `and` and `or`.
+- Control flow statements `if`, `for` and `while`
+- Functions and closures
+- Object-orientation (classes, methods, inheritance).
+
+In other words, __Lox__ contains interesting features expected from most general-purpose 
+languages.
+
+### What's missing in Lox?
+__Lox__ was constrained by design and therefore was not aimed to be a language used in real-world applications.
+Here are some missing parts to make it a _practical_ language:
+- Collections (arrays, maps, ...)
+- Modules (importing stuff from other packages/files)
+- Error handling (e.g. exceptions)  
+- Support for concurrency (e.g. threads, coroutines)
+
+Also a decent standard library for IO, networking,... is lacking. 
+
+For sure, the language has shortcomings but on the other hand, it exhibits the essential features 
+to cover in an introduction to language implementation.
+
+That's already fun... and if all this gives you the inspiration for creating your own
+language, that might be even funnier... 
+
+Last point: what's makes __Lox__ interesting is the fact that there are implementations in many [languages](https://github.com/munificent/craftinginterpreters/wiki/Lox-implementations)
+
+## Hello world example
+```ruby
+require 'loxxy'
+
+lox_program = <<LOX_END
+  // Your first Lox program!
+  print "Hello, world!";
+LOX_END
+
+lox = Loxxy::Interpreter.new
+lox.evaluate(lox_program) # Output: Hello, world!
+```
+
+## Retrieving the result from a Lox program
+The __Loxxy__ interpreter returns the value of the last evaluated expression. 
+
+```ruby
+require 'loxxy'
+
+lox = Loxxy::Interpreter.new
+
+lox_program = '47 - 5; // THE answer'
+result = lox.evaluate(lox_program) # => Loxxy::Datatype::Number
+
+# `result` is a Ruby object, so let's use it...
+puts result.value # Output: 42
+```
 
 ## Example using RawParser class
+
 ```ruby
 require 'loxxy'
 
@@ -109,6 +127,86 @@ program
 +-- EOF: ''
 ```
 
+## Suppported Lox language features
+Although the interpreter should parse almost any valid Lox program,
+it currently can evaluate a tiny set of AST node (AST = Abstract Syntax Tree).
+
+Here are the language features currently supported by the interpreter:
+
+- [Comments](#comments)
+- [Keywords](#keywords)
+- [Operators and Special Chars](#operators-and-special-chars)
+- [Datatypes](#datatypes)
+- [Statements](#statements)
+
+### Comments
+
+Loxxy supports single line C-style comments.
+
+```javascript
+// single line comment
+```
+
+### Keywords
+
+The parser knows all the __Lox__ reserved keywords:
+```lang-none
+and, class, else, false, fun, for, if, nil, or,
+print, return, super, this, true, var, while
+```
+Of these, the interpreter implements: `false`, `nil`, `true`
+
+### Operators and Special Chars
+#### Operators
+The parser recognizes all the __Lox__ operators, delimiters and separators:
+- Arithmetic operators: `+`, `-`, `*`, `/`
+- Comparison operators: `>`, `>=`, `<`, `<=`
+- Equality operators: `==`, `!=`
+
+Of these, the interpreter implements: 
+`+` (addition of two numbers or string concatenation)
+`-` (difference between two numbers)
+
+#### Delimiters
+The parser knows all the __Lox__ grouping delimiters:  
+(`, ), `{`, `}`
+
+These aren't yet implemented in the interpreter.
+
+The other characters that have a special meaning in __Lox__ are:
+- `,` Used in parameter list
+- `.` For the dot notation (i.e. calling a method)
+- `;` The semicolon is used to terminates expressions
+- `=` Assignment
+
+The parser recognizes them all but the interpreter accepts the semicolons only.
+
+### Datatypes
+
+loxxy supports  all the standard __Lox__ datatypes:
+- `Boolean`: Can be `true` or `false`
+- `Number`: Can be an integer or a floating-point numbers. For example: `123, 12.34, -45.67`
+- `String`: Sequence of characters surrounded by `"`. For example: `"Hello!"`
+- `Nil`: Used to define a null value, denoted by the `nil` keyword
+
+## Statements
+### Implemented expressions
+Loxxy implements expressions:
+- Plain literals only; or,
+- Addition of two numbers; or,
+- Subtraction of two numbers; or,  
+- Concatenation of two strings
+
+### Implemented statements
+Loxxy implements the following statements:
+- Expressions (see above sub-section)
+- Print statement
+
+```javascript
+// Print statement with nested concatenation
+print "Hello" + ", " + "world!";
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -130,7 +228,6 @@ Or install it yourself as:
 TODO: Write usage instructions here
 
 ## Other Lox implementations in Ruby
-An impressive list of Lox implementations can be found [here](https://github.com/munificent/craftinginterpreters/wiki/Lox-implementations)
 
 For Ruby, there is the [lox](https://github.com/rdodson41/ruby-lox) gem.
 There are other Ruby-based projects as well:  

data/lib/loxxy.rb

@@ -1,10 +1,31 @@
 # frozen_string_literal: true
 
 require_relative 'loxxy/version'
+require_relative 'loxxy/interpreter'
 require_relative 'loxxy/front_end/raw_parser'
-require_relative 'loxxy/front_end/parser'
 
+# Namespace for all classes and constants of __loxxy__ gem.
 module Loxxy
   class Error < StandardError; end
-  # Your code goes here...
+
+  # Shorthand method. Returns the sole object that represents
+  # a Lox false literal.
+  # @return [Loxxy::Datatype::False]
+  def self.lox_false
+    Datatype::False.instance
+  end
+
+  # Shorthand method. Returns the sole object that represents
+  # a Lox nil literal.
+  # @return [Loxxy::Datatype::Nil]
+  def self.lox_nil
+    Datatype::Nil.instance
+  end
+
+  # Shorthand method. Returns the sole object that represents
+  # a Lox true literal.
+  # @return [Loxxy::Datatype::True]
+  def self.lox_true
+    Datatype::True.instance
+  end
 end

data/lib/loxxy/ast/all_lox_nodes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'lox_print_stmt'
+require_relative 'lox_literal_expr'
+require_relative 'lox_noop_expr'

data/lib/loxxy/ast/ast_builder.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../datatype/all_datatypes'
-require_relative 'lox_literal_expr'
+require_relative 'all_lox_nodes'
 require_relative 'lox_binary_expr'
 
 module Loxxy
@@ -10,31 +10,33 @@ module Loxxy
     # (Abstract Syntax Tree) from a sequence of input tokens and
     # visit events produced by walking over a GFGParsing object.
     class ASTBuilder < Rley::ParseRep::ASTBaseBuilder
-      # Mapping Token name => operator | separator | delimiter characters
-      # @return [Hash{String => String}]
-      Name2special = {
-        'AND' => 'and',
-        'BANG' => '!',
-        'BANG_EQUAL' => '!=',
-        'COMMA' =>  ',',
-        'DOT' => '.',
-        'EQUAL' => '=',
-        'EQUAL_EQUAL' => '==',
-        'GREATER' => '>',
-        'GREATER_EQUAL' => '>=',
-        'LEFT_BRACE' =>  '{',
-        'LEFT_PAREN' => '(',
-        'LESS' => '<',
-        'LESS_EQUAL' => '<=',
-        'MINUS' => '-',
-        'OR' => 'or',
-        'PLUS' => '+',
-        'RIGHT_BRACE' => '}',
-        'RIGHT_PAREN' => ')',
-        'SEMICOLON' => ';',
-        'SLASH' =>  '/',
-        'STAR' => '*'
-      }.freeze
+      unless defined?(Name2special)
+        # Mapping Token name => operator | separator | delimiter characters
+        # @return [Hash{String => String}]
+        Name2special = {
+          'AND' => 'and',
+          'BANG' => '!',
+          'BANG_EQUAL' => '!=',
+          'COMMA' =>  ',',
+          'DOT' => '.',
+          'EQUAL' => '=',
+          'EQUAL_EQUAL' => '==',
+          'GREATER' => '>',
+          'GREATER_EQUAL' => '>=',
+          'LEFT_BRACE' =>  '{',
+          'LEFT_PAREN' => '(',
+          'LESS' => '<',
+          'LESS_EQUAL' => '<=',
+          'MINUS' => '-',
+          'OR' => 'or',
+          'PLUS' => '+',
+          'RIGHT_BRACE' => '}',
+          'RIGHT_PAREN' => ')',
+          'SEMICOLON' => ';',
+          'SLASH' =>  '/',
+          'STAR' => '*'
+        }.freeze
+      end # defined
 
       attr_reader :strict
 
@@ -117,6 +119,60 @@ module Loxxy
         [[operator, operand2]]
       end
 
+      #####################################
+      #  SEMANTIC ACTIONS
+      #####################################
+
+      # rule('program' => 'EOF').as 'null_program'
+      def reduce_null_program(_production, _range, _tokens, _theChildren)
+        Ast::LoxNoopExpr.new(tokens[0].position)
+      end
+
+      # rule('program' => 'declaration_plus EOF').as ''
+      def reduce_lox_program(_production, range, tokens, theChildren)
+        return_first_child(range, tokens, theChildren) # Discard the semicolon
+      end
+
+      # rule('exprStmt' => 'expression SEMICOLON')
+      def reduce_exprStmt(_production, range, tokens, theChildren)
+      return_first_child(range, tokens, theChildren) # Discard the semicolon
+      end
+
+      # rule('printStmt' => 'PRINT expression SEMICOLON')
+      def reduce_print_stmt(_production, _range, tokens, theChildren)
+        Ast::LoxPrintStmt.new(tokens[1].position, theChildren[1])
+      end
+
+      # rule('logic_or' => 'logic_and disjunct_plus')
+      def reduce_logic_or_plus(production, range, tokens, theChildren)
+        reduce_binary_operator(production, range, tokens, theChildren)
+      end
+
+      # rule('disjunct_plus' => 'disjunct_plus OR logic_and')
+      def reduce_logic_or_plus_more(production, range, tokens, theChildren)
+        reduce_binary_plus_more(production, range, tokens, theChildren)
+      end
+
+      # rule('disjunct_plus' => 'OR logic_and')
+      def reduce_logic_or_plus_end(production, range, tokens, theChildren)
+        reduce_binary_plus_end(production, range, tokens, theChildren)
+      end
+
+      # rule('logic_and' => 'equality conjunct_plus')
+      def reduce_logic_and_plus(production, range, tokens, theChildren)
+        reduce_binary_operator(production, range, tokens, theChildren)
+      end
+
+      # rule('conjunct_plus' => 'conjunct_plus AND equality')
+      def reduce_logic_and_plus_more(production, range, tokens, theChildren)
+        reduce_binary_plus_more(production, range, tokens, theChildren)
+      end
+
+      # rule('conjunct_plus' => 'AND equality')
+      def reduce_logic_and_plus_end(production, range, tokens, theChildren)
+        reduce_binary_plus_end(production, range, tokens, theChildren)
+      end
+
       # rule('equality' => 'comparison equalityTest_plus')
       def reduce_equality_plus(production, range, tokens, theChildren)
         reduce_binary_operator(production, range, tokens, theChildren)