easy_app_helper 0.0.9 → 1.0.0

data/lib/easy_app_helper/core/base.rb

@@ -0,0 +1,123 @@
+################################################################################
+# EasyAppHelper
+#
+# Copyright (c) 2013 L.Briais under MIT license
+# http://opensource.org/licenses/MIT
+################################################################################
+
+require 'slop'
+
+# This class is the base class for the {EasyAppHelper::Core::Config config} object.
+# It handles the internal_configs hash that actually contains all configurations read from
+# various sources: command line, config files etc...
+
+class EasyAppHelper::Core::Base
+  CHANGED_BY_CODE = 'Changed by code'
+
+  attr_reader :script_filename, :app_name, :app_version, :app_description, :internal_configs, :logger
+
+  def initialize(logger)
+    @app_name = @app_version = @app_description = ""
+    @script_filename = File.basename $0, '.*'
+    @internal_configs = {modified: {content: {}, source: CHANGED_BY_CODE}}
+    @logger = logger
+    @slop_definition = Slop.new
+    build_command_line_options
+  end
+
+
+  # @return [String] The formatted command line help
+  def help
+    @slop_definition.to_s
+  end
+
+  # sets the filename while maintaining the slop definition upto date
+  # @param [String] filename
+  def script_filename=(filename)
+    @script_filename = filename
+    @slop_definition.banner = build_banner
+  end
+  # sets the application name used for logging while maintaining the slop definition upto date
+  # @param [String] fname
+  def app_name=(name)
+    @app_name = name
+    @slop_definition.banner = build_banner
+  end
+  # sets the version while maintaining the slop definition upto date
+  # @param [String] version
+  def app_version=(version)
+    @app_version = version
+    @slop_definition.banner = build_banner
+  end
+  # sets the filename while maintaining the slop definition upto date
+  # @param [String] description
+  def app_description=(description)
+    @app_description = description
+    @slop_definition.banner = build_banner
+  end
+
+  def describes_application(app_name: nil, script_filename: nil, app_version: nil, app_description: nil)
+    self.app_name = app_name unless app_name.nil?
+    self.app_version = app_version unless app_version.nil?
+    self.app_description = app_description unless app_description.nil?
+    self.script_filename = script_filename unless script_filename.nil?
+  end
+
+  # @return [Hash] This hash built from slop definition correspond to the :command_line layer of internal_configs
+  def command_line_config
+    @slop_definition.parse
+    @slop_definition.to_hash
+  end
+
+  # Yields a slop definition to modify the command line parameters
+  # @param [String] title used to insert a slop separator
+  def add_command_line_section(title='Script specific')
+    raise "Incorrect usage" unless block_given?
+    @slop_definition.separator build_separator(title)
+    yield @slop_definition
+  end
+
+  # Sets the :command_line layer of internal_configs to the computed {#command_line_config}
+  def load_config
+    internal_configs[:command_line] = {content: command_line_config, source: 'Command line'}
+  end
+
+  # Any modification done to the config is in fact stored in the :modified layer of internal_configs
+  # @param [String] key
+  # @param [String] value
+  def []=(key,value)
+    internal_configs[:modified][:content][key] = value
+  end
+
+  # Reset the :modified layer of internal_configs rolling back any change done to the config
+  def reset
+    internal_configs[:modified] = {content: {}, source: CHANGED_BY_CODE}
+  end
+
+
+  # @return [Array] List of layers
+  def layers
+    internal_configs.keys
+  end
+
+  private
+
+  def build_separator(title)
+    "-- #{title} ".ljust 80, '-'
+  end
+
+  # Builds common used command line options
+  def build_command_line_options
+    add_command_line_section('Generic options') do |slop|
+      slop.on :auto, 'Auto mode. Bypasses questions to user.', :argument => false
+      slop.on :simulate, 'Do not perform the actual underlying actions.', :argument => false
+      slop.on :v, :verbose, 'Enable verbose mode.', :argument => false
+      slop.on :h, :help, 'Displays this help.', :argument => false
+    end
+  end
+
+  def build_banner
+    "\nUsage: #{script_filename} [options]\n#{app_name} Version: #{app_version}\n\n#{app_description}"
+  end
+
+end

