modulation 0.10 → 0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59463e46fe92ef35c671e713faccfef2cc66434cc50d82c0098e9b585f9716e6
-  data.tar.gz: 35f0cdf9e58f5d4482008d768ce9b70ab04209bc311d132bdca5aadcb7afabc1
+  metadata.gz: c196472c3122b723a0d76849c604cb6b8ce13cc2613cb418bf8ecbf9c794bbe8
+  data.tar.gz: cd027cc00a894ed92c43db09570ee301b82efb002d410d6daf9a584aca8c8357
 SHA512:
-  metadata.gz: 4f5e19c1025c591fe4db182222092341018eed467b0fa8cf1ecdf79d51da554ab934b105505c62c0e57c18a69cfa566a92df1d34db6f7bf76eac4e647e4d5e95
-  data.tar.gz: d3bd42db5a9d6bf57121b433e78a1abe3121f77f25dea0c517226ff95e3c14e1b83b667877bf150df172966676578ea956bb05577c02b3b6597003f8ff42c328
+  metadata.gz: 9c4d82cb9ae8ea84364dffbdd56603bf7db864d4254a587545436c983e157d315068cde11e51fbfec84cb8db08382769506e8f5273f70a64f4440d56150b18f4
+  data.tar.gz: bf00f6e03d79ce2a2c77322aee2f433780989030cceffc031421dcec419c1f9e7bf4a9c8cf178864942e12ceb713760e4b5634a430b5b21e5840e342608d151a

data/README.md

