modulation 0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 920b7e8e5d77f1c94944970aec2cda441f7dfadb
+  data.tar.gz: e7422d6abea4eb6b88c4435f6fd4a1dab1e86018
+SHA512:
+  metadata.gz: 70a95296ebf8feecbbe2361cbd8e021145d8cbad9fb6e7651acf72001bcf50f26dc33ee27fe309c04a711f050e2cd96ade41f5d0416c10b8c845b91eee7c5615
+  data.tar.gz: 85774eec2d3b3b34f48fffacad087ef2cd15dca5e346e3402732f9bfb7866237ba47991119138119eefe8250833331abbe7f6def0d9799f6dd29aec8d133f263

data/README.md

@@ -0,0 +1,277 @@
+# Modulation - explicit dependencies for Ruby
+
+Modulation provides an alternative way to organize Ruby code. Instead of 
+littering the global namespace with classes and modules, Mrodulation lets you 
+explicitly import and export declarations in order to better control 
+dependencies in your codebase.
+
+With Modulation, you always know where a module comes from, and you have full 
+control over which parts of a module's code you wish to expose to the outside 
+world. With Modulation, you can more easily write in a functional style with a 
+minimum of boilerplate code.
+
+> **Important notice**: Modulation is currently at an experimental stage. Use
+> it at your own risk!
+
+## Rationale
+
+Splitting your Ruby code into multiple files loaded using `require` poses a 
+number of problems:
+
+- Once a file is `require`d, any class, module or constant in it is available 
+  to any other file in your codebase. All "globals" (classes, modules, 
+  constants) are loaded, well, globally, in a single namespace. Namespace 
+  collisions are easy in Ruby.
+- Since a `require` can appear in any file in your code, it's easy to lose
+  track of where a certain file was required and where it is used.
+- To avoid class name ocnflicts, classes need to be nested under a single 
+  hierarchical tree, sometime reaching 4 levels or more, i.e. 
+  `ActiveSupport::Messages::Rotator::Encryptor`.
+- There's no easy way to control the visibility of specific so-called globals. 
+  Everything is wide-open.
+- Writing reusable functional code requires wrapping it in modules using 
+  `class << self`, `def self.foo ...` or `include Singleton`.
+
+Personally, I have found that managing dependencies with `require` over in 
+large codebases is... not as elegant or painfree as I would expect from a 
+first-class development environment.
+
+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, and are easily grokked.
+
+Here's a simple example:
+
+*math.rb*
+```ruby
+export :fib
+
+def fib(n)
+  (0..1).include?(n) ? n : (fib(n - 1) + fib(n - 2))
+end
+```
+*app.rb*
+```ruby
+require 'modulation'
+Math = import('./math')
+puts Math.fib(10)
+```
+
+## Organizing Ruby code base with Modul
+
+Any Ruby source file can be a module. Modules can export declarations (usually 
+an API for a specific 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.
+
+### Exporting declarations
+
+Any class, module or constant be exported using `export`:
+
+```ruby
+export :User, :Session
+
+class User
+...
+end
+
+class Session
+...
+end
+```
+
+A module may also expose a set of methods without using `class << self`, for 
+example when writing in a functional style:
+
+*seq.rb*
+```ruby
+export :fib, :luc
+
+def fib(n)
+  (0..1).include?(n) ? n : (fib(n - 1) + fib(n - 2))
+end
+
+def luc(n)
+  (0..1).include?(n) ? (2 - n) : (luc(n - 1) + luc(n - 2))
+end
+```
+*app.rb*
+```ruby
+require 'modulation'
+Seq = import('./seq')
+puts Seq.fib(10)
+```
+
+### Importing declarations
+
+Declarations from another module can be imported using `import`:
+
+```ruby
+require 'modulation'
+Models = import('./models')
+...
+
+user = Models::User.new(...)
+
+...
+```
+
+Alternatively, a module interested in a single declaration from another module 
+can use the following technique:
+
+```ruby
+require 'modulation'
+User = import('./models')::User
+...
+
+user = User.new(...)
+```
+
+> **Note about paths**: module paths are always relative to the file
+> calling the `import` method.
+
+### Default exports
+
+A module may wish to expose just a single class or constant, in which case it 
+can use `export_default`:
+
+*user.rb*
+```ruby
+export_default :User
+
+class User
+  ...
+end
+```
+
+*app.rb*
+```ruby
+require 'modulation'
+User = import('./user')
+User.new(...)
+```
+
+The default exported value can also be defined directly thus:
+
+*config.rb*
+```ruby
+export_default(
+  host: 'localhost',
+  port: 1234,
+  ...
+)
+```
+
+*app.rb*
+```ruby
+config = import('./config')
+db.connect(config[:host], config[:port])
+```
+
+### Importing methods into classes and modules
+
+Modulation provides the `extend_from` and `include_from` methods to include
+imported methods in classes and modules:
+
+```ruby
+module Sequences
+  extend_from('./seq.rb')
+end
+
+Sequences.fib(5)
+
+# extend integers
+class Integer
+  include_from('./seq.rb')
+
+  def seq(kind)
+    send(kind, self)
+  end
+end
+
+5.seq(:fib)
+```
+
+### Accessing the global namespace
+
+If you need to access the global namespace inside a module just prefix the 
+class name with double colons:
+
+```ruby
+class ::GlobalClass
+  ...
+end
+
+::ENV = { ... }
+
+what = ::MEANING_OF_LIFE
+```
+
+## Writing gems using Modulation
+
+Modulation can be used to write gems, providing fine-grained control over your
+gem's public APIs and letting you hide any implementation details. In order to
+allow loading a gem using either `require` or `import`, code your gem's main
+file normally, but add  `require 'modulation/gem'` at the top, and export your
+gem's main namespace as a default export, e.g.:
+
+```ruby
+require 'modulation/gem'
+
+export_default :MyGem
+
+module MyGem
+  ...
+  MyClass = import('my_gem/my_class')
+  ...
+end
+```
+
+## Importing gems using Modulation
+
+Gems written using modulation can also be loaded using `import`. If modulation
+does not find the module specified by the given relative path, it will attempt
+to load a gem by the same name.
+
+> **Note**: using `import` to load a gem is very much *alpha*, and might
+> introduce problems not encountered when loading with `require` such as 
+> shadowing of global namespaces, or any other bizarre and unexpected
+> behaviors. Actually, there's not much point in using it to load a gem which
+> does not use Modulation. When loading gems using import, Modulation will
+> raise an exception if no symbols were exported by the gem.
+
+## Coding style recommendations
+
+* Import modules into constants, not into variables:
+
+  ```ruby
+  Settings = import('./settings')
+  ```
+
+* Place your exports at the top of your module:
+
+  ```ruby
+  export :foo, :bar, :baz
+
+  ...
+  ```
+
+* Place your imports at the top of your module:
+
+  ```ruby
+  Foo = import('./foo')
+  Bar = import('./bar')
+  Baz = import('./baz')
+
+  ...
+  ```
+
+## Known limitations and problems
+
+- Modulation is (probably) not production-ready.
+- Modulation probably doesn't play well with `Marshal`.
+- Modulation probably doesn't play well with code-analysis tools.
+- Modulation doesn't play well with rdoc/yard.

data/lib/modulation.rb

@@ -0,0 +1,234 @@
+require 'fileutils'
+# frozen_string_literal: true
+
+# Kernel extensions - modul's API
+module Kernel
+  # Returns an encapsulated imported module.
+  # @param fn [String] module file name
+  # @param caller_location [String] caller location
+  # @return [Class] module facade
+  def import(fn, caller_location = caller.first)
+    Modulation.import_module(fn, caller_location)
+  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
+  # 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)
+    end
+  end
+
+  # Includes exported methods from the given file name in the receiver
+  # The module's methods will be available as instance methods
+  # @param fn [String] module filename
+  # @return [void]
+  def include_from(fn)
+    mod = import(fn, caller.first)
+    mod.methods(false).each do |sym|
+      send(:define_method, sym, mod.method(sym).to_proc)
+    end
+  end
+end
+
+class Modulation
+  @@loaded_modules = {}
+  @@full_backtrace = false
+
+  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]
+  # @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)
+  end
+
+  def self.module_absolute_path(fn, caller_location)
+    orig_fn = fn
+    caller_file = (caller_location =~ /^([^\:]+)\:/) ?
+      $1 : (raise "Could not expand path")
+    fn = File.expand_path(fn, File.dirname(caller_file))
+    if File.file?("#{fn}.rb")
+      fn + '.rb'
+    else
+      if File.file?(fn)
+        return fn
+      else
+        lookup_gem(orig_fn) || (raise "Module not found: #{fn}")
+      end
+    end
+  end
+
+  def self.lookup_gem(name)
+    spec = Gem::Specification.find_by_name(name)
+    fn = File.join(spec.full_require_paths, "#{name}.rb")
+    File.file?(fn) ? fn : nil
+  rescue Gem::MissingSpecError
+    nil 
+  end
+
+  # Creates a new module from a source file
+  # @param fn [String] source file name
+  # @return [Module] module
+  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
+  end
+
+  # 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 self.make_module(info, &block)
+    export_default = nil
+    m = initialize_module {|v| export_default = v}
+    m.__module_info = info
+    load_module_code(m, info, &block)
+
+    if export_default
+      transform_export_default_value(export_default, m)
+    else
+      m.tap {m.__set_exported_symbols(m, m.__exported_symbols)}
+    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 self.transform_export_default_value(value, mod)
+    if value.is_a?(Symbol) && mod.metaclass.const_defined?(value)
+      mod.metaclass.const_get(value)
+    else
+      value
+    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`
+  # @return [Module] new module
+  def self.initialize_module(&export_default_block)
+    Module.new.tap do |m|
+      m.extend(ModuleMethods)
+      m.metaclass.include(ModuleMetaclassMethods)
+      m.__export_default_block = export_default_block
+    end
+  end
+
+  # Loads a source file or a block into the given module
+  # @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)
+  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
+    end
+
+    # 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
+      module_name = name || 'Module'
+      if __module_info[:location]
+        "#{module_name}:#{__module_info[:location]}"
+      else
+        "#{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]
+    def export(*symbols)
+      symbols = symbols.first if Array === symbols.first
+      __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 v [Symbol, any] symbol or value
+    # @return [void]
+    def export_default(v)
+      @__export_default_block.call(v) if @__export_default_block
+    end
+
+    # read and write module info
+    attr_accessor :__module_info
+
+    # Returns exported_symbols array
+    # @return [Array] array of exported symbols
+    def __exported_symbols
+      @exported_symbols ||= []
+    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
+  end
+end
+

data/lib/modulation/gem.rb

@@ -0,0 +1,16 @@
+require_relative('../modulation')
+
+# Kernel extensions - mock up the Modulation API with nop methods, so
+# requiring a gem would work. Sample usage:
+# 
+#   require 'modulation/gem'
+#   export_default :MyGem
+#   
+#   module MyGem
+#     MyClass = import('my_class')
+#     MyOtherClass = import('my_other_class')
+#   end
+module Kernel
+  def export(*args); end
+  def export_default(v); end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: modulation
+version: !ruby/object:Gem::Version
+  version: '0.6'
+platform: ruby
+authors:
+- Sharon Rosner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-07-23 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
+  explicitly import and export declarations in order to better control \ndependencies
+  in your codebase.\n\nWith Modulation, you always know where a module comes from,
+  and you have\nfull control over which parts of a module's code you wish to expose
+  to the \noutside world. With Modulation, you can more easily write in a functional\nstyle
+  with a minimum of boilerplate code.\n"
+email: ciconia@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/modulation.rb
+- lib/modulation/gem.rb
+homepage: http://github.com/ciconia/modulation
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ciconia/modulation
+post_install_message: 
+rdoc_options:
+- "--title"
+- Modulation
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: 'Modulation: explicit dependencies for Ruby'
+test_files: []