sweet-moon 0.0.4 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdfabe100158948ea2c29fadca09e82cd9567d71230627f6bd0e8ba3a04f523d
-  data.tar.gz: 3bb2925b0ef437c3942a837a67bb94261d89c9aaf5a011973dcf4b98db07e6b9
+  metadata.gz: 880cceae5913b9a748b5b318bfc27c56ccf58d7ae54b7f31f8aeea943c524aac
+  data.tar.gz: ab2abc87ef9ead4ea7be474963a92ad647326ec6d4ad1bfec62ed20d103d4e4c
 SHA512:
-  metadata.gz: 582a792771b05e59a577349070709e78bb2a569ef14cdb955fb2666e826eb401ba4aa4e7b19297c30fd64f98eda244d656caf2e904f9c1af95e971807aed8820
-  data.tar.gz: 38307987e564f998b40b2792fd97a3e107095d6e46992689663d63d67bf248dfc16c3a8838f8461bf7a8765857e7b5c04da4e4ac3c636cd6a419abb85bab2e5b
+  metadata.gz: 1b613dba97c24527e3e71a8bd7c6d14cd98edcd9a0083a85463a3300f05886a81da33ea5c515108fe523ed43ab012760954edd40dacec4aa38a250e6846b3906
+  data.tar.gz: c8c09f0f1bc7cde58c789975b84491399af843b8d95cb69bd3600dbb4c22a056f232e99eea50d3af969ebea6fa298bd86214a596d7ab67afe5c4a209d8a43fa3

data/.rubocop.yml

@@ -5,6 +5,9 @@ AllCops:
 Style/Documentation:
   Enabled: false
 
+Lint/RescueException:
+  Exclude: ['components/interpreters/**/function.rb']
+
 Layout/LineLength:
   Max: 86
   Exclude: ['spec/**/*', 'logic/signatures/*']

data/README.md

