loxxy 0.0.11 → 0.0.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 583f5c2f620ea8f45b339607103955eda2f32c02f0358ccb88cf4d20b4398d21
-  data.tar.gz: f349b949c1315473027eaaab589ff1cf2da89deca3b243cd1508c088bf9a9cc5
+  metadata.gz: 7d7d30d3246aa8a8f06f3456d3996c680e9ddb4ed31bcf9fff99685702e50dd1
+  data.tar.gz: dc428ddd0fc03e153e70873bc2827b6e4aac813e5fdfba40ef2f28bfa7283fc2
 SHA512:
-  metadata.gz: 9c93648c634783348a22b3b65cf710a59c0ca5e3cefc5a20d7c60b9b429b4334e1e5603cc2bf74f302aed881daa71634cb7253445b3f376838197637f79f8cc7
-  data.tar.gz: 67d60e89985322911a7842a2b5fc2e22b4ccc3136ffa216027089ea05ea56a6932d1de9b8917173ad072695aaa6abb2147d456f54d09f2878d7831937c42af74
+  metadata.gz: d90f2494a324be036dae2f3d38636c571009b60f19d2b3d917b242ab98d231e03bb121f577e5598ac63514cc5817814972cabe927f05af2842a5a97c89eb69d9
+  data.tar.gz: e09a70a27baa1408904e1bfe512f4f523b8e4efd1aab00412b993c8f4a35b5498f1f6ddb5e67697108c80a91778301e41c15741451e73e1d869496d96441757a

data/CHANGELOG.md

@@ -1,3 +1,77 @@
+## [0.0.16] - 2021-01-11
+- The interpreter can evaluate product and division of two numbers.
+- It also implements equality `==` and inequality `!=` operators
+
+## Added
+- Method `Datatype::False#==` for equality testing
+- Method `Datatype::False#!=` for inequality testing
+- Method `Datatype::LXString#==` for equality testing
+- Method `Datatype::LXString#!=` for inequality testing
+- Method `Datatype::Nil#==` for equality testing
+- Method `Datatype::Nil#!=` for inequality testing
+- Method `Datatype::Number#==` for equality testing
+- Method `Datatype::Number#!=` for inequality testing
+- Method `Datatype::Number#*` for multiply operator
+- Method `Datatype::Number#/` for divide operator
+- Method `Datatype::True#==` for equality testing
+- Method `Datatype::True#!=` for inequality testing
+
+## Changed
+- Method `BackEnd::Engine#after_binary_expr` to allow `*`, `/`, `==`, `!=` operators
+- File `README.md` updated for the newly implemented operators
+
+## [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).
 

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
-- [X] 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,89 @@ 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)
+`*` (product of two numbers)
+`/` (division of two number)
+`==` and `!=` (in)equality testing of two Lox values
+
+#### 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, subtraction, product and division of two numbers; or,
+- Concatenation of two strings,
+- (In)equality test of two Lox values
+
+### 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 +231,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,30 @@ 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)
@@ -141,7 +167,7 @@ module Loxxy
       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)