modulation 0.34 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b35f333f45c8017d3fd44700fc5cd3d16dcdd575be012b3f86f2af17c2fcaef
-  data.tar.gz: de1b7cf9b6cd1d39080fd2ef971d99b23fa2b91f18a90db2bbcacf9debfdd7c7
+  metadata.gz: a81a52fa3760bfbda94193a1e1de70bd498dd8112455ec774fc9b5735bf8fbfa
+  data.tar.gz: 37e1ca88843461ccc8e3d137e4c686d3969641a381210ec7cb40a0215ec184c4
 SHA512:
-  metadata.gz: 914789190308c5b9133d4bc3f2a5b6209fe9123ba1d984e7e77b1062f6392b9cb09a4db32b44b631db631080e655bf7dfb32b1955693eb39d0573a85487dba4d
-  data.tar.gz: 2cba7fed4ae3c0a36abb3f8a2f1505074191ba52cfa7510022060730accf39a932e00b6e3323e7b0643ac8e6932f6046be4e10fa7bff435004a6ceb75492bd68
+  metadata.gz: 2f57985001fea20c87d1b8a7a1e06244fd21a52a5e1830177ee3d379e9cb81913a03dde161fdcc78fe4d7f14d8a486def00058cca2b01b8f8e233cb70b413107
+  data.tar.gz: 0cbc73dc2b7684a7b63fe50c6d505175f78b894fa0b043991ae4591cfc38e1a3849c3ac6c4b7f50e1cdb190f8570e6e00cd4405cb3f95d9494aff7485cf64437

data/CHANGELOG.md

@@ -1,8 +1,13 @@
+1.0 2019-10-18
+--------------
+
+* Cleanup code
+* Obfuscate bootstrap dictionary code in packages
+* Move packer, bootstrap, CLI, creator code into stock modules
+
 0.34 2019-10-14
 ---------------
 
-* Obfuscate bootstrapping code in packages
-* Move packer, bootstrap, CLI, creator code into stock modules
 * Improve README
 
 0.33 2019-10-02

data/README.md

