loxxy 0.2.00 → 0.2.01

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a071e03ebadb94c255a118d3bebd75227a2d36c535495a79ad2525e4fc2bf7c
-  data.tar.gz: 35aa1fc822287f7b86628acac39e5c3ca1c12c478cbb330d302705597ff2f13b
+  metadata.gz: 3137f0d16bb2c3dbbc4e2036abbf45888ba06b863fef69a8682898ffdb2a146b
+  data.tar.gz: 344ff5f99e7d64dd45074aaacde5622ecb676d8d3112773555b0fbcffbd5aa89
 SHA512:
-  metadata.gz: 51b1a4622ee11c20582fa9ffa72f499a64b280c0092b82a8f07d922309c800f787409e8c273a5316d09de594d82026af0d979e2ad7f52ee6d3eb02233549ebf5
-  data.tar.gz: 2649d33c23f73351f9ecb3b9b4b9899541398c94fa4effa8ca4f4c766589df575b1f68685a039f595ca1efb83a515d0a3620afa3721a0604e187b321449b9716
+  metadata.gz: f3cd447081d53619afeb040d9eade7fab0c0d5db79b8407fba412df727fb72849e5671679d7fd13fded703b9009399febfac6506ef91ac0bdd3220ef26472408
+  data.tar.gz: 4a83b84a9853787369d51f48d7c2eacfe8a7e58b4ab8cb5d5322b02e0a5de68c4481effa61587db70f066902d21c7b2a310509de74d13f2cf1476a490e2728a7

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,37 @@
+## [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.
 

data/README.md

@@ -1,59 +1,199 @@
 # 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?
 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).
+
+## 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 with __Loxxy__.
+
+### 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:
+
+    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:
 
-### 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.
+```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?...
+Features:
+- Complete tree-walking interpreter including lexer, parser and resolver
+- 100% pure Ruby with clean design (not a port from some other language)
+- Ruby API for integrating a Lox interpreter with your code.
+- Minimal runtime dependency (Rley gem). Won't drag a bunch of gems...
 
-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 +248,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 +479,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
 

data/bin/loxxy

@@ -3,9 +3,53 @@
 
 require 'loxxy'
 
-if ARGV[0]
-lox = Loxxy::Interpreter.new
-File.open(ARGV[0], 'r') do |f|
-lox.evaluate(f.read)
-end
-end
+class LoxxyRunner
+  DefaultLoxExtension = 'lox'
+  attr_reader(:cli_options)
+
+  def initialize(prog_name, args)
+    my_version = Loxxy::VERSION
+    cli = Loxxy::CLIParser.new(prog_name, my_version)
+    @cli_options = cli.parse!(args)
+  end
+
+  def run!(file_names)
+    return if file_names.nil? || file_names.empty?
+
+    lox = Loxxy::Interpreter.new
+    file_names.each do |lox_file|
+      fname = validate_filename(lox_file)
+      next unless file_exist?(fname)
+
+      File.open(fname, 'r') { |f| lox.evaluate(f.read) }
+    end
+  end
+
+  private
+
+  def validate_filename(raw_fname)
+    # When necessary add extension to file name
+    fname = raw_fname.dup
+    basename = File.basename(fname)
+    has_extension = basename =~ /(?<=[^.])\.[^.]+$/
+    fname << '.' << DefaultLoxExtension unless has_extension
+
+    fname
+  end
+
+  def file_exist?(fname)
+    exists = File.exist?(fname)
+    $stderr.puts "No such file '#{fname}'" unless exists
+
+    exists
+  end
+end # class
+
+########################################
+# ENTRY POINT
+########################################
+program = LoxxyRunner.new(File.basename(__FILE__), ARGV)
+
+# All options from CLI gobbled from ARGV, remains only file name
+program.run!(ARGV)
+# End of file

data/lib/loxxy.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'loxxy/version'
+require_relative 'loxxy/cli_parser'
 require_relative 'loxxy/interpreter'
 require_relative 'loxxy/front_end/raw_parser'
 

data/lib/loxxy/cli_parser.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'optparse' # Use standard OptionParser class for command-line parsing
+
+module Loxxy
+  # A command-line option parser for the Loxxy interpreter.
+  # It is a specialisation of the OptionParser class.
+  class CLIParser < OptionParser
+    # @return [Hash{Symbol=>String, Array}]
+    attr_reader(:parsed_options)
+
+    # Constructor.
+    def initialize(prog_name, ver)
+      super()
+      reset(prog_name, ver)
+
+      heading
+      separator 'Options:'
+      separator ''
+      add_tail_options
+    end
+
+    def parse!(args)
+      super
+      parsed_options
+    end
+
+    private
+
+    def reset(prog_name, ver)
+      @program_name = prog_name
+      @version = ver
+      @banner = "Usage: #{prog_name} LOX_FILE [options]"
+      @parsed_options = {}
+    end
+
+    def description
+      <<-DESCR
+  Description:
+    loxxy is a Lox interpreter, it executes the Lox file(s) given in command-line.
+    More on Lox Language: https://craftinginterpreters.com/the-lox-language.html
+
+  Example:
+    #{program_name} hello.lox
+      DESCR
+    end
+
+    def heading
+      banner
+      separator ''
+      separator description
+      separator ''
+    end
+
+    def add_tail_options
+      on_tail('--version', 'Display the program version then quit.') do
+        puts version
+        exit(0)
+      end
+
+      on_tail('-?', '-h', '--help', 'Display this help then quit.') do
+        puts help
+        exit(0)
+      end
+    end
+  end # class
+end # module
+# End of file

data/lib/loxxy/version.rb

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

data/loxxy.gemspec

@@ -41,7 +41,11 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Dimitri Geshef']
   spec.email         = ['famished.tiger@yahoo.com']
   spec.summary       = 'An implementation of the Lox programming language.'
-  spec.description   = 'An implementation of the Lox programming language.'
+  spec.description   = <<-DESCR_END
+  A Ruby implementation of the Lox programming language. Lox is a dynamically typed,
+  object-oriented programming language that features first-class functions, closures,
+  classes, and inheritance.
+  DESCR_END
   spec.homepage      = 'https://github.com/famished-tiger/loxxy'
   spec.license       = 'MIT'
   spec.required_ruby_version = '~> 2.4'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: loxxy
 version: !ruby/object:Gem::Version
-  version: 0.2.00
+  version: 0.2.01
 platform: ruby
 authors:
 - Dimitri Geshef
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-17 00:00:00.000000000 Z
+date: 2021-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rley
@@ -66,7 +66,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: An implementation of the Lox programming language.
+description: |2
+    A Ruby implementation of the Lox programming language. Lox is a dynamically typed,
+    object-oriented programming language that features first-class functions, closures,
+    classes, and inheritance.
 email:
 - famished.tiger@yahoo.com
 executables:
@@ -125,6 +128,7 @@ files:
 - lib/loxxy/back_end/symbol_table.rb
 - lib/loxxy/back_end/unary_operator.rb
 - lib/loxxy/back_end/variable.rb
+- lib/loxxy/cli_parser.rb
 - lib/loxxy/datatype/all_datatypes.rb
 - lib/loxxy/datatype/boolean.rb
 - lib/loxxy/datatype/builtin_datatype.rb