loxby 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c24f85fecb8840b0c2b6331b6b4dda6c5a4899e830d81f52ed6ffa12065b432
-  data.tar.gz: 3b694bcad715f645c52501d192944c207932d71909189f0b9f2dd0eae9e3d392
+  metadata.gz: 425095fb701b73736edd3558262a10753ae0b900389f47a5dcf50e77b556ad97
+  data.tar.gz: 05c522b5c1d6b099fe73748ddf8d041e6b49cf64335d727c3b5e251beced24c2
 SHA512:
-  metadata.gz: 14167ca0449fa15e8b5eba780ab63af4d9b702c9b762c8bb3d2724840549481a25ba1806a4d5702e8ed0b925518872a1ec72ec17db0bc7f8170011d1891e9903
-  data.tar.gz: 6b8366382f8c51bffdfe71802a0b551aee4938e0880c878012778c8508094544a9f1c02ca1f7dde57dcc1e03919545387b652877dc2ea38266c8422d6ba89b14
+  metadata.gz: 4ffca94d2a7d18ce137f7b1fda7fd09ef76530c361e5553df0bfb4764e8d5876f4f442b219c8393bc6708d76e10a4acfc41146c535e13ec89ff9f9bcea4e525a
+  data.tar.gz: 570bbfcc023ca9c697717c8a91810411b89c333e1e2f452970cfe500ed4d845c7b094ac8ca9ed2997e79b583c7b236edbb1a9a2f8b49f2bb20003a657ca51523

data/.github/workflows/gem-push.yml

@@ -12,12 +12,12 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Ruby 3.1
+    - name: Set up Ruby
     # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
     # change this to (see https://github.com/ruby/setup-ruby#versioning):
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: 3.1.3
+        ruby-version: 3.3.5
 
     - name: Publish to GPR
       run: |

data/.gitignore

@@ -0,0 +1,8 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.ruby-version