@@ -34,11 +34,13 @@ a functional style, minimizing boilerplate code.
   [importing](#importing-declarations) of methods and constants** lets you
   control the public interface for each module, as well as keep track of all
   dependencies in your code.
+- **[Tagged paths](#using-tags-to-designate-common-subdirectories)** simplify
+  the management of dependencies in large applications.
 - **[Lazy Loading](#lazy-loading)** improves start up time and memory
   consumption.
 - **[Hot module reloading](#reloading-modules)** streamlines your development
   process.
-- **[Dependency mocking](#mocking-dependencies)** facilitates testing.
+- **[Module mocking](#mocking-modules)** facilitates testing.
 - **[Dependency introspection](#dependency-introspection)** lets you introspect
   your dependencies at runtime.
 - **[Application packing](#packing-applications-with-modulation)** lets you
@@ -472,7 +474,7 @@ class FibTest < Minitest::Test
 end
 ```
 
-### Mocking dependencies
+### Mocking modules
 
 Modules loaded by Modulation can be easily mocked when running tests or specs,
 using `Modulation.mock`:
@@ -503,6 +505,9 @@ class UserControllerTest < Minitest::Test
 end
 ```
 
+`Modulation.mock` accepts a module path and a receiver, and the module stays
+mocked within the given block.
+
 ### Lazy Loading
 
 Modulation allows the use of lazy-loaded modules - loading of modules only once
@@ -583,6 +588,30 @@ settings = import('settings')
 settings = settings.__reload!
 ```
 
+Please note that Modulation does not include a directory watcher that
+automatically reloads changed modules. This is due to multiple considerations
+that include the chosen threading model, or the reactor engine in use, or even
+the chosen solution for watching files (whether it's an external gem or an
+internal tool).
+
+It is, however, quite trivial to watch files using
+[`directory_watcher`](https://rubygems.org/gems/directory_watcher/):
+
+```ruby
+require 'directory_watcher'
+
+dw = DirectoryWatcher.new 'lib', glob: '**/*.rb', interval: 2, pre_load: true
+dw.add_observer do |*events|
+  events.each do |e|
+    next unless e.type == :modified
+
+    Modulation.reload e.path
+  end
+end
+
+dw.start
+```
+
 ### Retaining state between reloads
 
 Before a module is reloaded, all of its methods and constants are removed. In
@@ -780,41 +809,52 @@ end
 
 ## API Reference
 
-This section will be expanded on in a future release.
+### Kernel
 
-#### `__module_info`
+#### `Kernel#auto_import_map(path, options = {})`
 
-### `__reload!`
+Returns a hash mapping keys to corresponding module files inside the given
+directory path. Modules are loaded automatically upon accessing hash keys.
 
-#### `alias_method_once()`
+#### `Kernel#import(path)`
 
-#### `auto_import()`
+#### `Kernel#import_all(path)`
 
-#### `auto_import_map()`
+#### `Kernel#import_map(path, options = {})`
 
-#### `export()`
+### Module
 
-#### `export_default()`
+#### `Module#__module_info`
 
-#### `export_from_receiver()`
+Returns a hash containing information about the module. This currently includes
+the following entries:
 
-#### `extend_from()`
+location|Absolute module file path
+exported_symbols|Array containing all symbols exported by the module
 
-#### `import()`
+### `Module#__reload!`
 
-#### `import_all()`
+#### `Module#alias_method_once(new_name, old_name)`
 
-#### `import_map()`
+#### `Module#auto_import(sym, path)`
 
-#### `include_from()`
+#### `Module#export(*symbols)`
 
-#### `Modulation.full_backtrace!`
+#### `Module#export_default(value)`
+
+#### `Module#export_from_receiver(receiver)`
 
-#### `Modulation.reload()`
+#### `Module#extend_from(path)`
 
-#### `MODULE`
+#### `Module#include_from(path, *symbols)`
+
+#### `Module::MODULE`
+
+### Modulation
+
+#### `Modulation.full_backtrace!`
 
-#### `MODULE.__module_info`
+#### `Modulation.reload`
 
 ## Why you should not use Modulation
 

data/lib/modulation/module_mixin.rb

@@ -31,8 +31,8 @@ module Modulation
 
       @__export_directives ||= []
       @__export_directives << {
-        method: :export,
-        args: symbols,
+        method:        :export,
+        args:          symbols,
         export_caller: caller
       }
     end
@@ -46,8 +46,8 @@ module Modulation
 
       @__export_directives ||= []
       @__export_directives << {
-        method: :export_from_receiver,
-        args: name,
+        method:        :export_from_receiver,
+        args:          name,
         export_caller: caller
       }
     end
@@ -113,7 +113,7 @@ module Modulation
 
     def __traverse_dependencies(&block)
       __dependencies.each do |mod|
-        block.call mod
+        block.(mod)
         if mod.respond_to?(:__traverse_dependencies)
           mod.__traverse_dependencies(&block)
         end

data/lib/modulation/modules/bootstrap.rb

@@ -27,9 +27,8 @@ def patch_builder
 end
 
 def transform_module_info(info)
-  if find(info[:location])
-    info[:source] = read_file(info[:location])
-  end
+  location = info[:location]
+  info[:source] = read_file(location) if location
   info
 end
 
@@ -46,4 +45,4 @@ def read_file(path)
   (offset, length) = @dictionary[path]
   @data.seek(@data_offset + offset)
   Zlib::Inflate.inflate(@data.read(length))
-end
+end

data/lib/modulation/modules/cli.rb

@@ -2,6 +2,7 @@
 
 export_default :CLI
 
+# Command line interface functionality
 class CLI
   def initialize(argv)
     @argv = argv
@@ -25,15 +26,15 @@ class CLI
     cleanup_backtrace(e)
     raise e
   end
-  
+
   def run_file(arg)
     fn, method = filename_and_method_from_arg(arg)
     mod = import(File.expand_path(fn))
     mod.send(method) if method
   end
-  
+
   FILENAME_AND_METHOD_RE = /^([^\:]+)\:(.+)$/.freeze
-  
+
   def filename_and_method_from_arg(arg)
     if arg =~ FILENAME_AND_METHOD_RE
       match = Regexp.last_match
@@ -42,14 +43,14 @@ class CLI
       [arg, :main]
     end
   end
-  
+
   BACKTRACE_RE = /^(#{Modulation::DIR})|(bin\/mdl)/.freeze
-  
+
   def cleanup_backtrace(error)
     backtrace = error.backtrace.reject { |l| l =~ BACKTRACE_RE }
     error.set_backtrace(backtrace)
   end
-  
+
   def collect_deps(path, array)
     if File.directory?(path)
       Dir["#{path}/**/*.rb"].each { |fn| collect_deps(fn, array) }
@@ -61,17 +62,17 @@ class CLI
       end
     end
   end
-  
+
   def deps
     paths = []
     @argv.each { |arg| collect_deps(arg, paths) }
     puts(*paths)
   end
-  
+
   def pack
     STDOUT << import('@modulation/packer').pack(@argv, hide_filenames: true)
   end
-  
+
   def version
     puts "Modulation version #{Modulation::VERSION}"
   end

data/lib/modulation/modules/creator.rb

@@ -4,7 +4,7 @@ export :from_block,
        :from_hash,
        :from_string
 
-RE_ATTR   = /^@(.+)$/.freeze
+RE_ATTR = /^@(.+)$/.freeze
 
 def from_block(block)
   Module.new.tap { |m| m.instance_eval(&block) }
@@ -16,20 +16,22 @@ end
 def from_hash(hash)
   Module.new.tap do |m|
     s = m.singleton_class
-    hash.each do |k, v|
-      if k =~ Modulation::RE_CONST
-        m.const_set(k, v)
-      elsif k =~ RE_ATTR
-        m.instance_variable_set(k, v)
-      elsif v.respond_to?(:to_proc)
-        s.send(:define_method, k) { |*args| instance_exec(*args, &v) }
-      else
-        s.send(:define_method, k) { v }
-      end
-    end
+    hash.each { |k, v| process_hash_entry(k, v, m, s) }
+  end
+end
+
+def process_hash_entry(key, value, mod, singleton)
+  if key =~ Modulation::RE_CONST
+    mod.const_set(key, value)
+  elsif key =~ RE_ATTR
+    mod.instance_variable_set(key, value)
+  elsif value.respond_to?(:to_proc)
+    singleton.send(:define_method, key) { |*args| instance_exec(*args, &value) }
+  else
+    singleton.send(:define_method, key) { value }
   end
 end
 
 def from_string(str)
-  m = Modulation::Builder.make(source: str)
+  Modulation::Builder.make(source: str)
 end

data/lib/modulation/modules/packer.rb

@@ -44,29 +44,27 @@ def generate_packed_data(deps, entry_point_filename)
 end
 
 def pack_files(files, entry_point_filename)
+  dictionary = { entry_point: entry_point_filename }
   data = (+'').encode('ASCII-8BIT')
   last_offset = 0
-  dictionary = {
-    entry_point: entry_point_filename
-  }
   files.each_with_object(dictionary) do |(path, content), dict|
-    zipped = Zlib::Deflate.deflate(content)
-    size = zipped.bytesize
-
-    data << zipped
-    dict[path] = [last_offset, size]
-    last_offset += size
+    last_offset = add_packed_file(path, content, data, dict, last_offset)
   end
-  packed_dictionary = Zlib::Deflate.deflate(dictionary.inspect)
-  data << packed_dictionary
+  data << Zlib::Deflate.deflate(dictionary.inspect)
+
+  { dict_offset: last_offset, data: data }
+end
+
+def add_packed_file(path, content, data, dict, last_offset)
+  zipped = Zlib::Deflate.deflate(content)
+  size = zipped.bytesize
 
-  {
-    dict_offset:  last_offset,
-    data:         data
-  }
+  data << zipped
+  dict[path] = [last_offset, size]
+  last_offset + size
 end
 
-def generate_bootstrap(package_info, entry_point)
+def generate_bootstrap(package_info, _entry_point)
   format(
     bootstrap_template,
     modulation_version: Modulation::VERSION,

data/lib/modulation/paths.rb

@@ -16,10 +16,14 @@ module Modulation
 
       def tags
         @tags ||= {
-          'modulation' =>  File.join(Modulation::DIR, 'modulation/modules')
+          'modulation' => modules_path
         }
       end
 
+      def modules_path
+        File.join(Modulation::DIR, 'modulation/modules')
+      end
+
       def add_tags(new_tags, caller_location)
         caller_file = caller_location[CALLER_FILE_REGEXP, 1]
         caller_dir = caller_file ? File.dirname(caller_file) : nil

data/lib/modulation/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: modulation
 version: !ruby/object:Gem::Version
-  version: '0.34'
+  version: '1.0'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-14 00:00:00.000000000 Z
+date: 2019-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest