manual.rdoc in carioca-1.0

- old
+ new

@@ -1,12 +1,12 @@
 = Carioca
 
 == Content
 
 Author:: Romain GEORGES <romain@ultragreen.net> 
-Version:: 1.2
-WWW:: http://www.ultragreen.net/projects/methodic
+Version:: 1.0
+WWW:: http://www.ultragreen.net/projects/carioca
 
 == Description 
 
 CARIOCA is Configuration Agent and Registry with Inversion Of Control for your Applications
 Carioca provide a full IoC light Container for designing your applications
@@ -23,12 +23,201 @@
    # gem ins carioca
 
 == Implementation 
 
 * [Carioca]
+* [Carioca::Services]
+* [Carioca:Services::Registry]
 
+== Utilisation
 
-== Example
+Carioca may be used to create Ruby applications, based on a service registry 
+Carioca come with somes builtin services :
+* logger : an Internal logger based on the logger gem.
+* Configuration : a Configuration Service, with Yaml percistance, and pretty accessors.
+* Debug : a Class Debugger, based on Proxy Design pattern and meta-programation like method_missing   
+
+
+=== Getting start
+
+==== Preparing Gem
+
+Just after Installation, Carioca :
+
+  $ gem ins bundler # if needed
+  $ bunlde gem myapp
+  $ cd myapp
+
+
+Edit your myapp.gemspec, add this line in Gem::Specification bloc :
+
+  gem.add_dependency 'carioca'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'carioca'
+
+Description and summary need to be changed to be correctly displayed on Rubygems.
+
+so, execute bundle :
+
+  $ bundle
+
+Your environment, is ready to create your app
+
+==== Prepare Carioca
+
+
+  $ mkdir config
+  $ mkdir bin
+ 
+edit bin/myapp :
+
+  require 'rubygems' 
+  require 'carioca'
+
+  registry = Carioca::Services::Registry.init :file => 'config/myservices.registry'
+
+
+
+After, you could Run Carioca and discover Builtins Services, you need the write access to config path
+
+
+
+  $ ruby -e 'require "rubygems"; require "carioca"; reg = Carioca::Services::Registry.init :file => "config/myservices.registry"; reg.discover_builtins; reg.save!'
+
+
+
+this create you, a New Registry config, with all builtins registered.
+Default path :
+* config file : ./.config
+* log file : /tmp/log.file
+Carioca Registry is a Singleton, and services also be unique instance.
+
+Now you could continue coding your bin/myapp
+
+==== Using Configuration Service
+
+
+  require 'rubygems'
+  require 'carioca'
+
+  registry = Carioca::Services::Registry.init :file => 'config/myservices.registry'
+  config = registry.start_service :name => 'configuration'
+  config.setings.db = { :name => 'mydb' }
+  config.settings.db.host = "myhost"
+  config.settings.db.port = "4545"
+  config.settings.email = "my@email.com"
+  config.save!
+
+
+==== Using Logger Service
+
+logger is automatically loaded with Carioca, loading registry with :debug => true, let you see the Carioca traces. 
+
+
+  require 'rubygems'
+  require 'carioca'
+
+  registry = Carioca::Services::Registry.init :file => 'config/myservices.registry' :debug => true
+  log = registry.get_service :name => 'logger'
+  log.info('myapp') {'my message' }
+
+
+==== Creating and using your own service
+
+before create your own service :
+
+
+  $ mkdir services
+
+
+Services, must be a class, if not do a wrapper
+edit services/myservice.rb
+
+  class MyService
+      def initialize
+      end
+
+      def test(arg = nil)
+        return 'OK'
+      end
+    end
+  end
+
+
+You could use the #service_register API (See spec for all details)
+but, you could write it directly in YAML in your config/myservices.registry :
+add the following lines :
+
+  ...
+  myservice:
+    :type: :file
+    :resource: services/myservice.rb
+    :description: a test service
+    :service: MyServices
+  ...
+
+So in your app :
+
+
+  require 'rubygems'
+  require 'carioca'
+
+  registry = Carioca::Services::Registry.init :file => 'config/myservices.registry'
+  service = registry.start_service :name => 'myservice'
+  service.test('titi')
+
+
+
+==== Using Debug in multiple service instance
+
+
+in your app, for debug you could use the Proxy Debug (you need to run Carioca Registry in debug mode ) :
+(Using "debug_", you create an instance of service debug, so with this syntaxe you could create multiple services instances, with different parameters calling.)
+
+
+  require 'rubygems'
+  require 'carioca'
+
+  registry = Carioca::Services::Registry.init :file => 'config/myservices.registry' :debug => true
+  proxy1  = registry.get_service :name => 'debug_myservice', :params => {:service => 'myservice'}
+  proxy1.test('titi')
+
+
+
+see the log /tmp/log.file  :
+
+
+    D, [2013-03-23T18:20:39.839826 #76641] DEBUG -- ProxyDebug: BEGIN CALL for mapped service myservice
+    D, [2013-03-23T18:20:39.839875 #76641] DEBUG -- ProxyDebug: called: test
+    D, [2013-03-23T18:20:39.839920 #76641] DEBUG -- ProxyDebug: args : titi
+    D, [2013-03-23T18:20:39.839970 #76641] DEBUG -- ProxyDebug: => returned: OK
+    D, [2013-03-23T18:20:39.840014 #76641] DEBUG -- ProxyDebug: END CALL
+
+==== Using Gem for a service
+
+
+For exemple install uuid gem :
+
+  $ gem ins uuid
+
+
+add to your YAML config config/myservices.registry :
+
+  uuid:
+    :type: :gem
+    :resource: uuid
+    :description: a Rubygems called uuid to build UUID ids.
+    :service: UUID  
+
+
+in your app :
+
+  require 'rubygems'
+  require 'carioca'
+
+  registry = Carioca::Services::Registry.init :file => 'config/myservices.registry' :debug => true
+  uuid  = registry.get_service :name => 'uuid'
+  uuid.generate
 
 
 == Copyright
 
 <pre>carioca (c) 2012-2013 Romain GEORGES <romain@ultragreen.net> for Ultragreen Software </pre>