data/lib/easy_app_helper/core/config.rb

@@ -0,0 +1,203 @@
+################################################################################
+# EasyAppHelper
+#
+# Copyright (c) 2013 L.Briais under MIT license
+# http://opensource.org/licenses/MIT
+################################################################################
+
+require 'yaml'
+# This is the class that will handle the configuration.
+# Configuration is read from different sources:
+# - config files (system, global, user, specified on the command line)
+# - command line options
+# - any extra config you provide programmatically
+#
+# == Config files:
+# system, global, and user config files are searched in the file system according to
+# complex rules. First the place where to search them depends on the OS
+# (Provided by {EasyAppHelper::Core::Config::Places}), and then multiple file extensions are
+# tested ({EasyAppHelper::Core::Config::CONFIG_FILE_POSSIBLE_EXTENSIONS}). This is basically
+# performed by the private method {#find_file}. The config specified on command (if any) is loaded the
+# same way.
+#
+# == Command line:
+# Any option can be declared as being callable from the command line. Modules add already some
+# command line options, but the application can obviously add its own (see
+# {EasyAppHelper::Core::Base#add_command_line_section}).
+#
+# Each of the config sources are kept in a separated "layer" and addressed this way using the
+# #internal_config attribute reader. But of course the config object provides a "merged" config
+# result of the computation of all the sources. See the #to_hash method to see the order for the
+# merge.
+# Any option can be accessed or modified directly using the {#[]} and {#[]=} methods.
+# Any change to the global config should be done using the {#[]=} method and is kept in the last separated
+# layer called "modified". Therefore the config can be easily reset using the {#reset}
+# method.
+class EasyAppHelper::Core::Config < EasyAppHelper::Core::Base
+end
+
+require 'easy_app_helper/core/places'
+require 'easy_app_helper/core/merge_policies'
+
+
+class EasyAppHelper::Core::Config < EasyAppHelper::Core::Base
+  include EasyAppHelper::Core::HashesMergePolicies
+  include EasyAppHelper::Core::Config::Places.get_OS_module
+
+  ADMIN_CONFIG_FILENAME = EasyAppHelper.name
+
+
+  # Potential extensions a config file can have
+  CONFIG_FILE_POSSIBLE_EXTENSIONS = %w(conf yml cfg yaml CFG YML YAML Yaml)
+  ADMIN_CONFIG_FILENAME
+
+  # @param [EasyAppHelper::Core::Logger] logger
+  # The logger passed to this constructor should be a temporary logger until the full config is loaded.
+  def initialize(logger)
+    super
+    add_cmd_line_options
+    load_config
+  end
+
+  # After calling the super method, triggers a forced reload of the file based config.
+  # @param [String] name of the config file
+  # @see Base#script_filename=
+  def script_filename=(name)
+    super
+    force_reload
+  end
+
+  # Sets the Application name and passes it to the logger.
+  # @param [String] name
+  # @see Base#app_name=
+  def app_name=(name)
+    super
+    logger.progname = name
+  end
+
+  # Loads all config (command line and config files)
+  # Do not reload a file if already loaded unless forced too.
+  # It *does not flush the "modified" layer*. Use {#reset} instead
+  # @param [Boolean] force to force the reload
+  def load_config(force=false)
+    super()
+    load_layer_config :system, ADMIN_CONFIG_FILENAME, force
+    load_layer_config :global, script_filename, force
+    load_layer_config :user, script_filename, force
+    load_layer_config :specific_file, internal_configs[:command_line][:content][:'config-file'], force
+  end
+
+  # @see #load_config
+  def force_reload
+    load_config true
+  end
+
+
+  # This is the main method that provides the config as a hash.
+  #
+  # Every layer is kept untouched (and could accessed independently
+  # using {#internal_configs}), while this methods provides a merged config.
+  # @return [Hash] The hash of the merged config.
+  def to_hash
+    merged_config = [:system, :global, :user].inject({}) do |temp_config, config_level|
+      hashes_second_level_merge temp_config, internal_configs[config_level][:content]
+    end
+    if command_line_config[:'config-file']
+      if command_line_config[:'config-override']
+        override_merge merged_config, internal_configs[:specific_file][:content]
+      else
+        hashes_second_level_merge merged_config, internal_configs[:specific_file][:content]
+      end
+
+    end
+    hashes_second_level_merge merged_config, command_line_config
+    hashes_second_level_merge merged_config, internal_configs[:modified][:content]
+  end
+
+  # @param [Object] key: The key to access the data in the merged_config hash (see {#to_hash})
+  # @return [String] Value for this key in the merged config.
+  def [](key)
+    self.to_hash[key]
+  end
+
+
+  # @return [String] The merged config (see {#to_hash}) rendered as Yaml
+  def to_yaml
+    to_hash.to_yaml
+  end
+
+  #############################################################################
+  private
+
+  # Command line options specific to config manipulation
+  def add_cmd_line_options
+    add_command_line_section('Configuration options') do |slop|
+      slop.on 'config-file', 'Specify a config file.', :argument => true
+      slop.on 'config-override', 'If specified override all other config.', :argument => false
+    end
+  end
+
+  # Tries to find a config file to be loaded into the config layer cake unless cached.
+  def load_layer_config(layer, filename_or_pattern, force=false)
+    unless_cached(layer,  filename_or_pattern, force) do |layer, filename_or_pattern|
+      fetch_config_layer layer, filename_or_pattern
+    end
+  end
+
+  # Actual loads
+  def fetch_config_layer(layer, filename_or_pattern)
+    if filename_or_pattern.nil?
+      internal_configs[layer] = {content: {}}
+      filename = nil
+    else
+      if File.exists? filename_or_pattern
+        filename = filename_or_pattern
+      else
+        filename = find_file POSSIBLE_PLACES[layer], filename_or_pattern
+      end
+      internal_configs[layer] = {content: load_config_file(filename), source: filename, origin: filename_or_pattern}
+    end
+  ensure
+    logger.info "No config file found for layer #{layer}." if filename.nil?
+  end
+
+  def unless_cached(layer, filename_or_pattern, forced)
+    cached = false
+    if internal_configs[layer]
+      cached = true unless internal_configs[layer][:origin] == filename_or_pattern
+    end
+    if forced or not cached
+      yield layer, filename_or_pattern
+    end
+  end
+
+  # Tries to find config files according to places (array) given and possible extensions
+  def find_file(places, filename)
+    return nil if places.nil? or filename.nil? or filename.empty?
+    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
+          logger.debug "Trying \"#{filename_with_path}\" as config file."
+        end
+      end
+    end
+    nil
+  end
+
+  def load_config_file(conf_filename)
+    conf = {}
+    return conf if conf_filename.nil?
+
+    begin
+      logger.debug "Loading config file \"#{conf_filename}\""
+      conf = Hash[YAML::load(open(conf_filename)).map { |k, v| [k.to_sym, v] }]
+    rescue => e
+      logger.error "Invalid config file \"#{conf_filename}\". Skipped as not respecting YAML syntax!\n#{e.message}"
+    end
+    conf
+  end
+
+end

