prometheus-splash 0.5.3 → 0.6.0

data/lib/splash/exiter.rb

@@ -1,5 +1,9 @@
 # coding: utf-8
+
+# base Splash namespace
 module Splash
+
+  # Exiter namespace
   module Exiter
     include Splash::Loggers
     EXIT_MAP= {
@@ -35,6 +39,10 @@ module Splash
 
     }
 
+    # exiter wrapper
+    # @param [Hash] options
+    # @option options [Symbol] :case an exit case
+    # @option options [String] :more a complementary string to display
     def splash_exit(options = {})
       log = get_logger
       mess = ""
@@ -50,7 +58,13 @@ module Splash
       end
     end
 
+    def splash_return(options = {})
 
+      data = EXIT_MAP[options[:case]]
+      data[:status] = (data[:code]>0)? :failure : :success
+      data[:more] = options[:more] if options[:more]
+      return data
+    end
 
   end
 end

data/lib/splash/helpers.rb

@@ -1,24 +1,30 @@
-# @option  options [String] :stdout_trace the path of the file where to redirect STDOUT
 # coding: utf-8
+
+# base Splash Module
 module Splash
-  module Helpers
 
+  # Helpers namespace
+  module Helpers
 
 
+    # return the 'root' name
+    # @return [String] name
     def user_root
       return Etc.getpwuid(0).name
     end
 
+    # return the 'root' group name : root or wheel
+    # @return [String] name
     def group_root
       return Etc.getgrgid(0).name
     end
 
-    # facilité pour récupérer les PID depuis une regexp
+    # facility for retreiving PID from process query
     # @param [Hash] options
-    # @option options [String] :pattern un motif de regexp
-    # @option options [Array] :patterns Un tableau de motif de regexp
-    # @option options [Bool] :full renvoie tout les details si True
-    # @return [String|Array] le PID or tout les détails
+    # @option options [String] :pattern a regexp to search
+    # @option options [Array] :patterns an array of regexp to search
+    # @option options [Bool] :full flag to retrieve all process data not only PID
+    # @return [String|Array] PID or data structure
     def get_processes(options = {})
       patterns = []
       patterns  = options[:patterns] if options[:patterns]
@@ -35,7 +41,7 @@ module Splash
     end
 
 
-    # facilities to find a file in gem path
+    # facility to find a file in gem path
     # @param [String] _gem a Gem name
     # @param [String] _file a file relative path in the gem
     # @return [String] the path of the file, if found.
@@ -67,8 +73,8 @@ module Splash
 
 
 
-    # facilité pour vérifier si le process actif est root
-    # @return [Bool] vrai ou faux
+    # facility to verifyingif the active process run as root
+    # @return [Bool] status
     def is_root?
       case (Process.uid)
       when 0
@@ -78,9 +84,9 @@ module Splash
       end
     end
 
-    # facilité pour s'assurer qu'on execute une méthode avec les droits root
+    # wrapping execution if process run as root
     # @param [Symbol] method a method name th wrap
-    # @return [void] le retour de la méthode wrappée
+    # @return [void] return of wrapped method
     def run_as_root(method, options = {})
       unless is_root?
         return {:case => :not_root, :more => "subcommands : #{method.to_s}"}
@@ -188,15 +194,15 @@ module Splash
       return 0
     end
 
-    # @!group facilités sur le système de fichier
+    # @!group facilities for file system commands
 
-    # facilité d'installation de fichier
+    # facility for file installation
     # @param [Hash] options
-    # @option options [String] :source le chemin source du fichier
-    # @option options [String] :target le chemin cible du fichier
-    # @option options [String] :mode les droits du fichier du type Octal "XXX"
-    # @option options [String] :owner le owner du fichier
-    # @option options [String] :group le groupe du fichier
+    # @option options [String] :source file source path
+    # @option options [String] :target file target path
+    # @option options [String] :mode String for OCTAL rights like "644"
+    # @option options [String] :owner file owner for target
+    # @option options [String] :group  file group for target
     def install_file(options = {})
       #begin
         FileUtils::copy options[:source], options[:target] #unless File::exist? options[:target]
@@ -208,12 +214,12 @@ module Splash
       #end
     end
 
-    # facilité de création de répertoire
+    # facility for folder creation
     # @param [Hash] options
-    # @option options [String] :path le répertoire à créer (relatif ou absolut)
-    # @option options [String] :mode les droits du fichier du type Octal "XXX"
-    # @option options [String] :owner le owner du fichier
-    # @option options [String] :group le groupe du fichier
+    # @option options [String] :path folder path (relative or absolute)
+    # @option options [String] :mode String for OCTAL rights like "644"
+    # @option options [String] :owner file owner for folder
+    # @option options [String] :group  file group for folder
     def make_folder(options = {})
       begin
         FileUtils::mkdir_p options[:path] unless File::exist? options[:path]
@@ -225,10 +231,10 @@ module Splash
       end
     end
 
-    # facilité de liaison symbolique  de fichier
+    # facility for Symbolic link
     # @param [Hash] options