@@ -28,10 +28,14 @@ _Sweet Moon_ is a resilient solution that makes working with [Lua](https://www.l
 - [Fennel](#fennel)
   - [Fennel Usage](#fennel-usage)
   - [Fennel Global vs Local Variables](#fennel-global-vs-local-variables)
+  - [allowedGlobals and options](#allowedglobals-and-options)
   - [Fennel Setup](#fennel-setup)
   - [Integration with fnx](#integration-with-fnx)
+  - [Fennel REPL](#fennel-repl)
 - [Global vs Isolated](#global-vs-isolated)
+- [Global FFI](#global-ffi)
 - [Error Handling](#error-handling)
+  - [Ruby feat. Lua Errors](#ruby-feat-lua-errors)
 - [Where can I find .so files?](#where-can-i-find-so-files)
 - [Low-Level C API](#low-level-c-api)
   - [The API](#the-api)
@@ -71,7 +75,7 @@ gem install sweet-moon
 > **Disclaimer:** It's an early-stage project, and you should expect breaking changes.
 
 ```ruby
-gem 'sweet-moon', '~> 0.0.4'
+gem 'sweet-moon', '~> 0.0.7'
 ```
 
 ```ruby
@@ -442,6 +446,16 @@ second = state.get(:second)
 second.([%w[a b c]]) # => 'b'
 ```
 
+Alternatively, you can send the `outputs` parameter:
+
+```ruby
+require 'sweet-moon'
+
+state = SweetMoon::State.new
+
+state.eval('return "a", "b"', { outputs: 2 }) # => ['a', 'b']
+```
+
 You can call Ruby _Lambdas_ from _Lua_ as well:
 
 ```ruby
@@ -612,21 +626,21 @@ state.add_package_path('/home/me/my-lua-modules/?/init.lua')
 
 state.add_package_cpath('/home/me/my-lua-modules/?.so')
 
-state.add_package_path('/home/me/fennel.lua')
+state.add_package_path('/home/me/fennel/?.lua')
 
-state.add_package_cpath('/home/me/lib.so')
+state.add_package_cpath('/home/me/?.so')
 
 state.package_path
 # => ['./?.lua',
  #    './?/init.lua',
  #    '/home/me/my-lua-modules/?.lua',
  #    '/home/me/my-lua-modules/?/init.lua',
- #    '/home/me/fennel.lua']
+ #    '/home/me/fennel/?.lua']
 
 state.package_cpath
 # => ['./?.so',
 #     '/home/me/my-lua-modules/?.so',
-#     '/home/me/lib.so']
+#     '/home/me/?.so']
 ```
 
 Requiring a module:
@@ -646,8 +660,8 @@ You can set packages in State constructors:
 require 'sweet-moon'
 
 SweetMoon::State.new(
-  package_path: '/folder/lib.lua',
-  package_cpath: '/lib/lib.so',
+  package_path: '/folder/lib/?.lua',
+  package_cpath: '/lib/lib/?.so',
 )
 ```
 
@@ -657,8 +671,8 @@ Also, you can add packages through the global config:
 require 'sweet-moon'
 
 SweetMoon.global.config(
-  package_path: '/folder/lib.lua',
-  package_cpath: '/lib/lib.so',
+  package_path: '/folder/lib/?.lua',
+  package_cpath: '/lib/lib/?.so',
 )
 ```
 
@@ -818,6 +832,71 @@ fennel.eval('var-b') # => nil
 fennel.eval('_G.var-b') # => 35
 ```
 
+### allowedGlobals and options
+
+As Lua, Fennel functions may return [multiple results](https://www.lua.org/pil/5.1.html), so `eval` and `load` accept a second parameter to indicate the expected number of outputs:
+
+```fnl
+; source.fnl
+
+(fn multi [] (values "c" "d"))
+
+(multi)
+```
+
+```ruby
+require 'sweet-moon'
+
+fennel = SweetMoon::State.new.fennel
+
+fennel.eval('(values "a" "b")', 2) # => ['a', 'b']
+fennel.load('source.fnl', 2) # => ['c', 'd']
+```
+
+The Fennel API offers [some options](https://fennel-lang.org/api) that `eval` and `load` accept as a third parameter:
+
+```ruby
+require 'sweet-moon'
+
+fennel = SweetMoon::State.new.fennel
+
+fennel.eval('(print (+ 2 3))', 1, { allowedGlobals: ['print'] }) # => 5
+
+fennel.eval('(print (+ 2 3))', 1, { allowedGlobals: [] })
+# Compile error in unknown:1 (SweetMoon::Errors::LuaRuntimeError)
+#   unknown identifier in strict mode: print
+
+# (print (+ 2 3))
+#  ^^^^^
+# * Try looking to see if there's a typo.
+# * Try using the _G table instead, eg. _G.print if you really want a global.
+# * Try moving this code to somewhere that print is in scope.
+# * Try binding print as a local in the scope of this code.
+```
+
+Alternatively, you can use the second parameter for options as well:
+
+```ruby
+require 'sweet-moon'
+
+fennel = SweetMoon::State.new.fennel
+
+fennel.eval('(print (+ 2 3))', { allowedGlobals: ['print'] }) # => 5
+```
+
+You can also specify the expected outputs in the options parameter (it will be removed and not forwarded to Fennel):
+
+```ruby
+require 'sweet-moon'
+
+fennel = SweetMoon::State.new.fennel
+
+fennel.eval(
+  '(values "a" "b")',
+  { allowedGlobals: ['values'], outputs: 2 }
+) # => ['a', 'b']
+```
+
 ### Fennel Setup
 
 To ensure that the Fennel module is available, you can set up the [_LuaRocks_](#integration-withluarocks) integration or manually add the `package_path` for the module.
@@ -831,7 +910,7 @@ require 'sweet-moon'
 
 state = SweetMoon::State.new
 
-state.add_package_path('/folder/fennel.lua')
+state.add_package_path('/folder/fennel/?.lua')
 
 state.fennel.eval('(+ 1 1)') # => 2
 ```
@@ -841,7 +920,7 @@ With the constructor:
 ```ruby
 require 'sweet-moon'
 
-fennel = SweetMoon::State.new(package_path: '/folder/fennel.lua').fennel
+fennel = SweetMoon::State.new(package_path: '/folder/fennel/?.lua').fennel
 
 fennel.eval('(+ 1 1)') # => 2
 ```
@@ -851,7 +930,7 @@ With global:
 ```ruby
 require 'sweet-moon'
 
-SweetMoon.global.state.add_package_path('/folder/fennel.lua')
+SweetMoon.global.state.add_package_path('/folder/fennel/?.lua')
 
 SweetMoon.global.state.fennel.eval('(+ 1 1)') # => 2
 ```
@@ -861,7 +940,7 @@ Alternatively:
 ```ruby
 require 'sweet-moon'
 
-SweetMoon.global.config(package_path: '/folder/fennel.lua')
+SweetMoon.global.config(package_path: '/folder/fennel/?.lua')
 
 SweetMoon.global.state.fennel.eval('(+ 1 1)') # => 2
 ```
@@ -888,6 +967,44 @@ To enforce the path for the `.fnx.fnl` file:
 fennel.eval('(let [fnx (require :fnx)] (fnx.bootstrap! "/project/.fnx.fnl"))')
 ```
 
+### Fennel REPL
+
+In Ruby, you can start a [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) at any time somewhere in your code with [_pry_](https://github.com/pry/pry):
+
+```ruby
+require 'pry'
+
+binding.pry
+```
+
+The same is true for Fennel, you just need to:
+```fnl
+(let [fennel (require :fennel)]
+  (fennel.repl {}))
+```
+
+Fennel's REPL won't have your _local_ values. But, you can tweak it to receive values to be checked inside the REPL:
+
+```fnl
+(fn my-repl [to-expose]
+  (let [fennel (require :fennel) env _G]
+    (each [key value (pairs to-expose)] (tset env key value))
+    (fennel.repl {:env env})))
+
+(local value "some value")
+
+(my-repl {:value value})
+
+; Inside the REPL:
+
+; >> value
+; "some value"
+```
+
+You can install [_readline_](https://luarocks.org/modules/peterbillam/readline) for a better experience, e.g., autocompleting.
+
+> _Check [Fennel's documentation](https://fennel-lang.org/api#start-a-configurable-repl) to learn more about the REPL._
+
 ## Global vs Isolated
 
 You can use the **global** helper that provides an _API_ and a _State_ for quick-and-dirty coding. It uses internally a Ruby [_Singleton_](https://docs.ruby-lang.org/en/3.1/Singleton.html):
@@ -934,6 +1051,8 @@ api_5.luaL_newstate
 api_3.luaH_new
 ```
 
+> _Check the caveats related to [_Global FFI_](#global-ffi) when working with multiple versions._
+
 On the other hand, using the **global** _State_ may lead to a lot of issues. You need to consider from simple things – _"If I load two different files, the first file may impact the state of the second one?"_ – to more complex ones like multithreading, concurrency, etc.
 
 So, you can at any time create a new isolated _State_ and destroy it when you don't need it anymore:
@@ -963,6 +1082,48 @@ state_5.eval('return _VERSION') # => Lua 5.4
 state_3.eval('return _VERSION') # => Lua 3.2
 ```
 
+> _Check the caveats related to [_Global FFI_](#global-ffi) when working with multiple versions._
+
+## Global FFI
+
+Some Lua libraries (e.g., [_readline_](https://pjb.com.au/comp/lua/readline.html) and [_luafilesystem_](https://keplerproject.github.io/luafilesystem/)) require the Lua C API functions available in the global C environment.
+
+By default, _Sweet Moon_ enables [_Global FFI_](https://github.com/ffi/ffi/wiki/Loading-Libraries#function-visibility) to reduce friction when using popular libraries.
+
+Using distinct Lua versions simultaneously with multiple _Shared Objects_ may be dangerous in this setup: Two APIs with the same name functions could be an issue because something will be overwritten.
+
+Also, libraries that need Lua C API functions are compiled for a specific Lua version. If you are, e.g., using _LuaJIT_ and your library expects the _Standard Lua_, you may face issues.
+
+You can disable _Global FFI_ at any time with:
+
+```ruby
+require 'sweet-moon'
+
+SweetMoon.global.config(global_ffi: false)
+
+SweetMoon::State.new(global_ffi: false)
+
+SweetMoon::API.new(global_ffi: false)
+```
+
+To check if it's enabled or not:
+
+```ruby
+require 'sweet-moon'
+
+SweetMoon.global.api.meta.global_ffi # => true
+SweetMoon.global.state.meta.global_ffi # => true
+
+SweetMoon::API.new.meta.global_ffi # => true
+
+SweetMoon::State.new.meta.global_ffi # => true
+```
+
+**Caveats:**
+
+Binding globally a C API is irreversible, so if you start something with `global_ffi: true` and then change to `global_ffi: false`, it won't make the global one disappear. If you need _local_, ensure that you do it from the first line and never put anything as global throughout the entire program life cycle.
+
+Also, the simple action of accessing `meta.global_ff` will bind the API, so you need to set your desired configuration before checking.
 
 ## Error Handling
 
@@ -1007,6 +1168,108 @@ rescue LuaRuntimeError => error
 end
 ```
 
+### Ruby feat. Lua Errors
+
+Lua errors can be rescued inside Ruby:
+
+```lua
+-- source.lua
+error('error from lua')
+```
+
+```ruby
+require 'sweet-moon'
+require 'sweet-moon/errors'
+
+state = SweetMoon::State.new
+
+begin
+  state.load('source.lua')
+rescue LuaRuntimeError => e
+  puts e.message
+  # => source.lua:2: error from lua
+end
+```
+
+Ruby errors can be handled inside Lua:
+
+```ruby
+require 'sweet-moon'
+
+state = SweetMoon::State.new
+
+state.set(:rubyFn, -> { raise 'error from ruby' })
+
+state.load('source.lua')
+```
+
+```lua
+-- source.lua
+local status, err = pcall(rubyFn)
+
+print(status) -- => false
+
+print(err)
+-- [string "    return function (...)..."]:5: RuntimeError: error from ruby stack traceback:
+--         [string "    return function (...)..."]:5: in function 'rubyFn'
+--         [C]: in function 'pcall'
+--         source.lua:2: in main chunk
+```
+
+Ruby errors not handled inside Lua can be rescued inside Ruby again, with an additional Lua backtrace:
+
+```lua
+-- source.lua
+a = 1
+
+rubyFn()
+```
+
+```ruby
+require 'sweet-moon'
+
+state = SweetMoon::State.new
+
+state.set(:rubyFn, -> { raise 'error from ruby' })
+
+begin
+  state.load('source.lua')
+rescue RuntimeError => e
+  puts e.message # => error from ruby
+
+  puts e.backtrace.last
+  # => source.lua:4: in main chunk
+end
+```
+
+Lua errors inside Lua functions can be rescued inside Ruby:
+
+```lua
+-- source.lua
+function luaFn()
+  error('lua function error')
+end
+```
+
+```ruby
+require 'sweet-moon'
+require 'sweet-moon/errors'
+
+state = SweetMoon::State.new
+
+state.load('source.lua')
+
+lua_fn = state.get(:luaFn)
+
+begin
+  lua_fn.()
+rescue LuaRuntimeError => e
+  puts e.message # => "source.lua:3: lua function error"
+end
+```
+
+For Fennel, all the examples above are equally true, with additional stack traceback as well.
+
 ## Where can I find .so files?
 
 Due to the Lua's popularity, you likely have it already on your system, and _Sweet Moon_ will be able to find the files by itself.
@@ -1261,6 +1524,8 @@ Update the [`config/tests.yml`](https://github.com/gbaptista/sweet-moon/blob/mai
 
 Alternatively: Find or build the _Shared Objects_ for your Operating System on your own.
 
+Install the expected Lua _rocks_ described in `config/tests.yml`.
+
 ### Running
 
 ```sh

data/components/api.rb

@@ -2,7 +2,7 @@ require 'ffi'
 
 module Component
   API = {
-    open!: ->(shared_objects) {
+    open!: ->(shared_objects, options = {}, default = {}) {
       api = Module.new
 
       api.extend FFI::Library
@@ -10,8 +10,11 @@ module Component
       # TODO: Lua Constants
       # attach_variable
 
-      if shared_objects.size > 1
-        # TODO: Dangerous
+      global_ffi = default[:global_ffi]
+
+      global_ffi = options[:global_ffi] unless options[:global_ffi].nil?
+
+      if global_ffi
         api.ffi_lib_flags(:global, :now)
       else
         api.ffi_lib_flags(:local, :now)

data/components/default.rb

@@ -0,0 +1,17 @@
+require 'singleton'
+
+module Component
+  class Default
+    include Singleton
+
+    attr_reader :options
+
+    def initialize
+      @options = { global_ffi: true }
+    end
+
+    def set(key, value)
+      @options[key.to_sym] = value
+    end
+  end
+end

data/components/injections/injections_503.rb

@@ -6,7 +6,8 @@ module Component
           ffi: [:cfunction, [:pointer], :int],
           overwrite: {
             lua_pushcclosure: [%i[pointer cfunction int], :void],
-            lua_tocfunction: [%i[pointer int], :cfunction]
+            lua_tocfunction: [%i[pointer int], :cfunction],
+            lua_atpanic: [%i[pointer cfunction], :cfunction]
           }
         }
       ],

data/components/injections/injections_514.rb

@@ -6,7 +6,8 @@ module Component
           ffi: [:cfunction, [:pointer], :int],
           overwrite: {
             lua_pushcclosure: [%i[pointer cfunction int], :void],
-            lua_tocfunction: [%i[pointer int], :cfunction]
+            lua_tocfunction: [%i[pointer int], :cfunction],
+            lua_atpanic: [%i[pointer cfunction], :cfunction]
           }
         }
       ],

data/components/injections/injections_542.rb

@@ -6,7 +6,8 @@ module Component
           ffi: [:cfunction, [:pointer], :int],
           overwrite: {
             lua_pushcclosure: [%i[pointer cfunction int], :void],
-            lua_tocfunction: [%i[pointer int], :cfunction]
+            lua_tocfunction: [%i[pointer int], :cfunction],
+            lua_atpanic: [%i[pointer cfunction], :cfunction]
           }
         }
       ],

data/components/interpreters/50/function.rb

@@ -1,55 +1,19 @@
-require_relative '../../../logic/interpreters/interpreter_50'
-require_relative '../../../dsl/errors'
-
-require_relative 'writer'
-require_relative 'reader'
+require_relative '../54/function'
 
 module Component
   module V50
-    Function = {
-      push!: ->(api, state, closure) {
-        handler = ->(current_state) {
-          updated_state = state.merge(lua: current_state)
-          input = Reader[:read_all!].(api, updated_state)
-          result = closure.(*input)
-          Writer[:push!].(api, updated_state, result)
-          return 1
-        }
-
-        state[:avoid_gc] << handler
-
-        api.lua_pushcclosure(state[:lua], handler, 0)
-      },
-
-      read!: ->(api, state, _stack_index) {
-        reference = api.luaL_ref(
-          state[:lua], Logic::V50::Interpreter[:LUA_REGISTRYINDEX]
-        )
-
-        { value: ->(input = [], output = 1) {
-          api.lua_rawgeti(
-            state[:lua], Logic::V50::Interpreter[:LUA_REGISTRYINDEX], reference
-          )
-
-          input.each do |value|
-            Writer[:push!].(api, state, value)
-          end
-
-          result = Interpreter[:call!].(api, state, input.size, output)
-
-          if result[:error]
-            raise SweetMoon::Errors::SweetMoonErrorHelper.for(
-              result[:error][:status]
-            ), result[:error][:value]
-          end
-
-          result = Reader[:read_all!].(api, state)
-
-          return result.first if output == 1
-
-          result
-        }, pop: false }
-      }
-    }
+    Function = Component::V54::Function
+
+    LUA_HANDLER = <<~LUA
+      return function (...)
+        result = _ruby(unpack(arg))
+
+        if result['error'] then
+          error(result['output'])
+        else
+          return result['output']
+        end
+      end
+    LUA
   end
 end

data/components/interpreters/50/interpreter.rb

@@ -1,17 +1,19 @@
 require_relative '../../../logic/interpreters/interpreter_50'
 
+require_relative 'function'
 require_relative 'reader'
-require_relative 'writer'
 require_relative 'table'
+require_relative 'writer'
 
 module Component
   module V50
     Interpreter = {
       version: Logic::V50::Interpreter[:version],
+      logic: Logic::V50,
 
       create_state!: ->(api) {
         state = api.lua_open
-        { state: { lua: state, avoid_gc: [] },
+        { state: { lua: state, avoid_gc: [], ruby_error_info: nil },
           error: state ? nil : :MemoryAllocation }
       },
 
@@ -48,7 +50,7 @@ module Component
       },
 
       push_value!: ->(api, state, value) {
-        Writer[:push!].(api, state, value)
+        Writer[:push!].(api, state, Component::V50, value)
         { state: state }
       },
 
@@ -70,7 +72,10 @@ module Component
         api.lua_pushstring(state[:lua], variable.to_s)
         api.lua_gettable(state[:lua], Logic::V50::Interpreter[:LUA_GLOBALSINDEX])
 
-        Table[:read_field_and_push!].(api, state, key, -1) unless key.nil?
+        unless key.nil?
+          Table[:read_field_and_push!].(api, state, Component::V50, key,
+                                        -1)
+        end
 
         { state: state, extra_pop: extra_pop }
       },
@@ -81,7 +86,8 @@ module Component
       },
 
       read_and_pop!: ->(api, state, stack_index = -1, extra_pop: false) {
-        result = Component::V50::Reader[:read!].(api, state, stack_index)
+        result = Component::V50::Reader[:read!].(api, state, Component::V50,
+                                                 stack_index)
 
         api.lua_settop(state[:lua], -2) if result[:pop]
         api.lua_settop(state[:lua], -2) if extra_pop
@@ -90,7 +96,7 @@ module Component
       },
 
       read_all!: ->(api, state) {
-        result = Reader[:read_all!].(api, state)
+        result = Reader[:read_all!].(api, state, Component::V50)
 
         { state: state, output: result }
       },