@@ -0,0 +1 @@
+3.3.5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Paul Hartman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -10,4 +10,7 @@ Loxby is written following the first half of Robert Nystrom's wonderful web-form
     ```ruby
     require 'loxby/runner'
     Lox::Runner.new(ARGV, $stdout, $stderr)
-    ```
+    ```
+
+## License
+This gem is licensed under the [MIT License](https://opensource.org/license/mit). See LICENSE.txt for more.

data/bin/loxby

@@ -4,5 +4,5 @@
 require 'bundler/setup'
 require 'loxby/runner'
 
-# Start interpreter when run as script
-Lox::Runner.new.run(ARGV) if __FILE__ == $PROGRAM_NAME
+# Start interpreter
+Lox::Runner.new.run(ARGV)

data/lib/loxby/config.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'dry-configurable'
+require_relative 'helpers/errors'
+
+class Lox # rubocop:disable Style/Documentation
+  extend Dry::Configurable
+
+  setting :scanner do
+    setting :expressions do
+      setting :whitespace, default: /\s/
+      setting :number_literal, default: /\d/
+      setting :identifier, default: /[a-zA-Z_]/
+    end
+
+    setting :keywords,
+            default: %w[and class else false for fun if nil or print return super this true var while break]
+  end
+
+  setting :token_types do
+    setting :tokens, default: [
+      # Single-character tokens.
+      :left_paren, :right_paren, :left_brace, :right_brace,
+      :comma, :dot, :minus, :plus, :semicolon, :slash, :star,
+      :question, :colon,
+
+      # 1-2 character tokens.
+      :bang, :bang_equal,
+      :equal, :equal_equal,
+      :greater, :greater_equal,
+      :less, :less_equal,
+
+      # Literals.
+      :identifier, :string, :number,
+
+      # Keywords.
+      :and, :class, :else, :false, :fun, :for, :if, :nil, :or,
+      :print, :return, :super, :this, :true, :var, :while, :break,
+
+      :eof
+    ].freeze
+
+    setting :single_tokens,
+            default: '(){},.-+;/*?:',
+            constructor: -> { _1.split('').zip(Lox.config.token_types.tokens).to_h }
+  end
+
+  setting :native_functions do
+    setting :clock do
+      setting :arity, default: 0
+      setting :block, default: ->(_, _) { Time.now.to_i.to_f }
+    end
+    setting :exit do
+      setting :arity, default: 0
+      setting :block, default: ->(_, _) { throw :lox_exit }
+    end
+  end
+
+  setting :ast do
+    setting :expression,
+            default: {
+              assign: [%i[token name], %i[expr value]],
+              binary: [%i[expr left], %i[token operator], %i[expr right]],
+              ternary: [%i[expr left], %i[token left_operator], %i[expr center], %i[token right_operator],
+                        %i[expr right]],
+              call: [%i[expr callee], %i[token paren], %i[expr_list arguments]],
+              grouping: [%i[expr expression]],
+              literal: [%i[object value]],
+              logical: [%i[expr left], %i[token operator], %i[expr right]],
+              unary: [%i[token operator], %i[expr right]],
+              variable: [%i[token name]]
+            }
+    setting :statement,
+            default: {
+              block: [%i[stmt_list statements]],
+              expression: [%i[expr expression]],
+              function: [%i[token name], %i[token_list params], %i[stmt_list body]],
+              if: [%i[expr condition], %i[stmt then_branch], %i[stmt else_branch]],
+              print: [%i[expr expression]],
+              return: [%i[token keyword], %i[expr value]],
+              var: [%i[token name], %i[expr initializer]],
+              while: [%i[expr condition], %i[stmt body]],
+              break: []
+            }
+  end
+
+  setting :exit_code do
+    setting :interrupt, default: 130
+    setting :usage, default: 64
+    setting :syntax_error, default: 65
+    setting :runtime_error, default: 70
+  end
+end

data/lib/loxby/core.rb

@@ -4,6 +4,7 @@ require_relative 'scanner'
 require_relative 'parser'
 require_relative 'interpreter'
 require_relative 'helpers/token_type'
+require_relative 'config'
 
 # Lox interpreter.
 # Each interpreter keeps track of its own
@@ -13,36 +14,45 @@ class Lox
   attr_reader :errored, :interpreter
 
   def initialize
+    # Whether an error occurred while parsing.
     @errored = false
+    # Whether an error occurred while interpreting
     @errored_in_runtime = false
-    @interpreter = Interpreter.new(self) # Make static so REPL sessions reuse it
+    # `Lox::Interpreter` instance. Static so interactive sessions reuse it
+    @interpreter = Interpreter.new(self)
   end
 
-  # Run from file
+  # Parse and run a file
   def run_file(path)
     if File.exist? path
-      run File.read(path)
+      catch(:lox_exit) do
+        run File.read(path)
+      end
     else
       report(0, '', "No such file: '#{path}'")
     end
-    exit(65) if @errored # Don't execute malformed code
-    exit(70) if @errored_in_runtime
+    exit Lox.config.exit_code.syntax_error if @errored # Don't execute malformed code
+    exit Lox.config.exit_code.runtime_error if @errored_in_runtime
   end
 
-  # Run interactively
+  # Run interactively, REPL-style
   def run_prompt
-    loop do
-      print '> '
-      line = gets
-      break unless line # Trap eof (Ctrl+D unix, Ctrl+Z win)
+    catch(:lox_exit) do
+      loop do
+        print '> '
+        line = gets
+        break unless line # Trap eof (Ctrl+D unix, Ctrl+Z win)
 
-      result = run(line)
-      puts "=> #{@interpreter.lox_obj_to_str result}" unless @errored
-      @errored = false # Reset so a mistake doesn't kill the repl
+        result = run(line)
+        puts "=> #{@interpreter.lox_obj_to_str result}" unless @errored
+
+        # When run interactively, resets after every prompt so as to not kill the repl
+        @errored = false
+      end
     end
   end
 
-  # Run a string
+  # Parse and run a string
   def run(source)
     tokens = Scanner.new(source, self).scan_tokens
     parser = Parser.new(tokens, self)

data/lib/loxby/helpers/ast.rb

@@ -16,17 +16,22 @@ end
 
 class Lox
   # Interface:
+  # ```ruby
   #   Lox::AST.define_ast(
   #     "ASTBaseClass",
   #     {
-  #       :ast_type => [[:field_one_type, :field_one_name], [:field_two_type, :field_two_name]],
+  #       :ast_type => [
+  #         [:field_one_type, :field_one_name],
+  #         [:field_two_type, :field_two_name]
+  #       ],
   #       :other_ast_type => [[:field_type, :field_name]]
   #     }
   #   )
+  # ```
   #
-  # This defines Lox::AST::ASTBaseClass, which ::AstType and ::OtherAstType descend from
-  # and are scoped under. It also defines the Visitor pattern: AstType defines #accept(visitor),
-  # which calls `visitor.visit_ast_type(self)`
+  # This call to `#define_ast` generates `Lox::AST::ASTBaseClass`, as well as `::AstType` and
+  # `::OtherAstType` descending from and scoped uner it. Generated classes follow the Visitor
+  # pattern: `::AstType` generates with `#accept(visitor)` which calls `visitor.visit_ast_type(self)`.
   module AST
     module_function
 
