sweet-moon 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e216a8bf96c191f08675bad6b2d4d9a1dceb9649a5e856ce4d6b4894e09b35e
-  data.tar.gz: b807eb9b92df1e53a0e0011f6132724c95b11a76dafab1073a46d2c5bf35c6ab
+  metadata.gz: 46891cd3e8103176f3f909415432df155df1bd33cbed89a80f0042f5d303a2b7
+  data.tar.gz: af7617e43eacc588135285dbd652f644d9bda8b87735c86ff89a7719ce6bfe1a
 SHA512:
-  metadata.gz: 538a7a773c11fe66a13c0be49efeb1f8d37da83f52a85d32fe8a7c52b3b590d155b0cdfb50efec3755181947db6a7b67a238b31c10bc382362b70301594949fb
-  data.tar.gz: 95d84ea3cf24919e4646c766f66302308f22392434ba5f76b0ae7743d4ef9ad3868d90b13b3d4bf26d58d7500d276b88be7ee26393818cf00950f08f4e6c4fc6
+  metadata.gz: 1949e5f83c00dd65cdf78e2e8ebd4f66654dc24df1769add99ad8f01e75cc97bcb090e9d0dc0cf5d10dcdd4d1d338252b4ad78894bd3d4cef40b91ae31aab3d0
+  data.tar.gz: 9a09f1231c7e02250f232e368abd95b7bb1b4d5e366ef2614ce9871248c49201fb480b8b698833df66d769e7688602e8c3415a454366ef5ad3ede02163e1c5a4

data/README.md

@@ -30,7 +30,9 @@ _Sweet Moon_ is a resilient solution that makes working with [Lua](https://www.l
   - [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)
@@ -72,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.5'
+gem 'sweet-moon', '~> 0.0.6'
 ```
 
 ```ruby
@@ -889,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):
@@ -935,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:
@@ -964,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
 
@@ -1364,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/interpreters/50/function.rb

@@ -4,16 +4,16 @@ module Component
   module V50
     Function = Component::V54::Function
 
-    LUA_HANDLER = <<LUA
-    return function (...)
-      result = _ruby(unpack(arg))
+    LUA_HANDLER = <<~LUA
+      return function (...)
+        result = _ruby(unpack(arg))
 
-      if result['error'] then
-        error(result['output'])
-      else
-        return result['output']
+        if result['error'] then
+          error(result['output'])
+        else
+          return result['output']
+        end
       end
-    end
-LUA
+    LUA
   end
 end

data/components/interpreters/54/function.rb

@@ -96,16 +96,16 @@ module Component
       }
     }
 
-    LUA_HANDLER = <<LUA
-    return function (...)
-      result = _ruby(...)
-
-      if result['error'] then
-        error(result['output'] .. ' ' .. debug.traceback())
-      else
-        return result['output']
+    LUA_HANDLER = <<~LUA
+      return function (...)
+        result = _ruby(...)
+
+        if result['error'] then
+          error(result['output'] .. ' ' .. debug.traceback())
+        else
+          return result['output']
+        end
       end
-    end
-LUA
+    LUA
   end
 end

data/config/tests.sample.yml

@@ -3,11 +3,12 @@
 fennel-dev: '/home/me/sweet-moon-test/fennel/dev/?.lua'
 
 luarocks:
+  expected: ['dkjson', 'supernova', 'readline']
   path:
     - /home/me/.luarocks/share/lua/5.4/?.lua
     - /home/me/.luarocks/share/lua/5.4/?/init.lua
+  cpath:
     - /home/me/.luarocks/lib/lua/5.4/?.so
-  expected: ['supernova', 'dkjson', 'lfs']
 
 jit:2.0.5:
   description: 'Lua Jit 2.0.5 + Fennel 1.0.0'

data/controllers/api.rb

@@ -1,5 +1,6 @@
 require_relative '../components/injections'
 require_relative '../components/api'
+require_relative '../components/default'
 require_relative '../components/io'
 require_relative '../dsl/errors'
 
@@ -11,7 +12,9 @@ module Controller
     handle!: ->(options) {
       shared_objects = API[:elect_shared_objects!].(options[:shared_objects])
 
-      api = Component::API[:open!].(shared_objects)
+      api = Component::API[:open!].(
+        shared_objects, options, Component::Default.instance.options
+      )
 
       api_reference = API[:elect_api_reference!].(
         api.ffi_libraries, options[:api_reference]

data/dsl/api.rb

@@ -1,3 +1,5 @@
+require_relative '../components/default'
+
 module DSL
   class Api
     attr_reader :functions, :meta
@@ -7,13 +9,31 @@ module DSL
 
       @functions = @component[:signatures].keys
 
-      @meta = Struct.new(
-        *@component[:meta][:elected].keys
-      ).new(*@component[:meta][:elected].values)
+      build_meta
 
       extend @component[:api]
     end
 
+    def build_global_ffi
+      global_ffi = Component::Default.instance.options[:global_ffi]
+
+      unless @component[:meta][:options][:global_ffi].nil?
+        global_ffi = @component[:meta][:options][:global_ffi]
+      end
+
+      global_ffi
+    end
+
+    def build_meta
+      meta_data = @component[:meta][:elected].clone
+
+      meta_data[:global_ffi] = build_global_ffi
+
+      @meta = Struct.new(
+        *meta_data.keys
+      ).new(*meta_data.values)
+    end
+
     def signature_for(function)
       @component[:signatures][function.to_sym]
     end

data/dsl/cache.rb

@@ -7,112 +7,126 @@ require_relative '../controllers/state'
 require_relative 'api'
 require_relative 'sweet_moon'
 
-class Cache
-  include Singleton
+module DSL
+  class Cache
+    include Singleton
 
-  def clear_global!
-    @cache[:global_state]&._unsafely_destroy
+    API_KEYS = %i[shared_objects api_reference global_ffi]
+    STATE_KEYS = %i[interpreter package_path package_cpath]
 
-    @cache.each_key { |key| @cache.delete(key) if key[/^global/] }
-  end
+    def api_keys?(options)
+      API_KEYS.each { |key| return true if options.key?(key) }
+      false
+    end
 
-  def keys
-    @cache.keys
-  end
+    def state_keys?(options)
+      STATE_KEYS.each { |key| return true if options.key?(key) }
+      false
+    end
 
-  def initialize
-    @cache = {}
-  end
+    def clear_global!
+      @cache[:global_state]&._unsafely_destroy
 
-  def global_state(options = {}, recreate: false)
-    key = :global_state
+      @cache.each_key { |key| @cache.delete(key) if key[/^global/] }
+    end
 
-    clear_global_state_cache!(options) if recreate
+    def keys
+      @cache.keys
+    end
 
-    return @cache[key] if @cache[key]
+    def initialize
+      @cache = {}
+    end
 
-    api = Cache.instance.api_module(options, :global_api_module)
-    interpreter = Cache.instance.interpreter_module(
-      api, options, :global_interpreter_module
-    )
+    def global_state(options = {}, recreate: false)
+      key = :global_state
 
-    @cache[key] = DSL::State.new(api, interpreter, Controller::State, options)
-    @cache[key].instance_eval('undef :destroy', __FILE__, __LINE__)
+      clear_global_state_cache!(options) if recreate
 
-    @cache[key]
-  end
+      return @cache[key] if @cache[key]
 
-  def global_api(options = {}, recreate: false)
-    key = :global_api
+      api = Cache.instance.api_module(options, :global_api_module)
+      interpreter = Cache.instance.interpreter_module(
+        api, options, :global_interpreter_module
+      )
 
-    clear_global_api_cache! if recreate
+      @cache[key] = DSL::State.new(api, interpreter, Controller::State, options)
+      @cache[key].instance_eval('undef :destroy', __FILE__, __LINE__)
 
-    @cache[key] ||= api(options, :global_api, :global_api_module)
-  end
+      @cache[key]
+    end
 
-  def api(options = {}, key = nil, api_module_key = nil)
-    key ||= cache_key_for(:api, options, %i[shared_objects api_reference])
-    @cache[key] ||= DSL::Api.new(api_module(options, api_module_key))
-  end
+    def global_api(options = {}, recreate: false)
+      key = :global_api
 
-  def api_module(options = {}, key = nil)
-    key ||= cache_key_for(:api_module, options, %i[shared_objects api_reference])
-    @cache[key] ||= Controller::API[:handle!].(options)
-  end
+      clear_global_api_cache! if recreate
 
-  def interpreter_module(api, options = {}, key = nil)
-    key ||= cache_key_for(
-      :interpreter_module,
-      { shared_objects: api[:meta][:elected][:shared_objects],
-        api_reference: api[:meta][:elected][:api_reference],
-        interpreter: options[:interpreter], package_path: options[:package_path],
-        package_cpath: options[:package_cpath] },
-      %i[shared_objects api_reference interpreter package_path package_cpath]
-    )
-
-    @cache[key] ||= Controller::Interpreter[:handle!].(api, options)
-  end
+      @cache[key] ||= api(options, :global_api, :global_api_module)
+    end
 
-  private
+    def api(options = {}, key = nil, api_module_key = nil)
+      key ||= cache_key_for(:api, options, API_KEYS)
+      @cache[key] ||= DSL::Api.new(api_module(options, api_module_key))
+    end
 
-  def clear_global_api_cache!
-    @cache[:global_state]&._unsafely_destroy
+    def api_module(options = {}, key = nil)
+      key ||= cache_key_for(:api_module, options, API_KEYS)
+      @cache[key] ||= Controller::API[:handle!].(options)
+    end
 
-    %i[global_api global_api_module
-       global_interpreter_module
-       global_state].each do |key|
-      @cache.delete(key)
+    def interpreter_module(api, options = {}, key = nil)
+      key ||= cache_key_for(
+        :interpreter_module,
+        { shared_objects: api[:meta][:elected][:shared_objects],
+          api_reference: api[:meta][:elected][:api_reference],
+          global_ffi: api[:meta][:global_ffi],
+          interpreter: options[:interpreter], package_path: options[:package_path],
+          package_cpath: options[:package_cpath] },
+        API_KEYS.concat(STATE_KEYS)
+      )
+
+      @cache[key] ||= Controller::Interpreter[:handle!].(api, options)
     end
-  end
 
-  def clear_global_state_cache!(options)
-    @cache[:global_state]&._unsafely_destroy
+    def cache_key_for(prefix, options = {}, relevant_keys = [])
+      values = [prefix]
 
-    %i[global_interpreter_module global_state].each do |key|
-      @cache.delete(key)
-    end
+      relevant_keys.each do |key|
+        value = options[key]
+        value = options[key.to_s] if value.nil?
 
-    return unless options.key?(:shared_objects) || options.key?(:api_reference)
+        values << (value.is_a?(Array) ? value.sort.join(':') : value.inspect)
+      end
 
-    %i[global_api global_api_module].each do |key|
-      @cache.delete(key)
+      values.join('|')
     end
 
-    global_api(options, recreate: true)
-  end
+    private
 
-  def cache_key_for(prefix, options = {}, relevant_keys = [])
-    values = [prefix]
+    def clear_global_api_cache!
+      @cache[:global_state]&._unsafely_destroy
 
-    relevant_keys.each do |key|
-      value = options[key] || options[key.to_s]
-      if value.is_a?(Array)
-        values << value.sort.join(':')
-      elsif value
-        values << value
+      %i[global_api global_api_module
+         global_interpreter_module
+         global_state].each do |key|
+        @cache.delete(key)
       end
     end
 
-    values.join('|')
+    def clear_global_state_cache!(options)
+      @cache[:global_state]&._unsafely_destroy
+
+      %i[global_interpreter_module global_state].each do |key|
+        @cache.delete(key)
+      end
+
+      return unless api_keys?(options)
+
+      %i[global_api global_api_module].each do |key|
+        @cache.delete(key)
+      end
+
+      global_api(options, recreate: true)
+    end
   end
 end

data/dsl/global.rb

@@ -2,41 +2,40 @@ require_relative '../logic/options'
 
 require_relative 'cache'
 
-module Global
-  def api
-    Cache.instance.global_api
-  end
+module DSL
+  module Global
+    def api
+      Cache.instance.global_api
+    end
 
-  def state
-    Cache.instance.global_state
-  end
+    def state
+      Cache.instance.global_state
+    end
 
-  def config(options = {})
-    options = Logic::Options[:normalize].(options)
+    def config(options = {})
+      options = Logic::Options[:normalize].(options)
 
-    if options.key?(:shared_objects) || options.key?(:api_reference)
-      Cache.instance.global_api(options, recreate: true)
-    end
+      if Cache.instance.api_keys?(options)
+        Cache.instance.global_api(options, recreate: true)
+      end
 
-    return unless
-      options.key?(:interpreter) ||
-      options.key?(:package_path) ||
-      options.key?(:package_cpath)
+      return unless Cache.instance.state_keys?(options)
 
-    Cache.instance.global_state(options, recreate: true)
+      Cache.instance.global_state(options, recreate: true)
 
-    nil
-  end
+      nil
+    end
 
-  def cached(all: false)
-    return Cache.instance.keys if all
+    def cached(all: false)
+      return Cache.instance.keys if all
 
-    Cache.instance.keys.select { |key| key[/^global/] }
-  end
+      Cache.instance.keys.select { |key| key[/^global/] }
+    end
 
-  def clear
-    Cache.instance.clear_global!
-  end
+    def clear
+      Cache.instance.clear_global!
+    end
 
-  module_function :api, :state, :config, :cached, :clear
+    module_function :api, :state, :config, :cached, :clear
+  end
 end

data/dsl/state.rb

@@ -1,6 +1,7 @@
 require_relative 'errors'
 require_relative 'concerns/packages'
 require_relative 'concerns/fennel'
+require_relative '../components/default'
 
 module DSL
   class State
@@ -87,13 +88,25 @@ module DSL
 
     private
 
-    def build_meta(api_component, interpreter_component)
-      meta_data = {
+    def build_api_meta(api_component)
+      global_ffi = Component::Default.instance.options[:global_ffi]
+
+      unless api_component[:meta][:options][:global_ffi].nil?
+        global_ffi = api_component[:meta][:options][:global_ffi]
+      end
+
+      {
         api_reference: api_component[:meta][:elected][:api_reference],
         shared_objects: api_component[:meta][:elected][:shared_objects],
-        interpreter: interpreter_component[:meta][:elected][:interpreter],
-        runtime: interpreter_component[:meta][:runtime][:lua]
+        global_ffi: global_ffi
       }
+    end
+
+    def build_meta(api_component, interpreter_component)
+      meta_data = build_api_meta(api_component)
+
+      meta_data[:interpreter] = interpreter_component[:meta][:elected][:interpreter]
+      meta_data[:runtime] = interpreter_component[:meta][:runtime][:lua]
 
       @meta = Struct.new(*meta_data.keys).new(*meta_data.values)
     end

data/dsl/sweet_moon.rb

@@ -11,7 +11,7 @@ require_relative '../logic/interpreter'
 module SweetMoon
   module API
     def new(options = {})
-      Cache.instance.api(Logic::Options[:normalize].(options))
+      DSL::Cache.instance.api(Logic::Options[:normalize].(options))
     end
 
     module_function :new
@@ -21,9 +21,9 @@ module SweetMoon
     def new(options = {})
       options = Logic::Options[:normalize].(options)
 
-      api = Cache.instance.api_module(options)
+      api = DSL::Cache.instance.api_module(options)
 
-      interpreter = Cache.instance.interpreter_module(api, options)
+      interpreter = DSL::Cache.instance.interpreter_module(api, options)
 
       DSL::State.new(api, interpreter, Controller::State, options)
     end
@@ -46,7 +46,7 @@ module SweetMoon
   end
 
   def global
-    Global
+    DSL::Global
   end
 
   module_function :meta, :global

data/logic/spec.rb

@@ -2,7 +2,7 @@ module Logic
   Spec = {
     name: 'sweet-moon',
     command: 'sweet-moon',
-    version: '0.0.5',
+    version: '0.0.6',
     author: 'gbaptista',
     summary: 'Lua / Fennel from Ruby and vice versa. Support to LuaJIT, Lua 5.0, ' \
              'and 5.1. Lua C API for Lua 5, 4, and 3. LuaRocks and fnx integration.',

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sweet-moon
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - gbaptista
 autorequire:
 bindir: ports/in/shell
 cert_chain: []
-date: 2022-03-25 00:00:00.000000000 Z
+date: 2022-03-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -48,6 +48,7 @@ files:
 - LICENSE
 - README.md
 - components/api.rb
+- components/default.rb
 - components/injections.rb
 - components/injections/injections_503.rb
 - components/injections/injections_514.rb