modulation 0.26 → 0.27

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98cf3c047ad9ba16b0658581dfd6031fd5cdcfb8ce74f50aaaba490f13945216
-  data.tar.gz: '09777077cec02eb4f48d4edf9307d55226d992a096226ebeab689ae0a9e34e47'
+  metadata.gz: 04f2ab2cc42f117c9c8fb1b306b2239fbe9bca4a96f890e693bb92fb6c900318
+  data.tar.gz: 9ead222ae4fc275174b3e5d62a3b3b30e094761e5801de7b3a9fe21a346174be
 SHA512:
-  metadata.gz: 6912cf32746a94e17909a3ec05f7b7cd891c6c70e93a6ee389fae72165d058845a85dbbc482c205baa053bab16cd71b3514ed92f40a1021dd7a6918945eeb3c9
-  data.tar.gz: 02a489e032fb5451977eae9f58a8dadfba87dc073e451d712765721abfd0f20c8a69755894a7b1d72e8c5a346e216bc62979b4761f09703e4d93fb4128341b13
+  metadata.gz: 2bd5727f5ca807fcc6238b0679234ba5df79102eaa6153a5acb8db8eb66054a1d9bdb2f8250292cad4784101c1c58b343766b19a3a07be013dfb67ce13b7c175
+  data.tar.gz: 63a1bc298932c0b1d4bbf804099df2940755b23358f4e4c72023c61054d03102c97f4138324570821685eaeb82bd0101146c9a4d469f245d8af093b906a623bd

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+0.27 2019-08-21
+---------------
+
+* Add initial packing functionality.
+
 0.26 2019-08-20
 ---------------
 
@@ -24,7 +29,7 @@
 0.22 2019-05-15
 ---------------
 
-* Export_default of a method now exportsa proc calling that method
+* Export_default of a method now exports a proc calling that method
 * Raise error on export of undefined symbols
 
 0.21 2019-02-19

data/README.md

@@ -83,7 +83,8 @@ easy to understand.
 - 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.