-    # @option options [String] :source le chemin source du fichier
-    # @option options [String] :link le chemin du lien symbolique
+    # @option options [String] :source path of the file
+    # @option options [String] :link path of the symlink
     def make_link(options = {})
       begin
         FileUtils::rm options[:link] if (File::symlink? options[:link] and not File::exist? options[:link])
@@ -241,15 +247,15 @@ module Splash
     # @!endgroup
 
 
-    #@!group  Vérifiers de l'application
+    #@!group  Verifiers for application : FS and TCP/IP services
 
-    # verifier d'existence d'un repertoire
+    # check folder
     # @return [Array] of Symbol with error type : [:inexistant,:mode,:owner,:group]
     # @param [Hash] options
-    # @option options [String] :path le répertoire (relatif ou absolut) obligatoire
-    # @option options [String] :mode droit du  répertoire optionnel
-    # @option options [String] :owner owner du répertoire optionnel
-    # @option options [String] :group groupe du répertoire optionnel
+    # @option options [String] :path folder path (relative or absolute)
+    # @option options [String] :mode String for OCTAL rights like "644", optionnal
+    # @option options [String] :owner file owner for folder, optionnal
+    # @option options [String] :group  file group for folder, optionnal
     def verify_folder(options ={})
       res = Array::new
       return  [:inexistant] unless File.directory?(options[:name])
@@ -267,21 +273,21 @@ module Splash
       return res
     end
 
-    # verifier d'existence d'un lien
-    # @return [Bool] vrai ou faux
+    # check symlink
+    # @return [Boolean]
     # @param [Hash] options
-    # @option options [String] :name path du lien
+    # @option options [String] :name path of the link
     def verify_link(options ={})
       return File.file?(options[:name])
     end
 
-    # verifier d'existence d'un fichier
+    # check file
     # @return [Array] of Symbol with error type : [:inexistant,:mode,:owner,:group]
     # @param [Hash] options
-    # @option options [String] :name path du fichier obligatoire
-    # @option options [String] :mode droit du fichier optionnel
-    # @option options [String] :owner owner du fichier optionnel
-    # @option options [String] :group groupe du fichier optionnel
+    # @option options [String] :name path of file
+    # @option options [String] :mode String for OCTAL rights like "644", optionnal
+    # @option options [String] :owner file owner for file, optionnal
+    # @option options [String] :group  file group for file, optionnal
     def verify_file(options ={})
       res = Array::new
       return  [:inexistant] unless File.file?(options[:name])
@@ -299,11 +305,11 @@ module Splash
       return res
     end
 
-    # verifier de l'ecoute d'un service sur un host et port donné en TCP
-    # @return [Bool] vrai ou faux
+    # TCP/IP service checker
+    # @return [Bool] status
     # @param [Hash] options
-    # @option options [String] :host le nom d'hote
-    # @option options [String] :port le port TCP
+    # @option options [String] :host hostname
+    # @option options [String] :port TCP port
     def verify_service(options ={})
       begin
         Timeout::timeout(1) do
@@ -322,6 +328,24 @@ module Splash
     #!@endgroup
 
 
+    def format_response(data, format)
+      response = case format
+                 when 'application/json' then JSON.pretty_generate(data)
+                 when 'text/x-yaml' then data.to_yaml
+                 else JSON.pretty_generate(data)
+                 end
+      return response
+    end
+
+    def format_by_extensions(extension)
+      result = {
+        'json' => 'application/json',
+        'yaml' => 'text/x-yaml',
+        'yml' => 'text/x-yaml'
+      }
+       return result[extension]
+    end
+
 
   end
 end

data/lib/splash/loggers.rb

@@ -1,12 +1,20 @@
 # coding: utf-8
 
-
+# base Splash module
 module Splash
+
+  # Loggers namespace
   module Loggers
     include Splash::Config
 
     @@logger=nil
 
+
+    # factory for Loggers
+    # @param [Hash] options
+    # @option options [Symbol] :logger the name of the logger actually in [:cli, :daemon, :dual]
+    # @option options [Boolean] :force to force new instance creation (Logger is class variable)
+    # @return [SPlash::Loggers::<type>] type is Cli, Dual, Daemon, Web
     def get_logger(options = {})
       logger = (get_config.loggers[:list].include? options[:logger])? options[:logger].to_s : get_config.loggers[:default].to_s
       aclass = "Splash::Loggers::#{logger.capitalize}"
@@ -18,11 +26,15 @@ module Splash
       end
     end
 
+    # build a session number
+    # @return [String] Session number
     def get_session
       return "#{Time.now.to_i.to_s}#{rand(999)}"
     end
 
 
+    # wrapper to change logger, call get_logger with force: true
+    # @option options [Symbol] :logger the name of the logger actually in [:cli, :daemon, :dual]
     def change_logger(options = {})
       level = get_logger.level
       options[:force] = true