@@ -43,19 +48,19 @@ class Lox
       define_class base_name.to_camel_case, base_class
     end
 
-    def define_type(base_class, base_class_name, subtype_name, fields) # rubocop:disable Metrics/MethodLength
+    def define_type(base_class, base_class_name, subtype_name, fields) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
       subtype = Class.new(base_class)
       parameters = fields.map { _1[1].to_s }
 
       subtype.class_eval <<~RUBY, __FILE__, __LINE__ + 1
         include Visitable # Visitor pattern
-        attr_reader #{parameters.map { ":#{_1}" }.join(', ')}
+        #{parameters.empty? ? '' : 'attr_reader '}#{parameters.map { ":#{_1}" }.join(', ')}
         def initialize(#{parameters.map { "#{_1}:" }.join(', ')})
-          #{parameters.map { "@#{_1}" }.join(', ')} = #{parameters.join ', '}
+          #{parameters.map { "@#{_1}" }.join(', ')}#{parameters.empty? ? '' : ' = '}#{parameters.join ', '}
         end
 
-        # Dynamically generated for visitor pattern.
-        # Expects visitor to define #visit_#{subtype_name}
+        # This function was dynamically generated for visitor pattern.
+        # Expects visitors to define `#visit_#{subtype_name}_#{base_class_name}`.
         def accept(visitor)
           visitor.visit_#{subtype_name}_#{base_class_name}(self)
         end
@@ -70,25 +75,7 @@ class Lox
   end
 end
 
-Lox::AST.define_ast(
-  :expression,
-  {
-    assign: [%i[token name], %i[expr value]],
-    binary: [%i[expr left], %i[token operator], %i[expr right]],
-    ternary: [%i[expr left], %i[token left_operator], %i[expr center], %i[token right_operator], %i[expr right]],
-    grouping: [%i[expr expression]],
-    literal: [%i[object value]],
-    unary: [%i[token operator], %i[expr right]],
-    variable: [%i[token name]]
-  }
-)
-
-Lox::AST.define_ast(
-  :statement,
-  {
-    block: [%i[stmt_list statements]],
-    expression: [%i[expr expression]],
-    print: [%i[expr expression]],
-    var: [%i[token name], %i[expr initializer]]
-  }
-)
+# Default AST specification for loxby.
+Lox.config.ast.values.each do |name, definition|
+  Lox::AST.define_ast(name, definition)
+end

data/lib/loxby/helpers/callable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class Lox
+  # The interface for callable objects
+  # in loxby. Currently just functions.
+  #
+  # To mark a class as callable, simply
+  # `include Lox::Callable`.
+  module Callable
+    def call(_interpreter, _arguments)
+      raise NotImplementedError, "#{self.class} has not implemented #call"
+    end
+
+    def arity
+      raise NotImplementedError, "#{self.class} has not implemented #arity"
+    end
+  end
+end

data/lib/loxby/helpers/environment.rb

@@ -3,9 +3,8 @@
 require_relative 'errors'
 
 class Lox
-  # Lox::Environment stores namespace for
-  # a Lox interpreter. Environments can be
-  # nested (for scope).
+  # Stores namespaces for a Lox interpreter.
+  # Environments can be nested (for scope).
   class Environment
     def initialize(enclosing = nil)
       @enclosing = enclosing
@@ -17,16 +16,26 @@ class Lox
     end
 
     def []=(name, value)
-      @values[name.lexeme] = value
+      set name.lexeme, value
     end
 
-    def exists?(name)
+    # Used to set a static association. For example:
+    #   env.set 'static_function_name', static_function
+    def set(name, value)
+      @values[name] = value
+    end
+
+    def declared?(name)
+      # We can't check for a dummy value
+      # since loxby uses `nil` as well
       @values.keys.member? name.lexeme
     end
 
     def [](name)
-      if exists? name
+      if @values[name.lexeme]
         @values[name.lexeme]
+      elsif declared? name
+        raise Lox::RunError.new(name, "Declared variable not initialized: '#{name.lexeme}'")
       elsif @enclosing
         @enclosing[name]
       else
@@ -35,7 +44,7 @@ class Lox
     end
 
     def assign(name, value)
-      if exists? name
+      if declared? name
         self[name] = value
       elsif @enclosing
         @enclosing.assign(name, value)
@@ -43,5 +52,7 @@ class Lox
         raise undefined_variable(name)
       end
     end
+
+    alias define []=
   end
 end

data/lib/loxby/helpers/errors.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
 class Lox
+  # A generic loxby error class raised
+  # when a syntax error is found.
   class ParseError < RuntimeError; end
 
-  class RunError < RuntimeError # rubocop:disable Style/Documentation
+  # A generic loxby error class raised
+  # when a runtime error is found.
+  class RunError < RuntimeError
     attr_reader :token
 
     def initialize(token, message)
@@ -12,5 +16,7 @@ class Lox
     end
   end
 
+  # A loxby error class raised when
+  # a number is divided by zero.
   class DividedByZeroError < RunError; end
 end

data/lib/loxby/helpers/functions.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'callable'
+require_relative 'environment'
+require_relative '../interpreter'
+
+class Lox
+  # A 'Function' is a loxby function.
+  #
+  # You could manually instantiate one,
+  # but why would you?
+  class Function
+    include Callable
+    attr_reader :declaration, :enclosure
+
+    def initialize(declaration, closure)
+      @declaration = declaration
+      @closure = closure
+    end
+
+    def call(interpreter, args)
+      env = Environment.new(@closure)
+      @declaration.params.zip(args).each do |param, arg|
+        env[param] = arg # Environment grabs the lexeme automatically
+      end
+
+      # Interpreter will `throw :return, return_value` to unwind
+      # callstack, jumping out of the `catch` block. `catch` then
+      # implicitly returns that value.
+      catch(:return) do
+        interpreter.execute_block @declaration.body, env
+        # If we get here, there was no return statement.
+        return nil
+      end
+    end
+
+    def arity = @declaration.params.size
+    def to_s = "<fn #{@declaration.name ? @declaration.name.lexeme : '(anonymous)'}>"
+  end
+end

data/lib/loxby/helpers/native_functions.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative '../interpreter'
+require_relative 'callable'
+require_relative '../visitors/base'
+
+class Interpreter < Visitor # rubocop:disable Style/Documentation
+  # A `NativeFunction` is a loxby function
+  # which references a callable Ruby
+  # object (block, proc, method, etc.).
+  #
+  # For example:
+  # ```ruby
+  # @environment.set(
+  #   'clock',
+  #   NativeFunction.new(0) do |_interpreter, _args|
+  #     Time.now.to_i.to_f
+  #   end
+  # )
+  # ```
+  class NativeFunction
+    include Lox::Callable
+    def initialize(given_arity = 0, &block)
+      @block = block
+      @arity = given_arity
+    end
+
+    def call(interpreter, args) = @block.call(interpreter, args)
+
+    def arity
+      if @arity.respond_to? :call
+        @arity.call
+      else
+        @arity
+      end
+    end
+
+    def to_s
+      '<native fn>'
+    end
+  end
+
+  def define_native_functions
+    Lox.config.native_functions.values.each do |name, func|
+      @globals.set name.to_s, NativeFunction.new(func.arity, &func.block)
+    end
+  end
+end

data/lib/loxby/helpers/token_type.rb

@@ -1,29 +1,17 @@
 # frozen_string_literal: true
 
+require_relative '../config'
+
 class Lox
+  # A single token. Emitted by
+  # `Lox::Scanner` and consumed
+  # by `Lox::Parser`.
   class Token
-    TOKENS = [
-      # Single-character tokens.
-      :left_paren, :right_paren, :left_brace, :right_brace,
-      :comma, :dot, :minus, :plus, :semicolon, :slash, :star,
-      :question, :colon,
-
-      # 1-2 character tokens.
-      :bang, :bang_equal,
-      :equal, :equal_equal,
-      :greater, :greater_equal,
-      :less, :less_equal,
-
-      # Literals.
-      :identifier, :string, :number,
-
-      # Keywords.
-      :and, :class, :else, :false, :fun, :for, :if, :nil, :or,
-      :print, :return, :super, :this, :true, :var, :while,
+    # List of all token types.
+    TOKENS = Lox.config.token_types.tokens
 
-      :eof
-    ].freeze
-    SINGLE_TOKENS = TOKENS.zip('(){},.-+;/*'.split('')).to_h
+    # Map of single-character token types.
+    SINGLE_TOKENS = Lox.config.token_types.single_tokens
 
     attr_reader :type, :lexeme, :literal, :line