@@ -1,7 +1,7 @@
 # Modulation - better dependency management for Ruby
 
 [INSTALL](#installing-modulation) |
-[GUIDE](#developing-with-modulation) |
+[GUIDE](#organizing-your-code-with-modulation) |
 [EXAMPLES](https://github.com/ciconia/modulation/tree/master/examples) |
 [DOCS](https://www.rubydoc.info/gems/modulation/)
 
@@ -18,12 +18,18 @@ code in a functional style, with a minimum of boilerplate code.
 
 ## 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.
+- Provides complete isolation of each module: constant declarations in one file
+  don't leak into another.
+- Supports circular dependencies.
+- Enforces explicit exporting and importing of methods, classes, modules and 
+  constants.
+- Allows [default exports](#default-exports) for modules exporting a single
+  class or value.
+- Can [reload](#reloading-modules) modules at runtime without breaking your 
+  code in wierd ways.
+- Supports [nested namespaces](#using-nested-namespaces) with explicit exports.
+- Allows [mocking of dependencies](#mocking-dependencies) for testing purposes.
+- Can be used to [write gems](#writing-gems-using-modulation).
 
 ## Rationale
 
@@ -80,14 +86,16 @@ $ gem install modulation
 
 ## Organizing your code with Modulation
 
-Modulation enhances the idea of a Ruby module as a ["collection of methods and constants"](https://ruby-doc.org/core-2.5.1/Module.html).
+Modulation builds on the idea of a Ruby module as a
+["collection of methods and constants"](https://ruby-doc.org/core-2.5.1/Module.html).
 Using modulation, any Ruby source file can be a module. Modules usually export
 method and constant declarations (usually an API for a specific, well-defined 
 functionality) to be shared with other modules. Modules can also import 
 declarations from other modules.
 
-Each module is loaded and evaluated in the context of a newly-created `Module`,
-then transformed into a class and handed off to the importing module.
+Each module is evaluated in the context of a newly-created `Module` instance, 
+with some additional methods that make it possible to identify the module's 
+source location and reload it.
 
 ### Exporting declarations
 
@@ -189,11 +197,12 @@ export_default(
 
 *app.rb*
 ```ruby
+require 'modulation'
 config = import('./config')
 db.connect(config[:host], config[:port])
 ```
 
-### Further organising module functionality into nested namespaces
+### Using 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
@@ -243,6 +252,7 @@ end
 Sequences.fib(5)
 
 # extend integers
+require 'modulation'
 class Integer
   include_from('./seq.rb')
 
@@ -293,11 +303,43 @@ end
 what = ::MEANING_OF_LIFE
 ```
 
+### Mocking dependencies
+
+Modules loaded by Modulation can be easily mocked when running tests or specs,
+using `Modulation.mock`:
+
+```ruby
+require 'minitest/autorun'
+require 'modulation'
+
+module MockStorage
+  extend self
+  
+  def get_user(user_id)
+    {
+      user_id: user_id,
+      name: 'John Doe',
+      email: 'johndoe@gmail.com'
+    }
+  end
+end
+
+class UserControllerTest < Minitest::Test
+  def test_user_storage
+    Modulation.mock('../lib/storage', MockStorage) do
+      controller = UserController.
+      assert_equal
+    end
+  end
+end
+```
+
 ### Reloading modules
 
 Modules can be easily reloaded in order to implement hot code reloading:
 
 ```ruby
+require 'modulation'
 SQL = import('./sql')
 ...
 SQL.__reload!
@@ -321,6 +363,7 @@ exported value with a `#__reload!` method. The value will need to be
 reassigned:
 
 ```ruby
+require 'modulation'
 settings = import('settings')
 ...
 settings = settings.__reload!

data/lib/modulation/builder.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Modulation
+  # Implements creation of module instances
+  module Builder
+    extend self
+
+    # Loads a module from file or block, wrapping it in a module facade
+    # @param info [Hash] module info
+    # @param block [Proc] module block
+    # @return [Class] module facade
+    def make(info, &block)
+      default = nil
+      mod = create(info) { |default_info| default = default_info }
+      Modulation.loaded_modules[info[:location]] = mod
+      load_module_code(mod, info, &block)
+      if default
+        set_module_default_value(default[:value], info, mod, default[:caller])
+      else
+        set_exported_symbols(mod, mod.__exported_symbols, true)
+        mod
+      end
+    end
+
+    # Initializes a new module ready to evaluate a file module
+    # @note The given block is used to pass the value given to `export_default`
+    # @param info [Hash] module info
+    # @return [Module] new module
+    def create(info, &export_default_block)
+      Module.new.tap do |mod|
+        mod.extend(mod)
+        mod.extend(ModuleMixin)
+        mod.__module_info = info
+        mod.__export_default_block = export_default_block
+        mod.const_set(:MODULE, mod)
+      end
+    end
+
+    # Loads a source file or a block into the given module
+    # @param mod [Module] module
+    # @param info [Hash] module info
+    # @return [void]
+    def load_module_code(mod, info, &block)
+      old_top_level_module = Modulation.top_level_module
+      Modulation.top_level_module = mod
+      if block
+        mod.module_eval(&block)
+      else
+        path = info[:location]
+        mod.module_eval(IO.read(path), path)
+      end
+    ensure
+      Modulation.top_level_module = old_top_level_module
+    end
+
+    # Marks all non-exported methods as private
+    # @param mod [Module] module with exported symbols
+    # @param symbols [Array] array of exported symbols
+    # @param perform_deferred_exports [Boolean] perform deferred export flag
+    # @return [void]
+    def set_exported_symbols(mod, symbols, perform_deferred_exports = false)
+      mod.__perform_deferred_namespace_exports if perform_deferred_exports
+
+      mod.instance_methods.each do |sym|
+        next if symbols.include?(sym)
+        mod.send(:private, sym)
+      end
+      mod.constants.each do |sym|
+        next if sym == :MODULE || symbols.include?(sym)
+        mod.send(:private_constant, sym)
+      end
+    end
+
+    # Returns exported value for a default export
+    # If the given value is a symbol, returns the value of the corresponding
+    # constant.
+    # @param value [any] export_default value
+    # @param mod [Module] module
+    # @return [any] exported value
+    def transform_export_default_value(value, mod)
+      value.is_a?(Symbol) ? mod.const_get(value) : value
+    rescue NameError
+      value
+    end
+
+    # Loads code for a module being reloaded, turning warnings off in order to
+    # not generate warnings upon re-assignment of constants
+    def reload_module_code(mod)
+      orig_verbose = $VERBOSE
+      $VERBOSE = nil
+      load_module_code(mod, mod.__module_info)
+    ensure
+      $VERBOSE = orig_verbose
+    end
+
+    # Removes methods and constants from module
+    # @param mod [Module] module
+    # @return [void]
+    def cleanup_module(mod)
+      mod.constants(false).each { |c| mod.send(:remove_const, c) }
+      mod.methods(false).each { |sym| mod.send(:undef_method, sym) }
+
+      private_methods = mod.private_methods(false) -
+                        Module.private_instance_methods(false)
+      private_methods.each { |sym| mod.send(:undef_method, sym) }
+
+      mod.__exported_symbols.clear
+    end
+
+    # Error message to be displayed when trying to set a singleton value as
+    # default export
+    DEFAULT_VALUE_ERROR_MSG =
+      'Default export cannot be boolean, numeric, or symbol'
+
+    # Sets the default value for a module using export_default
+    # @param value [any] default value
+    # @param info [Hash] module info
+    # @param mod [Module] module
+    # @return [any] default value
+    def set_module_default_value(value, info, mod, caller)
+      value = transform_export_default_value(value, mod)
+      case value
+      when nil, true, false, Numeric, Symbol
+        raise(TypeError, DEFAULT_VALUE_ERROR_MSG, caller)
+      end
+      set_reload_info(value, mod.__module_info)
+      Modulation.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 set_reload_info(value, info)
+      value.define_singleton_method(:__module_info) { info }
+      value.define_singleton_method(:__reload!) do
+        Modulation::Builder.make(info)
+      end
+    end
+  end
+end

data/lib/modulation/core.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Implements main Modulation functionality
+module Modulation
+  require_relative './paths'
+  require_relative './builder'
+  require_relative './module_mixin'
+
+  extend self
+
+  # @return [Hash] hash of loaded modules, mapping absolute paths to modules
+  attr_reader :loaded_modules
+
+  # @return [Module] currently loaded top-level module
+  attr_accessor :top_level_module
+
+  # Resets the loaded modules hash
+  def reset!
+    @loaded_modules = {}
+  end
+
+  # 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 full_backtrace!
+    @full_backtrace = true
+  end
+
+  # Imports a module from a file
+  # If the module is already loaded, returns the loaded module.
+  # @param path [String] unqualified file name
+  # @param caller_location [String] caller location
+  # @return [Module] loaded module object
+  def import(path, caller_location = caller(1..1).first)
+    path = Paths.absolute_path(path, caller_location)
+    @loaded_modules[path] || create_module_from_file(path)
+  end
+
+  # Creates a new module from a source file
+  # @param path [String] source file name
+  # @return [Module] module
+  def create_module_from_file(path)
+    Builder.make(location: path)
+  rescue StandardError => e
+    @full_backtrace ? raise : raise_with_clean_backtrace(e)
+  end
+
+  # (Re-)raises an error, filtering its backtrace to remove stack frames
+  # occuring in Modulation code
+  # @param error [Error] raised error
+  # @return [void]
+  def raise_with_clean_backtrace(error)
+    backtrace = error.backtrace.reject { |l| l.include?(__FILE__) }
+    raise(error, error.message, backtrace)
+  end
+
+  # Reloads the given module from its source file
+  # @param mod [Module, String] module to reload
+  # @return [Module] module
+  def reload(mod)
+    if mod.is_a?(String)
+      path = mod
+      mod = @loaded_modules[File.expand_path(mod)]
+      raise "No module loaded from #{path}" unless mod
+    end
+
+    Builder.cleanup_module(mod)
+    Builder.reload_module_code(mod)
+
+    mod.tap { Builder.set_exported_symbols(mod, mod.__exported_symbols, true) }
+  end
+
+  # Maps the given path to the given mock module, restoring the previously 
+  # loaded module (if any) after calling the given block
+  # @param path [String] module path
+  # @param mod [Module] module
+  # @param caller_location [String] caller location
+  # @return [void]
+  def mock(path, mod, caller_location = caller(1..1).first)
+    path = Paths.absolute_path(path, caller_location)
+    old_module = @loaded_modules[path]
+    @loaded_modules[path] = mod
+    yield if block_given?
+  ensure
+    @loaded_modules[path] = old_module if block_given?
+  end
+end
+
+Modulation.reset!

data/lib/modulation/ext.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Kernel extensions
+module Kernel
+  # Returns an encapsulated imported module.
+  # @param path [String] module file name
+  # @param caller_location [String] caller location
+  # @return [Class] module facade
+  def import(path, caller_location = caller(1..1).first)
+    Modulation.import(path, caller_location)
+  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
+  # 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 path [String] module filename
+  # @return [void]
+  def extend_from(path)
+    mod = import(path, caller(1..1).first)
+    mod.instance_methods(false).each do |sym|
+      self.class.send(:define_method, sym, mod.method(sym).to_proc)
+    end
+  end
+
+  # Includes exported methods from the given file name in the receiver
+  # The module's methods will be available as instance methods
+  # @param path [String] module filename
+  # @return [void]
+  def include_from(path)
+    mod = import(path, caller(1..1).first)
+    mod.instance_methods(false).each do |sym|
+      send(:define_method, sym, mod.method(sym).to_proc)
+    end
+  end
+end

data/lib/modulation/module_mixin.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Modulation
+  # Extension methods for loaded modules
+  module ModuleMixin
+    # read and write module information
+    attr_accessor :__module_info
+
+    # Adds given symbols to the exported_symbols array
+    # @param symbols [Array] array of symbols
+    # @return [void]
+    def export(*symbols)
+      symbols = symbols.first if symbols.first.is_a?(Array)
+      __exported_symbols.concat(symbols)
+    end
+
+    # Sets a module's value, so when imported it will represent the given value,
+    # instead of a module facade
+    # @param value [Symbol, any] symbol or value
+    # @return [void]
+    def export_default(value)
+      @__export_default_block&.call(value: value, caller: caller)
+    end
+
+    # 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
+    # a class or constant
+    # @param block [Proc] default export block
+    # @return [void]
+    def __export_default_block=(block)
+      @__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
+    # @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|
+        Builder.set_exported_symbols(m, symbols)
+      end
+    end
+
+    # Returns exported_symbols array
+    # @return [Array] array of exported symbols
+    def __exported_symbols
+      @__exported_symbols ||= []
+    end
+  end
+end

data/lib/modulation/paths.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Modulation
+  # Implements methods for expanding relative or incomplete module file names
+  module Paths
+    extend self
+
+    # Regexp for extracting filename from caller reference
+    CALLER_FILE_REGEXP = /^([^\:]+)\:/
+
+    # Resolves the absolute path to the provided reference. If the file is not
+    # found, will try to resolve to a gem
+    # @param path [String] unqualified file name
+    # @param caller_location [String] caller location
+    # @return [String] absolute file name
+    def absolute_path(path, caller_location = caller(1..1).first)
+      orig_path = path
+      caller_file = caller_location[CALLER_FILE_REGEXP, 1]
+      raise 'Could not expand path' unless caller_file
+
+      path = File.expand_path(path, File.dirname(caller_file))
+      check_path(path) || lookup_gem(orig_path) ||
+        (raise "Module not found: #{path}")
+    end
+
+    # Checks that the given path references an existing file, adding the .rb
+    # extension if needed
+    # @param path [String] absolute file path (with/without .rb extension)
+    # @return [String, nil] path of file or nil if not found
+    def check_path(path)
+      if File.file?("#{path}.rb")
+        path + '.rb'
+      elsif File.file?(path)
+        path
+      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 lookup_gem(name)
+      spec = Gem::Specification.find_by_name(name)
+      unless spec.dependencies.map(&:name).include?('modulation')
+        raise NameError, 'Cannot import gem not based on modulation'
+      end
+      path = File.join(spec.full_require_paths, "#{name}.rb")
+      File.file?(path) ? path : nil
+    rescue Gem::MissingSpecError
+      nil
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: modulation
 version: !ruby/object:Gem::Version
-  version: '0.10'
+  version: '0.11'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-19 00:00:00.000000000 Z
+date: 2018-08-20 00:00:00.000000000 Z
 dependencies: []
 description: "Modulation provides an better way to organize Ruby code. Modulation
   lets you \nexplicitly import and export declarations in order to better control
@@ -22,7 +22,12 @@ extra_rdoc_files:
 files:
 - README.md
 - lib/modulation.rb
+- lib/modulation/builder.rb
+- lib/modulation/core.rb
+- lib/modulation/ext.rb
 - lib/modulation/gem.rb
+- lib/modulation/module_mixin.rb
+- lib/modulation/paths.rb
 homepage: http://github.com/ciconia/modulation
 licenses:
 - MIT