+- Can load all source files in directory [at once](#importing-all-source-files-in-a-directory).
+- Pack entire applications [into a single file](#packing-applications-with-modulation).
 
 ## Installing Modulation
 
@@ -517,6 +518,42 @@ m1.__depedencies #=> [<Module m2>]
 m1.__dependencies.first.__dependent_modules #=> [<Module m1>]
 ```
 
+## Running Modulation-based applications
+
+Modulation provides a binary script for running Modulation-based applications.
+`mdl` is a wrapper around Ruby that loads your application's main file as a
+module, and then runs your application's entry point method. Let's look at a
+sample application:
+
+*app.rb*
+```ruby
+def greet(name)
+  puts "Hello, #{name}!"
+end
+
+def main
+  print "Enter your name: "
+  name = gets
+  greet(name)
+end
+```
+
+To run this application, execute `mdl app.rb`, or `mdl run app.rb`. `mdl` will
+automatically require the `modulation` gem and call the application's entry
+point, `#main`.
+
+## Packing applications with Modulation
+
+> *Note*: application packing is at the present time an experimental feature.
+> There might be security concerns for packaging your app, such as leaking
+> filenames from the developer's machine.
+
+Modulation can also be used to package your entire application into a single
+portable file that can be copied to another machine and run as is. To package
+your app, use `mdl pack`. This command will perform a dynamic analysis of all
+the app's dependencies and will put them together into a single Ruby file.
+For more information have a look at the [app](examples/app) example.
+
 ## Writing gems using Modulation
 
 Modulation can be used to write gems, providing fine-grained control over your
@@ -553,6 +590,48 @@ MyFeature = import 'my_gem/my_feature'
 > use Modulation to export symbols, Modulation will refuse to import any gem
 > that does not depend on Modulation.
 
+## Writing modules that patch external classes or modules
+
+It is generally recommended you refrain from causing side effects or patching
+external code in your modules. When you do have to patch external classes or
+modules (i.e. core, stdlib, or some third-party code) in your module, it's
+useful to remember that any module may be eventually reloaded by the application
+code. This means that any patching done during the loading of your module must
+be [idempotent](https://en.wikipedia.org/wiki/Idempotence), i.e. have the same
+effect when performed multiple times. Take for example the following module
+code:
+
+```ruby
+module ::Kernel
+  # aliasing #sleep more than once will break your code
+  alias_method :orig_sleep, :sleep
+
+  def sleep(duration)
+    STDERR.puts "Going to sleep..."
+    orig_sleep(duration)
+    STDERR.puts "Woke up!"
+  end
+end
+```
+
+Running the above code more than once would cause an infinite loop when calling
+`Kernel#sleep`. In order to prevent this situation, modulation provides the
+`Module#alias_method_once` method, which prevents aliasing the original method
+more than once:
+
+```ruby
+module ::Kernel
+  # alias_method_once is idempotent
+  alias_method_once :orig_sleep, :sleep
+
+  def sleep(duration)
+    STDERR.puts "Going to sleep..."
+    orig_sleep(duration)
+    STDERR.puts "Woke up!"
+  end
+end
+```
+
 ## Coding style recommendations
 
 * Import modules into constants, not variables:

data/bin/mdl

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+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
+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
+  paths = []
+  ARGV.each do |arg|
+    fn, method = (arg =~ /^([^\:]+)\:(.+)$/) ? [$1, $2.to_sym] : [arg, :main]
+    mod = import(File.expand_path(fn))
+    paths << File.expand_path(fn)
+    mod.__traverse_dependencies { |m| paths << m.__module_info[:location] }
+  end
+  
+  require 'modulation/packing'
+  STDOUT << Modulation::Packing.pack(paths, hide_filenames: true)
+end
+
+cmd = ARGV.shift
+respond_to?(cmd.to_sym) ? send(cmd) : (ARGV.unshift(cmd); run)

data/lib/modulation/builder.rb

@@ -55,7 +55,7 @@ module Modulation
       # @return [void]
       def load_module_code(mod, info)
         path = info[:location]
-        mod.instance_eval(IO.read(path), path)
+        mod.instance_eval(info[:source] || IO.read(path), path)
         mod.__post_load
       end
 

data/lib/modulation/packing.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative '../modulation'
+require 'zlib'
+require 'digest/md5'
+
+module Modulation
+  # Implements packing functionality
+  module Packing
+    BOOTSTRAP = <<~SRC.encode('ASCII-8BIT')
+      # encoding: ASCII-8BIT
+      require 'modulation'
+      require 'zlib'
+
+      b = Modulation::Builder
+      z = Zlib::Inflate
+      b::C = {%<module_dictionary>s}
+
+      class << b
+        alias_method :orig_make, :make
+
+        def make(info)
+          (pr = Modulation::Builder::C.delete(info[:location])) ? pr.call : orig_make(info)
+        end
+      end
+
+      import(%<entry_point>s).send(:main)
+    SRC
+
+    MAKE_CODE = <<~SRC
+      proc { b.orig_make(location: %<location>s, source: %<source>s) }
+    SRC
+
+    UNZIP_CODE = 'z.inflate(%<data>s)'
+
+    # MAKE_CODE = <<~SRC
+    #   Modulation::Builder.orig_make(location: %s, source: %s)
+    # SRC
+
+    # UNCAN_CODE = <<~SRC
+    #   proc { RubyVM::InstructionSequence.load_from_binary(
+    #     Zlib::Inflate.inflate(%s)).eval
+    #   }
+    # SRC
+
+    def self.pack(paths, _options = {})
+      paths = [paths] unless paths.is_a?(Array)
+
+      entry_point_filename = nil
+      dictionary = paths.each_with_object({}) do |path, dict|
+        warn "Processing #{path}"
+        source = IO.read(path)
+        entry_point_filename ||= path
+        dict[path] = pack_module(path, source)
+      end
+
+      generate_bootstrap(dictionary, entry_point_filename)
+    end
+
+    def self.pack_module(path, source)
+      # code = (MAKE_CODE % [fn.inspect, module_source.inspect])
+      # seq = RubyVM::InstructionSequence.compile(code, options)
+      # canned = Zlib::Deflate.deflate(seq.to_binary)
+      # dict[fn] = UNCAN_CODE % canned.inspect
+
+      zipped = Zlib::Deflate.deflate(source)
+      code = format(UNZIP_CODE, data: zipped.inspect)
+      format(MAKE_CODE, location: path.inspect, source: code)
+    end
+
+    def self.generate_bootstrap(module_dictionary, entry_point)
+      format(
+        BOOTSTRAP,
+        module_dictionary: format_module_dictionary(module_dictionary),
+        entry_point: entry_point.inspect
+      ).chomp.gsub(/^\s+/, '').gsub(/\n+/, "\n")
+    end
+
+    def self.format_module_dictionary(module_dictionary)
+      module_dictionary.map do |fn, code|
+        format(
+          '%<filename>s => %<code>s',
+          filename: fn.inspect,
+          code: code
+        ).chomp
+      end.join(',')
+    end
+  end
+end

data/lib/modulation/paths.rb

@@ -4,6 +4,12 @@ module Modulation
   # Implements methods for expanding relative or incomplete module file names
   module Paths
     class << self
+      TAGGED_REGEXP = /^@(.+)$/.freeze
+
+      def tagged_path(path)
+        path[TAGGED_REGEXP, 1]
+      end
+
       # Regexp for extracting filename from caller reference
       CALLER_FILE_REGEXP = /^([^\:]+)\:/.freeze
 

data/lib/modulation/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: modulation
 version: !ruby/object:Gem::Version
-  version: '0.26'
+  version: '0.27'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-08-20 00:00:00.000000000 Z
+date: 2019-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -44,7 +44,7 @@ description: "  Modulation provides an alternative way of organizing your Ruby c
   global namespace with a myriad modules, or complex multi-level nested\nmodule hierarchies.\n"
 email: ciconia@gmail.com
 executables:
-- rbm
+- mdl
 extensions: []
 extra_rdoc_files:
 - README.md
@@ -52,7 +52,7 @@ extra_rdoc_files:
 files:
 - CHANGELOG.md
 - README.md
-- bin/rbm
+- bin/mdl
 - lib/modulation.rb
 - lib/modulation/builder.rb
 - lib/modulation/core.rb
@@ -61,6 +61,7 @@ files:
 - lib/modulation/ext.rb
 - lib/modulation/gem.rb
 - lib/modulation/module_mixin.rb
+- lib/modulation/packing.rb
 - lib/modulation/paths.rb
 - lib/modulation/version.rb
 homepage: http://github.com/digital-fabric/modulation

data/bin/rbm

@@ -1,6 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'modulation'
-
-ARGV.each { |fn| import(File.expand_path(fn)) }