loxxy 0.1.15 → 0.2.02

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3994a3225b7dbc4a39d24cc646c20e4a7a19b074e85fe2dd9bc87d9ca1d61cb
-  data.tar.gz: 965c328057f51fb7d13886255955e782e51b1f030f3053a6f5f6f4534962855b
+  metadata.gz: afc822710c5023cdffd8eeb9e9316736f2b2d9ddb2d05e4c4e835dee9b9b4d8b
+  data.tar.gz: 5debd7264833555cc34c64586de96d4e811eef4ebebe25f6c42a0832dee8e433
 SHA512:
-  metadata.gz: 9db05948e45f7903ca71d7d0e3722f3c9b1fd3f50931e17b6bb1666c34cf03e1dc7f6cf32abee461dd6e6ec6824cd89b8ef5b2b56ae41fcd40068228d8cbaba2
-  data.tar.gz: eaa762982bd89f2b4cb85e8d6831017e702b87501b7c29132f25f79fa592bf804ec95736f518d304f43caf814aa55eeadd5041ffcba1afa3aaaed631d23027af
+  metadata.gz: d988772978387faa28692101e6b2dab580a93b6f5738ad9094faf22d8aed78aca68123982ff0a25d9b9029d4d27ef4f82788009b10942a14ce5dd9bd9f1e37a7
+  data.tar.gz: 711b3188b0dd14a9821eee5227ee0d574c60144b7be88a3f722d10b4506556fa864685659c7493acfd6d63c2cf82f8c0c6c36cc0431a57a2d476efe3b4bf7efd

data/.rubocop.yml

@@ -3,6 +3,9 @@ AllCops:
     - 'exp/**/*'
     - 'demo/**/*'
 
+Gemspec/DateAssignment:
+  Enabled: true
+
 Layout/ArgumentAlignment:
   Enabled: false
 
@@ -34,7 +37,7 @@ Layout/EndOfLine:
 
 Layout/FirstArgumentIndentation:
   Enabled: false
-  
+
 Layout/HashAlignment:
   Enabled: false
 
@@ -56,7 +59,7 @@ Layout/MultilineMethodCallBraceLayout:
 
 Layout/SpaceAroundOperators:
   Enabled: true
-  
+
 Layout/SpaceBeforeBrackets:
   Enabled: true
 
@@ -74,10 +77,13 @@ Layout/TrailingEmptyLines:
 
 Layout/TrailingWhitespace:
   Enabled: true
-  
+
 Lint/AmbiguousAssignment:
   Enabled: true
 
+Lint/DeprecatedConstants:
+  Enabled: true
+
 Lint/DuplicateBranch:
   Enabled: true
 
@@ -90,24 +96,42 @@ Lint/EmptyBlock:
 Lint/EmptyClass:
   Enabled: false
 
+Lint/LambdaWithoutLiteralBlock:
+  Enabled: true
+
 Lint/Loop:
   Enabled: true
 
 Lint/NoReturnInBeginEndBlocks:
   Enabled: true
 
+Lint/NumberedParameterAssignment:
+  Enabled: true
+
+Lint/OrAssignmentToConstant:
+  Enabled: true
+
 Lint/RaiseException:
   Enabled: true
 
+Lint/RedundantDirGlobSort:
+  Enabled: true
+
 Lint/RescueException:
   Enabled: true
 
 Lint/StructNewOverride:
   Enabled: true
 
+Lint/SymbolConversion:
+  Enabled: true
+
 Lint/ToEnumArguments:
   Enabled: true
 
+Lint/TripleQuotes:
+  Enabled: true
+
 Lint/UnexpectedBlockArity:
   Enabled: true
 
@@ -170,7 +194,7 @@ Naming/BlockParameterName:
 
 Naming/MethodParameterName:
   Enabled: false
-  
+
 Naming/MethodName:
   Enabled: false
 
@@ -200,7 +224,7 @@ Style/ClassCheck:
 
 Style/ClassVars:
   Enabled: false
-  
+
 Style/CollectionCompact:
   Enabled: true
 
@@ -221,7 +245,7 @@ Style/DefWithParentheses:
 
 Style/Documentation:
   Enabled: false
-  
+
 Style/DocumentDynamicEvalDefinition:
   Enabled: true
 
@@ -236,7 +260,7 @@ Style/GuardClause:
 
 Style/HashEachMethods:
   Enabled: true
-  
+
 Style/HashExcept:
   Enabled: true
 
@@ -254,13 +278,13 @@ Style/InverseMethods:
 
 Style/MissingRespondToMissing:
   Enabled: false
-  
+
 Style/NegatedIfElseCondition:
   Enabled: true
 
 Style/Next:
   Enabled: false
-  
+
 Style/NilLambda:
   Enabled: true
 
@@ -269,7 +293,7 @@ Style/NumericLiterals:
 
 Style/RaiseArgs:
   Enabled: true
-  
+
 Style/RedundantArgument:
   Enabled: true
 
@@ -290,7 +314,7 @@ Style/StderrPuts:
 
 Style/StringLiterals:
   Enabled: true
-  
+
 Style/SwapValues:
   Enabled: true
 
@@ -352,6 +376,9 @@ Style/BisectedAttrAccessor:
 Style/CaseLikeIf:
   Enabled: true
 
+Style/EndlessMethod:
+  Enabled: true
+
 Style/ExplicitBlockArgument:
   Enabled: true
 
@@ -361,9 +388,15 @@ Style/GlobalStdStream:
 Style/HashAsLastArrayItem:
   Enabled: true
 
+Style/HashConversion:
+  Enabled: true
+
 Style/HashLikeCase:
   Enabled: true
 
+Style/IfWithBooleanLiteralBranches:
+  Enabled: true
+
 Style/OptionalBooleanParameter:
   Enabled: true
 
@@ -388,5 +421,8 @@ Style/SingleArgumentDig:
 Style/SlicingWithRange:
   Enabled: true
 
+Style/StringChars:
+  Enabled: true
+
 Style/StringConcatenation:
   Enabled: true

data/CHANGELOG.md

@@ -1,3 +1,69 @@
+## [0.2.02] - 2021-04-21
+- Improvements in the scanner class (escape sequence for quotes and newlines), error messages closer to jlox.
+
+### Changed
+- File `loxxy` executable doesn't show a stack trace for scanner errors
+- Class `ScannerError` is now a subclass of `Loxxy::Error`
+- Class `Scanner` now returns a specific error message for unterminated strings
+- Class `Scanner` error messages are closer to the ones from jlox
+- Class `Scanner` supports now escape sequences \" for double quotes, \n for newlines
+- File `README.md` Reshuffled some text
+
+## [0.2.01] - 2021-04-18
+- Minor improvements in CLI, starting re-documenting `README.md`.
+
+### New
+- Class `Loxxy::CLIParser` parser for the command-line options
+
+### Changed
+- File `loxxy` executable now uses commad-line parsing
+- File `.rubocop.yml` updated with new cops
+- File `README.md` Added examples for command-line interface
+- File `loxxy.gemspec` expanded description of gem
+
+## [0.2.00] - 2021-04-17
+- `Loxxy` implements the complete `Lox` language including its object-oriented features.
+
+### New
+- Class `Ast::LoxSuperExpr` an AST node that represents the occurrence of `super` in source code.
+- Method `Ast::ASTBuilder#reduce_class_subclassing` action launched by the parser when detecting inheritance
+- Method `Ast::ASTBuilder#reduce_super_expr` action launched by the parser when detecting the super keyword
+- Method `Ast::Visitor#visit_super_expr` visit of an `Ast::LoxSuperExpr` node
+- Method `BackEnd::Engine#after_super_stmt` does the lookup of an inherited method.
+- Method `BackEnd::Resolver#after_super_stmt` checks for correct context for super occurrence
+
+
+### Changed
+- Method `Ast::ASTBuilder#reduce_class_decl` expanded in order to support superclass
+- Class `Ast::LoxClassStmt` added `superclass` attribute, expanded constructor signature.
+- Method `BackEnd::Engine#after_class_stmt` adds an environment for super variable.
+- Class `BackEnd::LoxClass` added `superclass` attribute, expanded constructor signature.
+- Method `BackEnd::LoxClass#find_method` now does the lookup in superclass(es)
+- Method `BackEnd::Resolver#after_class_stmt` super variable resolution
+- File `grammar.rb` changed rules to cope with superclass name and super keyword
+- File `README.md` updated to reflect current implementation level
+
+## [0.1.17] - 2021-04-11
+- `Loxxy` now support custom initializer.
+
+### Changed
+- Method `BackEnd::Class#call` updated for custom initializer.
+- Class `BackEnd::LoxFunction` added an attribute `is_initializer`
+- Class `BackEnd::Resolver#before_return_stmt` added a check that return in initializer may not return a value
+
+### Fixed
+- Method `BackEnd::Engine#after_call_expr` now does arity checking also for initalizer.
+- Method `BackEnd::LoxInstance#set` removed the check of field existence that prevented the creation of ... fields
+
+## [0.1.16] - 2021-04-10
+- Fixed an issue in name lookup. All the `this` test suite is passing.
+
+### Changed
+- Method `BackEnd::Engine#after_var_stmt` now it creates the variable and pouts it in the symbol table
+
+### Removed
+- Method `BackEnd::Engine#before_var_stmt` it generated bug when assigning a value to a var, when that var name occurred elsewhere
+
 ## [0.1.15] - 2021-04-08
 - Fixed the `dangling else`by tweaking the grammar rules
 

