modulation 0.7 → 0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfae406a29f60f3ae5a7611d2202a25cc1868599f083a8b465bf85a45a417a7c
-  data.tar.gz: 1caabf00cd4bed47694bfff8e107287244cf3f49bef02edfa7d218a8c5301706
+  metadata.gz: ddfb3af45389c8ef1d34c3ac29b7db56ec60ff48e7c2678c36e2b913db159e9f
+  data.tar.gz: 696b0e52f95113340fde1a51430f67892e7047362180755185bde46222d3077b
 SHA512:
-  metadata.gz: a6f7609ceb7d64e2c64e7be0c47bdfd8df5b5e3e528818c15cf70adf03aec9f1ff22e550359b6c5591ce080a8fdf36d2d2f6fa8d98d0ed8f4592c80bdbf4e73b
-  data.tar.gz: acd4250f81de4a1cb15abd6c4ee6b1d777ce9e19b461271ac2207b6302e9d414d39168a9e83835be44e5fff69ce22771c42d3db98d7c25da021078da9d2c5f00
+  metadata.gz: b49084b372e1d754457f7e3063c12945ac537c0ac3afa17befc67a1478ec3d58810cb2c10b7dad9c3f91ff835f9eb4e06c5384bf2df5ab5d52961c152f195cfb
+  data.tar.gz: d257762508c35b71dd4497c9950044f2621d598c12a2e419fb3a7a8c434690bc1b99f967dee029186fc6aaadcba811ec3f58941caf923bf18d8302f050dd3424

data/README.md

@@ -131,7 +131,7 @@ user = User.new(...)
 ```
 
 > **Note about paths**: module paths are always relative to the file
-> calling the `import` method.
+> calling the `import` method, just like `require_relative`.
 
 ### Default exports
 
@@ -171,6 +171,43 @@ config = import('./config')
 db.connect(config[:host], config[:port])
 ```
 
+### Further organising module functionality into nested namespaces
+
+Code inside modules can be further organised by separating it into nested 
+namespaces. The `export` method can be used to turn a normal nested module
+into a self-contained singleton-like object and prevent access to internal
+implementation details:
+
+*net.rb*
+```ruby
+export :Async, :TCPServer
+
+module Async
+  export :await
+
+  def await
+    Fiber.new do
+      yield Fiber.current
+      Fiber.yield
+    end
+  end
+end
+
+class TCPServer
+  ...
+  def read
+    Async.await do |fiber|
+      on(:read) {|data| fiber.resume data}
+    end
+  end
+end
+```
+
+> Note: when `export` is called inside a `module` declaration, Modulation calls
+> `extend self` implicitly, just like it does for the top-level loaded module.
+> That way there's no need to declare methods using the `def self.xxx` syntax,
+> and the module can still be used to extend arbitrary classes or objects.
+
 ### Importing methods into classes and modules
 
 Modulation provides the `extend_from` and `include_from` methods to include
@@ -195,6 +232,8 @@ 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

data/lib/modulation.rb

@@ -1,5 +1,5 @@
-require 'fileutils'
 # frozen_string_literal: true
+require 'fileutils'
 
 # Kernel extensions - modul's API
 module Kernel
@@ -12,21 +12,28 @@ module Kernel
   end
 end
 
-# Object extensions
-class Object
-  # Returns the objects metaclass (shamelessly stolen from the metaid gem).
-  # @return [Class] object's metaclass
-  def metaclass; class << self; self; end; end
-end
-
 class Module
+  # Exports symbols from a namespace module declared inside an importable
+  # module. Exporting the actual symbols is deferred until the entire code
+  # has been loaded
+  # @param symbols [Array] array of symbols
+  # @return [void]
+  def export(*symbols)
+    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)
+  end
+
   # Extends the receiver with exported methods from the given file name
   # @param fn [String] module filename
   # @return [void] 
   def extend_from(fn)
     mod = import(fn, caller.first)
-    mod.methods(false).each do |sym|
-      metaclass.send(:define_method, sym, mod.method(sym).to_proc)
+    mod.instance_methods(false).each do |sym|
+      self.class.send(:define_method, sym, mod.method(sym).to_proc)
     end
   end
 
