awesome_loader 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ff578e319ae7955c039a49a12e1a7dd41f4af2db
-  data.tar.gz: 1044693107960f3dbfd2b1f78f3247316ae01502
+  metadata.gz: 362e0c1826dd0bcde66b8e466799b0b37743f2f2
+  data.tar.gz: 0d981dffe720657efa76c056b37b4d4f09ad8ae3
 SHA512:
-  metadata.gz: 116775922f484ed6eca46c5d5655f72bae1c5234e6b039c1e4f69734c195f0faffa1ccd4759538dc9c3a476fb41a4d607c8862dc0874c8cd529c255b7670b425
-  data.tar.gz: 71ed372da0aaeba0719423c971d9399027adf980ffb5472dc63611c8cf16797fb05e1af2557601e04b1e1398b0caff2a1262a2963dcca4f8d955f43118c88771
+  metadata.gz: e7d754fce596bd375ed6dec3f11341b10e76e8f7320b5ba6ae3aed577cff50f6ef4614b17358054cd784c48974623af38672c0c288b80c07970d2274b59fe6cb
+  data.tar.gz: 905b71a2043b2334334f1472eab79d2d4bf0709892c7d691568410e815318ac76f805bbce5ad566ae2198b2176a3624a6d6c0b7d846ea276a7dfac77b15b78f1

data/README.md

@@ -10,9 +10,17 @@ Just add to your Gemfile.
 
 ## Basic Usage
 
-Let's say your (non-Rails) app has a very Rails-like layout. `app/models`, `app/helpers`, etc. And those might have some subdirectories that correspond to module names. This is all you have to do:
+`awesome_loader` assumes that your directories and files are all in "snake case" (my_dir/my_file.rb), and that your Ruby Modules and Classes are all in "camel case" (MyDir::MyFile). Additionally, it assumes that your directory structure matches your Module structure. In fact it will traverse your directory tree and make sure all those Modules are created for you.
+
+Let's say you have a fairly simple layout, somewhat inspired by Rails.
+
+* `app/models/user.rb` contains `User`
+* `app/models/widget.rb` contains `Widget`
+* `app/models/billing/line_item.rb` contains `Billing::LineItem`
+* `app/helpers/app_helpers.rb` contains `AppHelpers`
+
+Given those files and their contents, this is all you have to tell `awesome_loader`. Note the `root_depth: 2` argument. That's saying, "Only start creating modules for dirs after the first 2 levels." That means `app` and `app/*` won't get any modules, but deeper directories, like `app/models/billing`, will.
 
-    # The root_depth argument is saying "Start creating modules for dirs after the first 2 levels"
     AwesomeLoader.autoload root_depth: 2 do
       paths %w(app ** *.rb)
     end
@@ -33,11 +41,10 @@ Maybe your app structure is more complicated. That's fine too.
 
 ## Eager Loading
 
-If you're running a threaded server like Puma or Thin, it's often considered best practice to load everything
-up-front, instead of possibly loading something during a request Thread. At least in production.
+If you're running a threaded server like Puma or Thin, it's usually considered best practice to load everything up-front (at least in production), instead of lettings things load while other threads might be running. The `eager_load` option will ensure that all files are loaded before the block exits.
 
     AwesomeLoader.autoload root_depth: 2, eager_load: true do
-      ...
+      paths %w(app ** *.rb)
     end
 
 ## License

data/lib/awesome_loader.rb

@@ -1,3 +1,4 @@
 require 'awesome_loader/version'
+require 'awesome_loader/module_builder'
 require 'awesome_loader/autoloader'
 require 'awesome_loader/utils'

data/lib/awesome_loader/autoloader.rb

@@ -2,7 +2,7 @@ require 'set'
 require 'pathname'
 
 #
-# A module that holds all the awesomeness.
+# The module that holds the awesomeness.
 #
 module AwesomeLoader
   #
@@ -15,15 +15,16 @@ module AwesomeLoader
   #   end
   #
   # @param root_depth [String] Tells AwesomeLoader to start creating Modules for dirs *after* this level
-  # @param root [String] Path to root of the application (default Dir.cwd)
+  # @param root_path [String] Path to root of the application (default Dir.pwd)
+  # @param root_module [Module] Module to load your modules into (default Object). You'll probably always want to keep the default.
   # @param eager_load [Boolean] Make sure all files get loaded by the time the block finishes (default false)
   # @return [AwesomeLoader::Autoloader]
   #