data/README.md

@@ -1,59 +1,202 @@
 # loxxy
 [![Gem Version](https://badge.fury.io/rb/loxxy.svg)](https://badge.fury.io/rb/loxxy)
+[![Build status](https://ci.appveyor.com/api/projects/status/8e5p7dgjanm0qjkp?svg=true)](https://ci.appveyor.com/project/famished-tiger/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?
+## What is loxxy?
 A Ruby implementation of the [Lox programming language](https://craftinginterpreters.com/the-lox-language.html ),
-a simple language defined in Bob Nystrom's online book [Crafting Interpreters](https://craftinginterpreters.com/ ).
+a simple language defined in Bob Nystrom's excellent online book [Crafting Interpreters](https://craftinginterpreters.com/ ).
 
-### Purpose of this project:
-- To deliver an open source example of a programming language fully implemented in Ruby  
-  (from the scanner and parser to an interpreter).
-- The implementation should be mature enough to run [LoxLox](https://github.com/benhoyt/loxlox),  
-  a Lox interpreter written in Lox.
+Although __Lox__ is fairly simple, it is far from being a toy language:
+- Dynamically typed,
+- Provides data types 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).
+
+### Loxxy gem features
+- Complete tree-walking interpreter including lexer, parser and resolver
+- 100% pure Ruby with clean design (not a port from some other language)
+- Minimal runtime dependency (Rley gem). Won't drag a bunch of gems...  
+- Ruby API for integrating a Lox interpreter with your code.
+- A command-line interpreter `loxxy`
+- Open for your language extensions
+
+## How to start in 1, 2, 3...?
+... in less than 3 minutes...
+
+### 1. Installing
+Install __Loxxy__ as a gem:
+
+
+    $ gem install loxxy
+
+### 2. Your first `Lox`  program
+Create a text file and enter the following lines:
+```javascript
+// Your firs Lox program
+print "Hello, world.";
+```
+
+### 3. Running your program...
+Assuming that you named the file `hello.lox`, launch the `Loxxy` interpreter in same directory:
+
+    $ loxxy hello.lox
+
+Lo and behold! The output device displays the famous greeting:
+
+    Hello, world.
+ 
+
+Congrats! You ran your first `Lox` program thanks __Loxxy__ gem. 
+For a less superficial encounter with the language jump to the next section.
+
+## So you want something beefier?...
+Let's admit it, the hello world example was unimpressive.   
+To a get a taste of `Lox` object-oriented capabilities, let's try another `Hello world` variant:
+
+```javascript
+// Object-oriented hello world
+class Greeter {
+  // in Lox, initializers/constructors are named `init`
+  init(who) {
+    this.interjection = "Hello";
+    this.subject = who;
+  }
+
+  greeting() {
+    this.interjection + ", " + this.subject + ".";
+  }
+}
+
+var greeter = Greeter("world"); // an instance is created here...
+print greeter.greeting();
+```
+
+Running this version will result in the same famous greeting.
+
+Our next assignment: compute the first 20 elements of the Fibbonacci sequence.  
+Here's an answer using the `while` loop construct:
+
+```javascript
+// Compute the first 20 elements from the Fibbonacci sequence
+
+var a = 0;  // Use the var keyword to declare a new variable
+var b = 1;
+var count = 20;
+
+while (count > 0) {
+  print a;
+  print " ";
+  var tmp = a;
+  a = b;
+  b = tmp + b;
+  count = count - 1;
+}
+```
+
+Assuming, that this source code was put in a file named `fibbonacci.lox`, then
+the command line
+
+    $ loxxy fibbonacci.lox
+
+Results in:
 
-### Current status
-The interpreter currently can execute all allowed __Lox__ expressions and statements except  
-object-oriented feaures (classes and objects).
-The goal is to implement these missing features in Q2 2021.
+    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181
+ 
+Fans of `for` loops will be pleased to find their favorite looping construct.  
+Here again, the Fibbonacci sequence refactored with a `for` loop:
 
+```javascript
+// Fibbonacci sequence - version 2
+var a = 0;
+var b = 1;
+var count = 20;
+
+for (var i = 0; i < count; i = i + 1) {
+  print a;
+  print " ";
+  var tmp = a;
+  a = b;
+  b = tmp + b;
+}
+```
+Lets's call this file `fibbonacci_v2.lox` and execute it thanks `loxxy` CLI:
+
+    $ loxxy fibbonacci_v2.lox
+
+We see again the same sequence:
+
+    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181
+
+To complete our quick tour of `Lox` language, let's calculate the sequence with a recursive function:
+
+```javascript
+// Fibbonacci sequence - version 3
+var count = 20;
+
+// Let's define a recursive function
+fun fib(n) {
+  if (n < 2) return n;
+  return fib(n - 1) + fib(n - 2);
+}
+
+// For demo purposes, let's assign the function to a variable
+var fib_fun = fib;
+
+for (var i = 0; i < count; i = i + 1) {
+  print fib_fun(i);
+  print " ";
+}
+```
+
+This completes our quick tour of `Lox`, to learn more about the language,
+check the online book [Crafting Interpreters](https://craftinginterpreters.com/ )
 
 ## What's the fuss about Lox?
 ... Nothing...  
-Bob Nystrom designed a language __simple__ enough so that he could present 
+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 found in most general-purpose
+languages. In addition to that, there are [numerous implementations](https://github.com/munificent/craftinginterpreters/wiki/Lox-implementations) in different languages 
 
-In other words, __Lox__ contains interesting features found in most general-purpose 
-languages.
+Lox interpreters, like `Loxxy` give the unique opportunity for the curious to learn the internals of reasonably-sized language.
 
 ### What's missing in Lox?
-__Lox__ was constrained by design and was therefore 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)
+While `Lox` blends interesting features from the two mainstream paradigms (OO and functional),
+it doesn't pretend to be used in real-life projects.
 
-Also a decent standard library for IO, networking,... is lacking. 
+In fact, the language was designed to be simple to implement at the expense of missing advanced features.  
+Here are features I'll like to put on my wish list:
+- Collection classes (e.g. Arrays, Maps (Hash))
+- Modules  
+- Standard library
+- Concurrency / parallelism constructs
 
-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 `Lox` cannot be compared to a full-featured language, is both a drawback and and an opportunity.
+Indeed, an open-source language that misses some features is an invitation for the curious to tinker and experiment with extensions.
+There are already a number of programming languages derived from `Lox`...
 
-That's already fun... and if all this gives you the inspiration for creating your own
-language, that might be even funnier... 
+## Why `Loxxy`? What's in it for me?...
 
-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)
+### Purpose of this project:
+- To deliver an open source example of a programming language fully implemented in Ruby  
+  (from the scanner and parser to an interpreter).
+- The implementation should be mature enough to run [LoxLox](https://github.com/benhoyt/loxlox),  
+  a Lox interpreter written in Lox.
+  
+### Roadmap
+- Extend the test suite
+- Improve the error handling  
+- Improve the documentation
+- Ability run the LoxLox interpreter
 
 ## Hello world example
+The next examples show how to use the interpreter directly from Ruby code.
+
 ```ruby
 require 'loxxy'
 
@@ -108,48 +251,10 @@ lox_input = <<-LOX_END
   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)
-
-# Display the parse tree thanks to Rley formatters...
-visitor = Rley::ParseTreeVisitor.new(ptree)
-tree_formatter = Rley::Formatter::Asciitree.new($stdout)
-tree_formatter.render(visitor)
-```
-
-This is the output produced by the above example:
-```
-program
-+-- declaration_plus
-|   +-- declaration
-|       +-- statement
-|           +-- printStmt
-|               +-- PRINT: 'print'
-|               +-- expression
-|               |   +-- assignment
-|               |       +-- logic_or
-|               |           +-- logic_and
-|               |               +-- equality
-|               |                   +-- comparison
-|               |                       +-- term
-|               |                           +-- factor
-|               |                               +-- unary
-|               |                                   +-- call
-|               |                                       +-- primary
-|               |                                           +-- STRING: '"Hello, world!"'
-|               +-- SEMICOLON: ';'
-+-- EOF: ''
-```
 
 ## Suppported Lox language features
-On one hand, the parser covers the complete Lox grammar and should therefore, in principle,
-parse any valid Lox program.
 
-On the other hand, the interpreter is under development and currently it can evaluate only a subset of __Lox__.
-But the situation is changing almost daily, stay tuned...
 
 Here are the language features currently supported by the interpreter:
 
@@ -377,25 +482,7 @@ fun add4(n) // `add4` will be the name of the function
 print add4(6); // output: 10
 ```
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'loxxy'
-```
-
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
-
-    $ gem install loxxy
-
-## Usage
 
-TODO: Write usage instructions here
 
 ## Other Lox implementations in Ruby