data/lib/easy_app_helper/core/logger.rb

@@ -0,0 +1,101 @@
+################################################################################
+# EasyAppHelper
+#
+# Copyright (c) 2013 L.Briais under MIT license
+# http://opensource.org/licenses/MIT
+################################################################################
+
+require 'logger'
+require 'singleton'
+
+# Official Ruby Logger re-opened to introduce a method to hand-over the temporary history from a temporary logger
+# to the definitive one.
+# TODO: Ensure only the messages that are above the current level are displayed when handing over to the definitive logger.
+class Logger
+  def handing_over_to(log)
+    history = []
+    history = @logdev.dev.history if @logdev.dev.respond_to? :history
+    @logdev.close
+    @logdev = LogDevice.new log
+    history.each do |msg|
+      @logdev.write msg if ENV['DEBUG_EASY_MODULES'] or (msg =~ /^[WE]/)
+    end
+  end
+end
+
+# This is the logger that will be used by the application and any class that include {#EasyAppHelper} module.
+class EasyAppHelper::Core::Logger < Logger
+  include Singleton
+
+
+  def initialize
+    @config = {}
+    super(TempLogger.new)
+    self.level = Severity::DEBUG
+    debug "Temporary initialisation logger created..."
+  end
+
+  # Change the log level while keeping the config in sync.
+  def level=(level)
+    super
+    @config[:'log-level'] = level
+  end
+
+  # Displays the message according to application verbosity and logs it as info.
+  def puts_and_logs(msg)
+    puts msg if @config[:verbose]
+    info(msg)
+  end
+
+  # Reset the logger regarding the config provided
+  def set_app_config(config)
+    @config = config
+    add_cmd_line_options
+    @config.load_config
+    debug "Config layers:\n#{@config.internal_configs.to_yaml}"
+    debug "Merged config:\n#{@config.to_yaml}"
+    if config[:'log-file']
+      handing_over_to config[:'log-file']
+    elsif config[:"debug-on-err"]
+      handing_over_to STDERR
+    else
+      handing_over_to STDOUT
+    end
+    self.level = config[:'log-level'] ? config[:'log-level'] : Severity::WARN
+    self
+  end
+
+  private
+
+
+  def add_cmd_line_options
+    @config.add_command_line_section('Debug and logging options') do |slop|
+      slop.on :debug, 'Run in debug mode.', :argument => false
+      slop.on 'debug-on-err', 'Run in debug mode with output to stderr.', :argument => false
+      slop.on 'log-level', "Log level from 0 to 5, default #{Severity::WARN}.", :argument => true, :as => Integer
+      slop.on 'log-file', 'File to log to.', :argument => true
+    end
+  end
+
+  # This class will act as a temporary logger, actually just keeping the history until the real
+  # configuration for the logger is known. Then the history is displayed or not regarding the
+  # definitive logger configuration.
+  class TempLogger
+    attr_reader :history
+
+    def initialize
+      @history = []
+    end
+
+    def write(data)
+      @history << data if @history
+    end
+
+    def close
+
+    end
+  end
+
+end
+
+

data/lib/easy_app_helper/core/merge_policies.rb

@@ -0,0 +1,37 @@
+################################################################################
+# EasyAppHelper
+#
+# Copyright (c) 2013 L.Briais under MIT license
+# http://opensource.org/licenses/MIT
+################################################################################
+
+# This module proposes different merge policies for two hashes.
+module EasyAppHelper::Core::HashesMergePolicies
+
+  # Performs a merge at the second level of hashes.
+  # simple entries and arrays are overridden.
+  def hashes_second_level_merge(h1, h2)
+    h2.each do |key, v|
+      if h1[key] and h1[key].is_a?(Hash)
+        # Merges hashes
+        h1[key].merge! h2[key]
+      else
+        # Overrides the rest
+        h1[key] = h2[key] unless h2[key].nil?
+      end
+    end
+    h1
+  end
+
+  # Uses the standard "merge!" method
+  def simple_merge(h1, h2)
+    h1.merge! h2
+  end
+
+  # Brutal override
+  def override_merge(h1, h2)
+    h1 = nil
+    h1 = h2
+
+  end
+end