commonjs_modules 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01f2805d82cb9ecedf647b202119a9307ad8b408c693db12c15191d2a516f312
+  data.tar.gz: 5fbd2f54d96ddb04074caa187cb791e2bd388a8fdd3a0f39069f2ca87af20e33
+SHA512:
+  metadata.gz: 04f6920a4b215c1418b44accda06f0569fdac2dd3b78634769864155a705347814957f639f87fad36652f9fee0f33eba27a43bc48194e0dbd821a264843ff7ed
+  data.tar.gz: 7a982632f08a49bc2a873ab012024ba2c1039ca446143ada3f7d9ef643d835441634f4bfcd153f99123611095be62b9c74bedb18505a5808822bfb20a13223d7

data/README.md

@@ -0,0 +1,70 @@
+# About
+
+[![Gem version][GV img]][Gem version]
+[![Build status][BS img]][Build status]
+[![Coverage status][CS img]][Coverage status]
+[![CodeClimate status][CC img]][CodeClimate status]
+
+This is experimental [CommonJS modules](http://wiki.commonjs.org/wiki/Modules) implementation in Ruby. The main difference is that in this implementation everything is local, there isn't any messing with the global namespace. It has a lot of advantages include [hot code reloading](http://romeda.org/blog/2010/01/hot-code-loading-in-nodejs.html).
+
+# Usage
+
+From `ruby -Ilib -S pry`:
+
+```ruby
+require 'import'
+
+sys = import('examples/1_basic')
+# => #<Imports::Export:0x00007f8dae26cd00
+#        @__DATA__={
+#          :language=>"Ruby", :VERSION_=>"0.0.1",
+#          :say_hello=>#<Method #say_hello>},
+#        @__FILE__="examples/1_basic.rb">
+
+sys.language
+# => "Ruby"
+
+sys.say_hello
+# => "Hello World!"
+```
+
+## `Kernel#import`
+
+`Kernel#import` is a substitute for:
+
+- `Kernel#require` when used with a path relative to `$LOAD_PATH` or
+- `Kernel#require_relative` when used with a path starting with `./` or `../`.
+
+# Discussion
+
+### Usage of modules
+
+This makes use of Ruby modules for namespacing obsolete. Obviously, they still have their use as mixins.
+
+This is a great news. With one global namespace, it's necessary to go full on with the namespacing craziness having all these `LibName::SubModule::Module::ClassName` and dealing either with horrible nesting or with potential for missing module on which we want to definie a class.
+
+Without a global namespace, everything is essentially flat. If we import a `Task`, there's no chance of colision, because we import everything manually and it's crystal clear where every single thing is coming from.
+
+### Why bother if no one else is using it?
+
+Even though all the gems out there are using the global namespace, it doesn't matter, it still a great way to organise your code. It plays well with the traditional approach.
+
+### Usage of refinements
+
+### YARD and RDoc
+
+# TODO
+
+- Rename examples, implicit is only `export ClassName`.
+- exports.default = Class.new {}. What .name to set? The file I guess.
+- What happens when include is used on a file level? I think this makes refinements obsolete as well UNLESS it's for the core classes such as String or Regexp.
+
+[Gem version]: https://rubygems.org/gems/commonjs_modules
+[Build status]: https://travis-ci.org/botanicus/commonjs_modules
+[Coverage status]: https://coveralls.io/github/botanicus/commonjs_modules
+[CodeClimate status]: https://codeclimate.com/github/botanicus/commonjs_modules/maintainability
+
+[GV img]: https://badge.fury.io/rb/commonjs_modules.svg
+[BS img]: https://travis-ci.org/botanicus/commonjs_modules.svg?branch=master
+[CS img]: https://img.shields.io/coveralls/botanicus/commonjs_modules.svg
+[CC img]: https://api.codeclimate.com/v1/badges/a99a88d28ad37a79dbf6/maintainability

data/examples/1_basic.rb

@@ -0,0 +1,8 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+exports.language = 'Ruby'
+exports.VERSION_ = '0.0.1'
+
+def exports.say_hello
+  return "Hello World!"
+end

data/examples/2_annonymous_classes.rb

@@ -0,0 +1,19 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+privateClass = Class.new do
+  def initialize(name)
+    @name = name
+  end
+end
+
+exports.Task = Class.new(privateClass) do
+  def schedule
+    :from_task
+  end
+end
+
+export ScheduledTask: Class.new(exports.Task) {
+  def schedule
+    :from_scheduled_task
+  end
+}

data/examples/3_classic_classes_module.rb

@@ -0,0 +1,24 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+# Using Kernel#require, we'd import this class into the global namespace.
+# Using Kernel#import, we won't, as everything is evaluated in a context
+# of a name context object.
+class PrivateClass
+end
+
+# Class inherits from Object, so no matter what we do, here all the puts
+# and everything will be available again.
+class Task < PrivateClass
+  def initialize(name)
+    @name = name
+  end
+end
+
+class ScheduledTask < Task
+end
+
+# Here we use a different export name to verify that the class name doesn't get
+# overriden (class_name.name reports Task resp. ScheduledTask rather than
+# the underscored version).
+exports._Task = Task
+exports._ScheduledTask = ScheduledTask

data/examples/4_classic_classes_export.rb

@@ -0,0 +1,23 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+# Using Kernel#require, we'd import this class into the global namespace.
+# Using Kernel#import, we won't, as everything is evaluated in a context
+# of a name context object.
+class PrivateClass
+end
+
+# Class inherits from Object, so no matter what we do, here all the puts
+# and everything will be available again.
+class Task < PrivateClass
+  def initialize(name)
+    @name = name
+  end
+end
+
+class ScheduledTask < Task
+end
+
+# Here we use a different export name to verify that the class name doesn't get
+# overriden (class_name.name reports Task resp. ScheduledTask rather than
+# the underscored version).
+export _Task: Task, _ScheduledTask: ScheduledTask

data/examples/5_default_import/exporting_annonymous_class.rb

@@ -0,0 +1,13 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+# NOTE that do/end block cannot be used.
+export default: Class.new {
+  # TODO: 06/06/2018 With this, exports.default shows the right thing,
+  # but exports.default.new still shows just an instance of an anonymous class.
+  def self.inspect
+    'Test'
+  end
+
+  def test
+  end
+}

data/examples/5_default_import/exporting_class.rb

@@ -0,0 +1,9 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+export Test: class Test
+  def test
+  end
+
+  self # Without this, it won't return the right thing.
+end
+

data/examples/5_default_import/using_export.rb

@@ -0,0 +1,5 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+class Test; end
+
+export default: Test

data/examples/5_default_import/using_export_with_block.rb

@@ -0,0 +1,7 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+class Test
+end
+
+# Obviously this can be used with an annonymous class or class N; self; end as well.
+export { Test }

data/examples/5_default_import/using_module.rb

@@ -0,0 +1,4 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+class Test; end
+exports.Test = Test

data/examples/6_settings.rb

@@ -0,0 +1,11 @@
+require 'ostruct'
+
+# Usage:
+# settings = import('examples/6_settings')
+# settings.algolia.app_id
+
+# Remember, nil cannot be exported.
+exports.algolia = OpenStruct.new(
+  app_id: 'ABCD',
+  api_key: '12CD'
+)

data/examples/7_implicit_export/export_annonymous_classs.rb

@@ -0,0 +1,8 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+# TODO: 06/06/2018 Define inspect based for this.
+export Class.new {
+  def self.name
+    'Test'
+  end
+}

data/examples/7_implicit_export/export_classs.rb

@@ -0,0 +1,5 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+export class Test
+  self # Required.
+end

data/examples/8_refinements/refinements.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby -Ilib -rimport
+
+# TODO: 06/06/2018 Fix this.
+using import('examples/8_refinements/modules_lib')
+
+puts "Test."
+

data/examples/8_refinements/refinements_lib.rb

@@ -0,0 +1,9 @@
+export do
+  Module.new do
+    refine Kernel do
+      def puts(message)
+        super("<red>#{message}</red>")
+      end
+    end
+  end
+end

data/examples/9_modules/modules.rb

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby -Ilib -rimport
+
+include import('examples/8_refinements/modules_lib')
+
+puts "Test."

data/examples/9_modules/modules_lib.rb

@@ -0,0 +1,7 @@
+export do
+  Module.new do
+    def puts(message)
+      super("<red>#{message}</red>")
+    end
+  end
+end

data/examples/9_using_import.rb

@@ -0,0 +1,27 @@
+# Run with ./examples/runner.rb examples/file.rb
+
+# Assigning to a constant will make the variable available within classes.
+# FIXME: 06/06/2018 relative paths don't work as of now.
+# Task = import('./3_classic_classes')._Task
+Task = import('examples/3_classic_classes_module')._Task
+Test = import('examples/5_default_import/using_export')
+
+# Assigning to a local variable will make the variable available only within the top-level context.
+# FIXME: 06/06/2018 relative paths don't work as of now.
+# sys = import('./1_basic')
+sys = import('examples/1_basic')
+
+def exports.method_using_imported_library_as_a_constant
+  Task.new("Repair the bike")
+end
+
+def exports.method_using_imported_library_as_a_variable
+  sys.language
+end
+
+export test_proc: Proc.new { self }
+
+# Here we are in Export instance, NOT in Context!
+def exports.method_using_kernel_methods
+  self
+end

data/examples/runner.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby -Ilib
+
+require 'import'
+require 'pry'
+
+path = ARGV.shift
+unless path && File.exist?(path)
+  abort "Usage: #{$0} examples/1_basic.rb"
+end
+
+exports = import(path)
+binding.pry

data/lib/import.rb

@@ -0,0 +1,167 @@
+module Imports
+  def self.register
+    @register ||= Hash.new
+  end
+
+  def self.resolve_path(path)
+    # import('./test') and import('../test') behave like require_relative.
+    if path.start_with?('.')
+      caller_file = caller_locations.first.absolute_path
+
+      unless caller_file
+        raise "Error when importing #{path}: caller[0] is #{caller[0]}"
+      end
+
+      base_dir = caller_file.split('/')[0..-2].join('/')
+      path = File.expand_path("#{base_dir}/#{path}")
+    end
+
+    if File.file?(path)
+      fullpath = path
+    elsif File.file?("#{path}.rb")
+      fullpath = "#{path}.rb"
+    else
+      $:.each do |directory|
+        choices  = [File.join(directory, path), File.join(directory, "#{path}.rb")]
+        fullpath = choices.find { |choice| File.file?(choice) }
+      end
+      if ! defined?(fullpath) || fullpath.nil?
+        raise LoadError, "no such file to import -- #{path}"
+      end
+    end
+
+    File.expand_path(fullpath)
+  end
+
+  module DSL
+    private
+
+    # export default: TaskList
+    # export Task: Task, TL: TaskList
+    # export { MyClass } # export as default
+    def export(*args, &block)
+      if block && args.empty?
+        value = block.call
+        raise TypeError.new if value.nil?
+        args << {default: block.call}
+      elsif block && ! args.empty?
+        raise "Block #{block.inspect} provided along with #{args.inspect}, only 1 can be passed."
+      end
+
+      if args.length == 1 && args.first.is_a?(Hash)
+        hash = args.first
+        if hash.keys.include?(:default) && hash.keys.length == 1
+          # export default: MyClass
+          exports.default = hash[:default]
+        elsif hash.keys.include?(:default) && hash.keys.length > 1
+          # export default: MyClass, something_else: MyOtherClass
+          raise "Default export detected, but it wasn't the only export: #{hash.keys.inspect}"
+        else
+          # export Task: Task, TL: TaskList
+          hash.keys.each do |key|
+            exports.send(:"#{key}=", hash[key])
+          end
+        end
+      else
+        # export MyClass
+        args.each do |object|
+          if object.nil?
+            raise TypeError.new("Exported object cannot be nil!")
+          end
+
+          exports.__DATA__[object.name.to_sym] = object
+        rescue NoMethodError
+          raise ArgumentError.new("Every object has to respond to #name. Export the module manually using exports.name = object if the object doesn't respond to #name.")
+        end
+      end
+    end
+  end
+
+  class Context < BasicObject
+    include DSL
+
+    attr_reader :exports
+    def initialize(path)
+      @exports = Export.new(path)
+    end
+
+    def self.const_missing(name)
+      ::Object.const_get(name)
+    end
+
+    KERNEL_METHODS_DELEGATED = [:import, :require, :raise, :puts, :p]
+
+    def method_missing(name, *args, &block)
+      super unless KERNEL_METHODS_DELEGATED.include? name
+      ::Kernel.send(name, *args, &block)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      KERNEL_METHODS_DELEGATED.include?(name) or super
+    end
+  end
+
+  # Only def exports.something; end is evaluated in the context of Export.
+  # Hence these are not recommented for bigger things, but it works fine
+  # for a collection of few methods that don't need a separate class.
+  class Export
+    attr_reader :__FILE__, :__DATA__
+    def initialize(path)
+      @__FILE__, @__DATA__ = path, ::Hash.new
+    end
+
+    # Register methods.
+    def singleton_method_added(method)
+      @__DATA__[method] = self.method(method)
+
+      @__DATA__[method].define_singleton_method(:inspect) do
+        "#<#{self.class} ##{method}>"
+      end
+    end
+
+    # Register variables and constants.
+    def method_missing(method, *args, &block)
+      if method.to_s.match(/=$/) && args.length == 1 && block.nil?
+        object_name = method.to_s[0..-2].to_sym
+        object = args.first
+
+        @__DATA__[object_name] = object
+
+        if object.is_a?(Class) && object.name.nil?
+          object.define_singleton_method(:name) { object_name.to_s }
+          object.define_singleton_method(:inspect) { object_name.to_s }
+        end
+      elsif @__DATA__.has_key?(method)
+        @__DATA__[method]
+      else
+        super(method, *args, &block)
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      (method.to_s.match(/=$/) && args.length == 1 && block.nil?) || @__DATA__.has_key?(method)
+    end
+  end
+end
+
+module Kernel
+  def import(path)
+    absolute_path = Imports.resolve_path(path)
+
+    object = Imports.register[absolute_path] ||= begin
+      code   = File.read(absolute_path)
+      object = Imports::Context.new(path)
+      object.instance_eval(code, path)
+      object
+    end
+
+    keys = object.exports.__DATA__.keys
+    if keys.include?(:default) && keys.length == 1
+      return object.exports.default
+    elsif keys.include?(:default) && keys.length > 1
+      raise "Default export detected, but it wasn't the only export: #{keys.inspect}"
+    else
+      return object.exports
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: commonjs_modules
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- James C Russell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-06-06 00:00:00.000000000 Z
+dependencies: []
+description: "."
+email: james@101ideas.cz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- examples/1_basic.rb
+- examples/2_annonymous_classes.rb
+- examples/3_classic_classes_module.rb
+- examples/4_classic_classes_export.rb
+- examples/5_default_import/exporting_annonymous_class.rb
+- examples/5_default_import/exporting_class.rb
+- examples/5_default_import/using_export.rb
+- examples/5_default_import/using_export_with_block.rb
+- examples/5_default_import/using_module.rb
+- examples/6_settings.rb
+- examples/7_implicit_export/export_annonymous_classs.rb
+- examples/7_implicit_export/export_classs.rb
+- examples/8_refinements/refinements.rb
+- examples/8_refinements/refinements_lib.rb
+- examples/9_modules/modules.rb
+- examples/9_modules/modules_lib.rb
+- examples/9_using_import.rb
+- examples/runner.rb
+- lib/import.rb
+homepage: http://github.com/botanicus/commonjs_modules
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+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.7.6
+signing_key: 
+specification_version: 4
+summary: ''
+test_files: []