sweet-moon 0.0.3 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79d7b00c236a8ce4b85d6cb4230d7e4e9714b0e537199fa3445254c0577b5bfa
-  data.tar.gz: befd1ae3a4bcec8a274a256b5aab3c690cf876df1167531a896650b956e7dc58
+  metadata.gz: 46891cd3e8103176f3f909415432df155df1bd33cbed89a80f0042f5d303a2b7
+  data.tar.gz: af7617e43eacc588135285dbd652f644d9bda8b87735c86ff89a7719ce6bfe1a
 SHA512:
-  metadata.gz: 05ff924f37bab331deb03a55e21b968384fd7755cc38d8b4780b45ec5a14d21487df64df1dea2122c41ad4dedfb4e8013964e926a826537e713aa253b923be90
-  data.tar.gz: 8d1266390a693ef67f8bf5209eb5b2cf2b997bddb1e9f90ba5e2030fadd9ddf5819f2411099173b7a4528eafdcd09b7157675bcff77e3ca864fe600018085355
+  metadata.gz: 1949e5f83c00dd65cdf78e2e8ebd4f66654dc24df1769add99ad8f01e75cc97bcb090e9d0dc0cf5d10dcdd4d1d338252b4ad78894bd3d4cef40b91ae31aab3d0
+  data.tar.gz: 9a09f1231c7e02250f232e368abd95b7bb1b4d5e366ef2614ce9871248c49201fb480b8b698833df66d769e7688602e8c3415a454366ef5ad3ede02163e1c5a4

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

@@ -21,15 +21,20 @@ _Sweet Moon_ is a resilient solution that makes working with [Lua](https://www.l
     - [Tables, Arrays, and Hashes](#tables-arrays-and-hashes)
     - [Functions](#functions)
     - [Other Types](#other-types)
+    - [Lua Global vs Local Variables](#lua-global-vs-local-variables)
   - [_destroy_ and _clear_](#destroy-and-clear)
 - [Modules, Packages and LuaRocks](#modules-packages-and-luarocks)
   - [Integration with LuaRocks](#integration-with-luarocks)
 - [Fennel](#fennel)
   - [Fennel Usage](#fennel-usage)
+  - [Fennel Global vs Local Variables](#fennel-global-vs-local-variables)
   - [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)
@@ -69,7 +74,7 @@ gem install sweet-moon
 > **Disclaimer:** It's an early-stage project, and you should expect breaking changes.
 
 ```ruby
-gem 'sweet-moon', '~> 0.0.3'
+gem 'sweet-moon', '~> 0.0.6'
 ```
 
 ```ruby
@@ -209,6 +214,7 @@ Compared to: [rufus-lua](https://github.com/jmettraux/rufus-lua), [YAML](https:/
   - [Tables, Arrays, and Hashes](#tables-arrays-and-hashes)
   - [Functions](#functions)
   - [Other Types](#other-types)
+  - [Lua Global vs Local Variables](#lua-global-vs-local-variables)
 - [_destroy_ and _clear_](#destroy-and-clear)
 
 ### Setup
@@ -389,6 +395,20 @@ state.eval('lua_value = {a = "text", b = 1.5, c = true}') # => nil
 state.get(:lua_value, :b) # => 1.5
 ```
 
+With `set`, you can use a second parameter to set a field:
+
+```ruby
+require 'sweet-moon'
+
+state = SweetMoon::State.new
+
+state.set(:myTable, {}) # => nil
+
+state.set(:myTable, :a, 3) # => nil
+
+state.eval('return myTable["a"]') # => 3
+```
+
 Caveats:
 
 - Ruby `Symbol` (e.g. `:value`) is converted to Lua `string`.
@@ -512,6 +532,24 @@ fennel_eval = state.get(:fennel_eval)
 fennel_eval.(['(+ 1 1)']) # => 2
 ```
 
+#### Lua Global vs Local Variables
+
+You can't exchange _local_ variables, only [_global_](https://www.lua.org/pil/1.2.html) ones:
+
+```ruby
+require 'sweet-moon'
+
+state = SweetMoon::State.new
+
+state.eval('lua_value = "Lua Text"') # => nil
+
+state.get('lua_value') # => 'Lua Text'
+
+state.eval('local lua_b = "b"') # => nil
+
+state.get('lua_b') # => nil
+```
+
 ## _destroy_ and _clear_
 
 You can destroy a state:
@@ -577,21 +615,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:
@@ -611,8 +649,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',
 )
 ```
 
@@ -622,8 +660,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',
 )
 ```
 
@@ -714,8 +752,8 @@ state = SweetMoon::State.new
 
 state.fennel.eval('(+ 1 2)') # => 3
 
-state.fennel.eval('(global mySum (fn [a b] (+ a b)))')
-state.fennel.eval('(mySum 2 3)') # => 5
+state.fennel.eval('(set _G.mySum (fn [a b] (+ a b)))')
+state.fennel.eval('(_G.mySum 2 3)') # => 5
 
 mySum = state.fennel.get(:mySum)
 
@@ -725,7 +763,7 @@ sum_list = -> (list) { list.sum }
 
 state.set('sumList', sum_list) # => nil
 
-state.fennel.eval('(sumList [2 3 5])') # => 10
+state.fennel.eval('(_G.sumList [2 3 5])') # => 10
 
 state.fennel.load('file.fnl')
 ```
@@ -740,6 +778,49 @@ state = SweetMoon::State.new.fennel
 state.eval('(+ 1 2)') # => 3
 ```
 
+### Fennel Global vs Local Variables
+
+Fennel encourages you to explicitly use the [_`_G`_](https://www.lua.org/manual/5.4/manual.html#pdf-_G) table to access global variables:
+
+```ruby
+require 'sweet-moon'
+
+fennel = SweetMoon::State.new.fennel
+
+fennel.eval('(set _G.a? 2)')
+
+fennel.get('a?') # => 2
+fennel.get('_G', 'a?') # => 2
+
+fennel.set('b', 3)
+
+fennel.eval('(print _G.b)') # => 3
+```
+
+Although older versions have the expression `(global name "value")`, it's deprecated, and you should avoid using that. _Sweet Moon_ has no commitments in supporting this deprecated expression, and you should prefer the `_G` way.
+
+As is [true for Lua](#lua-global-vs-local-variables), you can't exchange _local_ variables, only [_global_](https://www.lua.org/pil/1.2.html) ones:
+
+```ruby
+require 'sweet-moon'
+
+fennel = SweetMoon::State.new.fennel
+
+fennel.eval('(local name "value")')
+
+fennel.get('name') # => nil
+
+fennel.eval('(set _G.name "value")')
+
+fennel.get('name') # => "value"
+
+fennel.set('var-b', 35) # => nil
+
+fennel.eval('var-b') # => nil
+
+fennel.eval('_G.var-b') # => 35
+```
+
 ### 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.
@@ -753,7 +834,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
 ```
@@ -763,7 +844,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
 ```
@@ -773,7 +854,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
 ```
@@ -783,7 +864,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
 ```
@@ -810,6 +891,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):
@@ -856,6 +975,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:
@@ -885,6 +1006,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
 
@@ -929,6 +1092,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.
@@ -1183,6 +1448,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