-  def self.autoload(root_depth:, root: Dir.cwd, eager_load: false, &block)
-    autoloader = Autoloader.new(root: root, root_depth: root_depth, eager_load: eager_load)
+  def self.autoload(root_depth:, root_path: Dir.pwd, root_module: Object, eager_load: false, &block)
+    autoloader = Autoloader.new(root_depth: root_depth, root_path: root_path, root_module: root_module, eager_load: eager_load)
     if block
       autoloader.instance_eval(&block)
-      autoloader.finialize!
+      autoloader.finalize!
     end
     autoloader
   end
@@ -35,18 +36,20 @@ module AwesomeLoader
   #     paths(%w(app models ** *.rb)).
   #     paths(%w(app helpers *.rb)).
   #     paths(%w(app routes ** *.rb), root_depth: 1).
-  #     finialize!
+  #     finalize!
   #
   class Autoloader
     RB_EXT = /\.rb$/
 
-    # @return [Pathname] the application root
-    attr_reader :root
     # @return [Integer] root depth used for all paths unless otherwise specified
     attr_reader :default_root_depth
+    # @return [Pathname] the application root
+    attr_reader :root_path
+    # @return [Module] the root ruby Module
+    attr_reader :root_module
     # @return [Boolean] whether or not to automatically load all files once they're defined
     attr_reader :eager_load
-    # @return [Array<String>] all defined files, ready to be eager_loaded
+    # @return [Set<String>] all defined files, ready to be eager_loaded
     attr_reader :all_files
     private :all_files
 
@@ -54,13 +57,14 @@ module AwesomeLoader
     # Initialize a new AwesomeLoader::Autoloader.
     #
     # @param root_depth [String] Tells AwesomeLoader to start creating Modules for dirs *after* this level
-    # @param root [String] Path to root of the application (default Dir.cwd)
+    # @param root_path [String] Path to root of the application (default Dir.pwd)
+    # @param root_module [Module] Module to load your modules into (default Object). You'll probably always want to keep the default.
     # @param eager_load [Boolean] Make sure all files get loaded by the time the block finishes (default false)
     #
-    def initialize(root_depth:, root: Dir.cwd, eager_load: false)
-      @root = Pathname.new(root.to_s)
+    def initialize(root_depth:, root_path: Dir.pwd, root_module: Object, eager_load: false)
+      @root_path, @root_module = Pathname.new(root_path.to_s), root_module
       @default_root_depth, @eager_load = root_depth, eager_load
-      @all_files = []
+      @all_files = Set.new
     end
 
     #
@@ -68,47 +72,28 @@ module AwesomeLoader
     #
     #   autoloader.paths %w(app models ** *.rb)
     #
-    # @param array [Array<String>] A glob pattern as an array.
+    # @param glob [Array<String>] A glob pattern as an array.
     # @paths root_depth [Integer] Depth at which to start creating modules for dirs. Defaults to whatever the AwesomeLoader::Autoloader instance was initialized with.
     # @return [AwesomeLoader::Autoloader] returns self, so you can chain calls
     #
-    def paths(array, root_depth: default_root_depth)
-      files = Dir.glob File.join *array
-      root_regex = Regexp.new "^([^/]+/){%d}" % root_depth
-
-      # Get an array of nested dirs (parent dir always comes before child dir)
-      nested_dirs = files.
-        map { |path| File.dirname(path).sub(root_regex, '') }.uniq.
-        reduce(Set.new) { |dirs, leaf_dir|
-          dirs + leaf_dir.split('/').reduce([]) { |a, dir|
-            a << File.join(*a, dir)
-          }
-        }
-
-      # Create modules for each dir. Set a Hash of dir path => Module.
-      modules = nested_dirs.reduce({'.' => Object}) { |a, dir|
-        parent_module = a.fetch File.dirname dir
-        new_module = parent_module.const_set Utils.camelize(File.basename dir), Module.new
-        a[dir] = new_module
-        a
-      }
-
-      # For each file, look up it's dir module and set autoload on the class/module in the file.
-      files.each do |path|
-        full_path = self.root.join(path)
-        const_name = Utils.camelize File.basename(path).sub(RB_EXT, '')
-        mod = modules.fetch File.dirname path.sub(root_regex, '')
-        mod.autoload const_name, full_path
+    def paths(glob, root_depth: default_root_depth)
+      builder = ModuleBuilder.new(root_depth: root_depth, root_module: root_module)
+      Dir.glob(File.join root_path.to_s, *glob).each do |full_path|
+        next if all_files.include? full_path
         all_files << full_path if eager_load
-      end
 
+        rel_path = full_path.sub root_path.to_s, ''
+        dir_path, file_name = File.split rel_path
+        const_name = Utils.camelize file_name.sub RB_EXT, ''
+        builder.module(dir_path).autoload const_name, full_path
+      end
       self
     end
 
     #
     # Perform any final operations or cleanup. If eager_load is true, this is where they're loaded.
     #
-    def finialize!
+    def finalize!
       all_files.each { |f| require f } if eager_load
       all_files.clear
       self

data/lib/awesome_loader/module_builder.rb

@@ -0,0 +1,72 @@
+module AwesomeLoader
+  #
+  # Recursively builds modules out of directory structures.
+  #
+  class ModuleBuilder
+    # @return [Integer] the dir depth at which to start building modules.
+    attr_reader :root_depth
+    # @return [Module] the root ruby Module
+    attr_reader :root_module
+
+    #
+    # Initializes a new builder.
+    #
+    # @param root_depth [Integer] directory depth at which to start building modules.
+    # @param root_module [Module] Module to load the modules into (default Object). You'll probably always want to keep the default.
+    #
+    def initialize(root_depth:, root_module: Object)
+      @root_depth = root_depth
+      @root_module = root_module
+    end
+
+    #
+    # Returns (building if necessary) the Module represented by the dir path. The path should be relative
+    # to your application root/working directory.
+    #
+    #   # Since root_depth is 2, the first 2 dirs in any path will be ignored
+    #   builder = ModuleBuilder.new(root_depth: 2)
+    #
+    #   builder.module('src/models')
+    #   => Object
+    #
+    #   builder.module('src/features/billing')
+    #   => Billing
+    #
+    #   builder.module('src/services/billing/foo')
+    #   => Billing::Foo
+    #
+    # @param rel_filepath [String] The path, relative to your application root, to the file you want the module for.
+    # @return [Module] The module that should contain the constant in the file.
+    #
+    def module(rel_path)
+      module_names(rel_path).reduce(root_module) { |parent_mod, mod_name|
+        if parent_mod.const_defined? mod_name, false
+          parent_mod.const_get mod_name 
+        else
+          parent_mod.const_set mod_name, Module.new
+        end
+      }
+    end
+
+    #
+    # Returns an array of nested Module names based on the directory structure of the given path.
+    #
+    #   builder = ModuleBuilder.new(root_depth: 2)
+    #
+    #   # Since root_depth is 2, 'src' and 'models' are ignored and there aren't any modules
+    #   builder.nested_dirs('src/models')
+    #   => []
+    #
+    #   builder.nested_dirs('src/features/billing')
+    #   => ['Billing']
+    #
+    #   builder.nested_dirs('src/features/billing/foo')
+    #   => ['Billing', 'Foo']
+    #
+    def module_names(rel_path)
+      dir_names = Utils.clean_path(rel_path).split '/'
+      return [] if rel_path == '.' or root_depth > dir_names.size
+      dir_names[root_depth..-1].map { |name| Utils.camelize name }
+    end
+  end
+end

data/lib/awesome_loader/utils.rb

@@ -4,7 +4,9 @@ module AwesomeLoader
   #
   module Utils
     # Regex to match "snake name" paths
-    SNAKE = /_([a-z])/
+    SNAKE = %r{_([a-z])}
+    LEADING_SEP = %r{^/}
+    TRAILING_SEP = %r{/$}
 
     #
     # Converts a snake_case_name to a CamelCaseName.
@@ -15,5 +17,15 @@ module AwesomeLoader
     def self.camelize(name)
       name.capitalize.gsub(SNAKE) { |match| match[1].capitalize }
     end
+
+    #
+    # Returns the path with any leading or trailing /'s removed.
+    #
+    # @param path [String]
+    # @return [String]
+    #
+    def self.clean_path(path)
+      path.sub(LEADING_SEP, '').sub(TRAILING_SEP, '')
+    end
   end
 end

data/lib/awesome_loader/version.rb

@@ -1,4 +1,4 @@
 module AwesomeLoader
   # Library version
-  VERSION = '0.1.0'.freeze
+  VERSION = '1.0.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: awesome_loader
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Jordan Hollinger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-07 00:00:00.000000000 Z
+date: 2017-04-09 00:00:00.000000000 Z
 dependencies: []
 description: An awesome wrapper for Ruby's built-in autoload
 email: jordan.hollinger@gmail.com
@@ -20,6 +20,7 @@ files:
 - README.md
 - lib/awesome_loader.rb
 - lib/awesome_loader/autoloader.rb
+- lib/awesome_loader/module_builder.rb
 - lib/awesome_loader/utils.rb
 - lib/awesome_loader/version.rb
 homepage: https://github.com/jhollinger/awesome_loader
@@ -42,7 +43,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: An awesome way to autoload your Ruby application