modulation 0.17 → 0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5daf7340b5dc5c4e5efb09a751b1e1fe6bd65fc79a76182bf665174b3287e95c
-  data.tar.gz: 6840631ce8268a819d47796b61d4b74dbabed5f5ad6e368c55705fdce40997aa
+  metadata.gz: 69a7acdf23627c8484110710afefe863049dec51ddf433d1dd607bd9ee9d4a56
+  data.tar.gz: fcef74b2bd0a0fd7450ab0d91b837c341d7c9dfd7b3964afa6bb4e15132ca974
 SHA512:
-  metadata.gz: 5f89f42981f3418d165af0c978291259b21ffc2480f0dd4506f1701daa23fbde3f355950962ad081479e9d1ebc9dd68e11f02a23c644d90c8200cece2d372e80
-  data.tar.gz: 760c2cfbfb460712f122782b57edbef1cb12ab030dbf82b5399ccc6c84a20056d70ecb8ce9eaae4b820d33305e60908b55df61ecbad24033e0f0e01d14214c6c
+  metadata.gz: 8e102e59feae6d84de4da96ce88ad45f389c678c883446e03db74d327c09045d7f0d22fca14e03aff5884f85cea56d8d2f6240335c7a75379f80fbc94df5c1c9
+  data.tar.gz: 3821d9bfc8d48939b24e3f7d94b134a28faabd595978747eae8628d50f9e5744015df7d1092576dfcaa377ce3911d28d11f1ede13d20492700d84ff754eba657

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+0.18 2018-12-30
+---------------
+
+* Add auto_import feature for lazy loading of modules
+
 0.17 2018-11-22
 ---------------
 

data/README.md

@@ -1,5 +1,8 @@
 # Modulation - Explicit Dependency Management for Ruby
 
+> Modulation | mɒdjʊˈleɪʃ(ə)n | *Music* -  a change from one key to another in a
+> piece of music.
+
 [INSTALL](#installing-modulation) |
 [GUIDE](#organizing-your-code-with-modulation) |
 [EXAMPLES](examples) |
@@ -31,11 +34,14 @@ a functional style, minimizing boilerplate code.
 - Supports circular dependencies.
 - Supports [default exports](#default-exports) for modules exporting a single
   class or value.
-- Can [reload](#reloading-modules) modules at runtime without breaking your 
+- Modules can be [reloaded](#reloading-modules) at runtime without breaking your 
   code in wierd ways.
+- Modules can be [lazy loaded](#lazy-loading) to improve start up time and
+  memory consumption.
 - Allows [mocking of dependencies](#mocking-dependencies) for testing purposes.
 - Can be used to [write gems](#writing-gems-using-modulation).
-- Facilitates [unit-testing](#unit-testing-modules) of private methods and constants.
+- Facilitates [unit-testing](#unit-testing-modules) of private methods and
+  constants.
 
 ## Rationale
 
@@ -373,6 +379,44 @@ settings = import('settings')
 settings = settings.__reload!
 ```
 
+## Lazy Loading
+
+Modulation allows the use of lazy-loaded modules - loading of modules only once
+they're needed by the application, in similar fashion to `Module#auto_load`. To
+lazy load modules use the `#auto_import` method, which takes a constant name and
+a path:
+
+```ruby
+export :foo
+
+auto_import :BAR, './bar'
+
+def foo
+  # the bar module will only be loaded once this method is called
+  MODULE::BAR
+end
+```
+
+> Lazy-loaded constants must always be qualified. When referring to a
+> lazy-loaded constant from the module's top namespace, use the `MODULE`
+> namespace, as shown above.
+
+The `auto_import` method can also take a hash mapping constant names to paths.
+This is especially useful when multiple concerns are grouped under a single
+namespace:
+
+```ruby
+export_default :SuperNet
+
+module SuperNet
+  auto_import(
+    HTTP1:      './http1',
+    HTTP2:      './http2',
+    WebSockets: './websockets'
+  )
+end
+```
+
 ## Writing gems using Modulation
 
 Modulation can be used to write gems, providing fine-grained control over your

data/lib/modulation/ext.rb

@@ -13,6 +13,22 @@ end
 
 # Module extensions
 class Module
+  # Registers a constant to be lazy-loaded upon lookup
+  # @param sym [Symbol, Hash] constant name or hash mapping names to paths
+  # @param path [String] path if sym is Symbol
+  # @return [void]
+  def auto_import(sym, path = nil, caller_location = caller(1..1).first)
+    unless @__auto_import_registry
+      a = @__auto_import_registry = {}
+      define_auto_import_const_missing_method(@__auto_import_registry)
+    end
+    if path
+      @__auto_import_registry[sym] = [path, caller_location]
+    else
+      sym.each { |k, v| @__auto_import_registry[k] = [v, caller_location] }
+    end
+  end
+
   # Extends the receiver with exported methods from the given file name
   # @param path [String] module filename
   # @return [void]
@@ -32,6 +48,15 @@ class Module
     add_module_constants(mod, self)
   end
 
+  private
+
+  def define_auto_import_const_missing_method(auto_import_hash)
+    singleton_class.define_method(:const_missing) do |sym|
+      (path, caller_location) = auto_import_hash[sym]
+      path ? const_set(sym, import(path, caller_location)) : super
+    end
+  end
+
   def add_module_methods(mod, target)
     mod.singleton_class.instance_methods(false).each do |sym|
       target.send(:define_method, sym, &mod.method(sym))

data/lib/modulation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Modulation
-  VERSION = '0.17'
+  VERSION = '0.18'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: modulation
 version: !ruby/object:Gem::Version
-  version: '0.17'
+  version: '0.18'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-22 00:00:00.000000000 Z
+date: 2018-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -38,12 +38,10 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 4.0.1
-description: |
-  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. Modulation helps you refrain from littering
-  the global namespace with a myriad modules, or declaring complex nested
-  class hierarchies.
+description: "  Modulation provides an alternative way of organizing your Ruby code.
+  Modulation\nlets you explicitly 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 complex multi-level nested\nmodule hierarchies.\n"
 email: ciconia@gmail.com
 executables:
 - rbm
@@ -87,9 +85,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
-summary: 'Modulation: better dependency management for Ruby'
+summary: 'Modulation: explicit dependency management for Ruby'
 test_files: []