easy_app_helper 0.0.6 → 0.0.7

data/README.md

@@ -24,16 +24,15 @@ Or install it yourself as:
 
 ## Usage
 
-To benefit from the different helpers. Once you installed the gem, the only thing you need to do is:
+To benefit from the different helpers. Once you installed the gem, you just need to require it:
 
 ```ruby
 require 'easy_app_helper'
 ```
 
-and then in the "main class" of your application, include the modules you want to use and call init_app_helper in the initialize method. Then what you can do with each 
-module is defined by each module.
+And then in the "main class" of your application, include the modules you want to use and call init_app_helper in the initialize method. Then what you can do with each module is defined by each module itself.
 
-The basic behaviour (when you include EasyAppHelper), actually adds basic command line handling (actually handled by slop), and provides the mechanism to enable you to add any other EasyAppHelper module.
+The basic behaviour (when you include EasyAppHelper), actually adds basic command line handling (actually handled by [Slop] [2]), and provides the mechanism to enable you to add any other EasyAppHelper module.
 
 ex:
 
@@ -41,10 +40,10 @@ ex:
 require 'easy_app_helper'
 
 class MyApp
- 	include EasyAppHelper
-	def initialize
-		init_app_helper "my_app"
-	end
+  include EasyAppHelper
+  def initialize
+    init_app_helper "my_app"
+  end
 end
 ```
 
@@ -56,13 +55,13 @@ You could then do something like:
 require 'easy_app_helper'
 
 class MyApp
- 	include EasyAppHelper
-	def initialize
-		"my_app" init_app_helper "my_app", "My Super Application", "This is the application everybody was waiting for.", "v 1.0"
-		if app_config[:verbose]
-			 puts "Waouh, hello World !!"
-		end
-	end
+  include EasyAppHelper
+  def initialize
+    init_app_helper "my_app", "My Super Application", "This is the application everybody was waiting for.", "1.0"
+    if app_config[:verbose]
+      puts "Waouh, hello World !!"
+    end
+  end
 end
 ```
 
@@ -76,10 +75,180 @@ Some other modules are provided:
 
 See [classes documentation] [3] for more information.
 
-### Debugging
+### Complete example
+
+Here under a more complete (still useless) example using all the modules.
+
+```ruby
+require 'easy_app_helper'
+
+class MyApp
+  include EasyAppHelper
+  include EasyAppHelper::Config
+  include EasyAppHelper::Logger
+
+  def initialize
+    init_app_helper "my_app", "My Super Application", "This is the application everybody was waiting for.", "1.0"
+    logger.info "Application is now started."
+    show_config if app_config[:verbose]
+  end
+
+  def show_config
+    puts "Application config is"
+    puts app_config.to_yaml
+  end
+
+  def add_specifc_command_line_options(opt) 
+    opt.on :s, :stupid, 'This is a very stupid option', :argument => false
+  end
+end
+
+app = MyApp.new
+```
+
+With this example you can already test some of the behaviours brought to the application by the different modules.
+
+		 $ ruby ./test_app.rb
+		 
+Nothing displayed... hum in fact normal.
+
+*The EasyAppHelper::Base module*
+
+		 $ ruby ./test_app.rb --verbose
+		 Application config is
+		 ---
+		 :verbose: true
+		 :log-level: 2
+
+Here again we see the impact of the --verbose
+
+		 $ ruby ./test_app.rb --help
+
+		 Usage: my_app [options]
+		 My Super Application Version: 1.0
+
+		 This is the application everybody was waiting for.
+		 -- Generic options -------------------------------------------
+        			--auto              Auto mode. Bypasses questions to user.
+        			--simulate          Do not perform the actual underlying actions.
+    			-v, --verbose           Enable verbose mode.
+				  -h, --help              Displays this help.
+
+		 -- Debug and logging options ---------------------------------
+        			--debug             Run in debug mode.
+        			--debug-on-err      Run in debug mode with output to stderr.
+        			--log-level         Log level from 0 to 5, default 2.
+        			--log-file          File to log to.
+
+		 -- Configuration options -------------------------------------
+        			--config-file       Specify a config file.
+
+		 -- Script specific options------------------------------------
+     			-s, --stupid            This is a very stupid option
+
+
+Here we see that:
+
+* each included module added its own part in the global help
+* The information passed to init_app_helper has been used in order to build a consistent help.
+* The method implemented add_specifc_command_line_options did add the --stupid command line option and that it fits within the global help. the syntax is the [Slop] [2] syntax, and many other options are available. See the [Slop] [2] for further info.
+
+*The EasyAppHelper::Debug module*
+
+Now let's try some options related to the EasyAppHelper::Logger module
+
+		 $ ruby ./test_app.rb --debug
+
+Nothing is displayed. Why ? We used the logger.info stuff !! Just because the default log-level is 2 (Logger::Severity::WARN), whereas we did a info (Logger::Severity::INFO equals to 1).
+Thus we can do a:
+
+		 $ ruby ./test_app.rb --debug --log-level 1
+		 I, [2013-03-20T10:58:40.819096 #13172]  INFO -- : Application is now started.
+
+Which correctly displays the log.
+Of course, as mentioned by the inline doc, this could go to a log file using the --log-file option...
+
+*The EasyAppHelper::Config module*
+
+From what we did, nothing really shows what the config module brought to the application, whereas in fact this is the one bringing the more features...
+
+This module will try to find config files (YAML format) in different places. All the config files could have a lot of different extensions (EasyAppHelper::Config::Instanciator::CONFIG_FILE_POSSIBLE_EXTENSIONS). Here under we will just say ".ext", but all of them are tried:
+
+First it will try to find the file:
+
+			/etc/EasyAppHelper.ext
+
+In this file you could define some options common to all the scripts you will build on top of EasyAppHelper helpers.
+
+Then it will try to find (it will stop on the first found):
+
+		 /etc/my_app.ext
+		 /usr/local/etc/my_app.ext
+
+In this file you could define some options common to all users
+
+Then it will try to find:
+
+		 ${HOME}/.config/my_app.conf
+
+Where each user will generally store his own configuration.
+
+Each of these file adds options to the common app_config hash. Enabling a simple and powerful override mechanism.
+
+Then everything defined on the command line will itself override what has been defined in these config files.
+Then if --config-file option is specified in the command line, it tries to load that file.
+
+Thus in the end following mechanism:
+
+		 admin wide -> system wide -> user -> command line options -> --config-file
+
+
+### Debugging the framework itself
 
 If you want to debug what happens during the framework instanciation, you can use the DEBUG_EASY_MODULES environment variable.
 
+ex:
+
+		 $ DEBUG_EASY_MODULES=y ruby ./test_app.rb
+		 D, [2013-03-20T13:14:32.149109 #10564] DEBUG -- : Processing helper module: EasyAppHelper::Logger::Instanciator
+		 D, [2013-03-20T13:14:32.149109 #10564] DEBUG -- : Processing helper module: EasyAppHelper::Config::Instanciator
+		 D, [2013-03-20T13:14:32.149109 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.conf" as config file.
+		 D, [2013-03-20T13:14:32.149109 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.yml" as config file.
+		 D, [2013-03-20T13:14:32.149109 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.cfg" as config file.
+		 D, [2013-03-20T13:14:32.149109 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.CFG" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.YML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.YAML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/EasyAppHelper.Yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.conf" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.yml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.cfg" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.CFG" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.YML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.YAML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/etc/my_app.Yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.conf" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.yml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.cfg" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.CFG" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.YML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.YAML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/usr/local/etc/my_app.Yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.conf" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.yml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.cfg" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.CFG" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.YML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.YAML" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Trying "/home/user_home_dir/.config/my_app.Yaml" as config file.
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Processing helper module: EasyAppHelper::Base::Instanciator
+		 D, [2013-03-20T13:14:32.164733 #10564] DEBUG -- : Processing helper module: EasyAppHelper::Common::Instanciator
+
+You can observe that for each included module, the framwork uses its related so-called instanciator in order to know how to start the module, externalizing the methods into a separated module to avoid poluting your own application with methods useless for you when you include the module.
+
 ## Contributing
 
 1. Fork it

data/lib/easy_app_helper/config.rb

@@ -94,17 +94,17 @@ module EasyAppHelper::Config::Instanciator
 
   # Reads config from admin config file.
   def self.load_admin_wide_config(app)
-    load_config_file app, find_file(ADMIN_CONFIG_POSSIBLE_PLACES, ADMIN_CONFIG_FILENAME)
+    load_config_file app, find_file(app, ADMIN_CONFIG_POSSIBLE_PLACES, ADMIN_CONFIG_FILENAME)
   end
 
   # Reads config from system config file.
   def self.load_system_wide_config(app, script_filename)
-    load_config_file app, find_file(SYSTEM_CONFIG_POSSIBLE_PLACES, script_filename)
+    load_config_file app, find_file(app, SYSTEM_CONFIG_POSSIBLE_PLACES, script_filename)
   end
 
   # Reads config from user config file.
   def self.load_user_config(app, script_filename)
-    load_config_file app, find_file(USER_CONFIG_POSSIBLE_PLACES, script_filename)
+    load_config_file app, find_file(app, USER_CONFIG_POSSIBLE_PLACES, script_filename)
   end
 
   # Loads a config file.
@@ -122,12 +122,14 @@ module EasyAppHelper::Config::Instanciator
   end
 
   # Tries to find config files according to places (array) given and possible extensions
-  def self.find_file(places, filename)
+  def self.find_file(app, places, filename)
     places.each do |dir|
       CONFIG_FILE_POSSIBLE_EXTENSIONS.each do |ext|
         filename_with_path = dir + '/' + filename + '.' + ext
         if File.exists? filename_with_path
           return filename_with_path
+        else
+          app.logger.debug "Trying \"#{filename_with_path}\" as config file."
         end
       end
     end

data/lib/easy_app_helper/logger.rb

@@ -87,7 +87,7 @@ module EasyAppHelper::Logger::Instanciator
     slop_definition.separator "\n-- Debug and logging options ---------------------------------"
     slop_definition.on :debug, 'Run in debug mode.', :argument => false
     slop_definition.on 'debug-on-err', 'Run in debug mode with output to stderr.', :argument => false
-    slop_definition.on 'log-level', "Log level from 0 to 5, default #{Logger::Severity::ERROR}.", :argument => true, :as => Integer
+    slop_definition.on 'log-level', "Log level from 0 to 5, default #{EasyAppHelper::Common::DEFAULT_LOG_LEVEL}.", :argument => true, :as => Integer
     slop_definition.on 'log-file', 'File to log to.', :argument => true
   end
 

data/lib/easy_app_helper/version.rb

@@ -6,5 +6,5 @@
 ################################################################################
 
 module EasyAppHelper
-  VERSION = "0.0.6"
+  VERSION = "0.0.7"
 end

metadata

@@ -1,69 +1,78 @@
 --- !ruby/object:Gem::Specification
 name: easy_app_helper
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
+  prerelease: 
 platform: ruby
 authors:
 - L.Briais
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-19 00:00:00.000000000 Z
+date: 2013-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: slop
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
-    - - '>='
+    - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: Easy Application Helpers framework
@@ -88,26 +97,28 @@ files:
 homepage: https://github.com/lbriais/easy_app_helper
 licenses:
 - MIT
-metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
-  - - '>='
+  - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.0.rc.2
+rubygems_version: 1.8.25
 signing_key: 
-specification_version: 4
+specification_version: 3
 summary: Provides cool helpers to your application, including configuration and logging
   features
 test_files: []
+has_rdoc: 

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA1:
-  metadata.gz: 50d87ed053be2fd95061ffa2437b85d54624733d
-  data.tar.gz: 49c874b9d20f77fbd39dd0b1e85dfe3ac6b59dd5
-SHA512:
-  metadata.gz: 07a81b4154ce7c2325d64b7d471063e458fca4d14e161fa97ad612523dad0475b85dbb3d7e5988ce3136d6cacaea3b09c860bb81ef87daf67d480d121201b72d
-  data.tar.gz: 2b2d0d30cd08aa7d3e6a1d847734d2c60937b653d39f5498289e8e98dc9a07a0768bfd84066f205b996699126b5c70ba0d8c68cfb955e6dab6456e34f5e943bc