micon 0.1.16 → 0.1.17

data/readme.md

@@ -1,95 +1,188 @@
-# Assembles and manages pieces of Your Application
+# Micon IoC assembles and manages Your Application
 
-Micon is infrastructural component, invisible to user and it's main goal is to simplify development. It reduces complex monolithic application to set of simple low coupled components. 
+Micon is infrastructural component, invisible to user and it's main goal is to simplify development. It reduces complex monolithic application to set of simple low coupled components.  
 
 Concentrate on business logic and interfaces and Micon will provide automatic configuration, life cycle management and dependency resolving.
 
 Technically it's [IoC][ioc] like framework with components, callbacks, scopes and bijections, inspired by Spring and JBoss Seam.
 
-Is it usefull, is there any real-life application? - I'm using it as a heart of my [web framework][rad_core], this site http://ruby-lang.info for example powered with it.
+Is it usefull, is there any real-life application? - I'm using it as a heart of my [web framework][rad_core], this sites http://robotigra.ru, http://ruby-lang.info for example powered with it.
 
 ## Usage
-	
+  
 Let's suppose you are building the Ruby on Rails clone, there are lots of modules let's try to deal with them
 
-	require 'micon'
-	def app; Micon end
-
-	# static (singleton) components
-	class Environment
-		register_as :environment
-	end
-
-	class Logger
-		register_as :logger
-		
-		def info msg; end
-	end	
-
-	class Router
-		register_as :router
-		
-		def parse rote_filename
-		  # do something
-		end
-	end
-
-	# callbacks, we need to parse routes right after environment is initialized
-	app.after :environment do
-		app[:router].parse '/config/routes.rb'
-	end
-
-	# dynamic components, will be created and destroyed for every request
-	class Request
-		register_as :request, scope: :request
-	end
-
-	class Application
-		# injecting components into attributes
-		inject request: :request, logger: :logger
-
-		def do_business
-			# now we can use injected component
-			do_something_with request
-			logger.info 'done'
-		end
-		
-		def do_something_with request; end
-	end
-
-	# Web Server / Rack Adapter
-	class RackAdapter
-		def call env		
-			# activating new request scope, the session component will be created and destroyed automatically
-			app.activate :request, {} do
-				Application.new.do_business
-			end
-		end
-	end    
-	
-	RackAdapter.new.call({})
-	
-For actual code go to spec/overview_spec.rb
+``` ruby
+require 'micon'
+
+# Here's our Web Framework, let's call it Rad
+
+# Let's define shortcut to access the IoC API (optional
+# but handy step). I don't know how You would like to call it,  
+# so I leave this step to You.
+class ::Object
+  def rad; MICON end
+end
+
+# let's define some components  
+# the :logger is one per application, it's a static component (like singleton)
+class Logger
+  register_as :logger
+  attr_accessor :log_file_path
+  def info msg
+    puts "#{msg} (writen to #{log_file_path})" unless defined?(RSpec)
+  end
+end
+
+# To demostrate basics of working with compnents let's configure our :logger
+# explicitly (in the next example, it will be configured automatically).
+rad.logger.log_file_path = '/tmp/rad.log'  
+
+# The :router requires complex initialization, so we use 
+# another form of component registration.
+class Router
+  def initialize routes; @routes = routes end
+  def decode request;  
+    class_name, method = @routes[request.url]  
+    return eval(class_name), method # returning actual class
+  end
+end
+rad.register :router do
+  Router.new '/index' => ['PagesController', :index]
+end
+
+# The :controller component should be created and destroyed dynamically,  
+# for each request, we specifying that component is dynamic  
+# by declaring it's :scope.  
+# And, we don't know beforehead what it actully will be, for different  
+# request there can be different controllers,  
+# so, here we just declaring it without any initialization block, it
+# will be created at runtime later.
+rad.register :controller, scope: :request
+
+# Let's define some of our controllers, the PagesController, note - we
+# don't register it as component.
+class PagesController
+  # We need access to :logger and :request, let's inject them
+  inject logger: :logger, request: :request
+
+  def index
+    # Here we can use injected component
+    logger.info "Application: processing #{request}"  
+  end
+end
+
+# Request is also dynamic, and it also can't be created beforehead.
+# We also registering it without initialization, it will be
+# created at runtime later.
+class Request
+  attr_reader :url  
+  def initialize url; @url = url end  
+  def to_s; @url end
+end
+# Registering without initialization block.
+rad.register :request, scope: :request
+
+# We need to integrate our application with web server, for example with the Rack.
+# When the server receive web request, it calls the :call method of our RackAdapter
+class RackAdapter
+  # Injecting components
+  inject request: :request, controller: :controller
+  
+  def call env
+    # We need to tell Micon that the :request scope is started, so it will know
+    # that some dynamic components should be created during this scope and  
+    # destroyed at the end of it.
+    rad.activate :request, {} do
+      # Here we manually creating the Request component
+      self.request = Request.new '/index'
+  
+      # The :router also can be injected via :inject,
+      # but we can also use another way to access components,
+      # every component also availiable as rad.<component_name>
+      controller_class, method = rad.router.decode request
+  
+      # Let's create and call our controller
+      self.controller = controller_class.new
+      controller.send method
+    end
+  end
+end  
+
+# Let's pretend that there's a Web Server and run our application,
+# You should see something like this in the console:
+#   Application: processing /index
+RackAdapter.new.call({})
+```
+
+The example above is a good way to demonstrate how the IoC works in general, but it will not show two **extremelly important** aspects of IoC: **auto-discovery** and **auto-configuration**.
+In real-life scenario You probably will use it in a little different way, as will be shown below, and utilize these important features (there's a short article about why these features are important [You underestimate the power of IoC][article]).
+
+I would like to repeat it one more time - **auto-discovery and auto-configuration is extremelly important features** of the IoC, don't ignore them.
+
+Below are the same example but done with utilizing these features, this is how the Micon IoC is supposed be used in the real-life scenario. As You can see it's almost empty, because all the components are auto-discovered, auto-loaded and auto-configured. Components are located in the [spec/example_spec/lib](https://github.com/alexeypetrushin/micon/blob/master/spec/example_spec/lib) folder.
+
+Please note that this time logger convigured automatically, with logger.yml configuration file.
+
+``` ruby
+require 'micon'
+require 'class_loader'
+
+# Here's our Web Framework, let's call it Rad
+
+# Let's define shortcut to access the IoC API (optional
+# but handy step). I don't know how You would like to call it,  
+# so I leave this step to You.
+class ::Object
+  def rad; MICON end
+end
+
+# Auto-discovering:
+#  
+# All components (:logger, :router, :request, :controller) are  
+# defined in spec/example_spec/lib/components folder.
+# All classes (PagesController, RackAdapter) are
+# located in spec/example_spec/lib folder.
+#  
+# Note that there's no any "require 'xxx'" clause, all components and
+# classes are loaded and dependecies are resolved automatically.
+
+# Auto-configuring
+#  
+# Remember our manual configuration of "logger.log_file_path" from  
+# the previous example?
+# This time it will be configured automatically, take a look at
+# the spec/example_spec/lib/components/logger.yml file.
+#  
+# Note, that there are also logger.production.yml, configs are smart
+# and are merged in the following order:
+# logger.yml <- logger.<env>.yml <- <runtime_path>/config/logger.yml
+# (If you define :environment and :runtime_path variables).
+  
+# Let's pretend that there's a Web Server and run our application,
+# You should see something like this in the console:
+#   Application: processing /index
+RackAdapter.new.call({})
+```
+  
+For the actual code please look at [spec/example_spec.rb](https://github.com/alexeypetrushin/micon/blob/master/spec/example_spec.rb)
 
 ## Note
 
 Current wersion isn't thread-safe, instead it supported evented IO (EventMachine).
-Actually I implemented first wersion as thread-safe, but because there's no actual multithreading in
-Ruby, the only thing it does - adds complexity and performance losses, so I removed it.
-But if you need it it can be done very easy.
-	
+Actually I implemented first wersion as thread-safe, but because there's no actual multithreading in Ruby, the only thing it does - adds complexity and performance losses, so I removed it.
+But if you need it it can be easily done.
+  
 ## Installation
 
-	$ sudo gem install micon
-	
-## TODO
-
-- remove threads and synchronization support, probably it will be never needed in any real situation, because 
-there's no multithreading in ruby.
-- refactor specs, they are messy a little.
-- maybe it makes sense to add ability to add dependencies for components after component registration?
+``` bash
+gem install micon
+```
+  
+## License
 
 Copyright (c) Alexey Petrushin http://petrush.in, released under the MIT license.
 
 [ioc]: http://en.wikipedia.org/wiki/Inversion_of_control
-[rad_core]: https://github.com/alexeypetrushin/rad_core
+[rad_core]: https://github.com/alexeypetrushin/rad_core
+[article]: http://ruby-lang.info/blog/you-underestimate-the-power-of-ioc-3fh

data/spec/callbacks_spec.rb

@@ -8,17 +8,17 @@ describe "Callbacks" do
   describe "components callbacs" do
     it "basic" do
       micon.register(:the_object){"The Object"}
-    
+  
       check = mock
       check.should_receive(:before)
       micon.before :the_object do
         check.before
       end
-    
+  
       check.should_receive(:after1).ordered
       check.should_receive(:after2).ordered
       obj = nil
-      micon.after :the_object do |o|        
+      micon.after :the_object do |o|  
         check.after1
         obj = o
       end
@@ -26,7 +26,7 @@ describe "Callbacks" do
         check.after2
         obj.object_id.should == o.object_id
       end
-      
+  
       micon[:the_object].should == obj
     end
   
@@ -54,8 +54,8 @@ describe "Callbacks" do
       micon.after_scope(:custom){|container| check.after2 container}
 
       micon.activate(:custom, {}){check.run}
-    end    
-  end 
+    end  
+  end  
   
   describe "miscellaneous" do
     it "should fire callbacks after assigning component" do
@@ -67,32 +67,32 @@ describe "Callbacks" do
       end
       micon.the_object = 'the_object'
     end
-    
+  
     it "should raise error if callback defined after component already created" do
       micon.register(:the_object){"the_object"}
       micon[:the_object]
-      
+  
       -> {micon.before(:the_object){}}.should raise_error(/already created/)
       -> {micon.after(:the_object){}}.should raise_error(/already created/)
     end
-    
+  
     it "should raise error if callback defined after scope already started" do
       micon.activate :custom, {} do
         -> {micon.before_scope(:custom){}}.should raise_error(/already started/)
         -> {micon.after_scope(:custom){}}.should raise_error(/already started/)
       end
     end
-    
+  
     it ":after with bang: false should execute callback if component already started and also register it as :after callback" do
       micon.register(:the_object){"the_object"}
       micon[:the_object]
-      
+  
       check = mock
-      check.should_receive(:first).twice      
+      check.should_receive(:first).twice  
       micon.after(:the_object, bang: false){check.first}
-      
+  
       micon.delete :the_object
       micon[:the_object]
     end
-  end 
+  end  
 end

data/spec/config_spec.rb

@@ -1,18 +1,18 @@
 require 'spec_helper'
 
-describe "Configuration" do    
+describe "Configuration" do
   before{self.micon = Micon::Core.new}
   
   it "should configure component if config provided" do
-    micon.register(:logger){::OpenStruct.new}    
-    with_load_path "#{spec_dir}/basic/lib" do      
+    micon.register(:logger){::OpenStruct.new}  
+    with_load_path "#{spec_dir}/basic/lib" do  
       micon[:logger].level.should == :info
     end
   end
   
   it "should merge in order: conf <- conf.mode <- runtime <- runtime.mode" do
     micon.register(:object){::OpenStruct.new}
-    with_load_path "#{spec_dir}/order/lib" do    
+    with_load_path "#{spec_dir}/order/lib" do  
       micon.runtime_path = "#{spec_dir}/order/app"
       micon.mode = :production
       micon[:object].tap do |o|

data/spec/constants_spec.rb

@@ -1,70 +1,70 @@
 # require 'spec_helper'
-# 
+#  
 # describe "Autoloading" do
 #   with_load_path "#{spec_dir}/get_constant_component/lib"
-#   
+#  
 #   before do
 #     self.micon = Micon::Core.new
 #   end
-# 
+#  
 #   after do
 #     remove_constants :TheRouter, :TheRad, :TheController, :SomeModule
 #   end
-#   
+#  
 #   describe "get_constant_component" do
 #     it "should autoload components" do
 #       micon.get_constant_component(:TheController).should == "TheController"
 #     end
-#     
+#  
 #     it "should not raise error if component not defined" do
 #       micon.get_constant_component(:TheValue).should == nil
 #       micon.register(:TheValue, constant: true){"TheValue"}
 #       micon.get_constant_component(:TheValue).should == "TheValue"
 #     end
-#     
+#  
 #     it "should get constants only" do
 #       micon.register(:TheController){"TheController"}
 #       micon.get_constant_component(:TheController).should == nil
-#       
+#  
 #       micon.register(:TheController, constant: true){"TheController"}
 #       micon.get_constant_component(:TheController).should == "TheController"
 #     end
 #   end
-# 
+#  
 #   it 'validation' do
 #     -> {micon.register 'TheController', constant: true}.should raise_error(/symbol/)
 #     -> {micon.register 'TheController'.to_sym, constant: true, scope: :custom}.should raise_error(/scope/)
 #   end
-# 
+#  
 #   it "should use constants as components" do
 #     -> {::TheRouter}.should raise_error(/uninitialized constant/)
-#     
+#  
 #     micon.register :TheRouter, constant: true do
 #       "TheRouter"
-#     end    
-#     
+#     end  
+#  
 #     module ::TheRad
 #       TheRouter.should == 'TheRouter'
 #     end
 #     ::TheRouter.should == 'TheRouter'
 #     micon[:TheRouter].should == 'TheRouter'
 #   end
-#   
+#  
 #   it "should support nested constants" do
-#     module ::TheRad; end    
+#     module ::TheRad; end  
 #     -> {::TheRad::TheView}.should raise_error(/uninitialized constant/)
-#     
+#  
 #     micon.register 'TheRad::TheView'.to_sym, constant: true do
 #       'TheRad::TheView'
-#     end    
-#     
+#     end  
+#  
 #     module ::SomeModule
 #       ::TheRad::TheView.should == 'TheRad::TheView'
 #     end
 #     ::TheRad::TheView.should == 'TheRad::TheView'
 #     micon['TheRad::TheView'.to_sym].should == 'TheRad::TheView'
 #   end
-#   
+#  
 #   it "should check if constant is already defined" do
 #     micon.register :TheRouter, constant: true do
 #       class ::TheRouter; end

data/spec/custom_scope_spec.rb

@@ -6,7 +6,7 @@ describe "Custom Scope" do
   end
   
   it "activate" do
-    container = {}    
+    container = {}  
     micon.should_not be_active(:custom)
     micon.activate :custom, container
     micon.should be_active(:custom)
@@ -15,7 +15,7 @@ describe "Custom Scope" do
 
     micon.deactivate :custom
     -> {micon.deactivate :custom}.should raise_error(/not active/)
-    
+  
     micon.should_not be_active(:custom)
     micon.activate :custom, container do
       micon.should be_active(:custom)
@@ -31,20 +31,20 @@ describe "Custom Scope" do
   it "get" do
     micon.register(:value, scope: :custom){"The Object"}
     container, the_object = {}, nil
-    
+  
     micon.activate :custom, container do
       micon[:value].should == "The Object"
       the_object = micon[:value]
     end
-    
+  
     micon.activate :custom, {} do
       micon[:value].object_id.should_not == the_object.object_id
     end
-    
+  
     micon.activate :custom, container do
       micon[:value].object_id.should == the_object.object_id
     end
-    
+  
     container.size.should == 1
     container[:value].should == the_object
   end
@@ -52,17 +52,17 @@ describe "Custom Scope" do
   it "set" do
     micon.register(:value, scope: :custom){"The Object"}
     container = {}
-    
+  
     micon.activate :custom, container do
       micon[:value].should == "The Object"
       micon[:value] = "Another Object"
       the_object = micon[:value]
     end
-    
+  
     micon.activate :custom, {} do
       micon[:value].should == "The Object"
     end
-    
+  
     micon.activate :custom, container do
       micon[:value].should == "Another Object"
     end

data/spec/example_spec/lib/components/controller.rb

@@ -0,0 +1,8 @@
+# The :controller component should be created and destroyed dynamically,  
+# for each request, we specifying that component is dynamic  
+# by declaring it's :scope.  
+# And, we don't know beforehead what it actully will be, for different  
+# request there can be different controllers,  
+# so, here we just declaring it without any initialization block, it
+# will be created at runtime later.
+rad.register :controller, scope: :request

data/spec/example_spec/lib/components/logger.production.yml

@@ -0,0 +1 @@
+log_file_path: /tmp/rad.production.log

data/spec/example_spec/lib/components/logger.rb

@@ -0,0 +1,8 @@
+# the :logger is one per application, it's a static component (like singleton)
+class Logger
+  register_as :logger  
+  attr_accessor :log_file_path  
+  def info msg
+    puts "#{msg} (writen to #{log_file_path})" unless defined?(RSpec)
+  end
+end

data/spec/example_spec/lib/components/logger.yml

@@ -0,0 +1 @@
+log_file_path: /tmp/rad.log

data/spec/example_spec/lib/components/request.rb

@@ -0,0 +1,2 @@
+# Registering without initialization block.
+rad.register :request, scope: :request

data/spec/example_spec/lib/components/router.rb

@@ -0,0 +1,12 @@
+# The :router requires complex initialization, so we use 
+# another form of component registration.
+class Router
+  def initialize routes; @routes = routes end
+  def decode request;  
+    class_name, method = @routes[request.url]  
+    return eval(class_name), method # returning actual class
+  end
+end
+rad.register :router do
+  Router.new '/index' => ['PagesController', :index]
+end

data/spec/example_spec/lib/pages_controller.rb

@@ -0,0 +1,11 @@
+# Let's define some of our controllers, the PagesController, note - we
+# don't register it as component.
+class PagesController
+  # We need access to :logger and :request, let's inject them
+  inject logger: :logger, request: :request
+
+  def index
+    # Here we can use injected component
+    logger.info "Application: processing #{request}"  
+  end
+end

data/spec/example_spec/lib/rack_adapter.rb

@@ -0,0 +1,25 @@
+# We need to integrate our application with web server, for example with the Rack.
+# When the server receive web request, it calls the :call method of our RackAdapter
+class RackAdapter
+  # Injecting components
+  inject request: :request, controller: :controller
+
+  def call env
+    # We need to tell Micon that the :request scope is started, so it will know
+    # that some dynamic components should be created during this scope and  
+    # destroyed at the end of it.
+    rad.activate :request, {} do
+      # Here we manually creating the Request component
+      self.request = Request.new '/index'
+  
+      # The :router also can be injected via :inject,
+      # but we can also use another way to access components,
+      # every component also availiable as rad.<component_name>
+      controller_class, method = rad.router.decode request
+  
+      # Let's create and call our controller
+      self.controller = controller_class.new
+      controller.send method
+    end
+  end
+end

data/spec/example_spec/lib/request.rb

@@ -0,0 +1,8 @@
+# Request is also dynamic, and it also can't be created beforehead.
+# We also registering it without initialization, it will be
+# created at runtime later.
+class Request
+  attr_reader :url  
+  def initialize url; @url = url end  
+  def to_s; @url end
+end