modulation 0.31 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2fdd479aff209b4cf494c13fc4f7bce1ebc64c058ac6860c2dec80928b46b3b
-  data.tar.gz: 3ffce99915f23b4d1444e50c2c216e4b695f00ffdc5c5d9ff6960beb03f8fb9e
+  metadata.gz: 79d44ad3050dcd57ba2c0ca917d16179197fa4ffe12e12aa7de42a050e8872c3
+  data.tar.gz: 643f1853f37b82fe0e49f62d99db0120696d5e0fa11b4d93faa5d0b9eed60070
 SHA512:
-  metadata.gz: 10e1497aa425b14ebabad8247f7898d45f67a255c0b88854c4eeacddaa5ffa36530425d51292f43f478e9043dc15e472a06930b9f9f9d4258e9d9651990eda6e
-  data.tar.gz: d84f11b4c5b206e30462a75307d6399492781cf5009426103e176c48aad65222c6f938468da1453755487559ae08848dc7fd641378d2167fc88f050da0d51977
+  metadata.gz: 3df78b0f925e7d2f6ddd5547c46755d51a89a76f6aba84bdd02871e456de7bdbbd1c458e46f92d7cbbd3c782b8051abfac3ace1b60853e97e7fc3694e90b3c7b
+  data.tar.gz: f7ae45414fca8d849e521efc4980e6a30b9dd1678b9f21a2b8ce438626369e77845bef4cd4be676bd67cdeb39e2b05153d9a9e5b7f9134818d7beba93280bd17

data/CHANGELOG.md