@@ -31,9 +43,10 @@ module Splash
 
     LEVELS = [:debug, :warn, :info, :result, :fatal, :unknown]
     ALIAS = {:flat => :info, :item => :info, :ok => :info, :ko => :info, :trigger => :info,
-      :schedule => :info, :arrow => :info, :send => :info,
+      :schedule => :info, :arrow => :info, :send => :info, :call => :info,
       :receive => :info, :error => :result, :success => :result }
 
+      # class template for loggers
     class LoggerTemplate
       include Splash::Config
 
@@ -48,13 +61,18 @@ module Splash
             self.log({ :level => method, :message => message, :session => session})
         end
       end
+
+      # constructor
       def initialize
         self.level = get_config.loggers[:level]
 
 
       end
 
-
+      # abstract method for log wrapper
+      # @param [Hash] options
+      # @option options [Symbol] :level, a valid level in LEVELS or ALIAS
+      # @option options [String] :message text
       def log(options)
         level = (ALIAS.keys.include? options[:level])?  ALIAS[options[:level]] : options[:level]
         if @active_levels.include? level then
@@ -62,11 +80,15 @@ module Splash
         end
       end
 
-
+      # getter for the current level
+      # @return [Symbol] level
       def level
         return @active_levels.first
       end
 
+      # virtual setter for level, set the current level
+      # @raise a badLevel in case of bad level
+      # @param [Symbol] level
       def level=(level)
         if LEVELS.include? level then
           @active_levels = LEVELS.dup
@@ -78,6 +100,9 @@ module Splash
 
 
       private
+      # mapper for symbol Symbol to String
+      # @param [Symbol] symbol
+      # @return [String] in upcase, exception :arrow give '=>', :flat give ''
       def alt(symbol)
         return "=>" if symbol == :arrow
         return '' if symbol == :flat
@@ -86,6 +111,7 @@ module Splash
 
     end
 
+    # badLevel Exception
     class BadLevel < Exception; end
 
   end

data/lib/splash/loggers/cli.rb

@@ -1,11 +1,17 @@
 # coding: utf-8
+
+# base Splash module
 module Splash
+
+  # Splash Loggers module
   module Loggers
 
+    # Cli specific logger
     class Cli < Splash::Loggers::LoggerTemplate
 
       include Splash::Config
 
+      # mapping of UTf-8 emoji for log levels or alias
       EMOJI =  { :unknown => "\u{1F4A5}",
                  :fatal => "\u{26D4}",
                  :error => "\u{1F6AB}",
@@ -22,6 +28,7 @@ module Splash
                  :success => "\u{1F4AA}",
                  :debug => "\u{1F41B}"}
 
+      # mapping of colors for log levels or alias
       COLORS = { :unknown => :red,
                  :fatal => :red,
                  :error => :red,
@@ -39,7 +46,11 @@ module Splash
                  :debug => :magenta}
 
 
-
+      # log wrapper
+      # @param [Hash] options
+      # @option options [Symbol] :level defined in Splash::Loggers::LEVEL or Splash::Loggers::ALIAS
+      # @option options [String] :message
+      # display formatted string to STDOUT
       def log(options)
         level = (ALIAS.keys.include? options[:level])?  ALIAS[options[:level]] : options[:level]
         if @active_levels.include? level then
@@ -59,14 +70,20 @@ module Splash
         end
       end
 
+      # setter in configuration for emoji display
+      # @param [Boolean] status
       def emoji=(status)
         get_config.loggers[:cli][:emoji] = status
       end
 
+      # setter in configuration for color display
+      # @param [Boolean] status
       def color=(status)
         get_config.loggers[:cli][:color] = status
       end
 
+      # check if unicode must be used with term ENV
+      # @return [Boolean]
       def check_unicode_term
         return false unless ENV.include? "TERM"
         if ENV.values_at("LC_ALL","LC_CTYPE","LANG").compact.first.include?("UTF-8") and ENV.values_at('TERM').first.include? "xterm" then
@@ -78,7 +95,5 @@ module Splash
 
     end
 
-    class BadLevel < Exception; end
-
   end
 end

data/lib/splash/loggers/daemon.rb

@@ -1,12 +1,17 @@
 # coding: utf-8
+
+# base Splash module
 module Splash
-  module Loggers
 
+  # Splash Loggers module
+  module Loggers
 
+    # Daemon specific logger
     class Daemon < Splash::Loggers::LoggerTemplate
 
 
-
+      # contructor, open log file
+      # @return [Splash::Loggers::Daemon]
       def initialize
         self.level = get_config.loggers[:level]
         @log_file = get_config.loggers[:daemon][:file]
@@ -14,7 +19,12 @@ module Splash
         @stream.sync = true
       end
 
-
+      # log wrapper
+      # @param [Hash] options
+      # @option options [Symbol] :level defined in Splash::Loggers::LEVEL or Splash::Loggers::ALIAS
+      # @option options [String] :message
+      # @option options [String] :session a session number
+      # write formatted string to log file
       def log(options)
         pid = Process.pid.to_s
         date = DateTime.now.to_s
@@ -28,6 +38,7 @@ module Splash
         end
       end
 
+      # close log file descriptor
       def close
         @stream.close
       end