modulation 0.8 → 0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddfb3af45389c8ef1d34c3ac29b7db56ec60ff48e7c2678c36e2b913db159e9f
-  data.tar.gz: 696b0e52f95113340fde1a51430f67892e7047362180755185bde46222d3077b
+  metadata.gz: 3899712e3a895dcc3c3aa712bdf03cf7f01243ec73194b2b3548594ef34d8ce6
+  data.tar.gz: a79b4b422014895a5bbdf86dd3e1d239941e273c476e757688dd0a93d5ca62ff
 SHA512:
-  metadata.gz: b49084b372e1d754457f7e3063c12945ac537c0ac3afa17befc67a1478ec3d58810cb2c10b7dad9c3f91ff835f9eb4e06c5384bf2df5ab5d52961c152f195cfb
-  data.tar.gz: d257762508c35b71dd4497c9950044f2621d598c12a2e419fb3a7a8c434690bc1b99f967dee029186fc6aaadcba811ec3f58941caf923bf18d8302f050dd3424
+  metadata.gz: 571677f6138bd087cfeac6469b3e00a692aa6699a77485b87786f6a2dd41faf1d8a9db22970e1ce47d9c93615897ba54bac161887d69ada26529c7ad7bf3b7ed
+  data.tar.gz: 34c76b1028909118f75872a03affadf35285e3bd40bcd8b3505803a61135a85eefe65948913ca16b4c06a945e6fc88d6077ad29340d60c569fa7739fa7b5fdab

data/README.md

@@ -1,17 +1,24 @@
-# Modulation - explicit dependencies for Ruby
+# Modulation - better dependency management for Ruby
 
-Modulation provides an alternative way to organize Ruby code. Instead of 
-littering the global namespace with classes and modules, Mrodulation lets you 
+Modulation provides an better way to organize Ruby code. Modulation lets you 
 explicitly import and export declarations in order to better control 
-dependencies in your codebase.
+dependencies in your codebase. Modulation helps you refrain from littering
+the global namespace with a myriad modules, or declaring complex nested
+class hierarchies.
 
-With Modulation, you always know where a module comes from, and you have full 
-control over which parts of a module's code you wish to expose to the outside 
-world. With Modulation, you can more easily write in a functional style with a 
-minimum of boilerplate code.
+Using Modulation, you will always be able to tell know where a piece of code 
+comes from, and you'll have full control over which parts of a module's code 
+you wish to expose to the outside world. Modulation also helps you write Ruby 
+code in a functional style, with a minimum of boilerplate code.
 
-> **Important notice**: Modulation is currently at an experimental stage. Use
-> it at your own risk!
+## Features
+
+- Complete isolation of each module for better control of dependencies.
+- Explicit exporting of methods, classes, modules and other constants.
+- Default exports for modules exporting a single class or value.
+- Nested namespaces with explicit exports.
+- Modules can be reloaded at runtime without breaking dependencies.
+- Can be used to write gems.
 
 ## Rationale
 
@@ -156,7 +163,7 @@ User.new(...)
 
 The default exported value can also be defined directly thus:
 
-*config.rb*
+*config.rb* 
 ```ruby
 export_default(
   host: 'localhost',
@@ -232,8 +239,6 @@ end
 5.seq(:fib)
 ```
 
-### Organizing 
-
 ### Accessing a module from nested namespaces within itself
 
 The special constant `MODULE` allows you to access the containing module from
@@ -273,6 +278,39 @@ end
 what = ::MEANING_OF_LIFE
 ```
 
+### Reloading modules
+
+Modules can be easily reloaded in order to implement hot code reloading:
+
+```ruby
+SQL = import('./sql')
+...
+SQL.__reload!
+```
+
+Another way to reload modules is using `Modulation.reload`, which accepts a
+module or a filename:
+
+```ruby
+require 'filewatcher'
+
+FileWatcher.new(['lib']).watch do |fn, event|
+  if(event == :changed)
+    Modulation.reload(fn)
+  end
+end
+```
+
+Reloading of default exports is also possible. Modulation will extend the 
+exported value with a `#__reload!` method. The value will need to be
+reassigned:
+
+```ruby
+settings = import('settings')
+...
+settings = settings.__reload!
+```
+
 ## Writing gems using Modulation
 
 Modulation can be used to write gems, providing fine-grained control over your
@@ -299,7 +337,7 @@ Gems written using modulation can also be loaded using `import`. If modulation
 does not find the module specified by the given relative path, it will attempt
 to load a gem by the same name.
 
-> **Note**: using `import` to load a gem is very much *alpha*, and might
+> **Note**: using `import` to load a gem is very much *experimental*, and might
 > introduce problems not encountered when loading with `require` such as 
 > shadowing of global namespaces, or any other bizarre and unexpected
 > behaviors. Actually, there's not much point in using it to load a gem which
@@ -328,13 +366,13 @@ to load a gem by the same name.
   Foo = import('./foo')
   Bar = import('./bar')
   Baz = import('./baz')
-
   ...
   ```
 
 ## Known limitations and problems
 
 - Modulation is (probably) not production-ready.
+- Modulation is not thread-safe.
 - Modulation probably doesn't play well with `Marshal`.
 - Modulation probably doesn't play well with code-analysis tools.
-- Modulation doesn't play well with rdoc/yard.
+- Modulation probably doesn't play well with rdoc/yard.

data/lib/modulation.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 require 'fileutils'
 
-# Kernel extensions - modul's API
+# Kernel extensions
 module Kernel
   # Returns an encapsulated imported module.
   # @param fn [String] module file name
@@ -12,6 +12,7 @@ module Kernel
   end
 end
 
+# Module extensions
 class Module
   # Exports symbols from a namespace module declared inside an importable
   # module. Exporting the actual symbols is deferred until the entire code
@@ -19,12 +20,12 @@ class Module
   # @param symbols [Array] array of symbols
   # @return [void]
   def export(*symbols)
-    unless Modulation.top_level_module
+    unless Modulation.__top_level_module__
       raise NameError, "Can't export symbols outside of an imported module"
     end
 
     extend self
-    Modulation.top_level_module.__defer_namespace_export(self, symbols)
+    Modulation.__top_level_module__.__defer_namespace_export(self, symbols)
   end
 
   # Extends the receiver with exported methods from the given file name
@@ -50,10 +51,20 @@ class Module
 end
 
 class Modulation
+  # Hash mapping fully-qualified paths to loaded modules
   @@loaded_modules = {}
+
+  # Reference to currently loaded top-level module, used for correctly 
+  # exporting symbols from namespaces
   @@top_level_module = nil
+
+  # Flag denoting whether to provide full backtrace on errors during
+  # loading of a module (normally Modulation removes stack frames 
+  # occuring in Modulation code)
   @@full_backtrace = false
 
+  public
+
   # Show full backtrace for errors occuring while loading a module. Normally
   # Modulation will remove stack frames occurring inside the modulation.rb code
   # in order to make backtraces more readable when debugging.
@@ -73,10 +84,12 @@ class Modulation
 
   # Returns the currently loaded top level module
   # @return [Module] currently loaded module
-  def self.top_level_module
+  def self.__top_level_module__
     @@top_level_module
   end
 
+  private
+
   # Resolves the absolute path to the provided reference. If the file is not
   # found, will try to resolve to a gem
   # @param fn [String] unqualified file name
@@ -133,21 +146,51 @@ class Modulation
   # @param block [Proc] module block
   # @return [Class] module facade
   def self.make_module(info, &block)
-    export_default = nil
-    m = initialize_module {|v| export_default = v}
+    default_value = :__no_default_value__
+    default_value_caller = nil
+    m = initialize_module do |v, caller|
+      default_value = v
+      default_value_caller = caller
+    end
     @@loaded_modules[info[:location]] = m
     m.__module_info = info
     load_module_code(m, info, &block)
-    m.__perform_deferred_namespace_exports
-
-    if export_default
-      @@loaded_modules[info[:location]] = transform_export_default_value(export_default, m)
-      
+    if default_value != :__no_default_value__
+      set_module_default_value(default_value, info, m, default_value_caller)
     else
-      m.tap {set_exported_symbols(m, m.__exported_symbols)}
+      m.__perform_deferred_namespace_exports
+      set_exported_symbols(m, m.__exported_symbols)
+      m
     end
   end
 
+  DEFAULT_VALUE_ERROR_MSG = "Default export cannot be boolean, numeric, or symbol"
+  private_constant(:DEFAULT_VALUE_ERROR_MSG)
+
+  # Sets the default value for a module using export_default
+  # @param value [any] default value
+  # @param info [Hash] module info
+  # @param m [Module] module
+  # @return [any] default value
+  def self.set_module_default_value(value, info, m, caller)
+    value = transform_export_default_value(value, m)
+    case value
+    when nil, true, false, Numeric, Symbol
+      raise(TypeError, DEFAULT_VALUE_ERROR_MSG, caller)
+    end
+    set_reload_info(value, m.__module_info)
+    @@loaded_modules[info[:location]] = value
+  end
+
+  # Adds methods for module_info and reloading to a value exported as default
+  # @param value [any] export_default value
+  # @param info [Hash] module info
+  # @return [void]
+  def self.set_reload_info(value, info)
+    value.define_singleton_method(:__module_info) {info}
+    value.define_singleton_method(:__reload!) {Modulation.make_module(info)}
+  end
+
   # Returns exported value for a default export
   # If the given value is a symbol, returns the value of the corresponding
   # constant.
@@ -155,7 +198,7 @@ class Modulation
   # @param mod [Module] module
   # @return [any] exported value
   def self.transform_export_default_value(value, mod)
-    if value.is_a?(Symbol) && mod.const_defined?(value)
+    if value.is_a?(Symbol) && (mod.const_defined?(value) rescue nil)
       mod.const_get(value)
     else
       value
@@ -207,22 +250,43 @@ class Modulation
     end
   end
 
-  # Module façade methods
+  # Reloads the given module from its source file
+  # @param m [Module, String] module to reload
+  # @return [Module] module
+  def self.reload(m)
+    if m.is_a?(String)
+      fn, m = m, @@loaded_modules[File.expand_path(m)]
+      raise "No module loaded from #{fn}" unless m
+    end
+    
+    cleanup_module(m)
+
+    orig_verbose, $VERBOSE = $VERBOSE, nil
+    load_module_code(m, m.__module_info)
+    $VERBOSE = orig_verbose
+    
+    m.__perform_deferred_namespace_exports
+    m.tap {set_exported_symbols(m, m.__exported_symbols)}
+  end
+
+  # Removes methods and constants from module
+  # @param m [Module] module
+  # @return [void]
+  def self.cleanup_module(m)
+    m.constants(false).each {|c| m.send(:remove_const, c)}
+    m.methods(false).each {|sym| m.send(:undef_method, sym)}
+
+    private_methods = m.private_methods(false) - Module.private_instance_methods(false)
+    private_methods.each {|sym| m.send(:undef_method, sym)}
+
+    m.__exported_symbols.clear
+  end
+
+  # Extension methods for loaded modules
   module ModuleMethods
     # read and write module information
     attr_accessor :__module_info
 
-    # Returns a text representation of the module for inspection
-    # @return [String] module string representation
-    def inspect
-      module_name = name || 'Module'
-      if __module_info[:location]
-        "#{module_name}:#{__module_info[:location]}"
-      else
-        "#{module_name}"
-      end
-    end
-
     # Adds given symbols to the exported_symbols array
     # @param symbols [Array] array of symbols
     # @return [void]
@@ -236,16 +300,18 @@ class Modulation
     # @param v [Symbol, any] symbol or value
     # @return [void]
     def export_default(v)
-      @__export_default_block.call(v) if @__export_default_block
+      @__export_default_block.call(v, caller) if @__export_default_block
     end
 
-    # read and write module info===
-    attr_accessor :__module_info
-
-    # Returns exported_symbols array
-    # @return [Array] array of exported symbols
-    def __exported_symbols
-      @exported_symbols ||= []
+    # Returns a text representation of the module for inspection
+    # @return [String] module string representation
+    def inspect
+      module_name = name || 'Module'
+      if __module_info[:location]
+        "#{module_name}:#{__module_info[:location]}"
+      else
+        "#{module_name}"
+      end
     end
 
     # Sets export_default block, used for setting the returned module object to
@@ -256,6 +322,12 @@ class Modulation
       @__export_default_block = block
     end
 
+    # Reload module
+    # @return [Module] module
+    def __reload!
+      Modulation.reload(self)
+    end
+
     # Defers exporting of symbols for a namespace (nested module), to be 
     # performed after the entire module has been loaded
     # @param namespace [Module] namespace module
@@ -276,6 +348,11 @@ class Modulation
         Modulation.set_exported_symbols(m, symbols)
       end
     end
-  end
-end
 
+    # Returns exported_symbols array
+    # @return [Array] array of exported symbols
+    def __exported_symbols
+      @exported_symbols ||= []
+    end
+  end
+end

metadata

@@ -1,22 +1,23 @@
 --- !ruby/object:Gem::Specification
 name: modulation
 version: !ruby/object:Gem::Version
-  version: '0.8'
+  version: '0.9'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-05 00:00:00.000000000 Z
+date: 2018-08-14 00:00:00.000000000 Z
 dependencies: []
-description: "Modulation provides an alternative way to organize Ruby code. Instead
-  of \nlittering the global namespace with classes and modules, Modulation lets\nyou
-  explicitly import and export declarations in order to better control \ndependencies
-  in your codebase.\n\nWith Modulation, you always know where a module comes from,
-  and you have\nfull control over which parts of a module's code you wish to expose
-  to the \noutside world. With Modulation, you can more easily write in a functional\nstyle
-  with a minimum of boilerplate code.\n"
+description: "Modulation provides an better way to organize Ruby code. Modulation
+  lets you \nexplicitly import and export declarations in order to better control
+  \ndependencies in your codebase. Modulation helps you refrain from littering\nthe
+  global namespace with a myriad modules, or declaring complex nested\nclass hierarchies.\n\nUsing
+  Modulation, you will always be able to tell know where a piece of code \ncomes from,
+  and you'll have full control over which parts of a module's code \nyou wish to expose
+  to the outside world. Modulation also helps you write Ruby \ncode in a functional
+  style, with a minimum of boilerplate code.\n"
 email: ciconia@gmail.com
 executables: []
 extensions: []
@@ -54,5 +55,5 @@ rubyforge_project:
 rubygems_version: 2.7.3
 signing_key: 
 specification_version: 4
-summary: 'Modulation: explicit dependencies for Ruby'
+summary: 'Modulation: better dependency management for Ruby'
 test_files: []