@@ -1,3 +1,35 @@
+1.0.1 2021-04-21
+----------------
+
+* Override inspect method for classes defined in modules (#7)
+
+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
+---------------
+
+* Improve README
+
+0.33 2019-10-02
+---------------
+
+* Add backward compatibility with Ruby 2.4.x
+* Add support for creating modules programmatically
+* Fix use of tags in import_map, auto_import_map, include_from, extend_from
+
+0.32 2019-09-03
+---------------
+
+* Implement export_from_receiver
+* Implement additive exports
+* Refactor auto_import_map, add not_found option
+* Fix backtrace for exports of missing symbols
+
 0.31 2019-08-28
 ---------------
 

data/README.md

@@ -1,13 +1,19 @@
 # Modulation - Explicit Dependency Management for Ruby
 
+[![Gem Version](https://badge.fury.io/rb/modulation.svg)](http://rubygems.org/gems/modulation)
+[![Modulation Test](https://github.com/digital-fabric/modulation/workflows/Tests/badge.svg)](https://github.com/digital-fabric/modulation/actions?query=workflow%3ATests)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/digital-fabric/modulation/blob/master/LICENSE)
+
 > 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) |
+[API](#api-reference) |
 [EXAMPLES](examples) |
 [RDOC](https://www.rubydoc.info/gems/modulation/)
 
+
 Modulation provides an alternative way of organizing your 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
@@ -27,25 +33,23 @@ a functional style, minimizing boilerplate code.
 
 ## Features
 
-- Provides complete isolation of each module: constant definitions in one file
-  do not leak into another.
-- Enforces explicit exporting and importing of methods, classes, modules and 
-  constants.
-- Supports circular dependencies.
-- Supports [default exports](#default-exports) for modules exporting a single
-  class or value.
-- Modules can be [lazy loaded](#lazy-loading) to improve start up time and
-  memory consumption.
-- Modules can be [reloaded](#reloading-modules) at runtime without breaking your 
-  code in wierd ways.
-- Allows [mocking of dependencies](#mocking-dependencies) for testing purposes.
-- Can be used to [write gems](#writing-gems-using-modulation).
-- Module dependencies can be [introspected](#dependency-introspection).
-- Facilitates [unit-testing](#unit-testing-modules) of private methods and
-  constants.
-- Can load all source files in directory [at once](#importing-all-source-files-in-a-directory).
-- Packs entire applications [into a single
-  file](#packing-applications-with-modulation).
+- **[Complete isolation of each module](#organizing-your-code-with-modulation)**
+  prevents literring of the global namespace.
+- **Explicit [exporting](#exporting-declarations) and
+  [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.
+- **[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
+  bundle your code in a single, optionally obfuscated file (WIP).
 
 ## Rationale
 
@@ -65,6 +69,8 @@ issues:
 - There's no easy way to hide implementation-specific classes or methods. Yes,
   there's `#private`, `#private_constant` etc, but by default everything is 
   `#public`!
+- Extracting functionality is harder when modules are namespaced and
+  dependencies are implicit.
 - Writing reusable functional code requires wrapping it in modules using 
   `class << self`, `def self.foo ...`, `extend self` or `include Singleton`
   (the pain of implementing singletons in Ruby has been
@@ -81,11 +87,10 @@ codebases is... not as elegant or painfree as I would expect from a
 first-class development environment. I also wanted to have a better solution
 for writing in a functional style.
 
-So I came up with Modulation, a small gem (less than 300 LOC) that takes a 
-different approach to organizing Ruby code: any so-called global declarations 
-are hidden unless explicitly exported, and the global namespace remains 
-clutter-free. All dependencies between source files are explicit, visible, and 
-easy to understand.
+So I came up with Modulation, a small gem that takes a different approach to
+organizing Ruby code: any so-called global declarations are hidden unless
+explicitly exported, and the global namespace remains clutter-free. All
+dependencies between source files are explicit, visible, and easy to understand.
 
 ## Installing Modulation
 
@@ -98,7 +103,7 @@ gem 'modulation'
 ## Organizing your code with Modulation
 
 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).
+["collection of methods and constants"](https://ruby-doc.org/core-2.6.5/Module.html).
 Using modulation, each Ruby source file becomes 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
@@ -109,6 +114,12 @@ Each source file is evaluated in the context of a newly-created `Module`
 instance, with some additional methods for introspection and miscellaneous
 operations such as [hot reloading](#reloading-modules).
 
+Modulation provides alternative APIs for loading modules. Instead of using
+`require` and `require_relative`, we use `import`, `import_map` etc, discussed
+in detail in the [API reference](#api-reference).
+
+## Basic Usage
+
 ### Exporting declarations
 
 Any class, module or constant be exported using `#export`:
@@ -174,6 +185,17 @@ Any capitalized key will be interpreted as a const, otherwise it will be defined
 as a method. If the value is a symbol, Modulation will look for the
 corresponding method or const definition and will treat the key as an alias.
 
+The `export` method can be called multiple times. Its behavior is additive:
+
+```ruby
+# this:
+export :foo, :bar
+
+# is the same as this:
+export :foo
+export :bar
+```
+
 ### Importing declarations
 
 Declarations from another module can be imported using `#import`:
@@ -199,6 +221,16 @@ User = import('./models')::User
 user = User.new(...)
 ```
 
+### A word about paths
+
+Paths given to `import` are always considered relative to the importing file,
+unless they are absolute (e.g. `/home/dave/repo/my_app`), specify a
+[tag](#using-tags-to-designate-common-subdirectories) or reference a
+[gem](#importing-gems-using-modulation). This is true for all Modulation APIs
+that accept path arguments.
+
+## Advanced Usage
+
 ### Using tags to designate common subdirectories
 
 Normally, module paths are always relative to the file calling the `#import`
@@ -212,12 +244,25 @@ sources. A tagged source is simply a path associated with a label. For example,
 an application may tag `lib/models` simply as `@models`. Once tags are defined,
 they can be used when importing files, e.g. `import('@models/post')`.
 
+To define tags, use `Modulation.add_tags`:
+
+```ruby
+Modulation.add_tags(
+  models: '../lib/models',
+  views:  '../lib/views'
+)
+
+...
+
+User = import '@models/user'
+```
+
 ### Importing all source files in a directory
 
 To load all source files in a directory you can use `#import_all`:
 
 ```ruby
-import_all('./ext') # will load ./ext/kernel.rb, ./ext/socket.rb etc 
+import_all('./ext')
 ```
 
 Groups of modules providing a uniform interface can also be loaded using
@@ -311,6 +356,12 @@ config = import('./config')
 db.connect(config[:host], config[:port])
 ```
 
+### Circular dependencies
+
+Circular dependencies, while not the best practice for organizing a code base,
+are sometimes useful. Modulation supports circular dependencies, with the
+exception of modules with default exports.
+
 ### Accessing a module's root namespace from nested modules within itself
 
 The special constant `MODULE` allows you to access the containing module from
@@ -350,6 +401,51 @@ end
 what_is = ::THE_MEANING_OF_LIFE
 ```
 
+### Programmatic module creation
+
+In addition to loading modules from files, modules can be created dynamically at
+runtime using `Modulation.create`. You can create modules by supplying a hash
+prototype, a string or a block:
+
+```ruby
+# Using a hash prototype
+m = Modulation.create(
+  add: -> x, y { x + y },
+  mul: -> x, y { x * y }
+)
+m.add(2, 3)
+m.mul(2, 3)
+
+# Using a string
+m = Modulation.create <<~RUBY
+export :foo
+
+def foo
+  :bar
+end
+RUBY
+
+m.foo
+
+# Using a block
+m = Modulation.create do { |mod|
+  export :foo
+
+  def foo
+    :bar
+  end
+
+  class mod::BAZ
+    ...
+  end
+}
+
+m.foo
+```
+
+The creation of a objects using a hash prototype is also available as a separate
+gem called [eg](https://github.com/digital-fabric/eg/).
+
 ### Unit testing modules
 
 Methods and constants that are not exported can be tested using the `#__expose!`
@@ -384,7 +480,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`:
@@ -415,6 +511,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
@@ -495,6 +594,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
@@ -520,7 +643,7 @@ overwrite any value retained in the instance variable. To assign initial values,
 use the `||=` operator as in the example above. See also the
 [reload example](examples/reload).
 
-## Dependency introspection
+### Dependency introspection
 
 Modulation allows runtime introspection of dependencies between modules. You can
 interrogate a module's dependencies (i.e. the modules it imports) by calling
@@ -690,6 +813,58 @@ end
   ...
   ```
 
+## API Reference
+
+### Kernel
+
+#### `Kernel#auto_import_map(path, options = {})`
+
+Returns a hash mapping keys to corresponding module files inside the given
+directory path. Modules are loaded automatically upon accessing hash keys.
+
+#### `Kernel#import(path)`
+
+Returns a loaded module identified by the given path. The path can contain
+[tags](#using-tags-to-designate-common-subdirectories)
+
+#### `Kernel#import_all(path)`
+
+#### `Kernel#import_map(path, options = {})`
+
+### Module
+
+#### `Module#__module_info`
+
+Returns a hash containing information about the module. This currently includes
+the following entries:
+
+location|Absolute module file path
+exported_symbols|Array containing all symbols exported by the module
+
+### `Module#__reload!`
+
+#### `Module#alias_method_once(new_name, old_name)`
+
+#### `Module#auto_import(sym, path)`
+
+#### `Module#export(*symbols)`
+
+#### `Module#export_default(value)`
+
+#### `Module#export_from_receiver(receiver)`
+
+#### `Module#extend_from(path)`
+
+#### `Module#include_from(path, *symbols)`
+
+#### `Module::MODULE`
+
+### Modulation
+
+#### `Modulation.full_backtrace!`
+
+#### `Modulation.reload`
+
 ## Why you should not use Modulation
 
 - Modulation is not production-ready.

data/bin/mdl

@@ -4,40 +4,5 @@
 require 'bundler/setup'
 require 'modulation'
 
-def self.run
-  ARGV.each do |arg|
-    fn, method = (arg =~ /^([^\:]+)\:(.+)$/) ? [$1, $2.to_sym] : [arg, :main]
-    mod = import(File.expand_path(fn))
-    mod.send(method) if method
-  end
-rescue StandardError => e
-  backtrace = e.backtrace.reject { |l| l =~ /^(#{Modulation::DIR})|(bin\/mdl)/ }
-  e.set_backtrace(backtrace)
-  raise e
-end
-
-def collect_deps(fn, paths)
-  if File.directory?(fn)
-    Dir["#{fn}/**/*.rb"].each { |fn| collect_deps(fn, paths) }
-  else
-    paths << File.expand_path(fn)
-    mod = import(File.expand_path(fn))
-    if mod.respond_to?(:__traverse_dependencies)
-      mod.__traverse_dependencies { |m| paths << m.__module_info[:location] }
-    end
-  end
-end
-
-def self.deps
-  paths = []
-  ARGV.each { |arg| collect_deps(arg, paths) }
-  puts *paths
-end
-
-def self.pack
-  require 'modulation/packer'
-  STDOUT << Modulation::Packer.pack(ARGV, hide_filenames: true)
-end
-
-cmd = ARGV.shift
-respond_to?(cmd.to_sym) ? send(cmd) : (ARGV.unshift(cmd); run)
+CLI = import '@modulation/cli'
+CLI.new ARGV

data/lib/modulation.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Modulation
-  DIR = File.dirname(__FILE__)
+  DIR = __dir__
 end
 
 require_relative 'modulation/ext'