@@ -36,7 +43,7 @@ class Module
   # @return [void]
   def include_from(fn)
     mod = import(fn, caller.first)
-    mod.methods(false).each do |sym|
+    mod.instance_methods(false).each do |sym|
       send(:define_method, sym, mod.method(sym).to_proc)
     end
   end
@@ -44,23 +51,38 @@ end
 
 class Modulation
   @@loaded_modules = {}
+  @@top_level_module = nil
   @@full_backtrace = false
 
+  # 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.
   def self.full_backtrace!
     @@full_backtrace = true
   end
 
   # Imports a module from a file
   # If the module is already loaded, returns the loaded module.
-  # @param fn [String] source file name (with or without extension)
-  # @param caller_location [String]
+  # @param fn [String] unqualified file name
+  # @param caller_location [String] caller location
   # @return [Module] loaded module object
   def self.import_module(fn, caller_location = caller.first)
     fn = module_absolute_path(fn, caller_location)
-    @@loaded_modules[fn] ||= create_module_from_file(fn)
+    @@loaded_modules[fn] || create_module_from_file(fn)
   end
 
-  def self.module_absolute_path(fn, caller_location)
+  # Returns the currently loaded top level module
+  # @return [Module] currently loaded module
+  def self.top_level_module
+    @@top_level_module
+  end
+
+  # 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
+  # @param caller_location [String] caller location
+  # @return [String] absolute file name
+  def self.module_absolute_path(fn, caller_location = caller.first)
     orig_fn = fn
     caller_file = (caller_location =~ /^([^\:]+)\:/) ?
       $1 : (raise "Could not expand path")
@@ -76,6 +98,9 @@ class Modulation
     end
   end
 
+  # Resolves the provided file name into a gem. If no gem is found, returns nil
+  # @param name [String] gem name
+  # @return [String] absolute path to gem main source file
   def self.lookup_gem(name)
     spec = Gem::Specification.find_by_name(name)
     unless(spec.dependencies.map(&:name)).include?('modulation')
@@ -93,13 +118,14 @@ class Modulation
   def self.create_module_from_file(fn)
     make_module(location: fn)
   rescue => e
-    if @@full_backtrace
-      raise
-    else
-      # remove *modul* methods from backtrace and reraise
-      backtrace = e.backtrace.reject {|l| l.include?(__FILE__)}
-      raise(e, e.message, backtrace)
-    end
+    @@full_backtrace ? raise : raise_with_clean_backtrace(e)
+  end
+
+  # (Re-)raises an error, filtering its backtrace to remove stack frames
+  # occuring in Modulation code
+  def self.raise_with_clean_backtrace(e)
+    backtrace = e.backtrace.reject {|l| l.include?(__FILE__)}
+    raise(e, e.message, backtrace)
   end
 
   # Loads a module from file or block, wrapping it in a module facade
@@ -109,13 +135,16 @@ class Modulation
   def self.make_module(info, &block)
     export_default = nil
     m = initialize_module {|v| export_default = v}
+    @@loaded_modules[info[:location]] = m
     m.__module_info = info
     load_module_code(m, info, &block)
+    m.__perform_deferred_namespace_exports
 
     if export_default
-      transform_export_default_value(export_default, m)
+      @@loaded_modules[info[:location]] = transform_export_default_value(export_default, m)
+      
     else
-      m.tap {m.__set_exported_symbols(m, m.__exported_symbols)}
+      m.tap {set_exported_symbols(m, m.__exported_symbols)}
     end
   end
 
@@ -126,8 +155,8 @@ class Modulation
   # @param mod [Module] module
   # @return [any] exported value
   def self.transform_export_default_value(value, mod)
-    if value.is_a?(Symbol) && mod.metaclass.const_defined?(value)
-      mod.metaclass.const_get(value)
+    if value.is_a?(Symbol) && mod.const_defined?(value)
+      mod.const_get(value)
     else
       value
     end
@@ -138,10 +167,10 @@ class Modulation
   # @return [Module] new module
   def self.initialize_module(&export_default_block)
     Module.new.tap do |m|
+      m.extend(m)
       m.extend(ModuleMethods)
-      m.metaclass.include(ModuleMetaclassMethods)
       m.__export_default_block = export_default_block
-      m.metaclass.const_set(:MODULE, m)
+      m.const_set(:MODULE, m)
     end
   end
 
@@ -149,44 +178,40 @@ class Modulation
   # @param m [Module] module
   # @param fn [String] source file path
   # @return [void]
-  def self.load_module_code(m, info)
-    fn = info[:location]
-    m.instance_eval(IO.read(fn), fn)
+  def self.load_module_code(m, info, &block)
+    old_top_level_module = @@top_level_module
+    @@top_level_module = m
+    if block
+      m.module_eval(&block)
+    else
+      fn = info[:location]
+      m.module_eval(IO.read(fn), fn)
+    end
+  ensure
+    @@top_level_module = old_top_level_module
   end
 
-  # Module façade methods
-  module ModuleMethods
-    # Responds to missing constants by checking metaclass
-    # If the given constant is defined on the metaclass, the same constant is
-    # defined on self and its value is returned. This is essential to
-    # supporting constants in modules.
-    # @param name [Symbol] constant name
-    # @return [any] constant value
-    def const_missing(name)
-      if metaclass.const_defined?(name)
-        unless !@__exported_symbols || @__exported_symbols.include?(name)
-          raise NameError, "private constant `#{name}' accessed in #{inspect}", caller
-        end
-        metaclass.const_get(name).tap {|value| const_set(name, value)}
-      else
-        raise NameError, "uninitialized constant #{inspect}::#{name}", caller
-      end
+  # Sets exported_symbols ivar and marks all non-exported methods as private
+  # @param m [Module] module with exported symbols
+  # @param symbols [Array] array of exported symbols
+  # @return [void]
+  def self.set_exported_symbols(m, symbols)
+    # m.__exported_symbols = symbols
+    m.instance_methods.each do |sym|
+      next if symbols.include?(sym)
+      m.send(:private, sym)
     end
+    m.constants.each do |sym|
+      next if sym == :MODULE || symbols.include?(sym)
+      m.send(:private_constant, sym)
+    end
+  end
 
+  # Module façade methods
+  module ModuleMethods
     # read and write module information
     attr_accessor :__module_info
 
-    # Sets exported_symbols ivar and marks all non-exported methods as private
-    # @param m [Module] imported module
-    # @param symbols [Array] array of exported symbols
-    # @return [void]
-    def __set_exported_symbols(m, symbols)
-      @__exported_symbols = symbols
-      metaclass.instance_methods(false).each do |m|
-        metaclass.send(:private, m) unless symbols.include?(m)
-      end
-    end
-
     # Returns a text representation of the module for inspection
     # @return [String] module string representation
     def inspect
@@ -197,10 +222,7 @@ class Modulation
         "#{module_name}"
       end
     end
-  end
 
-  # Module façade metaclass methods
-  module ModuleMetaclassMethods
     # Adds given symbols to the exported_symbols array
     # @param symbols [Array] array of symbols
     # @return [void]
@@ -217,7 +239,7 @@ class Modulation
       @__export_default_block.call(v) if @__export_default_block
     end
 
-    # read and write module info
+    # read and write module info===
     attr_accessor :__module_info
 
     # Returns exported_symbols array
@@ -233,6 +255,27 @@ class Modulation
     def __export_default_block=(block)
       @__export_default_block = block
     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
+    # @param symbols [Array] array of symbols
+    # @return [void]
+    def __defer_namespace_export(namespace, symbols)
+      @__namespace_exports ||= Hash.new {|h, k| h[k] = []}
+      @__namespace_exports[namespace].concat(symbols)
+    end
+
+    # Performs exporting of symbols for all namespaces defined in the module,
+    # marking unexported methods and constants as private
+    # @return [void]
+    def __perform_deferred_namespace_exports
+      return unless @__namespace_exports
+
+      @__namespace_exports.each do |m, symbols|
+        Modulation.set_exported_symbols(m, symbols)
+      end
+    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: modulation
 version: !ruby/object:Gem::Version
-  version: '0.7'
+  version: '0.8'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-29 00:00:00.000000000 Z
+date: 2018-08-05 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